@codedology/code-forge 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -6,6 +6,59 @@ waits on a second real consumer (plan §10.4, Q17).
 
 ## [Unreleased]
 
+## [0.14.0] — 2026-10-15
+
+### Changed
+
+- `review-file --wait-block`: when the current content's ticket is done with a result that never counted (`stale`, `unavailable`, round-1 `split_required`), the join drops that done marker with the `--fresh` claim and the worker reviews the content once; one drop per ticket at most, kept on disk; a counted result is never dropped (B125)
+- `block waive --yes`: a warning or nit finding can be waived without a terminal when the reason cites evidence (path:line, a test file, or an acceptance clause) and a fresh L3 judge agrees; one signed `review.waived {by: agent}` row with the verdict; refusals `waive-yes-critical`, `waive-yes-no-evidence`, `waive-yes-disagreed`; `block close` lists agent waivers and `--json` adds `agent_waivers`; `block reopen` stays human-only (B124a)
+- `block accept-hit <id> --run --rule --line --transcript --reason`: human-only; refuses `accept-hit-no-such-hit` before any prompt; writes a signed `rule_break.accepted {block, rule, line, line_sha256, reason, by: human}` row; `block close` drops a transcript hit only on the same rule and the sha256 of that line, prints each accepted hit, and `--json` adds `accepted_hits`; the verb is on the coder forbidden list (B127)
+- `block unwaive <id> <finding> --run --file --reason`: human-only; refuses `unwaive-no-agent-waiver` before any prompt; a signed `review.unwaived` row cancels the earlier agent waivers of that finding at the gate and the review-file pre-check; `code-forge report` gets a 15th section `agent_waivers`; new key `review.agent_waivers.require_ack` (frozen at run start): `block close` refuses `agent-waivers-not-acked` until a human `block ack-waivers <id> --run` row matches the current agent waivers (`ack-waivers-none` when there are none); both verbs are on the coder forbidden list (B124b)
+- `block reopen <id> --file --reason --yes`: agent reopen; refuses `reopen-yes-no-evidence` without cited evidence, `reopen-yes-disagreed` when a fresh judge disagrees, and `reopen-yes-limit` after one agent reopen per block and file in a run; the row is `by: agent`; an agreed, verified agent reopen supersedes the review cap like a human reopen; `block close --json` lists `agent_reopens` (B124c)
+- Docs: the README command table lists `--yes` on `block waive` and `block reopen` and adds `block accept-hit`, `block unwaive` and `block ack-waivers`; `docs/getting-started.md` and `skill/references/review.md` no longer say reopen has no `--yes`
+
+
+## [0.13.0] — 2026-10-14
+
+### Changed
+
+- The leak test in `test/worker/orphan.test.mjs` takes the current contents of the repo's `.code-forge` folder as its baseline, so `npm test` passes when that folder already holds files (B126).
+- Close check: a `review.cap` row is superseded by a later verified human `review.reopened` row followed by a signed
+  `review.round` of the file's current content; a superseded cap row adds no ids, so old stop findings need no
+  waiver after a reopen (B123)
+- `review-file --wait-block`: a file whose newest review left open findings and whose content changed after it is not
+  re-queued; the join answers `status: findings` with that ticket and writes one delivered marker; the next join
+  queues the latest content once, so a commit made blind to the findings never counts as a stall round (B122)
+- Worker registry: each worker writes `<repo>/.code-forge/workers/<pid>-<start_time>.json` next to `queue/worker.json`
+  and beats both; boot counts live entries and writes its entry under one cross-process lock (limit 1); boot
+  removes dead entries (a known start-time mismatch is dead); an unreadable entry blocks the boot and `doctor`
+  lists it; `liveWorker` keeps the B30 fresh-heartbeat rule (B106)
+- Watch mode holds rechecks: a commit of a file that already has a ticket gets no ticket, only a `watch.held`
+  row; `review-file --wait-block` queues one ticket for the latest content; older pending tickets are still
+  superseded (B121)
+- Locks now hold across processes (`src/util/file-locks.mjs`, `~/.code-forge/locks`): ticket claims, the per-file and
+  block locks, the budget row, schema fallback and autopilot actions; a dead owner's lock (pid + start time) is broken
+  under a per-key break mutex; `doctor` lists bad locks and crashed break mutexes (B105)
+- New opt-in key `review.fair_share` (boolean, default `false`): the worker pool gives each free slot to the
+  pending ticket whose block has the fewest running tickets; ties stay oldest first (B101)
+- `context pack` with no `context` key writes a pack with the block header and the built-in proof rule (300-line cap)
+  instead of refusing; a bad `context` value still refuses (B118)
+- `block close` prints `WARN block <id>: no green gates run for this block; …` when `gates.test` is set and the block's
+  last gate row is not a green `gate.done`; it still closes (B118)
+- `block close --transcript` reads a Codex JSON log (`codex exec --json`) by its commands and file writes only;
+  agent messages, reasoning, command output and non-item events are skipped; other logs are scanned as before (B119)
+
+### Fixed
+
+- `block open` refuses an `--owned` or `--tests` entry that contains whitespace and names no existing file or directory
+  (a shell quoting slip), naming the entry; nothing is written (B118)
+- `npm test -- --test-name-pattern=<p>` exits 0: six test files no longer call `rm(undefined)` in cleanup when
+  their setup was skipped by the pattern (B116, built with `code-forge run` itself)
+- The close reason names each transcript rule break once (`rule_break transcript line <n>: <id>`, at most 5,
+  then `+<k> more rule_break`) instead of repeating a bare `rule_break` (B119)
+- `gates run --run <r> --block <id>` with plain gates (no `{test_files}`, no `--changed`) writes its `gate.done` and
+  `gate.red` rows to the run's project ledger; before, it wrote none, so the B118 close warning fired after a green run (B120)
+
 ## [0.12.0] — 2026-10-14
 
 ### Added

package/README.md

@@ -8,10 +8,36 @@ for cross-model, parallel, evidence-gated feature delivery — on Claude Code, C
 > `examples/` have all landed (`docs/reference/blocks.json` lists every build block). What changed
 > in each version is in [CHANGELOG.md](CHANGELOG.md).
 
-## What's new in 0.12
+## What's new in 0.14
 
 In the next release:
 
+In 0.14.0:
+
+- **A stale review no longer counts as done (B125).** When a file changed during its review and came back to the same content, `review-file --wait-block` now reviews it once more by itself. No `--fresh` by hand.
+- **Agent waivers with proof (B124a).** `block waive --yes` now works for a warning or nit finding. The reason must name evidence: a `path:line`, a test file, or an acceptance clause. A fresh judge must agree. The row is marked `by: agent`, and `block close` lists it. A critical finding and `block reopen` stay human-only.
+- **Accept a false rule hit (B127).** `block accept-hit <id> --run <r> --rule <rule-id> --line <n> --transcript <path> --reason <text>` lets a human accept one false transcript hit, after a yes in their own terminal. The close then skips that hit only when the rule and the exact line text match. The close lists each accepted hit, and `--json` adds `accepted_hits`. A coder can never run this verb.
+- **Undo and check agent waivers (B124b).** `block unwaive <id> <finding> --run <r> --file <path> --reason <text>` lets a human undo one agent waiver. The finding is then open again. `code-forge report` has a new `agent_waivers` section. Set `review.agent_waivers.require_ack: true`, and `block close` waits until a human runs `block ack-waivers <id> --run <r>` and says yes to the list. Both verbs are human-only.
+- **Agent reopen with evidence (B124c).** `block reopen <id> --file <path> --reason <text> --yes` lets the orchestrator reopen a stopped file without you. The reason must cite evidence, a fresh judge must agree, and only one agent reopen per block and file is allowed in a run. The row says `by: agent`. `block close --json` lists them in `agent_reopens`. Without `--yes`, a human still confirms.
+
+## What's new in 0.13
+
+In 0.13.0:
+
+- **Every block gets the proof rule, with or without a `context` key (B118).** `code-forge context pack` no longer refuses a config with no `context` key. The pack then holds the block header and the proof rule.
+- **Safer block open and close (B118).** `block open` refuses an owned or test path that has spaces and names no file, a common shell quoting slip. `block close` warns when the block has no green gates run.
+- **Clean rule checks on Codex logs (B119).** Run `codex exec --json` and pass the log to `block close --transcript`. code-forge then checks only the commands Codex ran and the files it wrote. Agent messages, reasoning and command output no longer give false rule breaks. The close reason names each rule break once.
+- **Gate results are recorded again (B120).** `gates run --run <r> --block <id>` now writes its `gate.done` row also when no gate uses `{test_files}`. Before, the row was missing, so `block close` warned after a green run and `status` showed no gate result.
+- **Fair share between blocks (B101).** Set `review.fair_share: true` and each free review slot goes to the block with the fewest running reviews. A block with many queued files no longer makes another block wait. Without the key, the order stays oldest first.
+- **Locks hold across processes (B105).** Ticket claims and the locks for files, blocks and the budget row now work across worker processes. Lock files live in `~/.code-forge/locks`. A lock of a dead process is taken over safely. A bad lock, or a break lock left by a crashed process, blocks its key until you remove it, and `code-forge doctor` names it.
+- **Watch waits for the whole fix (B121).** In watch mode, a file's first commit is reviewed at once. A later commit of a file that already has a review is held, and a `watch.held` row records it. `review-file --wait-block` then queues one review for the file's latest content. A half-done fix commit no longer uses up the file's review rounds.
+- **One registry file per worker (B106).** Each worker writes its own file in `.code-forge/workers/` and keeps it fresh with its heartbeat. A new worker starts only when the live count is under the limit, which is 1 for now. The count and the new file are written under one lock, so two workers that start at the same time cannot both run. A file of a dead worker is removed at the next start. A file that cannot be read blocks the start, and `code-forge doctor` names it.
+- **The join shows findings before it rechecks (B122).** Sometimes the coder commits again before reading the last review. At `review-file --wait-block`, such a file is not reviewed again yet. The join answers `findings` with the old ticket, so the coder reads and fixes them first. The next join rechecks the latest content once. A blind commit no longer counts as a stall round.
+- **A reopen clears old stop findings (B123).** After `block reopen` and a fresh review of the new content, the close no longer asks you to waive the findings of the old stop. Only the fresh review's findings count.
+- **The test suite passes on machines that use code-forge on itself (B126).** A leak test no longer counts files that were already in the repo's `.code-forge` folder.
+
+## What's new in 0.12
+
 In 0.12.0:
 
 - **Faster fix rounds (B99).** `code-forge gates run --run <r> --block <id> --changed` runs only the tests of files changed since the last green gate run, and `{changed_files}` passes only the changed files to lint or format gates. It falls back to the normal scope when it cannot be sure.
