scrumrun 3.0.3 → 3.1.1

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+## 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.
+
+## 3.1.0 - 2026-08-31
+
+### Changed
+
+- **Markdown-first daily workflow.** `.scrumrun/` is now the normal runtime: agents create and update Task handoffs directly instead of making CLI state transitions their prerequisite. Feature, Sprint, and Run are optional context/audit records; malformed or missing administrative metadata no longer blocks approved work.
+- **CLI at the edges.** The CLI is now positioned for `init`, `update --project`, migration, repair, doctor, reports, and release checks. Strict ledger finalization and edit permits remain opt-in for teams that explicitly want them.
+- **Existing projects.** `scrumrun update --project` refreshes packaged `core.md` and recognized generated `AGENTS.md`, preserving byte-exact local backups before replacement. Ordinary `update` no longer applies a migration implicitly; only `update --migrate` may do so.
+
+### Safety
+
+- Agents block only for active Guardrails, security/secret risks, destructive work without approval, or unmet required Acceptance Criteria. Missing Runs, legacy status vocabulary, stale derived views, and optional test coverage are documented warnings/follow-ups, not workflow blockers.
+
 ## 3.0.3 - 2026-08-31
 
 ### Fixed

package/CORE.md

@@ -84,9 +84,13 @@ 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/`.
 
-**Never write Run events by hand.** After approval, work directly in code and in the linked Task Markdown. Finish the normal session once with `scrumrun plan run --finalize RUN-NNN`; the CLI then audits the complete workspace delta, verifies Guardrails and evidence, and writes the validated Run event chain. Do not use `npx scrumrun@latest` during execution. The older `--validate | --learn | --complete | --satisfy-guardrail | --authorize-mutation | --record-mutation` operations remain available only for an owner-requested strict path. Existing hand-written Runs can be recovered with `scrumrun plan run --normalize-legacy` (byte-exact original preserved in `.scrumrun/.migration-backup/runs/`).
+**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.
 
-**Amend planning truth through the CLI, never by hand.** Before execution, use `scrumrun plan task|feature|sprint --amend <ID>` to adjust the title, structured fields, or any named body section (`--section "Heading=content"`). A Task may be amended only in `backlog` or `proposed`; changing its `--feature` or `--sprint` also synchronizes the related projections atomically. Runs, Reviews, confirmed memory, and Guardrails are evidence/history and are not amendable: append a transition, record a new Review, or supersede/deprecate the old fact instead.
+**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.
+
+**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.
 
 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.
 
@@ -164,34 +168,22 @@ Before approval, do not create canonical files, update status, edit application
 
 ## Execution lifecycle
 
-Explicit approval creates or updates the Task and creates a Run:
+Explicit approval authorizes direct source and Markdown work. The normal lifecycle is a human-readable Task handoff:
 
 ```text
-executing
-  → validating
-  → learning
-  → completed
-       ↘ failed
-       ↘ blocked
+understand → approve → work → validate required criteria → hand off
 ```
 
 Rules:
 
-- one Run belongs to one Task;
-- one Task may have multiple immutable attempts;
-- every state transition writes exactly one append-only `RUN-NNN-EVT-NNN` JSON event with RFC3339 time, actor, reason, and typed evidence;
-- the Run ledger is operational history; Task synchronizes current status without copying the Run event;
-- validation, learning, completion, failure, block, and resume require a reason or evidence;
-- validation must match the risk and acceptance criteria;
-- 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 follow-up/risk, never a reason by itself to fail or block an otherwise accepted Task;
-- each Task declares its `## Acceptance Criteria` before execution; check them off as evidence, never mark done on vibes;
-- configured reviews run before completion;
-- every deferred policy result is persisted as a Run Guardrail obligation;
-- before changing application/source files, issue a short-lived path-scoped mutation permit and record the verified before/after hashes in the Run;
-- unrecorded workspace drift, policy drift, out-of-scope paths, unsafe symlinks, new secret-like content, or unresolved obligations block validation/completion;
-- learning proposes memory candidates after validation and never auto-confirms AI inference;
-- record a `## Technical Summary` at completion with `scrumrun plan run --complete --summary "…"` so the next agent inherits what was actually done;
-- complete a Sprint only when all its included Tasks meet the Sprint exit gate;
+- a Task carries the intended scope, `## Acceptance Criteria`, `## Technical Summary`, 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;
+- a structured Run may be created for audit/release work. When used, it follows `executing → validating → learning → completed|failed|blocked` and preserves prior attempts;
+- 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.
 
 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.
@@ -200,7 +192,7 @@ Task/Run pair mutations use an ignored durable journal under `.scrumrun/.backup/
 
 ### Backlog and sequencing
 
-Backlog is the queue of Tasks with `status: backlog`, ordered oldest-first by id. When a Run completes, the briefing's `## Next Up` names the next backlog Task. `scrumrun plan task --next` shows it; `scrumrun plan task --start [TASK-NNN]` promotes it to `running`, creates its first Run, re-evaluates policy, and records the agent identity. Starting is itself the explicit approval (I-01): no work executes silently, and the owner can always say "not now".
+Backlog is the queue of Tasks that are intentionally parked. The briefing may name the next one, but an explicit owner request/approval starts work; no CLI state transition is required.
 
 ### Agent identity and assignment
 
@@ -251,7 +243,7 @@ scrumrun migrate --to 2 --apply
 scrumrun migrate --to 2 --rollback
 ```
 
-- ordinary install/update never applies a migration; update performs a read-only v1 preflight, and only explicit `update --migrate` applies its verified plan;
+- ordinary install/update never inspects or applies a migration; only explicit `update --migrate` performs and applies its verified migration plan;
 - early v2 Run prose is also preflighted read-only and upgraded explicitly to ledger schema 1 with byte-exact backup and safe rollback;
 - dry-run writes no project data;
 - apply inventories source hashes, creates a byte-exact local backup, transforms in staging, validates, and activates by atomic directory swap;

package/README.md

@@ -4,7 +4,7 @@
 
 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.0.3` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+**Package:** `3.1.1` · **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).
 
@@ -79,33 +79,29 @@ 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 atomically materializes the required plan artifacts and always creates the linked Task and Run. Feature and Sprint artifacts are created automatically when the request calls for them. Execution then follows:
+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.
 
 ```text
 EXECUTING → VALIDATING → LEARNING → COMPLETED | FAILED | BLOCKED
 ```
 
-Every approved Task carries an `## Acceptance Criteria` section so "done" is defined before work begins. After approval, the agent works directly in code and the Task Markdown. It adds `## Technical Summary` and, when a non-automatic rule needs proof, a compact `## Guardrail Evidence` section. One final checkpoint closes the work:
+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.
 
-```bash
-scrumrun plan run --finalize RUN-001
-```
-
-The checkpoint validates the complete delta, policy, protected paths, secret boundary, Task summary, and every applicable Guardrail before writing the Run ledger and synchronizing the Task. Failed retries remain available as separate Runs. Tests, reviews, and environments are a completion gate only when the owner, Acceptance Criteria, or an active Guardrail explicitly requires them; an optional missing E2E suite 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 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.
 
-Before a Task starts, refine it through the CLI rather than hand-editing Markdown. `--amend` updates title, request, acceptance criteria, Feature/Sprint links, task type, or any named section while preserving its ID and status. It synchronizes related Feature/Sprint projections atomically.
+Use the CLI at the edges, where its safety is valuable:
 
 ```bash
-scrumrun plan task --amend TASK-153 \
-  --title "Organization Aside and context selector" \
-  --request "Add shared organization navigation, context selection, routes, and authorization boundaries." \
-  --acceptance "Organization context is available before protected routes render." \
-  --section "Architecture Notes=Navigation stays in the Aside; authorization stays server-side."
+scrumrun init
+scrumrun update --project
+scrumrun doctor
+scrumrun repair --recover-orphan-tasks --apply
+scrumrun review release --run
 ```
 
-Tasks become immutable in scope once started; create a follow-up Task for a new request. Runs, Reviews, confirmed memory, and Guardrails are deliberately append-only/evidence-led rather than editable. See [the command reference](docs/COMMANDS.md#what-can-be-changed) for the complete artifact matrix.
+`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.
 
-Each Run contains a machine-validated event ledger. Events have stable ids such as `RUN-044-EVT-003`, RFC3339 timestamps, actors, reasons, and typed evidence for commands, tests, files, reviews, decisions, insights, and risks. Run is the only operational history; Task keeps its approved scope and synchronized current status without duplicating those events. Completion is rejected when validation or learning evidence is missing.
+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.
 
@@ -163,10 +159,10 @@ It is progressive disclosure: the briefing is enough for most work; the agent fo
 
 ## Migrating an ongoing v1 project
 
-Update the client integrations and automatically run a read-only migration preflight:
+Update the client integrations. For an existing project, refresh the Markdown-first guidance explicitly:
 
 ```bash
-scrumrun update
+scrumrun update --project
 ```
 
 This shows the source inventory, proposed mappings, and blockers without changing project data. Apply only the verified plan with:

package/SPEC.md

@@ -200,15 +200,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 atomically creates one Task and its first Run. If either write fails, neither may remain. Project changes after planning invalidate the token. Reusing a successfully consumed token is idempotent. 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 Acceptance Criteria, or an active Guardrail; missing optional coverage is a documented follow-up/risk, not a failure by itself.
 
-The approved Run binds the exact Guardrail-policy fingerprint and a canonical workspace baseline. Every post-approval `deferred` check becomes an append-only Guardrail obligation. In the normal session path, agents work directly and one final checkpoint verifies the complete baseline-to-final delta: policy freshness, read-only boundaries, symlink safety, scannability, newly introduced secret-like content, and evidence for every Guardrail. Missing or unverifiable evidence fails closed. Strict teams may opt into short-lived, path-scoped permits and per-edit recording; those commands add stronger intermediate control but are not required for normal execution.
+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.
 
-Run transitions synchronously update the linked Task and append exactly one structured event to the Run ledger. The normal `--finalize` checkpoint writes the required validating, learning, and completed transitions together after its audit; strict mode may write them individually. Task status changes without receiving a duplicate narrative history. Completion requires a `## Technical Summary` and evidenced validation/learning. Multi-file mutations use a durable local transaction journal: `prepared` operations roll back byte-exactly after failure/interruption, while `committed` journals are verified and finalized. Ordinary audit is read-only and reports pending recovery; `doctor --recover` or retrying the approved mutation performs recovery explicitly. Entering `learning` may extract structured candidates from the Run, but extraction failure never blocks Run progress.
+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.
 
-Backlog is a queue view of Tasks with `status: backlog`, ordered oldest-first by id. Starting a backlog Task (`--next` to surface, `--start` to promote) transitions `backlog → running`, creates the Task's first Run, re-evaluates policy, and records the agent identity. Starting is itself the explicit approval required by I-01.
+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.
 
 ## 6. Policy and precedence
 
@@ -274,7 +274,7 @@ scrumrun migrate --to 2 --apply
 scrumrun migrate --to 2 --rollback
 ```
 
-`scrumrun update` performs the same read-only preflight when run inside a v1 project and leaves project data untouched. `update --migrate` is an explicit request to apply the verified plan; it is not implicit migration.
+`scrumrun update` refreshes integrations only. `update --migrate` is the explicit request to inspect and apply the verified migration plan; migration is never implicit.
 
 Inside an early v2 project, the same commands preflight and explicitly upgrade legacy Run prose to ledger schema 1. Deterministic transition chains are recovered; incomplete history becomes an evidenced snapshot. Apply keeps byte-exact ignored backups, verifies hashes, is idempotent, and supports rollback that refuses to erase later Run changes.
 
@@ -296,7 +296,7 @@ Legacy sprint entries become Tasks. History entries become Runs only with an evi
 ## 10. Normative invariants
 
 - **I-01** No canonical artifact or code write occurs before explicit approval.
-- **I-02** Approval creates a linked Task/Run pair atomically or creates nothing.
+- **I-02** The optional strict CLI approval path creates a linked Task/Run pair atomically or creates nothing; Markdown-first approval remains human-authorized and non-blocking.
 - **I-03** Task is atomic work; Sprint only groups Tasks with real batch/timebox evidence.
 - **I-04** Every retry creates a new Run and preserves earlier attempts.
 - **I-05** Only declared, ordered, evidenced state transitions are accepted; Run event ids are unique and paired transitions are recoverable.

package/bin/scrumrun.js

@@ -58,7 +58,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] [--no-migrate] [--verbose]
+  scrumrun update  [all|codex|opencode|claude] [--project] [--migrate] [--verbose]
   scrumrun init [--local|--shared] [--lean] [--no-agent-hint] [--force]
   scrumrun status
   scrumrun core [--path|--prompt]
@@ -318,7 +318,7 @@ function migrationPreflightOnUpdate({ apply = false } = {}) {
           return { status: "blocked" };
         }
         if (!apply) {
-          console.log("\nThe project remains unchanged. Re-run update to apply the verified plan, or keep opt-out with: scrumrun update --no-migrate");
+          console.log("\nThe project remains unchanged. Apply only with: scrumrun update --migrate");
           return { status: "ready" };
         }
         const result = applyRunLedgerMigration(process.cwd());
@@ -344,7 +344,7 @@ function migrationPreflightOnUpdate({ apply = false } = {}) {
       return { status: "blocked" };
     }
     if (!apply) {
-      console.log("\nThe project remains unchanged. Re-run update to apply the verified plan, or keep opt-out with: scrumrun update --no-migrate");
+      console.log("\nThe project remains unchanged. Apply only with: scrumrun update --migrate");
       return { status: "ready" };
     }
     const result = applyMigration(process.cwd(), { plan: preview.plan });
@@ -359,14 +359,39 @@ function migrationPreflightOnUpdate({ apply = false } = {}) {
   }
 }
 
-function updateInstallation(target, { migrate = false, verbose = false } = {}) {
+function refreshProjectGuidance(cwd = process.cwd()) {
+  if (!v2Project(cwd)) return [];
+  const vars = { PROJECT_NAME: path.basename(cwd), DATE: today() };
+  const renderTemplate = (source) => Object.entries(vars).reduce(
+    (content, [key, value]) => content.split(`{{${key}}}`).join(value),
+    fs.readFileSync(source, "utf8")
+  );
+  const results = [];
+  const coreFile = path.join(cwd, ".scrumrun", "core.md");
+  const coreResult = writeFile(coreFile, renderTemplate(path.join(root, "CORE.md")), { backup: true });
+  results.push({ status: coreResult.changed ? "updated" : "skipped", dest: coreFile, backup: coreResult.backup });
+  const agentsFile = path.join(cwd, "AGENTS.md");
+  if (!fs.existsSync(agentsFile) || looksLikeScrumRunAgents(agentsFile)) {
+    const current = readIfExists(agentsFile);
+    const leanProject = /lean read policy/i.test(current);
+    const template = path.join(templates, leanProject ? "project-lean" : "project", "AGENTS.md");
+    const agentResult = writeFile(agentsFile, renderTemplate(template), { backup: true });
+    results.push({ status: agentResult.changed ? "updated" : "skipped", dest: agentsFile, backup: agentResult.backup });
+  } else {
+    results.push({ status: "skipped", dest: `${agentsFile} (not recognized as ScrumRun-generated)` });
+  }
+  return results;
+}
+
+function updateInstallation(target, { migrate = false, project = false, verbose = false } = {}) {
   installVerbose = verbose;
   installSummary.cleaned = 0;
   installSummary.written = 0;
   installSummary.skipped = 0;
   installSummary.targets.length = 0;
-  const migration = migrationPreflightOnUpdate({ apply: migrate });
+  const migration = migrate ? migrationPreflightOnUpdate({ apply: true }) : { status: "skipped" };
   install(target, true, { compatibility: true });
+  const projectResults = project ? refreshProjectGuidance() : [];
   if (migrate && v2Project()) {
     try {
       refreshState(path.join(process.cwd(), ".scrumrun"));
@@ -377,7 +402,8 @@ function updateInstallation(target, { migrate = false, verbose = false } = {}) {
   }
   if (!verbose) {
     const targetSummary = installSummary.targets.join(", ") || "no clients";
-    console.log(`Updated ${targetSummary} — ${installSummary.written} files written, ${installSummary.cleaned} legacy removed. Run with --verbose to see file paths.`);
+    const projectSummary = projectResults.length ? ` Project guidance: ${projectResults.filter((item) => item.status === "updated").length} file(s) refreshed.` : "";
+    console.log(`Updated ${targetSummary} — ${installSummary.written} files written, ${installSummary.cleaned} legacy removed.${projectSummary} Run with --verbose to see file paths.`);
   }
   return migration;
 }
@@ -2597,7 +2623,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("--no-migrate"), verbose: args.includes("--verbose") });
+  if (command === "update") updateInstallation(target, { migrate: args.includes("--migrate"), project: args.includes("--project"), 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.0 Command Reference
+# ScrumRun 3.1 Command Reference
 
 The canonical grammar is:
 
@@ -6,7 +6,7 @@ The canonical grammar is:
 scrumrun <noun> <subject> <action> [args]
 ```
 
-Use the installed `scrumrun` command for all normal project work. `/sc` is an optional AI-client shortcut and `scrumrun sc ...` remains a compatibility alias. Do not use `npx scrumrun@latest` inside an agent's execution loop.
+Use `.scrumrun/` Markdown for normal project work. `/sc` and the installed CLI are optional maintenance/release tools; do not use `npx scrumrun@latest` inside an agent's execution loop.
 
 ## Plan
 
@@ -27,9 +27,9 @@ 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 linked Task, then use one `--finalize` checkpoint. It verifies every workspace change and all Guardrail evidence before writing the Run transitions. A retry requires a failed, blocked, or partial Task and creates a new Run. 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, 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.
 
-`--amend` is the canonical way to adjust planning truth before execution — never edit an artifact Markdown file directly. Every named `--section "Heading=content"` replaces or adds one `## Heading` section, so new planning context does not need a new CLI release. Repeated `--acceptance`, `--exit-criteria`, and `--exit-gate` values become checklist items. Updating a Task's `--feature` or `--sprint` synchronizes the linked Feature/Sprint projection atomically. A Task is amendable only while `backlog` or `proposed`; after it starts, scope is historical/approved truth and follow-up work needs a new Task.
+`--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.
 
@@ -37,8 +37,8 @@ Every new Task starts with a `## Validation Scope`: only checks explicitly requi
 
 | Artifact | Canonical operation | Why |
 | --- | --- | --- |
-| Task, Feature, Sprint | `--add`, `--amend`, lifecycle commands | Planning truth can be refined before execution. |
-| Run | transitions, `--finalize`, `--retry` | Execution history is append-only; it is never amended. |
+| Task, Feature, Sprint | Markdown directly; optional `--add`, `--amend`, lifecycle helpers | Planning truth can be refined at the speed of work. |
+| Run | optional Markdown handoff; CLI transitions/`--finalize` for strict audit | Useful operational history, never an administrative work gate. |
 | Review | `--run` / `--record` | A verdict is evidence, not editable prose. Record another review if it changes. |
 | Knowledge, Decision, Insight, Dossier | create + lifecycle commands | Preserve evidence lineage; supersede/deprecate rather than rewrite confirmed truth. |
 | Guardrail | `--add` / `--retire` | Policy history must remain auditable. |
@@ -80,14 +80,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] [--migrate]
+scrumrun config update [all|codex|opencode|claude] [--project] [--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. Ordinary update runs only a read-only migration preflight; `--migrate` is explicit application consent.
+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.
 
 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/lib/commands/render.js

@@ -19,7 +19,7 @@ Execute ScrumRun with this request: $ARGUMENTS
 
 Use the installed \`scrumrun\` skill as the authoritative workflow. This prompt is the only canonical slash-command entry point.
 
-If \`$ARGUMENTS\` is empty, show the five nouns below and the current project status; do not guess an action. Otherwise parse exactly \`<noun> <subject> <action> [args]\` and use the installed CLI as \`scrumrun <noun> <subject> <action> [args]\`. \`/sc\` is a client shortcut retained for compatibility, never a reason to use \`npx\`.
+If \`$ARGUMENTS\` is empty, show the five nouns below and the current project status; do not guess an action. Otherwise parse exactly \`<noun> <subject> <action> [args]\`. \`/sc\` is a client shortcut retained for compatibility, never a reason to use \`npx\`. The CLI is optional maintenance; do not turn ordinary product work into a sequence of CLI calls.
 
 ## Grammar
 
@@ -27,16 +27,17 @@ ${grammarLines().join("\n")}
 
 ## Execution contract
 
-- Natural-language product work enters through \`plan intake\` automatically.
+- 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.
-- Approved work creates/updates a Task and creates a Run; a Sprint only groups Tasks when a real timebox/batch exists.
-- Run execution follows \`executing → validating → learning → completed|failed|blocked\`.
-- Run owns one structured, evidenced event ledger; Task synchronizes current status without copying Run history.
-- Linked Task/Run writes use a durable recovery journal; audit reports pending recovery and never repairs without explicit authorization.
+- 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.
+- 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.
-- The normal path is one session checkpoint: after approval, work directly in code and the linked Task Markdown; finish once with \`scrumrun plan run --finalize RUN-NNN\`. It verifies the complete workspace delta, policy, secrets, protected paths, and all Guardrail evidence together. Do not invoke \`npx scrumrun@latest\` during execution.
-- Strict per-path Mutation Gateway permits remain available only when the owner explicitly requests strict execution.
+- 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.
+- 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.
 - 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/v2/conformance.js

@@ -30,7 +30,7 @@ const INVARIANTS = Object.freeze([
   { id: "I-12", summary: "canonical schemas and identities are valid", tests: ["v2 artifact schemas round-trip", "malformed and mismatched artifacts are rejected"] },
   { id: "I-13", summary: "generated state exposes staleness", tests: ["generated state includes structured decisions", "approval rejects tampered or stale plans", "state staleness uses metadata fast path", "generated map status refuses stale projection"] },
   { id: "I-14", summary: "context and retrieval are bounded", tests: ["lean context stays within twenty-five percent", "semantic query caps relation output", "semantic index staleness uses metadata fast path"] },
-  { id: "I-15", summary: "migration and ordinary update are read-only by default", tests: ["migration dry-run is read-only", "update preflights an ongoing v1 project"] },
+  { id: "I-15", summary: "migration is explicit and ordinary update does not touch project migration state", tests: ["migration dry-run is read-only", "ordinary update refreshes integrations without inspecting an ongoing v1 project"] },
   { id: "I-16", summary: "migration is hashed, idempotent, and reversible", tests: ["migration apply is idempotent and rollback restores", "Run ledger migration failure and rollback restore"] },
   { id: "I-17", summary: "ambiguous migration is preserved and warned", tests: ["partial v1 layout is preserved"] },
   { id: "I-18", summary: "unsafe and partial writes fail safely", tests: ["canonical writes reject traversal and symlink paths", "repository refuses conflicting overwrite", "interrupted kernel transaction is recovered"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scrumrun",
-  "version": "3.0.3",
+  "version": "3.1.1",
   "description": "Evidence-driven Agile runtime and semantic project memory for AI coding agents.",
   "bin": {
     "scrumrun": "bin/scrumrun.js",

package/templates/project/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md - {{PROJECT_NAME}}
 
-## ScrumRun 3.0
+## ScrumRun 3.1 — Markdown-first
 
 This project uses ScrumRun. The method is mandatory; the direct CLI is `scrumrun <noun> <subject> <action>`. `/sc` is only an optional client shortcut.
 
@@ -11,23 +11,22 @@ For normal work, read:
 3. the referenced Task, Sprint, Feature, Run, Memory, and Review artifacts relevant to the request (go deeper only when the briefing lacks what you need);
 4. `.scrumrun/core.md` when the method contract or an exceptional transition is needed.
 
-Natural-language product requests automatically enter the read-only ScrumRun intake pipeline. Before explicit approval, do not create canonical records or modify application code.
+Natural-language product requests begin with a read-only understanding pass. Before explicit approval, do not modify application code. After approval, operate directly in `.scrumrun/` Markdown and source files; normal work must not depend on a CLI state transition.
 
 After approval:
 
-- Task is the atomic work item; define its `## Acceptance Criteria` before execution;
+- 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;
 - 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;
-- before a Task starts, amend its intended scope through `scrumrun plan task --amend TASK-NNN` (including `--section "Heading=content"`); never hand-edit canonical planning Markdown;
+- 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 one execution attempt and follows `executing → validating → learning → completed|failed|blocked`;
-- a retry creates a new Run and preserves the old one;
-- record a `## Technical Summary` at completion so the next agent inherits what was done;
-- work directly in code and the linked Task Markdown after approval; do not call `npx scrumrun@latest` during execution;
-- record one `## Guardrail Evidence` line per non-automatic guardrail in the Task, then run `scrumrun plan run --finalize RUN-NNN` once to validate and close the Run;
-- when a Run completes and work remains queued, surface it with `scrumrun plan task --next` and start it with `scrumrun plan task --start` — starting is explicit approval;
-- learning proposes evidence-backed Knowledge, Decisions, or candidate Insights;
-- the final checkpoint verifies all Guardrails, workspace changes, protected paths, and secret boundaries before completion; use the path-scoped Mutation Gateway only when the owner requests strict execution.
-
-Never bypass guardrails or edit around the Mutation Gateway, overwrite owner work, treat generated state/cache as truth, auto-confirm AI knowledge, auto-migrate a v1 project, or print vault values.
+- 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`;
+- 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;
+- 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.
+
+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 2.0 lean read policy
+## ScrumRun 3.1 lean read policy — Markdown-first
 
 This project stores the complete ScrumRun v2 truth but uses a bounded default read path:
 
@@ -11,10 +11,12 @@ 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 read-only intake. Explicit approval creates/updates a Task and creates one Run. A Sprint exists only for a real batch/timebox. Run state is `executing → validating → learning → completed|failed|blocked`; retries preserve prior Runs. Define the Task's `## Acceptance Criteria` before execution and record a `## Technical Summary` at completion. When work remains queued, surface it with `sc plan task --next` and start it with `sc plan task --start`.
+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.
 
-Every application/source edit requires a short-lived path-scoped Mutation Gateway permit and immediate hash recording in the active Run. Resolve all persisted Guardrail obligations before completion; policy/workspace drift fails closed.
+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 or the Mutation Gateway, overwrite owner work, auto-confirm AI knowledge, auto-migrate v1 state, or print vault values.
+`.scrumrun/guardrails.md` is canonical policy. Never bypass it, overwrite owner work, auto-confirm AI knowledge, auto-migrate v1 state, or print vault values.
 
-Use `/sc <noun> <subject> <action> [args]`; if `/sc` is unavailable, follow `.scrumrun/core.md` manually.
+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

@@ -36,15 +36,17 @@ 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.
 
-**Never write Run events by hand.** Work directly in code and the linked Task Markdown after approval, then let the one final CLI checkpoint mutate `runs/RUN-NNN.md`: `scrumrun plan run --finalize RUN-NNN`. It creates the validated transition ledger, audits the full workspace delta, and records the Guardrail results together. Do not invoke `npx scrumrun@latest` during normal execution. The older `--validate | --learn | --complete | --satisfy-guardrail | --authorize-mutation | --record-mutation` commands remain only for owner-requested strict mode. Recover hand-written Runs via `scrumrun plan run --normalize-legacy` — originals are preserved byte-exact under `.scrumrun/.migration-backup/runs/`.
+**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.
 
-**Never hand-edit canonical planning Markdown.** Before a Task starts, refine it with `scrumrun plan task --amend TASK-NNN`; use title/request/acceptance/relation options or generic repeated `--section "Heading=content"`. Feature and Sprint support the same `--amend` pattern. Runs, Reviews, confirmed memory, and Guardrails are append-only evidence/policy, so record a new event or supersede them instead of rewriting them.
+**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.
+
+**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.
 
 Lean mode is a read policy, not an incomplete store. Generated files and `.scrumrun/.cache/` are never authoritative.
 
 Generated state and semantic indexes use a metadata-watch fast path with a full content-hash fallback. Treat cache-schema mismatch as a request to rebuild the disposable projection, never as permission to rewrite canonical Markdown.
 
-For a v1 project without canonical v2 artifacts, use the dual-layout reader conceptually and recommend `scrumrun migrate --to 2 --dry-run`. `update` may run that read-only preflight automatically, but only explicit `update --migrate` may apply it.
+For a v1 project without canonical v2 artifacts, recommend `scrumrun migrate --to 2 --dry-run`. `update` refreshes integrations only; only explicit `update --migrate` may inspect and apply migration.
 
 ## Domain model
 
@@ -55,7 +57,7 @@ For a v1 project without canonical v2 artifacts, use the dual-layout reader conc
 - Memory — what was learned and why: `K-NNN`, `DEC-NNN`, `INS-NNN`, and dossiers.
 - Review (`REV-NNN`) — evidence from a scoped quality gate.
 
-Never create a Sprint merely because work exists. A standalone Task is valid. A retry creates a new Run and preserves the failed/blocked prior Run.
+Never create a Sprint merely because work exists. A standalone Task is valid. Strict audit retries preserve their prior Runs, but retries are never part of the normal workflow.
 
 ## Request pipeline
 
@@ -91,7 +93,7 @@ The approval token binds both canonical context and a complete workspace fingerp
 
 ## Approved execution
 
-Explicit approval creates/updates the Task and creates a Run. The Run follows:
+Explicit approval authorizes the Task and source changes. A Run may be created as an audit/handoff record when useful; it never gates daily work. When used, its historical lifecycle is:
 
 ```text
 executing → validating → learning → completed
@@ -103,19 +105,19 @@ 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` and, for non-automatic rules, `## Guardrail Evidence` as evidence becomes available;
-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; record a material coverage gap as a follow-up/risk instead;
-6. run configured reviewers when a Guardrail requires one;
-7. finish once with `scrumrun plan run --finalize RUN-NNN`; it verifies every changed path, policy, secret boundary, and guardrail evidence before creating the structured Run events and completing the Task;
+4. work normally: edit code and update the Task's `## Technical Summary`, `## Follow-ups`, and any Guardrail evidence required by an active rule;
+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;
 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.
 
-When a Run completes and work remains queued, the briefing's `## Next Up` names the next backlog Task. Surface it with `scrumrun plan task --next` and start it with `scrumrun plan task --start [TASK-NNN]` — starting is the explicit approval; the owner can always decline. Each agent declares its identity via `SCRUMRUN_AGENT` (or `Agent Identity` in `config.md`); it is recorded as the Task `assignee` and the Run event `actor`.
+When work remains queued, the briefing may name the next backlog Task. The owner starts it through natural-language approval; do not call CLI start/retry commands to manufacture operational state. Each agent may record its identity in the Task handoff when useful.
 
-Every deferred policy result is an append-only Run obligation. The final checkpoint fails closed on policy drift, protected-path changes, unsafe symlinks, unscannable content, newly introduced secret-like content, or missing Guardrail Evidence. In strict mode it additionally requires the permit chain. The ignored permit cache is disposable; deleting it invalidates outstanding strict-mode permits and never creates authority.
+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.
 
-Run is the sole operational-history authority. Task synchronizes current status without copying Run events. Validation, learning, completion, failure, block, and resume require a reason or structured evidence; completion also requires evidenced validation and learning. Early v2 prose Runs are migrated explicitly, with deterministic chains recovered and uncertain history represented as an evidenced snapshot.
+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.
 
 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.
 
@@ -157,7 +159,7 @@ scrumrun migrate --to 2 --apply
 scrumrun migrate --to 2 --rollback
 ```
 
-Inside a v1 project, `scrumrun update` runs a read-only preflight. `update --migrate` explicitly approves application of that verified plan and keeps rollback available.
+Inside a v1 project, `scrumrun update --migrate` explicitly inspects and approves application of the verified plan; ordinary update never performs migration work.
 
 Dry-run must not write project data. Apply requires a hashed inventory, byte-exact local backup, staged validation, atomic switch, mapping report, and idempotent replay. Incomplete hybrid trees reuse existing evidenced v2 relations rather than duplicating them; early v2 prose Runs upgrade to ledger schema 1 only through the same explicit apply gate. Legacy-only aggregates leave the active tree but remain byte-exact in the ignored backup. Ambiguous records are preserved as warnings or evidenced snapshots, never guessed. Vault content remains local and is never rendered. Rollback must refuse if it would erase post-migration changes.
 
@@ -165,7 +167,7 @@ Dry-run must not write project data. Apply requires a hashed inventory, byte-exa
 
 ### `scrumrun plan`
 
-- `task`: add/amend/list/show/run/audit/cancel/retry atomic work; use `--amend TASK-NNN` before it starts to refine planning truth without hand-editing Markdown. Use `type: fix` for fixes and `status: backlog` for parked work. `--next` surfaces the oldest backlog Task; `--start [TASK-NNN]` promotes it and creates its first Run.
+- `task`: optional add/amend/list/show/run/audit/cancel/retry helpers. Daily Task planning and handoff are Markdown-first; use the helpers for reports/recovery when useful.
 - `sprint`: add/amend/list/show/start/complete/block a real Task batch/timebox.
 - `feature`: add/amend/list/show/activate/complete long-lived initiatives.
 - `run`: list/show/render/stats/normalize-legacy/authorize-mutation/record-mutation/satisfy-guardrail/validate/learn/complete/resume/fail/block concrete Task attempts. `--complete` accepts `--summary "…"` to store a technical summary.