scrumrun 2.7.11 → 3.0.1

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+## 3.0.1 - 2026-08-31
+
+### Fixed
+
+- **Orphan Task recovery.** `doctor --strict` now reports `TASK_ORPHANED` when an active Task has no canonical Run. `scrumrun repair --recover-orphan-tasks` previews the affected Tasks; only `scrumrun repair --recover-orphan-tasks --apply` resets them to `backlog`, preserves a byte-exact backup, and never fabricates a Run or execution history.
+- **Direct CLI grammar.** `scrumrun plan task --start TASK-NNN` is now the canonical command form. `scrumrun sc ...` and `/sc` remain compatibility shortcuts, but generated instructions, approval output, recovery guidance, and documentation use the direct installed CLI, avoiding accidental `npx` execution loops.
+
+## 3.0.0 - 2026-08-31
+
+### Changed
+
+- **Lightweight execution is now the default.** After approval, agents work directly in application files and the linked Task Markdown, then close the Run with one `scrumrun sc plan run --finalize RUN-NNN` checkpoint.
+- **Finalization is fail-closed.** It audits the complete workspace delta, policy fingerprint, protected paths, symlink safety, scannability, secret boundary, Run ledger, and every Guardrail before completing the Task.
+- **Guardrail proof is co-located with work.** Non-automatic rules use a compact `## Guardrail Evidence` section in the Task and are validated together at finalization; missing evidence blocks completion.
+- **No network command loop.** Generated agent instructions prohibit repeated `npx scrumrun@latest` calls during execution. `npx` remains for one-off installation, migration, and recovery.
+- **Strict mode remains available.** Path-scoped Mutation Gateway permits and individual Run transitions are retained for owners who explicitly request per-edit control.
+
 ## 2.7.7 - 2026-08-24
 
 ### Added

package/CORE.md

@@ -9,7 +9,7 @@ Method version: `2.0.0`
 The canonical command is:
 
 ```text
-/sc <noun> <subject> <action> [args]
+scrumrun <noun> <subject> <action> [args]
 ```
 
 The five nouns are:
@@ -22,7 +22,7 @@ The five nouns are:
 
 Incomplete syntax lists only valid next tokens. Unknown syntax never guesses or mutates.
 
-The command manifest at `lib/commands/manifest.js` generates client prompts, compatibility adapters, help, and grammar tests. Fresh v2 integrations install only `/sc`. A v1 upgrade may install generated compatibility adapters for one release cycle.
+The command manifest at `lib/commands/manifest.js` generates client prompts, compatibility adapters, help, and grammar tests. The installed CLI is canonical; `/sc` is a client shortcut. A v1 upgrade may install generated compatibility adapters for one release cycle.
 
 ## Entity model
 
@@ -84,7 +84,7 @@ 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.** Runs are only mutated through the CLI: `sc plan run --validate | --learn | --complete | --resume | --fail | --block | --satisfy-guardrail | --authorize-mutation | --record-mutation`. Editing `runs/RUN-NNN.md` directly bypasses schema validation, produces invalid ledger events (invalid `type`, unknown evidence `kind`, missing snapshot, wrong `from`), and breaks conformance for the entire project. If the CLI does not expose the shape you need, propose a spec change through an ADR — do not invent event vocabulary. Existing hand-written Runs can be recovered with `sc plan run --normalize-legacy` (byte-exact original preserved in `.scrumrun/.migration-backup/runs/`).
+**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/`).
 
 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.
 
@@ -112,7 +112,7 @@ Normal read path:
 4. only the canonical ids and evidence relevant to current work;
 5. `.scrumrun/core.md` when method details or exceptional transitions are needed.
 
-The briefing is a progressive-disclosure index, not full context. Read it first and follow its pointers to specific artifacts (`## Where to look`, `sc knowledge study "<topic>"`). Go deeper — a Task body, a Run ledger, a Decision — only when the briefing lacks what you need. Never treat the briefing as a substitute for the canonical artifact it points to.
+The briefing is a progressive-disclosure index, not full context. Read it first and follow its pointers to specific artifacts (`## Where to look`, `scrumrun knowledge study "<topic>"`). Go deeper — a Task body, a Run ledger, a Decision — only when the briefing lacks what you need. Never treat the briefing as a substitute for the canonical artifact it points to.
 
 Lean mode is this bounded read policy; it is not permission to omit canonical truth.
 
