ForgeGuard v1.6.1 — Current-task Goal Management

ForgeGuard v1.6.1 — Current-task Goal Management

This patch release fixes the boundary between Goal Intelligence and task creation.

• Goal definition and persistent goal state remain attached to the current task.
• ForgeGuard does not create a separate task, thread, chat, worktree, or delegated worker merely to define, refine, store, replace, or continue a goal.
• A goal conflict is not treated as authorization to create a separate task.
• Environments with goal-management capabilities use those capabilities according to their actual contract.
• Environments without goal-management capabilities keep the goal in current-task context or use an established in-task planning mechanism.

The managed Codex AGENTS block and the compact skill instructions include the same invariant, and contract tests protect the shipped policy text.

Upgrade

Run forgeguard install --force, preserving the client and scope options used for the existing installation, then start a new coding-agent session so updated instructions are loaded.

No CLI flags, runtime preset defaults, or public package APIs changed.

Release validation

Run npm test and npm pack --dry-run. The CI matrix validates Node.js 18, 20, and 22, CLI lifecycle behavior, version consistency, installed policy references, and the current-task Goal Intelligence contract.

Remote CI must pass before the release is considered complete.

ForgeGuard v1.6.0 - Delegation Intelligence

ForgeGuard v1.6.0 - Delegation Intelligence

This release adds a portable decision layer for whether and how authorized workers should be used.

• Reuse explicit approval within the current task/scope; request renewed approval only for delegation beyond it.
• Actively evaluate independent work for time, quality, coverage, or verification benefits; avoid workers when coordination costs dominate.
• Specify objective, scope, expected output, evidence required, and constraints for every worker.
• Keep planning, integration, conflict resolution, final verification, and the final response with the primary agent.
• Resolve instruction conflicts using the host platform's hierarchy while keeping explicit user instructions above ForgeGuard skill guidelines within ForgeGuard's own guidance.
• Calibrate verification to risk and scope and avoid redundant checks without new evidence or concerns.
• Default depth is 1; workers must not spawn subagents under this policy.

The managed Codex AGENTS block activates these concise rules; full policies ship in the skill references. Existing references remain available.

Design basis

The delegation, instruction-following, and testing principles in this release are informed by OpenAI's current Model guidance for GPT-6 Astra:

https://developers.openai.com/api/docs/guides/latest-model

The source recommends making user-versus-skill priority explicit, tuning when subagents should parallelize work, and calibrating testing for smaller changes. ForgeGuard keeps those ideas separate from its own policy choices: explicit delegation authorization, bounded worker contracts, primary-agent ownership, depth = 1, and a risk-aware verification matrix.

ForgeGuard does not use that OpenAI-specific guidance to invent a universal instruction hierarchy for Codex, Claude Code, Cursor, or future clients. The host platform remains authoritative for its actual instruction precedence and scope rules.

Upgrade

Run forgeguard install --force, preserving your original client/global options, and start a new coding-agent session. No migration or new CLI flag is required.

The optional runtime preset remains gpt-5.6-luna with xhigh reasoning. Existing --subagents, --subagent-model, --subagent-reasoning, and --no-subagent-config flags are unchanged. ForgeGuard does not change the primary model, mandate delegation, automatically route models, or become a standalone multi-agent runtime.

Release validation

Run npm test and npm pack --dry-run. The existing CI matrix runs Node.js 18, 20, and 22 and checks install/status/reinstall/uninstall. Tests validate installed policy references, managed instructions, version consistency, preservation, runtime defaults, portable instruction resolution, and the documented OpenAI design basis. Policy text checks protect the shipped contract; they do not prove model compliance. Exercise the five delegation scenarios in the target client when evaluating agent behavior.

Remote CI must pass before release; local test results alone are not evidence of remote CI success.

ForgeGuard v1.5.0 — Codex Subagent Runtime

ForgeGuard v1.5.0 — Codex Subagent Runtime

ForgeGuard v1.5.0 adds optional Codex runtime defaults for authorized subagents while preserving the existing manual approval gate.

Default preset

[agents]
enabled = true
default_subagent_model = "gpt-5.6-luna"
default_subagent_reasoning_effort = "xhigh"

Enable it explicitly:

forgeguard install --client codex --subagents

A normal ForgeGuard install does not change Codex runtime defaults.

Delegation model

Subagent authorization is permission, not a requirement. If the user explicitly allows subagents, the primary agent may delegate bounded work when useful, but remains responsible for planning, integration, conflict resolution, final verification, and the final response.

A runtime preset never bypasses the explicit approval policy.

Safe config management

ForgeGuard manages only a marked block inside .codex/config.toml or the global $CODEX_HOME/config.toml.

It preserves unrelated settings and custom [agents.<role>] tables. Existing unmanaged subagent model or reasoning defaults are never overwritten automatically. An existing unmanaged enabled = false is treated as a conflict.

forgeguard uninstall removes only the ForgeGuard-managed runtime block. Use --no-subagent-config when the runtime block should be kept.

CLI additions

--subagents
--subagent-model <model>
--subagent-reasoning <effort>
--no-subagent-config

The default preset is equivalent to:

forgeguard install \
  --client codex \
  --subagent-model gpt-5.6-luna \
  --subagent-reasoning xhigh

Verification

The release adds Node built-in tests for runtime config creation, preservation, conflict detection, idempotency, status reporting, and uninstall cleanup. CI runs the unit suite on Node 18, 20, and 22 and exercises the Luna/xhigh CLI integration.

ForgeGuard v1.4.0 — Goal Intelligence

ForgeGuard v1.4.0 — Goal Intelligence

ForgeGuard v1.4.0 upgrades goal handling from a simple gate into a portable measurable-objective policy for substantial agent-driven work.

The objective is not to turn every task into a planning exercise. Goal Intelligence activates only when the user explicitly asks for goal-backed work or when a substantial task does not yet have an honest, measurable completion condition.

Highlights

Goal need-check

ForgeGuard first decides whether a goal is useful at all.

Routine tasks with clear acceptance criteria should proceed directly. Substantial ambiguous work gets a measurable objective before implementation.

Goal quality bar

A goal is expected to define:

• a concrete outcome;
• the relevant system/artifact/environment or user-visible target;
• verification evidence;
• a binary or quantitative success threshold;
• in-scope and out-of-scope boundaries when they matter;
• a stop or escalation condition.

This shifts goal definition away from activity descriptions and toward observable completion.

Weak-goal detection

Activity-only objectives such as "make progress", "improve things", "keep investigating", or "work on performance" are not considered sufficient for substantial goal-backed work.

ForgeGuard sharpens them when repository context makes the intended result clear. When multiple materially different outcomes remain plausible, it asks one focused clarification question instead of guessing.

Meaningful quantification

Goal Intelligence supports quantitative engineering success when the domain provides a real metric:

• exact test, typecheck, build, CI, or acceptance commands;
• latency, throughput, memory, bundle size, error rate, cost, accuracy, coverage, flake rate, or uptime thresholds;
• required successful repetitions or reviewed examples;
• bounded files, modules, services, routes, records, or environments;
• monitoring windows, failure thresholds, and rollback triggers.

ForgeGuard avoids decorative precision. When a useful metric is unavailable, it uses the strongest honest binary validator instead.

Domain heuristics

The goal policy now includes guidance for:

• bugs — reproduce, fix, and regression verification;
• tests — exact validator and pass condition;
• performance — metric, threshold, method, and repetition count;
• quality/reliability — observable quality gates;
• research/architecture — decision, scope, and evidence standard;
• operations — healthy state, monitoring window, rollback, and escalation.

Existing goal state

When an agent environment provides persistent goal-management capabilities, ForgeGuard checks existing active goal state before creating another goal.

Matching unfinished goals can be reused. Conflicting goals are surfaced instead of silently duplicated or overwritten.

ForgeGuard remains portable: it does not assume specific goal tool names or invent persistent goal APIs when they do not exist.

Clarification discipline

Goal Intelligence uses at most one concise clarification question when missing information can materially change the outcome, validator, environment, or scope.

The policy is designed to improve precision without turning engineering work into a questionnaire.

Integration with other ForgeGuard layers

Goal Intelligence defines what success means.

The rest of ForgeGuard then operates around that goal:

Goal Intelligence
      │
      ▼
   Risk Gate
      │
      ▼
Implementation
      │
      ▼
 Verification
      │
      ▼
Commit Intelligence

This creates a consistent path from measurable intent to safe execution to evidence-backed completion and commit documentation.

Automation fix

The repository branch has moved from main to master. ForgeGuard v1.4.0 updates CI and release workflow branch filters to accept both names so automation continues to work across the rename.

Upgrade

npx --yes github:GendByteMaster/ForgeGuard install --force

For Codex, start a new session after upgrading so the refreshed skill and managed instruction block are loaded.

Breaking changes

None.

Goal behavior is stricter only for substantial ambiguous work: ForgeGuard now expects measurable evidence and success criteria before treating such a goal as ready.

License

MIT.

ForgeGuard v1.3.0 — Commit Intelligence

ForgeGuard v1.3.0 — Commit Intelligence

ForgeGuard v1.3.0 strengthens commit preparation into an evidence-driven engineering step rather than a one-line message generator.

The release makes structured git diff analysis mandatory whenever ForgeGuard prepares a commit message or commit summary.

Highlights

Mandatory diff-first analysis

The real git diff is the primary source of truth. ForgeGuard determines the primary change type from the actual changes and supports Conventional Commit categories including:

• feat — new capability;
• fix — bug fix;
• refactor — restructuring without intended behavior change;
• perf — performance improvement;
• docs — documentation-only change;
• style — formatting/style-only change;
• test — test-focused change;
• chore — maintenance work.

If a diff contains materially unrelated changes, ForgeGuard must state that and recommend splitting the work into separate commits when appropriate.

Conventional Commit subject discipline

Preferred format:

<type>(<scope>): <short summary>

When no meaningful scope can be inferred:

<type>: <short summary>

Rules include:

• maximum 72 characters unless the repository defines a stricter limit;
• imperative mood;
• concise and specific wording;
• scope only when supported by the affected module/service/package/domain;
• no claims unsupported by the diff.

Mandatory structured Description

The Description section is now mandatory and must not be omitted, even when the user asks only for a commit message.

Required shape:

<type>(<scope>): <short summary>

Description:
- Changes:
  - ...

- Reason:
  - ...

- Implementation Details:
  - ...

- Impact / Risks:
  - ...

- Breaking Changes:
  - None

Evidence-aware Reason

ForgeGuard only explains why a change was made when the reason is inferable from the diff or explicitly supplied task context.

If intent cannot be established, ForgeGuard says so directly instead of inventing a plausible explanation:

- Reason is not inferable from the diff alone.

Evidence-aware verification claims

Commit preparation must not claim that tests, builds, migrations, deployments, benchmarks, or verification steps succeeded without supporting evidence.

ForgeGuard also avoids unsupported claims about:

• security improvements;
• compatibility guarantees;
• performance improvements;
• production effects.

Explicit Impact / Risks and Breaking Changes

Commit reports now separate observed changes from their direct engineering impact.

Impact / Risks should contain effects reasonably supported by the diff. Breaking Changes must describe actual breaking changes when present; otherwise it must explicitly contain None.

Why this matters

A commit message is part of the engineering record. Agent-generated commits become dangerous when they sound authoritative while inventing intent, verification, or impact that the diff does not prove.

ForgeGuard v1.3.0 treats commit preparation as evidence-backed documentation of the change.

Upgrade

Refresh an existing installation:

npx --yes github:GendByteMaster/ForgeGuard install --force

For Codex installations, start a new session after upgrading so the managed repository instructions reload the updated skill.

Compatibility

No compatibility changes. ForgeGuard remains portable across supported Codex, Claude Code, and Cursor skill locations.

Breaking changes

None to installation or runtime behavior.

Commit-output behavior is intentionally stricter: ForgeGuard now always emits the complete structured Description when preparing commit output.

License

MIT.

ForgeGuard v1.2.0 — Automatic AGENTS.md Integration

ForgeGuard v1.2.0 — Automatic AGENTS.md Integration

ForgeGuard v1.2.0 connects the installed Agent Skill directly to Codex repository instructions.

The main change is simple: installing ForgeGuard no longer only copies engineering-guardrails into a skills directory. For Codex installations, the CLI now also adds a small managed ForgeGuard activation block to the active AGENTS.md instruction file so repository work consistently discovers and applies the skill.

Highlights

Automatic Codex instruction integration

Running:

npx --yes github:GendByteMaster/ForgeGuard install

now installs the skill and, when Codex is among the selected clients, adds a ForgeGuard-managed block to the active repository instructions.

The managed block tells Codex to load engineering-guardrails before implementation, bug fixes, refactors, migrations, security-sensitive work, production changes, or commit preparation.

It also explicitly activates ForgeGuard's:

• Risk Gate;
• explicit Subagent approval gate;
• repository-local instruction preservation;
• safe fallback behavior when the skill cannot be loaded.

Idempotent AGENTS.md management

ForgeGuard uses explicit managed markers:

<!-- forgeguard:managed-start -->
...
<!-- forgeguard:managed-end -->

This gives the CLI ownership of only its own section.

Repeated installs update the existing managed block instead of appending duplicates. Existing user instructions outside the block remain untouched.

AGENTS.override.md awareness

When a non-empty AGENTS.override.md exists in the active Codex instruction scope, ForgeGuard uses it instead of writing a competing block to AGENTS.md.

The CLI keeps the managed activation block in only the active instruction file to avoid conflicting ForgeGuard instructions.

Safe uninstall

forgeguard uninstall now removes both:

• installed ForgeGuard skill directories for the selected clients;
• the ForgeGuard-managed block from Codex instructions.

If an AGENTS.md file contains other project instructions, those instructions are preserved. If ForgeGuard created a file that contains nothing except the managed block, the empty file is removed during uninstall.

Status includes instruction linkage

forgeguard status now reports Codex instruction integration in addition to skill installation state.

Example output can distinguish:

installed codex+cursor: .../.agents/skills/engineering-guardrails (v1.2.0)
installed claude: .../.claude/skills/engineering-guardrails (v1.2.0)
linked    agents: .../AGENTS.md

Opt-out with --no-agents

Projects that want the skill installed without modifying Codex instructions can use:

forgeguard install --client codex --no-agents

This keeps AGENTS integration explicit and reversible rather than mandatory.

Global installation

For global Codex installation, ForgeGuard uses CODEX_HOME when configured and otherwise falls back to ~/.codex for the managed instruction file.

The skill itself continues to use the supported user-level Agent Skills directory.

Session reload requirement

Codex loads repository instructions when a session starts. After ForgeGuard changes AGENTS.md or AGENTS.override.md, start a new Codex session so the updated instructions are loaded.

The CLI prints this reminder after installation.

CI hardening

The CLI workflow was updated alongside v1.2.0:

• Node 18, 20, and 22 run independently with matrix fail-fast: false;
• expected versions are read dynamically from package.json instead of being hardcoded;
• CI verifies skill installation and AGENTS integration;
• repeated installation is tested for idempotency;
• uninstall cleanup is verified;
• npm pack --dry-run continues to validate the distributable npm artifact.

CLI

Project installation:

npx --yes github:GendByteMaster/ForgeGuard install

Status:

npx --yes github:GendByteMaster/ForgeGuard status

Uninstall:

npx --yes github:GendByteMaster/ForgeGuard uninstall

Codex only:

npx --yes github:GendByteMaster/ForgeGuard install --client codex

Global:

npx --yes github:GendByteMaster/ForgeGuard install --global

Skip AGENTS integration:

npx --yes github:GendByteMaster/ForgeGuard install --client codex --no-agents

Upgrade from v1.1.0

Re-run the installer with --force:

npx --yes github:GendByteMaster/ForgeGuard install --force

This refreshes the installed skill to v1.2.0 and adds or updates the managed Codex instruction block.

Then start a new Codex session.

Breaking changes

None.

The new AGENTS integration is automatically enabled when Codex is selected, but it is isolated to a managed block and can be disabled with --no-agents or completely removed with uninstall.

