scrumrun 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+## 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.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

@@ -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/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.0",
   "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.