scrumrun 1.5.2 → 2.0.0

package/lib/v2/project-store.js

@@ -0,0 +1,44 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { ArtifactRepository, graphFromRecords } = require("./artifacts");
+const { MANIFEST_PATH, migrationPlan } = require("./migration");
+
+const LEGACY_PATHS = [
+  "backlog.md",
+  "fixes.md",
+  "golden-rules.md",
+  "knowledge.md",
+  path.join("goals", "main", "sprint.md"),
+  path.join("goals", "main", "history.md"),
+  path.join("goals", "main", "decisions.md")
+];
+
+function readProjectModel(projectRoot) {
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  if (!fs.existsSync(scrumDir)) throw new Error("Not a ScrumRun project: .scrumrun/ is missing.");
+  const hasV2Marker = fs.existsSync(path.join(scrumDir, "method.json")) || fs.existsSync(path.join(scrumDir, MANIFEST_PATH));
+  const hasLegacy = LEGACY_PATHS.some((relative) => fs.existsSync(path.join(scrumDir, relative)));
+
+  if (hasV2Marker) {
+    const repository = new ArtifactRepository(scrumDir);
+    return {
+      layout: hasLegacy ? "mixed" : "v2",
+      source: "canonical-v2",
+      graph: repository.graph(),
+      warnings: []
+    };
+  }
+
+  const plan = migrationPlan(projectRoot);
+  return {
+    layout: "v1",
+    source: "read-only-v2-projection",
+    graph: graphFromRecords(plan.artifacts.map((artifact) => artifact.record)),
+    warnings: plan.warnings,
+    errors: plan.errors
+  };
+}
+
+module.exports = { LEGACY_PATHS, readProjectModel };

package/lib/v2/schema.js

@@ -0,0 +1,128 @@
+"use strict";
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const nested of Object.values(value)) deepFreeze(nested);
+  return Object.freeze(value);
+}
+
+const METHOD_VERSION = "2.0.0";
+
+const ARTIFACT_TYPES = deepFreeze({
+  feature: {
+    prefix: "FEAT",
+    directory: "features",
+    initial: ["backlog", "proposed"],
+    statuses: ["backlog", "proposed", "active", "completed", "paused", "cancelled"]
+  },
+  task: {
+    prefix: "TASK",
+    directory: "tasks",
+    initial: ["backlog", "proposed", "running"],
+    statuses: ["backlog", "proposed", "running", "validating", "learning", "partial", "completed", "failed", "blocked", "cancelled"]
+  },
+  sprint: {
+    prefix: "SPRINT",
+    directory: "sprints",
+    initial: ["proposed"],
+    statuses: ["proposed", "running", "partial", "completed", "blocked", "cancelled"]
+  },
+  run: {
+    prefix: "RUN",
+    directory: "runs",
+    initial: ["executing"],
+    statuses: ["executing", "validating", "learning", "partial", "completed", "failed", "blocked"]
+  },
+  review: {
+    prefix: "REV",
+    directory: "reviews",
+    initial: ["proposed"],
+    statuses: ["proposed", "running", "passed", "failed", "archived"]
+  },
+  knowledge: {
+    prefix: "K",
+    directory: "memory/knowledge",
+    initial: ["candidate"],
+    statuses: ["candidate", "approved", "rejected", "deprecated", "invalidated"]
+  },
+  decision: {
+    prefix: "DEC",
+    directory: "memory/decisions",
+    initial: ["open"],
+    statuses: ["open", "resolved", "deprecated", "invalidated"]
+  },
+  insight: {
+    prefix: "INS",
+    directory: "memory/insights",
+    initial: ["candidate"],
+    statuses: ["candidate", "confirmed", "stale", "deprecated", "invalidated"]
+  },
+  dossier: {
+    prefix: "DOS",
+    directory: "memory/dossiers",
+    initial: ["active"],
+    statuses: ["active", "stale", "deprecated", "archived"]
+  }
+});
+
+const ARTIFACT_TRANSITIONS = deepFreeze({
+  feature: {
+    backlog: ["proposed", "active", "cancelled"], proposed: ["active", "cancelled"], active: ["paused", "completed", "cancelled"], paused: ["active", "cancelled"]
+  },
+  task: {
+    backlog: ["proposed", "running", "cancelled"], proposed: ["running", "cancelled"], running: ["validating", "failed", "blocked", "cancelled"], validating: ["learning", "failed", "blocked"], learning: ["completed", "failed", "blocked"], partial: ["running", "cancelled"], failed: ["running", "cancelled"], blocked: ["running", "cancelled"]
+  },
+  sprint: {
+    proposed: ["running", "cancelled"], running: ["partial", "completed", "blocked", "cancelled"], partial: ["running", "completed", "cancelled"], blocked: ["running", "cancelled"]
+  },
+  run: {
+    executing: ["validating", "failed", "blocked"], validating: ["learning", "failed", "blocked"], learning: ["completed", "failed", "blocked"], partial: ["executing", "failed", "blocked"], blocked: ["executing", "failed"]
+  },
+  review: { proposed: ["running"], running: ["passed", "failed"], failed: ["running", "archived"], passed: ["archived"] },
+  knowledge: { candidate: ["approved", "rejected"], approved: ["deprecated", "invalidated"], rejected: ["candidate"], deprecated: ["approved"], invalidated: [] },
+  decision: { open: ["resolved", "deprecated", "invalidated"], resolved: ["deprecated", "invalidated"], deprecated: ["open"], invalidated: [] },
+  insight: { candidate: ["confirmed", "invalidated"], confirmed: ["stale", "deprecated", "invalidated"], stale: ["confirmed", "deprecated", "invalidated"], deprecated: ["confirmed"], invalidated: [] },
+  dossier: { active: ["stale", "deprecated", "archived"], stale: ["active", "deprecated", "archived"], deprecated: ["archived"], archived: [] }
+});
+
+const STRUCTURAL_RELATIONS = deepFreeze({
+  feature: { targetKind: "feature", cardinality: "0..1", meaning: "long-lived initiative containing the artifact" },
+  sprint: { targetKind: "sprint", cardinality: "0..1", meaning: "optional delivery batch containing a Task or Run" },
+  task: { targetKind: "task", cardinality: "1 for Run; otherwise 0..1", requiredFor: ["run"], meaning: "atomic work executed or reviewed by the artifact" }
+});
+
+const SCALAR_FIELDS = deepFreeze({
+  attempt: { kinds: ["run"], required: true, type: "positive integer", meaning: "monotonic execution-attempt number within one Task" }
+});
+
+const TRUTH_OWNERSHIP = deepFreeze({
+  feature: { question: "Why does this initiative exist?", truth: "initiative purpose, scope, dependencies, and lifecycle" },
+  task: { question: "What approved atomic outcome is intended?", truth: "scope, acceptance criteria, approval, and intended status" },
+  sprint: { question: "When are related Tasks grouped?", truth: "timebox or delivery-batch membership; never execution history" },
+  run: { question: "How did one execution attempt actually happen?", truth: "append-only execution events, evidence, result, and attempt number" },
+  review: { question: "What independent validation was performed?", truth: "scoped findings, checks, evidence, and verdict" },
+  knowledge: { question: "What verified project fact is reusable?", truth: "approved evidence-backed fact and validity" },
+  decision: { question: "What normative choice constrains future work?", truth: "decision, rationale, validity, and lifecycle" },
+  insight: { question: "Why is something arranged or constrained this way?", truth: "explanatory candidate/confirmed context and evidence" },
+  dossier: { question: "What evidence belongs to one retrieval topic?", truth: "reviewed topic bundle and freshness" }
+});
+
+const AUTHORITY = deepFreeze({
+  semantics: { source: "SPEC.md", scope: "normative meanings and invariants" },
+  schema: { source: "lib/v2/schema.js", scope: "machine-enforced ids, paths, statuses, transitions, relations, and ownership metadata" },
+  commands: { source: "lib/commands/manifest.js", scope: "public command grammar and compatibility routes" },
+  projectPolicy: { source: ".scrumrun/guardrails.md", scope: "owner/project constraints" },
+  projectTruth: { source: ".scrumrun/**/*.md", scope: "authored canonical project records" },
+  projections: { source: ".scrumrun/state.md, .scrumrun/map.md, .scrumrun/.cache/", scope: "disposable derived views; never authority" }
+});
+
+module.exports = {
+  ARTIFACT_TRANSITIONS,
+  ARTIFACT_TYPES,
+  AUTHORITY,
+  METHOD_VERSION,
+  SCALAR_FIELDS,
+  STRUCTURAL_RELATIONS,
+  TRUTH_OWNERSHIP,
+  deepFreeze
+};

package/package.json

@@ -1,21 +1,30 @@
 {
   "name": "scrumrun",
-  "version": "1.5.2",
-  "description": "ScrumRun: portable sprint-driven AI workflow for real software projects.",
+  "version": "2.0.0",
+  "description": "Evidence-driven Agile runtime and semantic project memory for AI coding agents.",
   "bin": {
     "scrumrun": "bin/scrumrun.js",
     "sr-claude": "bin/claude-install.js"
   },
   "files": [
     "bin",
+    "lib",
+    "scripts",
     "templates",
     "CORE.md",
     "SPEC.md",
     "DECISIONS.md",
-    "README.md"
+    "README.md",
+    "MIGRATION-1-to-2.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "docs"
   ],
   "scripts": {
-    "test": "node --test tests/*.test.js"
+    "docs:contract": "node scripts/generate-contract-docs.js",
+    "check:contract": "node scripts/generate-contract-docs.js --check",
+    "test": "node scripts/generate-contract-docs.js --check && node --test tests/*.test.js",
+    "benchmark": "node --test tests/performance.test.js"
   },
   "keywords": [
     "ai",
@@ -23,7 +32,8 @@
     "codex",
     "opencode",
     "agents",
-    "sprints"
+    "sprints",
+    "semantic-memory"
   ],
   "author": {
     "name": "Leander Costa",
@@ -43,6 +53,6 @@
   },
   "license": "MIT",
   "engines": {
-    "node": ">=18"
+    "node": ">=22.13.0"
   }
 }

package/scripts/generate-contract-docs.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const {
+  ARTIFACT_TRANSITIONS,
+  ARTIFACT_TYPES,
+  AUTHORITY,
+  METHOD_VERSION,
+  SCALAR_FIELDS,
+  STRUCTURAL_RELATIONS,
+  TRUTH_OWNERSHIP
+} = require("../lib/v2/schema");
+
+const ROOT = path.resolve(__dirname, "..");
+const OUTPUT = path.join(ROOT, "docs", "SCHEMA.md");
+
+function inline(value) {
+  return String(value).replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+
+function renderContract() {
+  const entityRows = Object.entries(ARTIFACT_TYPES).map(([kind, spec]) => {
+    const ownership = TRUTH_OWNERSHIP[kind];
+    return `| ${kind} | \`${spec.prefix}-NNN\` | \`${spec.directory}/\` | ${spec.initial.map((item) => `\`${item}\``).join(", ")} | ${inline(ownership.truth)} |`;
+  });
+  const relationRows = Object.entries(STRUCTURAL_RELATIONS).map(([field, relation]) => {
+    const target = ARTIFACT_TYPES[relation.targetKind];
+    return `| \`${field}\` | ${relation.targetKind} (\`${target.prefix}-NNN\`) | ${relation.cardinality} | ${inline(relation.meaning)} |`;
+  });
+  const scalarRows = Object.entries(SCALAR_FIELDS).map(([field, constraint]) => `| \`${field}\` | ${constraint.kinds.join(", ")} | ${constraint.required ? "required" : "optional"} | ${constraint.type} | ${inline(constraint.meaning)} |`);
+  const lifecycleRows = Object.entries(ARTIFACT_TYPES).map(([kind, spec]) => {
+    const transitions = ARTIFACT_TRANSITIONS[kind] || {};
+    const rendered = spec.statuses.map((status) => {
+      const targets = transitions[status];
+      return targets ? `\`${status}\` → ${targets.length ? targets.map((target) => `\`${target}\``).join(", ") : "terminal"}` : `\`${status}\` → terminal`;
+    }).join("<br>");
+    return `| ${kind} | ${rendered} |`;
+  });
+  const authorityRows = Object.entries(AUTHORITY).map(([concern, rule]) => `| ${concern} | \`${rule.source}\` | ${inline(rule.scope)} |`);
+
+  return `# ScrumRun ${METHOD_VERSION} Executable Schema
+
+> Generated by \`scripts/generate-contract-docs.js\` from \`lib/v2/schema.js\`. Do not edit this file manually.
+
+## Authority boundaries
+
+| Concern | Authoritative source | Scope |
+|---|---|---|
+${authorityRows.join("\n")}
+
+The boundaries above are deliberately different: SPEC owns meanings, the executable schema owns mechanically enforced values, the command manifest owns grammar, project Markdown owns authored project truth, and generated views own nothing.
+
+## Artifact contract
+
+| Kind | Stable ID | Canonical directory | Allowed initial status | Truth owned by this artifact |
+|---|---|---|---|---|
+${entityRows.join("\n")}
+
+Every artifact also requires \`id\`, \`kind\`, \`status\`, \`created\`, \`updated\`, and \`method: ${METHOD_VERSION}\`.
+
+## Structural cardinalities
+
+| Frontmatter field | Target | Cardinality | Meaning |
+|---|---|---|---|
+${relationRows.join("\n")}
+
+Task is the atomic unit. A Task may have zero or one Sprint. A Task may have many Runs, but every Run belongs to exactly one Task and has a monotonically increasing attempt number within that Task. Sprint membership is authoritative on \`Task.sprint\`; a Sprint's \`## Tasks\` list is a human-readable projection that must agree with it.
+
+## Scalar constraints
+
+| Field | Kinds | Presence | Type | Meaning |
+|---|---|---|---|---|
+${scalarRows.join("\n")}
+
+Native creation uses the declared initial statuses. Migration may restore a historical non-initial status only with provenance and validation.
+
+## Truth questions
+
+${Object.entries(TRUTH_OWNERSHIP).map(([kind, owner]) => `- **${kind}:** ${owner.question}`).join("\n")}
+
+## Lifecycles
+
+| Kind | Declared transitions |
+|---|---|
+${lifecycleRows.join("\n")}
+
+## Projections
+
+\`state.md\`, \`map.md\`, context packages, and \`.cache/\` are disposable. They may summarize or index canonical artifacts, but they cannot introduce status, policy, relations, decisions, or knowledge.
+`;
+}
+
+function main(args = process.argv.slice(2)) {
+  const rendered = renderContract();
+  if (args.includes("--check")) {
+    const current = fs.existsSync(OUTPUT) ? fs.readFileSync(OUTPUT, "utf8") : "";
+    if (current !== rendered) {
+      console.error("docs/SCHEMA.md is stale; run `npm run docs:contract`.");
+      process.exitCode = 1;
+      return;
+    }
+    console.log("ok docs/SCHEMA.md matches lib/v2/schema.js");
+    return;
+  }
+  fs.writeFileSync(OUTPUT, rendered);
+  console.log(`generated ${path.relative(ROOT, OUTPUT)}`);
+}
+
+if (require.main === module) main();
+
+module.exports = { renderContract };

package/templates/project/.scrumrun/config.md

@@ -1,13 +1,10 @@
-# ScrumRun Config - {{PROJECT_NAME}}
+# ScrumRun Project Config - {{PROJECT_NAME}}
 
+Method Version: 2.0.0
+CLI Target: 2.0.0
 Language: English
 Interaction Mode: guided
 Execution Approval: always
 Quick Tasks: ask
 
-## Preferences
-
-- Keep sprint summaries concise and actionable.
-- Ask only blocking questions before implementation.
-- Preserve main goal history and feature lane history separately.
-Sprint Automation: backlog
+These are operating preferences. They can never weaken `.scrumrun/guardrails.md`.

package/templates/project/.scrumrun/guardrails.md

@@ -0,0 +1,23 @@
+# ScrumRun Project Guardrails - {{PROJECT_NAME}}
+
+Canonical project policy. Universal method invariants live in `core.md`; this file contains stable owner/project constraints.
+
+## GR-001 - Protect secrets
+
+Status: active
+Rule: Never commit or print real secrets. Keep local development values in `vault.local.md` and runtime values in environment/config.
+
+## GR-002 - Preserve owner work
+
+Status: active
+Rule: Never overwrite unrelated or pre-existing owner changes. Canonical mutations must be scoped, lossless, validated, and recoverable.
+
+## GR-003 - Respect read-only paths
+
+Status: active
+Rule: Never modify a path marked read-only by the owner or project configuration.
+
+## GR-004 - Approval gates execution
+
+Status: active
+Rule: Intake remains read-only. Create/update a Task and create a Run only after explicit valid approval.

package/templates/project/.scrumrun/map.md

@@ -1,20 +1,8 @@
-# Project Map - {{PROJECT_NAME}}
+# ScrumRun Map - {{PROJECT_NAME}}
 
 Generated: {{DATE}}
+Authority: none; rebuild from canonical artifacts and source code.
 
-## Purpose
+## Active Graph
 
-This file is a compact navigation aid for agents. It is not a source of truth. Verify paths before editing code.
-
-## Top-Level Structure
-
-- `AGENTS.md` — root agent instructions.
-- `.scrumrun/` — ScrumRun project memory, plans, histories, decisions, and reviews.
-
-## Important Commands
-
-- Pending: run `/scr-map --build` after project files exist.
-
-## Notes
-
-- Update this file when important folders, modules, commands, routes, or config files are added or moved.
+- Pending: no Features, Tasks, Sprints, Runs, Memory, or Reviews yet.

package/templates/project/.scrumrun/memory/decisions/.gitkeep

@@ -0,0 +1 @@
+

package/templates/project/.scrumrun/memory/dossiers/.gitkeep

@@ -0,0 +1 @@
+

package/templates/project/.scrumrun/memory/insights/.gitkeep

@@ -0,0 +1 @@
+

package/templates/project/.scrumrun/memory/knowledge/.gitkeep

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,4 @@
+{
+  "method": "2.0.0",
+  "layout": "v2"
+}

package/templates/project/.scrumrun/project.md

@@ -1,26 +1,20 @@
 # Project - {{PROJECT_NAME}}
 
 Created: {{DATE}}
+Method: 2.0.0
 
 ## Purpose
 
-Pending: define the product or system goal with `/scr-goal --new`.
+Pending: define the project outcome through `/sc plan intake <request>`.
 
 ## Stack
 
-Pending: detect or confirm language, framework, database, deployment, test tooling, and integrations.
+Pending: discover or confirm runtime, frameworks, persistence, tests, deployment, and integrations.
 
 ## Architecture
 
-Pending: define architecture style and important boundaries.
+Pending: record verified boundaries and link evidence-backed Decisions/Insights.
 
-## Active Lanes
+## Read-only Paths
 
-- Main goal: `.scrumrun/goals/main/`
-- Features: `.scrumrun/features/`
-
-## Safety Boundaries
-
-- Never commit real secrets.
-- Runtime-specific values must come from env/config.
-- Read-only source paths: pending confirmation.
+- Pending: none declared.

package/templates/project/.scrumrun/runs/.gitkeep

@@ -0,0 +1 @@
+

package/templates/project/.scrumrun/sprints/.gitkeep

@@ -0,0 +1 @@
+

package/templates/project/.scrumrun/state.md

@@ -0,0 +1,21 @@
+# ScrumRun State - {{PROJECT_NAME}}
+
+Generated: {{DATE}}
+Authority: none; this is a disposable view.
+
+## Active Work
+
+- Feature: none.
+- Task: none.
+- Sprint: none.
+- Run: none.
+
+## Relevant Memory
+
+- Decisions: none.
+- Knowledge: none.
+- Insights: none.
+
+## Next Action
+
+- Use `/sc plan intake <request>`.

package/templates/project/.scrumrun/tasks/.gitkeep

@@ -0,0 +1 @@
+

package/templates/project/AGENTS.md

@@ -1,59 +1,26 @@
 # AGENTS.md - {{PROJECT_NAME}}
 
-## ScrumRun
+## ScrumRun 2.0
 
-This project uses ScrumRun.
+This project uses ScrumRun. The method is mandatory; `/sc` is its single optional shortcut.
 
-ScrumRun is mandatory in this project. Slash commands are optional shortcuts; the methodology is not optional.
+For normal work, read:
 
-Before planning, executing, auditing, or reviewing work, read:
+1. `.scrumrun/guardrails.md` — canonical project policy;
+2. `.scrumrun/state.md` — disposable index of active ids;
+3. the referenced Task, Sprint, Feature, Run, Memory, and Review artifacts relevant to the request;
+4. `.scrumrun/core.md` when the method contract or an exceptional transition is needed.
 
