scrumrun 3.1.1 → 4.0.0

package/docs/SCHEMA.md

@@ -20,9 +20,9 @@ The boundaries above are deliberately different: SPEC owns meanings, the executa
 | Kind | Stable ID | Canonical directory | Allowed initial status | Truth owned by this artifact |
 |---|---|---|---|---|
 | feature | `FEAT-NNN` | `features/` | `backlog`, `proposed` | initiative purpose, scope, dependencies, and lifecycle |
-| task | `TASK-NNN` | `tasks/` | `backlog`, `proposed`, `running` | scope, acceptance criteria, approval, and intended status |
-| sprint | `SPRINT-NNN` | `sprints/` | `proposed` | timebox or delivery-batch membership; never execution history |
-| run | `RUN-NNN` | `runs/` | `executing` | append-only execution events, evidence, result, and attempt number |
+| task | `TASK-NNN` | `tasks/` | `backlog`, `proposed`, `in_progress`, `running` | scope, owner-defined sections, links, and status |
+| sprint | `SPRINT-NNN` | `sprints/` | `proposed` | timebox or delivery-batch membership; may be feature, fix, or maintenance |
+| run | `RUN-NNN` | `runs/` | `executing` | optional human-readable execution record and outcome |
 | review | `REV-NNN` | `reviews/` | `proposed` | scoped findings, checks, evidence, and verdict |
 | knowledge | `K-NNN` | `memory/knowledge/` | `candidate` | approved evidence-backed fact and validity |
 | decision | `DEC-NNN` | `memory/decisions/` | `open` | decision, rationale, validity, and lifecycle |
@@ -37,9 +37,9 @@ Every artifact also requires `id`, `kind`, `status`, `created`, `updated`, and `
 |---|---|---|---|
 | `feature` | feature (`FEAT-NNN`) | 0..1 | long-lived initiative containing the artifact |
 | `sprint` | sprint (`SPRINT-NNN`) | 0..1 | optional delivery batch containing a Task or Run |
-| `task` | task (`TASK-NNN`) | 1 for Run; otherwise 0..1 | atomic work executed or reviewed by the artifact |
+| `task` | task (`TASK-NNN`) | 0..1 | atomic work executed or reviewed by the artifact |
 
-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.
+Task is the atomic unit. A Task may have zero or one Sprint. A Run is optional Markdown history and may reference either a Task or a Sprint; it never controls Task status in Markdown-first work. Sprint membership is authoritative on `Task.sprint`; a Sprint's `## Tasks` list is a human-readable projection that must agree with it. Additional owner-defined relations such as `depends_on: [TASK-014, DEC-018]` are preserved as local Markdown graph data.
 
 ## Scalar constraints
 
@@ -58,14 +58,14 @@ Newly authored Runs use `ledger: 1`. Their `## Events` section contains append-o
 
 Every event requires `schema`, `id`, contiguous `sequence`, RFC3339 `occurred_at`, `timestamp_precision`, `actor`, `from`, `to`, `reason`, and structured `evidence`. Event types are `transition`, `snapshot`, `guardrail`, `mutation`. Evidence kinds are `approval`, `command`, `test`, `file`, `review`, `decision`, `insight`, `risk`, `note`, `migration`, `legacy`, `guardrail`, `mutation`.
 
-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.
+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 when a strict audit Run is used. Run owns optional event history; Task Markdown owns the delivered scope and status in normal work.
 
 ## Truth questions
 
 - **feature:** Why does this initiative exist?
-- **task:** What approved atomic outcome is intended?
-- **sprint:** When are related Tasks grouped?
-- **run:** How did one execution attempt actually happen?
+- **task:** What concrete outcome is intended?
+- **sprint:** Which Tasks are grouped for this delivery?
+- **run:** What happened while executing a Task or Sprint?
 - **review:** What independent validation was performed?
 - **knowledge:** What verified project fact is reusable?
 - **decision:** What normative choice constrains future work?