License

MIT.

ForgeGuard v1.1.0 — Risk Gate and CLI

ForgeGuard v1.1.0 — Risk Gate and CLI

ForgeGuard v1.1.0 extends the initial guardrail model with two major capabilities: explicit engineering risk classification and a portable CLI installer for Agent Skills.

Highlights

Risk Gate

ForgeGuard now classifies consequential work before execution using four levels:

• Low — routine, reversible changes with limited blast radius;
• Medium — behavior, dependency, contract, or infrastructure changes that require compatibility and rollback awareness;
• High — security, authentication, cryptography, billing, production deployment, data-transforming migrations, breaking contracts, and distributed consistency changes;
• Critical — destructive production data operations, irreversible migrations, large-scale credential/key changes, security-control disablement, or other operations with extreme blast radius and weak rollback guarantees.

For High and Critical work, ForgeGuard requires explicit reasoning about blast radius, failure modes, rollback/recovery, and verification before execution.

Critical operations are never executed automatically and require explicit user approval immediately before the consequential step.

Preparation vs execution

The Risk Gate distinguishes preparing a risky change from executing it.

ForgeGuard can still prepare:

• migration files;
• deployment manifests;
• key-rotation plans;
• destructive-operation runbooks;
• breaking API transition plans;

without immediately applying them to production. The approval gate applies to the irreversible or production-impacting execution step.

npm/npx CLI

ForgeGuard now ships with a zero-runtime-dependency Node.js CLI.

The package name is:

@gendbytemaster/forgeguard

The executable is:

forgeguard

Supported commands:

forgeguard install
forgeguard status
forgeguard uninstall

Supported options include:

--client codex|claude|cursor|all
--global
--force
--dry-run

The CLI installs the complete engineering-guardrails/ directory into the appropriate Agent Skills location for the selected client.

Run directly from GitHub

ForgeGuard can be executed with npx before npm registry publication:

npx --yes github:GendByteMaster/ForgeGuard install

Other examples:

npx --yes github:GendByteMaster/ForgeGuard status
npx --yes github:GendByteMaster/ForgeGuard install --client codex
npx --yes github:GendByteMaster/ForgeGuard install --global
npx --yes github:GendByteMaster/ForgeGuard install --dry-run

After publication to npm, the intended command is:

npx @gendbytemaster/forgeguard install

or:

npm install -g @gendbytemaster/forgeguard
forgeguard install

Multi-client installation

ForgeGuard understands the native Agent Skills paths used by supported clients:

Client	Project location
OpenAI Codex	.agents/skills/engineering-guardrails/
Claude Code	.claude/skills/engineering-guardrails/
Cursor	.agents/skills/engineering-guardrails/ or .cursor/skills/engineering-guardrails/

Codex and Cursor can share the .agents/skills installation instead of maintaining duplicate copies.

CLI verification

The CLI is designed to be tested across supported Node.js versions and includes CI coverage for:

• Node.js 18;
• Node.js 20;
• Node.js 22;
• package construction through npm pack --dry-run;
• installation/status/uninstallation behavior.

npm publication workflow

The repository includes a publication workflow intended to publish @gendbytemaster/forgeguard from a GitHub Release once npm authentication or Trusted Publishing is configured for the package.

GitHub repository access alone does not authorize publication to the npm registry; npm account configuration remains a separate trust boundary.

Updated skill structure

engineering-guardrails/
├── SKILL.md
└── references/
    ├── commit-policy.md
    ├── goal-policy.md
    ├── gsd-workflow.md
    ├── risk-gate.md
    └── subagent-policy.md

The repository also now contains the CLI package and release tooling:

bin/forgeguard.js
package.json
.github/workflows/
docs/
examples/

Upgrade from v1.0.0

If ForgeGuard is copied manually into a project, replace the complete engineering-guardrails/ directory with the v1.1.0 version so that SKILL.md and references/risk-gate.md remain synchronized.

If using the CLI from GitHub, rerun:

npx --yes github:GendByteMaster/ForgeGuard install --force

After npm publication:

npx @gendbytemaster/forgeguard install --force