-1. `.scrumrun/core.md` — portable ScrumRun method and command equivalents.
-2. `.scrumrun/golden-rules.md` — **MANDATORY. Highest priority. Never violate.**
-3. `.scrumrun/config.md` — response language and ScrumRun behavior preferences.
-4. `.scrumrun/token-policy.md` — context economy rules.
-5. `.scrumrun/context.md` — token-safe snapshot, not source of truth.
-6. `.scrumrun/map.md` — project folders, paths, modules, and key files.
-7. `.scrumrun/project.md`
-8. `.scrumrun/knowledge.md`
-9. `.scrumrun/runbook.md` — execution protocol before reading operational work.
-10. `.scrumrun/backlog.md`
-11. `.scrumrun/goals/main/sprint.md`
-12. `.scrumrun/agents.md`
-13. `.scrumrun/goals/main/history.md`
-14. `.scrumrun/goals/main/decisions.md`
+Natural-language product requests automatically enter the read-only ScrumRun intake pipeline. Before explicit approval, do not create canonical records or modify application code.
 
-If the current AI client does not support `/sc-*` slash commands, read `.scrumrun/core.md` and execute the matching ScrumRun workflow manually.
+After approval:
 
-If the user asks for work without mentioning ScrumRun, still follow ScrumRun because this project was initialized with it.
+- Task is the atomic work item;
+- Sprint is only a real timebox/batch of Tasks;
+- Run is one execution attempt and follows `executing → validating → learning → completed|failed|blocked`;
+- a retry creates a new Run and preserves the old one;
+- learning proposes evidence-backed Knowledge, Decisions, or candidate Insights.
 
-Unless `.scrumrun/config.md` sets `Interaction Mode: strict`, treat natural-language requests for fixes, features, refactors, investigations, or product changes as ScrumRun intake. Classify the request, recommend the safest workflow, and obtain the approval required by `.scrumrun/config.md` before creating operational records or changing application code. The user does not need to know or invoke a slash command.
+Never bypass guardrails, overwrite owner work, treat generated state/cache as truth, auto-confirm AI knowledge, auto-migrate a v1 project, or print vault values.
 
-## Absolute Safety Rules
-
-- Do not start a sprint unless the owner explicitly asks for that sprint.
-- Do not convert an intake recommendation into a backlog item, sprint, feature lane, fix, or code change until the configured approval gate is satisfied.
-- Before executing any main-goal sprint, check `.scrumrun/goals/main/history.md`.
-- Before executing any feature sprint, check that feature lane's `history.md`.
-- If a sprint is `completed`, ask whether to audit, rerun/fix, or continue to the next sprint.
-- If a sprint is `partial` or `blocked`, ask whether to resume, audit, or move to another sprint.
-- Never commit real secrets.
-- Runtime-specific values must come from env/config, not hardcoded strings.
-- If a project has a read-only source path, never modify it.
-- Keep main goal history and feature lane history separate.
-- Use `.scrumrun/context.md` to reduce unnecessary reading, but never as canonical truth.
-- If context conflicts with golden rules, approved knowledge, history, decisions, or source code, context loses.
-
-## Sprint Protocol
-
-Every sprint must follow:
-
-1. Entenda
-2. Avalie Impactos
-3. Tire Duvidas
-4. Execute
-5. Teste
-
-## Handoff
-
-At the end of each sprint, update the relevant history file with status, files changed, commands run, tests, decisions, env variable names, risks, and follow-ups.
+If `/sc` is unavailable, follow the equivalent workflow in `.scrumrun/core.md` manually.

package/templates/project-lean/AGENTS.md

@@ -0,0 +1,18 @@
+# AGENTS.md - {{PROJECT_NAME}}
+
+## ScrumRun 2.0 lean read policy
+
+This project stores the complete ScrumRun v2 truth but uses a bounded default read path:
+
+1. `.scrumrun/guardrails.md`;
+2. `.scrumrun/state.md`;
+3. only canonical artifacts referenced by active ids;
+4. `.scrumrun/core.md` only when method details are needed.
+
+Do not scan every Task, Run, Sprint, Feature, or Memory file by default. Generated `state.md`, `map.md`, and `.cache/` guide retrieval but never override canonical Markdown.
+
+Natural-language product work begins as read-only intake. Explicit approval creates/updates a Task and creates one Run. A Sprint exists only for a real batch/timebox. Run state is `executing → validating → learning → completed|failed|blocked`; retries preserve prior Runs.
+
+`.scrumrun/guardrails.md` is canonical policy. Never bypass it, overwrite owner work, auto-confirm AI knowledge, auto-migrate v1 state, or print vault values.
+
+Use `/sc <noun> <subject> <action> [args]`; if `/sc` is unavailable, follow `.scrumrun/core.md` manually.