@codedology/code-forge 0.1.0

package/skill/references/harden.md

@@ -0,0 +1,26 @@
+# Harden — the adversary is an L3 session; the human answers; you relay
+
+## §1 The author loop
+
+`forge author --job harden --brief <brief> --facts <sheet> --draft <plan> [--answers <file>] --out <plan>` runs a fresh L3 closed-book session over the brief, the facts sheet, the current draft and the answers so far. It returns `{draft, questions: [{id, question, options[], why, blocking}], cost}`.
+
+Loop: write the draft to the plan file → print `questions[]` to the human in chat (and to the Solo scratchpad when present) → collect answers into `<answers file>` → re-run with `--draft` and `--answers`. Stop when **no blocking question is left**: `questions[]` is empty, or every remaining item is non-blocking and the human chose to skip it — a skipped question is written into the plan's Q&A as `skipped` with the human's word, never silently dropped. Each round prints its cost. **The human answers; the orchestrator never answers for them.** Under Solo the human may run harden as an interactive L3 session (`harness.solo.interactive_harden`).
+
+## §2 What the L3 session interrogates (so you can judge its questions)
+
+- Correctness and data integrity: idempotency (can it run twice?), rounding and units for money-like values, timezone and date handling, migration reversibility, backfill for existing rows, races between blocks at runtime.
+- Authorization and tenancy: every new surface behind the project's policy pattern; cross-tenant and cross-user leak paths.
+- Performance and safety: N+1s, heavy work queued, retry and backoff, rate limits on new public endpoints.
+- Testing and rollout: happy, failure and weird paths named per block; permission-denial tests; a flag or backout plan where state changes are risky.
+- Decomposition audit: `owned_files` truly disjoint, `depends_on` acyclic, every block independently testable, every clause mapped (`plan.md` §3), forecasts within the split rule.
+- Benchmark: how comparable products solve the core mechanic — concrete adoptable gaps, not "best practices".
+
+## §3 The tranche gate — a plan is spent when its blocks are
+
+Never roll from one tranche into the next without an architect pass. Risk class is not size: a tranche of pure computation says nothing about the next one's migrations, money or historical data. Hard stops: the plan's blocks are delivered; the next work touches **schema, money, auth/tenancy or historical data** when the current one did not; candidates are tagged planned-not-hardened; or several waves shipped mechanism nothing calls (ask *adoption or more mechanism?*).
+
+Before a coder is spawned the architect answers in writing: which block and why; the risk class and what the plan must therefore carry (down-safety, backfill strategy, idempotency, a dry-run path, proof of correctness without touching production); size, shape, owned paths, split rule; and what would make the block unreviewable, prevented up front. The S1 `security_sensitive` answer and the `proof.tiers.high.paths` floors raise the first-attempt level automatically (`decisions.md` §5); the tranche gate is the human judgement on top.
+
+## §4 Exit
+
+`forge plan check <plan>` green (`plan.md` §4) and no blocking question left (skipped non-blocking ones recorded as `skipped` in the Q&A, §1) ⇒ set `status: hardened` in the plan header, append the Q&A and the risks table to the plan, and say: *next: `/code-forge code <plan>`*.

package/skill/references/ledger.md

@@ -0,0 +1,23 @@
+# Ledger — `~/.code-forge/ledger/<slug>.jsonl`, append-only, never committed
+
+## §1 What a row carries
+
+Every row has the run, the block, the event and a timestamp; the ones the block gate relies on carry `mac` (`security.md` §3). Useful fields: `level`, `provider`, `model`, `effort`, `fallback_step` (every spawn), `role ∈ {coder, reviewer, judge, s2, author, facts}`, `trigger` (escalations), `source ∈ {jev, rules, s2, s2-fallback, shadow}` (decisions), `depth_unconstrained` / `depth_chosen` / `degrade_step` and `context_mode ∈ {whole, hunks, minimal, recheck}` (reviews), `round` and `kind ∈ {full, recheck, patch_check, sweep}` (rounds), `isolation ∈ {export, lock}` (proof), `l3_patch`, `l3_fallback`, `overspend`. **Tokens are facts, dollars are estimates**: `tokens_source: reported` when the CLI's JSON carries usage, else `estimated`. File paths in rows are relative to the repository root.
+
+Events you will read most: `run.start`, `run.stop {reason}`, `run.end`, `dispatch`, `gate.red`, `review.plan`, `review.round`, `review.done`, `review.approved`, `review.unavailable {reason}`, `review.late_finding`, `review.waived {by: human}`, `review.budget`, `forecast.cases_exceeded`, `proof`, `outcome`, `block.rebase`, `block.orphan`, `ledger.tamper`, `worker.replaced`, `facts.built`, `tmp.swept`.
+
+## §2 `forge report --slug <slug> [--json] [--export <dir>]`
+
+Terminal output in this version. Sections: cost per completed block (per level and lane, split review / coder / S1+S2 / facts / proof time) · lane distribution · escalations per block with `trigger` · S1 calls per block · S2 rate and overrule rate per question · the review budget table with `missed_after_degrade` per degrade step · review depth and context-mode distribution, findings by category and severity · fix rounds per file, rounds that stalled, files stopped at `review_cap` · `review.unavailable` by reason · proof time per block · forecast vs actual lines and cases with the measured lines-per-case · blocks stopped at L3 · `overspend` and `l3_fallback` counts · runs stopped for `no_engine`. `--export <dir>` writes one JSON file per section — the durable dataset a future UI reads.
+
+## §3 Live views
+
+`forge ledger tail --slug <slug> [--n <count>]` prints the last rows — the orchestrator's live view when no Solo process list exists. `forge run status --run <id>` prints the run record: active blocks, orphans, whether the worker is pinned.
+
+## §4 Calibration — `forge ledger calibration --slug <slug> [--question <id>]`
+
+Per question id and `source`: reliability buckets × outcome, the count of `≥ 0.99` answers later marked wrong, and a threshold recommendation per question — **never applied automatically**; the human edits `thresholds.<question>`. Ground truth arrives from four callers: shadow sampling (`calibration.shadow_rate`; ships at 0 — the code path exists, turn it on by config once outcome rows flow), the block gate's `outcome` rows (`next = complete` then a red gate ⇒ `wrong`; an escalation after a `lane` pick ⇒ `lane.under`), `forge ledger outcome --slug <slug> --pr <n> --ci red|green|reverted` from the shipped CI template, and `forge ledger outcome --slug <slug> --scan-git [--cwd <dir>] [--days <n>]`, which walks `git log` for reverts (the `This reverts commit <sha>` chain, parity-aware) and marks `reverted` on the matching review rows — run by `run start` and on demand, no CI needed.
+
+## §5 Durability
+
+Rotated at 10 MB; rows are signed only where the gate relies on them; `report --export` snapshots are what anything downstream reads. The ledger is per project slug, so a run from a sub-directory still lands in the same file.

