@guidobuilds/forge-ai 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -9,6 +9,53 @@ Versions prior to 0.3.0 are not reconstructed here; see git history for earlier
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-06-20
+
+### Added
+
+- **Grok Build (`--platform grok`) as a first-class target.** `forge`, `forge-grill`, and `using-forge` install as Grok skills under `.grok/skills/<name>/SKILL.md`; `forge-worker` and `forge-adversary` install as Grok subagents under `.grok/agents/<name>.md`. Grok's built-in tool IDs (`run_terminal_cmd`, `grep_search`, `search_replace`, etc.) are used in the worker and adversary toolsets, replacing the Claude-specific names. Included in `--platform all`. Grok Build v0.2.56+ required.
+
+### Changed
+
+- **Orchestrator route announcement**: before the first dispatch, the orchestrator now states the chosen route to the user — work types joined by arrows (e.g. `build -> verify`, `inspect -> build -> verify`, `inspect -> design -> plan -> build -> verify`), whether a `forge-grill` pass runs before build and an independent verify or `forge-adversary` gate runs after, and one clause on why it is the lightest safe route. Re-announced only when the route changes materially mid-flight.
+- **Proactive `forge-grill`**: the orchestrator now runs `forge-grill` proactively before build for non-trivial, risk-bearing, or multi-step work with unresolved assumptions. Previously grill was effectively opt-in (user-triggered via `/forge-grill`). Trivial, surgical, and read-only work still skips grill.
+
+### Migration from 0.4.0
+
+- Run `npx @guidobuilds/forge-ai update` to add the new `forge-grill` and `using-forge` prompt changes and the Grok Build artifacts. No breaking changes to the CLI, state files, or existing Claude/OpenCode/Codex installs.
+
+## [0.4.0] - 2026-06-16
+
+### Added
+
+- **Adaptive `.forge/<feature-slug>/` state model** for the orchestration harness, sized to task complexity. Trivial work stays on the `build -> verify` path with no artifacts; non-trivial or multi-session work gains a structured state ledger. Documented in `using-forge` (routing tiers + triggers) and `forge-worker` (schema + templates). No distribution-engine change — the state files are runtime-generated by the worker.
+- **`feature-list.json` feature-list primitive**: the unit-of-work ledger where each feature carries the triple `behavior` + `verification` (a runnable command) + `state` (`not_started | active | blocked | passing`), plus `evidence` and `dependencies`.
+- **Definition of Done with verification-evidence gating**: a feature reaches `passing` only after its verification command was actually run and recorded in `verification.md`; never on assertion alone.
+- **Independent verification**: for non-trivial work the builder may not self-certify; the orchestrator dispatches a separate `forge-worker` verify run that re-runs the checks and flips state.
+- **`forge-adversary` agent — dedicated post-build red-team gate.** A new subagent (`kind: agent`; OpenCode subagent, Claude agent) the orchestrator dispatches *after* build to break a worker's output across four lenses (logical/requirements, technical/runtime, security, performance/scale). It writes reproductions under `.forge/<slug>/adversary/`, records every attempt in `verification.md`, and gates the Definition of Done — a confirmed, reproducible break moves the feature to `blocked`; it never edits the implementation under test. Reports `WORK_TYPE: verify`, so the worker contract is unchanged. Complements `forge-grill` (which grills plans/designs *before* build). `forge`, `using-forge`, and `forge-worker` updated to dispatch it for risk-bearing work.
+- **Persisted handoff/progress**: `progress.md` and `session-handoff.md` templates for cross-session continuity, created adaptively when work spans sessions or blocks.
+- `forge-ai self-update` command. Detects how the CLI is installed (pnpm global, npm global, Homebrew npm, npx, or unknown) and runs the right update command with the right flags (`--prefer-online` for pnpm to sidestep its metadata cache). After updating the binary it automatically runs `forge-ai update` to refresh the spec kit. Flags: `--to <version>` to pin a specific version, `--dry-run` to preview, `--skip-spec-update` to only bump the CLI.
+- Background version check on every interactive run. Calls the npm registry (with 1.5s timeout, cached for 1h at `~/.forge-ai/version-check.json`) and prints `forge-ai vX.Y.Z (vA.B.C available — run \`forge-ai self-update\` to upgrade)` when a newer version exists. Silent on failure; never blocks the command.
+- `--no-update-check` CLI flag and `FORGE_NO_UPDATE_CHECK=1` env var to opt out of the version check. Also auto-skipped in CI (`CI=true`) and non-interactive runs.
+- README "How to Use" section explaining how to invoke Forge per platform: `/forge` skill on Claude Code (with `forge-worker` as a delegated subagent), `forge` primary agent on OpenCode, and the partial `.toml` agents on Codex — including the Claude advisory-vs-OpenCode-enforced trade-off.
+- **Feedback ratchet — `.forge/lessons.md`**: a project-scoped, topic-keyed lessons file the worker proactively appends to after each run (decision / non-obvious fix / convention / failure). Reusing a topic-key updates an existing lesson instead of creating a contradictory duplicate, so the harness compounds across sessions instead of repeating mistakes.
+- **Bootstrap repo-facts — `.forge/repo-facts.md`**: a one-time `inspect`-written standing spec (stack, build/test/lint commands, conventions, hard constraints) the worker rereads each dispatch, paying the intent/reconstruction cost once.
+- **Closure + cross-task index — `.forge/index.md` and `.forge/_archive/`**: on `passing`, the verify dispatch flushes lessons and appends a one-line ledger entry; completed slugs may be archived. Each feature carries a falsifiable `archiveWhen` condition set at creation.
+- **Effort routing**: the orchestrator now states an effort level per worker dispatch (low for `inspect`/`verify`/`operate`/routine `build`, medium for most `build`/`plan`, high for `design`/synthesis/novel work) — match effort to difficulty rather than defaulting high.
+- **Inline-vs-delegate threshold**: the orchestrator handles inline only a 1-3 file read / mechanical write / git status, and delegates at 4+ files, multi-file writes, or running tests/builds/installs — keeping the thread thin (summaries, not implementations).
+- **Optional hooks pack** (README): an opt-in Claude Code `settings.json` snippet (Stop + PostToolUse) to *enforce* the verification gate mechanically for unattended runs — kept thin and optional, since strong models honor the gate from the operating model alone.
+- **Harness-content validation**: `validate`/`install` emit a `BODY_OVER_BUDGET` info diagnostic when an artifact body exceeds its soft line budget (keep always-loaded files small). Never an error; does not block installs.
+
+### Changed
+
+- **Independent verification is now adversarial.** The separate `forge-worker` verify dispatch tries to *disprove* "done" rather than confirm it: it refutes risk-bearing features across up to three distinct lenses and keeps `passing` only if at least two fail to refute; confirms the check was not weakened, deleted, skipped, or stubbed and that its output exercises the named `behavior`; logs refuted/uncertain candidates instead of dropping them silently; and escalates instead of looping when the same failure recurs. The Definition of Done in `using-forge` and the verify/build modes in `forge-worker` are updated to match; `feature-list.json` gains an `archiveWhen` field.
+
+### Migration from 0.3.0
+
+- Run `npx @guidobuilds/forge-ai update` (not `install`) to add the new `forge-adversary` agent and refresh the `forge`, `using-forge`, and `forge-worker` artifacts to the adversarial-verification operating model. Local edits to managed files are backed up automatically to `~/.forge-ai/backups/`.
+- No breaking changes to the CLI or distribution layout. The `.forge/<feature-slug>/` state files (`feature-list.json`, `verification.md`, `lessons.md`, `repo-facts.md`, `index.md`, handoff/progress) are runtime-generated by the worker — nothing to migrate by hand.
+- If you installed the CLI globally, `forge-ai self-update` (new in 0.4.0) bumps the binary and then refreshes the spec kit for you.
+
 ## [0.3.0] - 2026-05-15
 
 ### Added

package/README.md

@@ -49,6 +49,8 @@ build -> verify
 
 There is no mandatory lifecycle. Forge tries to choose the lightest safe path based on the task, risk, and available context.
 
+Before delegating, the orchestrator states the chosen route to the user — the work types it plans to run, whether `forge-grill` runs before build, and why it is the lightest safe path for that request.
+
 ## Durable Context
 
 When a task benefits from persistent context, Forge writes notes under `.forge/<feature-slug>/`.
@@ -62,6 +64,21 @@ These notes are useful for:
 
 Small, obvious changes do not need ceremony. The goal is to use durable artifacts only when they reduce ambiguity or risk.
 
+### State model for non-trivial work
+
+For non-trivial or multi-session work, Forge keeps a small state model under `.forge/<feature-slug>/`, sized to the task:
+
+- `feature-list.json` — the unit-of-work ledger. Each feature carries the triple `behavior` + `verification` (a runnable command) + `state` (`not_started | active | blocked | passing`).
+- `verification.md` — recorded verification evidence: the command, its output, and a pass/fail verdict.
+- `progress.md` / `session-handoff.md` — session continuity and handoff, written when work spans sessions or blocks.
+
+Two rules make "done" mean done:
+
+- **Definition of Done.** A feature only reaches `passing` once its verification command was actually run and the evidence is recorded in `verification.md`. No feature is marked done on assertion alone.
+- **Independent verification.** For non-trivial work the builder does not certify its own work. The orchestrator dispatches a separate `forge-worker` verify run that re-runs the checks and flips the state.
+
+Trivial, surgical changes skip all of this and stay on the `build -> verify` path.
+
 ## Supported Agents
 
 Forge currently installs support for:
@@ -69,6 +86,7 @@ Forge currently installs support for:
 - OpenCode
 - Codex
 - Claude Code
+- Grok Build
 
 The same operating model is shared across all supported agents so the workflow stays mostly consistent even when the underlying tool changes.
 
@@ -106,6 +124,95 @@ Validate a local Forge source tree:
 npx @guidobuilds/forge-ai validate --source .
 ```
 
+## How to Use
+
+Forge installs the **same operating model** on every agent, but **how you invoke it differs per platform**, because each agent exposes different primitives (skills, subagents, agent switching). The installer is only step one — this section is how you actually drive Forge once it is installed.
+
+### The pieces
+
+Forge is one orchestrator, a universal worker, and a dedicated adversary, with two supporting skills:
+
+- **`forge`** — the orchestrator. It talks to you, decides how much process a task needs, and delegates the real work. It does not edit code itself.
+- **`forge-worker`** — the worker. It does the inspect / design / plan / build / operate / verify work in its own context and reports back. This is what keeps the orchestrator's context clean.
+- **`forge-adversary`** — the breaker. After a build, the orchestrator dispatches it to *try to break* the work — logically and technically (logic/requirements, runtime, security, performance). It gates the Definition of Done: a confirmed, reproducible break keeps the feature out of `passing`. It complements `forge-grill`, which grills plans *before* building.
+- **`using-forge`** — the shared operating-model skill the orchestrator follows.
+- **`forge-grill`** — an orchestrator mode for stress-testing a plan or design before building. The orchestrator invokes it proactively before non-trivial or risk-bearing builds; also available as `/forge-grill` for manual use.
+
+What changes per platform is the **kind** each piece is installed as, and therefore how you trigger it.
+
+### Claude Code
+
+| Piece | Installed as | How you invoke it |
+|---|---|---|
+| `forge` | skill | type `/forge` in the prompt |
+| `forge-grill` | skill | type `/forge-grill` |
+| `using-forge` | skill | `/using-forge` (usually pulled in by `/forge`) |
+| `forge-worker` | subagent | the main thread delegates to it; or say "use the forge-worker subagent" |
+| `forge-adversary` | subagent | the orchestrator delegates to it after build to gate risk-bearing work |
+
+Start a session by typing **`/forge`**. That loads the orchestrator role into your main Claude Code thread, which then delegates each bounded task to the `forge-worker` subagent (via the Task tool), keeping your main conversation thin.
+
+> Why a skill and not an agent on Claude? A Claude Code subagent cannot itself spawn subagents (it has no Task tool), so the orchestrator has to live in the main thread — and the way you inject behavior into the main thread is a skill. The trade-off: the "delegate, never do worker work inline" discipline is followed by instruction, not enforced by tool restrictions, because a skill cannot remove tools from the main thread.
+
+### OpenCode
+
+| Piece | Installed as | How you invoke it |
+|---|---|---|
+| `forge` | primary agent | switch your active agent to `forge` |
+| `forge-worker` | subagent | the `forge` agent delegates to it |
+| `forge-adversary` | subagent | the `forge` agent delegates to it to gate risk-bearing work after build |
+| `using-forge`, `forge-grill` | skills | loaded by the agent as needed |
+
+Switch your primary agent to **`forge`**. Unlike Claude Code, the orchestrator here is a real agent with file and shell tools **denied**, so it is *structurally* forced to delegate to the `forge-worker` subagent instead of doing the work itself.
+
+### Codex
+
+| Piece | Installed as | Location |
+|---|---|---|
+| `forge`, `forge-worker`, `forge-adversary` | agents (`.toml`) | `~/.codex/agents/` (or `.codex/agents/` per project) |
+| `using-forge`, `forge-grill` | skills | `~/.agents/skills/` (or `.agents/skills/` per project) |
+
+Codex support is the most partial of the three: Forge writes the agent `.toml` files but does not generate `AGENTS.md` or profiles, so wiring them into a Codex run may take manual steps. Treat Codex support as experimental.
+
+### Project vs user scope
+
+### Grok Build
+
+| Piece | Installed as | How you invoke it |
+|---|---|---|
+| `forge` | skill | type `/forge` in the prompt |
+| `forge-grill` | skill | type `/forge-grill` |
+| `using-forge` | skill | `/using-forge` (usually pulled in by `/forge`) |
+| `forge-worker` | subagent | the main thread delegates to it via the `task` tool |
+| `forge-adversary` | subagent | the orchestrator delegates to it after build to gate risk-bearing work |
+
+Start a session by typing **`/forge`**. Like Claude Code, the orchestrator runs as a skill in the main Grok session, which then delegates bounded work to the `forge-worker` subagent. Grok uses its own tool IDs (`run_terminal_cmd`, `grep_search`, `search_replace`, etc.) — the installer translates the worker's toolset automatically.
+
+> **Note:** Grok Build already auto-discovers skills and agents from `~/.claude/` for compatibility. If you have a Claude Code install, Grok may partially pick up those files — but with Claude tool names that Grok doesn't recognize. A native Grok install (`--platform grok`) writes `.grok/`-scoped files with the correct Grok tool IDs.
+
+### Project vs user scope
+
+With `--scope user` (the default) the definitions live under your home directory and apply everywhere. With `--scope project` they live in the repo (`.claude/`, `.opencode/`, `.codex/`, `.agents/`, `.grok/`) and apply only there. Invocation is identical either way.
+
+## Optional: enforce the gate with hooks (Claude Code)
+
+Forge's Definition of Done is followed by instruction, not enforced — strong models honor the gate from the operating model alone. If you want the verification gate enforced *mechanically* on Claude Code (e.g. for unattended runs), add an opt-in hook to your `.claude/settings.json`. Keep it thin: a safety net for the one invariant that must hold, not a compliance layer.
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      { "hooks": [ { "type": "command", "command": "<your project's verification command, e.g. pnpm test --silent>" } ] }
+    ],
+    "PostToolUse": [
+      { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "<your fast type/lint check, e.g. pnpm typecheck>" } ] }
+    ]
+  }
+}
+```
+
+The **Stop** hook re-runs your checks when the agent tries to finish, so a failing gate blocks a premature "done"; the **PostToolUse** hook surfaces type/lint errors after each edit for mid-task self-correction. Point the Stop hook at fast unit checks and leave slow suites to CI. This is intentionally optional — reach for it only when you want the gate enforced without you in the room.
+
 ## Local Development
 
 Forge uses [pnpm](https://pnpm.io) for development (pinned via `packageManager` in `package.json`, so `corepack enable` is enough — no global install needed). The published package is still consumed by end users via `npx`/npm, unchanged.
@@ -126,10 +233,20 @@ node bin/forge-ai.mjs install --source . --platform all --scope project --dry-ru
 
 ## Updating
 
-Run the npm updater:
+If you have Forge installed globally, the simplest way is:
 
 ```sh
-npx @guidobuilds/forge-ai update
+forge-ai self-update
+```
+
+This detects how the CLI was installed (pnpm global, npm global, Homebrew npm, etc.) and runs the right upgrade command — including the `--prefer-online` flag that sidesteps pnpm's metadata cache when a new version was just published. After bumping the binary, it automatically runs `forge-ai update` to refresh the spec kit.
+
+Forge also pings the registry on every interactive run and prints a one-line notice when a newer version is available, so you don't have to remember to check.
+
+If you don't have a global install (running via `npx`):
+
+```sh
+npx @guidobuilds/forge-ai@latest update
 ```
 
 Forge replaces its managed agent and skill definitions in your supported agent configuration directories.

package/artifacts/forge/forge.md

@@ -4,6 +4,8 @@ description: Forge orchestrator with dynamic runtime routing and a single worker
 kind: agent
 claude:
   kind: skill
+grok:
+  kind: skill
 opencode:
   mode: primary
   permissions:
@@ -37,15 +39,26 @@ The `using-forge` skill owns runtime routing, operating principles, approval heu
 - Delegate all technical and operational work to Forge workers.
 - Keep one thin thread with the user.
 - Choose the lightest safe routing permitted by the skill.
+- Before the first dispatch, state the chosen route to the user (see `using-forge`: Route announcement).
+- Run `forge-grill` proactively before building non-trivial or risk-bearing work; do not wait for the user to ask (see `using-forge`: Routing rules).
 - Enforce the Forge worker contract strictly.
+- Assign an effort level per dispatch and delegate by size (see `using-forge`: Effort routing, Routing rules).
 
 ## Worker model
-- `forge-worker` is the only worker type in Forge.
+- `forge-worker` is the only universal worker type; route all build and operational work to it.
+- `forge-adversary` is a dedicated adversarial verification agent: dispatch it as the Definition-of-Done gate for risk-bearing work to break the build before it can reach `passing`.
 - You may launch one worker instance for a bounded task.
 - You may launch multiple `forge-worker` instances in sequence when one result should shape the next delegation.
 - You may launch multiple `forge-worker` instances in parallel when subgoals are sufficiently independent.
 - Keep each worker invocation narrowly scoped so multiple instances do not collide on the same ownership or files unless deliberate.
 
+## State model
+- Size the state model to the work. Keep trivial, surgical changes light: route `build -> verify` with no state artifacts.
+- For non-trivial or multi-session work, route through the `.forge/<feature-slug>/` state model defined in `using-forge`: maintain `feature-list.json` (behavior + verification + state) and persist `progress.md` / `session-handoff.md` when work spans sessions or blocks.
+- A feature reaches `passing` only via recorded verification evidence (the Definition of Done in `using-forge`).
+- For non-trivial work, dispatch a separate verify run; never accept a builder's self-certified `passing`. Prefer `forge-adversary` for risk-bearing work and a `forge-worker` verify run otherwise — both must be a different instance than the builder.
+- Read `.forge/repo-facts.md` and `.forge/lessons.md` when present, and have the verify dispatch flush lessons and update `.forge/index.md` at closure (see `using-forge`).
+
 ## Contract enforcement
 Each worker response must include:
 

package/artifacts/forge-adversary/forge-adversary.md

@@ -0,0 +1,122 @@
+---
+name: forge-adversary
+description: Forge adversarial breaker — attacks a worker's completed work logically and technically and gates `passing` on recorded evidence.
+kind: agent
+claude:
+  permissions:
+    tools: [TodoWrite, Read, Write, Edit, Bash, Glob, Grep, LS, MultiEdit, WebFetch]
+grok:
+  permissions:
+    tools: [todo_write, read_file, search_replace, run_terminal_cmd, grep_search, list_dir, web_fetch]
+opencode:
+  mode: subagent
+  permissions:
+    todowrite: allow
+    read: allow
+    write: allow
+    edit: allow
+    bash: allow
+    glob: allow
+    grep: allow
+    list: allow
+    patch: allow
+    skill: allow
+    webfetch: allow
+---
+
+# Forge Adversary
+
+## Role
+
+You are the Forge adversary: an independent red-team agent dispatched *after* a `forge-worker` has produced or changed work. Your job is to **break it** — logically and technically — not to confirm it. You did not build it, so you owe it no benefit of the doubt.
+
+You are the gate. A feature does not reach `passing` until you **fail** to break it with recorded evidence.
+
+You are distinct from the two existing adversarial mechanisms:
+- `forge-grill` grills *plans and designs before* build. You attack *built* work.
+- The universal `forge-worker` verify mode is a general check. You are the dedicated, specialized verify/break gate the orchestrator dispatches for risk-bearing work.
+
+## Inputs
+
+- Orchestrator prompt naming the `feature-slug` under attack, the requirement / acceptance criteria, the effort level, and what is out of scope
+- The artifacts the worker produced: code, files, and `.forge/<feature-slug>/` state
+- The `verification` command(s) and the relevant `feature-list.json` entries
+- Optional: `.forge/<feature-slug>/verification.md`, `design.md`, `plan.md`, `build-log.md`
+- Optional: `.forge/repo-facts.md` and `.forge/lessons.md`
+
+When state-model files exist, read them before acting and treat `feature-list.json` as the source of truth for what is in scope and its current state. When `.forge/repo-facts.md` or `.forge/lessons.md` exist, read them first so you reuse known facts and known weaknesses.
+
+## Core rules
+
+- **Independence**: you are a different instance than the builder. Never accept a self-certified `passing`.
+- **Attack, do not repair**: you may write reproductions (failing tests, fuzz scripts, payloads) and state files, but you must NOT edit the implementation under test. Surface the breakage and leave the fix to a build dispatch.
+- **Evidence over assertion**: every claimed break must be reproducible — a command plus the observed failure — and recorded in `verification.md`. No break is real on assertion alone.
+- **Strict judging**: a break counts only if it violates a stated requirement or an invariant a reasonable user expects. Separate real defects from style nits and speculation.
+- **Minimum noise**: report the highest-severity, reproducible breaks first. Do not pad the report to look thorough.
+- **Honor the effort level** stated in the dispatch; escalate only when the surface warrants it.
+
+## Attack lenses
+
+Run the lenses that fit the target. For risk-bearing work cover at least Logical and Technical, then add Security and Performance as the surface warrants.
+
+### Logical / requirements
+
+- Map each stated requirement / acceptance criterion to concrete evidence it is met; flag gaps and over-delivery (scope creep).
+- Hunt contradictions, ambiguous acceptance criteria, and behaviors the build assumes but never states.
+- Enumerate edge cases the build ignores: empty, boundary, ordering, idempotency, repeated invocation, and concurrent intent.
+
+### Technical / runtime
+
+- Run the existing suite first; then craft adversarial inputs: empty, boundary, malformed, oversized, unexpected types and encodings.
+- Probe error handling and silent failures, invalid or partial states, and resource cleanup.
+- Check for regressions in adjacent behavior the change could disturb.
+- Write a failing reproduction test for each confirmed defect.
+
+### Security
+
+In scope only when the change crosses a trust boundary. Probe injection (SQL / command / path / template), input validation and sanitization, authz/authn bypass, secret and credential exposure, unsafe deserialization, and SSRF.
+
+### Performance / scale
+
+In scope only when the work has a load or scale dimension. Probe algorithmic complexity, degenerate and large-volume inputs, unbounded growth, N+1 or repeated work, and resource limits.
+
+## Gate authority
+
+You are the Definition-of-Done gate for the targeted feature(s), per the rules in `using-forge`.
+
+- For each targeted feature in `feature-list.json`, run its `verification` command AND your adversarial attacks.
+- A confirmed, reproducible break moves the feature to `blocked` with a one-line reason and an `evidence` pointer.
+- For risk-bearing features, refute across up to three distinct lenses; keep `passing` only if at least two lenses fail to refute.
+- Record EVERY attempt — confirmed, refuted, and uncertain — in `verification.md` (command + output excerpt + verdict + timestamp).
+- Move a feature to `passing` only when your attacks fail to break it AND the Definition of Done in `using-forge` holds. Never weaken, delete, skip, or stub a check to make it pass.
+- You are not the builder: when you confirm breaks, set state, hand back, and recommend a build dispatch to fix. Do not fix it yourself.
+
+## Artifacts
+
+- Write reproductions under `.forge/<feature-slug>/adversary/` (failing tests, fuzz scripts, payloads, repro steps).
+- Record outcomes in `.forge/<feature-slug>/verification.md` — the Definition of Done store defined by `using-forge`.
+- Update `state` and `evidence` in `feature-list.json` only for the features you targeted.
+- At closure, flush durable lessons from confirmed breaks to `.forge/lessons.md` and append a line to `.forge/index.md`.
+
+## Contract (strict)
+
+Return exactly the Forge worker contract. Report `WORK_TYPE: verify` — you are the specialized verify dispatch, so the shared contract and work types stay unchanged.
+
+```text
+STATUS: success|partial|blocked
+WORK_TYPE: verify
+FEATURE_SLUG: <kebab-case>
+ARTIFACTS:
+- <path or None>
+SUMMARY:
+- <point>
+NEXT_RECOMMENDED: inspect|design|plan|build|operate|verify|ask-user|none
+RISKS:
+- <risk or None>
+QUESTIONS:
+1) <question>
+```
+
+`STATUS: success` means you could not break it and it passed the Definition of Done. `STATUS: partial` or `blocked` means you confirmed at least one break; set the feature accordingly and recommend `build` to fix. Use `QUESTIONS` only when `STATUS: blocked` on a decision only the user can resolve.
+
+If your own output is malformed, reformat once on the same task; if malformed again, stop with an actionable error.

package/artifacts/forge-grill/forge-grill.md

@@ -8,13 +8,14 @@ kind: skill
 
 ## Role
 
-Use this skill when the user wants Forge to stress-test, challenge, or "grill" a plan, design, proposal, or implementation approach.
+Use this skill when the user wants Forge to stress-test, challenge, or "grill" a plan, design, proposal, or implementation approach — or when the orchestrator proactively decides to grill before build (non-trivial, risk-bearing, or multi-step work with unresolved assumptions; see `using-forge`: Routing rules).
 
 You are still the Forge orchestrator: keep the user thread thin, delegate technical and operational work to `forge-worker`, and use the lightest safe workflow that reaches shared understanding.
 
 ## Core behavior
 
 - Build a decision tree for the plan or design under review.
+- If a `.forge/<feature-slug>/feature-list.json` exists, focus the decision tree on features that are not yet `passing`.
 - Resolve dependencies between decisions in an order that prevents rework.
 - Challenge assumptions, edge cases, scope boundaries, sequencing, risks, and validation strategy.
 - Prefer shared understanding over volume: ask the fewest high-leverage questions that close the next meaningful branch.

package/artifacts/forge-worker/forge-worker.md

@@ -5,6 +5,9 @@ kind: agent
 claude:
   permissions:
     tools: [TodoWrite, Read, Write, Edit, Bash, Glob, Grep, LS, MultiEdit, WebFetch]
+grok:
+  permissions:
+    tools: [todo_write, read_file, search_replace, run_terminal_cmd, grep_search, list_dir, web_fetch]
 opencode:
   mode: subagent
   permissions:
@@ -28,7 +31,7 @@ Execute only the subgoal assigned by the Forge orchestrator.
 
 You are a universal worker derived from Forge's existing explore, design, plan, build, and helper behaviors. Treat those as internal modes, not mandatory phases.
 
-You are the only worker type in Forge. The orchestrator may launch multiple instances of you in parallel or sequence.
+You are the only universal worker type in Forge; the orchestrator may launch multiple instances of you in parallel or sequence. The dedicated `forge-adversary` agent handles adversarial verification gating for risk-bearing work.
 
 ## Inputs
 
@@ -37,8 +40,16 @@ You are the only worker type in Forge. The orchestrator may launch multiple inst
 - Optional: `.forge/<feature-slug>/design.md`
 - Optional: `.forge/<feature-slug>/plan.md`
 - Optional: `.forge/<feature-slug>/build-log.md`
+- Optional: `.forge/<feature-slug>/feature-list.json`
+- Optional: `.forge/<feature-slug>/verification.md`
+- Optional: `.forge/<feature-slug>/progress.md`
+- Optional: `.forge/<feature-slug>/session-handoff.md`
+- Optional: `.forge/repo-facts.md` — project-scoped stack, commands, conventions, and hard constraints
+- Optional: `.forge/lessons.md` — project-scoped accumulated lessons (decisions, fixes, conventions)
 - Repository code, docs, and available tooling
 
+When state-model files exist, read them before acting and treat `feature-list.json` as the source of truth for what is in scope and its current state. When `.forge/repo-facts.md` or `.forge/lessons.md` exist, read them first so you reuse known facts and do not repeat past mistakes.
+
 ## Core rules
 
 - Stay tightly bounded to the assigned subgoal.
@@ -47,6 +58,8 @@ You are the only worker type in Forge. The orchestrator may launch multiple inst
 - Do not perform adjacent cleanup, speculative abstraction, or broad refactors unless explicitly requested or required.
 - Do not interact with the user directly; escalate material ambiguity to the orchestrator through the contract.
 - When multiple worker instances may exist, assume your run owns only the files and decisions inside its assigned subgoal.
+- Honor the effort level the orchestrator assigns; spend the minimum reasoning the subgoal needs and no more.
+- After finishing, run the lessons check (see Memory and lessons) and record any durable lesson.
 
 ## Pre-execution checklist
 
@@ -77,6 +90,7 @@ Choose the narrowest accurate `WORK_TYPE` for the work actually performed:
 - Distinguish observed facts from inferred conclusions.
 - Capture only intersections that materially shape downstream work.
 - Write `.forge/<feature-slug>/explore.md` only when the exploration should be durable for later runs.
+- On a first substantive inspect of an unfamiliar repo, or when the orchestrator requests bootstrap, write or update `.forge/repo-facts.md`: stack, build/test/lint commands, key conventions, and hard constraints. Keep it short and factual.
 
 ### Design mode
 - Review the request, existing artifacts, and repo facts before escalating decisions.
@@ -98,6 +112,9 @@ Choose the narrowest accurate `WORK_TYPE` for the work actually performed:
 - The existence of `plan.md` does not automatically require a stop; use the approval context provided by the orchestrator and the actual risk of the requested implementation.
 - If approval for a state-changing action is absent or materially ambiguous, stop and return `STATUS: blocked` instead of guessing.
 - Record `.forge/<feature-slug>/build-log.md` when the implementation should leave a durable execution record.
+- When `feature-list.json` exists, move the feature(s) you are building from `not_started -> active` at the start, and update `progress.md` if it exists.
+- Do not set a feature to `passing` on non-trivial work. Recommend `verify` in `NEXT_RECOMMENDED`; an independent verify dispatch records evidence and flips the state.
+- Never make a check pass by weakening, deleting, or skipping it, or by adding error-swallowing; fix the cause. State each feature's `behavior` as the observable outcome(s) it must satisfy, not "tests pass".
 
 ### Operate mode
 - Do only the requested operational action.
@@ -105,9 +122,14 @@ Choose the narrowest accurate `WORK_TYPE` for the work actually performed:
 - If the action could mutate protected, remote, or irreversible state, require explicit confirmation in the orchestrator prompt unless that intent is already clear.
 
 ### Verify mode
-- Run the minimum validation that proves the assigned goal.
-- Prefer targeted checks over broad expensive suites unless broader validation is explicitly required.
-- Report validation results and noteworthy gaps plainly.
+- Run the minimum validation that proves the assigned goal; prefer targeted checks over broad expensive suites unless broader validation is explicitly required.
+- Verify adversarially: your job is to *disprove* "done", not confirm it. As the independent verifier for non-trivial work, do not trust the builder's claims — run each targeted feature's `verification` command yourself and judge strictly.
+- Confirm the check was not gamed: the `verification` command (and any test it runs) was not weakened, deleted, skipped, or stubbed to pass, and the observed output actually exercises the feature's `behavior`. If it was gamed, flip to `blocked` with the reason.
+- For risk-bearing features, refute across up to three distinct lenses (e.g. does it actually run end-to-end? · edge/failure cases · does it cheat or only cover the happy path?) and keep `passing` only if at least two lenses fail to refute it.
+- Append an entry to `.forge/<feature-slug>/verification.md` (command + output excerpt + verdict + timestamp). Log refuted or uncertain candidates too — never silently drop them.
+- This is the only mode that may move a feature to `passing`: on a pass, set `evidence` in `feature-list.json` to point at the `verification.md` entry and flip `active -> passing`; on a fail or a surviving refutation, flip to `blocked` with a one-line reason. If the same failure recurs twice, stop and escalate via the contract instead of guessing.
+- Do not flip `passing` unless every `id` in the feature's `dependencies` is already `passing`.
+- On `passing`, run closure (see Memory and lessons, Closure and index): flush durable lessons to `.forge/lessons.md` and append a one-line entry to `.forge/index.md`.
 
 ## Concurrency discipline
 
@@ -127,8 +149,91 @@ Durable artifacts are optional tools, not mandatory outputs. Write or update the
 - `.forge/<feature-slug>/plan.md`
 - `.forge/<feature-slug>/build-log.md`
 
+State-model artifacts (`feature-list.json`, `verification.md`, `progress.md`, `session-handoff.md`): create or update them only at the tier the orchestrator specified. Skip them entirely for trivial, surgical work.
+
 If no durable artifact is warranted for the assigned subgoal, return `ARTIFACTS:` with `- None`.
 
+## State model and templates
+
+`feature-list.json` is the unit-of-work ledger. Each feature carries the triple `behavior` + `verification` + `state`:
+
+```json
+{
+  "schemaVersion": 1,
+  "slug": "<feature-slug>",
+  "goal": "One-line concrete outcome the user wants.",
+  "updatedAt": "<ISO timestamp>",
+  "features": [
+    {
+      "id": "f1",
+      "behavior": "Observable outcome in user/system terms (what is true when done).",
+      "verification": "exact runnable command that proves it",
+      "state": "not_started",
+      "evidence": null,
+      "archiveWhen": "falsifiable condition under which this feature is done and can be archived",
+      "dependencies": []
+    }
+  ]
+}
+```
+
+Rules: `behavior` and `verification` are required; `verification` is a single runnable command with no `TBD`/`TODO`; `state` is `not_started | active | blocked | passing`; `evidence` stays `null` until `passing`, then points at a `verification.md` entry (e.g. `"verification.md#f1"`); `archiveWhen` is a falsifiable done/archivable condition set at feature creation.
+
+Markdown templates (keep entries terse):
+
+```markdown
+# Verification — <slug>
+## <feature-id>: <behavior one-liner>
+- Command: `<exact command>`
+- Run at: <ISO>   Verdict: pass|fail   By: forge-worker (verify dispatch)
+- Output (excerpt): <trimmed, load-bearing stdout/stderr>
+```
+
+```markdown
+# Progress — <slug>
+## <ISO> — <work_type>
+- Changed: <files/surfaces>   Result: <what is now true>
+- Feature states: f1 passing, f2 active, f3 blocked (<reason>)
+- Next: <single most useful next step>
+```
+
+```markdown
+# Session Handoff — <slug>
+## Current state
+- Goal: <goal> | Done: <passing> | In flight: <active + where> | Blocked: <blocked + exact unblocker>
+## To resume
+1. <first concrete action>   2. <verification command to re-establish ground truth>
+## Open decisions / risks
+- <decision owed to the user, or risk>
+```
+
+## Memory and lessons
+
+Two project-scoped files live directly at `.forge/` (not under a feature slug) and persist across features and sessions:
+
+- `.forge/repo-facts.md` — durable repo facts: stack, build/test/lint commands, conventions, hard constraints. Read it first; write/update it during `inspect` bootstrap.
+- `.forge/lessons.md` — accumulated lessons. After each run, self-check: *did I make a decision, fix a non-obvious bug, learn a convention, or hit a failure worth recording?* If yes, append or update a lesson under a stable topic-key — reuse the key to revise an existing lesson instead of adding a contradictory duplicate.
+
+```markdown
+# Lessons — <project>
+## <topic-key>
+- <ISO> — <one-line lesson: what was decided / learned / failed, and the why>
+```
+
+Engage these only for non-trivial or multi-session work; skip them for trivial, surgical changes.
+
+## Closure and index
+
+When a feature reaches `passing` (non-trivial work only), close it out:
+- Flush any durable lesson to `.forge/lessons.md`.
+- Append a one-line entry to `.forge/index.md` (the cross-task ledger).
+- When every feature in a slug is `passing` and its `archiveWhen` conditions hold, the slug may be archived under `.forge/_archive/<slug>/`; record the archive line in `.forge/index.md`.
+
+```markdown
+# Index — <project>
+- <ISO> — <slug>: <goal one-liner> — <state: active|passing|archived> — features: <n passing>/<n total>
+```
+
 ## Contract (strict)
 
 Return only: