scrumrun 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+## 2.5.0 - 2026-07-23
+
+### Added
+
+- `sc plan run --normalize-legacy [--dry-run]` collapses malformed Run ledgers (invalid `type`, unknown evidence `kind`, missing snapshot invariant, unparseable `task` reference, empty ledger) into a single valid `snapshot` event that preserves the fact of the Run without inventing transitions. Byte-exact originals are moved to `.scrumrun/.migration-backup/runs/RUN-NNN.md` (numbered suffix if a backup already exists). Coherent with ADR-021: ambiguous history becomes evidence, never invented state.
+- Invariant **I-24**: canonical Runs must pass ledger validation. Hand-written Runs surface as a `high` `RUN_WRITE_BYPASS` finding in `doctor --strict`, with a pointer to the recovery command.
+- New module `lib/commands/normalize-legacy` exposes `normalizeLegacyRuns`, `analyze`, `apply`, `renderReport`, `needsNormalization`, and `scanRuns` for library consumers.
+- CORE and the shared SKILL now open with a hard instruction: **never write Run events by hand**. Only the CLI mutates `runs/*.md`. Direct writes produce invalid vocabulary and break conformance; if the CLI does not expose the shape you need, propose a spec change instead of inventing.
+
+### Changed
+
+- Manifest declares `--normalize-legacy` and `--dry-run` on `sc plan run`.
+- SPEC.md conformance range extended to `I-01 through I-24`.
+- Test suite grew from 184 to 192 passing.
+
+## 2.4.1 - 2026-07-23
+
+### Added
+
+- `sc plan intake` now renders a **pretty terminal layout** in interactive TTYs: a boxed intake pipeline with streaming stages, aligned Classification / Why / Risk / Deferred-guardrails fields, and a highlighted approval-command box that mirrors the LP replay. Zero-dep — pure ANSI + Unicode. Falls back automatically to the existing Markdown summary when stdout is piped, `NO_COLOR` is set, or `--plain` is passed. `--json` returns the full structured plan for automation.
+- New module `lib/commands/pretty-intake` exposes `canRenderPretty`, `renderIntake`, and `renderIntakePlain` for library consumers.
+
+### Changed
+
+- Manifest declares `--plain` and `--json` on `sc plan intake`.
+- Test suite grew from 177 to 184 passing (added contract tests for TTY detection, `NO_COLOR` / `FORCE_COLOR` overrides, backwards-compatible plain output, and blocked-plan rendering).
+
 ## 2.4.0 - 2026-07-23
 
 ### Added

package/CORE.md

@@ -84,6 +84,8 @@ AGENTS.md
 
 **Before querying project state, read `.scrumrun/method.json`.** Its `paths` block is the authoritative index of every canonical location in this project. Navigate by that index; if a path is not declared there, it is not canonical truth. Directory listing and grep are fallbacks — never the first step. A ScrumRun-aware agent must never search for `goals/`, `backlog.md`, `sprint.md`, or any legacy layout: those are absent by design once migration completes and are surfaced only through `.scrumrun/.migration-backup/`.
 
+**Never write Run events by hand.** Runs are only mutated through the CLI: `sc plan run --validate | --learn | --complete | --resume | --fail | --block | --satisfy-guardrail | --authorize-mutation | --record-mutation`. Editing `runs/RUN-NNN.md` directly bypasses schema validation, produces invalid ledger events (invalid `type`, unknown evidence `kind`, missing snapshot, wrong `from`), and breaks conformance for the entire project. If the CLI does not expose the shape you need, propose a spec change through an ADR — do not invent event vocabulary. Existing hand-written Runs can be recovered with `sc plan run --normalize-legacy` (byte-exact original preserved in `.scrumrun/.migration-backup/runs/`).
+
 Canonical truth is Markdown. SQLite/cache data stores only rebuildable indexes, symbol projections, relations, and bounded context packages. Deleting `.cache/` must never delete authored truth.
 
 `state.md` and the semantic index use two-tier freshness checks. Matching path/stat watch fingerprints avoid rereading unchanged sources; any metadata drift falls back to complete content hashing. A cache schema mismatch rebuilds the disposable index once. Watch metadata is only an optimization and never authority.

package/README.md

@@ -4,7 +4,7 @@
 
 ScrumRun gives an agent a small command surface and a precise project memory: what should be done, how each attempt happened, which decisions constrain the code, and why the architecture exists in its current form.
 
-**Package:** `2.4.0` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+**Package:** `2.5.0` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
 
 **New here?** Read the [Quickstart](docs/QUICKSTART.md) — first Run in under 10 minutes, no `SPEC.md` reading required. Full docs map in [`docs/INDEX.md`](docs/INDEX.md).
 

package/SPEC.md

@@ -310,6 +310,7 @@ Legacy sprint entries become Tasks. History entries become Runs only with an evi
 - **I-21** Material mutations are policy-bound, path-scoped, hash-verified, append-only, and fail closed on bypass; unresolved Guardrail obligations block completion.
 - **I-22** The semantic index's declared search backend must match the runtime capabilities of the current Node.js SQLite build; conformance flags a mismatch instead of relying on lazy runtime fallback.
 - **I-23** `method.json` declares the canonical path index for every artifact family so agents navigate by declaration, not by search. Missing or drifted paths fail conformance; grep and directory scans are fallbacks, never the first step.
+- **I-24** Runs are only mutated through the CLI. A canonical Run whose ledger fails validation is a bypass — conformance reports `RUN_WRITE_BYPASS` with a pointer to the recovery command `sc plan run --normalize-legacy`, which collapses the bad ledger into a single `snapshot` event and preserves the byte-exact original under `.scrumrun/.migration-backup/runs/`.
 
 ## 11. Command grammar
 
@@ -327,7 +328,7 @@ Unknown syntax fails deterministically and never guesses a mutation.
 
 An implementation may claim ScrumRun method 2.0.0 only when it:
 
-1. passes positive and negative tests for I-01 through I-23;
+1. passes positive and negative tests for I-01 through I-24;
 2. enforces every exposed state machine and schema;
 3. proves read-only intake and dry-run migration through full-tree fingerprints;
 4. proves migration failure recovery, rollback safety, and vault exclusion;

package/bin/scrumrun.js

@@ -1351,19 +1351,18 @@ function executeRootRoute(route) {
     }
     const request = routeArgs[0] === "--request" ? routeArgs.slice(1).join(" ") : routeArgs.join(" ");
     const plan = planRequest(process.cwd(), request);