@@ -156,7 +156,7 @@ Intake must:
 
 Policy evaluation is structured per active `GR-NNN`: `passed`, `blocked`, or `deferred`. A block must cite the exact Guardrail id and reason code. Deferred checks must be visible in the plan and re-evaluated at their named execution boundary; they are never silently counted as passed. Invalid/duplicate Guardrails or configuration that weakens approval block conformance and intake.
 
-The agent may assert the classification explicitly with `sc plan intake "…" --type fix|task|feature|docs|discovery`, overriding keyword inference (validated, with a stable reason). It may also attach a short technical explanation with `--preview "…"`, rendered in the pretty terminal layout, bound into the approval token, and stored as `## Preview` on the Task.
+The agent may assert the classification explicitly with `scrumrun plan intake "…" --type fix|task|feature|docs|discovery`, overriding keyword inference (validated, with a stable reason). It may also attach a short technical explanation with `--preview "…"`, rendered in the pretty terminal layout, bound into the approval token, and stored as `## Preview` on the Task.
 
 Before approval, do not create canonical files, update status, edit application code, or retain request content outside ignored disposable context cache. The approval token binds both canonical context and the workspace fingerprint; drift in either requires a new intake. Ambiguous acknowledgement is not approval.
 
@@ -187,7 +187,7 @@ Rules:
 - 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 `sc plan run --complete --summary "…"` so the next agent inherits what was actually done;
+- 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;
 - do not mark work complete merely because time or token budget ended.
 
@@ -197,7 +197,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. `sc plan task --next` shows it; `sc 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 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".
 
 ### Agent identity and assignment
 
@@ -264,7 +264,7 @@ Legacy sprint plan entries normally become Tasks. History attempts become Runs w
 
 ## Command reference
 
-### `/sc plan`
+### `scrumrun plan`
 
 - `task --add|--list|--show|--run|--audit|--cancel|--retry|--next|--start [TASK-NNN]`
 - `sprint --add|--list|--show|--start|--complete|--block`
@@ -273,7 +273,7 @@ Legacy sprint plan entries normally become Tasks. History attempts become Runs w
 - `intake <request> [--type fix|task|feature|docs|discovery] [--preview "…"]`
 - `challenge <question>`
 
-### `/sc knowledge`
+### `scrumrun knowledge`
 
 - `fact --add|--list|--show|--approve|--reject|--deprecate|--invalidate`
 - `decision --add|--list|--show|--resolve|--deprecate|--invalidate`
@@ -284,12 +284,12 @@ Legacy sprint plan entries normally become Tasks. History attempts become Runs w
 - `study <focus>`
 - `vault --add|--list|--show|--remove|--path`
 
-### `/sc rules`
+### `scrumrun rules`
 
 - `guardrail --add|--list|--show|--retire`
 - `reviewer --add|--list|--show|--run`
 
-### `/sc review`
+### `scrumrun review`
 
 - `code --run`
 - `artifact --run`
@@ -298,7 +298,7 @@ Legacy sprint plan entries normally become Tasks. History attempts become Runs w
 
 Review is read-only unless fixes are separately authorized. Report findings by severity with evidence.
 
-### `/sc config`
+### `scrumrun config`
 
 - `project --show|--language|--interaction|--approval|--quick-tasks`
 - `init --local|--shared|--force`

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:** `2.7.11` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+**Package:** `3.0.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).
 
@@ -48,17 +48,17 @@ npm i -g scrumrun@latest
 scrumrun update
 ```
 
-`npx scrumrun@latest <command>` also works if you prefer not to install globally, but pin the version explicitly (`@latest` or `@2.6.1`) — `npx scrumrun` alone will happily reuse a stale cached version.
+Use the installed `scrumrun` command for project work. `npx` is appropriate for one-off installation, migration, or recovery only; agents must never invoke `npx scrumrun@latest` repeatedly while executing a Task, because that adds network dependency and latency to the work loop.
 
 `install` adds the client integration; `init` creates the project tree. Initialization is local by default: `.scrumrun/` and the generated agent hint are added to `.git/info/exclude`. Use `--shared` when the team wants to commit the project memory.
 
-ScrumRun installs one canonical agent command:
+ScrumRun's canonical CLI is:
 
 ```text
-/sc <noun> <subject> <action> [args]
+scrumrun <noun> <subject> <action> [args]
 ```
 
-The five nouns are `plan`, `knowledge`, `rules`, `review`, and `config`.
+The five nouns are `plan`, `knowledge`, `rules`, `review`, and `config`. `/sc` is an optional AI-client shortcut; `scrumrun sc ...` remains a compatibility alias for existing integrations.
 
 ## Daily flow
 
@@ -85,7 +85,13 @@ Explicit approval atomically materializes the required plan artifacts and always
 EXECUTING → VALIDATING → LEARNING → COMPLETED | FAILED | BLOCKED
 ```
 
-Every approved Task carries an `## Acceptance Criteria` section so "done" is defined before work begins; `--complete --summary "…"` stores a `## Technical Summary` on the Run so the next agent inherits what was actually done. Failed retries remain available as separate Runs.
+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:
+
+```bash
+scrumrun plan run --finalize RUN-001
+```
+
+The checkpoint validates the complete delta, policy, protected paths, secret boundary, acceptance evidence, and every Guardrail before writing the Run ledger and synchronizing the Task. Failed retries remain available as separate Runs.
 
 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.
 
@@ -148,21 +154,21 @@ It is progressive disclosure: the briefing is enough for most work; the agent fo
 Update the client integrations and automatically run a read-only migration preflight:
 
 ```bash
-npx scrumrun@latest update
+scrumrun update
 ```
 
 This shows the source inventory, proposed mappings, and blockers without changing project data. Apply only the verified plan with:
 
 ```bash
-npx scrumrun@latest update --migrate
+scrumrun update --migrate
 ```
 
 The standalone workflow remains available:
 
 ```bash
-npx scrumrun@latest migrate --to 2 --dry-run
-npx scrumrun@latest migrate --to 2 --apply
-npx scrumrun@latest migrate --to 2 --rollback
+scrumrun migrate --to 2 --dry-run
+scrumrun migrate --to 2 --apply
+scrumrun migrate --to 2 --rollback
 ```
 
 Migration uses content hashes, a byte-exact ignored backup, staging validation, an atomic directory switch, a source-to-destination report, idempotent replay, and rollback protection. It also recognizes incomplete hybrid v1/v2 trees, reuses already-linked canonical work, and normalizes only deterministic schema aliases. Early v2 Run prose is preflighted and upgraded to the structured ledger by the same explicit `update --migrate` gate; ambiguous paths become evidenced snapshots instead of invented transitions. Legacy-only files leave the active tree but remain byte-exact in the ignored backup; vault contents remain local. Ambiguous history remains an explicit warning, and the migrator never invents a Sprint or Run.
@@ -170,16 +176,26 @@ Migration uses content hashes, a byte-exact ignored backup, staging validation,
 For projects that already have v2 directories but contain pre-v2 Markdown records without YAML frontmatter, use the explicit repair gate:
 
 ```bash
-npx scrumrun@latest repair
-npx scrumrun@latest repair --apply
+scrumrun repair
+scrumrun repair --apply
 ```
 
 Repair converts deterministic `## Metadata` fields into v2 frontmatter, preserves the authored body, recovers IDs from canonical filenames, and stores byte-exact backups under `.scrumrun/.migration-backup/repair/`. It does not guess ambiguous relationships; validate afterward with `doctor --strict`.
 
+If `doctor --strict` reports `TASK_ORPHANED`, first inspect the exact recovery plan, then explicitly reset only those active Tasks to backlog and start the intended one normally:
+
+```bash
+scrumrun repair --recover-orphan-tasks
+scrumrun repair --recover-orphan-tasks --apply
+scrumrun plan task --start TASK-144
+```
+
+Recovery never invents a Run or historical events; it creates a byte-exact backup before changing the Task. The final `--start` is the intentional action that creates its first Run.
+
 After migration or an integration update, verify both installed assets and project state:
 
 ```bash
-npx scrumrun@latest doctor codex --strict
+scrumrun doctor codex --strict
 ```
 
 `doctor` compares managed prompt/skill contents with the package, so an obsolete installation is reported as `stale` rather than `ok` merely because the file exists.
@@ -211,7 +227,7 @@ npx scrumrun@latest doctor codex --strict
 
 `guardrails.md` is canonical project policy. Active `GR-NNN` rules are evaluated into explicit `passed`, `blocked`, or `deferred` results; blocks identify the exact Guardrail and deferred checks stay visible for their execution-time gate. `config.md` contains preferences and cannot weaken policy. Duplicate/unknown Guardrails, disabled approval, and unsafe read-only paths fail conformance. `state.md`, `map.md`, context packages, and SQLite are generated navigation aids, never authority. `state.md` carries the same source fingerprint used by intake, an RFC3339 generation time, and a watch fingerprint for fast verified staleness checks.
 
-Approved Runs persist every deferred result as an append-only obligation and bind the exact policy plus workspace baseline. Material source edits use a 15-minute, path-scoped Mutation Gateway permit. Recording verifies before/after hashes, owner/read-only scope, symlinks, new secret-like content, and workspace drift. Validation and completion fail closed when edits bypass that chain or obligations remain unresolved.
+Approved Runs persist every deferred result as an append-only obligation and bind the exact policy plus workspace baseline. The normal final checkpoint verifies all workspace changes at once: owner/read-only scope, symlinks, new secret-like content, policy drift, and required Guardrail evidence. Completion fails closed when any verification is missing or fails. The 15-minute path-scoped Mutation Gateway remains available for teams that explicitly choose strict per-edit control.
 
 ### Owner-controlled allowlist for descriptive files
 
@@ -243,46 +259,45 @@ Rules:
 
 ```bash
 # inspect the grammar
-npx scrumrun@latest commands
+scrumrun commands
 
 # plan without writes, then approve the emitted token
-npx scrumrun@latest sc plan intake "Fix pricing rounding" --type fix --preview "Rounding moved after tax calc"
-npx scrumrun@latest sc plan intake --approve <token>
+scrumrun plan intake "Fix pricing rounding" --type fix --preview "Rounding moved after tax calc"
+scrumrun plan intake --approve <token>
 
 # record what was done at completion, so the next agent inherits it
-npx scrumrun@latest sc plan run --complete RUN-001 --note "Done" --evidence "npm test: passed" --summary "Moved rounding after tax calc in checkout/pricing.ts"
+scrumrun plan run --finalize RUN-001 --summary "Moved rounding after tax calc in checkout/pricing.ts"
 
 # auto-sequencing: surface and start the next backlog Task
-npx scrumrun@latest sc plan task --next
-npx scrumrun@latest sc plan task --start TASK-009
+scrumrun plan task --next
+scrumrun plan task --start TASK-009
 
 # authorize and record a material source mutation
-npx scrumrun@latest sc plan run --authorize-mutation RUN-001 --path src/pricing.ts
-npx scrumrun@latest sc plan run --record-mutation RUN-001 --permit MUT-... --note "Pricing change recorded"
+scrumrun plan run --authorize-mutation RUN-001 --path src/pricing.ts  # strict mode only
+scrumrun plan run --record-mutation RUN-001 --permit MUT-... --note "Pricing change recorded"
 
 # record an audit-derived Review, then resolve a persisted completion gate
-npx scrumrun@latest sc review artifact --run
-npx scrumrun@latest sc review artifact --record --task TASK-001 --run RUN-001 --evidence "npm test: passed"
-npx scrumrun@latest sc plan run --satisfy-guardrail RUN-001 --guardrail GR-003 --review REV-001
+scrumrun review artifact --run
+scrumrun review artifact --record --task TASK-001 --run RUN-001 --evidence "npm test: passed"
 
 # memory lifecycle
-npx scrumrun@latest sc knowledge insight --propose "Pricing stays in backend" --evidence src/pricing.ts
-npx scrumrun@latest sc knowledge insight --confirm INS-001
-npx scrumrun@latest sc knowledge study calculateFinalPrice
+scrumrun knowledge insight --propose "Pricing stays in backend" --evidence src/pricing.ts
+scrumrun knowledge insight --confirm INS-001
+scrumrun knowledge study calculateFinalPrice
 
 # rebuild or inspect the derived graph
-npx scrumrun@latest sc knowledge map --build
-npx scrumrun@latest sc knowledge map --show
+scrumrun knowledge map --build
+scrumrun knowledge map --show
 
 # read a Run as a human timeline instead of raw ledger JSON
-npx scrumrun@latest sc plan run --render RUN-001
+scrumrun plan run --render RUN-001
 
 # aggregate every Run in the project (p50/p95 durations, retries, guardrail counts)
-npx scrumrun@latest sc plan run --stats
-npx scrumrun@latest sc plan run --stats --task TASK-001 --json
+scrumrun plan run --stats
+scrumrun plan run --stats --task TASK-001 --json
 
 # preview a canonical-transaction recovery before touching disk
-npx scrumrun@latest sc config doctor --recover --dry-run
+scrumrun config doctor --recover --dry-run
 ```
 
 The command manifest in `lib/commands/manifest.js` generates help and compatibility adapters, preventing client grammar drift. A recorded artifact Review cannot self-declare success: ScrumRun reruns the audit and derives the `REV-NNN` verdict from the result.