@@ -77,7 +77,7 @@ A native ledger begins with `created → executing`; an evidenced migration `sna
 | Kind | Declared transitions |
 |---|---|
 | feature | `backlog` → `proposed`, `active`, `cancelled`<br>`proposed` → `active`, `cancelled`<br>`active` → `paused`, `completed`, `cancelled`<br>`completed` → terminal<br>`paused` → `active`, `cancelled`<br>`cancelled` → terminal |
-| task | `backlog` → `proposed`, `running`, `cancelled`<br>`proposed` → `running`, `cancelled`<br>`running` → `validating`, `failed`, `blocked`, `cancelled`<br>`validating` → `learning`, `failed`, `blocked`<br>`learning` → `completed`, `failed`, `blocked`<br>`partial` → `running`, `cancelled`<br>`completed` → terminal<br>`failed` → `running`, `cancelled`<br>`blocked` → `running`, `cancelled`<br>`cancelled` → terminal |
+| task | `backlog` → `proposed`, `in_progress`, `running`, `cancelled`<br>`proposed` → `in_progress`, `running`, `cancelled`<br>`in_progress` → `completed`, `failed`, `blocked`, `cancelled`<br>`running` → `validating`, `completed`, `failed`, `blocked`, `cancelled`<br>`validating` → `learning`, `completed`, `failed`, `blocked`<br>`learning` → `completed`, `failed`, `blocked`<br>`partial` → `in_progress`, `running`, `cancelled`<br>`completed` → terminal<br>`failed` → `in_progress`, `running`, `cancelled`<br>`blocked` → `in_progress`, `running`, `cancelled`<br>`cancelled` → terminal |
 | sprint | `proposed` → `running`, `cancelled`<br>`running` → `partial`, `completed`, `blocked`, `cancelled`<br>`partial` → `running`, `completed`, `cancelled`<br>`completed` → terminal<br>`blocked` → `running`, `cancelled`<br>`cancelled` → terminal |
 | run | `executing` → `validating`, `failed`, `blocked`<br>`validating` → `learning`, `failed`, `blocked`<br>`learning` → `completed`, `failed`, `blocked`<br>`partial` → `executing`, `failed`, `blocked`<br>`completed` → terminal<br>`failed` → terminal<br>`blocked` → `executing`, `failed` |
 | review | `proposed` → `running`<br>`running` → `passed`, `failed`<br>`passed` → `archived`<br>`failed` → `running`, `archived`<br>`archived` → terminal |

package/lib/commands/manifest.js

@@ -6,7 +6,7 @@ const nouns = Object.freeze({
   plan: {
     description: "turn intent into Features, Tasks, Sprints, and Runs",
     subjects: {
-      task: ["--add [--type fix] [--status backlog]", "--amend <TASK-NNN> [--title] [--request] [--acceptance] [--section \"Heading=content\"] [--type task|fix|feature|docs|discovery] [--feature] [--sprint]", "--list", "--show", "--run", "--audit", "--cancel", "--retry [--reassign]", "--next", "--start [TASK-NNN]"],
+      task: ["--add [--type fix] [--status backlog]", "--amend <TASK-NNN> [--title] [--request] [--acceptance] [--section \"Heading=content\"] [--type task|fix|feature|docs|discovery] [--feature] [--sprint]", "--list", "--show", "--run", "--audit", "--cancel", "--retry [--reassign] --strict", "--next", "--start [TASK-NNN] --strict"],
       sprint: ["--add", "--amend <SPRINT-NNN> [--title] [--timebox] [--exit-gate] [--section \"Heading=content\"]", "--list", "--show", "--start", "--complete", "--block"],
       feature: ["--add", "--amend <FEAT-NNN> [--title] [--purpose] [--exit-criteria] [--section \"Heading=content\"]", "--list", "--show", "--activate", "--complete"],
       run: [
@@ -15,16 +15,16 @@ const nouns = Object.freeze({
         "--render <RUN-NNN>",
         "--stats [--task <TASK-NNN>] [--feature <FEAT-NNN>] [--sprint <SPRINT-NNN>] [--json]",
         "--normalize-legacy [--dry-run]",
-        "--finalize <RUN-NNN> [--summary \"technical recap\"] [--note]",
+        "--finalize <RUN-NNN> --strict [--summary \"technical recap\"] [--note]",
         "--authorize-mutation <RUN-NNN> --path <relative-path>",
         "--record-mutation <RUN-NNN> --permit <MUT-id> [--note] [--actor]",
         "--satisfy-guardrail <RUN-NNN> --guardrail <GR-NNN> [--note] [--evidence] [--review] [--migration] [--actor]",
-        "--validate [--note] [--evidence] [--command] [--test] [--file] [--review] [--actor] [--at]",
-        "--learn [--note] [--evidence] [--decision] [--insight] [--file] [--actor] [--at]",
-        "--complete [--note] [--evidence] [--review] [--test] [--file] [--actor] [--at] [--summary \"technical recap for future tasks\"]",
-        "--resume [--note] [--evidence] [--risk] [--actor] [--at]",
-        "--fail [--note] [--evidence] [--risk] [--test] [--actor] [--at]",
-        "--block [--note] [--evidence] [--risk] [--actor] [--at]"
+        "--validate --strict [--note] [--evidence] [--command] [--test] [--file] [--review] [--actor] [--at]",
+        "--learn --strict [--note] [--evidence] [--decision] [--insight] [--file] [--actor] [--at]",
+        "--complete --strict [--note] [--evidence] [--review] [--test] [--file] [--actor] [--at] [--summary \"technical recap for future tasks\"]",
+        "--resume --strict [--note] [--evidence] [--risk] [--actor] [--at]",
+        "--fail --strict [--note] [--evidence] [--risk] [--test] [--actor] [--at]",
+        "--block --strict [--note] [--evidence] [--risk] [--actor] [--at]"
       ],
       intake: ["<request>", "--request", "--approve", "--plain", "--json", "--type <fix|task|feature|docs|discovery>", "--preview \"technical summary\""],
       challenge: ["<question>"]
@@ -65,7 +65,7 @@ const nouns = Object.freeze({
     subjects: {
       project: ["--show", "--language", "--interaction", "--approval", "--quick-tasks"],
       init: ["--local", "--shared", "--lean", "--no-agent-hint", "--force"],
-      update: ["all [--migrate]", "codex [--migrate]", "opencode [--migrate]", "claude [--migrate]"],
+      update: ["all [--project] [--seal-policy] [--migrate]", "codex [--project] [--seal-policy] [--migrate]", "opencode [--project] [--seal-policy] [--migrate]", "claude [--project] [--seal-policy] [--migrate]"],
       migrate: ["--to 2 --dry-run", "--to 2 --apply", "--to 2 --rollback"],
       doctor: ["all [--strict] [--recover] [--dry-run]", "codex [--strict] [--recover] [--dry-run]", "opencode [--strict] [--recover] [--dry-run]", "claude [--strict] [--recover] [--dry-run]"],
       uninstall: ["--force"],

package/lib/commands/render.js

@@ -29,15 +29,16 @@ ${grammarLines().join("\n")}
 
 - Natural-language product work begins with a read-only understanding pass; do not invoke \`plan intake\` merely to satisfy procedure.
 - Intake, contextualization, policy, risk, classification, and planning are read-only until explicit approval.
-- After approval, work directly in source files and relevant \`.scrumrun/\` Markdown. Create/refine a Task, acceptance criteria, technical summary, and follow-ups directly. Feature/Sprint/Run are useful only when they add context.
+- After approval, work directly in source files and relevant \`.scrumrun/\` Markdown until the approved Task is delivered. Keep executing discover → implement → verify → fix → verify; a progress report is allowed only when the owner asks for it and never ends the workflow. Do not answer with an inventory, partial progress report, decomposition, or remaining-work list; those are internal steps. A gap discovered in scope is work to implement now, not a “next step”. Feature/Sprint/Run are useful only when they add context.
 - A Run is optional audit/handoff context, never a prerequisite for starting, amending, or completing a Task. Do not block on a missing Run, a legacy status, or stale generated state.
 - The CLI can inspect/repair/report structured artifacts, but it does not own the daily workflow.
 - \`guardrails.md\` is canonical project policy; \`golden-rules.md\` is v1 compatibility only.
 - Evaluate active Guardrails as \`passed\`, \`blocked\`, or \`deferred\`; cite exact \`GR-NNN\` ids and keep deferred execution gates visible.
-- Block only for an explicit Guardrail, secret/security risk, destructive action without approval, or an unmet required Acceptance Criterion. Optional unrun E2E/review coverage is a follow-up/risk, not a failed Run.
+- Block only for an explicit Guardrail, secret/security risk, destructive action without approval, or an unmet required delivery criterion. \`Follow-ups\` may only contain work outside the approved \`Done when\` contract; optional unrun E2E/review coverage is a follow-up/risk, not a failed Run.
 - Use the CLI only for \`init\`, \`update --project\`, \`migrate\`, \`repair\`, \`doctor\`, reports, or release checks. Do not invoke \`npx scrumrun@latest\` during execution.
 - Never invoke \`plan run --fail|--block|--retry|--finalize|--complete|--validate\` or \`plan task --start\` during normal work. These optional strict-audit commands must not decide a Task outcome.
 - Strict per-path Mutation Gateway permits and ledger finalization remain available only when the owner explicitly requests strict execution.
+- Never edit \`core.md\` or \`guardrails.md\` during product work. They are sealed policy; owner-requested policy changes are reviewed and sealed at the maintenance edge.
 - Knowledge/Decision/Insight records require evidence; AI-proposed Insights remain \`candidate\` until confirmed.
 - Never print vault values or write before approval.
 - Unknown nouns, subjects, actions, ids, or ambiguous approval must produce a deterministic explanation, never a guessed mutation.

package/lib/runtime/briefing.js

@@ -29,6 +29,31 @@ function generateBriefing(scrumDir, repository) {
       }))
     .slice(0, 5);
 
+  // Blocked-by-dependency: Tasks with `depends_on: [ID, ...]` in frontmatter
+  // where at least one target artifact is missing or not terminal. This is a
+  // visibility signal, not a hard gate — the agent reads it and decides.
+  const allById = new Map();
+  for (const kind of Object.keys(snapshot.records)) {
+    for (const r of snapshot.records[kind] || []) {
+      if (r.id) allById.set(r.id, r);
+    }
+  }
+  const blockedLines = [];
+  for (const task of snapshot.records.task || []) {
+    if (!task.id || TERMINAL.has(task.status)) continue;
+    const deps = Array.isArray(task.depends_on) ? task.depends_on : [];
+    const blocking = [];
+    for (const depId of deps) {
+      if (typeof depId !== "string") continue;
+      const dep = allById.get(depId);
+      if (!dep) blocking.push(`${depId} (missing)`);
+      else if (!TERMINAL.has(dep.status)) blocking.push(`${depId} (${dep.status})`);
+    }
+    if (blocking.length) {
+      blockedLines.push(`- ${task.id} waits on ${blocking.join(", ")} — ${task.title || task.id}`);
+    }
+  }
+
   const completedRuns = (snapshot.records.run || [])
     .filter((r) => r.status === "completed")
     .slice(-5)
@@ -76,6 +101,10 @@ Progressive disclosure: read this first; go deeper only if the briefing lacks wh
 
 ${activeWork.length ? activeWork.join("\n") : "- No active canonical work."}
 
+## Blocked by dependency
+
+${blockedLines.length ? blockedLines.join("\n") : "- None. All active Tasks have their `depends_on` targets terminal (or none declared)."}
+
 ## Recent
 
 ${recentLines.length ? recentLines.join("\n") : "- No completed Runs."}

package/lib/runtime/orchestrator.js

@@ -57,7 +57,7 @@ function sprintBody(title, request, created, taskId) {
 function buildTaskBody(request, classification, approvalId, fingerprint, risk, previewSection, links = {}) {
   const featureSection = links.feature ? `\n## Feature\n\n- ${links.feature}\n` : "";
   const sprintSection = links.sprint ? `\n## Sprint\n\n- ${links.sprint}\n` : "";
-  return `# ${titleFor(request)}\n\n## Request\n\n${request}\n\n## Acceptance Criteria\n\n- [ ] _Define what "done" means before execution._\n\n## Validation Scope\n\n- Required: validate the stated Acceptance Criteria and active Guardrails proportionately to risk.\n- Non-blocking: tests, reviews, or environments not explicitly required by the owner, Acceptance Criteria, or an active Guardrail. Record a material coverage gap as a follow-up; do not fail the Task solely because that optional check was not run.\n${previewSection}${featureSection}${sprintSection}\n## Classification\n\n- Type: ${classification.type}\n- Reason: ${classification.reason}\n- Risk: ${risk.level}\n\n## Approval\n\n- Explicit approval token: ${approvalId}\n- Context fingerprint: ${fingerprint}`;
+  return `# ${titleFor(request)}\n\n## Request\n\n${request}\n\n## Done when\n\n- [ ] _State the smallest observable delivery contract before execution._\n\n## Validation Scope\n\n- Required: validate the stated Done when contract and active Guardrails proportionately to risk.\n- Non-blocking: tests, reviews, or environments not explicitly required by the owner, Done when contract, or an active Guardrail. Record a material coverage gap as a follow-up only when it is outside the approved contract; do not fail the Task solely because that optional check was not run.\n\n## Completion\n\n- _Fill this once, after the delivery contract is satisfied._\n${previewSection}${featureSection}${sprintSection}\n## Classification\n\n- Type: ${classification.type}\n- Reason: ${classification.reason}\n- Risk: ${risk.level}\n\n## Approval\n\n- Explicit approval token: ${approvalId}\n- Context fingerprint: ${fingerprint}`;
 }
 
 function stateFingerprint(repository) {
@@ -595,9 +595,9 @@ function planArtifactBody(kind, title, created) {
       "",
       title,
       "",
-      "## Acceptance Criteria",
+      "## Done when",
       "",
-      '- [ ] _Define what "done" means before execution._',
+      "- [ ] _State the smallest observable delivery contract before execution._",
       "",
       "## Source",
       "",
@@ -792,7 +792,7 @@ function amendPlanArtifact(projectRoot, kind, id, options = {}) {
     let body = artifact.body;
     if (options.title !== undefined) body = replaceTitle(body, options.title);
     if (options.request !== undefined) body = replaceSection(body, "Request", options.request);
-    if (options.acceptance !== undefined) body = replaceSection(body, "Acceptance Criteria", options.acceptance.map((item) => `- [ ] ${normalizeAmendText(item, "Acceptance criterion")}`).join("\n"));
+    if (options.acceptance !== undefined) body = replaceFirstKnownSection(body, ["Done when", "Acceptance Criteria"], options.acceptance.map((item) => `- [ ] ${normalizeAmendText(item, "Delivery criterion")}`).join("\n"));
     if (options.purpose !== undefined) body = replaceFirstKnownSection(body, ["Purpose", "Motivation"], options.purpose);
     if (options.exitCriteria !== undefined) body = replaceFirstKnownSection(body, ["Exit Criteria", "Exit criteria"], options.exitCriteria.map((item) => `- [ ] ${normalizeAmendText(item, "Exit criterion")}`).join("\n"));
     if (options.timebox !== undefined) body = replaceSection(body, "Timebox", options.timebox);

package/lib/runtime/policy-integrity.js

@@ -0,0 +1,83 @@
+"use strict";
+
+// Daily work is intentionally Markdown-first.  This module keeps the
+// enforcement at the boundary: project policy is pinned when ScrumRun is
+// initialized/updated and `doctor --strict` / release audits detect drift.
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function readRegular(file) {
+  if (!fs.existsSync(file) || !fs.lstatSync(file).isFile() || fs.lstatSync(file).isSymbolicLink()) return null;
+  return fs.readFileSync(file, "utf8");
+}
+
+function expectedCoreFingerprint(packageRoot = path.resolve(__dirname, "../..")) {
+  const core = readRegular(path.join(packageRoot, "CORE.md"));
+  return core === null ? null : sha256(core);
+}
+
+function readPolicyIntegrity(scrumDir) {
+  const marker = path.join(scrumDir, "method.json");
+  const raw = readRegular(marker);
+  if (raw === null) return { marker: null, integrity: null, error: "method.json is missing or unsafe" };
+  try {
+    const parsed = JSON.parse(raw);
+    return { marker: parsed, integrity: parsed.integrity || null, error: null };
+  } catch (error) {
+    return { marker: null, integrity: null, error: error.message };
+  }
+}
+
+function sealPolicyIntegrity(scrumDir, { includeGuardrails = false, coreFingerprint = expectedCoreFingerprint() } = {}) {
+  const state = readPolicyIntegrity(scrumDir);
+  if (state.error) throw new Error(`Cannot seal ScrumRun policy: ${state.error}`);
+  const core = readRegular(path.join(scrumDir, "core.md"));
+  if (core === null) throw new Error("Cannot seal ScrumRun policy: core.md is missing or unsafe.");
+  const guardrails = readRegular(path.join(scrumDir, "guardrails.md"));
+  if (guardrails === null) throw new Error("Cannot seal ScrumRun policy: guardrails.md is missing or unsafe.");
+  const next = {
+    ...state.marker,
+    workflow: { ...(state.marker.workflow || {}), daily: "markdown-first" },
+    integrity: {
+      ...(state.integrity || {}),
+      schema: 1,
+      core_sha256: sha256(core),
+      core_package_sha256: coreFingerprint || sha256(core),
+      ...(includeGuardrails || !state.integrity || !state.integrity.guardrails_sha256
+        ? { guardrails_sha256: sha256(guardrails) }
+        : {})
+    }
+  };
+  return `${JSON.stringify(next, null, 2)}\n`;
+}
+
+function auditPolicyIntegrity(scrumDir, { coreFingerprint = expectedCoreFingerprint() } = {}) {
+  const state = readPolicyIntegrity(scrumDir);
+  if (state.error) return [{ severity: "critical", code: "POLICY_MARKER", message: state.error }];
+  const integrity = state.integrity;
+  if (!integrity || integrity.schema !== 1) {
+    return [{ severity: "warning", code: "POLICY_INTEGRITY_UNSEALED", message: "Policy fingerprints are not sealed. Run `scrumrun update --project --seal-policy` after owner review." }];
+  }
+  const findings = [];
+  const core = readRegular(path.join(scrumDir, "core.md"));
+  const guardrails = readRegular(path.join(scrumDir, "guardrails.md"));
+  if (core === null) findings.push({ severity: "critical", code: "CORE_UNSAFE", message: "core.md is missing or unsafe." });
+  else {
+    const actual = sha256(core);
+    if (actual !== integrity.core_sha256) findings.push({ severity: "high", code: "CORE_TAMPERED", message: "core.md differs from the owner-sealed policy. Restore it with `scrumrun update --project`." });
+    if (coreFingerprint && actual !== coreFingerprint) findings.push({ severity: "high", code: "CORE_PACKAGE_DRIFT", message: "core.md differs from the installed ScrumRun Core. Review then run `scrumrun update --project`." });
+  }
+  if (guardrails === null) findings.push({ severity: "critical", code: "GUARDRAILS_UNSAFE", message: "guardrails.md is missing or unsafe." });
+  else if (sha256(guardrails) !== integrity.guardrails_sha256) {
+    findings.push({ severity: "high", code: "GUARDRAILS_TAMPERED", message: "guardrails.md changed after owner sealing. Review it, then explicitly run `scrumrun update --project --seal-policy`." });
+  }
+  return findings;
+}
+
+module.exports = { auditPolicyIntegrity, expectedCoreFingerprint, sealPolicyIntegrity, sha256 };

package/lib/v2/artifacts.js

@@ -17,6 +17,7 @@ function sha256(content) {
 
 function scalar(value) {
   if (value === null || value === undefined) return "null";
+  if (Array.isArray(value)) return `[${value.map((item) => scalar(item)).join(", ")}]`;
   if (typeof value === "boolean" || typeof value === "number") return String(value);
   const text = String(value);
   if (/^[A-Za-z0-9._/-]+$/.test(text)) return text;
@@ -36,6 +37,11 @@ function parseScalar(value) {
       return text;
     }
   }
+  if (text.startsWith("[") && text.endsWith("]")) {
+    const inner = text.slice(1, -1).trim();
+    if (!inner) return [];
+    return inner.split(",").map((item) => parseScalar(item));
+  }
   return text;
 }
 
@@ -102,6 +108,9 @@ function validateArtifact(record, expectedKind = null) {
       errors.push(`${record.kind}.${field} must reference ${target.prefix}-NNN`);
     }
   }
+  if (record.kind === "run" && (record.task === undefined || record.task === null) && (record.sprint === undefined || record.sprint === null)) {
+    errors.push("run must reference TASK-NNN or SPRINT-NNN");
+  }
   for (const [field, constraint] of Object.entries(SCALAR_FIELDS)) {
     if (!constraint.kinds.includes(record.kind)) continue;
     if (constraint.required && (record[field] === undefined || record[field] === null)) {

package/lib/v2/conformance.js

@@ -14,6 +14,7 @@ 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 { auditPolicyIntegrity } = require("../runtime/policy-integrity");
 
 const INVARIANTS = Object.freeze([
   { id: "I-01", summary: "pre-approval work is read-only", tests: ["intake builds bounded context without writing"] },
@@ -79,10 +80,10 @@ function auditProject(projectRoot) {
     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 \`scrumrun update --migrate\` to backfill.`, marker));
+      findings.push(finding("warning", "METHOD_PATHS_MISSING", `method.json is missing a canonical "paths" block. Non-blocking in Markdown-first daily work; run \`scrumrun update --migrate\` if you want the declared index.`, 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));
+      for (const entry of drift) findings.push(finding("warning", "METHOD_PATHS_DRIFT", `method.json paths[${entry.label}] is ${entry.actual === undefined ? "missing" : `"${entry.actual}"`}; expected "${entry.expected}". Non-blocking; regenerate via \`update --migrate\` when convenient.`, 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));
       }
@@ -94,6 +95,7 @@ function auditProject(projectRoot) {
     const file = path.join(scrumDir, relative);
     if (!fs.existsSync(file) || !fs.lstatSync(file).isFile()) findings.push(finding("high", "CANONICAL_MISSING", `${relative} is missing or unsafe.`, file));
   }
+  for (const item of auditPolicyIntegrity(scrumDir)) findings.push(finding(item.severity, item.code, item.message, marker));
   const guardrailsFile = path.join(scrumDir, "guardrails.md");
   const guardrails = fs.existsSync(guardrailsFile) && fs.lstatSync(guardrailsFile).isFile() ? fs.readFileSync(guardrailsFile, "utf8") : "";
   const guardrailValidation = validateGuardrailDocument(guardrails);
@@ -141,9 +143,9 @@ function auditProject(projectRoot) {
         task = null;
       }
     }
-    if (run.record && !run.record.task) {
-      findings.push(finding("high", "RUN_TASK_MISSING", `${run.record.id} has no task reference (record.task is null).`, run.file));
-    } else if (run.record && (!task || task.errors.length)) {
+    if (run.record && !run.record.task && !run.record.sprint) {
+      findings.push(finding("high", "RUN_TARGET_MISSING", `${run.record.id} must reference a Task or Sprint.`, run.file));
+    } else if (run.record && run.record.task && (!task || task.errors.length)) {
       findings.push(finding("high", "RUN_TASK_MISSING", `${run.record.id} references missing or invalid ${run.record.task}.`, run.file));
     }
     if (run.record && task && !task.errors.length && (run.record.sprint || null) !== (task.record.sprint || null)) {
@@ -170,6 +172,7 @@ function auditProject(projectRoot) {
     }
   }
   const byId = new Map(Object.values(records).flat().filter((artifact) => artifact.record).map((artifact) => [artifact.record.id, artifact]));
+  const markdownFirst = methodMarker && methodMarker.workflow && methodMarker.workflow.daily === "markdown-first";
   for (const task of records.task || []) {
     for (const [field, prefix] of [["feature", "FEAT"], ["sprint", "SPRINT"]]) {
       const target = task.record && task.record[field];
@@ -182,7 +185,7 @@ function auditProject(projectRoot) {
   }
   const attemptsByTask = new Map();
   for (const run of records.run || []) {
-    if (!run.record || run.errors.length) continue;
+    if (!run.record || run.errors.length || !run.record.task) continue;
     if (!attemptsByTask.has(run.record.task)) attemptsByTask.set(run.record.task, []);
     attemptsByTask.get(run.record.task).push(run.record.attempt);
   }
@@ -199,11 +202,14 @@ function auditProject(projectRoot) {
       .filter((run) => run.record && !run.errors.length && run.record.task === task.record.id)
       .sort((left, right) => right.record.attempt - left.record.attempt);
     if (!attempts.length) {
+      if (markdownFirst) continue;
       if (["running", "validating", "learning", "partial"].includes(task.record.status)) {
         findings.push(finding(
-          "high",
+          markdownFirst ? "warning" : "high",
           "TASK_ORPHANED",
-          `${task.record.id}.status is ${task.record.status}, but no canonical Run references it. Review with \`scrumrun repair --recover-orphan-tasks\`, then apply the explicit recovery and start the Task to create its first Run.`,
+          markdownFirst
+            ? `${task.record.id}.status is ${task.record.status} without a Run. This is valid Markdown-first work; keep the Task handoff current.`
+            : `${task.record.id}.status is ${task.record.status}, but no canonical Run references it. Review with \`scrumrun repair --recover-orphan-tasks\`, then apply the explicit recovery and start the Task to create its first Run.`,
           task.file
         ));
       }
@@ -219,17 +225,13 @@ function auditProject(projectRoot) {
       blocked: "blocked",
       partial: "partial"
     };
-    if (taskStatuses[latest.status] && task.record.status !== taskStatuses[latest.status]) {
+    if (!markdownFirst && taskStatuses[latest.status] && task.record.status !== taskStatuses[latest.status]) {
       findings.push(finding("high", "TASK_RUN_STATUS_MISMATCH", `${task.record.id}.status ${task.record.status} disagrees with latest ${latest.id}.status ${latest.status}.`, task.file));
     }
   }
-  for (const task of records.task || []) {
-    if (!task.record || task.errors.length) continue;
-    if (["backlog", "proposed", "cancelled"].includes(task.record.status)) continue;
-    if (!/^## Acceptance Criteria\b/m.test(task.body || "")) {
-      findings.push(finding("warning", "ACCEPTANCE_CRITERIA_MISSING", `${task.record.id} has no Acceptance Criteria section; define what "done" means before execution.`, task.file));
-    }
-  }
+  // Task bodies are intentionally extensible Markdown. Project Guardrails may
+  // require sections for selected Tasks; the kernel never requires one global
+  // heading or rejects unknown owner-defined structure.
   for (const sprint of records.sprint || []) {
     if (!sprint.record || sprint.errors.length) continue;
     const heading = /^## Tasks[ \t]*$/m.exec(sprint.body);

package/lib/v2/paths.js

@@ -56,10 +56,11 @@ function flattenPaths(paths = CANONICAL_PATHS, prefix = "") {
   return out;
 }
 
-function renderMethodJson({ methodVersion, layout = "v2", schemas = {}, migratedFrom, migration } = {}) {
+function renderMethodJson({ methodVersion, layout = "v2", schemas = {}, workflow = { daily: "markdown-first" }, migratedFrom, migration } = {}) {
   const payload = {
     method: methodVersion,
     layout,
+    workflow,
     paths_schema: PATHS_SCHEMA_VERSION,
     paths: canonicalPaths(),
     schemas

package/lib/v2/schema.js

@@ -38,8 +38,8 @@ const ARTIFACT_TYPES = deepFreeze({
   task: {
     prefix: "TASK",
     directory: "tasks",
-    initial: ["backlog", "proposed", "running"],
-    statuses: ["backlog", "proposed", "running", "validating", "learning", "partial", "completed", "failed", "blocked", "cancelled"]
+    initial: ["backlog", "proposed", "in_progress", "running"],
+    statuses: ["backlog", "proposed", "in_progress", "running", "validating", "learning", "partial", "completed", "failed", "blocked", "cancelled"]
   },
   sprint: {
     prefix: "SPRINT",
@@ -90,7 +90,7 @@ const ARTIFACT_TRANSITIONS = deepFreeze({
     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"]
+    backlog: ["proposed", "in_progress", "running", "cancelled"], proposed: ["in_progress", "running", "cancelled"], in_progress: ["completed", "failed", "blocked", "cancelled"], running: ["validating", "completed", "failed", "blocked", "cancelled"], validating: ["learning", "completed", "failed", "blocked"], learning: ["completed", "failed", "blocked"], partial: ["in_progress", "running", "cancelled"], failed: ["in_progress", "running", "cancelled"], blocked: ["in_progress", "running", "cancelled"]
   },
   sprint: {
     proposed: ["running", "cancelled"], running: ["partial", "completed", "blocked", "cancelled"], partial: ["running", "completed", "cancelled"], blocked: ["running", "cancelled"]
@@ -108,7 +108,7 @@ const ARTIFACT_TRANSITIONS = deepFreeze({
 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" }
+  task: { targetKind: "task", cardinality: "0..1", meaning: "atomic work executed or reviewed by the artifact" }
 });
 
 const SCALAR_FIELDS = deepFreeze({
@@ -120,9 +120,9 @@ const SCALAR_FIELDS = deepFreeze({
 
 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" },
+  task: { question: "What concrete outcome is intended?", truth: "scope, owner-defined sections, links, and status" },
+  sprint: { question: "Which Tasks are grouped for this delivery?", truth: "timebox or delivery-batch membership; may be feature, fix, or maintenance" },
+  run: { question: "What happened while executing a Task or Sprint?", truth: "optional human-readable execution record and outcome" },
   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" },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "scrumrun",
-  "version": "3.1.1",
-  "description": "Evidence-driven Agile runtime and semantic project memory for AI coding agents.",
+  "version": "4.0.0",
+  "description": "Markdown-first Agile memory and guardrails for AI coding agents.",
   "bin": {
     "scrumrun": "bin/scrumrun.js",
     "sr-claude": "bin/claude-install.js"

package/scripts/generate-contract-docs.js

@@ -69,7 +69,7 @@ Every artifact also requires \`id\`, \`kind\`, \`status\`, \`created\`, \`update
 |---|---|---|---|
 ${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.
+Task is the atomic unit. A Task may have zero or one Sprint. A Run is optional Markdown history and may reference either a Task or a Sprint; it never controls Task status in Markdown-first work. Sprint membership is authoritative on \`Task.sprint\`; a Sprint's \`## Tasks\` list is a human-readable projection that must agree with it. Additional owner-defined relations such as \`depends_on: [TASK-014, DEC-018]\` are preserved as local Markdown graph data.
 
 ## Scalar constraints
 
@@ -85,7 +85,7 @@ Newly authored Runs use \`ledger: ${RUN_LEDGER_VERSION}\`. Their \`## Events\` s
 
 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.
+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 when a strict audit Run is used. Run owns optional event history; Task Markdown owns the delivered scope and status in normal work.
 
 ## Truth questions
 

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

@@ -1,6 +1,9 @@
 {
   "method": "2.0.0",
   "layout": "v2",
+  "workflow": {
+    "daily": "markdown-first"
+  },
   "paths_schema": 1,
   "paths": {
     "guardrails": "guardrails.md",

package/templates/project/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md - {{PROJECT_NAME}}
 
-## ScrumRun 3.1 — Markdown-first
+## ScrumRun 4.0 — execution-first Markdown
 
 This project uses ScrumRun. The method is mandatory; the direct CLI is `scrumrun <noun> <subject> <action>`. `/sc` is only an optional client shortcut.
 
@@ -15,18 +15,24 @@ Natural-language product requests begin with a read-only understanding pass. Bef
 
 After approval:
 
-- Task is the atomic work item; create or refine its Markdown directly, define its `## Acceptance Criteria`, and retain a short `## Technical Summary` / `## Follow-ups` handoff;
+- execute continuously until the approved Task is delivered: keep working through discover → implement → verify → fix → verify. A progress report is allowed only when the owner asks for status and must be followed immediately by more execution; it never closes the workflow. Do not stop to send an inventory, a progress report, a decomposition, or a list of work still to do. A missing implementation found during the work remains work to do now, not a follow-up, a “next step”, or a reason to reply. Stop only for an owner decision, external access, an explicit Guardrail, a security/secret risk, destructive work without approval, or an unmet required Acceptance Criterion;
+- Task is the atomic work item; create or refine its Markdown directly, define a short `## Done when` delivery contract, and retain a short `## Completion` / `## Follow-ups` handoff;
+- you may decompose implementation privately or add linked child Tasks when needed, but do not make the owner manage that decomposition and do not stop after planning it;
 - validation is scoped: only a test/review/environment explicitly required by the owner, the Task's Acceptance Criteria, or an active Guardrail can block completion; a missing optional E2E suite is a documented follow-up/risk, never a reason to fail an otherwise accepted Task;
 - Feature and Sprint remain useful organization, but are optional; create them only when they clarify real initiative or timebox context;
 - Sprint is only a real timebox/batch of Tasks;
 - Run is an optional audit/handoff record, never an administrative prerequisite to start, amend, or complete a Task; preserve useful prior attempts but do not let missing/invalid Run metadata stop work;
-- record a `## Technical Summary` at completion so the next agent inherits what was done; record optional missing coverage in `## Follow-ups`;
+- only claim a condition validated when the check actually covers that condition; a narrow checker never proves a broad delivery claim. Record a `## Completion` at completion so the next agent inherits what was done; `## Follow-ups` may contain only work outside the approved `## Done when`, never unfinished acceptance work;
 - work directly in code and Task Markdown after approval; do not call `npx scrumrun@latest` or normal `scrumrun plan/run` commands during execution;
 - use the CLI only for `init`, `update --project`, `migrate`, `repair`, `doctor`, reports, or release checks. It audits/repairs the folder; it does not own the daily workflow;
 - never invoke `plan run --fail`, `--block`, `--retry`, `--finalize`, `--complete`, `--validate`, or `plan task --start` in normal work. A failed legacy Run due to administrative state remains historical; write the corrected delivery outcome directly in the Task instead;
-- learning proposes evidence-backed Knowledge, Decisions, or candidate Insights when the work reveals reusable context;
+- learning proposes evidence-backed Knowledge, Decisions, or candidate Insights after delivery, or only when it materially helps the current implementation; it never interrupts execution;
 - guardrails remain mandatory: stop only for an explicit Guardrail, security/secret risk, destructive action without approval, or an unmet required Acceptance Criterion. Status vocabulary, missing Runs, unavailable optional tests, and stale generated state are warnings to reconcile, not blockers.
 
+`core.md` and `guardrails.md` are sealed policy. Never edit either during a product Task. A policy change requires an explicit owner request; after review, seal it at the maintenance edge with `scrumrun update --project --seal-policy`.
+
+Artifacts are local Markdown connected by stable IDs and relative links. Preserve any owner-defined frontmatter and sections in a Task. A Guardrail may require sections such as `## Migration Plan`, `## Rollback`, or `## Guardrail Evidence`; add them only to the affected Task.
+
 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.
 
 Never use `npx scrumrun@latest` in the normal work loop. If the installed CLI is unavailable, stop and report that blocker rather than substituting a network command.

package/templates/project-lean/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md - {{PROJECT_NAME}}
 
-## ScrumRun 3.1 lean read policy — Markdown-first
+## ScrumRun 4.0 lean read policy — execution-first Markdown
 
 This project stores the complete ScrumRun v2 truth but uses a bounded default read path:
 
@@ -11,12 +11,16 @@ This project stores the complete ScrumRun v2 truth but uses a bounded default re
 
 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 a read-only understanding pass. Explicit approval authorizes direct work in source files and `.scrumrun/` Markdown. Define the Task's `## Acceptance Criteria` before execution and record a `## Technical Summary` at completion. A Run is optional handoff/audit context, not a state machine that may prevent starting, amending, or completing work. A Sprint exists only for a real batch/timebox.
+Natural-language product work begins as a read-only understanding pass. Explicit approval authorizes direct work in source files and `.scrumrun/` Markdown. Execute continuously until the approved Task is delivered: keep working through discover → implement → verify → fix → verify. A progress report is allowed only when the owner asks for status and must be followed immediately by more execution; it never closes the workflow. Do not stop to provide an inventory, a partial progress report, or a list of remaining work. A missing implementation found during the work remains work to do now, not a follow-up or “next step”. Define a short `## Done when` delivery contract, record `## Completion` only at the end, and never move unfinished contract work to `## Follow-ups` without explicit owner approval. A Run is optional handoff/audit context, not a state machine that may prevent starting, amending, or completing work. A Sprint exists only for a real batch/timebox.
 
 Guardrails are mandatory, but administrative state is not: block only for an explicit Guardrail, security/secret risk, destructive action without approval, or an unmet required Acceptance Criterion. Missing Runs, invalid legacy status vocabulary, stale generated views, and optional unrun tests are warnings to reconcile in Markdown. Record meaningful optional coverage gaps under `## Follow-ups`; they do not fail a delivered Task.
 
 `.scrumrun/guardrails.md` is canonical policy. Never bypass it, overwrite owner work, auto-confirm AI knowledge, auto-migrate v1 state, or print vault values.
 
+`core.md` and `guardrails.md` are sealed policy. Never edit them during a product Task. A policy change requires an explicit owner request and `scrumrun update --project --seal-policy` after review.
+
+Artifacts are local Markdown connected by stable IDs and relative links. Preserve owner-defined frontmatter and sections in each Task; Guardrails may require a section only on affected Tasks.
+
 Use the installed CLI only for `init`, `update --project`, `migrate`, `repair`, `doctor`, reports, and release checks. For daily product work, follow `.scrumrun/core.md` and edit the relevant Markdown directly.
 
 Never invoke `plan run --fail`, `--block`, `--retry`, `--finalize`, `--complete`, `--validate`, or `plan task --start` during normal work. If an old Run says failed for an administrative reason, leave it as history and record the actual delivered outcome in the Task's Technical Summary and Follow-ups.