scrumrun 3.0.0 → 3.0.1

package/CHANGELOG.md

@@ -4,6 +4,13 @@ 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

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.** After approval, work directly in code and in the linked Task Markdown. Finish the normal session once with `scrumrun sc 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 `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:** `3.0.0` · **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).
 
@@ -52,13 +52,13 @@ Use the installed `scrumrun` command for project work. `npx` is appropriate for
 
 `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
 
@@ -88,7 +88,7 @@ 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:
 
 ```bash
-scrumrun sc plan run --finalize RUN-001
+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.
@@ -154,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.
@@ -176,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.
@@ -252,42 +262,42 @@ Rules:
 scrumrun commands
 
 # plan without writes, then approve the emitted token
-scrumrun sc plan intake "Fix pricing rounding" --type fix --preview "Rounding moved after tax calc"
-scrumrun 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
-scrumrun sc plan run --finalize RUN-001 --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
-scrumrun sc plan task --next
-scrumrun sc plan task --start TASK-009
+scrumrun plan task --next
+scrumrun plan task --start TASK-009
 
 # authorize and record a material source mutation
-scrumrun sc plan run --authorize-mutation RUN-001 --path src/pricing.ts  # strict mode only
-scrumrun 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
-scrumrun sc review artifact --run
-scrumrun sc review artifact --record --task TASK-001 --run RUN-001 --evidence "npm test: passed"
+scrumrun review artifact --run
+scrumrun review artifact --record --task TASK-001 --run RUN-001 --evidence "npm test: passed"
 
 # memory lifecycle
-scrumrun sc knowledge insight --propose "Pricing stays in backend" --evidence src/pricing.ts
-scrumrun sc knowledge insight --confirm INS-001
-scrumrun 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
-scrumrun sc knowledge map --build
-scrumrun sc knowledge map --show
+scrumrun knowledge map --build
+scrumrun knowledge map --show
 
 # read a Run as a human timeline instead of raw ledger JSON
-scrumrun sc plan run --render RUN-001
+scrumrun plan run --render RUN-001
 
 # aggregate every Run in the project (p50/p95 durations, retries, guardrail counts)
-scrumrun sc plan run --stats
-scrumrun 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

@@ -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

@@ -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") {
@@ -1689,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();
@@ -1705,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;
   }
@@ -2180,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 = [
@@ -2236,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]");
@@ -2580,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") {
@@ -2594,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) {

package/docs/COMMANDS.md

@@ -3,25 +3,25 @@
 The canonical grammar is:
 
 ```text
-/sc <noun> <subject> <action> [args]
+scrumrun <noun> <subject> <action> [args]
 ```
 
-Use `/sc` inside a supported AI client. The equivalent CLI form is `scrumrun sc ...`. Use `npx scrumrun@latest` only for one-off installation or recovery, never inside an agent's normal execution loop.
+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.
 
 ## Plan
 
 ```text
-/sc plan intake <request>
-/sc plan intake --approve <token>
-/sc plan task --add|--list|--show|--run|--audit|--cancel|--retry
-/sc plan sprint --add|--list|--show|--start|--complete|--block
-/sc plan feature --add|--list|--show|--activate|--complete
-/sc plan run --list|--show|--validate|--learn|--complete|--resume|--fail|--block [--note] [typed evidence flags]
-/sc plan run --finalize RUN-NNN [--summary "technical recap"] [--note]
-/sc plan run --authorize-mutation RUN-NNN --path <relative-path> [--path ...]
-/sc plan run --record-mutation RUN-NNN --permit MUT-id [--note] [--actor]
-/sc plan run --satisfy-guardrail RUN-NNN --guardrail GR-NNN [typed evidence flags]
-/sc plan challenge <question>
+scrumrun plan intake <request>
+scrumrun plan intake --approve <token>
+scrumrun plan task --add|--list|--show|--run|--audit|--cancel|--retry
+scrumrun plan sprint --add|--list|--show|--start|--complete|--block
+scrumrun plan feature --add|--list|--show|--activate|--complete
+scrumrun plan run --list|--show|--validate|--learn|--complete|--resume|--fail|--block [--note] [typed evidence flags]
+scrumrun plan run --finalize RUN-NNN [--summary "technical recap"] [--note]
+scrumrun plan run --authorize-mutation RUN-NNN --path <relative-path> [--path ...]
+scrumrun plan run --record-mutation RUN-NNN --permit MUT-id [--note] [--actor]
+scrumrun plan run --satisfy-guardrail RUN-NNN --guardrail GR-NNN [typed evidence flags]
+scrumrun plan challenge <question>
 ```
 
 Normal execution is Markdown-first: after approval, work in code and the 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.
@@ -29,14 +29,14 @@ Normal execution is Markdown-first: after approval, work in code and the linked
 ## Knowledge
 
 ```text
-/sc knowledge fact --add|--list|--show|--approve|--reject|--deprecate|--invalidate
-/sc knowledge decision --add|--list|--show|--resolve|--deprecate|--invalidate
-/sc knowledge insight --propose|--list|--show|--confirm|--stale|--reject|--deprecate|--invalidate
-/sc knowledge dossier --add|--list|--show|--refresh|--stale|--deprecate|--archive
-/sc knowledge context --build|--update|--show|--clear
-/sc knowledge map --build|--show
-/sc knowledge study <focus>
-/sc knowledge vault --add|--list|--show|--remove|--path
+scrumrun knowledge fact --add|--list|--show|--approve|--reject|--deprecate|--invalidate
+scrumrun knowledge decision --add|--list|--show|--resolve|--deprecate|--invalidate
+scrumrun knowledge insight --propose|--list|--show|--confirm|--stale|--reject|--deprecate|--invalidate
+scrumrun knowledge dossier --add|--list|--show|--refresh|--stale|--deprecate|--archive
+scrumrun knowledge context --build|--update|--show|--clear
+scrumrun knowledge map --build|--show
+scrumrun knowledge study <focus>
+scrumrun knowledge vault --add|--list|--show|--remove|--path
 ```
 
 Creation options include `--title`, `--content`, repeated `--evidence`, repeated `--relation "used_by: Target"`, `--subject type:id`, `--source`, `--source-id`, `--confidence`, `--valid-from`, `--valid-until`, and `--review-trigger`. Promotion options accept repeated `--evidence` and `--note`.
@@ -46,13 +46,13 @@ Creation options include `--title`, `--content`, repeated `--evidence`, repeated
 ## Rules and review
 
 ```text
-/sc rules guardrail --add|--list|--show|--retire
-/sc rules reviewer --add|--list|--show|--run
-/sc review code --run
-/sc review artifact --run
-/sc review artifact --record --task TASK-NNN [--run RUN-NNN] [--title "..."] [--evidence "..."]
-/sc review migration --run
-/sc review release --run
+scrumrun rules guardrail --add|--list|--show|--retire
+scrumrun rules reviewer --add|--list|--show|--run
+scrumrun review code --run
+scrumrun review artifact --run
+scrumrun review artifact --record --task TASK-NNN [--run RUN-NNN] [--title "..."] [--evidence "..."]
+scrumrun review migration --run
+scrumrun review release --run
 ```
 
 `review artifact --run` is read-only and returns a machine-readable 21-invariant project audit. `--record` reruns that audit and persists its exact pass/fail result as a canonical `REV-NNN`; supplied evidence is additive and cannot turn a failed audit into a pass. Other review routes require repository reasoning and remain read-only unless fixes receive separate approval.
@@ -60,13 +60,13 @@ Creation options include `--title`, `--content`, repeated `--evidence`, repeated
 ## Config and lifecycle
 
 ```text
-/sc config project --show|--language|--interaction|--approval|--quick-tasks
-/sc config init --local|--shared|--lean|--no-agent-hint|--force
-/sc config update [all|codex|opencode|claude] [--migrate]
-/sc config migrate --to 2 --dry-run|--apply|--rollback
-/sc config doctor [all|codex|opencode|claude] [--strict] [--recover]
-/sc config uninstall --force
-/sc config help <topic>
+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 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.

package/docs/DEMO.md

@@ -28,13 +28,13 @@ Inside the recording, run these commands slowly (about 5 seconds of
 reading between each), typing them yourself so viewers see the cadence:
 
 ```bash
-npx scrumrun@latest install --client claude
-npx scrumrun@latest init
-npx scrumrun@latest sc plan intake "Fix duplicate charges after refresh"
+scrumrun install --client claude
+scrumrun init
+scrumrun plan intake "Fix duplicate charges after refresh"
 # copy the approval token printed above
-npx scrumrun@latest sc plan intake --approve <token>
-npx scrumrun@latest sc plan run --render RUN-001
-npx scrumrun@latest sc plan run --stats
+scrumrun plan intake --approve <token>
+scrumrun plan run --render RUN-001
+scrumrun plan run --stats
 ```
 
 Exit the shell (`exit`) to stop the recording.