@@ -339,7 +365,7 @@ usage line.
 | `validate` | `code-forge validate [--file <path>]` |
 | `resolve` | `code-forge resolve <L0\|L1\|L2\|L3>` |
 | `run` | `code-forge run start [--cwd <dir>] [--run <id>] [--engine <e>] [--worker-pid <pid>]` · `run start --reattach --run <id> [--worker-pid <pid>]` · `run status --run <id>` (with spent and budget USD) · `run reload --run <id>` (re-read `.code-forge.yml` mid-run) · `run end --run <id>` |
-| `block` | `code-forge block open <id> --run <r> [--level L<n>] --owned <paths…> --acceptance <file> [--brief <file>] [--attempt <n>] [--base <sha>] [--lines <n>] [--kind code\|docs\|contract]` · `block attempt\|rebase <id> --run <r>` · `block close <id> --run <r> [--transcript <file>] [--report <file>] [--no-require-reviews]` · `block claim <id> <path> --run <r>` · `block stop <id> --run <r> --reason <text>` · `block waive <id> <finding-id> --run <r> --file <path> --reason <text>` · `block reopen <id> --run <r> --file <path> --reason <text>` (both human-only: you run them in your own terminal, they ask for a yes, and there is no `--yes`) |
+| `block` | `code-forge block open <id> --run <r> [--level L<n>] --owned <paths…> --acceptance <file> [--brief <file>] [--attempt <n>] [--base <sha>] [--lines <n>] [--kind code\|docs\|contract]` · `block attempt\|rebase <id> --run <r>` · `block close <id> --run <r> [--transcript <file>] [--report <file>] [--no-require-reviews]` · `block claim <id> <path> --run <r>` · `block stop <id> --run <r> --reason <text>` · `block waive <id> <finding-id> --run <r> --file <path> --reason <text> [--yes]` · `block reopen <id> --run <r> --file <path> --reason <text> [--yes]` (without `--yes` you run them in your own terminal and they ask for a yes; with `--yes` the reason must cite evidence, a fresh judge must agree, and the row is `by: agent`) · `block accept-hit <id> --run <r> --rule <rule-id> --line <n> --transcript <path> --reason <text>` · `block unwaive <id> <finding-id> --run <r> --file <path> --reason <text>` · `block ack-waivers <id> --run <r>` (these three are human-only) |
 | `worker` | `code-forge worker --run <id> [--cwd <dir>] [--poll-ms <n>] [--once]` — started detached by `run start`, never by a coder |
 | `review` | `code-forge review [--base <ref>] [--files <path…>] [--acceptance <file> \| --intent "<text>"] [--run <id>] [--max <seconds>] [--json] [--keep-run]` — review only: no coder, no proof, never closes a block |
 | `review-file` | `code-forge review-file <path> --block <id> [--run <id>]` (enqueue) · `review-file --wait <ticket> [--max <seconds>s]` (poll, default 90s; still running at `--max` prints `status: pending, reason: wait_timeout`) |

package/docs/reference/blocks.json

@@ -4,7 +4,7 @@
     "plans/code-forge-plan-v1.3.md §10.4",
     "plans/NIGHT-LOG.md"
   ],
-  "block_count": 117,
+  "block_count": 133,
   "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": {
@@ -1982,6 +1982,359 @@
         "B104"
       ],
       "note": "owner 2026-10-13: pass the proof rule to every project built with code-forge; 1 round, 3 minors not-bug; removed dead proofRequirements (mutants: held)"
+    },
+    "B116": {
+      "title": "Test cleanup skips unset paths under --test-name-pattern (built with code-forge run)",
+      "wave": 14,
+      "level": "L1",
+      "status": "landed",
+      "owned": [
+        "test/config/cli-models.test.mjs",
+        "test/config/load.test.mjs",
+        "test/config/refresh.test.mjs",
+        "test/engines/isolation.test.mjs",
+        "test/ledger/outcome.test.mjs",
+        "test/skill/shim.test.mjs"
+      ],
+      "depends_on": [
+        "B117"
+      ],
+      "note": "dogfood: brief run, review.file_loop watch, worktree isolation; ~8 min wall; 0 findings"
+    },
+    "B118": {
+      "title": "Context pack without a context key; block open refuses whitespace paths that name no file; close warns without green gates",
+      "wave": 14,
+      "level": "L1",
+      "status": "landed",
+      "owned": [
+        "docs/brief-mode.md",
+        "skill/references/code.md",
+        "src/cli/block.mjs",
+        "src/cli/context.mjs",
+        "src/context/pack.mjs",
+        "test/cli/block-close-gates.test.mjs",
+        "test/cli/block-open-owned.test.mjs",
+        "test/context/pack.test.mjs",
+        "test/proof/worktree-flow.test.mjs"
+      ],
+      "depends_on": [
+        "B116"
+      ],
+      "note": "dogfood findings from B116, built with code-forge run; 0 review findings; the orchestrator updated the B62b malformed-record test for the new close warning"
+    },
+    "B119": {
+      "title": "Transcript grep reads Codex JSON logs by commands only; close names each rule break once",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "docs/brief-mode.md",
+        "skill/references/code.md",
+        "src/review/gate-check.mjs",
+        "src/util/forbidden.mjs",
+        "test/cli/block-close-rule-break.test.mjs",
+        "test/review/external.test.mjs",
+        "test/util/transcript-codex.test.mjs"
+      ],
+      "depends_on": [
+        "B118"
+      ],
+      "note": "dogfood finding from B118, built with code-forge run; 1 review warning answered; named mutation (unknown item types fail closed) caught"
+    },
+    "B120": {
+      "title": "Plain gates runs with --run --block write their gate rows",
+      "wave": 14,
+      "level": "L1",
+      "status": "landed",
+      "owned": [
+        "src/proof/lock.mjs",
+        "test/cli/block-close-gates.test.mjs"
+      ],
+      "depends_on": [
+        "B119"
+      ],
+      "note": "dogfood finding from B119, built with code-forge run; 0 review findings; first dogfood close with no warning"
+    },
+    "B101": {
+      "title": "Opt-in fair share across blocks in the worker pool (review.fair_share)",
+      "wave": 14,
+      "level": "L1",
+      "status": "landed",
+      "owned": [
+        "docs/how-it-works.md",
+        "docs/reference/config.md",
+        "schema/code-forge.schema.json",
+        "skill/references/review.md",
+        "src/worker/loop.mjs",
+        "test/config/schema-coverage.test.mjs",
+        "test/worker/fair-share.test.mjs"
+      ],
+      "depends_on": [
+        "B120"
+      ],
+      "note": "E4a; built with code-forge run; 0 review findings; the orchestrator re-pinned the schema path count (212 -> 213)"
+    },
+    "B105": {
+      "title": "Cross-process locks for ticket claims, files, blocks and the budget row (E4b part 1)",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "docs/how-it-works.md",
+        "skill/references/review.md",
+        "src/autopilot/actions.mjs",
+        "src/doctor/index.mjs",
+        "src/doctor/local.mjs",
+        "src/ledger/spend.mjs",
+        "src/review/schema-fallback.mjs",
+        "src/util/file-locks.mjs",
+        "src/worker/engine.mjs",
+        "src/worker/loop.mjs",
+        "test/util/file-locks.test.mjs",
+        "test/worker/claim.test.mjs"
+      ],
+      "depends_on": [
+        "B101"
+      ],
+      "note": "attempt 1 refused at close (coder transcript read ~/.code-forge/runs); re-run clean; two stopped reviews reopened by the owner and approved"
+    },
+    "B121": {
+      "title": "Watch holds rechecks until the block join",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "docs/how-it-works.md",
+        "docs/reference/config.md",
+        "schema/code-forge.schema.json",
+        "skill/references/code.md",
+        "skill/references/review.md",
+        "src/worker/watch.mjs",
+        "test/worker/watch.test.mjs"
+      ],
+      "depends_on": [
+        "B105"
+      ],
+      "note": "Watch mode queues a file's first commit at once; later commits of a file that already has a ticket are held (watch.held row) until review-file --wait-block queues one ticket for the latest content. Stops a half-done fix commit from using the file's review rounds."
+    },
+    "B106": {
+      "title": "Worker registry: one announcement per worker",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "docs/how-it-works.md",
+        "skill/references/code.md",
+        "src/cli/review.mjs",
+        "src/doctor/local.mjs",
+        "src/doctor/worker-probe.mjs",
+        "src/worker/loop.mjs",
+        "src/worker/queue.mjs",
+        "test/worker/registry.test.mjs"
+      ],
+      "depends_on": [
+        "B105"
+      ],
+      "note": "Each worker writes <repo>/.code-forge/workers/<pid>-<start_time>.json next to worker.json and beats both; boot counts live entries and announces under one cross-process lock (limit 1); boot prunes dead entries (known start-time mismatch = dead); an unreadable entry blocks boot and doctor lists it; liveWorker keeps the B30 fresh-heartbeat rule."
+    },
+    "B122": {
+      "title": "Join delivers unseen findings before a recheck",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "docs/how-it-works.md",
+        "skill/references/code.md",
+        "skill/references/review.md",
+        "src/cli/review-file.mjs",
+        "src/worker/queue.mjs",
+        "test/worker/wait-block.test.mjs"
+      ],
+      "depends_on": [
+        "B121"
+      ],
+      "note": "At review-file --wait-block, a file whose newest review found problems and that changed after it (a commit made blind to the findings) is not rechecked: the join answers status findings with that ticket and writes one delivered marker. The next join rechecks the latest content once. Stops a blind commit from counting as a stall round."
+    },
+    "B123": {
+      "title": "Reopen clears old cap ids after a fresh review",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "docs/how-it-works.md",
+        "skill/references/review.md",
+        "src/review/gate-check.mjs",
+        "test/review/gate-check-reopen-cap.test.mjs"
+      ],
+      "depends_on": [
+        "B122"
+      ],
+      "note": "A review.cap row is superseded when a verified human review.reopened row comes after it and then a signed review.round of the file's current content. A superseded cap row adds no ids to the close check, so after a reopen only the fresh review's own findings need a fix, waiver or answer."
+    },
+    "B126": {
+      "title": "Leak test ignores files already in the repo's .code-forge",
+      "wave": 14,
+      "level": "L1",
+      "status": "landed",
+      "owned": [
+        "test/worker/orphan.test.mjs"
+      ],
+      "depends_on": [
+        "B113"
+      ],
+      "note": "The final-check test in orphan.test.mjs forged an empty baseline, so files already in the repo's .code-forge folder (normal when code-forge builds itself) showed up as leaks and failed npm test. The test now records the folder's current contents as the baseline and still checks the exact planted leak list."
+    },
+    "B125": {
+      "title": "The join reruns a stale review of the current content once",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "docs/how-it-works.md",
+        "skill/references/review.md",
+        "src/cli/review-file.mjs",
+        "src/worker/queue.mjs",
+        "test/worker/wait-block.test.mjs"
+      ],
+      "depends_on": [
+        "B122"
+      ],
+      "note": "review-file --wait-block: when the ticket of a file's current content is done with a result that never counted (stale, unavailable, round-1 split_required), the join drops that done marker with the --fresh claim and the worker reviews the content once; at most one drop per ticket, kept on disk. Counted results are never dropped."
+    },
+    "B124a": {
+      "title": "block waive --yes: an evidence-backed agent waiver a fresh judge must agree with",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "docs/concepts.md",
+        "docs/how-it-works.md",
+        "skill/references/adapters/claude-code.md",
+        "skill/references/adapters/solo.md",
+        "skill/references/code.md",
+        "skill/references/ledger.md",
+        "skill/references/proof.md",
+        "skill/references/review.md",
+        "skill/references/security.md",
+        "src/cli/block.mjs",
+        "src/review/agent-waiver.mjs",
+        "src/review/gate-check.mjs",
+        "test/cli/block-human-confirm.test.mjs",
+        "test/cli/block-waive-yes.test.mjs",
+        "test/skill/structure.test.mjs"
+      ],
+      "depends_on": [
+        "B80",
+        "B62a",
+        "B90",
+        "B122",
+        "B93",
+        "B47"
+      ],
+      "note": "block waive --yes skips the terminal confirm only for a finding whose signed recorded severity is warning or nit; the reason must cite evidence (path:line, a test file, or an acceptance clause); a fresh L3 judge must agree; then one signed review.waived row by: agent with the verdict. Critical or unknown severity is refused waive-yes-critical; no evidence waive-yes-no-evidence (judge not called); disagree waive-yes-disagreed. The gate counts an agreed agent waiver; block close lists agent waivers and --json adds agent_waivers. block reopen stays human-only with no --yes."
+    },
+    "B127": {
+      "title": "block accept-hit: the human accepts one named false transcript hit",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "docs/how-it-works.md",
+        "skill/references/review.md",
+        "skill/references/security.md",
+        "src/cli/block.mjs",
+        "src/review/accept-hit.mjs",
+        "src/review/gate-check.mjs",
+        "src/util/forbidden.mjs",
+        "test/cli/block-accept-hit.test.mjs",
+        "test/engines/builders/argv-snapshots.test.mjs",
+        "test/engines/builders/forbidden-rendering.test.mjs",
+        "test/engines/codex-home.test.mjs",
+        "test/util/forbidden.test.mjs"
+      ],
+      "depends_on": [
+        "B124a",
+        "B80",
+        "B5"
+      ],
+      "note": "block accept-hit <id> --run --rule --line --transcript --reason: human-only (terminal yes, no --yes); pre-checks refuse accept-hit-no-such-hit before any prompt when the transcript scan does not report that (rule, line); on yes one signed rule_break.accepted row {block, rule, line, line_sha256, reason, by: human}. block close drops a transcript hit only when a verified accepted row of the same run and block has the same rule and the sha256 of that exact line text; a rule_break ledger row is never accepted. close prints each accepted hit; --json adds accepted_hits. The verb is coder-only forbidden."
+    },
+    "B124b": {
+      "title": "undo and audit agent waivers: block unwaive, report agent_waivers, require_ack + block ack-waivers",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "docs/concepts.md",
+        "docs/how-it-works.md",
+        "docs/reference/config.md",
+        "docs/tutorial-first-test.md",
+        "schema/code-forge.schema.json",
+        "skill/references/ledger.md",
+        "skill/references/review.md",
+        "skill/references/security.md",
+        "src/cli/block.mjs",
+        "src/cli/report.mjs",
+        "src/ledger/export.mjs",
+        "src/ledger/report.mjs",
+        "src/review/agent-waiver.mjs",
+        "src/review/gate-check.mjs",
+        "src/state/config-snapshot.mjs",
+        "src/util/forbidden.mjs",
+        "test/cli/block-ack-waivers.test.mjs",
+        "test/cli/block-unwaive.test.mjs",
+        "test/config/schema-coverage.test.mjs",
+        "test/engines/builders/argv-snapshots.test.mjs",
+        "test/engines/builders/forbidden-rendering.test.mjs",
+        "test/engines/codex-home.test.mjs",
+        "test/first-use.test.mjs",
+        "test/ledger/cli.test.mjs",
+        "test/ledger/export.test.mjs",
+        "test/ledger/report.test.mjs",
+        "test/skill/structure.test.mjs",
+        "test/state/brief-mode.test.mjs",
+        "test/util/forbidden.test.mjs"
+      ],
+      "depends_on": [
+        "B124a",
+        "B127",
+        "B66",
+        "B58"
+      ],
+      "note": "block unwaive <id> <finding> --run --file --reason: human-only; refuses unwaive-no-agent-waiver before any prompt unless a verified by: agent waiver exists; writes a signed review.unwaived row that cancels earlier agent waivers of that (block, file, finding) on the gate and the review-file pre-check. report gets a 15th section agent_waivers {block, file, finding, severity, reason, verdict, unwaived}. review.agent_waivers.require_ack (frozen at run start): close refuses agent-waivers-not-acked until a human block ack-waivers row matches the digest of the counted agent waivers; ack-waivers-none with none. Both verbs are coder-only forbidden."
+    },
+    "B124c": {
+      "title": "agent reopen: block reopen --yes with evidence, fresh judge, one per block and file per run; close audit agent_reopens",
+      "wave": 14,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "docs/concepts.md",
+        "docs/how-it-works.md",
+        "skill/references/adapters/claude-code.md",
+        "skill/references/adapters/solo.md",
+        "skill/references/code.md",
+        "skill/references/ledger.md",
+        "skill/references/review.md",
+        "skill/references/security.md",
+        "src/cli/block.mjs",
+        "src/review/agent-waiver.mjs",
+        "src/review/gate-check.mjs",
+        "src/review/reopen.mjs",
+        "test/cli/block-human-confirm.test.mjs",
+        "test/cli/block-reopen-yes.test.mjs",
+        "test/review/gate-check-reopen-cap.test.mjs",
+        "test/review/reopen.test.mjs",
+        "test/skill/structure.test.mjs"
+      ],
+      "depends_on": [
+        "B124b",
+        "B124a",
+        "B72",
+        "B80",
+        "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."
     }
   }
 }

