@ai-dev-methodologies/rlp-desk 0.10.1 → 0.11.0

package/src/governance.md

@@ -248,6 +248,63 @@ Verifier records WHY each judgment was made in `verify-verdict.json`:
 - Without reasoning, Verifier's verdict is an unsubstantiated judgment
 - Both are archived in `logs/<slug>/` per existing audit trail pattern
 
+### Cost Log (US-023 R11 P2-K)
+`logs/<slug>/cost-log.jsonl` always has at least one entry per campaign. tmux mode runs the estimated path (no LLM SDK token counters), so when prompt/claim/verdict bytes are all zero the entry's `note` field is set to `no_actual_usage_recorded`. Audit pipelines branch on `note` to distinguish "iteration ran but tokens not captured" (tmux estimated path) from "logging broken" (file empty / writer never called). The runner registers `trap '_emit_final_cost_log; cleanup' EXIT INT TERM` so an unconditional final entry is appended even if the campaign exits via an early-return path.
+
+### A4 Fallback Audit (US-017 R5 P0-D)
+When Worker writes done-claim.json but forgets iter-signal.json, the runner auto-generates a verify signal as A4 fallback. This produces an opaque `summary="auto-generated by A4 fallback (done-claim without signal)"` that erases debugging context.
+
+- Each A4 fallback invocation appends a JSONL entry to `logs/<slug>/a4-fallback-audit.jsonl` (event=`a4_fallback`, iter, us_id, source).
+- **Recommended ratio < 10%** of total iterations (per mission). Above this threshold, Worker prompt mandate (Step N+1) is failing — investigate prompt clarity or Worker model.
+- Verifier sets `meta.iter_signal_quality='auto_generated'` when it detects an A4 fallback summary so audit pipelines can join the signal-quality dimension to verdicts.
+
+### BLOCKED Surfacing
+A BLOCKED outcome MUST surface its reason on **FIVE channels at once**: (1) sentinel file (markdown `<slug>-blocked.md` + JSON sidecar `<slug>-blocked.json`), (2) status.json, (3) Leader's stderr console, (4) campaign report, (5) memory.md/latest.md hygiene update (worker mandate per US-020 R8 P1-H — `Blocking History` entry in memory.md and `Known Issues` update in latest.md before the sentinel is written). Sentinel-only is silent failure; operators (and wrappers) must see WHY without grep'ing memo files. The leader propagates `verdict.reason || verdict.summary` into the sentinel reason field, the JSON sidecar, the return object, and the campaign report. The 5th channel survives across iterations: the next worker reads memory.md before re-attempting, preventing same-block-reason loops.
+
+When the worker writes a sentinel without performing the 5th-channel hygiene update (memory.md/latest.md mtime older than 5 minutes at sentinel-write time), the runner stamps `meta.blocked_hygiene_violated=true` on the JSON sidecar and emits an analytics event so audit pipelines can track hygiene compliance.
+
+### Failure Taxonomy (P1-D)
+BLOCKED writes a JSON sidecar (`<slug>-blocked.json`) alongside the markdown sentinel so wrappers can `jq .reason_category` instead of regex'ing free text. Schema:
+
+```json
+{
+  "schema_version": "2.0",
+  "slug": "<slug>",
+  "us_id": "<us_id or ALL>",
+  "blocked_at_iter": <int>,
+  "blocked_at_utc": "<iso8601>",
+  "reason_category": "metric_failure | cross_us_dep | context_limit | infra_failure | repeat_axis | mission_abort",
+  "reason_detail": "<full reason text>",
+  "failure_category": "spec | implementation | integration | flaky | null",
+  "recoverable": true | false,
+  "suggested_action": "next_mission_chain | restart | retry_after_fix | terminal_alert"
+}
+```
+
+**Wrapper contract (binding)**:
+- `reason_category` is **PRIMARY** — wrappers MUST branch on this field for recovery decisions.
+- `failure_category` is **SECONDARY, diagnostic only** — do NOT branch on it; logging/triage only.
+
+**Category → wrapper recovery action mapping** (defaults set by writer; wrappers may override but should follow):
+- `metric_failure` → `retry_after_fix` (fix PRD/code, retry; recoverable=true)
+- `cross_us_dep` → `retry_after_fix` (move AC to later US or switch to batch mode; recoverable=true)
+- `infra_failure` → `restart` (CLI/network/spawn issue; recoverable=true)
+- `context_limit` → `next_mission_chain` (current mission stale; recoverable=false)
+- `repeat_axis` → `next_mission_chain` (model ceiling reached on this axis; recoverable=false)
+- `mission_abort` → `terminal_alert` (flywheel guard exhausted; recoverable=false)
+
+**Cross-US token list (cross_us_dep classifier)** — verifier verdict / worker signal text matching ANY of these is classified as `cross_us_dep`:
+- English: `depends on US-`, `blocking US-`, `awaits US-`, `post-iter US-`, `requires US-N`, `cross-US`
+- Korean: `US-N 산출물`, `신규 US-`, `post-iter`
+
+**Write Order Contract (atomicity invariant)**:
+1. JSON sidecar written FIRST (`fs.writeFile` / `atomic_write`).
+2. markdown sentinel written SECOND.
+3. Invariant: **markdown exists ⇒ JSON exists** (writer enforces order).
+4. Wrappers SHOULD watch markdown sentinel, then read JSON sidecar. If JSON not yet visible (rare), retry up to 5 × 50ms before failing.
+
+`atomic_write` provides per-file rename atomicity; cross-file ordering is enforced by the explicit two-call sequence.
+
 ## 2. Roles
 
 ### Leader (current session)
@@ -486,6 +543,7 @@ for iteration in 1..max_iter:
   ⑥½ Flywheel direction review (when --flywheel on-fail and consecutive_failures > 0)
      - Dispatch Flywheel agent (fresh context, --flywheel-model)
      - Read flywheel-signal.json for direction decision (hold/pivot/reduce/expand)
+     - Optional `next_mission_candidate` field (string | null): when present, the leader propagates it to status.json so consumer wrappers can chain the next mission without code edits. See docs/multi-mission-orchestration.md.
      - If --flywheel-guard on:
        - Dispatch Guard agent (fresh context, --flywheel-guard-model)
        - Read flywheel-guard-verdict.json:
@@ -544,6 +602,10 @@ Worker completes US-001 → signal verify (us_id: "US-001")
 
 **Batch mode** (`--verify-mode batch`) preserves legacy behavior: Worker signals `verify` only after all work is done, and the Verifier checks all AC at once.
 
+**Cross-US dependency rule (per-us only):** In per-us mode each AC must reference only the same US or earlier verified US' artifacts. Future-US references (e.g. "post-iter US-(N+M) batch", "new US-(M) artifact") make the AC unsatisfiable inside a single per-us iteration and are rejected at init time (`init_ralph_desk.zsh` exits 2). Fold cross-US verification into the last measurement US, or run with `--verify-mode batch`.
+
+**Cross-mission us_id leak prevention (US-022 R10 P2-J):** When the same `$DESK` directory hosts back-to-back missions, an `iter-signal.json` left over from the prior mission can carry a `us_id` (e.g. `US-005`) that has no corresponding section in the new mission's PRD (`US-001` through `US-003`). The runner would then scope-lock the next iteration to a non-existent US and block. `init_ralph_desk.zsh` runs `_quarantine_stale_signal` (lib_ralph_desk.zsh) which moves any signal whose `us_id` is absent from the new mission's PRD into `.sisyphus/quarantine/iter-signal.<epoch>.json` instead of `rm`-ing it. The PRD US-list extractor `_extract_prd_us_list` recognises three heading variants (`## US-005:`, `## US-005 -`, bare `## US-005`) so legitimate references are not false-flagged. The quarantine file is preserved so the operator can recover when the leak was actually intentional handoff state.
+
 ## 7b. Cross-Engine Consensus Verification
 
 Controlled by `--consensus off|all|final-only` (default: `off`).
@@ -625,6 +687,93 @@ If `cb_threshold` or more consecutive fix attempts fail for the same US:
 
 In tmux mode: Leader writes `<slug>-escalation.md` with the report and sets BLOCKED sentinel with reason "architecture-escalation."
 
+## 7e. Lane Enforcement (P1-E)
+
+Default mode is **WARN-only** (`LANE_MODE=warn`). The opt-in `--lane-strict`
+flag (or `LANE_MODE=strict`) escalates lane violations to BLOCKED, but the
+escalation is **downgraded** to `recoverable=true` + `suggested_action=retry_after_fix`
+(NOT `terminal_alert`) so an inaccurate mtime audit does not terminally
+kill a campaign.
+
+### Decision tree
+
+| Detection | Default (`warn`) | `--lane-strict` |
+|-----------|-----------------|-----------------|
+| PRD / test-spec / memory mtime changed during a worker iteration | analytics event `event_type=lane_violation_warning` + `log_warn` + audit log entry. Loop continues. | All of the WARN actions PLUS sentinel BLOCKED with `reason_category=infra_failure`, `recoverable=true`, `suggested_action=retry_after_fix`. |
+
+### Channels (Silent failure 0)
+
+WARN mode is NOT silent — violations always emit on three channels:
+1. analytics jsonl event (`lane_violation_warning`)
+2. leader stderr (`log_warn`)
+3. audit log file `~/.claude/ralph-desk/logs/<slug>/lane-audit.json`
+
+The audit log is initialized to `[]` at campaign start so the file always exists;
+each violation appends an entry `{file, mtime_before, mtime_after, iter, lane_mode}`.
+
+### Why downgrade in strict mode
+
+mtime audit is best-effort heuristic — it cannot accurately attribute the
+modifier (worker vs leader vs external editor). Running an inaccurate
+detector with `terminal_alert` would hand it the power to permanently
+terminate a campaign. The downgrade keeps `recoverable=true` so wrappers
+can re-launch after operator review.
+
+### Non-goals
+
+- chmod-based enforcement (would break test fixtures and consumer envs).
+- git_blame-based actor identification (best-effort hint only; verifier IL-2
+  is the real lane gate via worker process audit).
+- Auto-launching missions on violation (consumer wrapper responsibility).
+
+## 7f. Test Density Enforcement (US-018 R6 P1-F)
+
+Default mode is **WARN-default** (`TEST_DENSITY_MODE=warn`). The opt-in `--test-density-strict` flag escalates a `< 3 tests/AC` finding to a non-zero `init` exit. Worker prompt mandates **>= 3 tests per AC** (happy + negative + boundary categories — IL-4). The test-spec must encode the same density. When the test-spec encodes fewer (e.g., 1 test per AC) the contract collapses: Worker following the prompt fails IL-4, Worker following the spec fails the prompt.
+
+`init_ralph_desk.zsh` runs `_lint_test_density` (lib_ralph_desk.zsh) on the generated PRD + test-spec pair before campaign launch.
+
+### Decision tree
+
+| Detection | Default (`warn`) | `--test-density-strict` |
+|-----------|-----------------|-----------------|
+| Any US has `test_count < 3 * ac_count` | log_warn to stderr + audit log entry (`logs/<slug>/test-density-audit.jsonl`). Init exits 0. | All WARN actions PLUS init exits 1 with the same message. |
+
+### Why no downgrade in strict mode
+
+Test density is a *static* property of the test-spec, deterministically measurable, and observed before any worker runs. There is no risk asymmetry comparable to the lane-mtime audit (which is best-effort heuristic). Strict mode is a hard fail because the failure is unambiguous: too few tests for the AC count.
+
+### Categorization (happy + negative + boundary)
+
+The `>= 3 tests / AC` rule is a coverage floor, not a ceiling. Worker should distribute tests across:
+- **happy**: standard input → expected output
+- **negative**: malformed/missing input → defined error
+- **boundary**: edge of allowed range, off-by-one, empty/max collections
+
+If any category is missing for an AC the test-spec generator should densify before init. The runtime gate only counts; the categorization is enforced by the verifier's Test Coverage Audit (governance §1f Verifier reasoning).
+
+## 7g. Signal Vocabulary Extension (US-019 R7 P1-G)
+
+The base signal vocabulary (`continue | verify | blocked`) is binary at the iteration level: every AC in the current US either passes together or the whole iteration blocks. When unblocked ACs share an iteration with a single unsatisfiable AC the all-or-nothing semantic discards real progress.
+
+`verify_partial` lets the worker emit progress and a deferral in one signal:
+
+```json
+{
+  "iteration": N,
+  "status": "verify_partial",
+  "us_id": "US-001",
+  "verified_acs": ["AC1", "AC2"],
+  "deferred_acs": ["AC3"],
+  "defer_reason": "AC3 depends on US-003 batch artifacts; cross-US"
+}
+```
+
+- Verifier evaluates **only** `verified_acs`. `deferred_acs` are out-of-scope (not fail).
+- Deferred ACs queue for the next iteration or the final ALL verify pass.
+- The runner downgrades to `blocked` with reason `verify_partial_malformed` (reason_category `mission_abort`, recoverable=true, suggested_action=retry_after_fix) when `verified_acs` is missing or empty — the verifier has nothing to evaluate, so silent acceptance would be a false GREEN.
+
+The downgrade is intentionally recoverable: the malformed signal is a worker-side prompt regression, not an environment failure, and the operator can fix it in-place.
+
 ## 8. Circuit Breaker
 
 | Condition | Verdict |
@@ -633,12 +782,23 @@ In tmux mode: Leader writes `<slug>-escalation.md` with the report and sets BLOC
 | Same acceptance criterion fails 2 consecutive iterations | Upgrade model, retry once (Agent mode only; tmux: same model retry); if still failing → Architecture Escalation (§7¾) → BLOCKED |
 | `cb_threshold` (default: 6) consecutive **fail** verdicts on `cb_threshold` unique criterion IDs | Upgrade to opus, retry once; if still failing → BLOCKED (adjustable via `--cb-threshold`; when `--consensus` is not `off`, effective threshold doubles automatically: default 6 → 12) |
 | max_iter reached | TIMEOUT (report to user) |