Compatibility

ForgeGuard remains language-, framework-, and repository-host agnostic. The v1.1.0 changes add workflow controls and installation tooling without requiring a specific application stack.

Breaking changes

None for the Agent Skill behavior expected by v1.0.0 users.

The Risk Gate adds stricter approval requirements around High and Critical execution steps. This is an intentional safety behavior rather than an API incompatibility.

Verification

Before publishing this release, verify:

• package.json and SKILL.md both report 1.1.0;
• the CLI starts successfully on supported Node.js versions;
• install, status, and uninstall work in an isolated test directory;
• npm pack --dry-run includes the CLI and complete engineering-guardrails/ skill;
• release notes and changelog describe only features present in the repository.

License

MIT.

ForgeGuard v1.0.0 — Initial Public Release

ForgeGuard v1.0.0 — Initial Public Release

ForgeGuard v1.0.0 establishes the first stable version of a portable engineering guardrails skill for coding agents.

The release focuses on one problem: powerful coding agents should not be allowed to treat repository work as an unconstrained sequence of edits. ForgeGuard introduces a reusable workflow and policy layer that keeps agent work repository-aware, scoped, verifiable, and explicit about delegation.

Highlights

Repository-aware execution

Before changing code, ForgeGuard requires the agent to inspect the repository context first:

• AGENTS.md, CLAUDE.md, CONTRIBUTING.md, README.md, and project-local instructions;
• package manifests and build/test commands;
• formatting, linting, and verification tooling;
• architecture, module, service, and data-ownership boundaries.

The goal is to preserve the repository's existing engineering model instead of imposing a generic one.

Adaptive workflow selection

ForgeGuard selects the smallest workflow appropriate for the task:

• small change: inspect → edit → focused verification;
• bug: reproduce → isolate → fix → regression verification;
• substantial feature/refactor: define goal → inspect dependencies → plan → implement → verify.

GSD is supported when present, but it is not a dependency and is never injected into projects that do not use it.

Goal Gate

Substantial or ambiguous work gets a measurable goal before implementation. The goal can include:

• desired outcome;
• in-scope and out-of-scope work;
• completion evidence;
• binary or quantitative success criteria;
• stop or escalation conditions.

Routine tasks with already-clear acceptance criteria do not get unnecessary planning overhead.

Explicit Subagent Approval

ForgeGuard does not treat delegation recommendations as authorization.

A subagent may only be launched when the user explicitly approves it in the current conversation. Recommendations from GSD, planners, orchestrators, tools, or other agents are not permission.

When delegation is not approved, the agent should continue the work itself whenever possible.

Evidence-based verification

ForgeGuard prevents false completion claims. An agent must not claim that a test, build, benchmark, migration, or command succeeded unless it actually ran successfully or equivalent evidence is already available.

Verification failures and skipped checks must be reported rather than hidden.

Diff-grounded Conventional Commits

Commit preparation is based on the real diff. ForgeGuard can classify changes as feat, fix, refactor, perf, docs, test, chore, and related Conventional Commit types while refusing to invent functionality or motivation unsupported by the code change.

Skill structure

engineering-guardrails/
├── SKILL.md
└── references/
    ├── commit-policy.md
    ├── goal-policy.md
    ├── gsd-workflow.md
    └── subagent-policy.md

Supported clients

Initial documentation covers:

• OpenAI Codex;
• Claude Code;
• Cursor.

ForgeGuard is intentionally framework- and language-agnostic. It does not require Python, Rust, TypeScript, Next.js, FastAPI, Bevy, a particular database, CI provider, or deployment model.

Installation

Project-level installation is performed by copying the complete engineering-guardrails/ directory into the client's Agent Skills location.

See docs/INSTALLATION.md for client-specific paths and global installation options.

Design boundary

ForgeGuard is deliberately a guardrail/orchestration layer, not a monolithic coding framework.

Debugging, testing, security, architecture, repository hosting, deployment, and other domain-specific work can be delegated to specialized tools and skills while ForgeGuard governs how that work is entered, scoped, verified, and reported.

Breaking changes

None. This is the initial public release.

License

MIT.