scrumrun 3.1.2 → 4.0.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+## 4.0.0 - 2026-08-31
+
+### Changed
+
+- **Simple Markdown model.** Core, Guardrails, Knowledge, Feature, Sprint, Task, Run, and Backlog are one local Markdown graph connected by stable IDs and relative links. Derived cache/index data is optional and never required for normal work.
+- **Execution-first.** An approved Task continues through discover → implement → verify → fix → verify. Intermediate inventories, progress reports, and discovered in-scope gaps are internal work, never a valid stopping point or Follow-up.
+- **Flexible Task bodies.** Tasks preserve arbitrary owner frontmatter and sections. `## Done when` and `## Completion` are the packaged minimal convention; project Guardrails may require extra sections only for affected Tasks.
+- **Human status vocabulary.** `in_progress` is accepted as a Task status. A Markdown-first Task neither needs a Run nor must agree with historical Run state.
+- **Runs are optional.** A Run may record a Task or a Sprint execution, but no Run, ledger, permit, or CLI state transition can block daily delivery.
+
+### Safety
+
+- **Sealed Markdown policy.** Fresh and refreshed projects pin Core and Guardrail fingerprints. Agents do not edit policy during product work; owner-reviewed policy changes use `scrumrun update --project --seal-policy`. Strict doctor/release audits detect policy drift at the edge, not during every edit.
+
 ## 3.1.2 - 2026-08-31
 
 ### Fixed

package/CORE.md

@@ -84,13 +84,21 @@ AGENTS.md
 
 **Before querying project state, read `.scrumrun/method.json`.** Its `paths` block is the authoritative index of every canonical location in this project. Navigate by that index; if a path is not declared there, it is not canonical truth. Directory listing and grep are fallbacks — never the first step. A ScrumRun-aware agent must never search for `goals/`, `backlog.md`, `sprint.md`, or any legacy layout: those are absent by design once migration completes and are surfaced only through `.scrumrun/.migration-backup/`.
 
-**Markdown is the normal runtime.** After explicit approval, work directly in source files and relevant `.scrumrun/` Markdown. A Task is free to be created, refined, started, completed, and handed off in Markdown; a Run is optional audit context, never a state machine that can prevent daily work. Update the Task's scope, Acceptance Criteria, Technical Summary, and Follow-ups directly. Do not use `npx scrumrun@latest` or normal `scrumrun plan/run` commands during execution.
+**Markdown is the normal runtime.** After explicit approval, work directly in source files and relevant `.scrumrun/` Markdown. A Task is free to be created, refined, started, completed, and handed off in Markdown; a Run is optional audit context, never a state machine that can prevent daily work. Update the Task's scope, Done when, Completion, and Follow-ups directly. Do not use `npx scrumrun@latest` or normal `scrumrun plan/run` commands during execution.
+
+**Execution is continuous.** Once the owner approves a Task, implement it through its delivery contract before replying. Keep using tools and editing files through the full loop: discover → implement → verify → fix → verify. A progress report is allowed only when the owner asks for status, and it must be followed immediately by more execution in the same workflow; it is never an endpoint. Do not stop to give an inventory, a progress report, a decomposition, or a remaining-work list: those are internal steps, not a deliverable. A discovery of missing code, literals, tests, migrations, or configuration inside the approved contract is required work to implement now — it cannot become a report, a partial checker, a “next step”, or a Follow-up. Stop only for an owner decision, external access, an explicit Guardrail, a secret/security risk, destructive work without approval, or an unmet required delivery criterion. A Task's `## Done when` is short and observable; `## Follow-ups` contains only work outside that contract. Never move unfinished contract work to Follow-ups without explicit owner approval.
+
+**Verification must cover the claim.** Never claim that a Task condition is verified merely because a narrower check passes. If the request is “no visible hardcoded literals”, a locale-key parity checker alone is insufficient: scan the relevant views for literals, replace every result in scope, then re-run both the scan and the build. The same rule applies to every delivery claim.
 
 **The CLI is maintenance, not a work gate.** Use it for `init`, `update --project`, `migrate`, `repair`, `doctor`, reports, and release checks. Strict per-edit permits and ledger finalization remain available only when the owner asks for that audit level. Missing/invalid Runs, old status vocabulary, stale projections, and optional tests are warnings to reconcile in Markdown — never an automatic blocker.
 
-**Block only on real constraints.** An agent must stop for an explicit active Guardrail, secret/security risk, destructive action without approval, or an unmet required Acceptance Criterion. It must not manufacture a failed/blocked Run because optional E2E coverage, an optional reviewer, or a non-required environment is unavailable; record meaningful gaps in `## Follow-ups` or a risk note.
+**Block only on real constraints.** An agent must stop for an explicit active Guardrail, secret/security risk, destructive action without approval, or an unmet required Done when item. It must not manufacture a failed/blocked Run because optional E2E coverage, an optional reviewer, or a non-required environment is unavailable; record meaningful gaps in `## Follow-ups` or a risk note.
+
+**Normal operation never mutates Run state through the CLI.** Do not call `plan run --fail|--block|--retry|--finalize|--complete|--validate` or `plan task --start` in daily work. Those are owner-requested strict audit tools only. When a legacy Run already has the wrong administrative outcome, preserve it as history and correct the delivery record directly in the Task's Completion and Follow-ups.
+
+**Policy is sealed at the edge.** `core.md` is the universal execution contract and `guardrails.md` is project policy. Never edit either while delivering product work. A policy change requires an explicit owner request; after review, `scrumrun update --project --seal-policy` records fresh fingerprints. Daily work stays Markdown-only; `doctor --strict` and release audit policy fingerprints, canonical guardrails, and code checks at the boundary.
 
-**Normal operation never mutates Run state through the CLI.** Do not call `plan run --fail|--block|--retry|--finalize|--complete|--validate` or `plan task --start` in daily work. Those are owner-requested strict audit tools only. When a legacy Run already has the wrong administrative outcome, preserve it as history and correct the delivery record directly in the Task's Technical Summary and Follow-ups.
+**Markdown relations are the graph.** Every artifact has a stable ID. Use small frontmatter links such as `sprint: SPRINT-012`, `feature: FEAT-003`, and `depends_on: [TASK-151, DEC-008]`, plus a human-readable `## Related` section with relative links. Preserve all unknown frontmatter and all owner-defined sections. A Guardrail may require a Task section such as `## Migration Plan`, `## Rollback`, or `## Guardrail Evidence`; add it only to the affected Task and keep it until the rule is satisfied.
 
 Canonical truth is Markdown. SQLite/cache data stores only rebuildable indexes, symbol projections, relations, and bounded context packages. Deleting `.cache/` must never delete authored truth.
 
@@ -176,7 +184,7 @@ understand → approve → work → validate required criteria → hand off
 
 Rules:
 
-- a Task carries the intended scope, `## Acceptance Criteria`, `## Technical Summary`, and relevant `## Follow-ups`;
+- a Task carries intended scope, a short `## Done when` contract, `## Completion`, and relevant `## Follow-ups`;
 - validation matches risk and acceptance criteria; tests, reviews, and environments are gates only when explicitly required by the owner, the Task, or an active Guardrail;
 - direct Markdown workflow never blocks on Run linkage, status syntax, stale generated views, or missing optional coverage. If an optional check matters, record it as a follow-up/risk instead of fabricating failure;
 - configured reviews run only when a Guardrail requires one;
@@ -184,7 +192,7 @@ Rules:
 - strict permits, workspace-drift checks, and append-only Guardrail obligations apply only to that optional strict audit path;
 - learning proposes memory candidates when work reveals reusable context and never auto-confirms AI inference;
 - complete a Sprint only when its included Tasks meet its real exit gate;
-- do not mark work complete merely because time or token budget ended.
+- do not mark work complete merely because time or token budget ended, and do not stop an approved Task merely to report intermediate progress.
 
 Canonical mutations are schema-validated, lossless, and atomic. Preserve unknown fields, prose, and unrelated owner edits. A failed mutation must leave canonical state unchanged or recoverable.
 

package/README.md

@@ -4,30 +4,33 @@
 
 ScrumRun gives an agent a small command surface and a precise project memory: what should be done, how each attempt happened, which decisions constrain the code, and why the architecture exists in its current form.
 
-**Package:** `3.1.2` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+**Package:** `4.0.0` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
 
 **New here?** Read the [Quickstart](docs/QUICKSTART.md) — first Run in under 10 minutes, no `SPEC.md` reading required. Full docs map in [`docs/INDEX.md`](docs/INDEX.md).
 
 ## The model
 
 ```text
-Feature = why the initiative matters
-Task    = what atomic work must be done
-Sprint  = when Tasks are grouped as a timebox/batch
-Run     = how one concrete attempt happened
-Memory  = what the project learned and why
+Core       = how the agent works
+Guardrails = rules that cannot be broken
+Knowledge  = what the project knows and why
+Backlog    = provisioned Tasks not yet started
+Feature    = why a larger initiative exists
+Sprint     = a feature, fix, or maintenance delivery grouping Tasks
+Task       = concrete work, independent or in a Sprint
+Run        = optional record of what happened while executing a Task/Sprint
 ```
 
 ```text
-FEAT-003
+SPRINT-012 (type: fix)
    └── TASK-018
-          ├── executed_by → RUN-044
-          ├── included_in → SPRINT-012
-          ├── constrained_by → DEC-018
-          └── generated → INS-041
+          ├── feature → FEAT-003
+          ├── depends_on → TASK-014, DEC-018
+          ├── guardrails → GR-004
+          └── run → RUN-044 (optional)
 ```
 
-A Task does not need a Sprint. A retry creates a new Run. A fix is a Task with `type: fix`; backlog is a view of backlog Tasks.
+A Task does not need a Sprint. A Sprint may be `feature`, `fix`, or `maintenance`. A Run is optional and may document a Task or Sprint. Backlog is simply Tasks with `status: backlog`.
 
 See [`docs/SCHEMA.md`](docs/SCHEMA.md) for the generated executable contract and [`docs/ENTITY-MODEL.md`](docs/ENTITY-MODEL.md) for the conceptual guide.
 
@@ -79,15 +82,15 @@ RECEIVED → CONTEXTUALIZING → POLICY → RISK → CLASSIFICATION
 
 The agent may assert the classification (`--type fix|task|feature|docs|discovery`) and attach a short technical preview (`--preview "…"`), rendered with color in the terminal before any Task exists. Nothing canonical is persisted before approval.
 
-Explicit approval authorizes work. In 3.1, the daily runtime is the `.scrumrun/` folder: the agent creates or refines the relevant Task Markdown, works in code, and leaves a short handoff. Feature, Sprint, and Run are optional context, not prerequisites. A structured CLI audit path remains available when a team wants it.
+Explicit approval authorizes work. In 4.0, the daily runtime is the `.scrumrun/` folder: the agent creates or refines the relevant Task Markdown, works in code, and leaves a short handoff. Feature, Sprint, and Run are optional context, not prerequisites. A structured CLI audit path remains available only at maintenance/release edges.
 
 ```text
 EXECUTING → VALIDATING → LEARNING → COMPLETED | FAILED | BLOCKED
 ```
 
-Every Task carries `## Acceptance Criteria` so "done" is defined before work begins. After approval, the agent works directly in code and Task Markdown, updating `## Technical Summary` and `## Follow-ups`. The normal close is simply the documented Task handoff — no CLI transition is required.
+Every Task carries a short `## Done when` delivery contract. After approval, the agent works directly in code and Task Markdown until that contract is delivered: it keeps the full discover → implement → verify → fix → verify loop running. A report is allowed only when you ask for it and never ends execution. The normal close is a concise `## Completion`; `## Follow-ups` may only contain work outside the agreed contract. No CLI transition is required.
 
-Guardrails still apply. An agent stops only for an explicit active Guardrail, a secret/security risk, destructive work without approval, or an unmet required Acceptance Criterion. Tests, reviews, and environments are gates only when the owner, Acceptance Criteria, or a Guardrail explicitly requires them. Optional missing E2E coverage is a follow-up/risk, not a failed Task.
+Guardrails still apply. An agent stops only for an explicit active Guardrail, a secret/security risk, destructive work without approval, or an unmet required delivery criterion. Tests, reviews, and environments are gates only when the owner, `Done when`, or a Guardrail explicitly requires them. Optional missing E2E coverage is a follow-up/risk, not a failed Task.
 
 Use the CLI at the edges, where its safety is valuable:
 
@@ -99,6 +102,10 @@ scrumrun repair --recover-orphan-tasks --apply
 scrumrun review release --run
 ```
 
+`core.md` and `guardrails.md` are sealed Markdown policy. Agents never edit them during normal product work. An owner-requested policy change is reviewed and then sealed explicitly with `scrumrun update --project --seal-policy`; `doctor --strict` and release checks detect later policy drift.
+
+Relations are plain, offline Markdown: stable IDs in frontmatter (`sprint: SPRINT-012`, `depends_on: [TASK-014, DEC-018]`) and relative links in `## Related`. Task Markdown is intentionally extensible: a Guardrail can require `## Migration Plan`, `## Rollback`, or `## Guardrail Evidence` only where relevant, and ScrumRun preserves every unknown section.
+
 `update --project` refreshes packaged `core.md` and recognized generated `AGENTS.md` with a local byte-exact backup before replacing them. The CLI can still generate/validate Task, Feature, Sprint, and Run records when desired, but it must never become a routine blocker.
 
 For extra protection, CLI Task start/retry and every Run state transition require `--strict`. This prevents accidental administrative failures in the normal Markdown-first workflow.
@@ -161,12 +168,18 @@ It is progressive disclosure: the briefing is enough for most work; the agent fo
 
 ## Migrating an ongoing v1 project
 
-Update the client integrations. For an existing project, refresh the Markdown-first guidance explicitly:
+Update the client integrations. For an existing project, refresh the execution-first guidance explicitly:
 
 ```bash
 scrumrun update --project
 ```
 
+If you intentionally changed project Guardrails after owner review, seal the reviewed Markdown policy once:
+
+```bash
+scrumrun update --project --seal-policy
+```
+
 This shows the source inventory, proposed mappings, and blockers without changing project data. Apply only the verified plan with:
 
 ```bash

package/SPEC.md

@@ -83,6 +83,8 @@ method: 2.0.0
 
 IDs, filenames, kind, status, real ISO dates, and method version must agree. Unknown fields and authored prose are preserved. Duplicate fields, malformed frontmatter, unsafe paths, and symlinked canonical paths are invalid.
 
+Relationship lists are valid local frontmatter, for example `depends_on: [TASK-014, DEC-018]` and `guardrails: [GR-004]`. Human-readable `## Related` links use relative Markdown paths. These local IDs and links are the canonical graph; generated indexes only accelerate retrieval.
+
 A Task may carry an optional `assignee` scalar recording the agent identity (`SCRUMRUN_AGENT` or `config.md` `Agent Identity`) that owns the work. It is descriptive metadata, never a competing authority: it does not change status transitions or block conformance.
 
 ### 3.2 Stable identifiers
@@ -200,13 +202,15 @@ RECEIVED
 
 Everything through `AWAITING_APPROVAL` is read-only. It may exist in process memory or ignored cache only. A valid approval token binds the normalized request, policy result, classification, risk, issuance time, canonical context fingerprint, and complete workspace fingerprint. Canonical or source drift after planning invalidates approval.
 
-Approval authorizes work after the read-only planning pass. In Markdown-first mode, a Task and optional Run may be created or updated directly; their absence or imperfect administrative metadata never prevents approved work. The CLI's atomic Task/Run creation remains an optional strict/audit path. Tests, reviews, and environments are completion gates only when explicitly required by the owner, the Task's Acceptance Criteria, or an active Guardrail; missing optional coverage is a documented follow-up/risk, not a failure by itself.
+Approval authorizes work after the read-only planning pass. In Markdown-first mode, a Task and optional Run may be created or updated directly; their absence or imperfect administrative metadata never prevents approved work. The CLI's atomic Task/Run creation remains an optional strict/audit path. Tests, reviews, and environments are completion gates only when explicitly required by the owner, the Task's `## Done when` contract, or an active Guardrail; missing optional coverage is a documented follow-up/risk, not a failure by itself.
+
+An approved Task executes continuously to its delivery contract. An agent must not end a work turn merely to provide inventory, decomposition, progress, or a list of remaining implementation work. Those are internal execution steps. It may stop only for an owner decision, external access, an active Guardrail, secret/security risk, destructive work without approval, or an unmet required contract item. `## Follow-ups` may contain only work outside `## Done when`; moving required work there requires explicit owner approval.
 
 When a structured Run is explicitly chosen, it binds the exact Guardrail-policy fingerprint and workspace baseline. Strict audit then verifies the complete delta: policy freshness, read-only boundaries, symlink safety, scannability, newly introduced secret-like content, and evidence for every Guardrail. Strict teams may opt into short-lived, path-scoped permits and per-edit recording. This audit path is never a prerequisite for ordinary Markdown-first execution.
 
-The agent may assert the classification explicitly (`--type fix|task|feature|docs|discovery`), overriding keyword inference with validation and a stable reason. It may attach a short technical preview (`--preview`), rendered in the terminal, bound into the approval token, and stored as `## Preview` on the approved Task. A Task declares its `## Acceptance Criteria` before execution; completion is measured against them, never against elapsed time or token budget.
+The agent may assert the classification explicitly (`--type fix|task|feature|docs|discovery`), overriding keyword inference with validation and a stable reason. It may attach a short technical preview (`--preview`), rendered in the terminal, bound into the approval token, and stored as `## Preview` on the approved Task. A Task normally declares a concise `## Done when` contract before execution, but owner-defined Markdown sections remain valid; completion is measured against the agreed delivery contract, never against elapsed time or token budget.
 
-When a structured Run is used, CLI transitions synchronously update the linked Task and append one event to its ledger. This is an optional audit path, not daily operational authority. Markdown-first completion records the Acceptance Criteria, Technical Summary, validation evidence, and Follow-ups directly on the Task. Multi-file CLI mutations use a durable local transaction journal; `doctor --recover` and `repair` remain explicit maintenance operations. Entering learning may extract candidates, but no administrative artifact failure blocks approved work.
+When a structured Run is used, CLI transitions synchronously update the linked Task and append one event to its ledger. This is an optional audit path, not daily operational authority. Markdown-first completion records the Done when contract, Completion, validation evidence, and Follow-ups directly on the Task. Multi-file CLI mutations use a durable local transaction journal; `doctor --recover` and `repair` remain explicit maintenance operations. Entering learning may extract candidates, but no administrative artifact failure blocks approved work.
 
 Backlog is a queue view of intentionally parked Tasks, ordered oldest-first by id. CLI `--next`/`--start` helpers may create a structured Run when wanted, but an explicit owner approval is the only daily-work start gate.
 

package/bin/scrumrun.js

@@ -39,6 +39,7 @@ const { indexPath, indexStatus, mapStatus, queryIndex, rebuildIndex, writeMap }
 const { auditProject } = require(path.join(root, "lib", "v2", "conformance"));
 const { recoverPendingTransactions, previewPendingRecovery } = require(path.join(root, "lib", "v2", "transaction"));
 const { containsSecret } = require(path.join(root, "lib", "security", "secrets"));
+const { sealPolicyIntegrity } = require(path.join(root, "lib", "runtime", "policy-integrity"));
 
 const COMMANDS = ["sc"];
 const COMPATIBILITY_COMMANDS = Object.keys(COMMAND_ALIASES);
@@ -58,7 +59,7 @@ Usage:
   scrumrun <noun> <subject> <action> [args]
   scrumrun sc <noun> <subject> <action> [args]  # compatibility alias
   scrumrun install [all|codex|opencode|claude] [--force]
-  scrumrun update  [all|codex|opencode|claude] [--project] [--migrate] [--verbose]
+  scrumrun update  [all|codex|opencode|claude] [--project] [--seal-policy] [--migrate] [--verbose]
   scrumrun init [--local|--shared] [--lean] [--no-agent-hint] [--force]
   scrumrun status
   scrumrun core [--path|--prompt]
@@ -380,10 +381,13 @@ function refreshProjectGuidance(cwd = process.cwd()) {
   } else {
     results.push({ status: "skipped", dest: `${agentsFile} (not recognized as ScrumRun-generated)` });
   }
+  const marker = path.join(cwd, ".scrumrun", "method.json");
+  const sealed = writeFile(marker, sealPolicyIntegrity(path.join(cwd, ".scrumrun")), { backup: true });
+  results.push({ status: sealed.changed ? "updated" : "skipped", dest: marker, backup: sealed.backup });
   return results;
 }
 
