scrumrun 2.3.0 → 2.4.1

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+## 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
+
+- `method.json` now carries a canonical `paths` block plus `paths_schema: 1`. The block declares the exact relative location of every artifact family (`guardrails`, `config`, `project`, `core`, `state_view`, `map_view`, `tasks`, `sprints`, `features`, `runs`, `reviews`, `memory.{knowledge,decisions,insights,dossiers}`, `vault_local`, `cache`) so ScrumRun-aware agents navigate by index instead of grep. Powered by a new `lib/v2/paths` module used by init, migration, and conformance so drift is impossible.
+- Invariant **I-23** — *method.json declares canonical paths so agents navigate by index, not by search*. `doctor --strict` flags `METHOD_PATHS_MISSING`, `METHOD_PATHS_DRIFT`, and `METHOD_PATHS_SCHEMA` findings; a `high` severity blocks conformance until `update --migrate` regenerates the block.
+- CORE and the shared SKILL now open with a hard instruction: read `.scrumrun/method.json` **before** any grep, and never search for legacy paths (`goals/`, `backlog.md`, `sprint.md`, `history.md`). Directory listing is a fallback, never a first step.
+
+### Changed
+
+- Migration output writes `method.json` through the shared `renderMethodJson` helper, so v1→v2 migrations backfill the `paths` block automatically.
+- SPEC.md conformance range extended to `I-01 through I-23`.
+- Test suite grew from 170 to 177 passing.
+
 ## 2.3.0 - 2026-07-23
 
 ### Added

package/CORE.md

@@ -82,6 +82,8 @@ AGENTS.md
     contexts/
 ```
 
+**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/`.
+
 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.3.0` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+**Package:** `2.4.1` · **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

@@ -309,6 +309,7 @@ Legacy sprint entries become Tasks. History entries become Runs only with an evi
 - **I-20** Post-validation learning proposes candidates and never blocks Task/Run completion.
 - **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.
 
 ## 11. Command grammar
 
@@ -326,7 +327,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-22;
+1. passes positive and negative tests for I-01 through I-23;
 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") {

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

@@ -24,7 +24,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/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

@@ -13,6 +13,7 @@ const { containsSecret, containsSecretWithAllowlist, loadSecretAllowlist } = req
 const { pendingTransactionStatus } = require("./transaction");
 const { configWeakeningAttempts, validateGuardrailDocument } = require("../runtime/policy-engine");
 const { auditActiveWorkspace } = require("../runtime/mutation-gateway");
+const { canonicalPaths, PATHS_SCHEMA_VERSION } = require("./paths");
 
 const INVARIANTS = Object.freeze([
   { id: "I-01", summary: "pre-approval work is read-only", tests: ["intake builds bounded context without writing"] },
@@ -36,13 +37,32 @@ const INVARIANTS = Object.freeze([
   { id: "I-19", summary: "code intelligence is derived and fingerprinted", tests: ["language adapters are replaceable", "moves remap by fingerprint"] },
   { 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-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"] }
 ]);
 
 function finding(severity, code, message, file = null) {
   return { severity, code, message, ...(file ? { file } : {}) };
 }
 
+function diffPathIndex(expected, actual, prefix = "") {
+  const drift = [];
+  for (const [key, value] of Object.entries(expected)) {
+    const label = prefix ? `${prefix}.${key}` : key;
+    const actualValue = actual && typeof actual === "object" ? actual[key] : undefined;
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      if (!actualValue || typeof actualValue !== "object" || Array.isArray(actualValue)) {
+        drift.push({ label, expected: "<object>", actual: actualValue });
+        continue;
+      }
+      drift.push(...diffPathIndex(value, actualValue, label));
+    } else if (actualValue !== value) {
+      drift.push({ label, expected: value, actual: actualValue });
+    }
+  }
+  return drift;
+}
+
 function auditProject(projectRoot) {
   const scrumDir = path.join(projectRoot, ".scrumrun");
   const findings = [];
@@ -56,6 +76,16 @@ function auditProject(projectRoot) {
     if (!fs.existsSync(marker) || !fs.lstatSync(marker).isFile()) throw new Error("marker is missing, not a regular file, or is a symbolic link");
     methodMarker = JSON.parse(fs.readFileSync(marker, "utf8"));
     if (methodMarker.method !== METHOD_VERSION) findings.push(finding("critical", "METHOD_VERSION", `method.json must declare ${METHOD_VERSION}.`, marker));
+    const expectedPaths = canonicalPaths();
+    if (!methodMarker.paths || typeof methodMarker.paths !== "object" || Array.isArray(methodMarker.paths)) {
+      findings.push(finding("high", "METHOD_PATHS_MISSING", `method.json must declare a canonical "paths" block so agents navigate by declaration, not by search. Run \`npx scrumrun@latest update --migrate\` to backfill.`, marker));
+    } else {
+      const drift = diffPathIndex(expectedPaths, methodMarker.paths);
+      for (const entry of drift) findings.push(finding("high", "METHOD_PATHS_DRIFT", `method.json paths[${entry.label}] is ${entry.actual === undefined ? "missing" : `"${entry.actual}"`}; expected "${entry.expected}". Regenerate via \`update --migrate\`.`, marker));
+      if (methodMarker.paths_schema !== PATHS_SCHEMA_VERSION) {
+        findings.push(finding("warning", "METHOD_PATHS_SCHEMA", `method.json paths_schema is ${methodMarker.paths_schema || "missing"}; expected ${PATHS_SCHEMA_VERSION}.`, marker));
+      }
+    }
   } catch (error) {
     findings.push(finding("critical", "METHOD_MARKER", `method.json is missing or malformed: ${error.message}`, marker));
   }

package/lib/v2/migration.js

@@ -18,6 +18,7 @@ const {
 } = require("./artifacts");
 const { inferEnforcement, normalizeGuardrailDocument } = require("../runtime/policy-engine");
 const { RUN_LEDGER_VERSION } = require("./schema");
+const { renderMethodJson } = require("./paths");
 const { migrateLegacyRun } = require("../runtime/run-ledger");
 
 const MIGRATION_NAME = "v1-to-v2";
@@ -927,13 +928,12 @@ function migrationPlan(projectRoot) {
   }
 
   const sourceLayout = existingIds.size ? "hybrid-v1-v2" : "1.x";
-  generated.set("method.json", `${JSON.stringify({
-    method: METHOD_VERSION,
-    layout: "v2",
+  generated.set("method.json", renderMethodJson({
+    methodVersion: METHOD_VERSION,
     schemas: { run_ledger: RUN_LEDGER_VERSION, guardrails: 1, run_obligations: 1, mutation_gateway: 1 },
-    migrated_from: sourceLayout,
+    migratedFrom: sourceLayout,
     migration: MIGRATION_NAME
-  }, null, 2)}\n`);
+  }));
 
   const counts = {};
   for (const artifact of artifacts) counts[artifact.kind] = (counts[artifact.kind] || 0) + 1;

package/lib/v2/paths.js

@@ -0,0 +1,72 @@
+"use strict";
+
+// Single source of truth for the canonical layout inside `.scrumrun/`.
+//
+// This module powers `method.json.paths` — the machine-readable index a
+// ScrumRun-aware agent must consult BEFORE searching. Any change here
+// must land in the template, the migration generator, and the doctor
+// invariant together so no drift is possible.
+
+const CANONICAL_PATHS = Object.freeze({
+  guardrails: "guardrails.md",
+  config: "config.md",
+  project: "project.md",
+  core: "core.md",
+  state_view: "state.md",
+  map_view: "map.md",
+  tasks: "tasks/",
+  sprints: "sprints/",
+  features: "features/",
+  runs: "runs/",
+  reviews: "reviews/",
+  memory: Object.freeze({
+    knowledge: "memory/knowledge/",
+    decisions: "memory/decisions/",
+    insights: "memory/insights/",
+    dossiers: "memory/dossiers/"
+  }),
+  vault_local: "vault.local.md",
+  cache: ".cache/"
+});
+
+const PATHS_SCHEMA_VERSION = 1;
+
+function clone(value) {
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(clone);
+  const out = {};
+  for (const [key, entry] of Object.entries(value)) out[key] = clone(entry);
+  return out;
+}
+
+function canonicalPaths() {
+  return clone(CANONICAL_PATHS);
+}
+
+function flattenPaths(paths = CANONICAL_PATHS, prefix = "") {
+  const out = [];
+  for (const [key, value] of Object.entries(paths)) {
+    const label = prefix ? `${prefix}.${key}` : key;
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      out.push(...flattenPaths(value, label));
+    } else if (typeof value === "string") {
+      out.push({ label, relative: value });
+    }
+  }
+  return out;
+}
+
+function renderMethodJson({ methodVersion, layout = "v2", schemas = {}, migratedFrom, migration } = {}) {
+  const payload = {
+    method: methodVersion,
+    layout,
+    paths_schema: PATHS_SCHEMA_VERSION,
+    paths: canonicalPaths(),
+    schemas
+  };
+  if (migratedFrom) payload.migrated_from = migratedFrom;
+  if (migration) payload.migration = migration;
+  return `${JSON.stringify(payload, null, 2)}\n`;
+}
+
+module.exports = { CANONICAL_PATHS, PATHS_SCHEMA_VERSION, canonicalPaths, flattenPaths, renderMethodJson };

package/package.json

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

package/templates/project/.scrumrun/method.json

@@ -1,6 +1,28 @@
 {
   "method": "2.0.0",
   "layout": "v2",
+  "paths_schema": 1,
+  "paths": {
+    "guardrails": "guardrails.md",
+    "config": "config.md",
+    "project": "project.md",
+    "core": "core.md",
+    "state_view": "state.md",
+    "map_view": "map.md",
+    "tasks": "tasks/",
+    "sprints": "sprints/",
+    "features": "features/",
+    "runs": "runs/",
+    "reviews": "reviews/",
+    "memory": {
+      "knowledge": "memory/knowledge/",
+      "decisions": "memory/decisions/",
+      "insights": "memory/insights/",
+      "dossiers": "memory/dossiers/"
+    },
+    "vault_local": "vault.local.md",
+    "cache": ".cache/"
+  },
   "schemas": {
     "run_ledger": 1,
     "guardrails": 1,

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

@@ -29,11 +29,12 @@ Apply instructions in this order:
 
 Normal hot path:
 
-1. read `AGENTS.md`;
-2. read `.scrumrun/guardrails.md`;
-3. read `.scrumrun/state.md`;
-4. follow the ids/pointers to only the relevant canonical artifacts;
-5. load `.scrumrun/core.md` when the method contract or an exceptional transition is needed.
+1. read `.scrumrun/method.json` — its `paths` block is the authoritative index of every canonical location; navigate by that index and never grep for legacy paths (`goals/`, `backlog.md`, `sprint.md`, `history.md`);
+2. read `AGENTS.md`;
+3. read `.scrumrun/guardrails.md`;
+4. read `.scrumrun/state.md`;
+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.
 
 Lean mode is a read policy, not an incomplete store. Generated files and `.scrumrun/.cache/` are never authoritative.