scrumrun 1.5.2 → 2.1.0

package/lib/v2/transaction.js

@@ -0,0 +1,254 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+const {
+  assertNoSymlinkPath,
+  atomicWrite,
+  sha256,
+  withArtifactLock
+} = require("./artifacts");
+
+const TRANSACTION_SCHEMA = 1;
+const TRANSACTION_ROOT = path.join(".backup", "transactions");
+const PENDING_DIR = path.join(TRANSACTION_ROOT, "pending");
+const RECEIPT_DIR = path.join(TRANSACTION_ROOT, "receipts");
+const FORBIDDEN = [".backup/", ".cache/", ".migration/", "vault.local.md"];
+
+function posix(value) {
+  return value.split(path.sep).join("/");
+}
+
+function transactionId() {
+  return `TXN-${Date.now()}-${crypto.randomBytes(6).toString("hex")}`;
+}
+
+function safeTransactionPath(scrumDir, relative) {
+  return assertNoSymlinkPath(scrumDir, path.join(scrumDir, relative));
+}
+
+function relativeTarget(scrumDir, file) {
+  const target = assertNoSymlinkPath(scrumDir, path.resolve(file));
+  const relative = posix(path.relative(path.resolve(scrumDir), target));
+  if (!relative || relative.startsWith("../") || path.isAbsolute(relative)) throw new Error(`Transaction target escapes .scrumrun: ${file}`);
+  if (FORBIDDEN.some((entry) => relative === entry.replace(/\/$/, "") || relative.startsWith(entry))) {
+    throw new Error(`Transaction target is outside the canonical mutation boundary: ${relative}`);
+  }
+  return { relative, file: target };
+}
+
+function snapshot(content) {
+  if (content === null) return { exists: false, sha256: "missing", content_base64: null };
+  const value = Buffer.isBuffer(content) ? content : Buffer.from(String(content));
+  return { exists: true, sha256: sha256(value), content_base64: value.toString("base64") };
+}
+
+function fileSnapshot(scrumDir, relative) {
+  const file = safeTransactionPath(scrumDir, relative);
+  if (!fs.existsSync(file)) return snapshot(null);
+  if (!fs.lstatSync(file).isFile()) throw new Error(`Transaction target is not a regular file: ${relative}`);
+  return snapshot(fs.readFileSync(file));
+}
+
+function sameSnapshot(left, right) {
+  return Boolean(left && right && left.exists === right.exists && left.sha256 === right.sha256);
+}
+
+function applySnapshot(scrumDir, relative, value) {
+  const file = safeTransactionPath(scrumDir, relative);
+  if (!value.exists) {
+    if (fs.existsSync(file)) fs.rmSync(file, { force: true });
+    return;
+  }
+  atomicWrite(file, Buffer.from(value.content_base64, "base64"));
+}
+
+function pendingDirectory(scrumDir) {
+  return safeTransactionPath(scrumDir, PENDING_DIR);
+}
+
+function receipt(transaction, status, details = {}) {
+  return {
+    schema: TRANSACTION_SCHEMA,
+    id: transaction.id,
+    name: transaction.name,
+    status,
+    created_at: transaction.created_at,
+    finished_at: new Date().toISOString(),
+    changes: transaction.changes.map((change) => ({
+      relative: change.relative,
+      before_sha256: change.before.sha256,
+      after_sha256: change.after.sha256
+    })),
+    ...details
+  };
+}
+
+function finishJournal(scrumDir, journalFile, transaction, status, details = {}) {
+  const receiptFile = safeTransactionPath(scrumDir, path.join(RECEIPT_DIR, `${transaction.id}.json`));
+  atomicWrite(receiptFile, `${JSON.stringify(receipt(transaction, status, details), null, 2)}\n`);
+  fs.rmSync(journalFile, { force: true });
+}
+
+function pendingTransactions(scrumDir) {
+  const directory = pendingDirectory(scrumDir);
+  if (!fs.existsSync(directory)) return [];
+  if (!fs.lstatSync(directory).isDirectory()) throw new Error("Transaction pending path is not a directory.");
+  const entries = fs.readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+  for (const entry of entries) {
+    if (entry.isSymbolicLink() || !entry.isFile() || !/^TXN-[a-zA-Z0-9-]+\.json$/.test(entry.name)) {
+      throw new Error(`Unexpected transaction journal entry: ${entry.name}`);
+    }
+  }
+  return entries.map((entry) => {
+      const file = safeTransactionPath(scrumDir, path.join(PENDING_DIR, entry.name));
+      try {
+        const transaction = JSON.parse(fs.readFileSync(file, "utf8"));
+        return { file, transaction };
+      } catch (error) {
+        throw new Error(`Transaction journal is malformed: ${entry.name}: ${error.message}`);
+      }
+    });
+}
+
+function validateJournal(transaction) {
+  const errors = [];
+  if (!transaction || transaction.schema !== TRANSACTION_SCHEMA) errors.push(`schema must be ${TRANSACTION_SCHEMA}`);
+  if (!/^TXN-[a-zA-Z0-9-]+$/.test(transaction && transaction.id || "")) errors.push("id is invalid");
+  if (!transaction || !["prepared", "committed"].includes(transaction.status)) errors.push("status must be prepared or committed");
+  if (!transaction || !Array.isArray(transaction.changes) || !transaction.changes.length) errors.push("changes must be a non-empty array");
+  for (const change of transaction && Array.isArray(transaction.changes) ? transaction.changes : []) {
+    if (typeof change.relative !== "string" || !change.relative) errors.push("change.relative is required");
+    for (const key of ["before", "after"]) {
+      const value = change[key];
+      if (!value || typeof value.exists !== "boolean" || typeof value.sha256 !== "string") errors.push(`${change.relative || "change"}.${key} is malformed`);
+      if (value && value.exists && typeof value.content_base64 !== "string") errors.push(`${change.relative || "change"}.${key} content is missing`);
+      if (value && value.exists && typeof value.content_base64 === "string") {
+        const decoded = Buffer.from(value.content_base64, "base64");
+        if (decoded.toString("base64") !== value.content_base64 || sha256(decoded) !== value.sha256) {
+          errors.push(`${change.relative || "change"}.${key} content hash is invalid`);
+        }
+      }
+      if (value && !value.exists && (value.sha256 !== "missing" || value.content_base64 !== null)) {
+        errors.push(`${change.relative || "change"}.${key} missing snapshot is invalid`);
+      }
+    }
+  }
+  return errors;
+}
+
+function recoverPendingTransactionsUnlocked(scrumDir) {
+  const recovered = [];
+  for (const { file, transaction } of pendingTransactions(scrumDir)) {
+    const errors = validateJournal(transaction);
+    if (errors.length) throw new Error(`Unsafe transaction journal ${path.basename(file)}: ${errors.join("; ")}`);
+    for (const change of transaction.changes) {
+      const target = relativeTarget(scrumDir, path.join(scrumDir, change.relative));
+      if (target.relative !== change.relative) throw new Error(`Unsafe transaction target in ${transaction.id}: ${change.relative}`);
+    }
+    const current = transaction.changes.map((change) => ({ change, value: fileSnapshot(scrumDir, change.relative) }));
+    const unexpected = current.filter(({ change, value }) => !sameSnapshot(value, change.before) && !sameSnapshot(value, change.after));
+    if (unexpected.length) {
+      throw new Error(`Pending transaction ${transaction.id} cannot recover without overwriting owner changes: ${unexpected.map(({ change }) => change.relative).join(", ")}`);
+    }
+    if (transaction.status === "prepared") {
+      for (const change of [...transaction.changes].reverse()) applySnapshot(scrumDir, change.relative, change.before);
+      const unrestored = transaction.changes.filter((change) => !sameSnapshot(fileSnapshot(scrumDir, change.relative), change.before));
+      if (unrestored.length) throw new Error(`Transaction ${transaction.id} recovery verification failed: ${unrestored.map((change) => change.relative).join(", ")}`);
+      finishJournal(scrumDir, file, transaction, "recovered", { action: "rolled-back-prepared" });
+      recovered.push({ id: transaction.id, action: "rolled-back" });
+    } else {
+      const incomplete = current.filter(({ change, value }) => !sameSnapshot(value, change.after));
+      if (incomplete.length) throw new Error(`Committed transaction ${transaction.id} is incomplete: ${incomplete.map(({ change }) => change.relative).join(", ")}`);
+      finishJournal(scrumDir, file, transaction, "committed", { action: "verified-commit" });
+      recovered.push({ id: transaction.id, action: "verified" });
+    }
+  }
+  return recovered;
+}
+
+function recoverPendingTransactions(scrumDir) {
+  return withArtifactLock(scrumDir, "kernel", () => recoverPendingTransactionsUnlocked(scrumDir));
+}
+
+function normalizeChanges(scrumDir, changes) {
+  if (!Array.isArray(changes) || !changes.length) throw new Error("Kernel transaction requires at least one change.");
+  const seen = new Set();
+  return changes.map((change) => {
+    const target = relativeTarget(scrumDir, change.file);
+    if (seen.has(target.relative)) throw new Error(`Duplicate transaction target: ${target.relative}`);
+    seen.add(target.relative);
+    if (!Object.prototype.hasOwnProperty.call(change, "previous") || !Object.prototype.hasOwnProperty.call(change, "next")) {
+      throw new Error(`Transaction change requires previous and next content: ${target.relative}`);
+    }
+    return { relative: target.relative, before: snapshot(change.previous), after: snapshot(change.next) };
+  });
+}
+
+function writeKernelTransactionUnlocked(scrumDir, name, changes, { failurePoint = null, interruptPoint = null } = {}) {
+  if (!/^[a-z0-9-]+$/i.test(name || "")) throw new Error(`Invalid transaction name: ${name || "missing"}`);
+  const normalized = normalizeChanges(scrumDir, changes);
+  const conflicts = normalized.filter((change) => !sameSnapshot(fileSnapshot(scrumDir, change.relative), change.before));
+  if (conflicts.length) throw new Error(`Transaction source changed before prepare: ${conflicts.map((change) => change.relative).join(", ")}`);
+  const transaction = {
+    schema: TRANSACTION_SCHEMA,
+    id: transactionId(),
+    name,
+    status: "prepared",
+    created_at: new Date().toISOString(),
+    changes: normalized
+  };
+  const journalFile = safeTransactionPath(scrumDir, path.join(PENDING_DIR, `${transaction.id}.json`));
+  atomicWrite(journalFile, `${JSON.stringify(transaction, null, 2)}\n`);
+  if (interruptPoint === "after-prepare") throw Object.assign(new Error("Simulated interruption after transaction prepare."), { code: "SCRUMRUN_INTERRUPTED" });
+  try {
+    for (let index = 0; index < transaction.changes.length; index++) {
+      const change = transaction.changes[index];
+      applySnapshot(scrumDir, change.relative, change.after);
+      if (interruptPoint === `after-${index + 1}`) {
+        throw Object.assign(new Error(`Simulated interruption after transaction write ${index + 1}.`), { code: "SCRUMRUN_INTERRUPTED" });
+      }
+      if (failurePoint === `after-${index + 1}`) throw new Error(`Injected transaction failure after write ${index + 1}.`);
+    }
+    const invalid = transaction.changes.filter((change) => !sameSnapshot(fileSnapshot(scrumDir, change.relative), change.after));
+    if (invalid.length) throw new Error(`Transaction verification failed: ${invalid.map((change) => change.relative).join(", ")}`);
+    const committed = { ...transaction, status: "committed", committed_at: new Date().toISOString() };
+    atomicWrite(journalFile, `${JSON.stringify(committed, null, 2)}\n`);
+    if (interruptPoint === "after-commit") {
+      throw Object.assign(new Error("Simulated interruption after transaction commit."), { code: "SCRUMRUN_INTERRUPTED" });
+    }
+    finishJournal(scrumDir, journalFile, committed, "committed", { action: "applied" });
+    return { id: transaction.id, status: "committed", changes: transaction.changes.length };
+  } catch (error) {
+    if (error.code === "SCRUMRUN_INTERRUPTED") throw error;
+    for (const change of [...transaction.changes].reverse()) applySnapshot(scrumDir, change.relative, change.before);
+    finishJournal(scrumDir, journalFile, transaction, "recovered", { action: "rolled-back-error", error: error.message });
+    throw error;
+  }
+}
+
+function runKernelTransaction(scrumDir, name, changes, options = {}) {
+  return withArtifactLock(scrumDir, "kernel", () => {
+    const recovered = recoverPendingTransactionsUnlocked(scrumDir);
+    const result = writeKernelTransactionUnlocked(scrumDir, name, changes, options);
+    return { ...result, recovered };
+  });
+}
+
+function pendingTransactionStatus(scrumDir) {
+  try {
+    return { pending: pendingTransactions(scrumDir).map(({ transaction }) => ({ id: transaction.id, name: transaction.name, status: transaction.status })) };
+  } catch (error) {
+    return { pending: [], error: error.message };
+  }
+}
+
+module.exports = {
+  TRANSACTION_SCHEMA,
+  pendingTransactionStatus,
+  recoverPendingTransactions,
+  recoverPendingTransactionsUnlocked,
+  runKernelTransaction,
+  writeKernelTransactionUnlocked
+};

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.1.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,124 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const {
+  ARTIFACT_TRANSITIONS,
+  ARTIFACT_TYPES,
+  AUTHORITY,
+  METHOD_VERSION,
+  RUN_EVENT_TYPES,
+  RUN_EVIDENCE_KINDS,
+  RUN_LEDGER_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.
+
+## Run event ledger
+
+Newly authored Runs use \`ledger: ${RUN_LEDGER_VERSION}\`. Their \`## Events\` section contains append-only JSON event blocks with stable ids in the form \`RUN-NNN-EVT-NNN\`.
+
+Every event requires \`schema\`, \`id\`, contiguous \`sequence\`, RFC3339 \`occurred_at\`, \`timestamp_precision\`, \`actor\`, \`from\`, \`to\`, \`reason\`, and structured \`evidence\`. Event types are ${RUN_EVENT_TYPES.map((value) => `\`${value}\``).join(", ")}. Evidence kinds are ${RUN_EVIDENCE_KINDS.map((value) => `\`${value}\``).join(", ")}.
+
+A native ledger begins with \`created → executing\`; an evidenced migration \`snapshot\` may establish one historical baseline without inventing missing transitions. Event order, transition legality, final status, updated date, and completion evidence are machine-validated. Run owns the event history; Task stores its intended scope and synchronized current status without copying Run events.
+
+## 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,31 @@
+# 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
+Enforcement: builtin:secret-boundary
+Scope: all
+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
+Enforcement: builtin:owner-work
+Scope: all
+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
+Enforcement: builtin:read-only-path
+Scope: all
+Rule: Never modify a path marked read-only by the owner or project configuration.
+
+## GR-004 - Approval gates execution
+
+Status: active
+Enforcement: builtin:approval-gate
+Scope: intake, execution
+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,9 @@
-# Project Map - {{PROJECT_NAME}}
+# ScrumRun Project Map
 
 Generated: {{DATE}}
+Status: stale
+Authority: none; rebuild from canonical artifacts and source code.
 
-## Purpose
+## Summary
 
-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.
+- No source fingerprint exists until `/sc knowledge map --build` creates the disposable semantic index and this bounded view.

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,7 @@
+{
+  "method": "2.0.0",
+  "layout": "v2",
+  "schemas": {
+    "run_ledger": 1
+  }
+}

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,14 @@
+# ScrumRun State
+
+Projection schema: 1
+Generated: {{DATE}}T00:00:00.000Z
+Status: stale until `init` rebuilds this projection.
+Authority: none; rebuild from canonical artifacts.
+
+## Active Work
+
+- No active canonical work.
+
+## Relevant Memory
+
+- No active canonical memory.

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.