-function updateInstallation(target, { migrate = false, project = false, verbose = false } = {}) {
+function updateInstallation(target, { migrate = false, project = false, sealPolicy = false, verbose = false } = {}) {
   installVerbose = verbose;
   installSummary.cleaned = 0;
   installSummary.written = 0;
@@ -391,7 +395,14 @@ function updateInstallation(target, { migrate = false, project = false, verbose
   installSummary.targets.length = 0;
   const migration = migrate ? migrationPreflightOnUpdate({ apply: true }) : { status: "skipped" };
   install(target, true, { compatibility: true });
+  if (sealPolicy && !project) throw new Error("`--seal-policy` requires `--project` so the owner-reviewed project policy is explicit.");
   const projectResults = project ? refreshProjectGuidance() : [];
+  if (sealPolicy && project) {
+    const scrumDir = path.join(process.cwd(), ".scrumrun");
+    const marker = path.join(scrumDir, "method.json");
+    const sealed = writeFile(marker, sealPolicyIntegrity(scrumDir, { includeGuardrails: true }), { backup: true });
+    projectResults.push({ status: sealed.changed ? "updated" : "skipped", dest: marker, backup: sealed.backup });
+  }
   if (migrate && v2Project()) {
     try {
       refreshState(path.join(process.cwd(), ".scrumrun"));
@@ -1706,7 +1717,12 @@ function executeRootRoute(route) {
   }
   if (noun === "config" && subject === "update") {
     const target = ["all", "codex", "opencode", "claude"].includes(routeArgs[0]) ? routeArgs[0] : "all";
-    return updateInstallation(target, { migrate: !routeArgs.includes("--no-migrate"), verbose: routeArgs.includes("--verbose") });
+    return updateInstallation(target, {
+      migrate: routeArgs.includes("--migrate"),
+      project: routeArgs.includes("--project"),
+      sealPolicy: routeArgs.includes("--seal-policy"),
+      verbose: routeArgs.includes("--verbose")
+    });
   }
   if (noun === "config" && subject === "init") {
     const localMode = routeArgs.includes("--local");
@@ -2322,6 +2338,8 @@ function promptCommand(parts) {
 
 function initProject({ force, mode, agentHint, lean }) {
   const cwd = process.cwd();
+  const marker = path.join(cwd, ".scrumrun", "method.json");
+  const markerExisted = fs.existsSync(marker);
   const vars = {
     PROJECT_NAME: path.basename(cwd),
     DATE: new Date().toISOString().slice(0, 10)
@@ -2332,6 +2350,10 @@ function initProject({ force, mode, agentHint, lean }) {
 
   results.push(...copyDir(path.join(projectTemplate, ".scrumrun"), path.join(cwd, ".scrumrun"), { force, vars }));
   results.push(copyFile(path.join(root, "CORE.md"), path.join(cwd, ".scrumrun", "core.md"), { force, vars }));
+  if (force || !markerExisted) {
+    const sealed = writeFile(marker, sealPolicyIntegrity(path.join(cwd, ".scrumrun"), { includeGuardrails: true }), { backup: false });
+    results.push({ status: sealed.changed ? "written" : "skipped", dest: marker, backup: sealed.backup });
+  }
   results.push(ensureProjectIgnore(cwd));
 
   if (mode === "shared" || agentHint) {
@@ -2611,8 +2633,9 @@ function doctor(target = "all", { compatibility = false, strict = false, recover
       console.log(`miss ScrumRun project audit: ${scrumDir}`);
     } else {
       const audit = auditProject(process.cwd());
-      ok = ok && audit.passed && audit.findings.length === 0;
-      console.log(`${audit.passed && audit.findings.length === 0 ? "ok " : "fail"} ScrumRun project audit: ${audit.findings.length} finding(s)`);
+      const blocking = audit.findings.filter((item) => ["critical", "high"].includes(item.severity));
+      ok = ok && audit.passed && blocking.length === 0;
+      console.log(`${audit.passed && blocking.length === 0 ? "ok " : "fail"} ScrumRun project audit: ${audit.findings.length} finding(s)`);
       for (const item of audit.findings) console.log(`  ${item.severity} ${item.code}: ${item.message}`);
     }
   }
@@ -2633,7 +2656,7 @@ if (!command || command === "--help" || command === "-h") {
   console.log(`ScrumRun ${version}`);
 } else if (command === "install" || command === "update") {
   const target = ["all", "codex", "opencode", "claude"].includes(args[1]) ? args[1] : "all";
-  if (command === "update") updateInstallation(target, { migrate: args.includes("--migrate"), project: args.includes("--project"), verbose: args.includes("--verbose") });
+  if (command === "update") updateInstallation(target, { migrate: args.includes("--migrate"), project: args.includes("--project"), sealPolicy: args.includes("--seal-policy"), verbose: args.includes("--verbose") });
   else install(target, true, { compatibility: false });
 } else if (command === "sc") {
   runRoot(args.slice(1));

package/docs/COMMANDS.md

@@ -1,4 +1,4 @@
-# ScrumRun 3.1 Command Reference
+# ScrumRun 4.0 Command Reference
 
 The canonical grammar is:
 
@@ -27,13 +27,13 @@ scrumrun plan run --satisfy-guardrail RUN-NNN --guardrail GR-NNN [typed evidence
 scrumrun plan challenge <question>
 ```
 
-Normal execution is Markdown-first: after approval, work in code and the relevant Task Markdown, then record the Technical Summary and any Follow-ups directly. A Run/`--finalize` checkpoint is optional strict audit, never a prerequisite. Mutation permits are available only for explicitly requested strict mode.
+Normal execution is Markdown-first: after approval, work in code and the relevant Task Markdown through discover → implement → verify → fix → verify, then record `## Completion` and any genuinely out-of-scope Follow-ups directly. A Run/`--finalize` checkpoint is optional strict audit, never a prerequisite. Mutation permits are available only for explicitly requested strict mode.
 
 The CLI refuses Task start/retry and all Run state changes unless `--strict` is present. This prevents an agent from accidentally manufacturing a failed/blocked retry during normal work; `--strict` is for an owner-requested audit only.
 
 `--amend` is an optional structured helper. The Markdown-first workflow may adjust Task/Feature/Sprint content directly, preserving a useful handoff. Use the CLI when atomic relation synchronization or machine audit is valuable; do not let status vocabulary or missing relations stop approved work.
 
-Every new Task starts with a `## Validation Scope`: only checks explicitly required by the owner, Acceptance Criteria, or an active Guardrail block completion. Missing optional E2E, integration, or review coverage belongs in a follow-up/risk note; it must not be used to mark the Run failed.
+Every new Task starts with `## Done when` and `## Validation Scope`: only checks explicitly required by the owner, Done when contract, or an active Guardrail block completion. A discovered in-scope gap remains work to implement, not a status report or Follow-up. Missing optional E2E, integration, or review coverage belongs in a follow-up/risk note; it must not be used to mark the Run failed.
 
 ## What can be changed
 
@@ -82,14 +82,14 @@ scrumrun review release --run
 ```text
 scrumrun config project --show|--language|--interaction|--approval|--quick-tasks
 scrumrun config init --local|--shared|--lean|--no-agent-hint|--force
-scrumrun config update [all|codex|opencode|claude] [--project] [--migrate]
+scrumrun config update [all|codex|opencode|claude] [--project] [--seal-policy] [--migrate]
 scrumrun config migrate --to 2 --dry-run|--apply|--rollback
 scrumrun config doctor [all|codex|opencode|claude] [--strict] [--recover]
 scrumrun config uninstall --force
 scrumrun config help <topic>
 ```
 
-Top-level CLI aliases (`init`, `update`, `migrate`, `doctor`, `uninstall`, `status`) remain available for shell automation. `update --project` refreshes the packaged Markdown-first Core and recognized generated agent instructions with local backup; ordinary update does not inspect migrations, while `--migrate` explicitly does so and applies the verified plan.
+Top-level CLI aliases (`init`, `update`, `migrate`, `doctor`, `uninstall`, `status`) remain available for shell automation. `update --project` refreshes the packaged execution-first Core and recognized generated agent instructions with local backup. `update --project --seal-policy` is the owner-reviewed maintenance action that pins fresh Core/Guardrail fingerprints. Ordinary update does not inspect migrations, while `--migrate` explicitly does so and applies the verified plan.
 
 Run transitions accept typed evidence through `--command`, `--test`, `--file`, `--review`, `--decision`, `--insight`, `--risk`, or generic `--evidence kind:value`. `doctor --recover` is an explicit write that resolves only safe pending kernel transactions; doctor without it remains read-only.
 

package/docs/ENTITY-MODEL.md

@@ -1,4 +1,4 @@
-# ScrumRun 2.0 Entity Model
+# ScrumRun 4.0 Markdown Model
 
 This document explains the model. Exact ids, directories, initial states, transitions, structural cardinalities, truth ownership, and authority boundaries are generated from `lib/v2/schema.js` into [`SCHEMA.md`](SCHEMA.md). Do not maintain another hand-written schema table here.
 
@@ -6,32 +6,35 @@ This document explains the model. Exact ids, directories, initial states, transi
 
 | Entity | Question | Lifetime |
 |---|---|---|
+| Core | How must the agent work? | Stable, sealed policy |
+| Guardrails | What may never be broken here? | Stable, sealed project policy |
+| Knowledge | What do we know, and why? | Reviewed until stale/deprecated/invalidated |
+| Backlog | What is provisioned but not started? | Tasks with `status: backlog` |
 | Feature | Why does this initiative matter? | Long-lived |
-| Task | What atomic outcome is approved? | Until outcome/closure |
-| Sprint | When are related Tasks grouped? | Timebox/batch |
-| Run | How did one execution attempt happen? | Immutable attempt history |
-| Memory | What do we know, and why? | Reviewed until stale/deprecated/invalidated |
+| Sprint | Which Tasks ship together? | Feature, fix, or maintenance batch |
+| Task | What concrete outcome must be delivered? | Until outcome/closure |
+| Run | What happened while executing a Task or Sprint? | Optional audit/handoff record |
 
 ```text
-FEAT-003
+SPRINT-012 (type: fix)
    └── TASK-018
-          ├── executed_by → RUN-044
-          ├── included_in → SPRINT-012
-          ├── constrained_by → DEC-018
-          └── generated → INS-041
+          ├── feature → FEAT-003
+          ├── depends_on → TASK-014, DEC-018
+          ├── guardrails → GR-004
+          └── run → RUN-044 (optional)
 ```
 
-Task is always the executable unit. A Task may be independent of a Sprint. Sprint never substitutes for Task. A retry creates another Run for the same Task.
+Task is the executable unit. A Task may be independent of a Sprint. A Sprint groups Tasks and may be `feature`, `fix`, or `maintenance`. Runs are optional and never substitute for a Task's direct Markdown handoff.
 
 ## Canonical artifacts
 
-All artifacts carry `id`, `kind`, `status`, `created`, `updated`, and `method`. Relations live in frontmatter for structural ownership and in `## Relations` for extensible graph edges. The generated [`SCHEMA.md`](SCHEMA.md) is the authoritative inventory.
+All artifacts carry `id`, `kind`, `status`, `created`, `updated`, and `method`. Relations use simple frontmatter and relative links: `sprint: SPRINT-012`, `feature: FEAT-003`, `depends_on: [TASK-014, DEC-018]`, and `## Related`. Unknown fields and sections are preserved. The generated [`SCHEMA.md`](SCHEMA.md) is the authoritative inventory.
 
 ## Operational flow
 
-Approval creates one Task and one Run. The Run progresses `executing → validating → learning → completed|failed|blocked`, while the Task mirrors `running → validating → learning → completed|failed|blocked`. Pair mutations are recoverable.
+Approval creates or refines a Task. An optional Run can record strict audit or handoff history, but no Run, ledger, permit, or status synchronization blocks normal Markdown work. An approved Task continues through discover → implement → verify → fix → verify until its `## Done when` contract is delivered.
 
-Feature and Sprint provide context/grouping and do not own execution history. Review attaches evidence. Memory explains decisions and constraints across all of them.
+Feature and Sprint provide context/grouping and do not own execution history. Review attaches evidence. Knowledge, Decisions, and Insights explain constraints across all of them. Core and Guardrails are sealed Markdown policy: only explicit owner-reviewed maintenance may change them.
 
 ## Generated projections
 

package/docs/QUICKSTART.md

@@ -1,18 +1,19 @@
 # Quickstart
 
-Get from "never heard of it" to your first approved Run in under 10 minutes.
+Get from "never heard of it" to your first delivered Task in under 10 minutes.
 No `SPEC.md` reading required.
 
 ## The three-minute mental model
 
 ScrumRun gives an AI coding agent a small vocabulary and a project memory.
 
-- **Task** — one atomic piece of work.
-- **Sprint** — a batch of Tasks grouped by time or theme. Optional.
-- **Run** — one attempt at executing a Task. Retries create new Runs; the
-  previous one is never overwritten.
-- **Feature** — a bigger initiative that groups Tasks and its own decisions.
-- **Memory** — what the project learned: facts, decisions, insights, dossiers.
+- **Core** — how the agent works; read first and never edited during product work.
+- **Guardrails** — rules that cannot be broken.
+- **Knowledge** — facts, decisions, insights, and dossiers about the project.
+- **Task** — one concrete delivery, independent or inside a Sprint.
+- **Sprint** — a feature, fix, or maintenance batch of Tasks. Optional.
+- **Feature** — a bigger initiative that groups delivery context.
+- **Run** — optional audit/handoff Markdown for a Task or Sprint.
 
 Everything lives as Markdown under `.scrumrun/`. Any Markdown-capable agent
 can follow it.
@@ -64,24 +65,25 @@ command (`| less`, `> intake.txt`) or set `NO_COLOR=1` to get the plain
 Markdown summary instead; add `--json` for a fully structured payload
 you can feed to CI or a downstream tool.
 
-Only then does a Task and a Run get created.
+Only then does the Task become approved. The agent executes it directly in code and Markdown; a Run is optional.
 
-## Watching the Run
+## Delivering the Task
 
-The agent executes inside the approved scope. Every step lands in an
-append-only ledger under `.scrumrun/runs/RUN-NNN.md` with a stable event
-id, timestamp, actor, reason, and typed evidence.
+The agent executes inside the approved scope until `## Done when` is true.
+It does not stop after an inventory, partial fix, or progress report. Any
+missing implementation discovered in scope is work to do now, not a follow-up.
 
 ```
-RUN-001-EVT-001  planned by owner       reason: "checkout double-charge fix"
-RUN-001-EVT-002  executed               command: npm test  → 132 passed
-RUN-001-EVT-003  validated (REV-001)    guardrail checks: passed
-RUN-001-EVT-004  learned (INS-001)      "refresh triggers duplicate submit"
-RUN-001-EVT-005  completed
+TASK-001
+  → inspect the duplicate-submit path
+  → implement the fix
+  → run the relevant checks
+  → correct failures
+  → write ## Completion and status: completed
 ```
 
-A retry does not overwrite `RUN-001`. It creates `RUN-002` beside it. The
-old attempt stays as evidence.
+A Run may be added when a strict audit or detailed handoff is useful. It never
+needs to exist for normal work to start or finish.
 
 You can render a Run's ledger as a human timeline instead of reading the
 raw JSON:

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

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

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

@@ -3,7 +3,9 @@ name: scrumrun
 description: Use when initializing or migrating ScrumRun, handling product requests, planning or executing Tasks/Sprints/Features/Runs, managing guardrails or semantic memory, checking status, and running reviews.
 ---
 
-# ScrumRun 2.0
+# ScrumRun 4.0 — execution-first Markdown
+
+Package 4.0 implements the stable ScrumRun method contract 2.0.0.
 
 ScrumRun is an evidence-driven Agile runtime for AI agents. Its canonical shell command is:
 
@@ -36,9 +38,11 @@ Normal hot path:
 5. follow the briefing's pointers to only the relevant canonical artifacts; go deeper only when the briefing lacks what you need (`## Where to look`, `scrumrun knowledge study "<topic>"`);
 6. load `.scrumrun/core.md` when the method contract or an exceptional transition is needed.
 
-**Markdown is the daily runtime.** After approval, work directly in source files and the relevant `.scrumrun/` Markdown. Create/refine the Task, its acceptance criteria, technical summary, follow-ups, and optional Run handoff without waiting for a CLI transition. Do not invoke `npx scrumrun@latest` or normal `scrumrun plan/run` commands during execution. The CLI is optional maintenance for `init`, `update --project`, `migrate`, `repair`, `doctor`, reports, and release checks.
+**Markdown is the daily runtime.** After approval, work directly in source files and the relevant `.scrumrun/` Markdown until the approved Task is delivered. Continue the full loop — discover → implement → verify → fix → verify — before responding. A progress report is allowed only when the owner asks for status and must be followed immediately by further execution; it never ends the Task. Do not stop to issue a progress report, inventory, decomposition, or list of remaining work; those are internal implementation steps. A missing implementation discovered in scope remains required work now, never a follow-up or a “next step”. Stop only for an owner decision, external access, an explicit Guardrail, security/secret risk, destructive work without approval, or an unmet required delivery criterion. Do not invoke `npx scrumrun@latest` or normal `scrumrun plan/run` commands during execution. The CLI is optional maintenance for `init`, `update --project`, `migrate`, `repair`, `doctor`, reports, and release checks.
+
+**Do not block on administrative state.** A missing/invalid Run, legacy status vocabulary, stale generated view, or optional unrun test is a warning to reconcile in Markdown, not a reason to refuse productive work. Define a concise `## Done when` delivery contract. `## Follow-ups` is only for work outside that contract: never relabel an unfinished requirement as a follow-up without explicit owner approval. Optional E2E/integration/review coverage belongs there or in a risk note, never in a fabricated failed Run.
 
-**Do not block on administrative state.** A missing/invalid Run, legacy status vocabulary, stale generated view, or optional unrun test is a warning to reconcile in Markdown, not a reason to refuse productive work. Block only for an explicit Guardrail, security/secret risk, destructive action without approval, or an unmet required Acceptance Criterion. Optional E2E/integration/review coverage belongs in `## Follow-ups` or a risk note, never in a fabricated failed Run.
+**A check must prove its claim.** A passing narrow checker does not prove a broader Task condition. If the task says no visible hardcoded literals, scan the relevant source, replace every in-scope match, and re-run that scan plus the build. Apply the same coverage rule to all completion claims.
 
 **Normal-operation command ban.** Do not invoke `scrumrun plan run --fail`, `--block`, `--retry`, `--finalize`, `--complete`, `--validate`, or `scrumrun plan task --start` during ordinary work. Those are optional strict-audit tools and cannot be used to decide whether a Task is delivered. If an old Run is already failed for an administrative reason, leave it as historical evidence, continue the Task directly, and write the corrected outcome in the Task's Technical Summary and Follow-ups.
 
@@ -104,11 +108,11 @@ During execution:
 
 1. keep the change inside the approved Task scope;
 2. preserve existing owner work and unrelated dirty files;
-3. define or confirm the Task's `## Acceptance Criteria` before execution and check them off as evidence;
-4. work normally: edit code and update the Task's `## Technical Summary`, `## Follow-ups`, and any Guardrail evidence required by an active rule;
+3. define or confirm the Task's short `## Done when` contract before execution and use it as the only delivery boundary;
+4. work normally and continuously. Privately decompose work or create linked child Tasks when useful, but do not return after planning; edit code until the contract is satisfied;
 5. validate in proportion to risk and against the acceptance criteria. Tests, reviews, and environments are required only when the owner, Acceptance Criteria, or an active Guardrail says so. Do not fail or block an otherwise accepted Task merely because an optional E2E/integration suite does not exist or was not run;
 6. run a configured reviewer only when a Guardrail requires it;
-7. complete the Task directly in Markdown after the required work is satisfied; use CLI release/doctor/repair commands only when their audit or recovery value is wanted;
+7. complete the Task directly in Markdown after the required work is satisfied, adding a concise `## Completion`; use CLI release/doctor/repair commands only when their audit or recovery value is wanted;
 8. use path-scoped Mutation Gateway commands only when the owner explicitly requests strict execution.
 
 Never overwrite a prior attempt. Never mark work complete because time/token budget ended.
@@ -117,7 +121,7 @@ When work remains queued, the briefing may name the next backlog Task. The owner
 
 Every explicit Guardrail remains mandatory. In strict mode, the CLI final checkpoint fails closed on policy drift, protected-path changes, unsafe symlinks, unscannable content, newly introduced secret-like content, or missing Guardrail Evidence. The ignored permit cache is disposable; deleting it invalidates outstanding strict-mode permits and never creates authority.
 
-Task Markdown is the daily operational handoff authority. A structured Run is optional strict audit history only. Early v2 prose Runs may be repaired/migrated explicitly, but their state never overrides the Task's direct handoff or blocks approved work.
+Task Markdown is the daily operational handoff authority. A structured Run is optional strict audit history only. `core.md` and `guardrails.md` are sealed policy: never edit either during product work. A policy change requires an explicit owner request and the owner seals reviewed changes with `scrumrun update --project --seal-policy`. Early v2 prose Runs may be repaired/migrated explicitly, but their state never overrides the Task's direct handoff or blocks approved work.
 
 Linked canonical writes use the ignored durable transaction journal. An interrupted prepared mutation rolls back before the next approved mutation; a committed journal is verified and finalized. Audit remains read-only and reports pending recovery. Use `doctor --recover` only when explicitly requested, and never overwrite bytes changed after interruption.
 

package/types/index.d.ts

@@ -21,7 +21,7 @@ export type ArtifactKind =
 
 export type ArtifactStatus =
   | "backlog" | "proposed" | "active" | "completed" | "paused" | "cancelled"
-  | "running" | "validating" | "learning" | "partial" | "failed" | "blocked"
+  | "running" | "in_progress" | "validating" | "learning" | "partial" | "failed" | "blocked"
   | "candidate" | "approved" | "rejected" | "deprecated" | "invalidated"
   | "open" | "resolved" | "confirmed" | "stale" | "archived" | "executing" | "passed";