@codedology/code-forge 0.15.1 → 0.15.3

package/schema/pipeline.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://code-forge.dev/schema/pipeline.schema.json",
+  "title": "Specialist skill pipeline",
+  "type": "object",
+  "properties": {
+    "root": { "type": "string" },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+          "skill": { "type": "string" },
+          "needs": { "type": "array", "items": { "type": "string" }, "default": [] },
+          "outcome": {
+            "type": "string",
+            "pattern": "^(?![\\\\/])(?![A-Za-z]:)(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)).+$"
+          },
+          "approval": { "enum": ["human", "none"] }
+        },
+        "required": ["id", "skill", "outcome", "approval"],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": ["root", "steps"],
+  "additionalProperties": false
+}

package/scripts/first-use.mjs

@@ -50,7 +50,9 @@ import { fileURLToPath } from 'node:url';
 import { parse as parseYAML, parseDocument } from 'yaml';
 import { readAllRows } from '../src/ledger/write.mjs';
 import { estimateCostUsd } from '../src/ledger/prices.mjs';
+import { readRun } from '../src/state/run.mjs';
 import { exec } from '../src/util/exec.mjs';
+import { stopMembers } from '../src/util/reaper.mjs';
 import { runRoot, setRunRoot, tmpBase } from '../src/util/tmp.mjs';
 
 const PKG = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -435,6 +437,12 @@ export async function main(argv, io = {}) {
       const ended = await exec([process.execPath, BIN, 'run', 'end', '--run', run], { cwd: copy, env: scrubbedEnv(), timeoutMs: 60000 });
       say(`run end · exit ${ended.code} · ${ended.stdout.trimEnd() || ended.stderr.trimEnd()}`);
       summary.run_ended = ended.code === 0;
+      if (summary.run_ended) {
+        // `run end` sends SIGTERM; delivery is not exit. Wait for the pinned worker's
+        // cleanup before this script reports completion, rechecking identity before signals.
+        const record = await readRun(run);
+        await stopMembers(new Map((record.workers ?? (record.worker ? [record.worker] : [])).map((worker) => [worker.pid, worker.started_at])));
+      }
     }
     process.off('SIGINT', onSignal);
     process.off('SIGTERM', onSignal);

package/scripts/gen-config-doc.mjs

@@ -64,7 +64,7 @@ function notesLabel(nodeIn, defs) {
   if (node.exclusiveMinimum !== undefined) parts.push(`> ${node.exclusiveMinimum}`);
   if (node.minLength !== undefined) parts.push(`minLength ${node.minLength}`);
   if (node.minItems !== undefined) parts.push(`minItems ${node.minItems}`);
-  if (typeof node.description === 'string' && node.type !== 'object') parts.push(node.description);
+  if (typeof node.description === 'string') parts.push(node.description);
   return parts.join('; ');
 }
 

package/skill/references/code.md

@@ -2,6 +2,8 @@
 
 Small changes may use `block open <id> --kind light`. Close allows at most `light.max_files` owned changed files (default 5) and `light.max_lines` added plus removed lines (default 300), including new files. Auto ticket lines are unchanged. `gates run --block` runs the block's tests through `{test_files}`, ignoring the full-suite threshold; supply block tests and a test command containing that item. A close refusal `light-limits <files> files, <lines> lines` means the block outgrew this kind: the orchestrator stops the open attempt, then opens the same id with `block open <id> --kind code --attempt <n+1>` and the original base, ownership and acceptance.
 
+For website checks, configure `gates.custom` with up to 20 unique named `{name, argv, env?, evidence?}` gates, such as build, lighthouse and links. They run independently after the four fixed gates, including on light blocks and with `--changed`; custom argv refuses `{test_files}` and `{changed_files}`. The `gates-not-argv-array` error rule validates entries. Evidence paths/globs stay under cwd; after pass or fail, up to 200 sorted regular files are recorded as path, bytes and SHA-256 without copying content. Missing patterns are listed without failing the gate. `gate.done` carries custom summaries and, with `--run/--block`, the evidence map; red custom gates carry their name and `custom: true`.
+
 ## §1 The coder's first deliverable is a facts diff
 
 Before any forecast or code, the coder reads the code it will call and reports **every contradiction between the plan and the code** in one message — a signature, a flag, a key, a version. One stop for facts, never one per discovery. Contract corrections (a key, a rule, a signature) are the architect's alone and are recorded, not asked; a ruling reaches the human only when it changes user-visible behaviour, money semantics or an approved decision. A coder that stops three times for three true facts did nothing wrong; the protocol did.
@@ -14,6 +16,19 @@ The coder then forecasts **cases** (tests) and **lines**. Compute the floor your
 
 Acceptance (`block open --acceptance`) is a YAML/JSON list. Code clauses need `tests: [<test ids>]`. A device check instead uses `- clause: "Check the layout on a phone"` with `kind: human_check` on the next indented line and no `tests` key (even an empty list is refused). These texts are recorded as the block's `human_checks` and skipped by test-coverage checks; every other clause still needs tests.
 
+For design first, put `{clause: "Owner approves the design", kind: human_check}` in `design.acc.yml`, then follow this order:
+
+```sh
+code-forge block open DESIGN --run <r> --level L1 --kind docs --owned docs/design.md --acceptance design.acc.yml --brief <file> --lines <n>
+# Finish the design and pass its code gates, then:
+code-forge block close DESIGN --run <r>
+# The owner approves the design in their terminal:
+code-forge block human-pass DESIGN --run <r> --note "Design approved"
+code-forge block open CODE --run <r> --level L2 --owned src/feature.mjs --acceptance code.acc.yml --after DESIGN --brief <file> --lines <n>
+```
+
+`--after <id> [<id> ...]` collects ids like `--owned` and removes duplicates. Every dependency must be `closed` in this run, checked under the same run lock as the other open checks. Open refuses with `after-not-done`, naming every blocker and its status (`open`, `awaiting_human_check`, `stopped`, or `not in run`); no rows or worktree are created. With `--json`, the refusal also prints `{block, event: "refused", code: "after-not-done", message}` (self-dependency uses `bad-after`). Only a supplied flag adds `after: [ids]` to the entry and `dispatch` row. Supply it again on each later attempt that must wait for the design; an attempt without it does not recheck dependencies.
+
 Run a Codex coder with `codex exec --json` in its worktree, save stdout to a log, and pass that
 log to `block close --transcript <file>`. A Codex JSON log (every non-empty line is an object
 with a string `type`, first event `thread.started`) is checked by its commands: command items'

package/skill/references/ledger.md

@@ -10,7 +10,19 @@ Events you will read most: `run.start`, `run.mode {mode: brief, plan: none}` (a
 
 `review.unwaived {block, file, finding, reason, by: human}` is a signed human undo of earlier agent waivers. `agent_waivers.acked {block, digest, count, by: human}` is a signed human acknowledgement of the current counted set. The gate verifies both rows. The digest is SHA-256 of the sorted file, finding and row signature set. New or removed waivers need a new acknowledgement when the run snapshot requires one.
 
-Terminal output in this version. Sections: cost per block — completed and still open, with `completed` and the count of unknown-price sessions (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 (one block round is one round for each file it touched, `review.md` §5), 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` · `outside_review` (14th): per PR sorted by number, `{pr, rounds, findings, link, blocks, code_forge_usd, unknown_usd_sessions}` — `code_forge_usd` sums the `cost_per_block` totals of the PR's blocks in its run, rounded as `cost_per_block` rounds; unknown-price sessions count 0 and are counted; a PR with no blocks shows 0 and 0 unknown; `[]` with no row; in the terminal the lines print under `== outside_review ==`: `outside review: none`, or one line per PR (`PR #12 · 3 outside rounds · 7 findings · code-forge $3.75 (+1 unknown) · B1, B2`). `agent_waivers` is the 15th and last section. It lists every agent waiver as `{block, file, finding, severity, reason, verdict, unwaived}`. A later human unwaive marks earlier matching rows as `unwaived: true`. A later agent waiver is a separate entry. An empty run gives `[]`. `--export <dir>` writes one JSON file per section — the durable dataset a future UI reads. After the sections the terminal output prints the spend per run (open blocks included) and the total. `report` checks no row's signature in any section (an unsigned row counts like a signed one); shadow rows (`source: shadow`) are excluded from every section.
+Terminal output in this version. Sections: cost per block — completed and still open, with `completed` and the count of unknown-price sessions (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 (one block round is one round for each file it touched, `review.md` §5), 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` · `outside_review` (14th): per PR sorted by number, `{pr, rounds, findings, link, blocks, code_forge_usd, unknown_usd_sessions}` — `code_forge_usd` sums the `cost_per_block` totals of the PR's blocks in its run, rounded as `cost_per_block` rounds; unknown-price sessions count 0 and are counted; a PR with no blocks shows 0 and 0 unknown; `[]` with no row; in the terminal the lines print under `== outside_review ==`: `outside review: none`, or one line per PR (`PR #12 · 3 outside rounds · 7 findings · code-forge $3.75 (+1 unknown) · B1, B2`). `agent_waivers` is the 15th section. It lists every agent waiver as `{block, file, finding, severity, reason, verdict, unwaived}`. A later human unwaive marks earlier matching rows as `unwaived: true`. A later agent waiver is a separate entry. An empty run gives `[]`. `run_time` is appended as the 16th section (shape below). `--export <dir>` writes one JSON file per section — the durable dataset a future UI reads. After the sections the terminal output prints the spend per run (open blocks included) and the total. `report` checks no row's signature in any section (an unsigned row counts like a signed one); shadow rows (`source: shadow`) are excluded from every section.
+
+Each `cost_per_block` entry also carries `wallMs` and `humanWaitMs` in milliseconds. `wallMs` spans the first valid `dispatch.ts` through the final completion: `block.close` without a pending human check, or `block.human_pass` after `block.awaiting_human_check`. An entry whose last lifecycle row is `block.stop` has `stopped: true` and `wallMs` through the stop timestamp, with `humanWaitMs: null`; `stopped` is omitted otherwise. Stopped blocks are listed even without spend or a close. Attempts share the first dispatch; redispatching clears `stopped` and makes the block open again until its final completion, whose wall time still starts at the first dispatch. `humanWaitMs` spans the final check's `block.awaiting_human_check.ts` through `block.human_pass.ts`. Both fields are null while the block is open or awaiting a human check; `humanWaitMs` is also null with no human check. Missing or invalid endpoints give null, as do reversed endpoints. Existing grouping by run and block still applies.
+
+In text output, a `cost_per_block` entry with no run uses `outside runs` in the run column, and spend with no run prints as `  outside runs: $<usd> · <n> session(s)` (with the same unknown-price suffix) after the real runs and before the spend total; `--json` and `--export` keep `run: null` unchanged.
+
+`run_time` has the shape `{runs: [...], outside_runs?: {usd, rows}, total: {...}}` in `--json` and `run_time.json` from `--export`:
+
+- `runs` lists only runs with a string run id, in first-seen ledger order. Each entry is `{run, started, ended, wallMs, usd, blocks_closed, blocks_stopped}`, with `open: true` added only when there is no valid `run.end` timestamp. `started` is the first valid `run.start.ts`, falling back to the run's first valid row timestamp, or null. `ended` is the final valid `run.end.ts`, or null. These timestamp strings preserve the row's ISO representation. `wallMs` is elapsed milliseconds to `ended`, or to the last valid row timestamp for an open run; it is null when endpoints are unavailable or reversed. `usd` reuses the existing per-run spend total, including open blocks and counting unknown-price sessions as 0. `blocks_closed` counts distinct completed blocks (pending human checks do not count); `blocks_stopped` counts distinct blocks with a `block.stop` row, even across attempts.
+- `outside_runs` counts rows without a string run id as `{usd, rows}`: their spend from the same spend helpers and their row count. They contribute no run or wall time. The key is omitted when there are no such rows, including an empty ledger.
+- `total` is `{runs, wallMs, usd, blocks_closed}`: the number of listed real runs, the sum of their known durations (null contributes 0), the existing whole-ledger spend total **including `outside_runs.usd`**, and the sum of their completed-block counts. With no rows it is `{runs: 0, wallMs: 0, usd: 0, blocks_closed: 0}` and the list is `[]`. One slug is one repo/site, so this is the site's cost and cumulative run time.
+
+Only full ISO timestamps with a timezone are used for timing; missing or invalid `ts` values are ignored without dropping the row's spend or lifecycle information. Shadow rows never affect times, counts or spend. The terminal shows block dollars beside readable times (for example `12m 30s`) and a status of `completed`, `stopped` or `open`, retains the cost breakdown and proof time, and prints a short run table with its total line; `-` means unavailable time. When `outside_runs` exists, `outside runs: $<usd> (<rows> rows, no wall time)` prints immediately before the total, with no `(none)` run in the table.
 
 ## §3 Live views
 

package/skill/scripts/forge

@@ -10,7 +10,7 @@
 #      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.15.1"
+PINNED_VERSION="0.15.3"
 set -eu
 
 self="$0"

package/src/cli/block.mjs

@@ -4,7 +4,7 @@
  *
  *   block open <id> --run <r> [--level L<n>] --owned <paths…> --acceptance <file>
  *              [--brief <file>] [--attempt <n>] [--base <sha>] [--lines <forecast>] [--kind code|docs|contract|light]
- *              [--tests <paths…>]
+ *              [--tests <paths…>] [--after <ids…>] [--after-outcome <ids…>]
  *   block attempt <id> --run <r>
  *   block rebase <id> --run <r> [--head <ref>]
  *   block claim <id> <path> --run <r>
@@ -20,8 +20,9 @@
  * close (`closed`): status, reason, close_event (the close result's own event word, as the text
  * prints it in parentheses, else null), and `worktree {removed, path, branch}` with
  * `--remove-worktree`). On
- * failure the exit code and stderr are unchanged and stdout stays empty, except a close the gate
- * refused (`closeBlock` said no), which also prints `{"block", "ok": false, "reason"}`. A usage
+ * failure the exit code and stderr are unchanged and stdout stays empty, except an open refused
+ * for `after-not-done`, `bad-after`, `outcome-not-ready` or `bad-after-outcome`, which prints `{"block", "event": "refused", "code", "message"}`,
+ * or a close the gate refused (`closeBlock` said no), which also prints `{"block", "ok": false, "reason"}`. A usage
  * error, a thrown refusal, a cancelled `--no-require-reviews`, `block waive` or `block reopen` (or
  * one with no terminal, B80) and a failed `--remove-worktree`
  * print nothing on stdout. Without `--json` every output is byte-identical to before.
@@ -194,7 +195,8 @@
  * through `closeBlock`'s `extraChecks`.
  */
 
-import { existsSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { readFile, realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { parse as parseYAML } from 'yaml';
@@ -202,6 +204,8 @@ import { approvalCheckText, expiryChecks } from '../autopilot/limits.mjs';
 import { fallbackLane } from '../decide/fallback-rules.mjs';
 import { laneFacts } from '../decide/lane-facts.mjs';
 import { appendRow, readAllRows } from '../ledger/write.mjs';
+import { checkOutcome } from '../outcome/outcome.mjs';
+import { loadPipeline } from '../pipeline/pipeline.mjs';
 import { amendAcceptanceBlock, attemptBlock, claimPath, closeBlock, humanPassBlock, openBlock, prepareAcceptanceAmendment, rebaseBlock, repoTop, stopBlock } from '../state/block.mjs';
 import { intFlag, parseFlags } from '../state/cli-args.mjs';
 import { configInForce, externalReviewer, requireCoderTests } from '../state/config-snapshot.mjs';
@@ -209,17 +213,17 @@ import { readFileDiff } from '../review/packet.mjs';
 import { StateError } from '../state/paths.mjs';
 import { readRun, writeSigned } from '../state/run.mjs';
 import { loadKey, verifyRow } from '../state/signer.mjs';
-import { PROOF_FINDING, blockFileSet, changedFiles, checkBlockReviews, openFindings, ownsAt, recordedSeverity, resultFilesFor, reviewedFiles, reviewGateCheck, routineCloseProblem, unownedChanges, waiveFinding } from '../review/gate-check.mjs';
+import { PROOF_FINDING, blockFileSet, changedFiles, checkBlockReviews, lockfileProblem, openFindings, ownsAt, recordedSeverity, resultFilesFor, reviewedFiles, reviewGateCheck, routineCloseProblem, unownedChanges, waiveFinding } from '../review/gate-check.mjs';
 import { agentWaivers, agentWaiversAcked, prepareAckWaivers, prepareUnwaive, waiveAsAgent } from '../review/agent-waiver.mjs';
 import { checkExpiry, grantFor, grantState } from '../autopilot/grant.mjs';
 import { redact, writeSafe } from '../util/redact.mjs';
 import { blockTree, prepareWorktree, removeWorktree, worktreeSettings } from '../proof/worktree.mjs';
 import { DEFAULT_CONFIG_FILENAME, loadProjectConfig } from '../config/load.mjs';
-import { validateConfig } from '../config/validate.mjs';
+import { reviewExcludeRule, validateConfig } from '../config/validate.mjs';
 import { migrateConfig } from '../config/migrate.mjs';
 import { exec } from '../util/exec.mjs';
 import { contentHash, gitChildEnv, readRegularFileNoFollow } from '../worker/ticket.mjs';
-import { clearDone, resetAcceptanceWatch, resolveTicket } from '../worker/queue.mjs';
+import { clearDone, enqueue, resetAcceptanceWatch, resolveTicket } from '../worker/queue.mjs';
 import { loadState } from '../worker/review-state.mjs';
 import { agentReopens, openBlockEntry, reopenFile } from '../review/reopen.mjs';
 import { checkFileForm, checkFindingId } from '../review/verb-forms.mjs';
@@ -236,7 +240,7 @@ import { acceptedTranscriptHits, prepareAcceptHit, writeAcceptedHit } from '../r
  * main tree), its state is read (never moved) from the code-forge home or the run's old temp root,
  * the checks, the done marker's removal and then the signed row are `reopenFile`'s.
  * @param {{runId: string, id: string, file: string, reason: string, record: Record<string, any>, writeRow: (row: Record<string, any>) => Promise<unknown>, agent?: boolean, judge?: import('../review/agent-waiver.mjs').WaiverJudge}} opts
- * @returns {Promise<{row: Record<string, any>, cleared: boolean}>}
+ * @returns {Promise<{row: Record<string, any>, cleared: boolean, ticket?: string}>}
  */
 async function reopenBlockFile({ runId, id, file, reason, record, writeRow, agent = false, judge }) {
   if (agent) {
@@ -268,7 +272,7 @@ async function reopenBlockFile({ runId, id, file, reason, record, writeRow, agen
   const key = await loadKey(runId);
   const rows = await readAllRows(record.project);
   const tree = contentRoot === mainTop ? {} : { tree: contentRoot };
-  const { row, cleared } = await reopenFile({
+  const { row, cleared, ticket } = await reopenFile({
     runId,
     id,
     file,
@@ -286,13 +290,14 @@ async function reopenBlockFile({ runId, id, file, reason, record, writeRow, agen
       readFile: (f) => readRegularFileNoFollow(contentRoot, f),
       // C11 (synchronous): the cached result of the current content's ticket would repeat the stop
       clearDone: (f) => clearDone({ repoRoot: mainTop, run: runId, block: id, file: f, ...tree }).removed,
+      enqueue: (f, reopened) => enqueue({ repoRoot: mainTop, run: runId, block: id, file: f, ...tree, after: reopened.ts }).ticket,
     },
   });
-  return { row, cleared };
+  return { row, cleared, ticket };
 }
 
 const USAGE =
-  'usage: 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|light] [--tests <paths…>]\n' +
+  'usage: 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|light] [--tests <paths…>] [--after <ids…>] [--after-outcome <ids…>]\n' +
   '       code-forge block attempt|rebase <id> --run <r> · block close <id> --run <r> [--transcript <file>] [--report <file>] [--no-require-reviews] [--remove-worktree] · block claim <id> <path> --run <r> · block stop <id> --run <r> --reason <text>\n' +
   '       code-forge block waive <id> <finding-id> --run <r> --file <path> --reason <text> [--yes]\n' +
   '       code-forge block reopen <id> --run <r> --file <path> --reason <text> [--yes]\n' +
@@ -303,7 +308,34 @@ const USAGE =
   '       code-forge block amend-acceptance <id> --run <r> --acceptance <file> --reason <text>\n' +
   '       every block verb takes --json: one JSON line on stdout ({"block","event",…}) instead of the text\n';
 
-const SUBCOMMANDS = ['open', 'attempt', 'rebase', 'claim', 'close', 'stop', 'waive', 'reopen', 'accept-hit', 'unwaive', 'ack-waivers', 'human-pass', 'amend-acceptance'];
+/** @type {Record<string, string>} */
+const VERB_USAGE = {
+  open: '<id> --run <r> [--level L<n>] --owned <paths…> --acceptance <file> [--brief <file>] [--attempt <n>] [--base <sha>] [--lines <n>] [--kind code|docs|contract|light] [--tests <paths…>] [--after <ids…>] [--after-outcome <ids…>]',
+  attempt: '<id> --run <r>',
+  rebase: '<id> --run <r> [--head <ref>] [--accept-changed <file>… --reason <text>]',
+  claim: '<id> <path> --run <r>',
+  close: '<id> --run <r> [--worker-pid <pid>] [--transcript <file>] [--report <file>] [--no-require-reviews] [--remove-worktree] [--decide]',
+  stop: '<id> --run <r> --reason <text>',
+  waive: '<id> <finding-id> --run <r> --file <path> --reason <text> [--yes]',
+  reopen: '<id> --run <r> --file <path> --reason <text> [--yes]',
+  'accept-hit': '<id> --run <r> [--rule <rule-id>] --line <n> --transcript <path> --reason <text>',
+  unwaive: '<id> <finding-id> --run <r> --file <path> --reason <text>',
+  'ack-waivers': '<id> --run <r>',
+  'human-pass': '<id> --run <r> --note <text> [--proof <dir-or-file>]',
+  'amend-acceptance': '<id> --run <r> --acceptance <file> --reason <text>',
+};
+const SUBCOMMANDS = Object.keys(VERB_USAGE);
+
+/** @param {string} sub @returns {string} */
+function verbUsage(sub) {
+  return `usage: code-forge block ${sub} ${VERB_USAGE[sub]} [--json] [--help|-h]\n` +
+    '  --help, -h  Print this usage and exit without changing state.\n' +
+    '  --json      Print one JSON line on success instead of text.\n' +
+    (sub === 'open' || sub === 'amend-acceptance'
+      ? '  --acceptance <file>  JSON/YAML list [{clause, tests}]; tests is a nonempty list of test ids.\n' +
+        '                       Human checks use {clause, kind: human_check} without tests.\n' : '') +
+    (sub === 'open' ? '  --brief <file>       A file inside the repository, not inline text.\n' : '');
+}
 
 /** Refuse likely shell quoting slips before any row is written.
  * @param {string} workspace @param {string[]} entries @param {string} label
@@ -331,6 +363,32 @@ function checkWhitespacePaths(workspace, entries, label) {
 }
 const FLAG_VALUES = ['run', 'level', 'acceptance', 'brief', 'attempt', 'base', 'lines', 'head', 'worker-pid', 'reason', 'file', 'transcript', 'kind', 'report', 'rule', 'line', 'note', 'proof'];
 
+/** Check specialist outcomes against the run's project, before state open can write anything.
+ * @param {string} root @param {string} id @param {string[]} ids
+ * @returns {{step: string, sha256: string}[]}
+ */
+function acceptedOutcomes(root, id, ids) {
+  const loaded = loadPipeline(root);
+  const bad = (/** @type {string} */ problem) => new StateError('bad-after-outcome', `block ${id}: --after-outcome: ${problem}`);
+  if (!loaded.exists) throw bad(`no code-forge.pipeline.yml in ${root}`);
+  if (!loaded.ok) throw bad(loaded.problems[0]);
+  const steps = [...new Set(ids)].map((stepId) => {
+    const step = loaded.pipeline.steps.find((candidate) => candidate.id === stepId);
+    if (!step) throw bad(`unknown step ${stepId}`);
+    return step;
+  });
+  return steps.map((step) => {
+    const file = path.resolve(root, step.outcome);
+    const result = existsSync(file) ? checkOutcome(file, { root }) : { ok: false, problems: ['missing outcome'] };
+    if (!result.ok) throw new StateError('outcome-not-ready', `block ${id}: --after-outcome step ${step.id}: ${result.problems[0]}`);
+    try {
+      return { step: step.id, sha256: createHash('sha256').update(readFileSync(file)).digest('hex') };
+    } catch (err) {
+      throw new StateError('outcome-not-ready', `block ${id}: --after-outcome step ${step.id}: cannot read outcome (${err.code ?? 'error'})`);
+    }
+  });
+}
+
 /**
  * @param {string[]} args
  * @param {{
@@ -359,8 +417,13 @@ export async function runBlock(args, deps = {}) {
     err(USAGE);
     return 2;
   }
+  if (rest.includes('--help') || rest.includes('-h')) {
+    out(verbUsage(sub));
+    return 0;
+  }
+  let jsonOpenId;
   try {
-    const { flags, positionals } = parseFlags(rest, { values: FLAG_VALUES, multi: ['owned', 'tests'], booleans: ['no-require-reviews', 'remove-worktree', 'json', ...(sub === 'close' ? ['decide'] : []), ...(['waive', 'reopen'].includes(sub) ? ['yes'] : [])] });
+    const { flags, positionals } = parseFlags(rest, { values: FLAG_VALUES, multi: ['owned', 'tests', ...(sub === 'rebase' ? ['accept-changed'] : []), ...(sub === 'open' ? ['after', 'after-outcome'] : [])], booleans: ['no-require-reviews', 'remove-worktree', 'json', ...(sub === 'close' ? ['decide'] : []), ...(['waive', 'reopen'].includes(sub) ? ['yes'] : [])] });
     // B64a: --json prints ONE JSON line on success instead of the text lines (`emit`, one object
     // per verb, built where the text is); without it every output is exactly as before (`say` is `out`)
     const json = flags.json === true;
@@ -375,6 +438,7 @@ export async function runBlock(args, deps = {}) {
       if (t.startsWith('-')) throw new StateError('usage', `--tests: a path may not start with "-": ${JSON.stringify(t)}`);
     }
     const [id, extra] = positionals;
+    if (sub === 'open' && json) jsonOpenId = id;
     const runId = typeof flags.run === 'string' ? flags.run : undefined;
     if (!id || !runId) throw new StateError('usage', 'a block id and --run are required');
     if (sub === 'amend-acceptance' && (positionals.length !== 1 || typeof flags.acceptance !== 'string' || typeof flags.reason !== 'string' || !flags.reason.trim() || /\p{Cc}/u.test(flags.reason))) {
@@ -481,10 +545,11 @@ export async function runBlock(args, deps = {}) {
     const writeRow =(/** @type {Record<string, any>} */ row) => appendRow(row, { slug: record.project });
     const reopened = async (/** @type {boolean} */ agent) => {
       const file = /** @type {string} */ (flags.file);
-      const { row, cleared } = await reopenBlockFile({ runId, id, file, reason: /** @type {string} */ (flags.reason), record, writeRow, agent, judge: deps.waiverJudge });
+      const { row, cleared, ticket } = await reopenBlockFile({ runId, id, file, reason: /** @type {string} */ (flags.reason), record, writeRow, agent, judge: deps.waiverJudge });
       const fromText = row.stop_reason == null ? row.from : `${row.from} ${row.stop_reason}`;
       say(`block ${id} reopened ${file} (from ${fromText}; by: ${row.by})\n`);
-      if (json) emit({ block: id, event: 'reopened', file, from: row.from, stop_reason: row.stop_reason, at_seq: row.at_seq, from_hash: row.from_hash, to_hash: row.to_hash, ticket_cleared: cleared, by: row.by });
+      if (ticket) say(`ticket ${ticket}\nnext: code-forge review-file --wait ${ticket}\n`);
+      if (json) emit({ block: id, event: 'reopened', file, from: row.from, stop_reason: row.stop_reason, at_seq: row.at_seq, from_hash: row.from_hash, to_hash: row.to_hash, ticket_cleared: cleared, by: row.by, ticket });
       return 0;
     };
     // Agent refusals precede even the lazy expiry checks: no rows on refusal.
@@ -542,13 +607,18 @@ export async function runBlock(args, deps = {}) {
     // B48: every block command runs the lazy autopilot checks (grant expiry, expired approvals);
     // a failed check is a warning, never a reason to stop the block command
     const requireHumanClose = sub === 'close' && configInForce(record)?.close?.require_human === true;
-    try {
-      if (!deciding && !requireHumanClose) {
-        err(approvalCheckText(await expiryChecks(runId, (deps.now ?? (() => new Date()))(), { writeRow })));
+    const expire = async () => {
+      try {
+        if (!deciding && !requireHumanClose) {
+          err(approvalCheckText(await expiryChecks(runId, (deps.now ?? (() => new Date()))(), { writeRow })));
+        }
+      } catch (thrown) {
+        err(`autopilot: WARN the expiry check failed (${thrown?.message ?? String(thrown)})\n`);
       }
-    } catch (thrown) {
-      err(`autopilot: WARN the expiry check failed (${thrown?.message ?? String(thrown)})\n`);
-    }
+    };
+    // B148: a refused dependency must not leave even an expiry row behind.
+    const deferExpiry = sub === 'open' && (Array.isArray(flags.after) || Array.isArray(flags['after-outcome']));
+    if (!deferExpiry) await expire();
 
     if (sub === 'open') {
       // an explicit --level wins; B59: else in a brief-mode run the rules lane; B47: else the level
@@ -581,6 +651,20 @@ export async function runBlock(args, deps = {}) {
       }
       // B62a: the run's isolation, from its config snapshot (fixed for the run)
       const isolated = worktreeSettings(record);
+      // Preserve --after's self-before-unfinished order before examining specialist outcomes.
+      // State open still checks these dependencies under the run lock.
+      let afterOutcome;
+      if (Array.isArray(flags['after-outcome'])) {
+        if (Array.isArray(flags.after)) {
+          if (flags.after.includes(id)) throw new StateError('bad-after', `block ${id} cannot name itself in --after`);
+          const blocking = [...new Set(flags.after)].filter((dependency) => record.blocks[dependency]?.status !== 'closed');
+          if (blocking.length > 0) {
+            const statuses = blocking.map((dependency) => `${dependency} (${record.blocks[dependency]?.status ?? 'not in run'})`);
+            throw new StateError('after-not-done', `block ${id}: --after dependencies not closed: ${statuses.join(', ')}`);
+          }
+        }
+        afterOutcome = acceptedOutcomes(record.workspace, id, flags['after-outcome']);
+      }
       const { block, pointer, worktreeReused } = await openBlock({
         runId,
         id,
@@ -594,10 +678,13 @@ export async function runBlock(args, deps = {}) {
         ...(rules ? { decision: { question: 'lane', answer: rules.lane, source: 'rules', facts: rules.facts } } : {}),
         ...(typeof flags.kind === 'string' ? { kind: flags.kind } : {}),
         ...(Array.isArray(flags.tests) ? { tests: flags.tests } : {}),
+        ...(Array.isArray(flags.after) ? { after: flags.after } : {}),
+        ...(afterOutcome ? { after_outcome: afterOutcome } : {}),
         cfg: await openConfig(record.workspace),
         writeRow,
         ...(isolated ? { worktree: (/** @type {{baseSha: string, previous: any}} */ ctx) => prepareWorktree({ cwd: record.workspace, settings: isolated, runId, id, ...ctx }) } : {}),
       });
+      if (deferExpiry) await expire();
       const raised = block.level !== level ? ` (${block.kind} floor, asked ${level})` : '';
       const chosen = typeof flags.level === 'string' ? '' : rules ? ' (rules lane)' : ' (autopilot level)';
       const testCount = Array.isArray(block.test_files) ? block.test_files.length : 0;
@@ -629,7 +716,17 @@ export async function runBlock(args, deps = {}) {
       return 0;
     }
     if (sub === 'rebase') {
-      const moved = await rebaseBlock({ runId, id, head: typeof flags.head === 'string' ? flags.head : undefined, writeRow });
+      const acceptChanged = Array.isArray(flags['accept-changed']) ? [...new Set(flags['accept-changed'])] : [];
+      if (acceptChanged.length) {
+        if (positionals.length !== 1 || typeof flags.reason !== 'string' || !flags.reason.trim() || /\p{Cc}/u.test(flags.reason)) throw new StateError('usage', '--accept-changed needs one block id and a nonblank --reason without control characters');
+        for (const file of acceptChanged) checkFileForm(file, { normalized: true });
+        const asked = await confirmHumanVerb('rebase', runId, id, { file: acceptChanged.join(', ') }, record, deps, async () => {
+          if ((await checkExpiry(runId, (deps.now ?? (() => new Date()))())).state === 'active') throw new StateError('autopilot-active', 'block rebase --accept-changed is refused while an autopilot grant is active');
+        });
+        if (asked === 'no-tty') { err(`${humanVerbNoTTY('rebase')}\n`); return 2; }
+        if (asked === 'cancelled') { err(`block ${id} rebase: cancelled — nothing was recorded\n`); return 1; }
+      }
+      const moved = await rebaseBlock({ runId, id, head: typeof flags.head === 'string' ? flags.head : undefined, writeRow, acceptChanged, reason: typeof flags.reason === 'string' ? flags.reason : undefined });
       say(`block ${id} rebased ${moved.old_base.slice(0, 12)} → ${moved.new_base.slice(0, 12)}\n`);
       if (json) emit({ block: id, event: 'rebased', old_base: moved.old_base, new_base: moved.new_base });
       return 0;
@@ -679,7 +776,7 @@ export async function runBlock(args, deps = {}) {
         throw thrown;
       });
       // ONE base for the whole close: a worktree block is measured against the commit its tree was
-      // made from (kept equal to base_sha, including after a closed worktree rebase)
+      // made from (kept equal to base_sha, including after a worktree rebase)
       const base = wt !== null ? wt.base_sha : entry.base_sha;
       const reviewsWaived = flags['no-require-reviews'] === true;
       let routineGrant = null;
@@ -706,6 +803,7 @@ export async function runBlock(args, deps = {}) {
       // B58: the owner's other way out — `review.external.required` in the run's config snapshot
       // (set before `run start`, immutable): no TTY, allowed under autopilot, the human flag wins
       const external = reviewsWaived ? null : externalReviewer(record);
+      const reviewConfig = configInForce(record);
       const rows = (await readAllRows(record.project)).filter((row) => row.run === runId);
       // B52: ONE path base and ONE listing, memoised as a promise and shared by every check. The
       // base is the repository top level: the worker signs every review row with a repo-root-
@@ -770,6 +868,16 @@ export async function runBlock(args, deps = {}) {
         // B20: the high paths come first — a base the workspace does not know refuses the close here
         const highPaths = await highPathsAt(record.workspace, base);
         const { top, mainTop, where, inTree, wsPrefix, owns, changed, fileSet, reviewed } = await tree();
+        const excluded = fileSet.flatMap((f) => {
+          const rule = reviewExcludeRule(reviewConfig, f.file);
+          return rule === null ? [] : [{ ...f, rule }];
+        });
+        for (const f of excluded) {
+          const problem = lockfileProblem(top, f.file, reviewConfig);
+          if (problem !== null) throw new StateError('lockfile', `lockfile ${f.file}: ${problem}`);
+        }
+        const otherRows = closeRows.filter((r) => r.event !== 'gate.review_excluded');
+        closeRows.splice(0, closeRows.length, ...otherRows, ...excluded.map((f) => ({ event: 'gate.review_excluded', block: id, ...f })));
         const isMine = (/** @type {string} */ f) => owns(entry.owned_files, f, entry.owned_kinds);
         const key = await loadKey(runId);
         // B52: an empty diff with review rows is never silent — name the likely cause
@@ -801,7 +909,7 @@ export async function runBlock(args, deps = {}) {
           unowned: scope?.unowned ?? [],
           // B52: an old ledger's review.result rows are judged by their signed result files
           resultFiles: await resultFilesFor({ repoRoot: mainTop, runId, block: id, rows }),
-          files: reviewsWaived || external !== null ? [] : fileSet,
+          files: reviewsWaived || external !== null ? [] : fileSet.filter((f) => reviewExcludeRule(reviewConfig, f.file) === null),
           // B52: nothing changed and nothing reviewed is never a pass (the owner's way out is
           // --no-require-reviews); B58: `review.external` does not lift it
           noChanges: !reviewsWaived && fileSet.length === 0,
@@ -852,7 +960,7 @@ export async function runBlock(args, deps = {}) {
               }
             };
             return await (deps.reviewedLines ?? reviewedLines)({
-              files: fileSet,
+              files: fileSet.filter((f) => reviewExcludeRule(reviewConfig, f.file) === null),
               waivedAll,
               ticketOf,
               onNoTicket: (file) => lineWarnings.push(`WARN no ticket for ${file}\n`),
@@ -879,7 +987,7 @@ export async function runBlock(args, deps = {}) {
         const { fileSet } = await tree();
         const lines = await toolLines();
         const given = new Set(lines.map((l) => l.file));
-        const missing = missingReviewTickets(text, fileSet.map((f) => f.file)).filter((f) => !given.has(f));
+        const missing = missingReviewTickets(text, fileSet.filter((f) => reviewExcludeRule(reviewConfig, f.file) === null).map((f) => f.file)).filter((f) => !given.has(f));
         if (missing.length > 0) return { ok: false, reason: `coder report FAILED: no review-file ticket id for ${missing.join(', ')}` };
         for (const file of reportMismatches(text, lines)) lineWarnings.push(`WARN report ticket mismatch ${file}\n`);
         return { ok: true };
@@ -900,7 +1008,9 @@ export async function runBlock(args, deps = {}) {
       });
       if (configInForce(record)?.gates?.test != null) {
         const testGate = async () => {
-          const green = rows.filter((row) => row.block === id && row.event === 'gate.done' && row.all_ok === true);
+          // A rebase changes the tested tree even when owned commit timestamps are preserved.
+          const lastRebase = rows.reduce((last, row, index) => row.block === id && row.event === 'block.rebase' ? index : last, -1);
+          const green = rows.filter((row, index) => index > lastRebase && row.block === id && row.event === 'gate.done' && row.all_ok === true);
           // Only commits after the block base that touch its owned paths belong to this block.
           // Older rows without timestamps remain usable, but a failed history lookup cannot prove freshness.
           const commit = green.length === 0 ? null : await exec(['git', 'log', '-1', '--format=%ct', `${base}..HEAD`, '--', ...entry.owned_files], {
@@ -1024,6 +1134,7 @@ export async function runBlock(args, deps = {}) {
           await warnMovedBase(record.workspace, entry, id, runId, err);
           for (const w of lineWarnings) err(w);
           for (const l of reviewedJson) say(`reviewed ${l.file} ticket ${l.ticket}\n`);
+          for (const f of closeRows.filter((r) => r.event === 'gate.review_excluded')) say(`not reviewed (review.exclude ${f.rule}): ${f.file}\n`);
           for (const f of waivedAll) {
             const parts = f.findings.length > 0 ? [`${f.findings.join(', ')}; by ${f.by}`] : [];
             if (f.answered?.length) parts.push(`answered ${f.answered.join(', ')}`);
@@ -1072,6 +1183,9 @@ export async function runBlock(args, deps = {}) {
       }
     }
   } catch (thrown) {
+    if (jsonOpenId && thrown instanceof StateError && ['after-not-done', 'bad-after', 'outcome-not-ready', 'bad-after-outcome'].includes(thrown.code)) {
+      out(`${JSON.stringify({ block: jsonOpenId, event: 'refused', code: thrown.code, message: thrown.message })}\n`);
+    }
     err(`block ${sub ?? ''}: ${thrown?.message ?? String(thrown)}\n`);
     return thrown instanceof StateError && thrown.code === 'usage' ? 2 : 1;
   }
@@ -1168,7 +1282,7 @@ export const NO_REVIEWS_NO_TTY = '--no-require-reviews needs the human at a term
 
 /**
  * B80: the refusal when `block waive` or `block reopen` has no terminal to ask the human at.
- * @param {'waive' | 'reopen' | 'accept-hit' | 'unwaive' | 'ack-waivers' | 'human-pass' | 'amend-acceptance' | 'close'} verb @returns {string}
+ * @param {'waive' | 'reopen' | 'accept-hit' | 'unwaive' | 'ack-waivers' | 'human-pass' | 'amend-acceptance' | 'close' | 'rebase'} verb @returns {string}
  */
 export const humanVerbNoTTY = (verb) => verb === 'waive'
   ? 'block waive needs the human at a terminal to confirm; nothing was recorded (--yes works only for a recorded warning or nit finding, with evidence)'
@@ -1229,14 +1343,16 @@ async function confirmNoReviews(runId, id, deps) {
  * `by: autopilot`); human-pass instead refuses an active grant. The
  * pre-checks (`reopenPrecheck`, `waivePrecheck`) run first, at a terminal, so the human is never
  * asked about a waive or reopen the verb would refuse that way.
- * @param {'waive' | 'reopen' | 'accept-hit' | 'unwaive' | 'ack-waivers' | 'human-pass' | 'amend-acceptance'} verb @param {string} runId @param {string} id
+ * @param {'waive' | 'reopen' | 'accept-hit' | 'unwaive' | 'ack-waivers' | 'human-pass' | 'amend-acceptance' | 'rebase'} verb @param {string} runId @param {string} id
  * @param {{finding?: string, file: string, rule?: string, line?: number, hits?: {rule: string, line: number}[], oldCount?: number, newCount?: number}} what @param {Record<string, any>} record @param {ConfirmDeps} deps
  * @param {() => Promise<unknown> | unknown} [before]
  * @returns {Promise<'no-tty' | 'confirmed' | 'cancelled'>}
  */
 function confirmHumanVerb(verb, runId, id, what, record, deps, before) {
   const message = () =>
-    verb === 'amend-acceptance'
+    verb === 'rebase'
+      ? `Accept rebased changes in ${what.file} of block ${id} (run ${runId})? Only the owner may say yes.`
+      : verb === 'amend-acceptance'
       ? `Amend acceptance of block ${id} (run ${runId}) from ${what.oldCount} clauses to ${what.newCount} clauses? Only the owner may say yes.`
       : verb === 'human-pass'
       ? `Confirm all device checks of block ${id} (run ${runId}) passed? Only the owner may say yes.`

package/src/cli/context.mjs

@@ -7,7 +7,7 @@
  * (`tmp.root` is fixed for the run), as for the worker. The orchestrator sends the pack's text with
  * every coder task.
  *
- * Prints two lines: the path, then `tokens ~<n>` (the review packets' bytes / 4 estimate); with
+ * Prints the pack text; --path-only prints the path then `tokens ~<n>` for legacy callers; with
  * `--json` one line `{"path":…,"tokens":…,"lines":…,"cut":…,"sha256":…}`. Each pack written
  * appends a signed `context.pack {block, path, sha256, tokens, lines, cut}` ledger row — unless
  * the block's last verified `context.pack` row has the same sha256 and path (same pack: no row,
@@ -16,17 +16,19 @@
  * `<block>.md`. A row that cannot be appended removes only the temp file, so an earlier pack stays
  * as it was and nothing was written. A rename that fails after the row was appended says so.
  *
- * With no `context` key, the pack holds only the block header and built-in proof rule (300 lines).
+ * The header names this install's exact node/bin command and version. With no `context` key,
+ * the pack holds the block header, code-forge section and built-in proof rule (300 lines).
  * Exit codes: 0 written, 1 refused (a rules or lessons file missing or outside
  * the repository, a bad `context` value, a control character, an unknown run or block, a file or
  * ledger write that fails), 2 usage. Never runs any command it lists.
  */
 
 import { createHash } from 'node:crypto';
-import { mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { loadProjectConfig } from '../config/load.mjs';
-import { assemblePack, ContextError, contextSettings, packTokens, readSources } from '../context/pack.mjs';
+import { assemblePack, ContextError, contextSettings, packTokens, readBlockBrief, readSources } from '../context/pack.mjs';
 import { appendRow, readAllRows } from '../ledger/write.mjs';
 import { runRootFor } from '../session/spawn.mjs';
 import { parseFlags } from '../state/cli-args.mjs';
@@ -37,7 +39,7 @@ import { loadKey, verifyRow } from '../state/signer.mjs';
 import { assertBlockId, mainRootOf, WorkerError } from '../worker/ticket.mjs';
 import { writeSafe } from '../util/redact.mjs';
 
-const USAGE = 'usage: code-forge context pack --run <id> --block <id> [--json]\n';
+const USAGE = 'usage: code-forge context pack --run <id> --block <id> [--json] [--path-only]\n';
 
 /** @param {unknown} err @returns {string} the fs error's code (or message) for a one-line refusal. */
 const fsCode = (err) => /** @type {NodeJS.ErrnoException} */ (err)?.code ?? (err instanceof Error ? err.message : 'error');
@@ -76,7 +78,7 @@ export async function runContext(args, deps = {}) {
     return 2;
   }
   try {
-    const { flags, positionals } = parseFlags(rest, { values: ['run', 'block'], booleans: ['json'] });
+    const { flags, positionals } = parseFlags(rest, { values: ['run', 'block'], booleans: ['json', 'path-only'] });
     if (positionals.length > 0 || typeof flags.run !== 'string' || typeof flags.block !== 'string') throw new StateError('usage', 'context pack needs --run and --block');
     const runId = flags.run;
     let block;
@@ -106,7 +108,14 @@ export async function runContext(args, deps = {}) {
         level: entry.level ?? null,
         owned: Array.isArray(entry.owned_files) ? entry.owned_files : [],
         tests: Array.isArray(entry.test_files) ? entry.test_files : null,
+        brief: readBlockBrief(repoRoot, entry),
+        acceptance: entry.acceptance,
         worktree: entry.worktree && typeof entry.worktree.path === 'string' ? { path: entry.worktree.path, branch: entry.worktree.branch } : null,
+        codeForge: {
+          node: process.execPath,
+          bin: fileURLToPath(new URL('../../bin/code-forge.mjs', import.meta.url)),
+          version: JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version,
+        },
       },
     });
     const sha256 = createHash('sha256').update(text).digest('hex');
@@ -155,7 +164,8 @@ export async function runContext(args, deps = {}) {
       return 1;
     }
     if (flags.json === true) writeSafe(stdout, `${JSON.stringify({ path: file, tokens, lines, cut, sha256 })}\n`);
-    else writeSafe(stdout, `${file}\ntokens ~${tokens}\n`);
+    else if (flags['path-only'] === true) writeSafe(stdout, `${file}\ntokens ~${tokens}\n`);
+    else writeSafe(stdout, text);
     return 0;
   } catch (thrown) {
     if (thrown instanceof StateError && thrown.code === 'usage') {