package/skill/references/plan.md

@@ -0,0 +1,43 @@
+# Plan — facts first, then an L3 draft, then a deterministic check
+
+## §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:
+
+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.
+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). There is no pre-execution gate on individual commands beyond those 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: `ls cat head tail wc grep rg stat file uname sw_vers jq which` with in-cwd arguments (`grep` never recursive), `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|--version`, `npm view|ls|--version`, `node --version`, `test -e|-f|-d|-n <one operand>`, `curl` as a HEAD request of exactly one http(s) URL with `-s -S -I -L -f --max-time <N>` only, and `<cli> --help|-h|--version` for a bare CLI name that is not a build runner; 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.
+
+**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.
+
+## §1 The author job
+
+`forge author --job plan --brief <brief> --facts <sheet> --out <plan>` runs a fresh L3 closed-book session (empty cwd, the packet on stdin) and returns `{draft, questions[], cost}`. It refuses without `--facts` (exit 2, `facts sheet required: run forge facts first`) and refuses a sheet older than the brief. The draft follows `templates/plan.md`; its §0 **is** the facts sheet, verbatim, and it must contain the section "Acceptance clauses the facts sheet cannot back" — `none` when empty, never absent.
+
+## §2 Decomposition — what every block carries
+
+| field | rule |
+|---|---|
+| `id`, `title` | one deliverable per block |
+| `owned_files` | exact paths or disjoint globs; a glob never contains `[ ] ( ) ! + @` (an exact path may); pairwise disjoint across blocks that can run together |
+| `depends_on` | acyclic; a block imports only modules of blocks it depends on — a batch-mate's module is a `next = stop` |
+| `level` | the S1 `lane` answer (`L0` trivial · `L1` a plain feature following a pattern · `L2` money, dates, tenancy, migrations, concurrency · `split` too large or two concerns); **L3 is not a lane** |
+| `acceptance` | clauses that each name ≥ 1 test id; a clause citing a flag, path, version or API cites a VERIFIED fact id or sits in the unbackable list with a tolerance naming this block |
+| `cases`, `lines` | forecasts: `cases = 2 × counted clauses`, `lines = 26 × cases` with a floor of 1 200 for a greenfield block and 500 for an amendment; above `budget.block_cases` or `budget.block_lines` the block is split in the plan, never "split-ready" |
+| `test_command` | a quoted glob or an explicit file list, never a bare directory |
+| `commit_message` | house style |
+
+A file everyone needs (a route file, an enum, a registry) is a serialization point: one early block owns it, the others depend on it. Never more than `caps.coders` blocks are marked concurrent in one dispatch slot.
+
+## §3 A mechanism needs a caller (R8)
+
+Every clause of the parent's acceptance maps to exactly one block; an unmapped clause keeps the parent open whatever the sub-blocks report. A block that ships a mechanism is not shipped until a caller block is dispatched or deferred with a named id. The plan carries a **caller map** (mechanism → block that invokes it); `plan check` refuses a block table whose id is missing from it.
+
+## §4 The deterministic exit — `forge plan check <plan> [--facts <sheet>]`
+
+Prints every failing row by name and exits 1 on any of: an acceptance clause with a claim token that resolves to no VERIFIED fact and no tolerance row (`unbackable clause without tolerance: <block> <clause>`); a missing caller map or a block absent from it; a block without `cases` and `lines`; a forecast above `budget.block_cases` / `budget.block_lines` without a named split; overlapping `owned_files` in one wave; a cyclic `depends_on` or an import of a batch-mate; a glob with `[ ] ( ) ! + @`; more than `caps.coders` concurrent blocks in a slot; `questions[]` still open; the facts sheet's sha absent from the draft. Green ⇒ set `status: hardened` after the harden job (`harden.md`), never before.
+
+## §5 Cost
+
+One L0 session per plan for the facts (typically a claim list of 40–80 items) and one L3 session per author round; `forge report --slug <slug>` shows both as `facts $` and coder/review splits.

package/skill/references/proof.md

@@ -0,0 +1,34 @@
+# Proof — two tiers, red→green, the measurement export
+
+## §1 Tiers and what the gate enforces (R16)
+
+Tier per file = `high` when `risk ≥ 2`, or a `proof.tiers.high.paths` match, or `security_sensitive`; else `light`. `forge proof tier --file <path> --risk <0-3> [--security] [--cwd <dir>]` prints it; it is decided at `review-file` time, recorded, and the block gate enforces the union.
+
+| tier | proof required | when |
+|---|---|---|
+| light | red→green recommended for every new or changed test; **optional at the gate** | the coder or orchestrator runs the runner per test (§2) |
+| high | red→green **required at the gate** for every changed high-tier file, plus the deeper **review** depth of `review.md` §2 (two lenses and a judge) | as above; `block close` refuses `unproven <file>` |
+
+**`forge block close` enforces the high tier:** tier inputs are `proof.tiers.high.paths` (the union of the config at the block's base and the current one), the recorded `risk`, and `security_sensitive`; a row naming the file whose MAC fails makes it high. Each changed high-tier file needs a signed `proof` row of this run and block with `step: red-green`, `proven: true`, `red_kind: assertion` whose `covers` list names the file (`revert` covers the sources it put back; `assertion-deletion` covers only its test), else `unproven <file>`; only the human's `forge block waive <id> proof --file <path>` clears it.
+
+**Mutation testing is not part of this product.** The question whether tool-made mutants on changed lines (Infection, Stryker) should be a user-facing proof tier was decided: **cut**. There is no `proof mutate`, no nightly mutation run, no `min_msi` floor, and no mutation-tool key in `.code-forge.yml`; a consumer that runs a mutation tool does so outside code-forge and never beside a coder's test run in the same tree. What replaces it as proof is the rule itself: one exact test per acceptance clause plus one negative or boundary where the clause has a failure mode — assertions that say **which** element and **how many**, never merely whether something exists — and the isolated per-file review with the convergence rule, which on this package's own build found the defects green suites had missed.
+
+`proof.extra` (an argv array) keeps a consumer's legacy proof commands running inside the gate.
+
+## §2 Red→green — journaled, killable, RED must mean an assertion
+
+**One call proves one test** — a test file, or one case of it (`<file>::<case>` is the label) — with one of two mechanisms: `revert` (the block's changed source files are put back to their base version, so the test must fail against the code it was written for) or `assertion-deletion` (a characterization test, proven by deleting its assertions). The runner does not distinguish a new test from a changed one: the caller runs it once per test the acceptance names, new or changed alike, and the count of `RED` rows is the count of proven tests — there is no separate "new cases" tally. In this version the runner is invoked per test from the coder's or the orchestrator's side; the block gate reads the resulting signed `proof` rows but does not launch the runner itself.
+
+The runner works in the export (§3) or under the lock with a journal: it refuses when a journal already exists (an earlier run was interrupted) → journals every source file the test covers (bytes, sha256, mode — or `existed: false`) → writes the **base** version of each (`git show <base>:<path>`, never `stash` or `checkout --`); **a file the block added has no base version, so it is removed for the red run** → runs the filtered tests → **parses** the output: an assertion failure ⇒ `RED`; a fatal, compile or import error ⇒ `RED_INVALID`, which proves nothing (a removed module that the test imports is the usual cause — such a test needs an assertion that fails against the base, not an import that crashes) → restores every journaled file byte for byte, **verifies each sha256**, deletes the journal (in a `finally`, so an ordinary error restores too) → when the red step was `RED`, runs again ⇒ `GREEN`. A characterization test (`proof: characterization`) is proven by assertion deletion. The ledger `proof` row records `mechanism` and `red_kind`; one `RED` + `GREEN` pair per proven test. SIGTERM mid-run leaves the journal; `forge proof restore <block> --run <r>` restores the exact hashes and refuses when no journal exists.
+
+## §3 The measurement export (R13) — `proof.isolation: export`, the default
+
+Parallel blocks share one working tree, so nothing is measured there. `forge proof export <block> --run <r>` builds `.code-forge/export/<block>/`: (a) `git archive <base_sha>` extracted; (b) every path the base's `.gitattributes` marks `export-ignore` restored from `git show` — the hazard is real: repositories mark `/.github` and `CHANGELOG.md` that way; (c) every path in `proof.export.copy_untracked` that exists in the main tree added (`.env`, `.env.testing` by default; never anything under `.code-forge/`); (d) the block's owned files at their **current** content — new files included, and an owned file that existed at the base but is deleted in the tree is **removed from the export** too (listed under `removed` in the export's result), so a deletion is measured as a deletion; (e) the dependency dirs in `proof.export.link_dirs` symlinked read-only. Gates, red→green and the test-count delta run there; `--remove` deletes it at block close. A gate command that fails inside the export with a missing-file error is reported as `export.incomplete: <path>` with the sentence *add it to `proof.export.copy_untracked` or set `proof.isolation: lock`* — never as a red test.
+
+**`proof.isolation: lock`** is the fallback for stacks whose tests cannot run from an export: `forge proof lock <block> --run <r>` takes a run-wide lock (Solo `lock_acquire` when present, else a lock file) that pauses other blocks' gate runs (`proof.busy`); the runner works in the shared tree with the journal; `forge proof unlock <block> --run <r>` releases it. The ledger flags `isolation: lock`.
+
+Test-count delta = the count on the block's filtered run in the export minus the same filter at `base_sha` (a second export, cached per base). The full suite runs only above `gates.full_suite_threshold_files`, also in the export.
+
+## §4 Verified and unverified stacks
+
+The export is proven on the package's own example repository (a Node library with a `node:test` suite, `/.github` and `CHANGELOG.md` restored from `export-ignore`). A PHP/Pest or Vitest stack is **UNVERIFIED** until a real second consumer runs it; `proof.isolation: lock` is the documented fallback for those until then. `doctor` says which gate commands are on PATH.

package/skill/references/review.md

@@ -0,0 +1,42 @@
+# Review — per file, fresh L2 session, bounded rounds
+
+## §1 The trigger is a CLI call, and the file set is complete
+
+`forge review-file <path> --block <id> --run <r>` enqueues a ticket and returns `{ticket, status: queued}` in under a second; `forge review-file --wait <ticket> [--max 90s]` polls it. The worker computes the diff itself against the base sha `forge block open` recorded: tracked changes plus untracked files, filtered by `owned_files` for the review and unfiltered for the scope check. A coder that never calls `review-file` gains nothing: the block gate refuses any changed or new file without a signed `review.approved` row for its final content hash. The reviewer is always a new OS process (R1, R10) — identical under Solo, a harness subagent, a detached CLI process, or a human typing.
+
+## §2 Depth by risk (adaptive mode, `review.multimodel` off)
+
+1. Tools on the file first: lint, types, the file's own tests. Red ⇒ `tools_red` back to the coder, no model review, ledger `gate.red`.
+2. S1 `risk` (path floors first; `confidence < check` ⇒ S2 picks the depth).
+3. Planned depth: `risk < 1` ⇒ one L2 `quick` · `1 ≤ risk < 2` ⇒ one L2 `full` · `risk ≥ 2` ⇒ two blind L2 sessions (lens A correctness, lens B contracts and security) plus an L3 judge that reads the two reports — and the diff only when `review.judge_sees_diff` is true.
+4. Triage: findings from a single L2 session go to S1 `defect` (`thresholds.findings.fix` fix now · mid-band batched to one L3 ruling per file · below `thresholds.findings.nit` a nit). Findings that come from a judge are final.
+
+## §3 Isolation and the packet
+
+Every reviewer, recheck, judge and S2 session runs with cwd = a fresh empty temp dir under the run's temp root and the packet **on stdin** — a no-tools session never opens a path and the packet never enters argv. Packet order is fixed so provider prompt caching applies: lens, project rules digest (≤ 60 lines), facts-sheet excerpt for the symbols in the diff, context, diff. Context: a file at or under `review.context.whole_file_max_lines` travels whole; above it each hunk carries ± `review.context.hunk_context_lines` lines; over `review.budgets.full_in` the context shrinks to ± `review.context.min_context_lines`, then the digest is trimmed, never the diff; a diff alone over budget ⇒ `split_required`. The closed-book rule is in every lens: judge only what is in the packet; a file you cannot see goes in `needs_file`, and the worker attaches it (read-only, trimmed) for **one** more round.
+
+## §4 The stub guard — what counts as a review (R11)
+
+A result is a review only if the process exited 0, the JSON validates against the finding schema, `reviewed_hunks` equals the packet's hunk headers exactly and in order, and the output has at least `review.min_tokens_out` tokens. Anything else is ledger `review.unavailable` (`exit`, `schema`, `hunks_mismatch`, `too_short`, `timeout`) and **is not approval**; the worker retries once on the level's fallback, then the file stays unreviewed and the block cannot close. A session that hangs is killed at `review.session_timeout_s`, process group and all.
+
+## §5 The convergence rule — bounded fix rounds (R15)
+
+Per file, per block:
+
+1. Round 1 is the tiered review of §2 on the full packet.
+2. **Round n ≥ 2 reviews only the fix hunks**: the diff between the content hash reviewed in round n−1 and the current content, ± `review.context.hunk_context_lines`, plus the open findings by id (`review.recheck_scope: fix_hunks`, the default; `file` re-sends the whole packet for a consumer that wants it). The `recheck` lens answers `resolved[]` per finding — S1 `resolved` at or above `thresholds.findings.resolved` closes it, else the fresh L2 recheck decides — and may raise a new finding **only inside a fix hunk**; a finding outside becomes a `late_finding`, ruled at block close (`review.late_findings: sweep`; `block` makes it block the round).
+3. **Strictly shrinking**: the open `fix_now` set after round n is smaller than after round n−1, counting closures minus new in-hunk findings. Equal or larger ⇒ `review_stall` (rule 2b), a trigger at once.
+4. **Ladder**: the running ceiling is `min(L2, escalation.stop_at)` — L3 is never a *running* level. A trigger — rule 1 (`retries`), rule 2 (`escalation.review_rounds_per_level` exhausted with an open `fix_now`) or rule 2b (`review_stall`) — below the ceiling climbs one level, coded by a fresh session with the open findings and the fix history in its brief (an L1 block's rounds 3–4 run at L2). At the ceiling — an L2 block, or an L1 block that has climbed to L2 — it takes the **L3 rung**: a patch ≤ 80 lines, owned files only, reviewed as a `patch_check` round outside the cap. Under `escalation.l3_mode: code` (opt-in) the rung is instead one L3 coding turn. Either way the rung fires **once per block** and the same post-patch order follows it. After it, in order: `patch_check` clean ⇒ complete; open set not smaller than before the patch ⇒ `stopped: l3_patch_exhausted` (`review_stall`); round ≥ `review.max_rounds_per_file` ⇒ `stopped: review_cap`; otherwise the fixes continue at L2 with `rounds_at_level` reset and the patch in the brief. Any later trigger in that block stops with its named reason (`l3_patch_exhausted`, `review_cap`) and never patches again.
+5. **Cap — four rounds per file** (`review.max_rounds_per_file`, default 4, range 2–6). Round 4 still open ⇒ the L3 rung if the block has not used it (same post-patch order as step 4), else `stopped: review_cap`. A stop means the block cannot close, the ledger lists the open findings, and the human decides — fix by hand, `forge block waive <id> <finding-id> --run <r> --file <path> --reason <text>` (a signed `review.waived` row, `by: human`), or re-decompose. The coder never sees a `waive` verb; it is on the forbidden list.
+6. **Block-close sweep**: `forge block close` batches the `late_findings` per file to one L3 judge ruling (`fix_now | nit`); a `fix_now` opens a round on that file at the block's current level and counts toward its cap.
+7. Ledger: one `review.round` row per round with `open_before`, `closed`, `new_in_hunks`, `late`, `open_after`; `forge report` prints rounds per file and rounds that stalled.
+
+Rechecks are never degraded by the budget: a round-2+ packet is already the minimum.
+
+## §6 Consensus mode (`review.multimodel` on)
+
+Two L2 reviewers, one per effective provider (`resolve(L2)` and `review.second_levels`), each a fresh blind session with the `full` lens; then a fresh L3 judge **from the third provider** reads the two reports and returns the findings plus `agreement: both|A-only|B-only`. The judge's `fix_now` list is final. Second provider unavailable at run start ⇒ `consensus unavailable: <reason>`; ask the human once per run whether to continue adaptive, stop when non-interactive. Rechecks run on the provider that raised the finding; §5 applies unchanged.
+
+## §7 The review budget per block
+
+`review.block_budget_tokens` (and optionally `review.block_budget_usd`) bounds every review, recheck, judge and S2 session made for the block. When the forecast exceeds it the worker degrades one step at a time, cheapest first: batch small files of one tier into one packet (`review.batch_small_files`) → one judge per block instead of per file → standard band `full` → `quick` → high tier `A + B + judge` → one `full` L2 + judge, the floor. Tools-only is never a review; a light `quick` stays `quick`. Still over ⇒ `review.over_budget`: raise the budget once per run (a config edit by the human, on record) or split the block — never silently, never below the floors. The ledger keeps `depth_unconstrained` and `depth_chosen` per file so `forge report` can show `missed_after_degrade`.

package/skill/references/rules-core.md

@@ -0,0 +1,72 @@
+# Core rules — sixteen, each with its why
+
+The headings below are the list in `SKILL.md` §4. A rule names levels and roles, never a model. Config keys are the ones `forge validate` accepts.
+
+### R1 — Coder ≠ reviewer, always
+Every `forge review-file` call starts a new L2 session in an empty directory; the session that wrote a file never judges it. Why: a same-session review reads its own intent, not the diff.
+
+### R2 — The orchestrator never codes, reviews or judges
+Plans and patches are L3 sessions (`forge author`, the L3 rung); code is a coder's; verdicts come from the worker's sessions. Why: the orchestrator's context is the scarce resource, and a hand-written "surgical fix" is unreviewed code.
+
+### R3 — State lives outside the conversation
+The run record, the ledger, the plan file, then Solo scratchpad/kv when present. Why: a session dies mid-run; anything only in its context is lost (`continuity.md` §1).
+
+### R4 — The evidence gate is a re-measurement
+A coder's report is a claim sheet; `forge block close` recomputes every row itself (`code.md` §5). Why: green assertions pass for wrong reasons; a quoted number is not a number.
+
+### R5 — No destructive git, no production, no regex edits
+The forbidden list (`security.md` §2) is rendered into every spawn and grepped from every transcript; code is restructured by hand; a check's output is read, never discarded. Why: each entry names a real incident.
+
+### R6 — The budget stop is the feature
+A coder that forecasts, overruns and stops did the right thing; the cap moves once per run, by the human, on record (`code.md` §6). Why: a rule that never fires protects nothing.
+
+### R7 — Wire truncation is detectable
+The wire carries a pointer ≤ 200 B ending in `<<<EOM>>>`; the coder echoes `ACK <sha8> lines=<n>` before any tool call; no ACK ⇒ resend once, then park. Why: an input channel truncated a message to its last 240 bytes, silently.
+
+### R8 — A mechanism needs a caller
+Every acceptance clause of a parent maps to exactly one block; a block that ships a mechanism names the block that calls it or is not shipped (`plan.md` §3). Why: sub-blocks marked done while the parent's acceptance was unmet.
+
+### R9 — Own-family adjudication is visible and asymmetric
+When the orchestrator shares a family with the coder it may accept a finding alone but never dismiss, defer or waive one; every such call is a named ledger row (`decisions.md` §5). Why: a judgement inside the family is not independent.
+
+### R10 — A fresh isolated session per job
+Reviewer, recheck, judge, S2, author and facts each run as a new print-mode process with an empty cwd and the packet on stdin, whatever the engine. Why: isolation is what makes the harness irrelevant.
+
+### R11 — A review without matching `reviewed_hunks` is not a review
+Exit 0, a valid schema, `reviewed_hunks` equal to the packet's hunk headers in order, and enough output; anything else is `review.unavailable`, never approval. Why: three reviewers returned stubs on a green gate that hid a money bug.
+
+### R12 — The L3 rung writes a patch, never a feature
+On escalation past L2 an L3 session returns a diff ≤ 80 lines inside the owned files, reviewed as a `patch_check` round; the block then continues at L2. Why: bulk coding at L3 is the cost sink the ladder exists to avoid.
+
+### R13 — Measurement runs in an export or behind the proof lock
+Gates, test-count deltas and red→green run in `.code-forge/export/<block>/`, never in the shared tree while other blocks are active (`proof.md` §3). Why: parallel blocks in one tree cannot be measured apart.
+
+### R14 — No design before facts
+`forge author --job plan` refuses without `--facts`; every clause that cites a flag, path, version or API cites a VERIFIED fact or sits in the unbackable list with a tolerance (`plan.md` §0). Why: a plan built a reviewer on a flag that did not exist.
+
+### R15 — Re-checks shrink: fix hunks only, four rounds, then a patch, then a human
+Round n ≥ 2 reviews the fix hunks and the open findings; the open set shrinks every round or the coder climbs; `review.max_rounds_per_file` rounds, then the L3 rung once, then `stopped: review_cap` (`review.md` §5). Why: whole-file re-checks added new defects every round.
+
+### R16 — Proof is exact assertions on the main behaviour
+One exact test per clause plus a negative or boundary where the clause has a failure mode; red→green for every new test; there is no mutation tier (`proof.md` §1). Why: exhaustive suites hid the defects the isolated review found.
+
+## What survives from the previous pipeline (14 rows)
+
+| survivor | lands in | kind |
+|---|---|---|
+| Coder ≠ reviewer session | `rules-core.md` R1; `review.md` §1 | core rule + mechanism |
+| State outside the conversation | `rules-core.md` R3; `continuity.md` §1 | core rule |
+| Launch verification + completion sentinels | `adapters/solo.md` §3; `adapters/subprocess.md` §2 | mechanism |
+| Evidence gate = re-measurement | `rules-core.md` R4; `code.md` §5 | core rule + mechanism |
+| Wire truncation detection | `rules-core.md` R7; `adapters/solo.md` §2 | core rule + mechanism |
+| Facts sheet before dispatch + coder facts diff | `plan.md` §0; `code.md` §1 | core rule |
+| Risk-class gate between tranches | `harden.md` §3 | core rule |
+| Budget caps; the stop is the feature | `rules-core.md` R6; `code.md` §6 | config + core rule |
+| Mechanism needs a caller | `rules-core.md` R8; `plan.md` §3 | core rule |
+| Draft PR only after independent review | `code.md` §7 | config + core rule |
+| Continuity / takeover | `continuity.md` §2 | core rule |
+| Base-moves rules | `continuity.md` §3 | core rule |
+| Definition of Done | `code.md` §8 | core rule |
+| Own-family adjudication visible and asymmetric | `rules-core.md` R9; `decisions.md` §5 | core rule |
+
+Working habits folded into the rules above rather than listed: verification chains use `;` not `&&` and arrays for word-splitting; resolve a target before any destructive state command; spawned agents inherit the production ban; test every fix red→green; commit trailers follow `commit.trailers`; one PR ready at a time (`wip.ready_prs`); never close a process this run did not spawn; long input goes to a file plus a pointer; simplest solution first; no duplicate logic; read the source before reviewing it.

package/skill/references/security.md

@@ -0,0 +1,29 @@
+# Security — keys, the forbidden list, signed rows and where their guarantee ends
+
+## §1 Keys never reach a coder
+
+`keys.<name>` in `.code-forge.yml` holds a reference only (`user`, `op://…`, `env:NAME`, `keychain:<name>`), never a value. Resolution runs the chain — environment → OS keychain → 1Password `op read` (cached 8 h) → ask at setup — and runs **only inside the worker or the orchestrator's own CLI calls, never in a coder process**. `forge keys list | set <name> [--op <ref>] | test <name> [--ref <ref>] | remove <name>`; `list` never prints a value. Every output path is redacted: a message names the key path, never the value. Coder sessions receive neither the S1 key nor the signer key in their environment (subprocess env allow-list; Solo agent env likewise); reviewer sessions keep only the provider login variables they need to authenticate.
+
+## §2 The forbidden list — one list, rendered per CLI at spawn, grepped from every transcript
+
+`gh pr ready|merge|close` and base retargets · `git push --force*` · `git reset --hard` · `git checkout --` · `git restore` · `git clean` · `git stash` · `git branch -D` · `git rm` · `rm -rf` outside `.code-forge/` · any argv containing a `production.markers` token or a `production.names` name · any read or write of `~/.code-forge/runs/` · `forge worker`, `run start` and `block waive` from a coder (also via `npx`) · any write under `.code-forge/reviews/` or `.code-forge/queue/*.done`.
+
+Rendered into every coder spawn as the CLI's own deny rules (path rules widen a directory to `<dir>/**`; a read-write path denies read, edit and write); carried verbatim in the brief; refused by the package's own process spawner; and at block close the transcript (captured stdout, the harness log, or the Solo output) is grepped for the forbidden verbs **and paths** — a hit is a `rule_break` row that fails the gate. Where a CLI cannot load a rules file, `doctor` says so and the transcript grep remains the detector.
+
+## §3 Signed ledger rows — the threat model, stated honestly
+
+**Mechanism.** A per-run HMAC key (32 random bytes) lives in `~/.code-forge/runs/<run>.key`, mode 0600, outside the workspace; `forge run start` generates it, the worker and `forge block close` read it, and it is never placed in a coder's environment or workspace. Gate-relevant rows carry `mac`; a verification failure is a `ledger.tamper` row and the block is `stopped`. Key rotation = a new run.
+
+**What it defends against.** A coder that never called `review-file` and appends or edits rows or result files with its ordinary tools — no valid MAC, refused. A coder that edits a review result after the worker wrote it — the MAC no longer matches. A stale approval reused after the file changed — rows are keyed by content hash. A coder that starts its own worker to sign rows — the pinned pid and start time in the run record no longer match, `worker.replaced`, block stopped. A coder that waives its own finding — `block waive` is forbidden and the row requires `by: human` signed by the worker's key.
+
+**What it does not defend against, and the product does not claim.** A coder running as the same OS user with a shell can read the key file and mint a MAC, or edit the run record. Within one OS user there is no boundary that a determined bypass-permissions process cannot cross; the deny rules make it a deliberate, named rule break rather than an accident, and the transcript grep makes the attempt visible (`rule_break: key_path`). `doctor` prints `signer: same-user boundary only` on every full run so nobody reads "signed" as "unforgeable".
+
+**The real boundary is the consumer's choice:** run coders as a second OS user, or in a container that cannot reach `~/.code-forge/runs/` (a Codex `workspace-write` sandbox already blocks writes there; reads remain open). An in-memory key over a socket was considered and rejected: a same-user process can still replace the worker or edit the pin.
+
+## §4 Isolation of closed-book sessions
+
+Reviewer, recheck, judge, S2, author and facts sessions run in print mode with the provider's own isolation flags, cwd = an empty temp dir under the run's temp root, and the packet on stdin; `doctor` proves that no project document is visible (it asks the reviewer builder to echo the first line of the project's rules file and expects nothing) and that the coder builder cannot read a known file outside the workspace (`claude: path deny rules not honoured` when it can). The facts delegate gets read-only shell tools with every write verb denied.
+
+## §5 What the package itself never does
+
+No telemetry (`telemetry: off`, reserved). No `postinstall`. No secret in argv — a keychain write goes through stdin. Temp dirs live under one per-run root and are swept by the next `run start`; the reaper kills only processes this package registered whose start time still matches — never a foreign pid. Every child `git` runs with inherited `GIT_*` variables stripped, so a gate invoked from a hook still sees the right repository.

package/skill/scripts/forge

@@ -0,0 +1,40 @@
+#!/bin/sh
+# code-forge skill shim: `forge <verb> [args…]` runs the package's `bin/code-forge.mjs`.
+#
+# Resolution order (first hit wins):
+#   1. $CODE_FORGE_BIN, when set and a file (a checkout or a pinned version);
+#   2. <this skill dir>/../../bin/code-forge.mjs — the skill lives inside the package, and a
+#      symlinked install (`code-forge init`, the default) resolves back into it;
+#   3. `code-forge` on PATH (a global npm install);
+#   4. `npx @codedology/code-forge@<version>` pinned to the version this skill was built with (a
+#      copied install with no package next to it); `test/skill/shim.test.mjs` asserts the pin
+#      equals package.json's version.
+# The shim holds no logic of its own: every verb, flag and message is the CLI's.
+PINNED_VERSION="0.1.0"
+set -eu
+
+self="$0"
+while [ -L "$self" ]; do
+  link=$(readlink "$self")
+  case "$link" in
+    /*) self="$link" ;;
+    *) self="$(dirname "$self")/$link" ;;
+  esac
+done
+here=$(cd "$(dirname "$self")" && pwd -P)
+packaged="$here/../../bin/code-forge.mjs"
+
+if [ -n "${CODE_FORGE_BIN:-}" ] && [ -f "$CODE_FORGE_BIN" ]; then
+  exec node "$CODE_FORGE_BIN" "$@"
+fi
+if [ -f "$packaged" ]; then
+  exec node "$packaged" "$@"
+fi
+if on_path=$(command -v code-forge 2>/dev/null); then
+  exec "$on_path" "$@"
+fi
+if npx_path=$(command -v npx 2>/dev/null); then
+  exec "$npx_path" --yes "@codedology/code-forge@$PINNED_VERSION" "$@"
+fi
+echo "forge: no code-forge found. Install it: npm install -g @codedology/code-forge@$PINNED_VERSION (or set CODE_FORGE_BIN=<path>/bin/code-forge.mjs)" >&2
+exit 127

package/skill/templates/block-record.md

@@ -0,0 +1,19 @@
+### Block record — `<id>` `<title>`
+
+| field | value |
+|---|---|
+| run / block | `<run id>` / `<id>` |
+| level, attempt | `L<n>`, attempt `<n>` (escalations: `<trigger>` → `L<n+1>` …) |
+| base sha | `<sha>` (rebased: `<old>` → `<new>` on `<date>`) |
+| owned files | `<paths…>` |
+| brief pointer | `BRIEF <path> lines=<n> sha=<sha8>` · ACK received `<yes/no>` |
+| facts diff | `<n>` contradictions: `<one line each — plan said X, code says Y, ruling>` |
+| forecast | cases `<n>` · lines `<n>` · orchestrator's floor: test lines ≥ `<cases × rate>`, docblocks ≥ 10 % |
+| actual | cases `<n>` (runner count) · lines `<n>` (`git diff --stat`) · miss attributed to `<architect-added scope | coder under-forecast | none>` |
+| review rounds | per file: `<path>` `<n>` rounds (`<stalled | converged | review_cap>`) |
+| late findings | `<n>` ruled at close: `<fix_now | nit>` |
+| dispositions / waivers | `<finding id → successor block>` (architect) · `review.waived` via `forge block waive <id> <finding> --run <r> --file <path> --reason "<why>"` (human) |
+| spawn-flag defects | `<n>` — a coder parked at a permission or model prompt: closed and respawned with the pinned flags (`adapters/solo.md` §3) |
+| gate | `<complete | stopped: <reason>>` at `<iso-8601>` |
+| commit | `<sha>` · draft PR `<url or none>` |
+| cost | coder `<$>` · review `<$>` · S1+S2 `<$>` · tokens `<reported | estimated>` |

package/skill/templates/facts-sheet.md

@@ -0,0 +1,22 @@
+# Facts sheet — `<slug>`
+
+<!-- rendered by `forge facts`; edit nothing below the header by hand -->
+
+| field | value |
+|---|---|
+| brief | `<path>` |
+| brief sha | `<sha256>` |
+| brief mtime | `<iso-8601>` |
+| built at | `<iso-8601>` |
+| delegate | L0, read-only tools, empty cwd |
+| claims | `<n>` — VERIFIED `<v>` · NOT-FOUND `<nf>` · UNVERIFIABLE `<u>` |
+
+## Claims
+
+| fact id | claim | kind | command | output excerpt | tag |
+|---|---|---|---|---|---|
+| F1 | `<claim token as written in the brief>` | flag \| command \| path \| version \| endpoint \| package \| env | `<the read-only command that was run>` | `<≤ 200 characters of its output>` | VERIFIED |
+| F2 | … | … | … | `<why it could not be checked>` | UNVERIFIABLE |
+| F3 | … | … | … | `<the empty or negative output>` | NOT-FOUND |
+
+Rules the sheet was refused against: every `command` is read-only (checked against the forbidden list and a write-verb list); a VERIFIED tag has a non-empty excerpt; a tag is never inferred. An acceptance clause in the plan cites a fact by id (`F<n>`); a clause whose claim is NOT-FOUND or UNVERIFIABLE must appear in the plan's "Acceptance clauses the facts sheet cannot back" list with a tolerance naming a block, or `forge plan check` refuses it.

package/skill/templates/plan.md

@@ -0,0 +1,53 @@
+# `<feature>` — plan
+
+| field | value |
+|---|---|
+| status | facts \| planned \| hardened \| coding \| done |
+| brief | `<path>` (sha `<sha8>`) |
+| facts sheet | `<path>` (sha `<sha8>`, built `<iso-8601>`) |
+| authored at | L3 via `forge author --job plan`; hardened via `forge author --job harden` (`<n>` rounds) |
+| run | `<run id>` once `forge run start` has run |
+
+## §0 Facts sheet (verbatim)
+
+<!-- the whole facts sheet, unchanged; `forge plan check` looks for its sha here -->
+
+### §0.x Acceptance clauses the facts sheet cannot back
+
+`none` — or one row per clause:
+
+| block | clause | claim | tag | tolerance (how the block's acceptance survives it) |
+|---|---|---|---|---|
+
+## §1 Architecture decision
+
+Chosen approach and why · rejected alternatives (one line each) · the project conventions that apply · risk class of this tranche (`harden.md` §3).
+
+## §2 Blocks
+
+| id | title | level | depends_on | owned_files | cases | lines | acceptance (clauses, each naming its test ids and fact ids) | test_command | commit_message |
+|---|---|---|---|---|---|---|---|---|---|
+| B1 | … | L1 | — | `src/x.mjs`, `test/x.test.mjs` | 12 | 1 200 | (1) … (`test/x.test.mjs`, F3) · (2) … | `node --test 'test/x/**/*.test.mjs'` | … |
+
+Split rule: `cases = 2 × clauses`, `lines = 26 × cases` (floor 1 200 greenfield, 500 amendment); above `budget.block_cases` or `budget.block_lines` the block is split here. A glob in `owned_files` never contains `[ ] ( ) ! + @`.
+
+## §3 Caller map
+
+| mechanism | shipped by | called by |
+|---|---|---|
+
+Every block id above appears in this map; a mechanism with no caller names the block that will call it or is not shipped (`plan.md` §3).
+
+## §4 Dispatch order
+
+Slots = `caps.coders`. A block starts when a slot frees and every block in its `depends_on` has been committed: `1. B1 ∥ 2. B2 → 3. B3 (when B1 lands) → …`.
+
+## §5 Hardening Q&A
+
+<!-- appended by the harden job: question · options · the human's answer · what changed in §2 -->
+
+## §6 Risks and mitigations
+
+## §7 Block records
+
+<!-- one `templates/block-record.md` per dispatched block, appended by the code job -->

package/src/cli/author.mjs

@@ -0,0 +1,87 @@
+/**
+ * `code-forge author --job plan|harden --brief <file> [--facts <file>] [--draft <file>]
+ *   [--answers <file>] [--out <file>] [--run <id>] [--timeout <s>]` (plan §3.7, §3.8 rule 2;
+ * block B9b). One author round: writes the draft to `--out` (default
+ * `<project.plans_dir | plans>/<brief name>.<job>.md`) and prints `{draft, questions, cost}` as one
+ * JSON line (`draft` is the path). The orchestrator shows the questions to the human and calls the
+ * verb again with `--draft` and `--answers`.
+ * Exit codes: 0 answered, 1 failed or invalid answer, 2 usage / no facts sheet / stale sheet,
+ * 3 L3 and every fallback unavailable.
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { loadProjectConfig } from '../config/load.mjs';
+import { AuthorError, runAuthor } from '../session/author.mjs';
+import { runRootFor, SessionError } from '../session/spawn.mjs';
+import { intFlag, parseFlags } from '../state/cli-args.mjs';
+import { StateError } from '../state/paths.mjs';
+import { writeSafe } from '../util/redact.mjs';
+import { slugFor } from './run.mjs';
+import { exitCodeFor } from './spawn.mjs';
+
+const USAGE = 'usage: code-forge author --job plan|harden --brief <file> [--facts <file>] [--draft <file>] [--answers <file>] [--out <file>] [--run <id>] [--timeout <seconds>]\n';
+
+/**
+ * @param {string[]} args
+ * @param {import('../session/spawn.mjs').SessionDeps & {stdout?: {write: (s: string) => unknown}, cwd?: string}} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runAuthorVerb(args, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const cwd = deps.cwd ?? process.cwd();
+  try {
+    const { flags, positionals } = parseFlags(args, { values: ['job', 'brief', 'facts', 'draft', 'answers', 'out', 'run', 'timeout'] });
+    if (positionals.length > 0 || typeof flags.job !== 'string' || typeof flags.brief !== 'string') {
+      writeSafe(stderr, USAGE);
+      return 2;
+    }
+    /** @param {string | string[] | true | undefined} v */
+    const abs = (v) => (typeof v === 'string' ? path.resolve(cwd, v) : undefined);
+    const briefPath = /** @type {string} */ (abs(flags.brief));
+    const loaded = await loadProjectConfig(cwd);
+    if (!loaded.ok) {
+      writeSafe(stderr, `author: ${loaded.message}\n`);
+      return 2;
+    }
+    const cfg = /** @type {Record<string, any>} */ (loaded.config);
+    const timeout = intFlag(flags.timeout, 'timeout');
+    const run = typeof flags.run === 'string' ? flags.run : undefined;
+    const result = await runAuthor(
+      {
+        cfg,
+        job: flags.job,
+        briefPath,
+        factsPath: abs(flags.facts),
+        draftPath: abs(flags.draft),
+        answersPath: abs(flags.answers),
+        run,
+        runRoot: run ? runRootFor(run, cfg?.tmp?.root) : undefined,
+        slug: slugFor(cfg, cwd),
+        timeoutMs: timeout === undefined ? undefined : timeout * 1000,
+      },
+      { ...deps, stderr },
+    );
+    if (result.status !== 'ok') {
+      writeSafe(stderr, `author: ${result.status}${result.reason ? ` (${result.reason})` : ''}\n`);
+      return exitCodeFor(result);
+    }
+    const out = abs(flags.out) ?? path.join(path.resolve(cwd, cfg.project?.plans_dir ?? 'plans'), `${path.basename(briefPath, path.extname(briefPath))}.${flags.job}.md`);
+    mkdirSync(path.dirname(out), { recursive: true });
+    writeFileSync(out, /** @type {string} */ (result.draft));
+    writeSafe(stdout, `${JSON.stringify({ draft: out, questions: result.questions, cost: result.cost })}\n`);
+    return 0;
+  } catch (err) {
+    if (err instanceof AuthorError || err instanceof StateError || err instanceof SessionError) {
+      writeSafe(stderr, `author: ${/** @type {Error} */ (err).message}\n`);
+      return 2;
+    }
+    throw err;
+  }
+}
+
+/** @param {string[]} args */
+export default async function authorVerb(args) {
+  return runAuthorVerb(args);
+}