-    console.log(`# ScrumRun Intake`);
-    console.log(`State: ${plan.state}`);
-    console.log(`Classification: ${plan.classification.type} (${plan.classification.reason})`);
-    console.log(`Risk: ${plan.risk.level} — ${plan.risk.reasons.join("; ")}`);
-    console.log(`Policy: ${plan.policy.status} (${plan.policy.checked.length} checked; ${plan.policy.deferred.length} deferred)`);
-    for (const violation of plan.policy.violations) console.log(`BLOCKED: ${violation}`);
-    for (const result of plan.policy.evaluations.filter((item) => item.status === "deferred")) {
-      console.log(`DEFERRED: ${result.guardrail} ${result.code}: ${result.message}`);
+    if (routeArgs.includes("--json")) {
+      console.log(JSON.stringify(plan, null, 2));
+      return;
     }
-    for (const warning of plan.context.warnings) console.log(`WARNING: ${warning}`);
-    if (plan.approvalToken) {
-      console.log(`Approval: scrumrun sc plan intake --approve ${plan.approvalToken}`);
+    const { canRenderPretty, renderIntake, renderIntakePlain } = require(path.join(root, "lib", "commands", "pretty-intake"));
+    const forcePlain = routeArgs.includes("--plain");
+    if (!forcePlain && canRenderPretty()) {
+      console.log(renderIntake(plan));
+    } else {
+      console.log(renderIntakePlain(plan));
     }
+    for (const warning of plan.context.warnings) console.log(`WARNING: ${warning}`);
     return;
   }
   if (noun === "plan" && subject === "task" && routeArgs[0] === "--retry") {
@@ -1387,6 +1386,27 @@ function executeRootRoute(route) {
     }
     return;
   }
+  if (noun === "plan" && subject === "run" && routeArgs[0] === "--normalize-legacy") {
+    const { normalizeLegacyRuns, renderReport } = require(path.join(root, "lib", "commands", "normalize-legacy"));
+    const dryRun = routeArgs.includes("--dry-run");
+    const scrumDir = path.join(process.cwd(), ".scrumrun");
+    try {
+      const result = normalizeLegacyRuns(scrumDir, { dryRun });
+      console.log(renderReport(result.plan, result.applied));
+      if (!dryRun && result.applied && result.applied.length) {
+        refreshState(scrumDir);
+        console.log(`\nNormalized ${result.applied.length} Run(s). Byte-exact originals live under .scrumrun/.migration-backup/runs/.`);
+      } else if (dryRun && result.plan.malformed) {
+        console.log(`\nDry-run only. Re-run without --dry-run to apply the plan.`);
+      } else if (!result.plan.malformed) {
+        console.log(`\nEvery Run already conforms to the current ledger schema. Nothing to normalize.`);
+      }
+    } catch (error) {
+      console.error(error.message);
+      process.exitCode = 1;
+    }
+    return;
+  }
   if (noun === "plan" && subject === "run" && routeArgs[0] === "--stats") {
     const { computeStats, renderStats } = require(path.join(root, "lib", "commands", "run-stats"));
     const filters = {

package/docs/QUICKSTART.md

@@ -58,6 +58,12 @@ proposals. Approving is one command:
 npx scrumrun@latest sc plan intake --approve <token>
 ```
 
+In an interactive terminal, the output is rendered as a boxed intake
+pipeline with the exact structure shown on the landing page. Pipe the
+command (`| less`, `> intake.txt`) or set `NO_COLOR=1` to get the plain
+Markdown summary instead; add `--json` for a fully structured payload
+you can feed to CI or a downstream tool.
+
 Only then does a Task and a Run get created.
 
 ## Watching the Run

package/lib/commands/manifest.js

@@ -14,6 +14,7 @@ const nouns = Object.freeze({
         "--show",
         "--render <RUN-NNN>",
         "--stats [--task <TASK-NNN>] [--feature <FEAT-NNN>] [--sprint <SPRINT-NNN>] [--json]",
+        "--normalize-legacy [--dry-run]",
         "--authorize-mutation <RUN-NNN> --path <relative-path>",
         "--record-mutation <RUN-NNN> --permit <MUT-id> [--note] [--actor]",
         "--satisfy-guardrail <RUN-NNN> --guardrail <GR-NNN> [--note] [--evidence] [--review] [--migration] [--actor]",
@@ -24,7 +25,7 @@ const nouns = Object.freeze({
         "--fail [--note] [--evidence] [--risk] [--test] [--actor] [--at]",
         "--block [--note] [--evidence] [--risk] [--actor] [--at]"
       ],
-      intake: ["<request>", "--request", "--approve"],
+      intake: ["<request>", "--request", "--approve", "--plain", "--json"],
       challenge: ["<question>"]
     }
   },

package/lib/commands/normalize-legacy.js

@@ -0,0 +1,214 @@
+"use strict";
+
+// `sc plan run --normalize-legacy [--dry-run]`
+//
+// Reads every Run under `.scrumrun/runs/` and validates its ledger
+// against the current schema. When a Run fails validation (invalid
+// event type, unknown evidence kind, missing snapshot, bad transition,
+// empty ledger, etc.), the whole ledger is collapsed into a single
+// snapshot event that preserves the fact of the Run without inventing
+// transitions. The original body is preserved byte-exact under
+// `.scrumrun/.migration-backup/runs/RUN-NNN.md` (append `.NN` when a
+// backup already exists so history is never overwritten).
+//
+// This is coherent with ADR-021: ambiguous history becomes evidence,
+// never invented transitions.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+const { parseRunLedger, validateRunLedger, renderRunEvent } = require("../runtime/run-ledger");
+const { RUN_LEDGER_VERSION } = require("../v2/schema");
+
+const RUN_FILENAME_PATTERN = /^RUN-\d{3,}\.md$/;
+const TASK_REF_PATTERN = /^TASK-\d{3,}$/;
+
+function readFrontmatterAndBody(text) {
+  const match = String(text || "").match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) return { frontmatter: {}, header: "", body: String(text || "") };
+  const header = match[1];
+  const body = match[2] || "";
+  const frontmatter = {};
+  for (const line of header.split(/\r?\n/)) {
+    const kv = line.match(/^([a-z_][a-z0-9_]*):\s*(.*)$/i);
+    if (!kv) continue;
+    let value = kv[2].trim();
+    if (value === "null" || value === "") value = null;
+    else if (/^-?\d+$/.test(value)) value = Number(value);
+    frontmatter[kv[1]] = value;
+  }
+  return { frontmatter, header, body };
+}
+
+function extractTitle(body, fallback) {
+  const match = String(body || "").match(/^# ([^\r\n]+)$/m);
+  return match ? match[1] : fallback;
+}
+
+function serializeFrontmatter(frontmatter) {
+  const lines = Object.entries(frontmatter).map(([key, value]) => {
+    if (value === null || value === undefined) return `${key}: null`;
+    return `${key}: ${value}`;
+  });
+  return `---\n${lines.join("\n")}\n---`;
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function reserveBackupPath(backupDir, runId) {
+  ensureDir(backupDir);
+  const base = path.join(backupDir, `${runId}.md`);
+  if (!fs.existsSync(base)) return base;
+  for (let n = 1; n <= 99; n++) {
+    const candidate = path.join(backupDir, `${runId}.md.${String(n).padStart(2, "0")}`);
+    if (!fs.existsSync(candidate)) return candidate;
+  }
+  throw new Error(`Cannot reserve backup slot for ${runId}: 100 backups already exist.`);
+}
+
+function needsNormalization(record, body) {
+  if (!record) return { needs: true, reason: "frontmatter is malformed or missing" };
+  if (typeof record.task === "string" && record.task && !TASK_REF_PATTERN.test(record.task)) {
+    return { needs: true, reason: `task field does not match TASK-NNN (was ${JSON.stringify(record.task)})` };
+  }
+  const result = validateRunLedger(record, body);
+  const errors = result.errors || [];
+  if (errors.length) return { needs: true, reason: `ledger validation failed (${errors.length} error${errors.length === 1 ? "" : "s"})`, errors };
+  return { needs: false };
+}
+
+function buildNormalizedBody({ record, originalBody, backupRelative, reason, errors }) {
+  const title = extractTitle(originalBody, `Run ${record.id}`);
+  const sha = crypto.createHash("sha256").update(originalBody).digest("hex");
+  const normalizedRecord = {
+    id: record.id,
+    kind: "run",
+    status: record.status || "partial",
+    created: record.created,
+    updated: new Date().toISOString().slice(0, 10),
+    method: "2.0.0",
+    task: TASK_REF_PATTERN.test(record.task || "") ? record.task : null,
+    sprint: record.sprint || null,
+    attempt: record.attempt || 1,
+    ledger: RUN_LEDGER_VERSION
+  };
+  const evidence = [
+    { kind: "legacy", ref: backupRelative, summary: `byte-exact original preserved (sha256:${sha.slice(0, 12)}…)` },
+    { kind: "note", summary: reason }
+  ];
+  if (errors && errors.length) {
+    const sampled = errors.slice(0, 5).map((error) => `- ${error}`).join("; ");
+    evidence.push({ kind: "note", summary: `Pre-normalization validation errors: ${sampled}${errors.length > 5 ? `; +${errors.length - 5} more` : ""}` });
+  }
+  const event = {
+    schema: RUN_LEDGER_VERSION,
+    id: `${record.id}-EVT-001`,
+    sequence: 1,
+    type: "snapshot",
+    occurred_at: `${normalizedRecord.created || normalizedRecord.updated}T00:00:00.000Z`,
+    timestamp_precision: "date",
+    actor: "migration",
+    from: null,
+    to: normalizedRecord.status,
+    reason: `Legacy Run ledger normalized to preserve history without inventing canonical transitions. See ${backupRelative}.`,
+    evidence
+  };
+  const front = serializeFrontmatter(normalizedRecord);
+  const bodyText = `# ${title}\n\n## Events\n\n${renderRunEvent(event)}\n`;
+  return `${front}\n\n${bodyText}`;
+}
+
+function scanRuns(scrumDir) {
+  const runsDir = path.join(scrumDir, "runs");
+  if (!fs.existsSync(runsDir) || !fs.lstatSync(runsDir).isDirectory()) return [];
+  return fs
+    .readdirSync(runsDir)
+    .filter((name) => RUN_FILENAME_PATTERN.test(name))
+    .sort()
+    .map((name) => path.join(runsDir, name));
+}
+
+function analyze(scrumDir) {
+  const plan = { runs: [], safe: 0, malformed: 0 };
+  for (const file of scanRuns(scrumDir)) {
+    const raw = fs.readFileSync(file, "utf8");
+    const { frontmatter } = readFrontmatterAndBody(raw);
+    const check = needsNormalization(frontmatter, raw);
+    plan.runs.push({ id: frontmatter.id || path.basename(file, ".md"), file, needs: check.needs, reason: check.reason || "ledger validates", errors: check.errors || [] });
+    if (check.needs) plan.malformed += 1;
+    else plan.safe += 1;
+  }
+  return plan;
+}
+
+function apply(scrumDir, plan) {
+  const backupDir = path.join(scrumDir, ".migration-backup", "runs");
+  const applied = [];
+  for (const entry of plan.runs) {
+    if (!entry.needs) continue;
+    const raw = fs.readFileSync(entry.file, "utf8");
+    const { frontmatter } = readFrontmatterAndBody(raw);
+    const backupPath = reserveBackupPath(backupDir, entry.id);
+    fs.writeFileSync(backupPath, raw);
+    const backupRelative = path.relative(scrumDir, backupPath);
+    const normalized = buildNormalizedBody({
+      record: frontmatter,
+      originalBody: raw,
+      backupRelative,
+      reason: entry.reason,
+      errors: entry.errors
+    });
+    fs.writeFileSync(entry.file, normalized);
+    applied.push({ id: entry.id, backup: backupRelative, reason: entry.reason });
+  }
+  return applied;
+}
+
+function renderReport(plan, applied) {
+  const lines = [];
+  lines.push("## Run ledger normalization plan");
+  lines.push("");
+  lines.push(`Runs scanned:      ${plan.runs.length}`);
+  lines.push(`Already valid:     ${plan.safe}`);
+  lines.push(`Needs normalize:   ${plan.malformed}`);
+  if (plan.malformed) {
+    lines.push("");
+    lines.push("Malformed Runs:");
+    for (const entry of plan.runs) {
+      if (!entry.needs) continue;
+      lines.push(`  - ${entry.id}: ${entry.reason}`);
+    }
+  }
+  if (applied) {
+    lines.push("");
+    lines.push("Applied:");
+    if (!applied.length) lines.push("  (no changes)");
+    for (const entry of applied) {
+      lines.push(`  - ${entry.id} → normalized (backup ${entry.backup})`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function normalizeLegacyRuns(scrumDir, { dryRun = false } = {}) {
+  if (!fs.existsSync(scrumDir) || !fs.lstatSync(scrumDir).isDirectory()) {
+    throw new Error(".scrumrun/ not found; run this inside a ScrumRun project.");
+  }
+  const plan = analyze(scrumDir);
+  if (dryRun) return { plan, applied: null };
+  const applied = apply(scrumDir, plan);
+  return { plan, applied };
+}
+
+module.exports = {
+  normalizeLegacyRuns,
+  analyze,
+  apply,
+  renderReport,
+  buildNormalizedBody,
+  needsNormalization,
+  scanRuns
+};

package/lib/commands/pretty-intake.js

@@ -0,0 +1,272 @@
+"use strict";
+
+// Pretty terminal renderer for `sc plan intake` and related outputs.
+// Zero-dep: pure ANSI escapes plus Unicode box drawing. Automatically
+// falls back to a plain, machine-friendly format when the environment
+// is not an interactive TTY (piped, redirected, NO_COLOR, --json, ...).
+//
+// Contract:
+//   canRenderPretty(stream?) -> boolean
+//   renderIntake(plan)       -> string   (pretty; assumes canRenderPretty)
+//   renderIntakePlain(plan)  -> string   (existing Markdown-style summary)
+
+const RESET = "\x1b[0m";
+
+const STYLES = {
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  underline: "\x1b[4m"
+};
+
+const FG = {
+  black: "\x1b[30m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+  white: "\x1b[37m",
+  gray: "\x1b[90m",
+  brightGreen: "\x1b[92m",
+  brightYellow: "\x1b[93m",
+  brightRed: "\x1b[91m",
+  brightCyan: "\x1b[96m"
+};
+
+// Signature acid lime (#c9ff5c) via 24-bit truecolor when available.
+const ACID_FG = "\x1b[38;2;201;255;92m";
+const DIM_ACID_FG = "\x1b[38;2;140;180;60m";
+
+function canRenderPretty(stream = process.stdout) {
+  if (process.env.NO_COLOR) return false;
+  if (process.env.FORCE_COLOR === "0") return false;
+  if (process.env.FORCE_COLOR && Number(process.env.FORCE_COLOR) > 0) return true;
+  return Boolean(stream && stream.isTTY);
+}
+
+function paint(color, text) {
+  return `${color}${text}${RESET}`;
+}
+
+function stripAnsi(text) {
+  return String(text).replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+function visibleLength(text) {
+  return stripAnsi(text).length;
+}
+
+function padEnd(text, width) {
+  const visible = visibleLength(text);
+  if (visible >= width) return text;
+  return text + " ".repeat(width - visible);
+}
+
+function terminalWidth(min = 60, max = 90) {
+  const columns = (process.stdout && process.stdout.columns) || 80;
+  return Math.max(min, Math.min(max, columns - 2));
+}
+
+function wrap(text, width) {
+  if (!text) return [""];
+  const words = String(text).split(/\s+/);
+  const lines = [];
+  let current = "";
+  for (const word of words) {
+    if (!current) {
+      current = word;
+      continue;
+    }
+    if ((current + " " + word).length <= width) {
+      current += " " + word;
+    } else {
+      lines.push(current);
+      current = word;
+    }
+  }
+  if (current) lines.push(current);
+  return lines.length ? lines : [""];
+}
+
+function boxTop(width, title) {
+  const label = ` ${title} `;
+  const remaining = width - visibleLength(label) - 4;
+  const left = "╭─";
+  const right = "─".repeat(Math.max(0, remaining)) + "─╮";
+  return paint(FG.gray, `${left}${paint(ACID_FG, label)}${paint(FG.gray, right)}`);
+}
+
+function boxBottom(width) {
+  return paint(FG.gray, `╰${"─".repeat(width - 2)}╯`);
+}
+
+function boxBlank(width) {
+  return paint(FG.gray, `│`) + " ".repeat(width - 2) + paint(FG.gray, `│`);
+}
+
+function boxLine(width, content) {
+  const paddedInterior = padEnd(content, width - 4);
+  return paint(FG.gray, `│ `) + paddedInterior + paint(FG.gray, ` │`);
+}
+
+const RISK_TONE = {
+  low: FG.brightGreen,
+  medium: FG.brightYellow,
+  high: FG.brightRed
+};
+
+const CLASSIFICATION_ALIAS = {
+  task: "Task",
+  fix: "Task (fix)",
+  sprint: "Sprint",
+  feature: "Feature",
+  backlog: "Backlog Task",
+  knowledge: "Knowledge discovery",
+  reject: "Rejected"
+};
+
+function classificationLabel(classification) {
+  const alias = CLASSIFICATION_ALIAS[classification.type];
+  return alias || classification.type;
+}
+
+function classificationLaneLabel(classification) {
+  const alias = CLASSIFICATION_ALIAS[classification.type];
+  if (alias) return alias.toLowerCase() + " lane";
+  return `${classification.type} lane`;
+}
+
+function pipelineDot(stage, blocked) {
+  const color = blocked && stage === "BLOCKED" ? FG.brightRed : ACID_FG;
+  return paint(color, "●");
+}
+
+function fieldLine(label, value, width, valueColor = FG.white, labelColor = FG.gray) {
+  const labelText = paint(labelColor, padEnd(label.padEnd(15).toUpperCase(), 15));
+  const wrapWidth = Math.max(20, width - 4 - 15 - 2);
+  const lines = wrap(value, wrapWidth);
+  const rendered = [];
+  for (let i = 0; i < lines.length; i++) {
+    const prefix = i === 0 ? labelText : padEnd("", 15);
+    rendered.push(boxLine(width, `${prefix}  ${paint(valueColor, lines[i])}`));
+  }
+  return rendered;
+}
+
+function commandBox(interiorWidth, command) {
+  const inside = ` $ ${command} `;
+  const boxWidth = Math.min(interiorWidth, visibleLength(inside) + 4);
+  const top = paint(DIM_ACID_FG, `┌${"─".repeat(boxWidth - 2)}┐`);
+  const bottom = paint(DIM_ACID_FG, `└${"─".repeat(boxWidth - 2)}┘`);
+  const content = padEnd(inside, boxWidth - 2);
+  const middle = `${paint(DIM_ACID_FG, "│")}${paint(ACID_FG, content)}${paint(DIM_ACID_FG, "│")}`;
+  return [top, middle, bottom];
+}
+
+function pipelineDetail(stage, plan) {
+  if (stage === "POLICY") {
+    return `${plan.policy.checked.length} checked · ${plan.policy.deferred.length} deferred`;
+  }
+  if (stage === "RISK") {
+    return `${plan.risk.level} · ${plan.risk.reasons[0] || ""}`.replace(/·\s*$/, "").trim();
+  }
+  if (stage === "CLASSIFICATION") {
+    return classificationLabel(plan.classification).toLowerCase();
+  }
+  if (stage === "AWAITING_APPROVAL") return "";
+  if (stage === "BLOCKED") return "policy denied — no token issued";
+  return "";
+}
+
+function renderIntake(plan) {
+  const width = terminalWidth();
+  const isBlocked = plan.state === "blocked";
+  const title = `intake pipeline · ${classificationLaneLabel(plan.classification)}`;
+  const lines = [];
+
+  lines.push(boxTop(width, title));
+  lines.push(boxBlank(width));
+
+  // Owner prompt
+  const promptLines = wrap(plan.request, width - 6);
+  for (let i = 0; i < promptLines.length; i++) {
+    const marker = i === 0 ? paint(ACID_FG, "❯ ") : "  ";
+    lines.push(boxLine(width, `  ${marker}${paint(FG.white, promptLines[i])}`));
+  }
+  lines.push(boxBlank(width));
+
+  // Pipeline
+  for (const stage of plan.pipeline) {
+    const upper = stage.toUpperCase();
+    const detail = pipelineDetail(upper, plan);
+    const dot = pipelineDot(upper, isBlocked);
+    const label = paint(isBlocked && upper === "BLOCKED" ? FG.brightRed : FG.white, padEnd(upper, 18));
+    const suffix = detail ? paint(FG.gray, detail) : "";
+    lines.push(boxLine(width, `  ${dot} ${label} ${suffix}`));
+  }
+  lines.push(boxBlank(width));
+
+  // Field summary
+  const classificationText = classificationLabel(plan.classification);
+  lines.push(...fieldLine("Classification", classificationText, width, ACID_FG));
+  lines.push(...fieldLine("Why", plan.classification.reason, width, FG.gray));
+  const riskColor = RISK_TONE[plan.risk.level] || FG.white;
+  lines.push(...fieldLine("Risk", `${plan.risk.level} · ${plan.risk.reasons.join("; ")}`, width, riskColor));
+
+  // Deferred guardrails
+  const deferred = plan.policy.evaluations.filter((entry) => entry.status === "deferred");
+  if (deferred.length) {
+    lines.push(boxBlank(width));
+    lines.push(boxLine(width, `  ${paint(FG.gray, "DEFERRED GUARDRAILS")}`));
+    for (const entry of deferred) {
+      const gr = paint(FG.brightYellow, entry.guardrail);
+      const code = paint(FG.gray, entry.code);
+      const short = entry.message.length > width - 30 ? entry.message.slice(0, width - 33) + "…" : entry.message;
+      lines.push(boxLine(width, `  ${gr} ${code}  ${paint(FG.white, short)}`));
+    }
+  }
+
+  // Approval or blocked
+  lines.push(boxBlank(width));
+  if (isBlocked) {
+    lines.push(boxLine(width, `  ${paint(FG.brightRed, "BLOCKED")} ${paint(FG.gray, "no approval token issued")}`));
+    if (plan.policy.violations && plan.policy.violations.length) {
+      for (const violation of plan.policy.violations) {
+        lines.push(boxLine(width, `  ${paint(FG.brightRed, "!")} ${paint(FG.white, violation)}`));
+      }
+    }
+  } else if (plan.approvalToken) {
+    const command = `scrumrun sc plan intake --approve ${plan.approvalToken}`;
+    const truncated = command.length > width - 8 ? `scrumrun sc plan intake --approve ${plan.approvalToken.slice(0, 20)}…` : command;
+    for (const boxRow of commandBox(width - 6, truncated)) {
+      lines.push(boxLine(width, `  ${boxRow}`));
+    }
+    lines.push(boxBlank(width));
+    lines.push(boxLine(width, `  ${paint(FG.gray, "[ awaiting owner approval ]")}`));
+    if (command.length !== truncated.length) {
+      lines.push(boxLine(width, `  ${paint(FG.gray, "(full token above is truncated for display; copy from --json if needed)")}`));
+    }
+  }
+  lines.push(boxBlank(width));
+  lines.push(boxBottom(width));
+  return lines.join("\n");
+}
+
+function renderIntakePlain(plan) {
+  const lines = [];
+  lines.push("# ScrumRun Intake");
+  lines.push(`State: ${plan.state}`);
+  lines.push(`Classification: ${plan.classification.type} (${plan.classification.reason})`);
+  lines.push(`Risk: ${plan.risk.level} — ${plan.risk.reasons.join("; ")}`);
+  lines.push(`Policy: ${plan.policy.status} (${plan.policy.checked.length} checked; ${plan.policy.deferred.length} deferred)`);
+  for (const violation of plan.policy.violations || []) lines.push(`BLOCKED: ${violation}`);
+  for (const result of plan.policy.evaluations.filter((entry) => entry.status === "deferred")) {
+    lines.push(`DEFERRED: ${result.guardrail} ${result.code}: ${result.message}`);
+  }
+  for (const warning of plan.context.warnings) lines.push(`WARNING: ${warning}`);
+  if (plan.approvalToken) lines.push(`Approval: scrumrun sc plan intake --approve ${plan.approvalToken}`);
+  return lines.join("\n");
+}
+
+module.exports = { canRenderPretty, renderIntake, renderIntakePlain };

package/lib/v2/conformance.js

@@ -38,7 +38,8 @@ const INVARIANTS = Object.freeze([
   { id: "I-20", summary: "learning candidates never block execution", tests: ["post-validation extraction creates candidate insights"] },
   { id: "I-21", summary: "material mutations are scoped, policy-bound, and fail closed", tests: ["Mutation Gateway rejects bypass and out-of-scope writes", "Run completion rejects unresolved Guardrail obligations"] },
   { id: "I-22", summary: "declared search backend matches observed runtime capabilities", tests: ["conformance detects a semantic index that declares fts5 when the runtime does not provide it"] },
-  { id: "I-23", summary: "method.json declares canonical paths so agents navigate by index, not by search", tests: ["method.json path index is present, well-formed, and matches the canonical layout"] }
+  { id: "I-23", summary: "method.json declares canonical paths so agents navigate by index, not by search", tests: ["method.json path index is present, well-formed, and matches the canonical layout"] },
+  { id: "I-24", summary: "every canonical Run passes ledger validation; hand-written events surface as bypass findings", tests: ["conformance flags Run write bypass when the ledger uses invalid vocabulary or misses the snapshot invariant"] }
 ]);
 
 function finding(severity, code, message, file = null) {
@@ -139,7 +140,10 @@ function auditProject(projectRoot) {
     }
     if (run.record && run.record.ledger === RUN_LEDGER_VERSION) {
       const ledger = validateRunLedger(run.record, run.body);
-      for (const error of ledger.errors) findings.push(finding("high", "RUN_LEDGER_INVALID", `${run.record.id}: ${error}`, run.file));
+      if (ledger.errors.length) {
+        findings.push(finding("high", "RUN_WRITE_BYPASS", `${run.record.id}: ledger has ${ledger.errors.length} validation error(s); this Run was likely written without going through the CLI. Recover with \`sc plan run --normalize-legacy --dry-run\` then re-run without --dry-run.`, run.file));
+        for (const error of ledger.errors) findings.push(finding("high", "RUN_LEDGER_INVALID", `${run.record.id}: ${error}`, run.file));
+      }
     } else if (run.record) {
       const declared = methodMarker && methodMarker.schemas && methodMarker.schemas.run_ledger === RUN_LEDGER_VERSION;
       findings.push(finding(declared ? "high" : "warning", "RUN_LEDGER_LEGACY", `${run.record.id} requires the Run ledger ${RUN_LEDGER_VERSION} migration.`, run.file));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scrumrun",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Evidence-driven Agile runtime and semantic project memory for AI coding agents.",
   "bin": {
     "scrumrun": "bin/scrumrun.js",

package/templates/shared/skills/scrumrun/SKILL.md

@@ -36,6 +36,8 @@ Normal hot path:
 5. follow the ids/pointers to only the relevant canonical artifacts;
 6. load `.scrumrun/core.md` when the method contract or an exceptional transition is needed.
 
+**Never write Run events by hand.** Only the CLI mutates `runs/RUN-NNN.md`: `sc plan run --validate | --learn | --complete | --resume | --fail | --block | --satisfy-guardrail | --authorize-mutation | --record-mutation`. Direct edits produce invalid ledger events (unknown `type` like `execution`/`validation`/`learning`, unknown evidence `kind` like `guardrail-check`/`build`/`task-status`, missing snapshot invariant) and break project conformance. If the CLI does not expose the shape you need, propose a spec change instead of inventing vocabulary. Recover hand-written Runs via `sc plan run --normalize-legacy` — originals are preserved byte-exact under `.scrumrun/.migration-backup/runs/`.
+
 Lean mode is a read policy, not an incomplete store. Generated files and `.scrumrun/.cache/` are never authoritative.
 
 Generated state and semantic indexes use a metadata-watch fast path with a full content-hash fallback. Treat cache-schema mismatch as a request to rebuild the disposable projection, never as permission to rewrite canonical Markdown.