valent-pipeline 0.18.0 → 0.19.15

package/bin/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { Command } from 'commander';
-import { readFileSync } from 'fs';
+import { readFileSync, realpathSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 
@@ -74,6 +74,7 @@ program
   .option('--root <dir>', 'Project root to project the board over (defaults to the current directory)')
   .option('--open', 'Open the board in the default browser once it is listening')
   .option('--no-audit', 'Skip merging the per-agent token/wall-clock cost trail into the board')
+  .option('--actions', 'Enable the write bridge (POST /api/actions/* -> allowlisted `valent backlog` commands via execFile). Loopback-only; hardened with global Host validation + Origin checks + a per-process token embedded in the served shell')
   .action(async (options) => {
     const { boardCmd } = await import('../src/commands/board.js');
     await boardCmd(options);
@@ -95,6 +96,22 @@ program
     await auditCmd(options);
   });
 
+// launch command — preflight + the exact /valent-run-… command to paste (NEVER spawns: the
+// Claude Code window is the run mutex). Powers the board's launcher panel with --json.
+program
+  .command('launch')
+  .description('Preflight a run and print the exact /valent-run-… command to paste into your Claude Code window. Never spawns — the window is the run mutex (one window = one runner)')
+  .option('--story [id]', 'Launch a single story (id optional — omitted resolves the next eligible story)')
+  .option('--epic <id>', 'Launch an epic loop (plan → sprint → retro)')
+  .option('--project', 'Launch the full-backlog (cross-epic) loop')
+  .option('--spike [id]', 'Launch a spike de-risking session')
+  .option('--root <dir>', 'Project root (defaults to cwd)')
+  .option('--json', 'Emit the launch plan as JSON (for the board launcher)')
+  .action(async (options) => {
+    const { launchCmd } = await import('../src/commands/launch.js');
+    await launchCmd(options);
+  });
+
 // analyze command — evidence-per-token rollups (gate / model tier / profile / rework tax / window fit)
 program
   .command('analyze')
@@ -127,6 +144,36 @@ configCmd
     await validate();
   });
 
+configCmd
+  .command('set <path> <value>')
+  .description('Set one dot-path setting (board M5), comment-preserving, with validate-after-set ROLLBACK — an edit that invalidates the config is refused and not written. Value is JSON when it parses (true/5/[..]), else a bare string. e.g. `config set quality.max_rejection_cycles 4`')
+  .option('--root <dir>', 'Project root (defaults to cwd; resolves .valent-pipeline/pipeline-config.yaml)')
+  .option('--config <path>', 'Explicit config file path (overrides --root)')
+  .action(async (path, value, options) => {
+    const { configSet } = await import('../src/commands/config.js');
+    await configSet(options, path, value);
+  });
+
+configCmd
+  .command('set-raw')
+  .description('Replace the whole pipeline-config.yaml with YAML read from STDIN, validate-before-write (board M5 raw editor). Refused if the posted YAML is invalid')
+  .option('--root <dir>', 'Project root (defaults to cwd)')
+  .option('--config <path>', 'Explicit config file path (overrides --root)')
+  .action(async (options) => {
+    const { configSetRaw } = await import('../src/commands/config.js');
+    await configSetRaw(options);
+  });
+
+configCmd
+  .command('apply-preset <name>')
+  .description('Apply a coherent preset (fast-cheap | balanced | max-quality) — model tiers + rejection cycles + reasoning levels — comment-preserving, validated before write (board M5)')
+  .option('--root <dir>', 'Project root (defaults to cwd)')
+  .option('--config <path>', 'Explicit config file path (overrides --root)')
+  .action(async (name, options) => {
+    const { configApplyPreset } = await import('../src/commands/config.js');
+    await configApplyPreset(options, name);
+  });
+
 // validate-handoff command
 program
   .command('validate-handoff')
@@ -146,6 +193,7 @@ program
   .option('--file <path>', 'Explicit path to a task-graph YAML (overrides --type)')
   .option('--profiles <list>', 'Comma-separated testing profiles, e.g. api,ui,iac', '')
   .option('--validate-only', 'Validate the graph shape and references without resolving')