package/SPEC.md

@@ -202,11 +202,11 @@ Everything through `AWAITING_APPROVAL` is read-only. It may exist in process mem
 
 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.
 
-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. A material source mutation requires a short-lived, path-scoped permit issued from that baseline; recording it verifies before/after hashes, policy freshness, path scope, read-only boundaries, symlink safety, and newly introduced secret-like content. Unrecorded workspace drift fails closed. A Run cannot complete while an obligation is unresolved or the workspace differs from its last recorded mutation.
+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.
 
 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. Validation, learning, completion, failure, block, and resume transitions require a reason or typed evidence. Task status changes without receiving a duplicate narrative history. On completion, an optional `## Technical Summary` section records what was actually done, surfaced to later intake through the briefing. 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.
+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.
 
 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.
 
@@ -274,7 +274,7 @@ scrumrun migrate --to 2 --apply
 scrumrun migrate --to 2 --rollback
 ```
 
-`npx scrumrun@latest 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` 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.
 
 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.
 
@@ -318,17 +318,17 @@ Legacy sprint entries become Tasks. History entries become Runs only with an evi
 - **I-21** Material mutations are policy-bound, path-scoped, hash-verified, append-only, and fail closed on bypass; unresolved Guardrail obligations block completion.
 - **I-22** The semantic index's declared search backend must match the runtime capabilities of the current Node.js SQLite build; conformance flags a mismatch instead of relying on lazy runtime fallback.
 - **I-23** `method.json` declares the canonical path index for every artifact family so agents navigate by declaration, not by search. Missing or drifted paths fail conformance; grep and directory scans are fallbacks, never the first step.
-- **I-24** Runs are only mutated through the CLI. A canonical Run whose ledger fails validation is a bypass — conformance reports `RUN_WRITE_BYPASS` with a pointer to the recovery command `sc plan run --normalize-legacy`, which collapses the bad ledger into a single `snapshot` event and preserves the byte-exact original under `.scrumrun/.migration-backup/runs/`.
+- **I-24** Runs are only mutated through the CLI. A canonical Run whose ledger fails validation is a bypass — conformance reports `RUN_WRITE_BYPASS` with a pointer to the recovery command `scrumrun plan run --normalize-legacy`, which collapses the bad ledger into a single `snapshot` event and preserves the byte-exact original under `.scrumrun/.migration-backup/runs/`.
 
 ## 11. Command grammar
 
 The only canonical root is:
 
 ```text
-/sc <noun> <subject> <action> [args]
+scrumrun <noun> <subject> <action> [args]
 ```
 
-Exactly five nouns exist: `plan`, `knowledge`, `rules`, `review`, and `config`. The implementation manifest is the command source of truth for help and client adapters. Fresh installs expose `/sc`; generated v1 aliases may remain for one compatibility cycle and must execute the canonical route.
+Exactly five nouns exist: `plan`, `knowledge`, `rules`, `review`, and `config`. The implementation manifest is the command source of truth for help and client adapters. The installed direct CLI is canonical; `/sc` and generated v1 aliases may remain as compatibility shortcuts for one release cycle and must execute the canonical route.
 
 Unknown syntax fails deterministically and never guesses a mutation.
 

package/bin/scrumrun.js

@@ -31,7 +31,7 @@ const { ARTIFACT_TYPES, ArtifactRepository } = require(path.join(root, "lib", "v
 const { aliases: COMMAND_ALIASES, resolveAlias, resolveRoute } = require(path.join(root, "lib", "commands", "manifest"));
 const { renderCommandHelp, renderCompatibilityPrompt, renderRootPrompt } = require(path.join(root, "lib", "commands", "render"));
 const { planRequest } = require(path.join(root, "lib", "runtime", "request-engine"));
-const { addPlanArtifact, approveRequest, nextBacklogTask, refreshErrors, refreshState, retryTask, startBacklogTask, transitionRun } = require(path.join(root, "lib", "runtime", "orchestrator"));
+const { addPlanArtifact, approveRequest, finalizeRun, nextBacklogTask, refreshErrors, refreshState, retryTask, startBacklogTask, transitionRun } = require(path.join(root, "lib", "runtime", "orchestrator"));
 const { authorizeMutation, recordMutation, satisfyGuardrail } = require(path.join(root, "lib", "runtime", "mutation-gateway"));
 const { recordArtifactReview } = require(path.join(root, "lib", "runtime", "review-service"));
 const { createMemory, listMemory, showMemory, transitionMemory } = require(path.join(root, "lib", "memory", "service"));
@@ -55,8 +55,8 @@ function usage() {
 
 Usage:
   scrumrun --version
-  scrumrun sc
-  scrumrun sc <noun> <subject> <action> [args]
+  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 init [--local|--shared] [--lean] [--no-agent-hint] [--force]
@@ -67,18 +67,18 @@ Usage:
   scrumrun migrate --to 2 --apply
   scrumrun migrate --to 2 --rollback
   scrumrun doctor [all|codex|opencode|claude] [--strict] [--recover]
-  scrumrun repair [--apply]
+  scrumrun repair [--recover-orphan-tasks] [--apply]
   scrumrun uninstall [--force]
 
 Install:
   npm i -g scrumrun@latest          # recommended
-  npx scrumrun@latest <command>     # also works; pin @latest to avoid stale npx cache
+  npx scrumrun@latest <command>     # one-off recovery only; never use in an agent loop
 
 Examples:
   scrumrun install
   scrumrun init
   scrumrun status
-  scrumrun sc knowledge decision --list
+  scrumrun knowledge decision --list
   scrumrun migrate --to 2 --dry-run
 `);
 }
@@ -318,14 +318,14 @@ 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: npx scrumrun@latest update --no-migrate");
+          console.log("\nThe project remains unchanged. Re-run update to apply the verified plan, or keep opt-out with: scrumrun update --no-migrate");
           return { status: "ready" };
         }
         const result = applyRunLedgerMigration(process.cwd());
         refreshState(path.join(process.cwd(), ".scrumrun"));
         console.log("\nApplied the verified ScrumRun Run ledger schema migration.");
         console.log(`Source fingerprint: ${result.plan.fingerprint}`);
-        console.log("Rollback remains available with: npx scrumrun@latest migrate --to 2 --rollback");
+        console.log("Rollback remains available with: scrumrun migrate --to 2 --rollback");
         return { status: result.status, result };
       }
     } catch {
@@ -344,13 +344,13 @@ 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: npx scrumrun@latest update --no-migrate");
+      console.log("\nThe project remains unchanged. Re-run update to apply the verified plan, or keep opt-out with: scrumrun update --no-migrate");
       return { status: "ready" };
     }
     const result = applyMigration(process.cwd(), { plan: preview.plan });
     console.log("\nApplied the verified ScrumRun v1 → v2 project migration.");
     console.log(`Source fingerprint: ${result.manifest.sourceInventory.rootSha256}`);
