scrumrun 3.0.0 → 3.0.2

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

@@ -583,10 +583,10 @@ const ADD_PLAN_INITIAL_STATUS = Object.freeze({
   feature: ["backlog", "proposed"],
   sprint: ["proposed"]
 });
-const TASK_TYPES = new Set(["task", "fix", "docs", "discovery"]);
+const TASK_TYPES = new Set(["task", "fix", "feature", "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}`,
@@ -689,4 +689,159 @@ function addPlanArtifact(projectRoot, kind, label, options = {}) {
   return withArtifactLock(scrumDir, "create", () => addPlanArtifactUnlocked(projectRoot, kind, label, options));
 }
 
-module.exports = { addPlanArtifact, approveRequest, finalizeRun, nextBacklogTask, nextId, refreshErrors, refreshState, renderState, retryTask, startBacklogTask, stateFingerprint, stateIsStale, transitionRun };
+const AMENDABLE_STATUSES = Object.freeze({
+  task: new Set(["backlog", "proposed"]),
+  feature: new Set(["backlog", "proposed", "active", "paused"]),
+  sprint: new Set(["proposed"])
+});
+
+function normalizeAmendText(value, label) {
+  const text = String(value || "").trim();
+  if (!text) throw new Error(`${label} cannot be empty.`);
+  if (containsSecret(text)) throw new Error("Secret-like content is forbidden outside the local vault.");
+  return text;
+}
+
+function replaceTitle(body, title) {
+  const clean = normalizeAmendText(title, "Title");
+  if (/^# [^\r\n]+/m.test(body)) return body.replace(/^# [^\r\n]+/m, `# ${clean}`);
+  return `# ${clean}\n\n${body.trimStart()}`;
+}
+
+function sectionExpression(value) {
+  const match = String(value || "").match(/^([^=\r\n]{1,120})=([\s\S]*)$/);
+  if (!match) throw new Error('--section must use "Heading=content".');
+  const heading = match[1].trim();
+  const content = normalizeAmendText(match[2], `Section ${heading}`);
+  if (!heading || /[#\r\n]/.test(heading)) throw new Error("Section heading must be plain text without # or line breaks.");
+  return { heading, content };
+}
+
+function replaceSection(body, heading, content) {
+  const cleanHeading = String(heading).trim();
+  const cleanContent = normalizeAmendText(content, `Section ${cleanHeading}`);
+  const escaped = cleanHeading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const expression = new RegExp(`^## ${escaped}[ \\t]*\\r?\\n([\\s\\S]*?)(?=^## [^\\r\\n]+[ \\t]*$|\\s*$)`, "m");
+  const replacement = `## ${cleanHeading}\n\n${cleanContent}\n`;
+  if (expression.test(body)) return body.replace(expression, replacement);
+  return `${body.trimEnd()}\n\n${replacement}`;
+}
+
+function replaceFirstKnownSection(body, headings, content) {
+  for (const heading of headings) {
+    const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (new RegExp(`^## ${escaped}[ \\t]*$`, "m").test(body)) return replaceSection(body, heading, content);
+  }
+  return replaceSection(body, headings[0], content);
+}
+
+function relationValue(repository, kind, value) {
+  if (value === undefined) return undefined;
+  if (value === null || value === "null" || value === "none") return null;
+  const id = String(value).trim();
+  const artifact = repository.read(kind, id);
+  if (!artifact || artifact.errors.length) throw new Error(`${kind} relation must reference an existing valid ${ARTIFACT_TYPES[kind].prefix}-NNN or null.`);
+  return id;
+}
+
+function setReferenceSection(body, heading, id) {
+  const exists = new RegExp(`^## ${heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[ \\t]*$`, "m").test(body);
+  if (id) return replaceSection(body, heading, `- ${id}`);
+  if (!exists) return body;
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return body.replace(new RegExp(`^## ${escaped}[ \\t]*\\r?\\n[\\s\\S]*?(?=^## [^\\r\\n]+[ \\t]*$|\\s*$)`, "m"), "").replace(/\n{3,}/g, "\n\n").trimEnd();
+}
+
+function taskListBody(body, taskId, include) {
+  const heading = "Tasks";
+  const expression = /^## Tasks[ \t]*\r?\n([\s\S]*?)(?=^## [^\r\n]+[ \t]*$|\s*$)/m;
+  const current = expression.exec(body);
+  const listed = current ? [...current[1].matchAll(/^-\s+(TASK-\d{3,})\b.*$/gm)].map((match) => match[1]) : [];
+  const next = include ? [...new Set([...listed, taskId])] : listed.filter((id) => id !== taskId);
+  const content = next.length ? next.map((id) => `- ${id}`).join("\n") : "_Pending: add Task ids here._";
+  return replaceSection(body, heading, content);
+}
+
+function linkedTaskBody(body, taskId, include) {
+  const heading = "Linked Tasks";
+  const expression = /^## Linked Tasks[ \t]*\r?\n([\s\S]*?)(?=^## [^\r\n]+[ \t]*$|\s*$)/m;
+  const current = expression.exec(body);
+  const listed = current ? [...current[1].matchAll(/^-\s+(TASK-\d{3,})\b.*$/gm)].map((match) => match[1]) : [];
+  const next = include ? [...new Set([...listed, taskId])] : listed.filter((id) => id !== taskId);
+  const content = next.length ? next.map((id) => `- ${id}`).join("\n") : "_Pending: link Task ids here._";
+  return replaceSection(body, heading, content);
+}
+
+function amendPlanArtifact(projectRoot, kind, id, options = {}) {
+  if (!ADDABLE_PLAN_KINDS.has(kind)) throw new Error(`Only Task, Feature, and Sprint artifacts can be amended; ${kind} is not planning truth.`);
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  const methodFile = path.join(scrumDir, "method.json");
+  if (!fs.existsSync(methodFile) || !fs.lstatSync(methodFile).isFile()) throw new Error(`ScrumRun project not found in ${projectRoot}.`);
+  return withArtifactLock(scrumDir, `amend-${id}`, () => {
+    recoverPendingTransactions(scrumDir);
+    const repository = new ArtifactRepository(scrumDir);
+    const artifact = repository.read(kind, id);
+    if (!artifact) throw new Error(`${kind} not found: ${id}`);
+    if (artifact.errors.length) throw new Error(`Invalid ${id}: ${artifact.errors.join("; ")}`);
+    if (!AMENDABLE_STATUSES[kind].has(artifact.record.status)) {
+      throw new Error(`${id} is ${artifact.record.status}; its approved/executed scope is no longer amendable. Create a follow-up Task instead.`);
+    }
+    const hasChange = ["title", "request", "acceptance", "purpose", "exitCriteria", "timebox", "exitGate", "type", "feature", "sprint"].some((key) => options[key] !== undefined) || (options.sections && options.sections.length);
+    if (!hasChange) throw new Error("--amend requires at least one change.");
+    let record = { ...artifact.record, updated: date() };
+    let body = artifact.body;
+    if (options.title !== undefined) body = replaceTitle(body, options.title);
+    if (options.request !== undefined) body = replaceSection(body, "Request", options.request);
+    if (options.acceptance !== undefined) body = replaceSection(body, "Acceptance Criteria", options.acceptance.map((item) => `- [ ] ${normalizeAmendText(item, "Acceptance criterion")}`).join("\n"));
+    if (options.purpose !== undefined) body = replaceFirstKnownSection(body, ["Purpose", "Motivation"], options.purpose);
+    if (options.exitCriteria !== undefined) body = replaceFirstKnownSection(body, ["Exit Criteria", "Exit criteria"], options.exitCriteria.map((item) => `- [ ] ${normalizeAmendText(item, "Exit criterion")}`).join("\n"));
+    if (options.timebox !== undefined) body = replaceSection(body, "Timebox", options.timebox);
+    if (options.exitGate !== undefined) body = replaceSection(body, "Exit Gate", options.exitGate.map((item) => `- [ ] ${normalizeAmendText(item, "Exit gate")}`).join("\n"));
+    for (const rawSection of options.sections || []) {
+      const section = sectionExpression(rawSection);
+      body = replaceSection(body, section.heading, section.content);
+    }
+
+    const sideEffects = [];
+    if (kind === "task") {
+      if (options.type !== undefined) {
+        if (!TASK_TYPES.has(options.type)) throw new Error(`Invalid task --type: ${options.type}. Valid: ${[...TASK_TYPES].join(", ")}.`);
+        record.type = options.type;
+      }
+      const previousFeature = record.feature || null;
+      const previousSprint = record.sprint || null;
+      const nextFeature = relationValue(repository, "feature", options.feature);
+      const nextSprint = relationValue(repository, "sprint", options.sprint);
+      if (nextFeature !== undefined) {
+        record.feature = nextFeature;
+        body = setReferenceSection(body, "Feature", nextFeature);
+        for (const featureId of new Set([previousFeature, nextFeature].filter(Boolean))) {
+          const feature = repository.read("feature", featureId);
+          if (!feature || feature.errors.length) throw new Error(`Cannot synchronize invalid Feature relation ${featureId}; repair it before amending ${id}.`);
+          const include = featureId === nextFeature;
+          sideEffects.push({ file: feature.file, previous: fs.readFileSync(feature.file, "utf8"), next: serializeArtifact(feature.record, linkedTaskBody(feature.body, id, include)) });
+        }
+      }
+      if (nextSprint !== undefined) {
+        record.sprint = nextSprint;
+        body = setReferenceSection(body, "Sprint", nextSprint);
+        for (const sprintId of new Set([previousSprint, nextSprint].filter(Boolean))) {
+          const sprint = repository.read("sprint", sprintId);
+          if (!sprint || sprint.errors.length) throw new Error(`Cannot synchronize invalid Sprint relation ${sprintId}; repair it before amending ${id}.`);
+          const include = sprintId === nextSprint;
+          sideEffects.push({ file: sprint.file, previous: fs.readFileSync(sprint.file, "utf8"), next: serializeArtifact(sprint.record, taskListBody(sprint.body, id, include)) });
+        }
+      }
+    }
+    const next = serializeArtifact(record, body);
+    assertCanonicalWrite(projectRoot, `amend-${kind}`, [next, ...sideEffects.map((entry) => entry.next)]);
+    runKernelTransaction(scrumDir, `amend-${kind}`, [
+      { file: artifact.file, previous: fs.readFileSync(artifact.file, "utf8"), next },
+      ...sideEffects
+    ]);
+    refreshState(scrumDir);
+    return repository.read(kind, id);
+  });
+}
+
+module.exports = { addPlanArtifact, amendPlanArtifact, approveRequest, finalizeRun, nextBacklogTask, nextId, refreshErrors, refreshState, renderState, retryTask, startBacklogTask, stateFingerprint, stateIsStale, transitionRun };

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.2",
   "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:
 
@@ -16,16 +16,17 @@ Natural-language product requests automatically enter the read-only ScrumRun int
 After approval:
 
 - Task is the atomic work item; define its `## Acceptance Criteria` before execution;
+- before a Task starts, amend its intended scope through `scrumrun plan task --amend TASK-NNN` (including `--section "Heading=content"`); never hand-edit canonical planning Markdown;
 - Sprint is only a real timebox/batch of Tasks;
 - Run is one execution attempt and follows `executing → validating → learning → completed|failed|blocked`;
 - a retry creates a new Run and preserves the old one;
 - record a `## Technical Summary` at completion so the next agent inherits what was done;
 - work directly in code and the linked Task Markdown after approval; do not call `npx scrumrun@latest` during execution;
-- record one `## Guardrail Evidence` line per non-automatic guardrail in the Task, then run `scrumrun 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.

package/templates/shared/skills/scrumrun/SKILL.md

@@ -5,13 +5,13 @@ description: Use when initializing or migrating ScrumRun, handling product reque
 
 # ScrumRun 2.0
 
-ScrumRun is an evidence-driven Agile runtime for AI agents. Its canonical command is:
+ScrumRun is an evidence-driven Agile runtime for AI agents. Its canonical shell command is:
 
 ```text
-/sc <noun> <subject> <action> [args]
+scrumrun <noun> <subject> <action> [args]
 ```
 
-The five nouns are `plan`, `knowledge`, `rules`, `review`, and `config`. If the command is incomplete, show only the valid next tokens and do not guess.
+The five nouns are `plan`, `knowledge`, `rules`, `review`, and `config`. `/sc` is an optional AI-client shortcut; `scrumrun sc ...` is a compatibility alias. If the command is incomplete, show only the valid next tokens and do not guess.
 
 When a project contains `.scrumrun/`, use ScrumRun for product work even if the user did not type `/sc`. Natural-language work begins as `plan intake`.
 
@@ -33,10 +33,12 @@ Normal hot path:
 2. read `AGENTS.md`;
 3. read `.scrumrun/guardrails.md`;
 4. read `.scrumrun/state.md` — the **briefing**: active work, recent completions with their technical summaries, open decisions, active memory, backlog queue, and pointers;
-5. follow the briefing's pointers to only the relevant canonical artifacts; go deeper only when the briefing lacks what you need (`## Where to look`, `sc knowledge study "<topic>"`);
+5. follow the briefing's pointers to only the relevant canonical artifacts; go deeper only when the briefing lacks what you need (`## Where to look`, `scrumrun knowledge study "<topic>"`);
 6. load `.scrumrun/core.md` when the method contract or an exceptional transition is needed.
 
-**Never write Run events by hand.** Work directly in code and the linked Task Markdown after approval, then let the one final CLI checkpoint mutate `runs/RUN-NNN.md`: `scrumrun sc plan run --finalize RUN-NNN`. It creates the validated transition ledger, audits the full workspace delta, and records the Guardrail results together. Do not invoke `npx scrumrun@latest` during normal execution. The older `--validate | --learn | --complete | --satisfy-guardrail | --authorize-mutation | --record-mutation` commands remain only for owner-requested strict mode. Recover hand-written Runs via `sc plan run --normalize-legacy` — originals are preserved byte-exact under `.scrumrun/.migration-backup/runs/`.
+**Never write Run events by hand.** Work directly in code and the linked Task Markdown after approval, then let the one final CLI checkpoint mutate `runs/RUN-NNN.md`: `scrumrun plan run --finalize RUN-NNN`. It creates the validated transition ledger, audits the full workspace delta, and records the Guardrail results together. Do not invoke `npx scrumrun@latest` during normal execution. The older `--validate | --learn | --complete | --satisfy-guardrail | --authorize-mutation | --record-mutation` commands remain only for owner-requested strict mode. Recover hand-written Runs via `scrumrun plan run --normalize-legacy` — originals are preserved byte-exact under `.scrumrun/.migration-backup/runs/`.
+
+**Never hand-edit canonical planning Markdown.** Before a Task starts, refine it with `scrumrun plan task --amend TASK-NNN`; use title/request/acceptance/relation options or generic repeated `--section "Heading=content"`. Feature and Sprint support the same `--amend` pattern. Runs, Reviews, confirmed memory, and Guardrails are append-only evidence/policy, so record a new event or supersede them instead of rewriting them.
 
 Lean mode is a read policy, not an incomplete store. Generated files and `.scrumrun/.cache/` are never authoritative.
 
@@ -81,7 +83,7 @@ At intake:
 
 Evaluate every active Guardrail into a structured `passed`, `blocked`, or `deferred` result. Report blocked results with the exact `GR-NNN` id and reason code. Keep deferred results visible and enforce them at the mutation, migration, review, or owner gate they identify; never describe a deferred check as passed.
 
-Assert the classification explicitly when the keyword inference is wrong: `sc plan intake "…" --type fix|task|feature|docs|discovery`. Attach a short technical explanation before approval with `--preview "…"` (rendered in the terminal, bound into the token, stored as `## Preview` on the Task).
+Assert the classification explicitly when the keyword inference is wrong: `scrumrun plan intake "…" --type fix|task|feature|docs|discovery`. Attach a short technical explanation before approval with `--preview "…"` (rendered in the terminal, bound into the token, stored as `## Preview` on the Task).
 
 Do not create canonical artifacts, change status, edit application code, or treat ambiguous acknowledgement as approval. Temporary context may exist only in ignored disposable cache.
 
@@ -104,12 +106,12 @@ During execution:
 4. work normally: edit code and update the Task's `## Technical Summary` and, for non-automatic rules, `## Guardrail Evidence` as evidence becomes available;
 5. validate in proportion to risk and against the acceptance criteria;
 6. run configured reviewers when a Guardrail requires one;
-7. finish once with `scrumrun sc plan run --finalize RUN-NNN`; it verifies every changed path, policy, secret boundary, and guardrail evidence before creating the structured Run events and completing the Task;
+7. finish once with `scrumrun plan run --finalize RUN-NNN`; it verifies every changed path, policy, secret boundary, and guardrail evidence before creating the structured Run events and completing the Task;
 8. use path-scoped Mutation Gateway commands only when the owner explicitly requests strict execution.
 
 Never overwrite a prior attempt. Never mark work complete because time/token budget ended.
 
-When a Run completes and work remains queued, the briefing's `## Next Up` names the next backlog Task. Surface it with `sc plan task --next` and start it with `sc plan task --start [TASK-NNN]` — starting is the explicit approval; the owner can always decline. Each agent declares its identity via `SCRUMRUN_AGENT` (or `Agent Identity` in `config.md`); it is recorded as the Task `assignee` and the Run event `actor`.
+When a Run completes and work remains queued, the briefing's `## Next Up` names the next backlog Task. Surface it with `scrumrun plan task --next` and start it with `scrumrun plan task --start [TASK-NNN]` — starting is the explicit approval; the owner can always decline. Each agent declares its identity via `SCRUMRUN_AGENT` (or `Agent Identity` in `config.md`); it is recorded as the Task `assignee` and the Run event `actor`.
 
 Every deferred policy result is an append-only Run obligation. The final checkpoint fails closed on policy drift, protected-path changes, unsafe symlinks, unscannable content, newly introduced secret-like content, or missing Guardrail Evidence. In strict mode it additionally requires the permit chain. The ignored permit cache is disposable; deleting it invalidates outstanding strict-mode permits and never creates authority.
 
@@ -155,22 +157,22 @@ scrumrun migrate --to 2 --apply
 scrumrun migrate --to 2 --rollback
 ```
 
-Inside a v1 project, `npx scrumrun@latest update` runs a read-only preflight. `update --migrate` explicitly approves application of that verified plan and keeps rollback available.
+Inside a v1 project, `scrumrun update` runs a read-only preflight. `update --migrate` explicitly approves application of that verified plan and keeps rollback available.
 
 Dry-run must not write project data. Apply requires a hashed inventory, byte-exact local backup, staged validation, atomic switch, mapping report, and idempotent replay. Incomplete hybrid trees reuse existing evidenced v2 relations rather than duplicating them; early v2 prose Runs upgrade to ledger schema 1 only through the same explicit apply gate. Legacy-only aggregates leave the active tree but remain byte-exact in the ignored backup. Ambiguous records are preserved as warnings or evidenced snapshots, never guessed. Vault content remains local and is never rendered. Rollback must refuse if it would erase post-migration changes.
 
 ## Command grammar
 
-### `/sc plan`
+### `scrumrun plan`
 
-- `task`: add/list/show/run/audit/cancel/retry atomic work; use `type: fix` for fixes and `status: backlog` for parked work. `--next` surfaces the oldest backlog Task; `--start [TASK-NNN]` promotes it and creates its first Run.
-- `sprint`: add/list/show/start/complete/block a real Task batch/timebox.
-- `feature`: add/list/show/activate/complete long-lived initiatives.
+- `task`: add/amend/list/show/run/audit/cancel/retry atomic work; use `--amend TASK-NNN` before it starts to refine planning truth without hand-editing Markdown. Use `type: fix` for fixes and `status: backlog` for parked work. `--next` surfaces the oldest backlog Task; `--start [TASK-NNN]` promotes it and creates its first Run.
+- `sprint`: add/amend/list/show/start/complete/block a real Task batch/timebox.
+- `feature`: add/amend/list/show/activate/complete long-lived initiatives.
 - `run`: list/show/render/stats/normalize-legacy/authorize-mutation/record-mutation/satisfy-guardrail/validate/learn/complete/resume/fail/block concrete Task attempts. `--complete` accepts `--summary "…"` to store a technical summary.
 - `intake <request>`: execute the read-only request pipeline; accepts `--type fix|task|feature|docs|discovery` and `--preview "…"`.
 - `challenge <question>`: deep read-only analysis with evidence, risks, options, and recommendation.
 
-### `/sc knowledge`
+### `scrumrun knowledge`
 
 - `fact`: add/list/show/approve/reject/deprecate/invalidate `K-NNN` records.
 - `decision`: add/list/show/resolve/deprecate/invalidate `DEC-NNN` records.
@@ -181,12 +183,12 @@ Dry-run must not write project data. Apply requires a hashed inventory, byte-exa
 - `study <focus>`: deep read-only discovery with precise evidence.
 - `vault`: add/list/show/remove/path for explicitly requested local development values; list redacts values.
 
-### `/sc rules`
+### `scrumrun rules`
 
 - `guardrail`: add/list/show/retire project rules. Adding/retiring requires explicit approval.
 - `reviewer`: add/list/show/run configured review roles.
 
-### `/sc review`
+### `scrumrun review`
 
 - `code --run`: review code changes by severity with file/line evidence.
 - `artifact --run`: validate method artifacts and relations.
@@ -195,7 +197,7 @@ Dry-run must not write project data. Apply requires a hashed inventory, byte-exa
 
 Review is read-only unless the user separately authorizes fixes.
 
-### `/sc config`
+### `scrumrun config`
 
 - `project`: show/set language, interaction, approval, and quick-task preferences.
 - `init`: initialize ScrumRun without overwriting existing state silently.
@@ -207,16 +209,16 @@ Review is read-only unless the user separately authorizes fixes.
 
 ## Compatibility
 
-Upgrade installs may provide thin v1 adapters for one release cycle. An adapter must execute the mapped `/sc` route in the same turn and emit one concise deprecation note; it must not merely ask the user to invoke another command.
+Upgrade installs may provide thin v1 adapters for one release cycle. An adapter must execute the mapped direct route in the same turn and emit one concise deprecation note; it must not merely ask the user to invoke another command.
 
 Important mappings:
 
-- `/sc-sprint` → `/sc plan sprint`
-- `/sc-fix` → `/sc plan task` with `type: fix`
-- `/sc-backlog` → `/sc plan task` with `status: backlog`
-- `/sc-decisions` → `/sc knowledge decision`
-- `/sc-know` → `/sc knowledge fact`
-- `/sc-golden` → `/sc rules guardrail`
-- `/sc-agent` → `/sc rules reviewer`
+- `/sc-sprint` → `scrumrun plan sprint`
+- `/sc-fix` → `scrumrun plan task` with `type: fix`
+- `/sc-backlog` → `scrumrun plan task` with `status: backlog`
+- `/sc-decisions` → `scrumrun knowledge decision`
+- `/sc-know` → `scrumrun knowledge fact`
+- `/sc-golden` → `scrumrun rules guardrail`
+- `/sc-agent` → `scrumrun rules reviewer`
 
-Always generate and recommend the canonical `/sc` grammar.
+Always generate and recommend the canonical direct CLI grammar.