+| Same canonical block reason fires `BLOCK_CB_THRESHOLD` (default: 3) times in a row | Mission abort (`.sisyphus/mission-abort.json` + non-zero exit). US-021 R9 P2-I `consecutive_blocks` counter. |
 
 The Leader tracks `consecutive_failures` in `status.json`:
 - Increments on `fail`, resets on `pass`, **unchanged by `request_info`**.
 - "Same error" = same acceptance criterion ID in two consecutive **fail** verdicts (`request_info` does not break or contribute to this chain).
 - "Diverse failures" = `cb_threshold` most recent `fail` verdicts each have a unique criterion ID.
 
+### consecutive_blocks (US-021 R9 P2-I)
+
+`consecutive_failures` only counts `fail` verdicts; a worker that signals `blocked` does not advance it, so a contract defect (e.g., test-spec/PRD mismatch) can repeat silently for many iterations. `consecutive_blocks` closes that hole.
+
+- Counter increments when the **canonical** block reason matches the previous block's reason (`_canonical_block_reason` strips wrapper prefixes like `hygiene_violated:` and `wrapped:` before comparison so R8 hygiene wrappers don't fragment the chain).
+- Counter resets to 1 when a *different* canonical reason fires.
+- `infra_failure` category is **exempt** — transient API/tmux/process failures are environment problems, not contract defects, and shouldn't trip the abort.
+- The very first iteration (`ITERATION <= 1`) is **exempt** — mission setup blocks (e.g., missing PRD, init misconfig) shouldn't terminate before the first real attempt.
+- When the counter reaches `BLOCK_CB_THRESHOLD` the runner writes `.sisyphus/mission-abort.json` (`{reason, count, last_reason, threshold, timestamp}`) and exits non-zero so wrappers can chain to the next mission instead of looping.
+
 ## 8½. Self-Verification Feedback Loop
 
 When `--with-self-verification` is enabled, the SV report feeds back into the next brainstorm cycle:

package/src/node/reporting/campaign-reporting.mjs

@@ -165,6 +165,8 @@ export async function generateCampaignReport({
   now = new Date(),
   gitDiffProvider = defaultGitDiffProvider,
   svSummary = 'N/A — --with-self-verification not enabled',
+  blockedReason = null,
+  blockedCategory = null,
 }) {
   await fs.mkdir(path.dirname(reportFile), { recursive: true });
   await versionFile(reportFile, reportVersionPath);
@@ -197,6 +199,8 @@ export async function generateCampaignReport({
     '',
     '## Execution Summary',
     `- Terminal state: ${terminalState}`,
+    ...(blockedReason ? [`- Blocked reason: ${blockedReason}`] : []),
+    ...(blockedCategory ? [`- Blocked category: ${blockedCategory}`] : []),
     `- Iterations run: ${status.iteration ?? 0}`,
     `- Elapsed: ${elapsed}`,
     '',

package/src/node/run.mjs

@@ -21,6 +21,8 @@ const RUN_DEFAULTS = {
   lockWorkerModel: false,
   autonomous: false,
   withSelfVerification: false,
+  laneStrict: false,
+  testDensityStrict: false,
   flywheel: 'off',
   flywheelModel: 'opus',
   flywheelGuard: 'off',
@@ -60,6 +62,8 @@ function buildHelpText() {
     '  --iter-timeout N',
     '  --debug',
     '  --autonomous',
+    '  --lane-strict',
+    '  --test-density-strict',
     '  --with-self-verification',
     '  --flywheel off|on-fail',
     '  --flywheel-model MODEL',
@@ -147,6 +151,14 @@ function parseRunOptions(args, cwd) {
       case '--autonomous':
         options.autonomous = true;
         break;
+      case '--lane-strict':
+        // P1-E lane enforcement opt-in. Default WARN. governance §7¾.
+        options.laneStrict = true;
+        break;
+      case '--test-density-strict':
+        // US-018 R6 P1-F test density enforcement opt-in. Default WARN. governance §7f.
+        options.testDensityStrict = true;
+        break;
       case '--with-self-verification':
         options.withSelfVerification = true;
         break;
@@ -209,7 +221,17 @@ async function runRunCommand(args, deps) {
 
   const slug = args[0];
   const options = parseRunOptions(args.slice(1), deps.cwd);
-  await deps.runCampaign(slug, options);
+  const result = await deps.runCampaign(slug, options);
+  // governance §1f BLOCKED Surfacing: surface the blocked reason on stderr so
+  // the operator (or wrapper script) does not have to grep memo files.
+  if (result && result.status === 'blocked') {
+    // P1-D 4-channel surfacing: include category so wrappers can see
+    // reason_category alongside the textual reason without parsing JSON.
+    const reason = result.reason ? ` — ${result.reason}` : '';
+    const cat = result.category ? `, category=${result.category}` : '';
+    write(deps.stderr, `Campaign BLOCKED for ${slug} (US=${result.usId}${cat})${reason}`);
+    return 2;
+  }
   write(deps.stdout, `Campaign started for ${slug}`);
   return 0;
 }

package/src/node/runner/campaign-main-loop.mjs

@@ -64,6 +64,7 @@ function buildPaths(rootDir, slug) {
     flywheelSignalFile: path.join(deskRoot, 'memos', `${slug}-flywheel-signal.json`),
     flywheelGuardPromptFile: path.join(deskRoot, 'prompts', `${slug}.flywheel-guard.prompt.md`),
     flywheelGuardVerdictFile: path.join(deskRoot, 'memos', `${slug}-flywheel-guard-verdict.json`),
+    laneAuditFile: path.join(campaignLogDir, 'lane-audit.json'),
 };
 }
 
@@ -253,6 +254,10 @@ async function readCurrentState(paths, slug, options) {
     final_verifier_model: status.final_verifier_model ?? options.finalVerifierModel ?? 'opus',
     verified_us: status.verified_us ?? [],
     consecutive_failures: status.consecutive_failures ?? 0,
+    // US-021 R9 P2-I consecutive_blocks counter (governance §8). Tracks repeated
+    // same-canonical-reason worker blocks; verify_fail uses consecutive_failures.
+    consecutive_blocks: status.consecutive_blocks ?? 0,
+    last_block_reason: status.last_block_reason ?? '',
     current_us: status.current_us ?? null,
     session_name: status.session_name ?? null,
     leader_pane_id: status.leader_pane_id ?? null,
@@ -334,9 +339,171 @@ async function dispatchVerifier({
   return promptFile;
 }
 
-async function writeSentinel(filePath, status, usId) {
-  const content = `${status.toUpperCase()}: ${usId}\n`;
-  await fs.writeFile(filePath, content, 'utf8');
+// P1-E Lane Enforcement (governance §7e). WARN-only by default; opt-in
+// strict escalates lane violations to BLOCKED with downgraded action
+// (recoverable=true, retry_after_fix). audit log file is initialized to
+// `[]` so the file always exists, simplifying wrapper polling.
+async function _initLaneAuditLog(paths) {
+  await fs.mkdir(path.dirname(paths.laneAuditFile), { recursive: true });
+  if (!(await exists(paths.laneAuditFile))) {
+    await fs.writeFile(paths.laneAuditFile, '[]\n', 'utf8');
+  }
+}
+
+// US-020 R8 P1-H Blocked exit hygiene (governance §1f, 5th channel).
+// Worker must update memory.md (Blocking History) and latest.md (Known Issues)
+// before signalling blocked. We compare mtimes against `now`; either file older
+// than 5 minutes means the worker skipped the hygiene step. Returns true when violated.
+async function _checkBlockedHygiene(paths, now = Date.now()) {
+  const threshold = 5 * 60 * 1000; // 5 minutes
+  const targets = [paths.memoryFile, paths.contextFile].filter(Boolean);
+  for (const file of targets) {
+    try {
+      const stat = await fs.stat(file);
+      if (now - stat.mtimeMs > threshold) {
+        return true;
+      }
+    } catch {
+      // Missing file counts as violated — worker had nothing to update.
+      return true;
+    }
+  }
+  return false;
+}
+
+async function _snapshotLaneMtimes(paths) {
+  // PRD / test-spec are read-only artifacts the worker MUST NOT modify.
+  // memos and context are leader-owned; worker writes them via signal
+  // files only, never by direct edit.
+  const targets = [paths.prdFile, paths.testSpecFile, paths.contextFile];
+  const snapshot = {};
+  for (const file of targets) {
+    try {
+      const stat = await fs.stat(file);
+      snapshot[file] = stat.mtimeMs;
+    } catch {
+      snapshot[file] = null;
+    }
+  }
+  return snapshot;
+}
+
+async function _checkLaneViolations(paths, snapshotBefore, snapshotAfter, state, options) {
+  const violations = [];
+  for (const [file, before] of Object.entries(snapshotBefore)) {
+    const after = snapshotAfter[file];
+    if (before !== null && after !== null && after !== before) {
+      violations.push({
+        file,
+        mtime_before: before,
+        mtime_after: after,
+        iter: state.iteration ?? 0,
+        lane_mode: options.laneStrict ? 'strict' : 'warn',
+      });
+    }
+  }
+  if (violations.length === 0) return null;
+  // Append to audit log (best-effort).
+  try {
+    const existing = JSON.parse(await fs.readFile(paths.laneAuditFile, 'utf8'));
+    await fs.writeFile(paths.laneAuditFile, `${JSON.stringify([...existing, ...violations], null, 2)}\n`, 'utf8');
+  } catch {
+    // log file corrupted or missing — re-initialize and write fresh entries.
+    await fs.writeFile(paths.laneAuditFile, `${JSON.stringify(violations, null, 2)}\n`, 'utf8');
+  }
+  return violations;
+}
+
+// P1-D Cross-US dependency token list (governance §1f). Keep in sync with
+// the zsh helper _classify_cross_us_or_metric in lib_ralph_desk.zsh.
+const CROSS_US_TOKEN_RE = /depends on US-|blocking US-|awaits US-|post-iter US-|requires US-\d+|cross-US|US-\d+ 산출물|신규 US-|post-iter/i;
+
+// P1-D Failure Taxonomy classifier. governance §1f locks the 6 reason_category
+// values + recoverable + suggested_action defaults per source. wrapper MUST
+// branch on reason_category; failure_category is diagnostic only.
+function _classifyBlock(source, { verdict, state, slug } = {}) {
+  let category;
+  let recoverable;
+  let action;
+  let failureCategory = null;
+  switch (source) {
+    case 'flywheel_inconclusive':
+    case 'flywheel_exhausted':
+      category = 'mission_abort';
+      recoverable = false;
+      action = 'terminal_alert';
+      break;
+    case 'model_upgrade':
+      category = 'repeat_axis';
+      recoverable = false;
+      action = 'next_mission_chain';
+      break;
+    case 'verifier': {
+      const text = `${verdict?.reason ?? ''} ${verdict?.summary ?? ''}`;
+      category = CROSS_US_TOKEN_RE.test(text) ? 'cross_us_dep' : 'metric_failure';
+      recoverable = true;
+      action = 'retry_after_fix';
+      failureCategory = verdict?.failure_category ?? null;
+      break;
+    }
+    default:
+      category = 'metric_failure';
+      recoverable = false;
+      action = 'terminal_alert';
+  }
+  return {
+    reason_category: category,
+    failure_category: failureCategory,
+    recoverable,
+    suggested_action: action,
+    iteration: state?.iteration ?? 0,
+    slug,
+  };
+}
+
+async function writeSentinel(filePath, status, usId, reason, classification = null, paths = null) {
+  // governance §1f BLOCKED Surfacing: BLOCKED is surfaced on FIVE channels —
+  // sentinel (markdown + JSON sidecar), status, console (stderr), report,
+  // and (US-020 R8 P1-H, 5th channel) memory.md/latest.md hygiene update.
+  // Legacy 1-line parsers still work because line 1 is unchanged.
+  const lines = [`${status.toUpperCase()}: ${usId}`];
+  if (reason) lines.push(`Reason: ${reason}`);
+  if (classification?.reason_category) {
+    lines.push(`Category: ${classification.reason_category}`);
+  }
+
+  // P1-D Write Order Contract:
+  //   1. JSON sidecar FIRST (atomic per-file rename via writeFile).
+  //   2. markdown sentinel SECOND.
+  // Invariant: markdown exists ⇒ JSON exists. Wrappers watch markdown,
+  // then read JSON; if JSON not yet visible (rare race), retry up to 5×50ms.
+  if (status === 'blocked' && classification) {
+    const jsonPath = filePath.replace(/\.md$/, '.json');
+    let hygieneViolated = false;
+    if (paths) {
+      try {
+        hygieneViolated = await _checkBlockedHygiene(paths);
+      } catch {
+        hygieneViolated = false;
+      }
+    }
+    const jsonBody = {
+      schema_version: '2.0',
+      slug: classification.slug ?? null,
+      us_id: usId,
+      blocked_at_iter: classification.iteration ?? 0,
+      blocked_at_utc: new Date().toISOString(),
+      reason_category: classification.reason_category,
+      reason_detail: reason ?? null,
+      failure_category: classification.failure_category ?? null,
+      recoverable: classification.recoverable ?? false,
+      suggested_action: classification.suggested_action ?? 'terminal_alert',
+      meta: { blocked_hygiene_violated: hygieneViolated },
+    };
+    await fs.writeFile(jsonPath, `${JSON.stringify(jsonBody, null, 2)}\n`, 'utf8');
+  }
+
+  await fs.writeFile(filePath, `${lines.join('\n')}\n`, 'utf8');
 }
 
 async function runFinalSequentialVerify({
@@ -456,6 +623,9 @@ export async function run(slug, options = {}) {
     analyticsFile: paths.analyticsFile,
     statusFile: paths.statusFile,
   });
+  // P1-E Lane Enforcement: initialize audit log to `[]` so the file always
+  // exists. Wrappers can then poll/tail without ENOENT special-cases.
+  await _initLaneAuditLog(paths);
 
   if (await exists(paths.blockedSentinel)) {
     throw new Error(`Campaign ${slug} is blocked. Run clean first.`);
@@ -495,7 +665,49 @@ export async function run(slug, options = {}) {
 
   let fixContractPath = null;
 
+  // P1-E Lane Enforcement: snapshot lane mtimes before each iteration,
+  // compare at the top of the next iteration. Drift on read-only artifacts
+  // (PRD, test-spec, context) emits a lane_violation_warning event + audit
+  // log entry. governance §7e. Strict mode escalation hook is wired below
+  // (sentinel BLOCKED with infra_failure + recoverable=true downgrade).
+  let _laneSnapshot = await _snapshotLaneMtimes(paths);
+
   while (state.iteration <= maxIterations) {
+    // Audit drift from the prior iteration before doing anything new.
+    const _laneSnapshotAfter = await _snapshotLaneMtimes(paths);
+    const _laneViolations = await _checkLaneViolations(paths, _laneSnapshot, _laneSnapshotAfter, state, options);
+    if (_laneViolations) {
+      for (const v of _laneViolations) {
+        await appendIterationAnalytics(paths, state, state.current_us ?? 'ALL', 'lane_violation_warning', { ...options, lane_violation: v });
+      }
+      if (options.laneStrict) {
+        // Strict mode: escalate to BLOCKED with downgrade
+        // (recoverable=true, retry_after_fix). governance §7e justifies
+        // the downgrade — the mtime audit is best-effort and should not
+        // terminally kill a campaign.
+        state.phase = 'blocked';
+        const laneReason = `lane_violation: ${_laneViolations.length} read-only artifact(s) modified during prior iteration`;
+        const laneClassification = {
+          reason_category: 'infra_failure',
+          failure_category: null,
+          recoverable: true,
+          suggested_action: 'retry_after_fix',
+          iteration: state.iteration,
+          slug,
+        };
+        await writeSentinel(paths.blockedSentinel, 'blocked', state.current_us ?? 'ALL', laneReason, laneClassification, paths);
+        await writeStatus(paths, state, options.onStatusChange, options.now);
+        return {
+          status: 'blocked',
+          usId: state.current_us ?? 'ALL',
+          reason: laneReason,
+          category: 'infra_failure',
+          statusFile: paths.statusFile,
+        };
+      }
+    }
+    _laneSnapshot = _laneSnapshotAfter;
+
     state.current_us = getNextUs(usList, state.verified_us, state.current_us);
     if (state.current_us === 'ALL') {
       const finalResult = await runFinalSequentialVerify({
@@ -575,6 +787,11 @@ export async function run(slug, options = {}) {
       });
 
       state.last_flywheel_decision = flywheelSignal.decision;
+      // P0-A multi-mission orchestration: optionally captured from flywheel signal.
+      // null when the flywheel did not suggest a next mission. Consumer wrappers
+      // poll status.next_mission_candidate to chain missions without code edits.
+      // See docs/multi-mission-orchestration.md.
+      state.next_mission_candidate = flywheelSignal.next_mission_candidate ?? null;
       await fs.unlink(paths.flywheelSignalFile).catch(() => {});
 
       // Flywheel Guard (independent validation of flywheel decision)
@@ -601,12 +818,28 @@ export async function run(slug, options = {}) {
 
         if (guardVerdict.verdict === 'inconclusive') {
           state.phase = 'blocked';
-          await writeSentinel(paths.blockedSentinel, 'blocked', state.current_us);
+          const guardReason = 'flywheel-guard-escalate-inconclusive';
+          await writeSentinel(paths.blockedSentinel, 'blocked', state.current_us, guardReason, _classifyBlock('flywheel_inconclusive', { state, slug }), paths);
           await writeStatus(paths, state, options.onStatusChange, options.now);
+          // governance §1f three-channel: sentinel + report + return value all
+          // carry the same blocked reason. SV is intentionally not generated
+          // here because the guard fires before the iteration runs to
+          // completion; the campaign report uses the default SV message.
+          await generateCampaignReport({
+            slug,
+            reportFile: paths.reportFile,
+            prdFile: paths.prdFile,
+            statusFile: paths.statusFile,
+            analyticsFile: paths.analyticsFile,
+            now: resolveNow(options.now),
+            blockedReason: guardReason,
+            blockedCategory: 'mission_abort',
+          });
           return {
             status: 'blocked',
             usId: state.current_us,
-            reason: 'flywheel-guard-escalate-inconclusive',
+            reason: guardReason,
+            category: 'mission_abort',
             guardIssues: guardVerdict.issues,
             statusFile: paths.statusFile,
           };
@@ -615,12 +848,25 @@ export async function run(slug, options = {}) {
         if (guardVerdict.verdict === 'fail') {
           if (state.flywheel_guard_count[state.current_us] >= 3) {
             state.phase = 'blocked';
-            await writeSentinel(paths.blockedSentinel, 'blocked', state.current_us);
+            const exhaustReason = 'flywheel-guard-retries-exhausted';
+            await writeSentinel(paths.blockedSentinel, 'blocked', state.current_us, exhaustReason, _classifyBlock('flywheel_exhausted', { state, slug }), paths);
             await writeStatus(paths, state, options.onStatusChange, options.now);
+            // governance §1f three-channel: see comment above.
+            await generateCampaignReport({
+              slug,
+              reportFile: paths.reportFile,
+              prdFile: paths.prdFile,
+              statusFile: paths.statusFile,
+              analyticsFile: paths.analyticsFile,
+              now: resolveNow(options.now),
+              blockedReason: exhaustReason,
+              blockedCategory: 'mission_abort',
+            });
             return {
               status: 'blocked',
               usId: state.current_us,
-              reason: 'flywheel-guard-retries-exhausted',
+              reason: exhaustReason,
+              category: 'mission_abort',
               guardIssues: guardVerdict.issues,
               statusFile: paths.statusFile,
             };
@@ -679,6 +925,24 @@ export async function run(slug, options = {}) {
       }
     }
 
+    // US-019 R7 P1-G: verify_partial malformed downgrade.
+    // verify_partial requires verified_acs[] to be a non-empty array. Otherwise the verifier
+    // has nothing to evaluate and we must treat the signal as broken contract → blocked.
+    if (signal && signal.status === 'verify_partial') {
+      const acs = Array.isArray(signal.verified_acs) ? signal.verified_acs : null;
+      if (!acs || acs.length === 0) {
+        const malformedUs = signal.us_id ?? state.current_us;
+        const malformedClassification = {
+          reason_category: 'mission_abort',
+          recoverable: true,
+          suggested_action: 'retry_after_fix',
+          failure_category: 'spec',
+        };
+        await writeSentinel(paths.blockedSentinel, 'blocked', malformedUs, 'verify_partial_malformed', malformedClassification, paths);
+        return { status: 'blocked', usId: malformedUs, reason: 'verify_partial_malformed', category: 'mission_abort' };
+      }
+    }
+
     const usId = signal.us_id ?? state.current_us;
     const verifierModel = deriveVerifierModel(usId, options);
     state.phase = 'verifier';
@@ -720,7 +984,9 @@ export async function run(slug, options = {}) {
 
     if (verdict.verdict === 'blocked') {
       state.phase = 'blocked';
-      await writeSentinel(paths.blockedSentinel, 'blocked', usId);
+      const blockedReason = verdict.reason || verdict.summary || 'verifier-blocked';
+      const blockedClassification = _classifyBlock('verifier', { verdict, state, slug });
+      await writeSentinel(paths.blockedSentinel, 'blocked', usId, blockedReason, blockedClassification, paths);
       await appendIterationAnalytics(paths, state, usId, 'blocked', options);
       await writeStatus(paths, state, options.onStatusChange, options.now);
       let svSummary;
@@ -747,10 +1013,14 @@ export async function run(slug, options = {}) {
         analyticsFile: paths.analyticsFile,
         now: resolveNow(options.now),
         svSummary,
+        blockedReason,
+        blockedCategory: blockedClassification.reason_category,
       });
       return {
         status: 'blocked',
         usId,
+        reason: blockedReason,
+        category: blockedClassification.reason_category,
         statusFile: paths.statusFile,
       };
     }
@@ -760,7 +1030,8 @@ export async function run(slug, options = {}) {
     const upgradedModel = nextWorkerModel(options.workerModel ?? state.worker_model, state.consecutive_failures);
     if (upgradedModel === 'BLOCKED') {
       state.phase = 'blocked';
-      await writeSentinel(paths.blockedSentinel, 'blocked', usId);
+      const upgradeReason = `model-upgrade-exhausted (worker_model=${state.worker_model}, consecutive_failures=${state.consecutive_failures})`;
+      await writeSentinel(paths.blockedSentinel, 'blocked', usId, upgradeReason, _classifyBlock('model_upgrade', { state, slug }), paths);
       await writeStatus(paths, state, options.onStatusChange, options.now);
       let svSummary;
       if (options.withSelfVerification) {
@@ -786,10 +1057,14 @@ export async function run(slug, options = {}) {
         analyticsFile: paths.analyticsFile,
         now: resolveNow(options.now),
         svSummary,
+        blockedReason: upgradeReason,
+        blockedCategory: 'repeat_axis',
       });
       return {
         status: 'blocked',
         usId,
+        reason: upgradeReason,
+        category: 'repeat_axis',
         statusFile: paths.statusFile,
       };
     }