@codedology/code-forge 0.15.3 → 0.16.0

package/CHANGELOG.md

@@ -6,6 +6,57 @@ waits on a second real consumer (plan §10.4, Q17).
 
 ## [Unreleased]
 
+## [0.16.0] — 2026-11-01
+
+### Added
+
+- `forge spawn --print-argv` prints the exact command it would run and runs nothing; the Solo adapter guide step 2 now uses it (B229)
+- `npm run bench:block` measures one block flow under Node and under the Go daemon (process count, peak memory, wall time); each pass runs in its own child process (B184)
+- Forge facts checks the code names in a brief, marks ignored or outside-snapshot paths UNVERIFIABLE (never NOT-FOUND), takes claims from the brief only, maps absolute paths inside any `--sources` root to that source, and handles globs, `/dev/null` and route patterns (B227)
+
+### Changed
+
+- Reviewers get the bodies of the functions the changed code calls, inside the packet budget, so they stop raising false findings about code they could not see (B212)
+- A second stalled file now gets its own L3 patch rung instead of stopping the whole block with `l3_patch_exhausted` (B213)
+- The worker prunes done queue tickets and keeps an index; worker polls and done checks read only new ledger rows instead of the whole ledger each time (B214)
+
+### Fixed
+
+- Worker start times use one format everywhere: `ps` pads days 1-9 with two spaces, so worker pins and route checks failed on those days. Old padded pins still match (B225)
+- `gates run --changed` also runs the tests of files that import a changed file, so a change cannot break callers in other folders unseen (B221)
+- Daemon tests wait for readiness against a deadline instead of fixed sleeps, so they do not fail on a busy machine (B226)
+- `gates run --changed` gives each test runner only its own test files (no more `.go` files passed to `node --test`); when none fit, the gate runs the full suite and reports scope `full` (B203)
+- A gate that hits its time limit now says `TIMEOUT after <n> s (not a test failure)` with the flag to raise it, and test files left unfinished by the timeout are no longer listed as failed tests (B223)
+- `wait-block` no longer reports done while a file's last review was unavailable; it re-queues the file or names it, so `block close` does not refuse it later as unreviewed (B217)
+- `block close` no longer refuses a file that the block's own commits created and then deleted; a missing file with no such history still needs review (B230)
+- `status` warns when a live worker of the run is not the pinned one and names `run start --reattach`, before `block close` can stop blocks it served (B224)
+- CI is green again on Linux: `block rebase` works when git has no user name or email and keeps each commit's committer, and overlapping `watch` ticks for one block no longer lose state (B231)
+
+## [0.15.4] — 2026-10-31
+
+### Added
+
+- Go core, step 1: `native/` Go library (canonical JSON, row signing, ticket ids, ledger read) and a golden compat kit made from the Node functions; Go tests prove byte-equal output (B180)
+- `block land <id>` runs review join, changed-file gates and close in one step, stopping at the first failure with the next command; `--merge` also merges the block branch into its base (B185)
+- The npm package ships a prebuilt Go helper (`code-forge-native`, darwin/linux, arm64/x64; built at release) with `version` and `verify-ledger`; `doctor` shows it, and Node is used when it is missing or `CODE_FORGE_NATIVE=0` (B181)
+- `block land` and `block close --auto-claim` claim and review a file changed outside the owned list (unless another open block owns it), and claims are kept when a block is reopened with `--attempt N` (B186)
+- Review packets always keep the file's import header, the judge packet shows the cited `path:line` windows (ranges like `a-b` too), and `block reopen --yes` works on an open file with findings when the judge agrees (B192)
+- `block land --max <dur>` (default 30m) waits for reviews, retries the join up to 3 times while a findings round is open, and on timeout stops with `wait_timeout` and a next line that names a larger `--max` (B190)
+- Merge gate: `block land --merge` runs the full suite on the merged result in a temporary worktree first; a red suite or a conflict leaves main unchanged. Skip with `--no-merge-gate` or `gates.merge_gate: false` (B189)
+- A file whose review stopped with findings is reviewed again automatically when a fix changes its content; unchanged or waived files are not re-queued (B194)
+- Every Go command the tests run sets `CGO_ENABLED=0`, so `go test` passes on macOS without extra setup; `native/README.md` says how to test the Go code (B195)
+- `block waive --yes` now says the evidence may cite `:line or :start-end`, the same as `block reopen --yes`; a range citation is accepted (B193)
+- `forge facts` cuts an excerpt over 200 characters (ending with `…`) instead of refusing the whole sheet; repo-relative paths with an extension or a top-level folder, and absolute paths, are now path claims; `§ 12.1` is no longer a version claim; a long brief with almost no claims prints a warning (#29, B197)
+- Critical findings still need a human waiver by default; under an active autopilot grant, `block waive --yes` may waive a critical when the reason cites a passing acceptance test and the finding's lines and the judge agrees; the row records `by: agent` and `autopilot: true` (B196)
+- Go core, step 3: `code-forge-native daemon` serves `wait-block`, `block-tickets` and `status` over a Unix socket with a ledger tail index, a queue index and a cached worker start time; answers match the Node commands (compat tests). Not used by the CLI yet (B182)
+- The full test suite is green again: reopen output keeps its old text when no claims are kept, the config doc is current, and a plan clause that only cites a planned test file is no longer refused. (B204)
+- The native daemon status helper now lives with the other command files, so the import-order rule passes again. (B218)
+- Commit watch waits until a burst of commits ends (15 s quiet, 120 s at most) and reviews only the last commit, so a coder making several quick commits no longer starts extra reviews. (B211)
+- The worker and `status` use the native Go daemon when it runs and fall back to Node when it does not; status output is the same in every mode, and `doctor` shows the daemon state. (B183)
+- Two block tests now give the commit watch its second quiet tick, so they pass with the B211 debounce. (B219)
+- The worker runs up to 6 review tickets at once (was 3), with at most 4 sessions per provider (`review.provider_parallel`); tickets waiting for a provider still count toward the limit. (B208)
+- code-forge picks the primary reviewer from this project's measured speed, availability and accuracy (`review.adaptive`, on by default). A matching route still competes on performance unless it has `pin: true`. (B207)
+
 ## [0.15.3] — 2026-10-30
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 A CLI and Agent Skill for cross-model, parallel, evidence-gated feature delivery.
 
-Latest: 0.15.3 - see [CHANGELOG.md](CHANGELOG.md)
+Latest: 0.16.0 - see [CHANGELOG.md](CHANGELOG.md)
 
 ## The problem
 

package/docs/reference/blocks.json

@@ -4,7 +4,7 @@
     "plans/code-forge-plan-v1.3.md §10.4",
     "plans/NIGHT-LOG.md"
   ],
-  "block_count": 164,
+  "block_count": 165,
   "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": {
@@ -3036,6 +3036,14 @@
       ],
       "depends_on": ["B151"],
       "note": "F007 step 2; also amends the baseline-owned src/cli/validate.mjs to check the pipeline after config validation. Its pipeline import is recorded as an exact file/directory exemption in test/imports-order.test.mjs, following the existing later-block CLI amendments."
+    },
+    "B182": {
+      "title": "native daemon status companion",
+      "wave": 15,
+      "level": "L2",
+      "status": "landed",
+      "owned": ["src/cli/native-status.mjs"],
+      "depends_on": ["B64a"]
     }
   }
 }

package/docs/reference/config.md

@@ -11,6 +11,8 @@ Every other key defaults as shown, or is entirely absent from a minimal file. `a
 | Key | Type | Required | Default | Notes |
 |---|---|---|---|---|
 | `version` | const `1` | yes | — |  |
+| `native` | object |  | — |  |
+| `native.daemon` | boolean |  | `true` | Use the optional native daemon for run status and block waits. False uses Node only; CODE_FORGE_NATIVE=0 also disables it. |
 | `project` | object |  | — |  |
 | `project.name` | string |  | — |  |
 | `project.slug` | string |  | — | B50: the ledger name. Default: the project root's folder name (the nearest .code-forge.yml up to the git top level, else the git top level), so every verb run from a subfolder writes to the same ledger. |
@@ -115,9 +117,15 @@ Every other key defaults as shown, or is entirely absent from a minimal file. `a
 | `review.min_tokens_out` | integer |  | `120` | min 1; The stub guard: a review answer with fewer output tokens is unavailable (too_short). A clean pass (passed: true, no findings, a non-blank summary) needs only min(this, 40), whatever the diff size (B53). |
 | `review.batch_small_files` | boolean |  | `true` |  |
 | `review.session_timeout_s` | integer |  | `300` | min 1 |
+| `review.adaptive` | object |  | — | Choose the primary reviewer by availability × (1 − waived share) ÷ median session seconds from this project's ledger. No history keeps configured order; a matching explicit route has configured priority but competes on performance unless pinned. Disabling restores legacy routing exactly. |
+| `review.adaptive.enabled` | boolean |  | `true` |  |
+| `review.adaptive.window_days` | integer |  | `14` | min 1 |
+| `review.adaptive.min_sessions` | integer |  | `10` | min 1 |
+| `review.adaptive.explore` | number |  | `0.1` | min 0; max 1; Share of tickets given to a less-measured candidate, deterministically hashed from the ticket id. |
 | `review.routes` | array<object> |  | — | B90: size-based review routing. min_lines and model are required. A rule's level decides which sessions it changes: an L2 rule (level: L2, the default) changes only the reviewers' model, and in consensus mode only slot A (slot B stays review.second_levels.L2); an L3 rule changes only the judge's model. The count is the file's lines at the reviewed state (the bytes in the review packet): newline bytes, plus one for a last line without one; a deleted file is never routed. Rules compete only within their level: among the rules of one level, the largest min_lines at or under the count wins; the same level and min_lines twice is refused. Left out, an optional key gets: provider the top-level provider (the rule replaces the level entry, so the level's own provider is not inherited; validation checks the rule with that same provider); effort none; fallback none; session_timeout_s nothing (the rule does not count in the timeout); second review.second_levels for the rule's level. The timeout is one value for every session of the ticket: the largest session_timeout_s among the matched rules that set one (a matched rule without one is left out of that max), else review.session_timeout_s. The second-level try uses the rule's second, except for an L2 rule in consensus mode. The worker writes one signed review.route row per routed level before the first session, never twice for one ticket; its second_model is null when the rule's second is not used, which includes an L2 rule in consensus mode, because slot B is not the rule's. run reload accepts a change. |
 | `review.routes[].min_lines` | integer | yes | — | min 0; B90: the rule applies to a file with at least this many lines (0: every file that is not deleted). |
 | `review.routes[].level` | enum: `L2`, `L3` |  | `"L2"` | B90: the level the rule replaces, L2 (the reviewers) or L3 (the judge). |
+| `review.routes[].pin` | boolean |  | `false` | Force this matching route's model instead of adaptive primary-reviewer selection. |
 | `review.routes[].model` | string | yes | — | minLength 1 |
 | `review.routes[].effort` | string |  | — |  |
 | `review.routes[].provider` | enum: `anthropic`, `openai`, `xai` |  | — |  |
@@ -143,7 +151,8 @@ Every other key defaults as shown, or is entirely absent from a minimal file. `a
 | `review.provider_concurrency.anthropic` | integer |  | `4` | min 1 |
 | `review.provider_concurrency.openai` | integer |  | `2` | min 1 |
 | `review.provider_concurrency.xai` | integer |  | `2` | min 1 |
-| `review.parallel_tickets` | integer |  | `3` | min 1; max 16; B42: how many review tickets the worker runs at once (oldest first); 1 = one at a time. Tickets for the same file never overlap. |
+| `review.parallel_tickets` | integer |  | `6` | min 1; max 16; B42: how many review tickets the worker runs at once (oldest first); 1 = one at a time. Tickets for the same file never overlap. |
+| `review.provider_parallel` | integer |  | `4` | min 1; max 16; Maximum simultaneous review sessions per provider in the worker. Tickets waiting for this cap still count toward parallel_tickets; stricter provider_concurrency limits still apply. |
 | `review.fair_share` | boolean |  | `false` | Give each free ticket slot to the block with the fewest running tickets; ties stay oldest first. |
 | `review.file_loop` | enum: `wait`, `overlap`, `watch` |  | `"wait"` | After each green file, enqueue its review. wait (default): wait for its ticket before the next file. overlap: continue coding, then run review-file --wait-block <id> --run <run> before the completion sentinel; inspect findings with --wait <ticket>. watch: commit each green file instead of running review-file. A file's first commit is queued at once. Later commits of a file that already has a ticket of this block are held (a watch.held row) until --wait-block, which queues the latest content once before the sentinel. Older pending tickets are still superseded. |
 | `review.agent_waivers` | object |  | — | Human acknowledgement of counted agent waivers. Set before run start; run reload refuses to change require_ack. |
@@ -165,6 +174,7 @@ Every other key defaults as shown, or is entirely absent from a minimal file. `a
 | `gates.lint` | array<string> \| object \| null |  | — | An argv array (never a shell string), an {argv, env} object, or null. An argv item that is exactly {test_files} is replaced by the block's test files. It must be a whole item. It cannot be the command or the only item. The test files are the block open --tests paths, else the owned entries that are concrete test files. The item is dropped, and the full suite runs, in two cases. The block owns more files than full_suite_threshold_files (reason threshold). Or no test file is known, or the gate runs without --run/--block (reason no_tests). The gate.red and gate.done rows then carry scope related with test_count, or scope full with reason. With gates run --run --block --changed, {test_files} expands to changed tests plus stem-paired tests of changed sources, and {changed_files} expands to changed paths for lint or format. Both tokens must be whole argv items and cannot be the command or the only item. Config validation refuses a gate whose command or only item is {changed_files}. Deleted files count for pairing and the threshold, but both tokens receive only files that exist now. Without --changed, {changed_files} is dropped. Changed rows carry scope changed; narrowed rows have no reason. Only fallback rows carry a reason: no_baseline uses today's scope, unpaired uses today's test scope, threshold runs the full suite above the changed-file threshold, and no_changes uses today's scope when nothing is left to run. Gates without either token run unchanged. Any green gates run --run --block records owned file hashes on gate.done, including runs without --changed. When --slug is omitted, these rows go to the run's project ledger. More than 200 owned files means no record, so the next --changed falls back with no_baseline; unreadable inputs also leave no record. A fix-round TESTS line may use --changed; the orchestrator runs full gates before block close. |
 | `gates.types` | array<string> \| object \| null |  | — | An argv array (never a shell string), an {argv, env} object, or null. An argv item that is exactly {test_files} is replaced by the block's test files. It must be a whole item. It cannot be the command or the only item. The test files are the block open --tests paths, else the owned entries that are concrete test files. The item is dropped, and the full suite runs, in two cases. The block owns more files than full_suite_threshold_files (reason threshold). Or no test file is known, or the gate runs without --run/--block (reason no_tests). The gate.red and gate.done rows then carry scope related with test_count, or scope full with reason. With gates run --run --block --changed, {test_files} expands to changed tests plus stem-paired tests of changed sources, and {changed_files} expands to changed paths for lint or format. Both tokens must be whole argv items and cannot be the command or the only item. Config validation refuses a gate whose command or only item is {changed_files}. Deleted files count for pairing and the threshold, but both tokens receive only files that exist now. Without --changed, {changed_files} is dropped. Changed rows carry scope changed; narrowed rows have no reason. Only fallback rows carry a reason: no_baseline uses today's scope, unpaired uses today's test scope, threshold runs the full suite above the changed-file threshold, and no_changes uses today's scope when nothing is left to run. Gates without either token run unchanged. Any green gates run --run --block records owned file hashes on gate.done, including runs without --changed. When --slug is omitted, these rows go to the run's project ledger. More than 200 owned files means no record, so the next --changed falls back with no_baseline; unreadable inputs also leave no record. A fix-round TESTS line may use --changed; the orchestrator runs full gates before block close. |
 | `gates.format` | array<string> \| object \| null |  | — | An argv array (never a shell string), an {argv, env} object, or null. An argv item that is exactly {test_files} is replaced by the block's test files. It must be a whole item. It cannot be the command or the only item. The test files are the block open --tests paths, else the owned entries that are concrete test files. The item is dropped, and the full suite runs, in two cases. The block owns more files than full_suite_threshold_files (reason threshold). Or no test file is known, or the gate runs without --run/--block (reason no_tests). The gate.red and gate.done rows then carry scope related with test_count, or scope full with reason. With gates run --run --block --changed, {test_files} expands to changed tests plus stem-paired tests of changed sources, and {changed_files} expands to changed paths for lint or format. Both tokens must be whole argv items and cannot be the command or the only item. Config validation refuses a gate whose command or only item is {changed_files}. Deleted files count for pairing and the threshold, but both tokens receive only files that exist now. Without --changed, {changed_files} is dropped. Changed rows carry scope changed; narrowed rows have no reason. Only fallback rows carry a reason: no_baseline uses today's scope, unpaired uses today's test scope, threshold runs the full suite above the changed-file threshold, and no_changes uses today's scope when nothing is left to run. Gates without either token run unchanged. Any green gates run --run --block records owned file hashes on gate.done, including runs without --changed. When --slug is omitted, these rows go to the run's project ledger. More than 200 owned files means no record, so the next --changed falls back with no_baseline; unreadable inputs also leave no record. A fix-round TESTS line may use --changed; the orchestrator runs full gates before block close. |
+| `gates.merge_gate` | boolean |  | `true` | With block land --merge, run the configured full suite on a trial merge in a temporary detached worktree under the run worktree root before merging into main. Failure or conflict leaves main unchanged and removes the temporary tree. False or --no-merge-gate skips this check with a warning. Without --merge the gate does not run. |
 | `gates.kinds` | object |  | — | Optional gate sets for code, docs and contract blocks. Each value is an array of fixed gate names (test, lint, types, format) or gates.custom[].name values. Unknown names and explicitly null fixed gates are refused with the kind and name. With gates run --run R --block B, the declared block kind wins; otherwise the kind is inferred from owned files using block open's rules. An entry runs only its listed gates; every other configured gate is reported skipped with reason not in gates.kinds.<kind>. A missing entry runs all gates as usual. An empty array runs no commands, reports 0 gates for kind <kind>, and writes gate.done with all_ok: true so block close can proceed to its remaining checks. Light blocks keep their light rules and ignore kinds. A gates run without --block ignores kinds. Example: gates: {types: [npm, run, typecheck], kinds: {docs: [types], contract: []}}. |
 | `gates.kinds.code` | array<string> |  | — |  |
 | `gates.kinds.docs` | array<string> |  | — |  |

package/native/README.md

@@ -0,0 +1,10 @@
+# Native accelerator
+
+`native/` contains the optional Go accelerator and compatibility packages for code-forge.
+The build is pure Go, uses only the standard library, and keeps CGO off (`CGO_ENABLED=0`).
+This also avoids the macOS 26 LC_UUID linker error during local tests.
+Test from the repository root:
+
+```sh
+cd native && CGO_ENABLED=0 go vet ./... && CGO_ENABLED=0 go test ./...
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codedology/code-forge",
-  "version": "0.15.3",
+  "version": "0.16.0",
   "description": "Plan/harden/code/review orchestration CLI and Agent Skill for cross-model, parallel, evidence-gated feature delivery.",
   "repository": {
     "type": "git",
@@ -23,6 +23,7 @@
   },
   "files": [
     "bin",
+    "native/bin",
     "src",
     "schema",
     "skill",
@@ -33,6 +34,9 @@
     "!scripts/changelog.mjs",
     "!scripts/known-fix.mjs",
     "!scripts/bench-review.mjs",
+    "!scripts/bench-block.mjs",
+    "!scripts/build-native.mjs",
+    "!scripts/compat-golden.mjs",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -43,7 +47,8 @@
     "release": "node scripts/release.mjs",
     "changelog": "node scripts/changelog.mjs",
     "known-fix": "node scripts/known-fix.mjs",
-    "bench:review": "node scripts/bench-review.mjs"
+    "bench:review": "node scripts/bench-review.mjs",
+    "bench:block": "node scripts/bench-block.mjs"
   },
   "dependencies": {
     "@clack/prompts": "1.8.1",

package/schema/code-forge.schema.json

@@ -9,6 +9,13 @@
   "$comment": "version/provider/levels are REQUIRED with NO schema-level default (a config omitting them is refused here) — `migrate.mjs` fills a MISSING `version` to CURRENT_VERSION before this schema ever runs (so an on-disk file may omit `version`), but `provider` has no such auto-fill anywhere and must be present in the loaded document.",
   "properties": {
     "version": { "type": "integer", "const": 1 },
+    "native": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "daemon": { "type": "boolean", "default": true, "description": "Use the optional native daemon for run status and block waits. False uses Node only; CODE_FORGE_NATIVE=0 also disables it." }
+      }
+    },
     "project": {
       "type": "object",
       "additionalProperties": false,
@@ -166,6 +173,17 @@
         "min_tokens_out": { "type": "integer", "minimum": 1, "default": 120, "description": "The stub guard: a review answer with fewer output tokens is unavailable (too_short). A clean pass (passed: true, no findings, a non-blank summary) needs only min(this, 40), whatever the diff size (B53)." },
         "batch_small_files": { "type": "boolean", "default": true },
         "session_timeout_s": { "type": "integer", "minimum": 1, "default": 300 },
+        "adaptive": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Choose the primary reviewer by availability × (1 − waived share) ÷ median session seconds from this project's ledger. No history keeps configured order; a matching explicit route has configured priority but competes on performance unless pinned. Disabling restores legacy routing exactly.",
+          "properties": {
+            "enabled": { "type": "boolean", "default": true },
+            "window_days": { "type": "integer", "minimum": 1, "default": 14 },
+            "min_sessions": { "type": "integer", "minimum": 1, "default": 10 },
+            "explore": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.1, "description": "Share of tickets given to a less-measured candidate, deterministically hashed from the ticket id." }
+          }
+        },
         "routes": {
           "type": "array",
           "description": "B90: size-based review routing. min_lines and model are required. A rule's level decides which sessions it changes: an L2 rule (level: L2, the default) changes only the reviewers' model, and in consensus mode only slot A (slot B stays review.second_levels.L2); an L3 rule changes only the judge's model. The count is the file's lines at the reviewed state (the bytes in the review packet): newline bytes, plus one for a last line without one; a deleted file is never routed. Rules compete only within their level: among the rules of one level, the largest min_lines at or under the count wins; the same level and min_lines twice is refused. Left out, an optional key gets: provider the top-level provider (the rule replaces the level entry, so the level's own provider is not inherited; validation checks the rule with that same provider); effort none; fallback none; session_timeout_s nothing (the rule does not count in the timeout); second review.second_levels for the rule's level. The timeout is one value for every session of the ticket: the largest session_timeout_s among the matched rules that set one (a matched rule without one is left out of that max), else review.session_timeout_s. The second-level try uses the rule's second, except for an L2 rule in consensus mode. The worker writes one signed review.route row per routed level before the first session, never twice for one ticket; its second_model is null when the rule's second is not used, which includes an L2 rule in consensus mode, because slot B is not the rule's. run reload accepts a change.",
@@ -176,6 +194,7 @@
             "properties": {
               "min_lines": { "type": "integer", "minimum": 0, "description": "B90: the rule applies to a file with at least this many lines (0: every file that is not deleted)." },
               "level": { "type": "string", "enum": ["L2", "L3"], "default": "L2", "description": "B90: the level the rule replaces, L2 (the reviewers) or L3 (the judge)." },
+              "pin": { "type": "boolean", "default": false, "description": "Force this matching route's model instead of adaptive primary-reviewer selection." },
               "model": { "type": "string", "minLength": 1 },
               "effort": { "type": "string" },
               "provider": { "$ref": "#/$defs/provider" },
@@ -212,7 +231,8 @@
             "xai": { "type": "integer", "minimum": 1, "default": 2 }
           }
         },
-        "parallel_tickets": { "type": "integer", "minimum": 1, "maximum": 16, "default": 3, "description": "B42: how many review tickets the worker runs at once (oldest first); 1 = one at a time. Tickets for the same file never overlap." },
+        "parallel_tickets": { "type": "integer", "minimum": 1, "maximum": 16, "default": 6, "description": "B42: how many review tickets the worker runs at once (oldest first); 1 = one at a time. Tickets for the same file never overlap." },
+        "provider_parallel": { "type": "integer", "minimum": 1, "maximum": 16, "default": 4, "description": "Maximum simultaneous review sessions per provider in the worker. Tickets waiting for this cap still count toward parallel_tickets; stricter provider_concurrency limits still apply." },
         "fair_share": { "type": "boolean", "default": false, "description": "Give each free ticket slot to the block with the fewest running tickets; ties stay oldest first." },
         "file_loop": { "type": "string", "enum": ["wait", "overlap", "watch"], "default": "wait", "description": "After each green file, enqueue its review. wait (default): wait for its ticket before the next file. overlap: continue coding, then run review-file --wait-block <id> --run <run> before the completion sentinel; inspect findings with --wait <ticket>. watch: commit each green file instead of running review-file. A file's first commit is queued at once. Later commits of a file that already has a ticket of this block are held (a watch.held row) until --wait-block, which queues the latest content once before the sentinel. Older pending tickets are still superseded." },
         "agent_waivers": {
@@ -266,6 +286,11 @@
         "lint": { "$ref": "#/$defs/argvOrNull" },
         "types": { "$ref": "#/$defs/argvOrNull" },
         "format": { "$ref": "#/$defs/argvOrNull" },
+        "merge_gate": {
+          "type": "boolean",
+          "default": true,
+          "description": "With block land --merge, run the configured full suite on a trial merge in a temporary detached worktree under the run worktree root before merging into main. Failure or conflict leaves main unchanged and removes the temporary tree. False or --no-merge-gate skips this check with a warning. Without --merge the gate does not run."
+        },
         "kinds": {
           "type": "object",
           "additionalProperties": false,

package/schema/facts.schema.json

@@ -12,7 +12,7 @@
         "properties": {
           "fact_id": { "type": "string", "pattern": "^F[0-9]+$" },
           "claim": { "type": "string", "minLength": 1 },
-          "kind": { "type": "string", "enum": ["flag", "command", "path", "version", "endpoint", "package", "env"] },
+          "kind": { "type": "string", "enum": ["flag", "command", "path", "version", "endpoint", "package", "env", "symbol"] },
           "command": { "type": "string" },
           "output_excerpt": { "type": "string", "maxLength": 200 },
           "tag": { "type": "string", "enum": ["VERIFIED", "NOT-FOUND", "UNVERIFIABLE"] },

package/skill/SKILL.md

@@ -32,7 +32,7 @@ State lives in the plan file's header — `facts → planned → hardened → co
 | coder | the lane S1 picks (L0–L2); climbs one rung per escalation | the project tree | the engine adapter |
 | reviewer, recheck | L2 | closed-book, empty cwd, packet on stdin | the worker |
 | judge, S2, author | L3 | closed-book, one turn (never Codex: `references/security.md` §4) | the worker, `forge s2`, `forge author` |
-| L3 rung | L3 | a patch ≤ 80 lines, once per block | `forge spawn --level L3 --role coder` |
+| L3 rung | L3 | a patch ≤ 80 lines, once per file | `forge spawn --level L3 --role coder` |
 
 `forge resolve L<n>` prints what a level resolves to (provider, model, effort, fallback); `forge models` lists the catalog. With `review.multimodel` on, the second reviewer is another provider's L2 and the judge comes from a third provider.
 

package/skill/references/adapters/solo.md

@@ -16,7 +16,7 @@ Solo adds spawn, watch, timers, scratchpads, locks and `kv` on top of the CLI; i
 ## §3 Spawn protocol per block
 
 1. Pre-flight: `list_processes` and close **only** agents this run spawned (own pids only); `list_agent_tools` to resolve runtime ids live, never from memory. Never more than `caps.coders` coder processes alive; a further spawn waits for a completion wake, never for a timer.
-2. `forge block open <id> --run <r> …` (`code.md` §3), then `spawn_agent(agent_tool_id=<coder runtime>, name="coder-<id>", extra_args=<the argv the level resolves to>)` — the model, effort and permission mode are pinned **at spawn** from `forge resolve L<n>` and the provider's coder flags (`forge spawn --level L<n> --role coder --brief <file>` prints the exact argv without running it when you need to see it); never a post-boot model switch. Coders run in the provider's non-interactive auto mode: a session parked at a permission prompt is the first failure mode of every run.
+2. `forge block open <id> --run <r> …` (`code.md` §3), then `spawn_agent(agent_tool_id=<coder runtime>, name="coder-<id>", extra_args=<the argv the level resolves to>)` — the model, effort and permission mode are pinned **at spawn** from `forge resolve L<n>` and the provider's coder flags (`forge spawn --level L<n> --role coder --brief <file> --print-argv` prints the exact argv and runs nothing when you need to see it); never a post-boot model switch. Coders run in the provider's non-interactive auto mode: a session parked at a permission prompt is the first failure mode of every run.
 3. First `send_input` after the `❯` prompt: the agent's instructions, then the pointer (§2).
 4. **Launch-verification gate** — the one thing you babysit: poll `get_process_output` / `search_output` until the coder shows the ACK and tool activity. Dead-idle after the pointer (no prompt on screen) ⇒ one Enter (`send_input bytes=[13]`) and re-check. A **permission or model-picker prompt** is never answered with Enter — it would accept an unreviewed default: `close_process`, respawn with the correct `extra_args`, and record a `spawn-flag defect` line in the block record (the flags came from `forge resolve`; a prompt means they were not pinned).
 5. **Wake channels, event-driven, never fixed polls:** record your own pid once (`whoami` → `kv_set("forge:orchestrator_pid")`); coders that can call Solo carry the push contract (post-sentinel `kv_set("block:<id>", …)` + `timer_set(1s, body, delivery_process_id=<your pid>)`); for every group arm `timer_fire_when_idle_any([coders], max_wait≈20–25 min, delivery_process_id=<your pid>)` right after the launch gate (idle-any ignores already-idle processes, so arm while they are provably running); keep one long dead-man fallback per 30–40 min with an L0 triage first. On wake: sentinel ⇒ gate; no sentinel and active again ⇒ re-arm; no sentinel and idle ⇒ parked, intervene now.

package/skill/references/autopilot.md

@@ -13,6 +13,11 @@ Autopilot lets the owner leave for a set time. A delegate (a fresh L2 or L3 sess
 
 ## §2 During the window
 
+`block waive --yes` may waive a critical only while the run's autopilot grant is active; otherwise `waive-yes-critical`.
+Cite a test file named in the block's acceptance `tests:` and passed in its latest signed gate record for the current content; otherwise `waive-yes-critical-no-test`.
+Also cite the finding's path with `:line` or `:start-end`, and obtain agreement from the fresh L3 judge. Refusals write nothing.
+The signed waiver records `by: agent`, `autopilot: true` and the cited `test` path; the human can undo it with `block unwaive`. Warning/nit waivers are unchanged.
+
 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`.
@@ -44,7 +49,7 @@ These never go to the delegate, whatever the grant says (the CLI's fixed deny li
 - plan approval (`plan.md` §4.1) and design approval;
 - a budget raise (`code.md` §6, `review.md` §7);
 - a threshold edit or any other limit or rule change — only the owner's own `forge autopilot approve` at a terminal;
-- a critical waiver, a proof waiver, or closing a block without its reviews;
+- a critical waiver through the delegate's `autopilot waive` action (the evidence-backed agent exception is in §2), a proof waiver, or closing a block without its reviews;
 - merges and destructive actions.
 
 When one of these comes up during the window: stop that line of work, add it to Actions only you can take, and wait. The delegate never relaxes a rule or a limit to keep work moving (`rules-core.md` R17).

package/skill/references/code.md

@@ -87,6 +87,43 @@ Each `review-file` ticket is served by the worker `forge run start` launched: to
 
 ## §5 The block gate is a re-measurement — `forge block close <id> --run <r>`
 
+Paths added by `block claim` survive retries: `block open <id> --attempt N` (N > 1)
+restores earlier signed claims alongside `--owned`, and `block attempt` keeps them too.
+Both print `kept claims: <n>`. Do not claim the same paths again after a retry.
+
+The orchestrator can use `code-forge block land <id> --run <r> --report <file> --transcript <file> [--max <dur>] [--merge] [--no-merge-gate] [--json]`
+to join reviews, run changed gates in the recorded block worktree, then run the normal close checks.
+The first failure exits 1 and names the step, findings, gate output or close refusal, and the next
+command. Human checks must finish before a merge. With `--merge`, a closed block's branch is merged
+with `--no-ff` in the clean main checkout on the recorded base branch; the block worktree must also
+be clean. Before the real merge, land merges the current base branch HEAD and block branch in a
+temporary detached worktree under the run's worktree root and runs the configured full gates
+without block scope or `--changed`, using the shared gate runner. A green suite removes the
+temporary tree, prints `merge gate: full suite passed (<n>s)`, and permits the real merge.
+A red suite or conflict stops at `merge-gate` with the first ten failing TAP test names (or gate
+diagnostics) or conflict files and a `next:` action. Every outcome removes the temporary tree;
+a refusal leaves main clean and its HEAD unchanged. `gates.merge_gate` defaults to `true` in
+the run config; `false` or `--no-merge-gate` skips the check with a warning.
+It never forces or switches branches. Success prints `block <id> landed`; without
+`--merge`, it prints `block <id> closed; merge: <cmd>` and a hint that the merge gate runs only
+with `--merge`, and leaves the base unchanged. A merge refusal
+leaves the block closed; use the displayed next command after correcting the checkout. `--json`
+prints one object with `block`, `event` and `merge`, or a refusal with `step`, `reason` and `next`.
+
+`--max` defaults to `30m`; durations also accept seconds (`90s`) and milliseconds (`1500ms`).
+Land makes up to three join attempts while a held findings round remains open, all within one
+wait budget. Completed findings stop it. An exhausted wait stops at `join` with `wait_timeout`
+and prints a `next:` land command with a larger `--max`, preserving the report and transcript.
+
+Land automatically claims changed files outside the owned set before joining reviews.
+`block close --auto-claim` also claims, queues reviews in the block worktree, waits, and
+continues only after approval. Each file prints an auto-claim line and gets the same signed
+`block claim` row with `auto: true` and reason `auto-claim: changed outside owned files`.
+Findings stop the operation. A file owned or claimed by another open block still refuses
+`unowned_change`, naming that block, including separate worktrees. `.git/`, `.code-forge/`
+and paths outside the repository are never auto-claimed. Plain close keeps refusing
+unowned files; manual `block claim` remains available.
+
 To correct an open block's snapshotted clauses, the human uses `code-forge block amend-acceptance <id> --run <r> --acceptance <file> --reason <text>` with a nonblank reason and the same acceptance format as `block open`. Both terminals and confirmation are required, with no `--yes` and no active autopilot grant. Invalid or unchanged lists write nothing; a successful amendment updates the human checks and signs one `block.acceptance_amended` row with both clause-list hashes. Earlier reviews no longer count at close; review requests, block waits and watch ticks queue a fresh review with the new clauses. Coders must never run this human verb.
 
 The human can use `block close <id> --run <r> --decide --reason <text>` to see all waivable findings, unacknowledged agent waivers and acceptable transcript hits in one numbered list, then confirm once. Yes writes the same signed human rows as the individual verbs, with the shared reason for findings and hits, then runs normal close. No writes nothing. Unreviewed or stopped content needing a new review, failed gates, unowned changes and missing proof print `cannot decide here:` and write nothing. Both terminal streams are required; no `--yes`; an active autopilot grant refuses decision close. Coders must leave this step to the human.

package/skill/references/decisions.md

@@ -36,7 +36,7 @@ No key ⇒ a banner at run start; 401 ⇒ stop; 422 ⇒ stop with the request id
 3a. **Heavy rounds:** below L2, `escalation.after_rounds_with_warnings` (default 1) rounds at the current level whose open `fix_now` set holds ≥ `escalation.warning_threshold` (default 2) warnings or any `critical` ⇒ +1 level at once (`review_warnings`). A cheap coder that fails a round with several warnings climbs; it never spends three rounds at the same level. At L2 it does not fire — the L3 rung keeps its own triggers (rules 2, 3, 6). `after_rounds_with_warnings: 0` turns it off.
 4. **Security floor, at dispatch:** `security_sensitive` ⇒ first-attempt level `min(max(lane, L1) + 1, L2)` (`security`). Then the **docs floor**: a `docs` or `contract` block (below) is never dispatched under `levels.coder_floor_docs` (default L1) — `forge block open` raises the level and the `dispatch` row carries `requested_level` and `trigger: docs_floor`. L0 never codes docs or contracts.
 5. **S2 ruling:** S1 `next = escalate` is never acted on directly — it goes to S2 as a check (`s2_ruling`); S1 `next = stop` ⇒ the human.
-6. **Review cap:** `review.max_rounds_per_file` reached on a file with an open `fix_now` ⇒ the L3 rung for that file, once per block, always as a patch whatever `escalation.l3_mode` says (`review_cap`); checked last, only when no rule above returned an action this attempt.
+6. **Review cap:** `review.max_rounds_per_file` reached on a file with an open `fix_now` ⇒ the L3 rung for that file, once per file, always as a patch whatever `escalation.l3_mode` says (`review_cap`); checked last, only when no rule above returned an action this attempt.
 
 **Block kind.** `forge block open --kind code|docs|contract` declares it; without the flag it is detected from the owned paths: every path ends in `.md .mdx .markdown .rst .adoc` ⇒ `docs` (`.txt` is not docs: `requirements.txt`); every path is docs or a contract (`*.schema.json|yaml|yml`, `.proto`, `.graphql`, `.gql`, `.avsc`, `*.openapi.json|yaml|yml`, or a `.json/.yaml/.yml` under a `schema/`, `schemas/`, `contract/` or `contracts/` directory) and one is a contract ⇒ `contract`; anything else ⇒ `code`. A glob is judged by its literal ending, so a block owning `docs/**` declares its kind. The kind is recorded in the run record and drives the docs floor (rule 4) and the review topology (`review.md` §2).
 

package/skill/references/plan.md

@@ -2,12 +2,25 @@
 
 ## §0 Facts before design (step 0 of every plan)
 
-Run `forge facts --brief <brief> [--sources <path>...] --out <plans_dir>/<slug>.facts.md` before anything else. What it does:
+Run `forge facts --brief <brief> [--sources <path>...] --out <plans_dir>/<slug>.facts.md` before anything else.
 
-1. Deterministic: the CLI extracts every *claim token* from the brief and the sources it names — CLI flags, `<cli> <verb>` commands, paths, versions, endpoints, package names, environment variable names — and writes a claim list. A `<cli> <verb>` written without its CLI (`run reload`) whose first word is not one of the project's CLIs, not a well-known CLI (`git gh npm npx node pnpm yarn bun deno ls cat grep which find test make docker curl claude codex python python3 pip go cargo op`), and that the brief never uses as a CLI of its own (`` `gh` `` or `` `gh --repo x` `` in a code span) — decided from the brief and `package.json` alone, never PATH — becomes `<project CLI> <verb>` (`code-forge run reload`) when the brief itself (not a source) names one of the project's CLIs (its `package.json` `bin` names) as a whole word — `.code-forge.yml` or `code-forge.config` do not count; `plan check` then counts a clause citing `run reload` as backed by that VERIFIED fact, and only when the extra word is one of the project's own CLIs.
-2. One L0 session whose cwd is a **read-only snapshot of the repository at HEAD plus the `--sources` files**, built under the run's temp root and removed at session end — so `./path` claims are checkable, while **uncommitted files are not visible unless named as sources** (the snapshot is HEAD, not the working tree) — and whose packet is the claim list and the rule "run the cheapest read-only check, quote the command and the output line, tag VERIFIED / NOT-FOUND / UNVERIFIABLE, never infer". Two lines of defence, exactly as built. **First, at spawn:** the session gets the shell tool only, with the forbidden list plus every write verb rendered as deny rules and the provider's restricted mode (file tools confined to the working directory). Nothing is pre-approved: the delegate only runs what the provider already treats as read-only. A flag claim is therefore checked in the project's **source text**, never by running a program: `grep -rn -- <flag> <path>` over a top-level source folder of the snapshot such as `src` (never `.` or the root); it is VERIFIED only when the claim is that flag and the excerpt has a `file:line:text` hit from a source file — not `.md`/`.markdown`/`.txt`, not under `docs/ plans/ test/ tests/ fixtures/ node_modules/`, not the brief, and under the grep's path — holding the flag as a whole token (`--force-push` does not prove `--force`); a NOT-FOUND counts only over one whole top-level source folder that exists as a directory in the snapshot (not hidden, not `dist build coverage out` or the folders above). The grep's path must be an existing source directory of the snapshot (a nested one such as `src/cli` is fine for VERIFIED; a single file never is), and no other command — a plain grep included — ever proves or disproves a flag. Every check is ONE command: no pipe and no list (`| ; && || &`). There is no pre-execution gate on individual commands beyond the deny rules: the delegate runs what it runs. **Second, after the fact:** the CLI checks every `command` the delegate reports against an allow-list, fail closed, and refuses the whole sheet on the first violation. Allowed forms (never `rg`, which searches recursively by default): `ls cat head tail wc grep stat file uname sw_vers jq which` with in-cwd arguments (`grep` options only `-n -c -i -w -F` before `--`, recursive only as the whole command `grep -rn -- <--long-flag> <path>` with one relative subfolder, never `.` or a secret path; only a source folder proves a flag), `find` with only these predicates — `-name -iname -path -ipath -type -maxdepth -mindepth -print -print0 -newer -size -empty -mtime -mmin -not ! -a -o -and -or` — every other predicate refused, `git log|show|status|rev-parse|ls-files|cat-file`, `npm view|ls`, `test -e|-f|-d|-n <one operand>`, and `curl` as a HEAD request of exactly one http(s) URL with `-s -S -I -L -f --max-time <N>` only. No program ever runs with `--help`, `-h` or `--version` (BSD `rm foo --help` deletes `foo`): a version claim is checked with `npm view`, `which` or `ls`; an env claim is only `printenv NAME >/dev/null` with its excerpt blanked. Refused anywhere: backticks, `$`, redirection, unquoted globs, `~`, `..`, absolute paths outside `/usr`, `/opt/homebrew`, `/bin`, and secret-looking paths. **`npm view` and `curl -I` reach the network** — they are what makes a package version or an endpoint checkable; nothing else the delegate may run does.
-   **Path claims:** `./path` claims resolve against the HEAD snapshot, so a committed file is VERIFIED or NOT-FOUND by a plain `ls`/`test -e`; a file that exists only uncommitted in the working tree reads NOT-FOUND unless you passed it with `--sources`. `~/…` claims stay UNVERIFIABLE (`~` is refused), and absolute paths are allowed only under `/usr`, `/opt/homebrew` and `/bin`; a home-directory path that matters to a block is checked by you with one read-only command and recorded in the unbackable list with that command as the tolerance.
-3. Deterministic again: the answer is validated against the facts schema, rendered with `templates/facts-sheet.md`, and refused when a VERIFIED tag has no output excerpt. Every claim, command and excerpt passes through the redactor. The header records the brief's sha and mtime.
+Claims come from the brief only. `--sources <path>` chooses where checks run. Source text adds no claims.
+
+What it does:
+
+1. The CLI extracts claim tokens from the brief: flags, commands, paths, versions, endpoints, packages and environment names. Whole code spans also name `symbol` claims: PascalCase types with two or more humps, snake_case identifiers and code file names such as `SigmaClient.php`. A prose word such as Model adds no symbol. Command prefixes still come from the brief and the project's `package.json` bin names. For example, `run reload` becomes `code-forge run reload` when the brief names that project CLI. A known CLI or a CLI named separately in the brief keeps its own name.
+2. One L0 delegate checks a read-only snapshot. The project uses its git HEAD tree plus sources inside it. Each outside source directory appears under `_sources/<label>/`. Its label is its folder name; repeated names get `-2`, `-3`. Git sources use HEAD, limited to the named subfolder. Non-git sources use a copy. An outside source file appears at `_sources/<label>/<file name>`. Symlinks and secret files are dropped. Files and directories are sealed. The snapshot is removed when the session ends.
+
+   Absolute paths inside a root map to its snapshot path. Relative paths get one row per root when several roots are present. Flags and symbols also get a row per root. These rows have a `source` label. The sheet adds a `source` column after `kind` when any row has that label. A single-root relative claim keeps the old row format. Routes such as `/api/v1/*`, HTML fragments such as `/h1`, and `/dev/null` are not claims. An absolute path outside every source root and the tool roots is UNVERIFIABLE when its first directory exists on this machine.
+
+   Before the packet is sent, one `git check-ignore` batch checks each root's paths. Ignored paths are UNVERIFIABLE: `git-ignored in <label>: the snapshot leaves ignored paths out`. A path present on disk but absent from the snapshot is UNVERIFIABLE: `not at HEAD in <label>: outside the snapshot`. Neither goes to the delegate. Sources inside the project may still supply untracked files to the snapshot.
+
+   The delegate runs one read-only command per row and quotes its literal output. A flag needs `grep -rn -- <flag> <source folder>`. An identifier symbol needs `grep -rn -- 'TenantSubscription' app` or `grep -rn -- 'class TenantSubscription' app`. The quoted pattern is the token alone or one of `class interface trait enum struct type function func def` followed by the token. VERIFIED needs a `file:line:text` source-file hit holding the whole token. Markdown, text, docs, plans, tests, fixtures and the brief do not count. Symbols search one whole top-level source folder. A flag may use a nested source folder for VERIFIED; NOT-FOUND needs a whole top-level folder. Top-level means directly below a root: `src` or `_sources/<label>/app`. `_sources` itself never counts.
+
+   A file-name symbol needs `find <root> -name SigmaClient.php`, where the root is `.` or `_sources/<label>`. VERIFIED needs an output path ending in `/SigmaClient.php`. A glob path needs `find lang/es -name '*.php'`. Its pattern is quoted. Only that claim may also use `ls -d lang/es/*.php`, quoted or unquoted. VERIFIED needs a matching output path. NOT-FOUND needs `No such file` output. Unquoted globs on other claims are refused.
+
+   The session gets the shell tool with write deny rules and provider restrictions. Node validates the reported command afterward. Allowed reads include `ls cat head tail wc grep stat file uname sw_vers jq which`, `command -v`, the restricted `find` predicates, `git log|show|status|rev-parse|ls-files|cat-file`, `npm view|ls`, `test -e|-f|-d|-n`, and a single-URL HEAD `curl` request. No pipes or command lists. No program runs with `--help`, `-h` or `--version`. Versions use `npm view`, `which` or `ls`. Environment claims use only `printenv NAME >/dev/null`; their excerpts are blanked. Backticks, `$`, other redirections, `~`, `..`, secret paths and absolute paths outside `/usr`, `/opt/homebrew`, `/bin` are refused. Root paths in the brief use their mapped snapshot paths for checks. `npm view` and `curl -I` may reach the network.
+3. Node validates the closed delegate schema. A bad proof or an empty VERIFIED excerpt downgrades that row to UNVERIFIABLE with a reason. It does not count. Source labels are added by Node. Every claim, command, excerpt and reason passes through the redactor. The rendered sheet records the brief's sha and mtime.
 
 **Do not read the sources yourself; read the sheet.** Your context is spent on design, never on `--help` output. A fact is never a model's opinion: every claim carries the command that produced it.