@codedology/code-forge 0.14.0 → 0.15.0

package/docs/README.md

@@ -31,7 +31,7 @@ then 5a. Going away while a run goes on? Read 5b. One small task, no plan? Read
 | [reference/blocks.json](reference/blocks.json) | the build blocks of this package and what each one owns |
 | [marketing/code-forge-story.md](marketing/code-forge-story.md) | the marketing content bank (copy, lessons, what not to claim) |
 | [privacy.md](privacy.md) | what the local error log holds (errors, warnings, the last command names), every cleaning rule, the AI check, the setup check (`--with-doctor`), known fixes, and how to turn the log off or delete it |
-| [releasing.md](releasing.md) | for maintainers: record changes (`npm run changelog`) and known fixes (`npm run known-fix`), cut a release with one command (`npm run release`), publish by hand, GitHub Releases, the error-triage Action |
+| [releasing.md](releasing.md) | for maintainers: record changes (`npm run changelog`) and known fixes (`npm run known-fix`); release history lives only in CHANGELOG; releases update the optional README `Latest:` line; checks, commit, tag, manual publish, GitHub Releases, and the error-triage Action |
 | [`skill/SKILL.md`](../skill/SKILL.md) and [`skill/references/`](../skill/references/) | the Agent Skill the orchestrator follows. The deepest and most exact description of the rules |
 
 ## Conventions in these pages

package/docs/reference/blocks.json

@@ -4,7 +4,7 @@
     "plans/code-forge-plan-v1.3.md §10.4",
     "plans/NIGHT-LOG.md"
   ],
-  "block_count": 133,
+  "block_count": 149,
   "baseline_ids": ["B0", "B1", "B2", "B3", "B4", "B5", "B6", "B7", "B8"],
   "baseline_note": "Wave 0-1 blocks, landed before v1.3; depends_on may name them, but they have no entry under blocks.",
   "blocks": {
@@ -2335,6 +2335,425 @@
         "B123"
       ],
       "note": "block reopen <id> --file --reason --yes: the reason must cite evidence (reopen-yes-no-evidence), a fresh judge must agree (reopen-yes-disagreed), at most one agent reopen per block and file per run (reopen-yes-limit); the row is by: agent. An agreed, verified agent reopen supersedes the B123 cap like a human reopen. block close --json lists agent_reopens. Without --yes the verb still needs human confirmation."
+    },
+    "B128": {
+      "title": "CI green on Linux Node 22 and 24: test isolation flag both versions accept; claim fixture publishes its counts atomically",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "test/no-leak-final.test.mjs",
+        "test/worker/claim.test.mjs"
+      ],
+      "depends_on": [
+        "B115"
+      ],
+      "note": "Root cause: the claim fixture created its completion file before it wrote the count, so a Linux inotify wake could read an empty file as 0. Write to a temp file and rename. Node 22.23 rejects --test-isolation=none; use --experimental-test-isolation=none."
+    },
+    "B130": {
+      "title": "README for new users; per-version history lives only in CHANGELOG; release updates only the Latest line",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "README.md",
+        "scripts/release.mjs",
+        "docs/releasing.md",
+        "docs/README.md",
+        "CHANGELOG.md",
+        "test/release-readme.test.mjs",
+        "test/release.test.mjs",
+        "test/docs-marketing.test.mjs",
+        "test/skill/structure.test.mjs"
+      ],
+      "depends_on": [
+        "B108"
+      ],
+      "note": "README went from 474 to 171 lines: pitch, problem, install, quickstart, how it works, commands, agents, security, links (incl. public roadmap). Release no longer moves README bullets."
+    },
+    "B129": {
+      "title": "upgrade prints an ASCII code-forge logo, the version change and what's new; --plain for scripts",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/cli/upgrade.mjs",
+        "src/install/link.mjs",
+        "test/install/cli-upgrade.test.mjs",
+        "test/install/link.test.mjs",
+        "docs/getting-started.md",
+        "README.md",
+        "CHANGELOG.md"
+      ],
+      "depends_on": [
+        "B130"
+      ],
+      "note": "Install records get an optional version field. Summary: logo, 'code-forge <v>', '<old> -> <new>' / 'already on' / 'first versioned upgrade', kept record lines, first 5 CHANGELOG bullets, 'Full notes: <path>'."
+    },
+    "B131": {
+      "title": "Budget split counts removed lines; Markdown steps up to full; join reports an outcome per file and queues owned files with no ticket",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/review/engine.mjs",
+        "src/cli/review-file.mjs",
+        "skill/references/review.md",
+        "docs/how-it-works.md",
+        "CHANGELOG.md",
+        "test/review/budget-step-up.test.mjs",
+        "test/worker/wait-block.test.mjs",
+        "test/worker/watch.test.mjs",
+        "test/skill/structure.test.mjs"
+      ],
+      "depends_on": [
+        "B130"
+      ],
+      "note": "split_required only above full_in; --wait-block files carry outcome (approved/findings/stopped/split_required/unavailable/null); split_required gives done:false with reason and next."
+    },
+    "B132": {
+      "title": "A lens budget change reruns a split_required stop for the lens that was measured",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/cli/review-file.mjs",
+        "src/worker/ticket.mjs",
+        "src/worker/queue.mjs",
+        "src/review/fixloop.mjs",
+        "skill/references/review.md",
+        "CHANGELOG.md",
+        "test/worker/fresh-split.test.mjs",
+        "test/worker/fresh.test.mjs"
+      ],
+      "depends_on": [
+        "B131"
+      ],
+      "note": "F2: --fresh re-queues a counted split_required stop when its lens budget changed; the stop keeps its real lens (full, recheck or patch_check)."
+    },
+    "B135": {
+      "title": "Small CLI fixes: unknown ledger slugs, comma path lists, competing worker runs, /bin/ps, close needs green gates, accept-hit per line",
+      "wave": 14,
+      "level": "L1",
+      "status": "landed",
+      "owned": [
+        "src/cli/report.mjs",
+        "src/cli/ledger.mjs",
+        "src/cli/block.mjs",
+        "src/worker/loop.mjs",
+        "src/worker/queue.mjs",
+        "src/util/reaper.mjs",
+        "src/state/run.mjs",
+        "src/review/accept-hit.mjs",
+        "skill/references/code.md",
+        "CHANGELOG.md",
+        "test/ledger/report.test.mjs",
+        "test/ledger/cli.test.mjs",
+        "test/ledger/calibration.test.mjs",
+        "test/cli",
+        "test/worker/registry.test.mjs",
+        "test/util/reaper.test.mjs",
+        "test/state/run.test.mjs",
+        "test/review/close-gate.test.mjs",
+        "test/review/close-gate-field.test.mjs",
+        "test/review/gate-check.test.mjs"
+      ],
+      "depends_on": [
+        "B130"
+      ],
+      "note": "Closed after review, then held: the full suite showed regressions. Its changes landed through B135b."
+    },
+    "B135b": {
+      "title": "Finish B135: future test paths and brace globs allowed, first-use runs gates before close",
+      "wave": 14,
+      "level": "L1",
+      "status": "landed",
+      "owned": [
+        "src/cli/report.mjs",
+        "src/cli/ledger.mjs",
+        "src/cli/block.mjs",
+        "src/worker/loop.mjs",
+        "src/util/reaper.mjs",
+        "src/state/run.mjs",
+        "src/review/accept-hit.mjs",
+        "skill/references/code.md",
+        "CHANGELOG.md",
+        "test/ledger/report.test.mjs",
+        "test/ledger/cli.test.mjs",
+        "test/ledger/calibration.test.mjs",
+        "test/cli",
+        "test/worker/registry.test.mjs",
+        "test/util/reaper.test.mjs",
+        "test/state/run.test.mjs",
+        "test/review/close-gate.test.mjs",
+        "test/review/close-gate-field.test.mjs",
+        "test/review/gate-check.test.mjs",
+        "test/docs-marketing.test.mjs",
+        "scripts/first-use.mjs",
+        "test/first-use.test.mjs",
+        "test/gates/placeholders.test.mjs",
+        "test/proof/worktree-flow.test.mjs",
+        "test/review/external.test.mjs"
+      ],
+      "depends_on": [
+        "B135",
+        "B131"
+      ],
+      "note": "Carries the reviewed B135 changes onto the B131 base. A false critical finding was cleared by an answers ticket (B71), not a waiver."
+    },
+    "B133": {
+      "title": "A recheck must not repeat a stale finding: evidence in the recheck packet, current_lines quote, stale and repeated findings",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/review/fixloop.mjs",
+        "src/review/lenses/recheck.md",
+        "src/review/finding.schema.json",
+        "src/review/validate-review.mjs",
+        "skill/references/review.md",
+        "CHANGELOG.md",
+        "test/review/fixloop.test.mjs",
+        "test/review/validate-review.test.mjs",
+        "test/review/recheck-real.test.mjs"
+      ],
+      "depends_on": [
+        "B132"
+      ],
+      "note": "Stopped after review: the acceptance saved at open had a wrong stale rule. Its changes landed through B133b."
+    },
+    "B133b": {
+      "title": "Finish B133: stale only when a quoted current_lines is not in the file; a missing quote keeps the old behaviour",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/review/fixloop.mjs",
+        "src/review/lenses/recheck.md",
+        "src/review/finding.schema.json",
+        "src/review/validate-review.mjs",
+        "skill/references/review.md",
+        "CHANGELOG.md",
+        "test/review/fixloop.test.mjs",
+        "test/review/validate-review.test.mjs",
+        "test/review/recheck-real.test.mjs"
+      ],
+      "depends_on": [
+        "B133",
+        "B135b"
+      ],
+      "note": "Carries the B133 changes onto main with the corrected acceptance. Fixes issue #18."
+    },
+    "B134": {
+      "title": "Block open records the base branch HEAD; close warns when the base has commits the block lacks; block rebase accepts a closed block and keeps reviewed file blobs",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/state/block.mjs",
+        "src/cli/block.mjs",
+        "skill/references/code.md",
+        "CHANGELOG.md",
+        "test/state/block.test.mjs",
+        "test/cli/block-rebase-closed.test.mjs",
+        "test/cli/block-close-base-warning.test.mjs"
+      ],
+      "depends_on": [
+        "B135b"
+      ],
+      "note": "Fixes issue #21. A fix round removed a false warning when the block commits on its own base branch."
+    },
+    "B136": {
+      "title": "gates.repeat_new_tests: repeat the block's added or changed test files N times; a failed repeat is a red flaky-test gate with signed repeat evidence",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/cli/gates.mjs",
+        "src/gates/run.mjs",
+        "src/gates/expand.mjs",
+        "src/config/validate.mjs",
+        "schema/code-forge.schema.json",
+        "src/ledger/report.mjs",
+        "docs/reference/config.md",
+        "skill/references/code.md",
+        "CHANGELOG.md",
+        "test/gates/run.test.mjs",
+        "test/gates/cli.test.mjs",
+        "test/gates/changed.test.mjs",
+        "test/config/cli-validate.test.mjs",
+        "test/ledger/report.test.mjs",
+        "test/docs-config.test.mjs",
+        "test/config/schema-coverage.test.mjs"
+      ],
+      "depends_on": [
+        "B134"
+      ],
+      "note": "Fixes issue #20. A false critical finding (signed row callback) was cleared by making the sign-and-append call explicit."
+    },
+    "B137": {
+      "title": "A human device check gate: acceptance clauses marked human, block human-pass with a required note and optional proof, close refuses until passed",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/gates/acceptance.mjs",
+        "src/state/block.mjs",
+        "src/state/run.mjs",
+        "src/cli/block.mjs",
+        "src/cli/run.mjs",
+        "src/cli/status.mjs",
+        "src/cli/report.mjs",
+        "src/ledger/report.mjs",
+        "src/util/forbidden.mjs",
+        "skill/references/code.md",
+        "skill/SKILL.md",
+        "docs/how-it-works.md",
+        "CHANGELOG.md",
+        "test/gates/acceptance.test.mjs",
+        "test/cli/block-human-pass.test.mjs",
+        "test/util/forbidden.test.mjs",
+        "test/state/block.test.mjs"
+      ],
+      "depends_on": [
+        "B136"
+      ],
+      "note": "Stopped after review: the acceptance saved at open said --proof was required, but issue #19 makes it optional. Its changes landed through B137b."
+    },
+    "B137b": {
+      "title": "A human device check gate: acceptance clauses marked human, block human-pass with a required note and optional proof, close refuses until passed (corrected acceptance: proof optional)",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/gates/acceptance.mjs",
+        "src/state/block.mjs",
+        "src/state/run.mjs",
+        "src/cli/block.mjs",
+        "src/cli/run.mjs",
+        "src/cli/status.mjs",
+        "src/cli/report.mjs",
+        "src/ledger/report.mjs",
+        "src/util/forbidden.mjs",
+        "skill/references/code.md",
+        "skill/SKILL.md",
+        "docs/how-it-works.md",
+        "CHANGELOG.md",
+        "test/gates/acceptance.test.mjs",
+        "test/cli/block-human-pass.test.mjs",
+        "test/util/forbidden.test.mjs",
+        "test/state/block.test.mjs",
+        "test/engines/builders/argv-snapshots.test.mjs",
+        "test/engines/builders/forbidden-rendering.test.mjs",
+        "test/engines/codex-home.test.mjs"
+      ],
+      "depends_on": [
+        "B137",
+        "B136"
+      ],
+      "note": "Fixes issue #19. Fix round 1 appended the human-pass coder rule and updated the pinned coder-only counts. A false transcript hit (flag text inside an edit script) was accepted by the owner."
+    },
+    "B138": {
+      "title": "One human step per block: block close --decide lists every human-clearable refusal and asks one confirm; close.require_human; autopilot close:routine scope for routine closes",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/cli/block.mjs",
+        "src/state/block.mjs",
+        "src/review/gate-check.mjs",
+        "src/review/accept-hit.mjs",
+        "src/autopilot/scopes.mjs",
+        "src/autopilot/grant.mjs",
+        "src/config/validate.mjs",
+        "src/state/run.mjs",
+        "schema/code-forge.schema.json",
+        "docs/reference/config.md",
+        "skill/references/code.md",
+        "skill/references/autopilot.md",
+        "CHANGELOG.md",
+        "test/cli/block-close-decide.test.mjs",
+        "test/cli/block-close-routine.test.mjs",
+        "test/autopilot/grant.test.mjs",
+        "test/config/schema-coverage.test.mjs",
+        "test/autopilot/delegate.test.mjs",
+        "test/cli/autopilot.test.mjs"
+      ],
+      "depends_on": [
+        "B137b"
+      ],
+      "note": "Issue #16 item 8 (owner F4: one confirm + grant). Fix round 1 pinned close:routine in two old scope-message tests and proved the no answer was asked."
+    },
+    "B139": {
+      "title": "Light block kind: block open --kind light, one batched review per block (max 2), block-test-only gates, light-limits refusal at close",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/cli/block.mjs",
+        "src/state/block.mjs",
+        "src/worker/engine.mjs",
+        "src/worker/loop.mjs",
+        "src/worker/queue.mjs",
+        "src/review/engine.mjs",
+        "src/review/packet.mjs",
+        "src/cli/review-file.mjs",
+        "src/cli/gates.mjs",
+        "src/gates/run.mjs",
+        "src/gates/expand.mjs",
+        "src/config/validate.mjs",
+        "schema/code-forge.schema.json",
+        "docs/reference/config.md",
+        "skill/references/code.md",
+        "skill/references/review.md",
+        "CHANGELOG.md",
+        "test/cli/block-light.test.mjs",
+        "test/worker/light-batch.test.mjs",
+        "test/gates/run.test.mjs",
+        "test/config/schema-coverage.test.mjs"
+      ],
+      "depends_on": [
+        "B138"
+      ],
+      "note": "Issue #16 item 9 (owner F5: --kind light). Fix round 1: a cached light result was reused before the ticket hash check (critical). Fix round 2: test types."
+    },
+    "B107": {
+      "title": "Several review workers in one run: review.workers 1..4, run start --add-worker, worker identity on signed results, pin checks per worker",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/worker/loop.mjs",
+        "src/worker/queue.mjs",
+        "src/worker/engine.mjs",
+        "src/cli/run.mjs",
+        "src/util/forbidden.mjs",
+        "src/state/block.mjs",
+        "src/state/run.mjs",
+        "src/config/validate.mjs",
+        "schema/code-forge.schema.json",
+        "docs/reference/config.md",
+        "skill/references/review.md",
+        "CHANGELOG.md",
+        "test/worker/registry.test.mjs",
+        "test/worker/multi.test.mjs",
+        "test/state/block.test.mjs",
+        "test/util/forbidden.test.mjs",
+        "test/config/schema-coverage.test.mjs",
+        "test/engines/codex-home.test.mjs",
+        "test/engines/builders/forbidden-rendering.test.mjs",
+        "test/engines/builders/argv-snapshots.test.mjs",
+        "test/review/answers.test.mjs",
+        "test/review/reopen.test.mjs",
+        "test/review/route.test.mjs",
+        "test/worker/deletion-review.test.mjs",
+        "test/state/run.test.mjs"
+      ],
+      "depends_on": [
+        "B139",
+        "B106"
+      ],
+      "note": "Issue #16 item 7 (rest of Group E). Fix round 1: results without a worker field keep the old pin check (82 old tests). Fix round 2: a recycled live pid must match its own pin (critical); an added worker is stopped when its probe fails."
     }
   }
 }

package/docs/reference/config.md

@@ -55,6 +55,11 @@ Every other key defaults as shown, or is entirely absent from a minimal file. `a
 | `levels.L3.fallback[].effort` | string |  | — |  |
 | `levels.coder_floor_docs` | enum: `L0`, `L1`, `L2` |  | `"L1"` |  |
 | `orchestrator` | enum: `L0`, `L1`, `L2`, `L3` |  | — |  |
+| `light` | object |  | — |  |
+| `light.max_files` | integer |  | `5` | min 1; Maximum owned changed files in a light block at close. |
+| `light.max_lines` | integer |  | `300` | min 1; Maximum added plus removed lines in a light block at close. |
+| `close` | object |  | — |  |
+| `close.require_human` | boolean |  | `false` | B138: require a terminal-confirmed human close, unless an active close:routine grant covers a routine block. Read from the run snapshot; cannot change by run reload. |
 | `system1` | object |  | — |  |
 | `system1.provider` | enum: `anthropic`, `openai`, `xai` |  | — |  |
 | `system1.model` | string |  | — |  |
@@ -127,6 +132,7 @@ Every other key defaults as shown, or is entirely absent from a minimal file. `a
 | `review.routes[].second.fallback[].provider` | enum: `anthropic`, `openai`, `xai` | yes | — |  |
 | `review.routes[].second.fallback[].model` | string | yes | — | minLength 1 |
 | `review.routes[].second.fallback[].effort` | string |  | — |  |
+| `review.workers` | integer |  | `1` | min 1; max 4; B107: Maximum live workers serving the queue. The orchestrator adds one with run start --add-worker --run <id>. |
 | `review.max_rounds_per_file` | integer |  | `4` | min 2; max 6 |
 | `review.recheck_scope` | enum: `fix_hunks`, `file` |  | `"fix_hunks"` |  |
 | `review.late_findings` | enum: `sweep`, `block` |  | `"sweep"` |  |
@@ -161,6 +167,7 @@ Every other key defaults as shown, or is entirely absent from a minimal file. `a
 | `gates.extra.secret_scan` | boolean |  | `true` |  |
 | `gates.extra.safe_edit` | boolean |  | `true` |  |
 | `gates.extra.invariants` | string |  | — |  |
+| `gates.repeat_new_tests` | integer |  | — | min 2; max 10; After a passing test gate with --run and --block, run its command this many additional times for only tests added or changed against the block base; absent means off. Requires a whole {test_files} argv item; otherwise prints repeat_new_tests: skipped (gates.test has no {test_files}). A failed repeat makes the gate red with reason flaky-test; output and signed gate rows carry repeats {n, files, failed}, and report shows the count. |
 | `gates.full_suite_threshold_files` | integer |  | `10` | min 1; A block that owns more files than this runs the full suite for a {test_files} gate (reason threshold), not its related tests. Owned files are counted this way. A glob or a directory counts the tracked and new (not ignored) files it covers. A path not created yet counts as 1. Outside git each entry counts 1. A git failure runs the full suite. block open --tests names the test files precisely. With gates run --changed, the threshold counts changed files since the last green gates run --run --block instead. |
 | `proof` | object |  | — |  |
 | `proof.tiers` | object |  | — |  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codedology/code-forge",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Plan/harden/code/review orchestration CLI and Agent Skill for cross-model, parallel, evidence-gated feature delivery.",
   "repository": {
     "type": "git",

package/schema/code-forge.schema.json

@@ -41,6 +41,21 @@
       }
     },
     "orchestrator": { "$ref": "#/$defs/levelName" },
+    "light": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "max_files": { "type": "integer", "minimum": 1, "default": 5, "description": "Maximum owned changed files in a light block at close." },
+        "max_lines": { "type": "integer", "minimum": 1, "default": 300, "description": "Maximum added plus removed lines in a light block at close." }
+      }
+    },
+    "close": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "require_human": { "type": "boolean", "default": false, "description": "B138: require a terminal-confirmed human close, unless an active close:routine grant covers a routine block. Read from the run snapshot; cannot change by run reload." }
+      }
+    },
     "system1": {
       "type": "object",
       "additionalProperties": false,
@@ -170,6 +185,7 @@
             }
           }
         },
+        "workers": { "type": "integer", "minimum": 1, "maximum": 4, "default": 1, "description": "B107: Maximum live workers serving the queue. The orchestrator adds one with run start --add-worker --run <id>." },
         "max_rounds_per_file": { "type": "integer", "minimum": 2, "maximum": 6, "default": 4 },
         "recheck_scope": { "type": "string", "enum": ["fix_hunks", "file"], "default": "fix_hunks" },
         "late_findings": { "type": "string", "enum": ["sweep", "block"], "default": "sweep" },
@@ -246,6 +262,12 @@
             "invariants": { "type": "string" }
           }
         },
+        "repeat_new_tests": {
+          "type": "integer",
+          "minimum": 2,
+          "maximum": 10,
+          "description": "After a passing test gate with --run and --block, run its command this many additional times for only tests added or changed against the block base; absent means off. Requires a whole {test_files} argv item; otherwise prints repeat_new_tests: skipped (gates.test has no {test_files}). A failed repeat makes the gate red with reason flaky-test; output and signed gate rows carry repeats {n, files, failed}, and report shows the count."
+        },
         "full_suite_threshold_files": {
           "type": "integer",
           "minimum": 1,

package/scripts/first-use.mjs

@@ -25,8 +25,9 @@
  *    8 review  `code-forge review-file <file>` + `review-file --wait` per owned file
  *    9 proof   `proof export` (lists the export-ignore paths it restored), the test gate inside the
  *              export, `proof red-green` per test the acceptance names, `proof export --remove`
- *   10 close   `code-forge block close B1` — then the cost of the completed block is printed
- *   11 report  `code-forge report --slug <slug>`
+ *   10 gates   `code-forge gates run --run <run> --block B1` — green before close
+ *   11 close   `code-forge block close B1` — then the cost of the completed block is printed
+ *   12 report  `code-forge report --slug <slug>`
  * then `code-forge run end` (always, once the run started: it stops the worker).
  *
  * Engines: `harness` is the default (R2: the no-Solo default). `subprocess` is OPT-IN: it is
@@ -60,7 +61,7 @@ const DEGRADED_DOC = path.join(PKG, 'skill', 'references', 'degraded.md');
 
 export const BLOCK = 'B1';
 export const OWNED = Object.freeze(['src/math.mjs', 'test/clamp.test.mjs']);
-export const STEPS = Object.freeze(['copy', 'init', 'facts', 'author', 'start', 'open', 'code', 'review', 'proof', 'close', 'report']);
+export const STEPS = Object.freeze(['copy', 'init', 'facts', 'author', 'start', 'open', 'code', 'review', 'proof', 'gates', 'close', 'report']);
 const ENGINES = ['harness', 'subprocess'];
 const CODERS = ['scripted', 'harness', 'spawn'];
 const CLI_TIMEOUT_MS = 30 * 60 * 1000;
@@ -385,7 +386,12 @@ export async function main(argv, io = {}) {
     await cf(['proof', 'export', BLOCK, '--run', run, '--remove']);
     if (done('proof')) return 0;
 
-    // 10 — the gate, then what the completed block cost
+    // 10 — record green gates for this run and block, after the proofs
+    step('gates');
+    say((await cf(['gates', 'run', '--run', run, '--block', BLOCK])).stdout.trimEnd());
+    if (done('gates')) return 0;
+
+    // 11 — the close check, then what the completed block cost
     step('close');
     say((await cf(['block', 'close', BLOCK, '--run', run])).stdout.trimEnd());
     blockOpen = false;
@@ -398,7 +404,7 @@ export async function main(argv, io = {}) {
     );
     if (done('close')) return 0;
 
-    // 11 — the report
+    // 12 — the report
     step('report');
     const report = await cf(['report', '--slug', /** @type {string} */ (summary.slug)]);
     stdout.write(report.stdout);

package/skill/SKILL.md

@@ -22,6 +22,8 @@ State lives in the plan file's header — `facts → planned → hardened → co
 
 ## §2 Roles by level (never by model name)
 
+`block human-pass <id> --run <r> --note <text> [--proof <dir-or-file>]` is human-only: the owner checks the listed device checks and confirms in their own terminal, with no `--yes` and no active autopilot grant. The note is required; proof is optional, must name an existing path when given, and is recorded as `proof: null` when omitted. A successful code close with `kind: human_check` acceptance clauses leaves `awaiting_human_check`, which status and report list; it has no fresh done file until the human passes or stops it. Never run this verb for the human, and do not end the run or treat the block as ready to land while it is awaiting a check (`references/code.md` §5).
+
 | role | level | session | who runs it |
 |---|---|---|---|
 | facts delegate | L0 | read-only tools, empty cwd | `forge facts` |

package/skill/references/autopilot.md

@@ -13,6 +13,8 @@ Autopilot lets the owner leave for a set time. A delegate (a fresh L2 or L3 sess
 
 ## §2 During the window
 
+The allowable scope `close:routine` means “close a routine block.” It lets plain `block close` pass `close.require_human` without a terminal when every changed file has a signed approval, a signed green gate row exists, and the block has no waiver rows, transcript hits or accepted hits. Waived or answered-only reviews do not qualify. Refusal is `close-not-routine: <reason>` (exit 1); success signs `autopilot.close {block, grant}` alongside the normal close. It never permits `block close --decide` or critical waivers.
+
 - **Every owner-level question goes to the delegate first**: `forge autopilot ask --run <r> --scope <scope> --question <text> --options <words> [--block <id>] [--file <path>] [--finding <id>]`. Use the fixed option words, or the action will refuse the answer: a waiver `waive,fix` · an extra round `allow,deny` · a coder level the candidate levels, e.g. `L1,L2`.
 - **Act only when it acted** (exit 0): run the action with `--decision <id>` from the answer — `forge autopilot waive|round|level … --decision <id>`. Exit 3 means the question goes to the owner: leave it open, it shows under Open questions. Exit 1 means the grant refused it: also the owner's.
 - **A paused category** (`autopilot paused: … waiting for the owner`): wait. Never raise the cap, never route around it.