-    console.log("Rollback remains available with: npx scrumrun@latest migrate --to 2 --rollback");
+    console.log("Rollback remains available with: scrumrun migrate --to 2 --rollback");
     return { status: "applied", result };
   } catch (error) {
     console.error(`Project migration preflight failed: ${error.message}`);
@@ -1157,7 +1157,7 @@ function commandList() {
 CLI helpers:
   scrumrun status
   scrumrun commands
-  scrumrun sc knowledge decision --list
+  scrumrun knowledge decision --list
   scrumrun vault add "NAME" "local-dev-value"
   scrumrun context show
   scrumrun backlog add "Sprint 01"
@@ -1392,7 +1392,7 @@ function runSemanticContext(subject, args) {
     }
     const mapFile = path.join(process.cwd(), ".scrumrun", "map.md");
     const status = mapStatus(process.cwd());
-    if (status.stale) throw new Error(`Generated map.md is stale (${status.reason || status.error || "unknown reason"}); run /sc knowledge map --build.`);
+    if (status.stale) throw new Error(`Generated map.md is stale (${status.reason || status.error || "unknown reason"}); run scrumrun knowledge map --build.`);
     console.log(fs.readFileSync(mapFile, "utf8"));
     return;
   }
@@ -1456,7 +1456,7 @@ function executeRootRoute(route) {
       return;
     }
     console.log(`Next backlog Task: ${next.id} — ${next.title || next.id}`);
-    console.log(`Start it with: scrumrun sc plan task --start ${next.id}`);
+    console.log(`Start it with: scrumrun plan task --start ${next.id}`);
     return;
   }
   if (noun === "plan" && subject === "task" && routeArgs[0] === "--start") {
@@ -1562,6 +1562,15 @@ function executeRootRoute(route) {
     return;
   }
   if (noun === "plan" && subject === "run") {
+    if (routeArgs[0] === "--finalize") {
+      const runId = routeArgs[1];
+      if (!runId) throw new Error("--finalize requires RUN-NNN.");
+      const result = finalizeRun(process.cwd(), runId, runTransitionOptions(routeArgs.slice(2)));
+      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(", ")}.`);
+      return;
+    }
     if (routeArgs[0] === "--authorize-mutation") {
       const paths = optionValues(routeArgs.slice(2), "--path");
       const result = authorizeMutation(process.cwd(), routeArgs[1], paths);
@@ -1680,7 +1689,7 @@ function runRoot(parts) {
 
 function runCompatibilityAlias(alias, parts) {
   const route = resolveAlias(alias, parts);
-  console.warn(`Deprecated: ${alias} now executes /sc ${route.noun} ${route.subject}.`);
+  console.warn(`Deprecated: ${alias} now executes scrumrun ${route.noun} ${route.subject}.`);
   if (route.note) console.warn(route.note);
   if (alias === "sc-backlog") return runBacklog(parts);
   if (alias !== "sc-init") chdirToProjectRoot();
@@ -1696,7 +1705,7 @@ function printCore({ pathOnly = false, promptOnly = false } = {}) {
   if (promptOnly) {
     console.log(`Read AGENTS.md, .scrumrun/guardrails.md, and .scrumrun/state.md first.
 Follow ScrumRun 2.0 and load only the canonical ids/evidence relevant to the request.
-If /sc is unavailable, execute the equivalent /sc <noun> <subject> <action> workflow from .scrumrun/core.md manually.
+Use the installed CLI as scrumrun <noun> <subject> <action>; /sc is only a client shortcut.
 Keep intake read-only; do not create a Task or Run until explicit approval.`);
     return;
   }
@@ -2171,7 +2180,7 @@ function statusProject() {
     }
     console.log("");
     console.log(`Migration record: ${fs.existsSync(path.join(scrumDir, ".migration", "v1-to-v2", "manifest.json")) ? "v1-to-v2 applied" : "not applicable / native v2"}`);
-    console.log(`Canonical command: /sc`);
+    console.log(`Canonical command: scrumrun <noun> <subject> <action>`);
     return;
   }
   const required = [
@@ -2227,24 +2236,24 @@ function promptCommand(parts) {
   const kind = parts[0];
   const text = joinText(parts.slice(1));
   const prompts = {
-    intake: `/sc plan intake ${text}`.trim(),
-    study: `/sc knowledge study${text ? ` ${text}` : ""}`,
-    challenge: `/sc plan challenge ${text}`.trim(),
-    know: `/sc knowledge fact --add ${text}`.trim(),
-    "context-build": `/sc knowledge context --build${text ? ` ${text}` : ""}`,
-    "context-update": `/sc knowledge context --update${text ? ` ${text}` : ""}`,
-    "context-show": `/sc knowledge context --show${text ? ` ${text}` : ""}`,
-    context: `/sc knowledge context ${text}`.trim(),
-    vault: `/sc knowledge vault ${text}`.trim(),
-    "goal-set": `/sc plan feature --add ${text}`.trim(),
-    "goal-new": `/sc plan feature --add ${text}`.trim(),
-    goal: `/sc plan feature --add ${text}`.trim(),
-    "sprint-add": `/sc plan sprint --add ${text}`.trim(),
-    "sprint-new": `/sc plan sprint --add ${text}`.trim(),
-    "sprint-run": `/sc plan task --run ${text}`.trim(),
-    "backlog-add": `/sc plan task --add ${text} --status backlog`.trim(),
-    backlog: `/sc plan task --add ${text} --status backlog`.trim(),
-    status: `/sc plan sprint --show${text ? ` ${text}` : ""}`
+    intake: `scrumrun plan intake ${text}`.trim(),
+    study: `scrumrun knowledge study${text ? ` ${text}` : ""}`,
+    challenge: `scrumrun plan challenge ${text}`.trim(),
+    know: `scrumrun knowledge fact --add ${text}`.trim(),
+    "context-build": `scrumrun knowledge context --build${text ? ` ${text}` : ""}`,
+    "context-update": `scrumrun knowledge context --update${text ? ` ${text}` : ""}`,
+    "context-show": `scrumrun knowledge context --show${text ? ` ${text}` : ""}`,
+    context: `scrumrun knowledge context ${text}`.trim(),
+    vault: `scrumrun knowledge vault ${text}`.trim(),
+    "goal-set": `scrumrun plan feature --add ${text}`.trim(),
+    "goal-new": `scrumrun plan feature --add ${text}`.trim(),
+    goal: `scrumrun plan feature --add ${text}`.trim(),
+    "sprint-add": `scrumrun plan sprint --add ${text}`.trim(),
+    "sprint-new": `scrumrun plan sprint --add ${text}`.trim(),
+    "sprint-run": `scrumrun plan task --run ${text}`.trim(),
+    "backlog-add": `scrumrun plan task --add ${text} --status backlog`.trim(),
+    backlog: `scrumrun plan task --add ${text} --status backlog`.trim(),
+    status: `scrumrun plan sprint --show${text ? ` ${text}` : ""}`
   };
   if (!kind || !prompts[kind]) {
     console.error("Usage: scrumrun prompt <intake|study|challenge|know|context-build|context-update|vault|goal-set|sprint-add|sprint-run|backlog-add|status> [text]");
@@ -2571,6 +2580,8 @@ if (!command || command === "--help" || command === "-h") {
   else install(target, true, { compatibility: false });
 } else if (command === "sc") {
   runRoot(args.slice(1));
+} else if (["plan", "knowledge", "rules", "review", "config"].includes(command)) {
+  runRoot(args);
 } else if (COMMAND_ALIASES[command]) {
   runCompatibilityAlias(command, args.slice(1));
 } else if (command === "init") {
@@ -2585,7 +2596,8 @@ if (!command || command === "--help" || command === "-h") {
   try {
     const { repair } = require(path.join(root, "lib", "commands", "repair"));
     const doApply = args.includes("--apply");
-    const result = repair(scrumDir, { apply: doApply });
+    const recoverOrphanTasks = args.includes("--recover-orphan-tasks");
+    const result = repair(scrumDir, { apply: doApply, recoverOrphanTasks });
     console.log(result.report);
     if (!doApply && result.plan.entries.length) process.exitCode = 0;
   } catch (error) {