package/docs/reference/config.md

@@ -136,7 +136,10 @@ Every other key defaults as shown, or is entirely absent from a minimal file. `a
 | `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.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; the worker queues committed owned content, supersedes pending older tickets, and --wait-block joins before the sentinel. |
+| `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 |  | — |  |
+| `review.agent_waivers.require_ack` | boolean |  | `false` | Require a verified human acknowledgement of the current counted agent waiver set before block close. Read only from the run config snapshot. New or removed waivers need a new acknowledgement. |
 | `review.external` | object |  | — |  |
 | `review.external.required` | boolean |  | `false` | B58: true ⇒ block close skips the local per-file review checks (and the --report ticket check), with no terminal and under autopilot, and writes a signed gate.reviews_waived {by: config} row. Unowned changes, proof, no_changes and the transcript grep still refuse. No block may own .code-forge.yml. |
 | `review.external.name` | string |  | — | minLength 1; B58: the outside reviewer, written in the review.external and gate.reviews_waived rows. Required when required is true: run start refuses a missing or blank name. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codedology/code-forge",
-  "version": "0.12.0",
+  "version": "0.14.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

@@ -185,7 +185,16 @@
           }
         },
         "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." },
-        "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; the worker queues committed owned content, supersedes pending older tickets, and --wait-block joins before the sentinel." },
+        "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": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Human acknowledgement of counted agent waivers. Set before run start; run reload refuses to change require_ack.",
+          "properties": {
+            "require_ack": { "type": "boolean", "default": false, "description": "Require a verified human acknowledgement of the current counted agent waiver set before block close. Read only from the run config snapshot. New or removed waivers need a new acknowledgement." }
+          }
+        },
         "external": {
           "type": "object",
           "additionalProperties": false,

package/skill/references/adapters/claude-code.md

@@ -12,7 +12,7 @@ The harness's `Agent` tool runs the coder as a subagent; everything else — the
 
 The tool return is the completion signal; the report must begin with `ACK <sha8>` and end with `===BLOCK <id> COMPLETE===` (+ test summary + `git diff --stat`) or `===BLOCK <id> FAILED: <reason>===`. A report without the sentinel is a failed block, never a partial success.
 
-**Between completion and close come the review rounds.** The subagent ran `forge review-file <path> --block <id> --run <r>` per file and `--wait`ed on each ticket inside its turn, so most rounds happen before the sentinel; when the tool returns, first drain every `pending` ticket with `forge review-file --wait <ticket>` yourself — a pending ticket is a review in flight, not an open finding, and waiting on it costs no round. Then the open `fix_now` findings, the failing tests and the files the coder never submitted go into one fix round. Fix rounds are one per block: wait for every `review-file` ticket of the block and its tests, then send ONE fix message with every failing test and every open finding; a finding that arrives later waits for the next round (`code.md` §4). Dispatch that message as one new `Agent` call at the level the ladder says (`review.md` §5 — the coder is gone with its tool return, so the fix brief carries every failing test, every open finding and the fix history). Its brief says: in that round the coder fixes, runs the block's tests, re-runs `review-file` on every changed file, and prints its `TESTS` line. One block round is one round for each file it touched. Rounds are bounded: four rounds per file, then the L3 rung once, then `stopped: review_cap` for the human. Only when every changed file has a signed `review.approved` row do you run the re-measurement of `code.md` §5 and `forge block close <id> --run <r> --report <file>` (the subagent's final report, saved to a file) — the transcript grep reads `.code-forge/runs/<run>/<block>.log`; pass `--transcript <file>` when the harness saved the subagent's transcript elsewhere. Closing with a file still unreviewed is a human decision: `forge block waive <id> <finding> --run <r> --file <path> --reason "<why>"` per finding, which asks for a yes at a terminal and has no `--yes`, or `forge block close … --no-require-reviews`, which also asks and is refused under an active autopilot grant, all audited as their own rows. `forge block reopen <id> --file <path> --run <r> --reason "<why>"` does not close anything: it sends a fixed stopped file back to review, and it is also human-only and asks the same way. Print the exact command: the orchestrator never answers this prompt; the human types the command in their own terminal. You and the subagent never run it. The prompt checks only that stdin and stdout are terminals; a pseudo-terminal passes it, so it does not prove a human (`security.md` §3).
+**Between completion and close come the review rounds.** The subagent ran `forge review-file <path> --block <id> --run <r>` per file and `--wait`ed on each ticket inside its turn, so most rounds happen before the sentinel; when the tool returns, first drain every `pending` ticket with `forge review-file --wait <ticket>` yourself — a pending ticket is a review in flight, not an open finding, and waiting on it costs no round. Then the open `fix_now` findings, the failing tests and the files the coder never submitted go into one fix round. Fix rounds are one per block: wait for every `review-file` ticket of the block and its tests, then send ONE fix message with every failing test and every open finding; a finding that arrives later waits for the next round (`code.md` §4). Dispatch that message as one new `Agent` call at the level the ladder says (`review.md` §5 — the coder is gone with its tool return, so the fix brief carries every failing test, every open finding and the fix history). Its brief says: in that round the coder fixes, runs the block's tests, re-runs `review-file` on every changed file, and prints its `TESTS` line. One block round is one round for each file it touched. Rounds are bounded: four rounds per file, then the L3 rung once, then `stopped: review_cap` for the human. Only when every changed file has a signed `review.approved` row do you run the re-measurement of `code.md` §5 and `forge block close <id> --run <r> --report <file>` (the subagent's final report, saved to a file) — the transcript grep reads `.code-forge/runs/<run>/<block>.log`; pass `--transcript <file>` when the harness saved the subagent's transcript elsewhere. Closing with a file still unreviewed needs an audited waiver. Use `forge block waive <id> <finding> --run <r> --file <path> --reason "<why>"` per finding. The human can also use `forge block close … --no-require-reviews` at a terminal. That path asks for a yes. An active autopilot grant refuses it. `forge block reopen <id> --file <path> --run <r> --reason "<why>"` does not close anything: it sends a fixed stopped file back to review. Without `--yes` it asks for a yes at a terminal. The orchestrator prints the command for the human paths of `block reopen` and `block waive`. The orchestrator may run `block reopen --yes` with evidence and agreement from a fresh judge, at most once per block and file in a run. The orchestrator may run `block waive --yes` only for a recorded warning or nit finding with evidence and agreement from a fresh judge. A coder never runs either verb. The prompt checks only that stdin and stdout are terminals; a pseudo-terminal passes it, so it does not prove a human (`security.md` §3).
 
 ## §2.1 Plan approval
 

package/skill/references/adapters/solo.md

@@ -22,7 +22,7 @@ Solo adds spawn, watch, timers, scratchpads, locks and `kv` on top of the CLI; i
 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.
 6. Completion = `search_output(pattern="===BLOCK <id> COMPLETE===")`, last occurrence (the `kv` key is the truncation backup). Completion is not closure.
 7. **Review rounds, with the coder still alive.** The coder ran `forge review-file <path> --block <id> --run <r>` per file and `--wait`ed on each ticket; read the ledger (`forge ledger tail --slug <slug>`) for what is still open — a `fix_now` finding, a `pending` ticket, a file never submitted. After the coder's first COMPLETE, wait until every `review-file` ticket of the block is answered and the block's tests ran; then send ONE fix message with every failing test (name and first error line) and every open finding (by file and id). Never one finding or one file at a time. A finding that arrives after that message waits for the next round. In that round the coder fixes, runs the block's tests, re-runs `review-file` on every changed file, and prints its `TESTS` line. The message goes to the **warm coder** by `send_input`, ending in `<<<EOM>>>`; when it is over the input limit (§1), write it to a file and send its path. Round ≥ 2 re-checks only the fix hunks (`review.md` §5), and one block round is one round for each file it touched. **One ladder** (`decisions.md` §5): a stall or exhausted rounds *below L2* climbs one level — close this coder and respawn a fresh one at the higher level with the open findings and the fix history in its brief; **the respawn keeps the per-file round count**, the cap does not reset. L2 is the highest running level: a trigger at L2, or the four-round cap on a file, goes to the **L3 rung once** — a fresh L3 patch session, never this coder and never a coder at L3 — and if findings stay open after the `patch_check` round the file is `stopped: review_cap` for the human. No other path exists.
-8. **Close** only when every changed file has a signed `review.approved` row: the re-measurement of `code.md` §5, then `forge block close <id> --run <r> --report <file>` (the coder's final report) — the transcript grep reads the Solo output. Closing with a file still unreviewed is a human decision, audited: `forge block waive <id> <finding> --run <r> --file <path> --reason "<why>"` per finding, which asks for a yes at a terminal and has no `--yes`, or `forge block close … --no-require-reviews`, which also asks. `forge block reopen <id> --file <path> --run <r> --reason "<why>"` does not close anything: it sends a fixed stopped file back to review, and it is also human-only and asks the same way. Under an active autopilot grant `block waive` and `block reopen` still prompt; only `block close --no-require-reviews` is refused. Autopilot's own waive path, `forge autopilot waive` (`by: autopilot`), needs no terminal. Print the exact command: the orchestrator never answers this prompt; the human types the command in their own terminal. You and the coder never run it. The prompt checks only that stdin and stdout are terminals; a pseudo-terminal passes it, so it does not prove a human (`security.md` §3).
+8. **Close** only when every changed file has a signed `review.approved` row: the re-measurement of `code.md` §5, then `forge block close <id> --run <r> --report <file>` (the coder's final report) — the transcript grep reads the Solo output. Closing with a file still unreviewed needs an audited waiver. Use `forge block waive <id> <finding> --run <r> --file <path> --reason "<why>"` per finding. The human can also use `forge block close … --no-require-reviews` at a terminal. That path asks for a yes. An active autopilot grant refuses it. `forge block reopen <id> --file <path> --run <r> --reason "<why>"` does not close anything: it sends a fixed stopped file back to review. Without `--yes` it asks for a yes at a terminal. Under an active autopilot grant the human paths still prompt. Autopilot's own waive path, `forge autopilot waive` (`by: autopilot`), needs no terminal. The orchestrator prints the command for the human paths of `block reopen` and `block waive`. The orchestrator may run `block reopen --yes` with evidence and agreement from a fresh judge, at most once per block and file in a run. The orchestrator may run `block waive --yes` only for a recorded warning or nit finding with evidence and agreement from a fresh judge. A coder never runs either verb. The prompt checks only that stdin and stdout are terminals; a pseudo-terminal passes it, so it does not prove a human (`security.md` §3).
 9. **Reap after the close**: `close_process` the coder and confirm `lock_status` shows no lease before the next group. Locks: a coder that can call Solo holds `lock_acquire` on its file area while editing; coders that cannot never overlap another block.
 
 ## §4 Latency overlaps (standing)