scrumrun 3.0.0 → 3.0.1

package/docs/ERROR-CODES.md

@@ -65,8 +65,8 @@ SR-E-102 Run transition rejected: missing validation or learning evidence.
 
 | Code | Summary | Remediation |
 |---|---|---|
-| `SR-E-100` | Run not found. | Check the RUN-NNN id with `sc plan run --list`. |
-| `SR-E-101` | Run ledger contains an invalid event. | Inspect the reported event id; use `sc plan run --render` for a human view or restore from git history. |
+| `SR-E-100` | Run not found. | Check the RUN-NNN id with `scrumrun plan run --list`. |
+| `SR-E-101` | Run ledger contains an invalid event. | Inspect the reported event id; use `scrumrun plan run --render` for a human view or restore from git history. |
 | `SR-E-102` | Run transition rejected: missing validation or learning evidence. | Complete `--validate` and `--learn` with typed evidence before `--complete`. |
 | `SR-E-103` | Retry rejected because the previous Run is still active. | Complete, fail, or block the current Run before creating a retry. |
 
@@ -75,14 +75,14 @@ SR-E-102 Run transition rejected: missing validation or learning evidence.
 | Code | Summary | Remediation |
 |---|---|---|
 | `SR-E-150` | Guardrail check blocked the operation. | Read the reported GR-NNN, satisfy or retire it explicitly; guardrails never bypass silently. |
-| `SR-E-151` | Guardrail obligation is still pending. | Resolve each pending guardrail via `sc plan run --satisfy-guardrail` before completing the Run. |
+| `SR-E-151` | Guardrail obligation is still pending. | Resolve each pending guardrail via `scrumrun plan run --satisfy-guardrail` before completing the Run. |
 | `SR-E-152` | Guardrail declaration is malformed. | Every active guardrail requires Status, Enforcement, Scope, and Rule fields; check `.scrumrun/guardrails.md`. |
 
 ### Edit permits (Mutation Gateway)
 
 | Code | Summary | Remediation |
 |---|---|---|
-| `SR-E-200` | No edit permit for this path. | Request one with `sc plan run --authorize-mutation RUN-NNN --path <path>` before editing canonical or source files. |
+| `SR-E-200` | No edit permit for this path. | Request one with `scrumrun plan run --authorize-mutation RUN-NNN --path <path>` before editing canonical or source files. |
 | `SR-E-201` | Edit permit expired. | Permits last 15 minutes. Authorize a new one and record the change immediately. |
 | `SR-E-202` | Edit permit path scope mismatch. | The permit does not cover the modified path. Request a new permit that lists it. |
 | `SR-E-203` | File hash changed unexpectedly since the permit was issued. | Someone else modified the file. Re-plan the change and request a fresh permit. |
@@ -91,28 +91,28 @@ SR-E-102 Run transition rejected: missing validation or learning evidence.
 
 | Code | Summary | Remediation |
 |---|---|---|
-| `SR-E-250` | Pending kernel transaction cannot be recovered automatically. | Run `sc config doctor --recover --dry-run` to preview; if it shows "would overwrite owner changes", reconcile the file manually before applying. |
+| `SR-E-250` | Pending kernel transaction cannot be recovered automatically. | Run `scrumrun config doctor --recover --dry-run` to preview; if it shows "would overwrite owner changes", reconcile the file manually before applying. |
 | `SR-E-251` | Journal fails integrity check. | Inspect `.scrumrun/.transactions/pending`. Do not delete; contact support or restore from backup. |
 
 ### Memory
 
 | Code | Summary | Remediation |
 |---|---|---|
-| `SR-E-300` | Memory candidate rejected: missing resolvable evidence. | Attach at least one `--evidence` path or `sc knowledge <subject> --propose` before `--confirm`. |
+| `SR-E-300` | Memory candidate rejected: missing resolvable evidence. | Attach at least one `--evidence` path or `scrumrun knowledge <subject> --propose` before `--confirm`. |
 | `SR-E-301` | Attempt to write into vault via canonical channel. | `vault.local.md` is local-only and never indexed. Edit the file directly. |
 
 ### Semantic index and code intelligence
 
 | Code | Summary | Remediation |
 |---|---|---|
-| `SR-E-350` | Semantic index is stale. | Rebuild with `sc knowledge map --build`. Cache is disposable; canonical memory is unaffected. |
-| `SR-E-351` | Search backend advertised in the cache does not match this runtime. | Delete `.scrumrun/.cache/semantic-index.sqlite` and re-run any `sc knowledge` query to rebuild against the current runtime. |
+| `SR-E-350` | Semantic index is stale. | Rebuild with `scrumrun knowledge map --build`. Cache is disposable; canonical memory is unaffected. |
+| `SR-E-351` | Search backend advertised in the cache does not match this runtime. | Delete `.scrumrun/.cache/semantic-index.sqlite` and re-run any `scrumrun knowledge` query to rebuild against the current runtime. |
 
 ### Migration
 
 | Code | Summary | Remediation |
 |---|---|---|
-| `SR-E-400` | Migration preflight failed. | Run `npx scrumrun@latest update` (dry) to see blockers, resolve them, then apply with `--migrate`. |
+| `SR-E-400` | Migration preflight failed. | Run `scrumrun update` (dry) to see blockers, resolve them, then apply with `--migrate`. |
 | `SR-E-401` | Migration rollback requested but no backup was found. | Rollback needs the ignored byte-exact backup created during `--migrate`. Restore from version control if the backup is gone. |
 
 ### Conformance and doctor
@@ -120,13 +120,13 @@ SR-E-102 Run transition rejected: missing validation or learning evidence.
 | Code | Summary | Remediation |
 |---|---|---|
 | `SR-E-450` | Conformance check failed. | The reported invariant identifies the exact violation; the message includes the file and expected shape. |
-| `SR-E-451` | Installed client asset is stale. | Re-run `npx scrumrun@latest update` for the specific client. `doctor --strict` shows which files diverge. |
+| `SR-E-451` | Installed client asset is stale. | Re-run `scrumrun update` for the specific client. `doctor --strict` shows which files diverge. |
 
 ### Configuration and installation
 
 | Code | Summary | Remediation |
 |---|---|---|
-| `SR-E-500` | ScrumRun project not initialized. | Run `npx scrumrun@latest init` in the repository root. |
+| `SR-E-500` | ScrumRun project not initialized. | Run `scrumrun init` in the repository root. |
 | `SR-E-501` | Unsupported Node.js runtime. | ScrumRun requires Node.js >=22.13.0 for native SQLite. Upgrade Node and retry. |
 
 ## Adding a new code

package/docs/QUICKSTART.md

@@ -22,8 +22,8 @@ can follow it.
 You need Node.js 22.13 or newer.
 
 ```bash
-npx scrumrun@latest install    # installs the agent integration for your client
-npx scrumrun@latest init       # creates the .scrumrun/ tree in the current repo
+scrumrun install    # installs the agent integration for your client
+scrumrun init       # creates the .scrumrun/ tree in the current repo
 ```
 
 By default `.scrumrun/` is added to `.git/info/exclude` — the methodology
@@ -47,7 +47,7 @@ Classification: Task (fix)
 Risk: high — financial path
 Why: Payment behavior changed after completed work; corrective Task
      linked to the original Run history.
-Next: /sc plan intake "double charge on refresh"
+Next: scrumrun plan intake "double charge on refresh"
 Awaiting owner approval.
 ```
 
@@ -55,7 +55,7 @@ Nothing has been written yet. The classification, risk, and plan are
 proposals. Approving is one command:
 
 ```bash
-npx scrumrun@latest sc plan intake --approve <token>
+scrumrun plan intake --approve <token>
 ```
 
 In an interactive terminal, the output is rendered as a boxed intake
@@ -87,7 +87,7 @@ You can render a Run's ledger as a human timeline instead of reading the
 raw JSON:
 
 ```bash
-npx scrumrun@latest sc plan run --render RUN-001
+scrumrun plan run --render RUN-001
 ```
 
 For aggregate signal across every Run in the project — status mix, p50
@@ -95,9 +95,9 @@ and p95 time in `VALIDATING`, retries per Task, guardrail check counts —
 use `--stats`:
 
 ```bash
-npx scrumrun@latest sc plan run --stats
-npx scrumrun@latest sc plan run --stats --task TASK-001
-npx scrumrun@latest sc plan run --stats --json
+scrumrun plan run --stats
+scrumrun plan run --stats --task TASK-001
+scrumrun plan run --stats --json
 ```
 
 ## Reading the memory
@@ -113,8 +113,8 @@ Nothing becomes canonical without confirmation. AI extraction creates
 candidates; you promote them with evidence.
 
 ```bash
-npx scrumrun@latest sc knowledge insight --propose "..." --evidence src/foo.ts
-npx scrumrun@latest sc knowledge insight --confirm INS-001
+scrumrun knowledge insight --propose "..." --evidence src/foo.ts
+scrumrun knowledge insight --confirm INS-001
 ```
 
 Ask the agent things like *"why is calculateFinalPrice in checkout?"* or
@@ -134,10 +134,10 @@ the memory index, not by guessing.
 
 ## Common questions
 
-**Do I have to type `/sc` commands?** No. Natural language is the primary
-entry point. The `/sc` grammar exists for scripting and reproducibility.
+**Do I have to type commands?** No. Natural language is the primary entry
+point. For scripting and reproducibility, use `scrumrun <noun> <subject> <action>`; `/sc` is only an AI-client shortcut.
 
-**What if I already use v1?** Run `npx scrumrun@latest update` for a
+**What if I already use v1?** Run `scrumrun update` for a
 read-only migration preflight, then `update --migrate` when you are
 satisfied with the plan.
 
@@ -158,5 +158,5 @@ for the exact remediation. If a canonical transaction was interrupted,
 preview the repair before running it:
 
 ```bash
-npx scrumrun@latest sc config doctor --recover --dry-run
+scrumrun config doctor --recover --dry-run
 ```

package/docs/RELEASE-SCORECARD.md

@@ -26,7 +26,7 @@ Minimum local score: **9.7/10**.
 - Full suite: `npm test`.
 - Performance suite: `npm run benchmark`.
 - Contract drift: `scripts/generate-contract-docs.js --check` runs before tests.
-- Project conformance: `/sc review artifact --run`, twenty-one invariants, zero findings at the release checkpoint.
+- Project conformance: `scrumrun review artifact --run`, twenty-one invariants, zero findings at the release checkpoint.
 - Installed integration: `doctor codex --strict`, exact prompt/skill hashes and zero project findings.
 - Package boundary: `npm pack --dry-run --json`, explicit file inventory, no repository-local `.scrumrun/`, tests, vault, backup, migration state, or cache.
 - Tarball E2E: install, v2 memory, ongoing v1 migration, rollback, doctor, and uninstall run from the packed package in the test suite.

package/docs/RELEASE.md

@@ -11,7 +11,7 @@ npm test
 npm run benchmark
 git diff --check
 npm pack --dry-run
-npx scrumrun@latest sc review artifact --run   # in a clean v2 fixture/current package equivalent
+scrumrun review artifact --run   # in a clean v2 fixture/current package equivalent
 ```
 
 Confirm package contents exclude repository-local `.scrumrun/` state, caches, migration records, backups, vaults, tests, and secrets. The `.scrumrun/` directory inside project templates is expected. Confirm package metadata, README, changelog, tarball filename, checksum, and Git tag agree on `2.1.1`; SPEC, CORE, artifact frontmatter, migration, and installed skill continue to declare method `2.0.0`.

package/docs/SEMANTIC-MEMORY.md

@@ -60,9 +60,9 @@ Entering `learning` extracts `INS-NNN` candidates. Malformed extraction emits a
 ## Query and maintenance
 
 ```bash
-npx scrumrun@latest sc knowledge map --build
-npx scrumrun@latest sc knowledge study calculateFinalPrice
-npx scrumrun@latest sc knowledge context --clear
+scrumrun knowledge map --build
+scrumrun knowledge study calculateFinalPrice
+scrumrun knowledge context --clear
 ```
 
 SQLite is ignored and disposable. The derived index records its search backend: FTS5/BM25 is selected when the current Node.js SQLite build supports it; otherwise ScrumRun uses deterministic parameterized token matching over the same artifact, code, and relation tables. Queries default to 10 records/40 relations and hard-cap at 100/100. Match type, truth state, warnings, relation counts, and evidence are returned so recommendations remain explainable.

package/docs/TROUBLESHOOTING.md

@@ -2,7 +2,7 @@
 
 ## “Project must be explicitly migrated to v2”
 
-Run `npx scrumrun@latest update` for a read-only preflight, then review and apply with `update --migrate`. See [`MIGRATION-1-to-2.md`](../MIGRATION-1-to-2.md).
+Run `scrumrun update` for a read-only preflight, then review and apply with `update --migrate`. See [`MIGRATION-1-to-2.md`](../MIGRATION-1-to-2.md).
 
 ## Migration is blocked
 
@@ -22,7 +22,7 @@ Rollback detected post-migration work that it would erase. Copy/export wanted ch
 `state.md` refreshes after runtime transitions. Rebuild the semantic map with:
 
 ```bash
-npx scrumrun@latest sc knowledge map --build
+scrumrun knowledge map --build
 ```
 
 Fresh projections include a source fingerprint and a watch fingerprint. A matching watch avoids a full read. If file metadata changed, ScrumRun hashes canonical/source content before deciding whether the projection is actually stale. `check: "schema"` means the disposable SQLite format changed and one rebuild is required; `check: "hash"` means the safe fallback was used.
@@ -34,7 +34,7 @@ Stale generated views are warnings, not canonical corruption.
 An approved multi-file mutation was interrupted after its durable journal was prepared. Ordinary doctor/audit is read-only and leaves the evidence untouched. Either retry the same approved operation, which recovers before writing, or explicitly run:
 
 ```bash
-npx scrumrun@latest doctor codex --recover --strict
+scrumrun doctor codex --recover --strict
 ```
 
 Prepared transactions restore their original bytes; committed transactions verify the applied bytes and finalize. Recovery refuses if a target changed to content matching neither journal side, because that would overwrite later owner work. Receipts contain hashes and outcomes, not file contents.
@@ -44,8 +44,8 @@ Prepared transactions restore their original bytes; committed transactions verif
 Delete or clear only the disposable cache:
 
 ```bash
-npx scrumrun@latest sc knowledge context --clear
-npx scrumrun@latest sc knowledge map --build
+scrumrun knowledge context --clear
+scrumrun knowledge map --build
 ```
 
 Canonical Markdown is unchanged. Query automatically rebuilds a missing/stale index.
@@ -61,10 +61,10 @@ Inspect its invalidation warning and code/evidence relations. For a real code mo
 ## Doctor reports missing clients
 
 ```bash
-npx scrumrun@latest install codex
-npx scrumrun@latest install claude
-npx scrumrun@latest install opencode
-npx scrumrun@latest doctor all
+scrumrun install codex
+scrumrun install claude
+scrumrun install opencode
+scrumrun doctor all
 ```
 
 Use `doctor --compat` only while validating one-cycle v1 adapters.

package/lib/commands/normalize-legacy.js

@@ -1,6 +1,6 @@
 "use strict";
 
-// `sc plan run --normalize-legacy [--dry-run]`
+// `scrumrun plan run --normalize-legacy [--dry-run]`
 //
 // Reads every Run under `.scrumrun/runs/` and validates its ledger
 // against the current schema. When a Run fails validation (invalid

package/lib/commands/pretty-intake.js

@@ -244,7 +244,7 @@ function renderIntake(plan) {
       }
     }
   } else if (plan.approvalToken) {
-    const command = "scrumrun sc plan intake --approve";
+    const command = "scrumrun plan intake --approve";
     const tokenWidth = Math.max(16, width - 8);
     const materialization = plan.proposal && plan.proposal.materialization ? plan.proposal.materialization.summary : "Task + Run";
     lines.push(boxLine(width, `  ${paint(FG.gray, `APPROVE · copy the command below to create ${materialization}`)}`));
@@ -274,7 +274,7 @@ function renderIntakePlain(plan) {
     lines.push(`DEFERRED: ${result.guardrail} ${result.code}: ${result.message}`);
   }
   for (const warning of plan.context.warnings) lines.push(`WARNING: ${warning}`);
-  if (plan.approvalToken) lines.push(`Approval: scrumrun sc plan intake --approve ${plan.approvalToken}`);
+  if (plan.approvalToken) lines.push(`Approval: scrumrun plan intake --approve ${plan.approvalToken}`);
   return lines.join("\n");
 }
 

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 \`/sc <noun> <subject> <action> [args]\`.
+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\`.
 
 ## Grammar
 
@@ -35,7 +35,7 @@ ${grammarLines().join("\n")}
 - Linked Task/Run writes use a durable recovery journal; audit reports pending recovery and never repairs without explicit authorization.
 - \`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 \`sc 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.
+- 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.
 - Knowledge/Decision/Insight records require evidence; AI-proposed Insights remain \`candidate\` until confirmed.
 - Never print vault values or write before approval.
@@ -48,7 +48,7 @@ Method: ${METHOD_VERSION}. Command grammar source: \`lib/commands/manifest.js\`.
 function renderCompatibilityPrompt(alias) {
   const spec = aliases[alias];
   if (!spec) throw new Error(`Unknown compatibility alias: ${alias}`);
-  const target = `/sc ${spec.target.join(" ")}`;
+  const target = `scrumrun ${spec.target.join(" ")}`;
   return `---
 description: Deprecated ScrumRun v1 adapter — executes ${target}
 argument-hint: [action] [args]
@@ -63,11 +63,14 @@ Emit one concise deprecation note: \`/${alias}\` becomes \`${target}\` in ScrumR
 }
 
 function renderCommandHelp() {
-  const nounLines = Object.entries(nouns).map(([noun, spec]) => `  /sc ${noun.padEnd(10)} ${spec.description}`);
-  const aliasLines = Object.entries(aliases).map(([alias, spec]) => `  /${alias.padEnd(14)} -> /sc ${spec.target.join(" ")}`);
+  const nounLines = Object.entries(nouns).map(([noun, spec]) => `  scrumrun ${noun.padEnd(10)} ${spec.description}`);
+  const aliasLines = Object.entries(aliases).map(([alias, spec]) => `  /${alias.padEnd(14)} -> scrumrun ${spec.target.join(" ")}`);
   return `ScrumRun ${METHOD_VERSION} command grammar:
 
 Canonical root:
+  scrumrun <noun> <subject> <action> [args]
+
+Client compatibility shortcut:
   /sc <noun> <subject> <action> [args]
 
 Nouns:

package/lib/commands/repair.js

@@ -14,13 +14,16 @@
 //   4. run.attempt missing → 1 (documented default).
 //   5. Sprint task projections: add Task.sprint references absent from the
 //      Sprint's `## Tasks` list. Extra entries remain for human review.
+//   6. Orphan active Tasks: explicitly reset a Task with no associated Run to
+//      backlog. This never invents history; a later `task --start` creates
+//      the first real Run.
 //
 // Categories intentionally NOT touched (need human judgment):
 //   - Secret-like content (SECRET_CANONICAL)
 //   - Missing Acceptance Criteria sections
 //   - Guardrail scope/enforcement (authored semantics)
 //   - Task/Run status disagreements (requires domain knowledge)
-//   - Empty Run ledgers (use `sc plan run --normalize-legacy`)
+//   - Empty Run ledgers (use `scrumrun plan run --normalize-legacy`)
 //
 // Every mutated file is backed up byte-exact under
 // `.scrumrun/.migration-backup/repair/<relative-path>` before being rewritten.
@@ -430,6 +433,37 @@ function planOrphanRuns(scrumDir, taskIds) {
   return orphans;
 }
 
+function planOrphanTasks(scrumDir) {
+  const runTasks = new Set();
+  for (const file of listDir(path.join(scrumDir, "runs"), RUN_FILE)) {
+    const split = splitFrontmatter(readIf(file));
+    const task = split && extractField(split.header, "task");
+    if (TASK_REF.test(task || "")) runTasks.add(task);
+  }
+  const active = new Set(["running", "validating", "learning", "partial"]);
+  const orphans = [];
+  for (const file of listDir(path.join(scrumDir, "tasks"), TASK_FILE)) {
+    const original = readIf(file);
+    const split = splitFrontmatter(original);
+    if (!split) continue;
+    const id = extractField(split.header, "id") || path.basename(file, ".md");
+    const status = extractField(split.header, "status");
+    if (!TASK_REF.test(id) || !active.has(status) || runTasks.has(id)) continue;
+    const header = replaceField(split.header, "status", "backlog");
+    const updated = extractField(header, "updated");
+    const nextHeader = updated !== undefined ? replaceField(header, "updated", new Date().toISOString().slice(0, 10)) : header;
+    orphans.push({
+      id,
+      status,
+      file,
+      originalText: original,
+      nextText: `---\n${nextHeader}\n---${split.sep}${split.body}`,
+      reason: `${id} is ${status} but no Run references it.`
+    });
+  }
+  return orphans;
+}
+
 function planFile(file, kind, ctx) {
   const original = readIf(file);
   if (original === null) return null;
@@ -657,12 +691,13 @@ function planGuardrails(scrumDir) {
   return { file, kind: "guardrails", changes, nextText: text, originalText: original };
 }
 
-function analyze(scrumDir) {
+function analyze(scrumDir, { recoverOrphanTasks = false } = {}) {
   const featureIds = scanFeatureIds(scrumDir);
   const taskIds = scanTaskIds(scrumDir);
   const ctx = { featureIds };
   const entries = planMissingFrontmatter(scrumDir);
   const orphanRuns = planOrphanRuns(scrumDir, taskIds);
+  const orphanTasks = planOrphanTasks(scrumDir);
 
   const guardrailPlan = planGuardrails(scrumDir);
   if (guardrailPlan) entries.push(guardrailPlan);
@@ -704,7 +739,7 @@ function analyze(scrumDir) {
       totals.byField[change.field] = (totals.byField[change.field] || 0) + 1;
     }
   }
-  return { entries, totals, orphanRuns };
+  return { entries, totals, orphanRuns, orphanTasks, recoverOrphanTasks };
 }
 
 function writeWithBackup(scrumDir, backupRoot, file, originalText, nextText) {
@@ -760,7 +795,18 @@ function apply(scrumDir, plan) {
     applied.push({ ...rec, changes: entry.changes });
   }
 
-  // Pass 5: rebuild the disposable state.md briefing so it reflects the
+  // Pass 5: only after every ordinary deterministic repair has settled, reset
+  // explicitly requested orphan Tasks. This avoids one repair pass erasing
+  // another file's frontmatter update.
+  const recoveredTasks = [];
+  if (plan.recoverOrphanTasks) {
+    for (const orphan of planOrphanTasks(scrumDir)) {
+      const rec = writeWithBackup(scrumDir, backupRoot, orphan.file, orphan.originalText, orphan.nextText);
+      recoveredTasks.push({ ...rec, id: orphan.id, from: orphan.status, to: "backlog" });
+    }
+  }
+
+  // Pass 6: rebuild the disposable state.md briefing so it reflects the
   // repaired canonical tree (otherwise doctor keeps warning STATE_STALE).
   try {
     require("../runtime/orchestrator").refreshState(scrumDir);
@@ -769,7 +815,7 @@ function apply(scrumDir, plan) {
     // if it truly cannot be rebuilt.
   }
 
-  return { applied, ledger: ledgerResult, quarantined };
+  return { applied, ledger: ledgerResult, quarantined, recoveredTasks };
 }
 
 function renderReport(plan, applied) {
@@ -778,6 +824,7 @@ function renderReport(plan, applied) {
   lines.push(`Files needing frontmatter repair: ${plan.entries.length}`);
   if (plan.ledgerMalformed) lines.push(`Run ledgers to normalize:        ${plan.ledgerMalformed}`);
   if (plan.orphanRuns && plan.orphanRuns.length) lines.push(`Orphan Runs to quarantine:       ${plan.orphanRuns.length}`);
+  if (plan.orphanTasks && plan.orphanTasks.length) lines.push(`Orphan active Tasks found:        ${plan.orphanTasks.length}`);
   const byField = plan.totals.byField;
   if (Object.keys(byField).length) {
     lines.push("\nBy field:");
@@ -793,15 +840,21 @@ function renderReport(plan, applied) {
     }
     if (plan.entries.length > 30) lines.push(`  … and ${plan.entries.length - 30} more`);
   }
+  if (plan.orphanTasks && plan.orphanTasks.length && !plan.recoverOrphanTasks) {
+    lines.push("\nOrphan active Tasks are not changed automatically. Review and run: scrumrun repair --recover-orphan-tasks --apply");
+    for (const orphan of plan.orphanTasks.slice(0, 30)) lines.push(`  - ${orphan.id}: ${orphan.reason}`);
+  }
   if (applied) {
     lines.push("");
     const frontmatterCount = applied.applied ? applied.applied.length : 0;
     const ledgerCount = applied.ledger && applied.ledger.applied ? applied.ledger.applied.length : 0;
     const quarantinedCount = applied.quarantined ? applied.quarantined.length : 0;
-    if (frontmatterCount || ledgerCount || quarantinedCount) {
+    const recoveredTaskCount = applied.recoveredTasks ? applied.recoveredTasks.length : 0;
+    if (frontmatterCount || ledgerCount || quarantinedCount || recoveredTaskCount) {
       if (frontmatterCount) lines.push(`Applied: ${frontmatterCount} frontmatter file(s) rewritten.`);
       if (ledgerCount) lines.push(`Normalized: ${ledgerCount} Run ledger(s) collapsed to snapshot events.`);
       if (quarantinedCount) lines.push(`Quarantined: ${quarantinedCount} orphan Run(s) moved to .scrumrun/.migration-backup/repair/orphan-runs/.`);
+      if (recoveredTaskCount) lines.push(`Recovered: ${recoveredTaskCount} orphan active Task(s) reset to backlog; start each explicitly to create a Run.`);
       lines.push("Backups under .scrumrun/.migration-backup/repair/ and .scrumrun/.migration-backup/runs/.");
     } else {
       lines.push("Applied: no changes.");
@@ -813,11 +866,11 @@ function renderReport(plan, applied) {
   return lines.join("\n");
 }
 
-function repair(scrumDir, { apply: doApply = false } = {}) {
+function repair(scrumDir, { apply: doApply = false, recoverOrphanTasks = false } = {}) {
   if (!fs.existsSync(scrumDir) || !fs.lstatSync(scrumDir).isDirectory()) {
     throw new Error(".scrumrun/ not found; run this inside a ScrumRun project.");
   }
-  const plan = analyze(scrumDir);
+  const plan = analyze(scrumDir, { recoverOrphanTasks });
   let ledgerPreview = null;
   try {
     ledgerPreview = normalizeLegacyRuns(scrumDir, { dryRun: true }).plan;

package/lib/errors.js

@@ -31,44 +31,44 @@ const CATALOG = Object.freeze({
   "SR-E-052": { summary: "Approval token expired.", remediation: "Re-run intake to obtain a fresh token before approving." },
 
   // Runs and ledger
-  "SR-E-100": { summary: "Run not found.", remediation: "Check the RUN-NNN id with `sc plan run --list`." },
-  "SR-E-101": { summary: "Run ledger contains an invalid event.", remediation: "Inspect the reported event id; use `sc plan run --render` for a human view or restore from git history." },
+  "SR-E-100": { summary: "Run not found.", remediation: "Check the RUN-NNN id with `scrumrun plan run --list`." },
+  "SR-E-101": { summary: "Run ledger contains an invalid event.", remediation: "Inspect the reported event id; use `scrumrun plan run --render` for a human view or restore from git history." },
   "SR-E-102": { summary: "Run transition rejected: missing validation or learning evidence.", remediation: "Complete `--validate` and `--learn` with typed evidence before `--complete`." },
   "SR-E-103": { summary: "Retry rejected because the previous Run is still active.", remediation: "Complete, fail, or block the current Run before creating a retry." },
 
   // Guardrails
   "SR-E-150": { summary: "Guardrail check blocked the operation.", remediation: "Read the reported GR-NNN, satisfy or retire it explicitly; guardrails never bypass silently." },
-  "SR-E-151": { summary: "Guardrail obligation is still pending.", remediation: "Resolve each `pending guardrail` via `sc plan run --satisfy-guardrail` before completing the Run." },
+  "SR-E-151": { summary: "Guardrail obligation is still pending.", remediation: "Resolve each `pending guardrail` via `scrumrun plan run --satisfy-guardrail` before completing the Run." },
   "SR-E-152": { summary: "Guardrail declaration is malformed.", remediation: "Every active guardrail requires Status, Enforcement, Scope, and Rule fields; check .scrumrun/guardrails.md." },
 
   // Edit permits (Mutation Gateway)
-  "SR-E-200": { summary: "No edit permit for this path.", remediation: "Request one with `sc plan run --authorize-mutation RUN-NNN --path <path>` before editing canonical or source files." },
+  "SR-E-200": { summary: "No edit permit for this path.", remediation: "Request one with `scrumrun plan run --authorize-mutation RUN-NNN --path <path>` before editing canonical or source files." },
   "SR-E-201": { summary: "Edit permit expired.", remediation: "Permits last 15 minutes. Authorize a new one and record the change immediately." },
   "SR-E-202": { summary: "Edit permit path scope mismatch.", remediation: "The permit does not cover the modified path. Request a new permit that lists it." },
   "SR-E-203": { summary: "File hash changed unexpectedly since the permit was issued.", remediation: "Someone else modified the file. Re-plan the change and request a fresh permit." },
 
   // Transactions and recovery
-  "SR-E-250": { summary: "Pending kernel transaction cannot be recovered automatically.", remediation: "Run `sc config doctor --recover --dry-run` to preview; if it shows 'would overwrite owner changes', reconcile the file manually before applying." },
+  "SR-E-250": { summary: "Pending kernel transaction cannot be recovered automatically.", remediation: "Run `scrumrun config doctor --recover --dry-run` to preview; if it shows 'would overwrite owner changes', reconcile the file manually before applying." },
   "SR-E-251": { summary: "Journal fails integrity check.", remediation: "Inspect .scrumrun/.transactions/pending. Do not delete; contact support or restore from backup." },
 
   // Memory
-  "SR-E-300": { summary: "Memory candidate rejected: missing resolvable evidence.", remediation: "Attach at least one --evidence path or `sc knowledge <subject> --propose` before `--confirm`." },
+  "SR-E-300": { summary: "Memory candidate rejected: missing resolvable evidence.", remediation: "Attach at least one --evidence path or `scrumrun knowledge <subject> --propose` before `--confirm`." },
   "SR-E-301": { summary: "Attempt to write into vault via canonical channel.", remediation: "vault.local.md is local-only and never indexed. Edit the file directly." },
 
   // Semantic index / code intel
-  "SR-E-350": { summary: "Semantic index is stale.", remediation: "Rebuild with `sc knowledge map --build`. Cache is disposable; canonical memory is unaffected." },
-  "SR-E-351": { summary: "Search backend advertised in the cache does not match this runtime.", remediation: "Delete .scrumrun/.cache/semantic-index.sqlite and re-run any `sc knowledge` query to rebuild against the current runtime." },
+  "SR-E-350": { summary: "Semantic index is stale.", remediation: "Rebuild with `scrumrun knowledge map --build`. Cache is disposable; canonical memory is unaffected." },
+  "SR-E-351": { summary: "Search backend advertised in the cache does not match this runtime.", remediation: "Delete .scrumrun/.cache/semantic-index.sqlite and re-run any `scrumrun knowledge` query to rebuild against the current runtime." },
 
   // Migration
-  "SR-E-400": { summary: "Migration preflight failed.", remediation: "Run `npx scrumrun@latest update` (dry) to see blockers, resolve them, then apply with `--migrate`." },
+  "SR-E-400": { summary: "Migration preflight failed.", remediation: "Run `scrumrun update` (dry) to see blockers, resolve them, then apply with `--migrate`." },
   "SR-E-401": { summary: "Migration rollback requested but no backup was found.", remediation: "Rollback needs the ignored byte-exact backup created during --migrate. Restore from version control if the backup is gone." },
 
   // Conformance / doctor
   "SR-E-450": { summary: "Conformance check failed.", remediation: "The reported invariant identifies the exact violation; the message includes the file and expected shape." },
-  "SR-E-451": { summary: "Installed client asset is stale.", remediation: "Re-run `npx scrumrun@latest update` for the specific client. `doctor --strict` shows which files diverge." },
+  "SR-E-451": { summary: "Installed client asset is stale.", remediation: "Re-run `scrumrun update` for the specific client. `doctor --strict` shows which files diverge." },
 
   // Configuration / install
-  "SR-E-500": { summary: "ScrumRun project not initialized.", remediation: "Run `npx scrumrun@latest init` in the repository root." },
+  "SR-E-500": { summary: "ScrumRun project not initialized.", remediation: "Run `scrumrun init` in the repository root." },
   "SR-E-501": { summary: "Unsupported Node.js runtime.", remediation: "ScrumRun requires Node.js >=22.13.0 for native SQLite. Upgrade Node and retry." }
 });
 

package/lib/runtime/briefing.js

@@ -97,8 +97,8 @@ ${backlogTasks.length ? backlogTasks.join("\n") : "- No backlog Tasks."}
 - Guardrails: .scrumrun/guardrails.md
 - Tasks: .scrumrun/tasks/ (${counts.task || 0} total)
 - Runs: .scrumrun/runs/ (${counts.run || 0} total)
-- Semantic: sc knowledge study "<topic>" for deep queries
-- Full state: rebuild with sc config doctor --recover
+- Semantic: scrumrun knowledge study "<topic>" for deep queries
+- Full state: rebuild with scrumrun config doctor --recover
 `;
 
   return { content, sourceFingerprint, watchFingerprint: watch.fingerprint, sourceFiles: watch.files };

package/lib/runtime/orchestrator.js

@@ -586,7 +586,7 @@ const ADD_PLAN_INITIAL_STATUS = Object.freeze({
 const TASK_TYPES = new Set(["task", "fix", "docs", "discovery"]);
 
 function planArtifactBody(kind, title, created) {
-  const source = `- ${created}: created via CLI (\`sc plan ${kind} --add\`).`;
+  const source = `- ${created}: created via CLI (\`scrumrun plan ${kind} --add\`).`;
   if (kind === "task") {
     return [
       `# ${title}`,

package/lib/v2/conformance.js

@@ -79,7 +79,7 @@ function auditProject(projectRoot) {
     if (methodMarker.method !== METHOD_VERSION) findings.push(finding("critical", "METHOD_VERSION", `method.json must declare ${METHOD_VERSION}.`, marker));
     const expectedPaths = canonicalPaths();
     if (!methodMarker.paths || typeof methodMarker.paths !== "object" || Array.isArray(methodMarker.paths)) {
-      findings.push(finding("high", "METHOD_PATHS_MISSING", `method.json must declare a canonical "paths" block so agents navigate by declaration, not by search. Run \`npx scrumrun@latest update --migrate\` to backfill.`, marker));
+      findings.push(finding("high", "METHOD_PATHS_MISSING", `method.json must declare a canonical "paths" block so agents navigate by declaration, not by search. Run \`scrumrun update --migrate\` to backfill.`, marker));
     } else {
       const drift = diffPathIndex(expectedPaths, methodMarker.paths);
       for (const entry of drift) findings.push(finding("high", "METHOD_PATHS_DRIFT", `method.json paths[${entry.label}] is ${entry.actual === undefined ? "missing" : `"${entry.actual}"`}; expected "${entry.expected}". Regenerate via \`update --migrate\`.`, marker));
@@ -152,7 +152,7 @@ function auditProject(projectRoot) {
     if (run.record && run.record.ledger === RUN_LEDGER_VERSION) {
       const ledger = validateRunLedger(run.record, run.body);
       if (ledger.errors.length) {
-        findings.push(finding("high", "RUN_WRITE_BYPASS", `${run.record.id}: ledger has ${ledger.errors.length} validation error(s); this Run was likely written without going through the CLI. Recover with \`sc plan run --normalize-legacy --dry-run\` then re-run without --dry-run.`, run.file));
+        findings.push(finding("high", "RUN_WRITE_BYPASS", `${run.record.id}: ledger has ${ledger.errors.length} validation error(s); this Run was likely written without going through the CLI. Recover with \`scrumrun plan run --normalize-legacy --dry-run\` then re-run without --dry-run.`, run.file));
         for (const error of ledger.errors) findings.push(finding("high", "RUN_LEDGER_INVALID", `${run.record.id}: ${error}`, run.file));
       }
     } else if (run.record) {
@@ -198,7 +198,17 @@ function auditProject(projectRoot) {
     const attempts = (records.run || [])
       .filter((run) => run.record && !run.errors.length && run.record.task === task.record.id)
       .sort((left, right) => right.record.attempt - left.record.attempt);
-    if (!attempts.length) continue;
+    if (!attempts.length) {
+      if (["running", "validating", "learning", "partial"].includes(task.record.status)) {
+        findings.push(finding(
+          "high",
+          "TASK_ORPHANED",
+          `${task.record.id}.status is ${task.record.status}, but no canonical Run references it. Review with \`scrumrun repair --recover-orphan-tasks\`, then apply the explicit recovery and start the Task to create its first Run.`,
+          task.file
+        ));
+      }
+      continue;
+    }
     const latest = attempts[0].record;
     const taskStatuses = {
       executing: "running",

package/package.json

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

package/templates/project/AGENTS.md

@@ -2,7 +2,7 @@
 
 ## ScrumRun 3.0
 
-This project uses ScrumRun. The method is mandatory; `/sc` is its single optional shortcut.
+This project uses ScrumRun. The method is mandatory; the direct CLI is `scrumrun <noun> <subject> <action>`. `/sc` is only an optional client shortcut.
 
 For normal work, read:
 
@@ -21,11 +21,11 @@ After approval:
 - 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 sc plan run --finalize RUN-NNN` once to validate and close the Run;
-- when a Run completes and work remains queued, surface it with `sc plan task --next` and start it with `sc plan task --start` — starting is explicit approval;
+- 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.
 
-If `/sc` is unavailable, follow the equivalent workflow in `.scrumrun/core.md` manually.
+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.