+  .option('--out <path>', 'Also write the resolved graph JSON to this file (e.g. stories/<id>/evidence/resolved-graph.json — the durable stage-list record the status board reads); stdout is unchanged')
   .action(async (options) => {
     const { resolveGraphCmd } = await import('../src/commands/resolve-graph.js');
     await resolveGraphCmd(options);
@@ -171,6 +219,8 @@ program
   .option('--backlog <path>', 'Backlog file (YAML/JSON); resolves its `items`')
   .option('--stories <path>', 'Explicit item array (YAML/JSON); overrides --backlog')
   .option('--epic <id>', 'Scope candidates to one epic (deps still resolve against the whole backlog; cross-epic prerequisites must be shipped)')
+  .option('--full', 'Emit eligible/groomedBuffer as full workflow-args candidate objects instead of id lists')
+  .option('--project-type <type>', 'Stamp every --full candidate with this projectType (project config value; only meaningful with --full)')
   .action(async (options) => {
     const { resolveEligibleCmd } = await import('../src/commands/resolve-eligible.js');
     await resolveEligibleCmd(options);
@@ -243,6 +293,7 @@ backlogCmd
   .requiredOption('--story <id>', 'Story identifier')
   .requiredOption('--reason <text>', 'One-line escalation reason')
   .option('--escalation-type <type>', 'skippable | blocking (default skippable)')
+  .option('--origin <origin>', 'Escalation origin the inbox branches on: manual | reject-cap | spike-halt | … (default manual)')
   .option('--state <path>', 'pipeline-state.json path (default ./pipeline-state.json)')
   .option('--date <YYYY-MM-DD>', 'blocked_at date (defaults to today)')
   .action(async (options) => {
@@ -272,12 +323,78 @@ backlogCmd
   .requiredOption('--story <id>', 'Item to cancel')
   .requiredOption('--reason <text>', 'Why (e.g. "superseded by KANBAN-TESTINFRA-002: one root cause, N symptom bugs")')
   .option('--superseded-by <id>', 'Replacing item (usually the priority-0 remediation story); re-points dependents')
+  .option('--state <path>', 'pipeline-state.json path whose blocked_stories entry is cleared (default ./pipeline-state.json)')
   .option('--date <YYYY-MM-DD>', 'cancelled_at date (defaults to today)')
   .action(async (options) => {
     const { backlogCancel } = await import('../src/commands/backlog.js');
     await backlogCancel(options);
   });
 
+backlogCmd
+  .command('reorder')
+  .description('Stack-rank (board M3a): renumber `priority` dense + unique (1..N) across ALL live items — --order must list exactly the non-shipped/cancelled ids (the packer sorts by priority; partial renumbers leave two tie-break regimes). Dependency-order violations warn, never block')
+  .requiredOption('--backlog <path>', 'Backlog file (YAML)')
+  .requiredOption('--order <json>', 'JSON array of every live item id, highest priority first')
+  .option('--expect-hash <hash>', 'Compare-and-swap: refuse the renumber if the backlog file hash differs from this (the board\'s conflict guard — model.backlog_hash; omit to skip)')
+  .action(async (options) => {
+    const { backlogReorder } = await import('../src/commands/backlog.js');
+    await backlogReorder(options);
+  });
+
+backlogCmd
+  .command('set-priority')
+  .description('Single-item move (board M3a): set one item\'s numeric `priority` (lower = higher rank; ties resolve by file position)')
+  .requiredOption('--backlog <path>', 'Backlog file (YAML)')
+  .requiredOption('--story <id>', 'Item to move')
+  .requiredOption('--priority <n>', 'New numeric priority')
+  .action(async (options) => {
+    const { backlogSetPriority } = await import('../src/commands/backlog.js');
+    await backlogSetPriority(options);
+  });
+
+backlogCmd
+  .command('add')
+  .description('New story slot (board M3a): append a `pending` item at the BOTTOM of the ranking (unless --priority) and scaffold stories/<id>/story.md from the story-scaffold template (AC stubs — authoring stays in story files/BMAD). Never overwrites an existing story.md')
+  .requiredOption('--backlog <path>', 'Backlog file (YAML)')
+  .requiredOption('--story <id>', 'New item id (names the stories/<id>/ directory)')
+  .option('--title <text>', 'Human title (also templated into the scaffold)')
+  .option('--points <n>', 'story_points estimate')
+  .option('--depends-on <ids>', 'Comma-separated prerequisite item ids')
+  .option('--profiles <list>', 'Comma-separated testing_profiles, e.g. api,ui')
+  .option('--epic <id>', 'Epic the story belongs to')
+  .option('--priority <n>', 'Explicit priority (default: bottom of the current ranking)')
+  .option('--root <dir>', 'Project root for the story scaffold (defaults to cwd)')
+  .option('--no-scaffold', 'Backlog entry only — skip writing stories/<id>/story.md')
+  .option('--date <YYYY-MM-DD>', 'created_at date (defaults to today)')
+  .action(async (options) => {
+    const { backlogAdd } = await import('../src/commands/backlog.js');
+    await backlogAdd(options);
+  });
+
+backlogCmd
+  .command('comment')
+  .description('Append to a story\'s escalation thread in stories/<id>/output/escalation-log.md (creates the dir + a minimal log on first use) and stamp blocked_stories[].last_comment. --author is a caller convention: the board sends human, run-intake triage sends pipeline')
+  .requiredOption('--story <id>', 'Story identifier')
+  .requiredOption('--author <who>', 'human | pipeline')
+  .requiredOption('--text <text>', 'The comment body (markdown; heading-like lines are escaped)')
+  .option('--root <dir>', 'Project root (defaults to cwd)')
+  .option('--state <path>', 'pipeline-state.json path for the last_comment pointer (default ./pipeline-state.json)')
+  .option('--at <iso>', 'Entry timestamp (defaults to now)')
+  .action(async (options) => {
+    const { backlogComment } = await import('../src/commands/backlog.js');
+    await backlogComment(options);
+  });
+
+backlogCmd
+  .command('triage-scan')
+  .description('Read-only run-intake scan (board M3b): every blocked story whose escalation thread ends with a HUMAN entry (awaiting the pipeline), with origin/reason + size-bounded thread, as JSON — the deterministic half of intake triage (the session judges accept/needs-info/acknowledge and replies via `backlog comment --author pipeline`)')
+  .option('--root <dir>', 'Project root (defaults to cwd)')
+  .option('--state <path>', 'pipeline-state.json path (default ./pipeline-state.json)')
+  .action(async (options) => {
+    const { backlogTriageScan } = await import('../src/commands/backlog.js');
+    await backlogTriageScan(options);
+  });
+
 backlogCmd
   .command('lint')
   .description('Structural backlog validation BEFORE a run (PUR-001 R-6.3): duplicate/missing ids, self-deps, depends_on refs to nonexistent items, dependency cycles, non-array workspaces, case-variant types (errors, exit 1); unknown statuses, missing bug refs, non-numeric priority/points, undetected workspace dirs (warnings)')
@@ -514,6 +631,7 @@ evidenceCmd
   .option('--hash-files-from-spec', 'Also snapshot every acceptance source the spec manifest declares (files[] + per-case testFile) — helpers outside the acceptance dir stay frozen too')
   .option('--timeout <ms>', 'Kill the wrapped command after this many milliseconds')
   .option('--quiet', 'Suppress live echo of the child output (still captured to output.log)')
+  .option('--digest', 'Append failing case names (junit-derived) + a bounded output.log tail after the trailer')
   .action(async (commandArgs, options) => {
     const { evidenceRunCmd } = await import('../src/commands/evidence.js');
     await evidenceRunCmd(commandArgs, options);
@@ -574,6 +692,7 @@ evidenceCmd
   .option('--root <dir>', 'Project root (defaults to cwd)')
   .option('--label <name>', 'Assert label to bind to (defaults to evidence_gate.label, then qa-b-tests)')
   .option('--tip <ref>', 'Git ref the evidence must cover (defaults to HEAD)')
+  .option('--ancestry-only', 'Skip the post-evidence escape diff (the backlog ledger-door posture, review pass-4 #1); ancestry + green assert + proof only')
   .action(async (options) => {
     const { evidenceVerifyShipCmd } = await import('../src/commands/evidence.js');
     await evidenceVerifyShipCmd(options);
@@ -591,6 +710,18 @@ evidenceCmd
     await evidenceProofCmd(options);
   });
 
+evidenceCmd
+  .command('stage-record')
+  .description('Persist the workflow\'s per-stage verdict ledger (+ optionally the resolved task graph) into stories/<id>/evidence/ — the durable record the status board\'s gate rail reads after run journals are gone. Merge-by-stage: a later record replaces matching stages and keeps the rest.')
+  .requiredOption('--story <id>', 'Story identifier')
+  .requiredOption('--stages <json>', 'JSON array of { stage, verdict, cycles?, disposition?, reason? } — the workflow\'s post-coercion verdicts, verbatim')
+  .option('--graph <json>', 'Resolved task graph JSON ({ tasks, skipped, ... }) to persist as resolved-graph.json alongside')
+  .option('--root <dir>', 'Project root (defaults to cwd)')
+  .action(async (options) => {
+    const { evidenceStageRecordCmd } = await import('../src/commands/evidence.js');
+    await evidenceStageRecordCmd(options);
+  });
+
 evidenceCmd
   .command('pin')
   .description('Record which git SHA a gate reviewed (the CLI captures the SHA — there is no flag to type one)')
@@ -829,7 +960,35 @@ dbCmd
 // Introspection hook (review pass-3 #35): scripts/test-docs.js imports the registered command
 // tree to assert every `bin/cli.js …` invocation in pipeline/** and skills/** against the live
 // commander registry — a prompt referencing a command/flag that does not exist fails `npm test`.
-// Building the program executes nothing (all actions are lazy dynamic imports); the env guard
-// (not an argv heuristic) keeps every real invocation, npx shim included, behaving identically.
+// Building the program executes nothing (all actions are lazy dynamic imports).
+//
+// The guard fails CLOSED (review pass-4 #6): the old truthiness check silently no-opped the
+// ENTIRE CLI with exit 0 under ANY value of the var — a one-env-var trust-chain bypass had it
+// ever leaked into an agent's shell (every evidence/crosscheck/ship-clamp gate would have
+// returned success vacuously, with zero output to notice). Now: imported as a module
+// (test-docs.js) => parse() skipped as before; run as the ENTRYPOINT with the var set => loud
+// stderr + non-zero exit, never silence. realpath survives the npx/.bin shim symlinks; the
+// case-fold handles Windows drive-letter casing.
 export { program };
-if (!process.env.VALENT_CLI_INTROSPECT) program.parse();
+if (process.env.VALENT_CLI_INTROSPECT) {
+  const isEntrypoint = (() => {
+    try {
+      const argv1 = realpathSync(process.argv[1]);
+      return process.platform === 'win32'
+        ? argv1.toLowerCase() === __filename.toLowerCase()
+        : argv1 === __filename;
+    } catch {
+      return false; // no/unresolvable argv[1] (REPL, embedded import) — not a CLI invocation
+    }
+  })();
+  if (isEntrypoint) {
+    console.error('VALENT_CLI_INTROSPECT is set — this variable exists ONLY for scripts/test-docs.js module introspection. '
+      + 'Refusing to run the CLI under it: a silently no-op CLI would fake every evidence gate green. Unset it and re-run.');
+    process.exit(78); // EX_CONFIG
+  }
+  // Imported as a module under the var (the test-docs contract): build the tree, never parse.
+} else {
+  // The var is unset on every real invocation: parse UNCONDITIONALLY, exactly as before pass-4 #6
+  // — entrypoint detection must never be able to silently no-op a genuine CLI run.
+  program.parse();
+}

package/knowledge-seed/curated/pitfalls-cli-tool-node.md

@@ -0,0 +1,21 @@
+# Pitfalls Primer — cli-tool (Node)
+
+**Scope:** stories with the `cli-tool` profile (command-line surfaces: subcommands, flags, exit codes, terminal output contracts).
+**How to use:** This is a *primer, not a checklist to satisfy.* Scan your diff against each item and fix gaps now. It is deliberately short — also handle obvious things *like* these that aren't listed. CRITIC is still the grader; this is just wiping the obvious smudges off first.
+
+## The usual suspects
+
+1. **Exit 0 on failure.** Any path that prints an error (or catches and swallows one) and still exits 0. Scripts and CI branch on exit codes — this is the CLI equivalent of a swallowed exception.
+2. **Contract output polluted.** Logs, banners, progress, deprecation warnings, or color escapes on stdout in a machine-readable mode (or interleaved with pipeable output). Diagnostics go to stderr; stdout is the contract.
+3. **Hidden interactivity.** A code path that can reach a prompt (readline, inquirer, confirm) with no flag/env override and no non-TTY guard hangs CI forever. Guard `process.stdin.isTTY`; every prompt needs a non-interactive escape hatch.
+4. **Unknown input passes silently.** Unknown flags or subcommands ignored instead of erroring non-zero — typos become no-ops that look like success.
+5. **Windows paths and quoting.** Spaces in paths, backslash separators, `cmd.exe` quoting, drive-letter casing. Use `path` APIs and array-form `spawn` (never string-concatenated shell commands) for anything that touches the filesystem or subprocesses.
+6. **Accidental breaking changes.** Renamed/removed flags or subcommands, changed defaults, changed exit codes, or changed output shape that existing scripts depend on — without a deprecation path. Compare against the prior surface before you ship.
+7. **Partial-failure state.** A command that mutates files/state, fails midway, and leaves the mutation half-applied with exit 0 or no resume/rollback. Write-to-temp + rename; report what was and wasn't done.
+8. **Help text drift.** Behavior that contradicts `--help` — missing flags, wrong defaults, stale examples. The help IS documentation; keep it true in the same diff.
+9. **Argument-parsing edges.** Values that look like flags (`--name --verbose`), empty strings, the `--` separator, repeated flags. Probe every option you touched.
+10. **stdin/pipe behavior.** Reading stdin when none was intended (hangs in pipelines), or ignoring piped input a consumer would expect; `EPIPE` on `head`-style consumers crashes instead of exiting quietly.
+11. **Signal handling for long-running commands.** Ctrl-C mid-run leaves temp files, locks, or spinners that corrupt the terminal; cleanup handlers belong on SIGINT/SIGTERM.
+12. **Tests spawn the real binary.** Behavioral coverage spawns the bin entry as a subprocess and asserts exit code + stdout + stderr; failure tests assert the non-zero CODE, not just the message; `--json` modes are parsed with a real parser, not regexed.
+
+*Not exhaustive. If you know an obvious one for this stack that isn't here, handle it anyway.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "valent-pipeline",
-  "version": "0.18.0",
+  "version": "0.19.15",
   "description": "v3 multi-agent AI pipeline for software development lifecycle",
   "type": "module",
   "bin": {

package/pipeline/docs/communication-standard.md

@@ -354,7 +354,7 @@ The decision block is written to `decisions.md` in the story directory. Any agen
 
 ## 7. Headless Escalation Protocol
 
-When a blocker requires human input, the workflow orchestrator classifies it, logs it to `{story_output_dir}/escalation-log.md`, outputs the structured escalation block to CLI for visibility, marks the story `blocked-on-user`, and moves to the next unblocked story. The pipeline does not pause for skippable blockers. Blocking escalations (quality gate failures) stop the current story cleanly before moving on.
+When a blocker requires human input, the workflow orchestrator classifies it, outputs the structured escalation block to CLI for visibility, marks the story `blocked-on-user` (recording it in `pipeline-state.json blocked_stories` with its `origin`), and moves to the next unblocked story. The durable conversation lives in `{story_output_dir}/escalation-log.md`: the board inbox and `valent backlog comment --author human|pipeline` append to its `## Thread` section, and `valent backlog triage-scan` reads it at the next run's intake. The pipeline does not pause for skippable blockers. Blocking escalations (quality gate failures) stop the current story cleanly before moving on.
 
 ### Escalation block format
 
@@ -395,7 +395,7 @@ Need: Pick an option or provide guidance
 - **Blocking** failures (quality gate exhaustion): pipeline stops cleanly on this story, persists state, then moves to the next unblocked story if safe
 - If no unblocked stories remain, the pipeline stops cleanly with persisted state
 - Escalation is the **last resort** — the workflow should exhaust autonomous resolution first (e.g., the code-owned rework cap routing rejections upstream, or Design Council deliberation)
-- All escalations are logged in both `{story_output_dir}/escalation-log.md` and `story-report.md`
+- All escalations surface in `pipeline-state.json blocked_stories` and `story-report.md`; the human<->pipeline conversation about one lives in `{story_output_dir}/escalation-log.md` (`backlog comment`)
 - **Resume:** user fixes inputs, sets story status to `pending` in backlog, re-runs pipeline
 
 > **Note:** Headless escalation is implemented (skip-and-log; blocked stories surface with status `blocked-on-user`). For async notification when escalations occur during headless runs, scheduled remote agents and Slack integration (via MCP) are candidate notification channels.
@@ -453,4 +453,4 @@ Agents should verify their output against this checklist before finalizing.
 - [ ] Context references a file, not inline detail
 - [ ] Options are numbered, concrete, and actionable
 - [ ] Need statement tells the user exactly what is required
-- [ ] Escalation entry written to `{story_output_dir}/escalation-log.md`
+- [ ] Escalation recorded in `pipeline-state.json blocked_stories` (origin + reason); replies via `backlog comment`

package/pipeline/docs/cost-and-resumability-improvements.md

@@ -191,8 +191,9 @@ Resume = relaunch `Workflow({ scriptPath, resumeFromRunId })`; the journal repla
 
 ### Fix A — Idempotent, on-disk phase checkpoints (cross-session resume)
 
-Persist a durable run ledger in the existing SQLite DB (extends the `artifacts`/`calibration` tables in `src/lib/db.js`). Add a CLI command:
+Persist a durable run ledger in the existing SQLite DB (extends the `artifacts`/`calibration` tables in `src/lib/db.js`). Add a CLI command (PROPOSED — `checkpoint` does not exist yet):
 
+<!-- cli-drift: proposed -->
 ```
 node .valent-pipeline/bin/cli.js checkpoint --sprint <id> --story <id> --phase <spec|build|critic|qa|judge> --verdict <pass|ship|reject>
 ```

package/pipeline/docs/headroom-evaluation.md

@@ -0,0 +1,144 @@
+# Headroom Evaluation — Context Compression for the Pipeline
+
+**Date:** 2026-06-11
+**Status:** Research / recommendation. Not yet piloted. **Superseded in part:** integration point 1 (MCP-mode compression) was rejected on token-accounting grounds — `headroom_compress` only accepts inline `content`, so the bulk is already in agent context (and gets re-echoed as output tokens) before compression can act. See `output-discipline.md` for the verified finding and the zero-dependency counter-proposal. The `learn` analysis (integration point 2) stands.
+**Verdict (short):** **Worth a scoped pilot.** Adopt **one dependency** (Dockerized Headroom) for **two integration points**: (1) in-run **compression** via MCP — the primary justification, because it's the piece we couldn't cheaply rebuild; and (2) a post-run **failure-mining** signal (`headroom learn`, dry-run) that rides along for ~zero marginal cost and feeds our Retrospective as *gated proposals*. Two guardrails: keep lossy compression away from gate-critical evidence, and **never** let `learn` auto-write (`--apply`) into our live `~/.claude` / `MEMORY.md`. And reframe the goal: Headroom cuts per-agent context pressure and token cost; it does **not** fix the thing that actually limits our "long runs" (cross-session resumability).
+
+---
+
+## What Headroom is
+
+Open-source (Apache-2.0) "context optimization layer" that compresses verbose content — tool outputs, logs, API responses, RAG chunks, big files — **before it reaches the LLM**. Claims 60–95% token reduction with negligible accuracy delta (GSM8K 0.870→0.870, TruthfulQA 0.530→0.560 on their benchmarks).
+
+- Written in Python (77%) / Rust (18%) / TS. Requires Python 3.10+.
+- ~22.7k stars, 154 releases, v0.24.0 (2026-06-09), active. Apache-2.0.
+- Three deployment modes: **library**, **proxy** (sits between agent and provider, auto-compresses), **MCP server** (exposes tools the agent calls).
+- Ships a Docker image: `ghcr.io/chopratejas/headroom:latest`. So "dockerize it" is already done upstream.
+
+### How the compression works
+- **ContentRouter** auto-detects content type (JSON / source / logs / diffs / HTML) and routes to a purpose-built compressor (SmartCrusher for JSON, AST-aware CodeCompressor, log compressor, etc.).
+- **Selectively lossy**: preserves structural/high-signal tokens (JSON keys, function signatures, error messages, identifiers), compresses low-signal bulk (long string values, function bodies, repeated patterns).
+- **CCR store** (Compress-Cache-Retrieve): keeps the original locally; the LLM gets a `headroom_retrieve` tool to pull full detail on demand. This is the reversibility safety net.
+- **IntelligentContext**: importance-scores messages (recency, semantic relevance, error indicators) and drops the lowest-value ones to fit a token budget.
+
+### MCP mode specifics (the mode you proposed)
+- `headroom mcp install`, or run the Docker image as a local MCP server.
+- Exposes three tools: `headroom_compress`, `headroom_retrieve`, `headroom_stats`.
+- **Key property:** in MCP mode compression is **opt-in per call** — an agent only benefits from content it explicitly pipes through `headroom_compress`. It is *not* automatic interception (that's proxy mode).
+
+### The `learn` feature (separate runtime surface from the MCP server)
+`learn` is **not** something the MCP server "turns on" — it's a standalone offline CLI batch step. Mechanics, confirmed from the docs/source:
+- **Input:** reads Claude Code's **native** session logs at `~/.claude/projects/*.jsonl`. It does *not* require Headroom's own proxy/recording to have been active. **This means it already sees our pipeline runs** — our agents are Claude Code subagents writing exactly those jsonl logs.
+- **What it extracts:** correlates each failed tool call with the later call that fixed it, and emits *operational/environmental* corrections — commands that work, wrong→right file paths, search-scope guidance, large-file offset/limit hints. (Operational, not quality/spec knowledge.)
+- **Output:** prose inside a delimited block `<!-- headroom:learn:start -->`…`<!-- headroom:learn:end -->` in `CLAUDE.md` (project) and `MEMORY.md` (`~/.claude/projects/*/memory/`). On re-run only the marked block is replaced.
+- **Dry-run is the default.** `headroom learn` (no `--apply`) **prints recommendations to stdout and writes nothing.** `--apply` is what mutates files.
+- **Flags:** `--project PATH` (which project to analyze/write, default cwd), `--all` (every discovered project), `--apply` (write; omit for dry-run), `--claude-dir PATH` (override `~/.claude`). Output *file targets* are otherwise fixed (not configurable).
+
+The dry-run-prints-to-stdout behavior is the whole hijack: **stdout is the API.** We don't need a programmatic interface to capture the mined corrections as data.
+
+**Sources:** [docs](https://headroom-docs.vercel.app/docs) · [GitHub](https://github.com/chopratejas/headroom) · [how-compression-works](https://headroom-docs.vercel.app/docs/how-compression-works) · [failure-learning](https://github.com/chopratejas/headroom/blob/main/docs/content/docs/failure-learning.mdx) · [CLI reference](https://chopratejas.github.io/headroom/cli/) · [AIToolly writeup](https://aitoolly.com/ai-news/article/2026-06-07-headroom-new-open-source-tool-reduces-llm-token-consumption-by-60-95-for-rag-and-logs) · [Tosea guide](https://tosea.ai/blog/how-to-use-headroom-context-compression-guide)
+
+---
+
+## How it maps onto our pipeline
+
+Our agents are Claude Code **Workflow subagents** spawned via `agent()` in `sprint.workflow.js`. They self-serve from whatever MCP tools are present in the session (same way Ref MCP / Lever 6 works today). So **integration cost ≈ Lever 6**: register the MCP server in session config, then add per-role prompt hints telling the agents that ingest big outputs to route them through `headroom_compress`.
+
+Where it would actually move the needle, and where it wouldn't:
+
+| Pipeline context cost | Already addressed? | Headroom adds? |
+|---|---|---|
+| 40K-token doc-page pastes | **Yes** — Ref MCP (Lever 6) | No incremental gain |
+| Inter-agent prose bloat in handoffs | **Yes** — distilled handoff format (`communication-standard.md`) | Minimal |
+| Cache misses | **Yes** — byte-identical static-prefix discipline | Minimal in MCP mode |
+| **Raw test/build/lint logs** ingested by QA/EVIDENCE | No | **Strong fit** (logs compress 85–95%) |
+| **Large JSON / API responses** read by DATA/BEND | No | **Strong fit** (70–90%) |
+| **Large source-file reads** by dev agents | Partially | **Moderate fit** (AST-aware, 40–70%) |
+| Reversible "drop now, fetch later" | No | **New capability** (CCR + `headroom_retrieve`) |
+
+So the honest incremental value is **narrower than the headline 60–95%**: it's concentrated on agents that currently swallow raw, machine-generated bulk (logs, JSON, big files). For the rest of the pipeline we've already paid down most of the bloat with Ref + distilled handoffs.
+
+### Build vs. borrow — why this is one dependency, not two
+
+The two features differ sharply in how hard they'd be to rebuild ourselves, and that's what drives the recommendation:
+
+| Capability | Rebuild cost if we DIY | Decision |
+|---|---|---|
+| **Compression** (content-aware routers, AST-aware code compressor, CCR store + reversible `headroom_retrieve`, importance scoring) | **High** — months to do well | **Borrow.** This is the piece we can't cheaply replicate. |
+| **Failure-mining** (`learn`: parse jsonl, correlate fail→fix) | **Low** — our Retrospective could parse the same `~/.claude/projects/*.jsonl` itself | Would not justify a dependency *alone*. |
+
+The synthesis: **we take the dependency for the compression we can't rebuild; once it's in, the `learn` signal comes along at ~zero marginal cost.** That's a materially better cost story than evaluating either feature in isolation — one container amortized across two wins — and it's why reusing Headroom's miner beats writing our own. (If we ever drop the compression dependency, revisit owning the miner ourselves; on its own it's cheap.)
+
+---
+
+## Assessment of your specific proposal
+
+> "Dockerize it and install it as an MCP with the learning feature turned on → reduce context, allow longer runs."
+
+**Dockerize + MCP (compression):** ✅ Sound and low-cost. Upstream Docker image exists; MCP registration mirrors our existing Ref MCP pattern. No orchestrator changes needed — the Workflow script has no FS access, and tools activate from session config. This is the primary justification.
+
+**"Allow longer runs":** ⚠️ **Partial mismatch.** Each `agent()` is a fresh subagent with its own context window, so the real "long run" blocker is **cross-session resumability** — our journal is in-memory and same-session (`pipeline-state-schema.md`, and Problem 1 in `cost-and-resumability-improvements.md`). Headroom does nothing for that. What it *does* do is relieve **per-agent window pressure**: a QA/EVIDENCE agent chewing through huge logs hits its window later, and a dev agent can read more files before saturating. That's real, but it's "each agent does more before saturating," not "the overall run survives longer."
+
+**"Learning feature turned on":** ✅ **Yes — but as a gated proposal feed, not an auto-writer, and it's a separate step from the MCP server.** Worth correcting the framing first: installing the MCP server does **not** turn on `learn`. Compression is the live MCP server; `learn` is an offline CLI you invoke *after* a run. So "MCP with learning on" is really **two integration points from one dependency**, not one toggle.
+
+The right shape for `learn`:
+- Run it in the **Retrospective phase**, **dry-run** (`headroom learn --project <repo>`, no `--apply`), scoped to this project.
+- Capture **stdout** (the mined fail→fix corrections) and feed them as **candidate directives** into our existing gating — impact gating, invariant guards, stale-reissue guards. Our governance still decides what becomes active.
+- These corrections are *operational/environmental* (commands, paths, scopes), so they land in the **curated pitfall/environment layer** — which today is hand-seeded — not the retrospective *quality*-directive layer. Good fit for auto-proposing additions to a layer we currently maintain by hand.
+
+What we must **not** do — and why the naive "turn learning on" is dangerous on *this* machine specifically:
+- `headroom learn --apply` writes into `CLAUDE.md` **and `~/.claude/projects/*/memory/MEMORY.md`** — the exact auto-memory file this pipeline depends on. An uncontrolled `--apply` could clobber/append into live memory, bypassing our `correction-directives.yaml` lifecycle and once-per-batch curation discipline.
+- It reads `~/.claude` globally (`--all` spans every project; even scoped runs read the shared jsonl), so cross-project bleed is real — it could surface "corrections" mined from unrelated work on this box.
+- The fail→fix correlation is a **heuristic** — the "fix" may be coincidental, not causal. That's *why* it must enter as gated proposals, never raw auto-writes.
+
+**Rule:** dry-run only against the real `~/.claude` (or sandbox `--claude-dir`); never `--apply` to the live home dir; everything routes through our gating.
+
+---
+
+## Risks / caveats
+
+1. **MCP mode is opt-in.** Compression only happens on content agents deliberately pass to `headroom_compress`. Requires per-role prompt hints + the agents actually complying. Same adoption risk Ref MCP has.
+2. **Selectively lossy.** A compressor that drops "low-signal" content from a build log could drop the one stack frame a CRITIC/EVIDENCE agent needed. CCR/`headroom_retrieve` is the mitigation, but only if the agent knows to retrieve. For **gate-critical evidence** (EVIDENCE, JUDGE inputs) I'd be cautious — these are the artifacts we least want quietly summarized.
+3. **Caching interaction.** Our biggest existing lever is byte-identical static prefixes for Anthropic prompt-cache hits. MCP mode doesn't touch prompt structure, so low risk. **Proxy mode would** rewrite message contents and must be validated against our cache discipline before considering it.
+4. **Overlap.** Ref (Lever 6) + distilled handoffs already capture much of the easy savings. Don't double-count.
+5. **State/persistence.** CCR cache lives in the container (single-host fine). True cross-agent `SharedContext` wants the heavier memory stack (Qdrant/Neo4j devcontainer) — out of scope for a first pilot.
+6. **`learn` `--apply` collides with our live memory.** It writes into `CLAUDE.md` and `~/.claude/projects/*/memory/MEMORY.md` — the auto-memory this pipeline depends on. Mitigation: dry-run only / sandbox `--claude-dir`; never `--apply` to the live home dir.
+7. **`learn` cross-project bleed.** It reads `~/.claude` globally (`--all`, and shared jsonl even when scoped), so it can surface "corrections" mined from unrelated work on this box. Mitigation: `--project`-scope tightly and gate everything.
+8. **`learn` heuristic quality.** Fail→fix correlation can be coincidental, not causal. Mitigation: enter as gated proposals, measure true-positive rate at the gate.
+9. **Their own "skip it" advice:** Headroom docs say skip it if you rely solely on a provider's native compaction or run in sandboxes where local processes can't run. We're neither, but worth noting.
+
+---
+
+## Recommendation
+
+**Run a scoped pilot: one dependency, two integration points.** Compression is the reason to adopt; `learn` is the bundled bonus, gated.
+
+Sequence it with the **RAG / Knowledge Retrieval Audit we already owe** (`knowledge-system.md` §4) — both are "is the savings real on *our* workload?" questions and share an evaluation harness.
+
+**Dependency:** Dockerized Headroom (`ghcr.io/chopratejas/headroom:latest`), one container.
+
+**Integration point 1 — compression (MCP, in-run):**
+1. Wire `headroom_compress`/`headroom_retrieve` to **QA-B, EVIDENCE, and dev agents (BEND/DATA)** only — the large-raw-output ingesters. Mirror the Lever-6 config surface: `headroom: { enabled?: true, roles?: [...] }`.
+2. **Guardrail:** exclude gate-critical evidence artifacts from lossy compression, or require `headroom_retrieve` before any ship/reject decision references compressed content.
+
+**Integration point 2 — failure-mining (`learn` CLI, post-run, gated):**
+3. Add a **Retrospective sub-step** that shells `headroom learn --project <repo>` in **dry-run**, captures stdout, and submits the mined corrections as **candidate directives** into our existing impact/invariant/stale gating → curated pitfall/environment layer.
+4. **Guardrail:** never `--apply` against the live `~/.claude`; dry-run only (or sandbox `--claude-dir`); everything flows through our gating. Protects `MEMORY.md` and `correction-directives.yaml` discipline.
+
+**Measurement (both, over 5–10 stories):** tokens/story and cache-hit rate via `valent-review-cost`/`/audit`; whether any CRITIC/JUDGE/EVIDENCE decision degraded because signal was compressed away; and the signal-quality / false-positive rate of `learn`'s proposed corrections at the gate. Compare against today's Ref+distilled baseline, not an un-optimized strawman.
+
+**Decision:** keep compression for roles where net token savings is material **and** zero evidence-quality regressions; keep `learn` if its gated proposals show a useful true-positive rate. Revisit **proxy mode** (auto-compression) only if the MCP pilot proves out and we've validated it against our prompt-cache discipline.
+
+**Bottom line:** Not dumb. The headline framing oversells it — it's a **narrower, per-agent win** than 60–95%, and it doesn't extend run *length* (that's our resumability problem, untouched). But the build-vs-borrow math is the real story: **compression is the piece we couldn't cheaply rebuild, and taking that one dependency gets the failure-mining signal essentially for free.** Adopt as a scoped pilot — compression wired to the bulk-ingesting agents, `learn` running dry-run into our gating — measured honestly, with `--apply` kept away from our live home dir.
+
+---
+
+### References
+- Headroom docs — https://headroom-docs.vercel.app/docs
+- GitHub `chopratejas/headroom` — https://github.com/chopratejas/headroom
+- How compression works — https://headroom-docs.vercel.app/docs/how-compression-works
+- Failure-learning (`learn`) — https://github.com/chopratejas/headroom/blob/main/docs/content/docs/failure-learning.mdx
+- CLI reference — https://chopratejas.github.io/headroom/cli/
+- AIToolly overview — https://aitoolly.com/ai-news/article/2026-06-07-headroom-new-open-source-tool-reduces-llm-token-consumption-by-60-95-for-rag-and-logs
+- Tosea usage guide — https://tosea.ai/blog/how-to-use-headroom-context-compression-guide
+- Related internal docs: `cost-and-resumability-improvements.md` (Levers 1–7), `knowledge-system.md` (§4 RAG audit), `communication-standard.md`, `pipeline-state-schema.md`

package/pipeline/docs/output-discipline.md

@@ -0,0 +1,119 @@
+# Output Discipline v2 — Bulk-Log Containment via the Existing Evidence Wrapper
+
+**Date:** 2026-06-11
+**Status:** **Implemented (v0.19.5, 2026-06-11)** — Changes 1–2 live (`--quiet` on all mandated suite invocations; quiet-reporter + log-to-file guidance in all 9 dev roles and the QA-B live-environment steps). Change 3's `--digest` flag is **built but unwired** (`evidence run --digest`; junit-derived failing cases + bounded tail) — prompt wiring stays gated on §6 measurement. History: v2 of this doc followed a cold adversarial review that found v1 (`vp-run` wrapper + PreToolUse hook) duplicated `src/lib/evidence.js`; v1's Headroom analysis (§1) survives, its build plan does not.
+**Verdict (short):** The raw-log token problem is real but **~80% of the fix is two step-file edits and one workflow-string change against infrastructure that already ships**: `evidence run` already tees full stdout+stderr to a hashed, durable `output.log` and already has a `quiet` option — it just isn't used. Add `--quiet` to the mandated QA/ATDD invocations, add quiet-reporter guidance to the dev self-run steps that run bare today, and optionally enhance the existing run trailer with a bounded failure digest. **No new wrapper, no hook, no second log store.** Honest addressable savings: ~3–8% of story spend, concentrated in QA-B — worth shipping because the cost is near zero, not because the savings are large.
+
+---
+
+## 1. Why not Headroom MCP (unchanged from v1)
+
+`headroom-evaluation.md` proposed wiring Headroom's MCP compression into bulk-ingesting agents. Verified against the actual tool schema ([MCP docs](https://headroom-docs.vercel.app/docs/mcp)): **`headroom_compress` takes only inline `content`** — no file path, no server-side read. So the bulk is already in the agent's context as a tool result before compression can act, and compressing requires re-emitting it verbatim as **output tokens** (≈5× input price). Net: original in context twice + compressed copy + an output-token bill. Compression that works must intercept **before the tool result is constructed**. The Ref-MCP analogy fails because Ref retrieves server-side — the agent's first copy is already distilled. Proxy mode (the deployment that genuinely intercepts) stays deferred: it rewrites messages between turns, colliding with byte-identical prompt-cache discipline (Lever 7) and the OAuth'd Pro path.
+
+---
+
+## 2. What the pipeline already has (the v1 blind spot)
+
+`evidence run` (`src/lib/evidence.js`) is already the lossless capture-and-retrieve store v1 proposed to build:
+
+| v1 wanted (`vp-run`) | Already shipped (`evidence run`) |
+|---|---|
+| Tee full stdout+stderr to a log file | `output.log` per run dir (`evidence.js:425`), full interleaved stream |
+| Lossless, citable artifact | SHA-256-hashed into `evidence.json` (`evidence.js:534`), plus frozen junit, git SHA, run index — *stronger* than v1's plan |
+| Exit-code passthrough | Yes — gates depend on it |
+| Bounded digest into context | `formatRunTrailer` (`evidence.js:1246`): exit code, test counts, evidence path |
+| Suppress bulk from context | **`quiet` option already exists** (`evidence.js:399,449`) — suppresses live echo, leaves only the trailer |
+| Compliance enforcement | `qa-b/execute-tests.md:35`: "**Every suite runs wrapped in `evidence run`**"; both ATDD gates invoke it from the workflow (`sprint.workflow.js:788`) |
+| Durable, gate-citable store | `stories/<id>/evidence/` is tracked and survives worktree merge; `qa-b/write-report.md` already requires listing run IDs for JUDGE |
+
+What v1 got wrong as a consequence (all confirmed by the review against code):
+
+- **"Raw log exists only in the agent's transcript" — false.** `output.log` is the existing trust architecture; `qa-b/api.md` already calls it "the raw proof a transcribed table cannot replace."
+- **A second wrapper would *break* the Evidence gate.** A suite run through `vp-run` instead of `evidence run` produces no frozen junit → `assertRules` fails → a burned rework cycle.
+- **The PreToolUse hook fires on the pipeline's own gates.** STATIC runs `pre_critic_gate.commands` bare by design ("run each command… do NOT fix anything"); PACKGATE runs `pack_gate.commands` bare. The v1 default regex (`tsc`, `npm test`…) denies commands the config *orders* agents to run — and an unanchored `npx vitest` regex would deny the mandated `evidence run … -- npx vitest` itself.
+- **A gitignored `.valent-pipeline/logs/` store with retention pruning is a *weaker* audit trail** than the tracked evidence dir — and under `git.parallelism` it dies with the worktree.
+- **`vp-run` re-solves solved bugs** — `runEvidence` already carries the Windows tree-kill and argv re-quoting fixes from adversarial reviews #33/#34.
+
+---
+
+## 3. The actual remaining gap
+
+With `evidence run` accounted for, what still leaks raw bulk into context today:
+
+| Leak | Where | Size (honest) |
+|---|---|---|
+| `evidence run` **echoes the full child output live** by default — `quiet` exists but nothing passes it | QA-B suites (`execute-tests.md:38`), smoke curls (`api.md`), RED/GREEN ATDD gates (`sprint.workflow.js:788`) | 1–4K tokens/passing suite (default reporter, not verbose — v1's 5–30K figure assumed a verbose mode nothing specifies), more on failure; × suites × rejection cycles |
+| **Dev self-runs are bare** — no wrapper, no reporter guidance | `bend/write-tests.md` ("run the full backend test suite"), `handoff.md`, FEND/DATA equivalents | 1–5K tokens/run × attempts |
+| **Docker build / compose logs** during live-server QA | QA-B | 5–50K tokens, the single bulkiest item |
+| Paging fragments after the 30K-char Bash truncation | any of the above on big output | multiplies the above when it bites |
+
+Honest aggregate: **~10–30K addressable input tokens per story** against ~200–400K/story total — **roughly 3–8% of story spend**, mostly at sonnet/haiku input prices, and shrinking as Levers 1–3 reduce rejection cycles. This is a "ship it because it's nearly free," not a headline lever.
+
+---
+
+## 4. The plan (three small changes, no new infrastructure)
+
+### Change 1 — Pass `--quiet` on mandated `evidence run` invocations *(S, workflow + step files)*
+- `qa-b/execute-tests.md` and `qa-b/api.md`: add `--quiet` to the documented commands.
+- `atddRunCmd` (`sprint.workflow.js:788`): add `--quiet` — one string change. RED/GREEN consumers are haiku transcriber gates that need the trailer verdict, not the stream.
+- The trailer already carries exit code + test counts + evidence path; failure detail is one `Read` of the frozen junit/`output.log` away. Step files gain one line: *on failure, `Grep` the run's `output.log` / read the junit `<failure>` entries — never re-run loud.*
+
+### Change 2 — Quiet-reporter guidance in dev self-run steps *(S, prompt-only)*
+For `bend`/`fend`/`data` `write-tests` and `handoff` steps (these run bare and legitimately so — they're inner-loop self-checks, not evidence):
+1. Run quiet first (`--reporter=dot`, `--silent`, `tsc --pretty false`).
+2. On failure, re-run *only the failing file/test* with full output — never the whole suite verbose.
+3. For Docker: build/compose with output to a file (`> build.log 2>&1`), then `Grep`/`Read` the tail — kills the bulkiest leak (§3 row 3) with zero machinery.
+
+### Change 3 (optional, only if measurement demands) — `--digest` on the existing trailer *(S–M, ~30 lines)*
+If §6 measurement shows agents paging `output.log` too often after Changes 1–2: extend `formatRunTrailer` to append failing case names (it already parses junit) + a bounded log tail with an explicit `+K more lines` marker. This is v1's entire `vp-run` value proposition, landed as ~30 lines in the wrapper that already exists.
+
+**Explicitly cut from v1 (with reasons from the review):**
+- ❌ `vp-run` — duplicate of `evidence run`; would fail the Evidence gate if agents obeyed it.
+- ❌ PreToolUse hook — denies STATIC/PACKGATE/ATDD-mandated commands; regex needs maintenance across 9 task graphs / 9 testing profiles; `upgrade` doesn't manage `.claude/settings.json` (only `init` does), so the install story was also wrong. Compliance for QA already *is* deterministic (the Evidence gate rejects unwrapped suites); dev self-run compliance is measured first (§6), prompt-fixed second.
+- ❌ `logs:` template field — `write-report.md` already requires evidence run IDs for JUDGE; add line-range granularity to that existing rule only if measurement shows JUDGE missing signal.
+- ❌ `.valent-pipeline/logs/` + retention pruning — the tracked evidence dir is the log store; pruning an audit trail the gates cite is self-harm.
+
+---
+
+## 5. The "need verbose" question (unchanged answer, corrected mechanism)
+
+`--quiet` bounds *default ingestion*, never *verbose execution* — the full stream always reaches `output.log` (hashed, durable, tracked). An agent that needs everything pages the log with `Read`/`Grep` deliberately, in the amounts it chooses. The unwrapped alternative was never "full verbose in context" anyway: Claude Code truncates at ~30K chars at an arbitrary point. Quiet-wrapped is a strict superset of unwrapped verbose.
+
+One real caveat the review surfaced: QA-B smoke tables deliberately exercise **expected-error** paths, so `Error:`-pattern digests can fill with benign matches. That's an argument for Change 3's junit-derived digest (failing *cases*, not grepped *lines*) over v1's regex approach — and for keeping the digest junit-first if Change 3 ever ships.
+
+---
+
+## 6. Measurement (gates the optional work)
+
+A/B over 5–10 stories vs. current baseline, via `valent analyze` / `audit` on run journals:
+
+| Metric | Keep-criterion |
+|---|---|
+| Tokens/story in **QA-B + RED/GREEN gates + dev self-run turns** | ≥15% reduction *in those roles* (per the review: don't claim pipeline-wide) |
+| Gate quality (CRITIC/JUDGE/Evidence outcomes) | Zero regressions |
+| `output.log` paging frequency after Changes 1–2 | If high → build Change 3; if low → done |
+| Rejection cycles/story | No increase |
+
+Everything is one-line revertible (remove `--quiet`, drop prompt blocks).
+
+---
+
+## 7. Appendix — Headroom remnants (unchanged from v1)
+
+- **`headroom learn` (failure-mining), standalone:** still piloteable for ~zero cost — offline CLI reading `~/.claude/projects/*.jsonl`; never needed the MCP server. Dry-run only, in Retrospective; stdout → candidate directives → existing gating → curated pitfall/environment layer. Never `--apply` against the live `~/.claude` (it writes into `MEMORY.md`). Evaluate on true-positive rate at the gate.
+- **Proxy-mode revisit trigger:** only if raw-bulk pressure remains material after Changes 1–2 are measured, and only with explicit validation against prompt-cache discipline. Expectation: never fires.
+
+---
+
+## TL;DR
+
+v1 diagnosed the right problem (compress-before-context, not after — the Headroom MCP rejection stands) and designed the wrong solution by not reading `evidence.js`: the pipeline already owns a hashed, durable, gate-enforced capture store with an unused `quiet` flag. The corrected plan is **flip `--quiet` on in three places, add quiet-reporter + log-to-file guidance to the bare dev/Docker runs, and optionally teach the existing trailer a junit-derived failure digest later**. ~3–8% of story spend, near-zero build cost, zero new dependencies, evidence trail untouched (it was already better than v1 knew).
+
+---
+
+### References
+- Cold adversarial review (2026-06-11) — verdict "implement modified": cut `vp-run` + hook, rebuild on `evidence run`. Key citations verified: `evidence.js:399/425/449/534/1246`, `qa-b/execute-tests.md:35`, `sprint.workflow.js:788`, `upgrade.js` (no settings.json management).
+- `headroom-evaluation.md` — the rejected compression-dependency alternative (its `learn` analysis stands)
+- `cost-and-resumability-improvements.md` — Levers 1–7 (this is a minor sibling lever; compounds with 1–3)
+- `communication-standard.md` — same principle applied to inter-agent prose
+- Headroom MCP tool schema (verification source) — https://headroom-docs.vercel.app/docs/mcp