scrumrun 3.1.1 → 4.0.0

package/CHANGELOG.md

@@ -4,11 +4,32 @@ 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
+
+- **Mechanical strict-audit gate.** The CLI now refuses Task start/retry and every Run state transition unless `--strict` is explicitly present. This prevents a normal agent loop from creating failed/blocked administrative Runs even if it ignores the Markdown-first guidance.
+
 ## 3.1.1 - 2026-08-31
 
 ### Fixed
 
 - **No strict-Run commands in daily work.** Generated Core and agent instructions now explicitly prohibit `plan run --fail|--block|--retry|--finalize|--complete|--validate` and `plan task --start` in normal operation. A legacy Run incorrectly failed for administrative reasons stays as history; the Task's direct Markdown handoff records the real result.
+- **CLI backstop.** Task start/retry and Run state-changing commands now require an explicit `--strict`, so an agent that ignores the guidance cannot accidentally create another failed/blocked administrative Run.
 
 ## 3.1.0 - 2026-08-31
 

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.1` · **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,8 +102,14 @@ 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.
+
 Each optional structured Run contains a machine-validated event ledger. It remains useful for strict audit/release work, but daily history can stay as concise, human-readable Task handoff Markdown.
 
 Linked Task/Run writes use a durable ignored transaction journal. Captured failures roll back immediately; interrupted operations are recovered byte-exactly on retry or through explicit `doctor --recover`. Read-only audit reports pending recovery and never repairs state silently.
@@ -159,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"));
@@ -1308,6 +1319,7 @@ function runTransitionOptions(args) {
   let summary = null;
   for (let index = 2; index < args.length; index++) {
     const token = args[index];
+    if (token === "--strict") continue;
     const value = args[index + 1] && !args[index + 1].startsWith("--") ? args[index + 1] : null;
     if (token === "--note" || token === "--actor" || token === "--at" || token === "--evidence" || token === "--summary" || evidenceFlags.has(token)) {
       if (!value) throw new Error(`${token} requires a value.`);
@@ -1333,6 +1345,11 @@ function runTransitionOptions(args) {
   return { note: note || noteParts.join(" ").trim() || null, evidence, actor, occurredAt, summary };
 }
 
+function requireStrictAudit(args, action) {
+  if (args.includes("--strict")) return;
+  throw new Error(`${action} is disabled in Markdown-first daily work. Update the Task Markdown directly; use --strict only for an owner-requested audit.`);
+}
+
 function removeOptionPairs(args, names) {
   const hidden = new Set(names);
   const next = [];
@@ -1470,6 +1487,7 @@ function executeRootRoute(route) {
     return;
   }
   if (noun === "plan" && subject === "task" && routeArgs[0] === "--retry") {
+    requireStrictAudit(routeArgs, "Task retry");
     const result = retryTask(process.cwd(), routeArgs[1], { reassign: routeArgs.includes("--reassign") });
     console.log(`Created retry ${result.run.id} for ${result.task.id} (attempt ${result.run.attempt}).`);
     return;
@@ -1486,6 +1504,7 @@ function executeRootRoute(route) {
     return;
   }
   if (noun === "plan" && subject === "task" && routeArgs[0] === "--start") {
+    requireStrictAudit(routeArgs, "Task start");
     let target = routeArgs[1];
     if (!target) {
       const repository = new ArtifactRepository(projectFile());
@@ -1610,9 +1629,10 @@ function executeRootRoute(route) {
   }
   if (noun === "plan" && subject === "run") {
     if (routeArgs[0] === "--finalize") {
+      requireStrictAudit(routeArgs, "Run finalization");
       const runId = routeArgs[1];
       if (!runId) throw new Error("--finalize requires RUN-NNN.");
-      const result = finalizeRun(process.cwd(), runId, runTransitionOptions(routeArgs.slice(2)));
+      const result = finalizeRun(process.cwd(), runId, runTransitionOptions(routeArgs));
       console.log(`${result.run.id}: completed; ${result.task.id}: completed. Final session audit verified ${result.changes} change(s).`);
       if (result.resolved.length) console.log(`Guardrails verified: ${result.resolved.join(", ")}.`);
       if (result.learning && result.learning.created.length) console.log(`Learning candidates: ${result.learning.created.join(", ")}.`);
@@ -1654,6 +1674,7 @@ function executeRootRoute(route) {
       "--block": "blocked"
     };
     if (transitions[routeArgs[0]]) {
+      requireStrictAudit(routeArgs, `Run transition ${routeArgs[0]}`);
       const result = transitionRun(process.cwd(), routeArgs[1], transitions[routeArgs[0]], runTransitionOptions(routeArgs));
       console.log(`${result.run.id}: ${result.run.status}; ${result.task.id}: ${result.task.status}.`);
       if (result.learning) {
@@ -1696,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");
@@ -2312,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)
@@ -2322,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) {
@@ -2601,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}`);
     }
   }
@@ -2623,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:
 
@@ -13,25 +13,27 @@ Use `.scrumrun/` Markdown for normal project work. `/sc` and the installed CLI a
 ```text
 scrumrun plan intake <request>
 scrumrun plan intake --approve <token>
-scrumrun plan task --add|--list|--show|--run|--audit|--cancel|--retry
+scrumrun plan task --add|--list|--show|--run|--audit|--cancel|--retry --strict
 scrumrun plan task --amend TASK-NNN [--title "..."] [--request "..."] [--acceptance "..."] [--section "Heading=content"] [--type fix|task|feature|docs|discovery] [--feature FEAT-NNN|null] [--sprint SPRINT-NNN|null]
 scrumrun plan sprint --add|--list|--show|--start|--complete|--block
 scrumrun plan sprint --amend SPRINT-NNN [--title "..."] [--timebox "..."] [--exit-gate "..."] [--section "Heading=content"]
 scrumrun plan feature --add|--list|--show|--activate|--complete
 scrumrun plan feature --amend FEAT-NNN [--title "..."] [--purpose "..."] [--exit-criteria "..."] [--section "Heading=content"]
-scrumrun plan run --list|--show|--validate|--learn|--complete|--resume|--fail|--block [--note] [typed evidence flags]
-scrumrun plan run --finalize RUN-NNN [--summary "technical recap"] [--note]
+scrumrun plan run --list|--show|--validate|--learn|--complete|--resume|--fail|--block --strict [--note] [typed evidence flags]
+scrumrun plan run --finalize RUN-NNN --strict [--summary "technical recap"] [--note]
 scrumrun plan run --authorize-mutation RUN-NNN --path <relative-path> [--path ...]
 scrumrun plan run --record-mutation RUN-NNN --permit MUT-id [--note] [--actor]
 scrumrun plan run --satisfy-guardrail RUN-NNN --guardrail GR-NNN [typed evidence flags]
 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
 
@@ -80,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: