scrumrun 3.0.1 → 3.0.2

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+## 3.0.2 - 2026-08-31
+
+### Added
+
+- **Planning artifact amendments.** `scrumrun plan task|feature|sprint --amend <ID>` updates planning truth through the CLI rather than hand-editing Markdown. It supports title and structured fields plus generic repeated `--section "Heading=content"`, so new scope context does not require another command. Task Feature/Sprint relations update their projections atomically.
+
+### Safety
+
+- A Task can be amended only while `backlog` or `proposed`; once started, its approved scope is preserved and new work belongs in a follow-up Task. Runs, Reviews, confirmed memory, and Guardrails remain append-only/evidence-led by design.
+
 ## 3.0.1 - 2026-08-31
 
 ### Fixed

package/CORE.md

@@ -86,6 +86,8 @@ AGENTS.md
 
 **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/`).
 
+**Amend planning truth through the CLI, never by hand.** Before execution, use `scrumrun plan task|feature|sprint --amend <ID>` to adjust the title, structured fields, or any named body section (`--section "Heading=content"`). A Task may be amended only in `backlog` or `proposed`; changing its `--feature` or `--sprint` also synchronizes the related projections atomically. Runs, Reviews, confirmed memory, and Guardrails are evidence/history and are not amendable: append a transition, record a new Review, or supersede/deprecate the old fact instead.
+
 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.
 
 `state.md` and the semantic index use two-tier freshness checks. Matching path/stat watch fingerprints avoid rereading unchanged sources; any metadata drift falls back to complete content hashing. A cache schema mismatch rebuilds the disposable index once. Watch metadata is only an optimization and never authority.

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.1` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+**Package:** `3.0.2` · **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).
 
@@ -93,6 +93,18 @@ 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.
 
+Before a Task starts, refine it through the CLI rather than hand-editing Markdown. `--amend` updates title, request, acceptance criteria, Feature/Sprint links, task type, or any named section while preserving its ID and status. It synchronizes related Feature/Sprint projections atomically.
+
+```bash
+scrumrun plan task --amend TASK-153 \
+  --title "Organization Aside and context selector" \
+  --request "Add shared organization navigation, context selection, routes, and authorization boundaries." \
+  --acceptance "Organization context is available before protected routes render." \
+  --section "Architecture Notes=Navigation stays in the Aside; authorization stays server-side."
+```
+
+Tasks become immutable in scope once started; create a follow-up Task for a new request. Runs, Reviews, confirmed memory, and Guardrails are deliberately append-only/evidence-led rather than editable. See [the command reference](docs/COMMANDS.md#what-can-be-changed) for the complete artifact matrix.
+
 Each Run contains a machine-validated event ledger. Events have stable ids such as `RUN-044-EVT-003`, RFC3339 timestamps, actors, reasons, and typed evidence for commands, tests, files, reviews, decisions, insights, and risks. Run is the only operational history; Task keeps its approved scope and synchronized current status without duplicating those events. Completion is rejected when validation or learning evidence is missing.
 
 Linked Task/Run writes use a durable ignored transaction journal. Captured failures roll back immediately; interrupted operations are recovered byte-exactly on retry or through explicit `doctor --recover`. Read-only audit reports pending recovery and never repairs state silently.

package/bin/scrumrun.js

@@ -31,7 +31,7 @@ const { ARTIFACT_TYPES, ArtifactRepository } = require(path.join(root, "lib", "v
 const { aliases: COMMAND_ALIASES, resolveAlias, resolveRoute } = require(path.join(root, "lib", "commands", "manifest"));
 const { renderCommandHelp, renderCompatibilityPrompt, renderRootPrompt } = require(path.join(root, "lib", "commands", "render"));
 const { planRequest } = require(path.join(root, "lib", "runtime", "request-engine"));
-const { addPlanArtifact, approveRequest, finalizeRun, nextBacklogTask, refreshErrors, refreshState, retryTask, startBacklogTask, transitionRun } = require(path.join(root, "lib", "runtime", "orchestrator"));
+const { addPlanArtifact, amendPlanArtifact, approveRequest, finalizeRun, nextBacklogTask, refreshErrors, refreshState, retryTask, startBacklogTask, transitionRun } = require(path.join(root, "lib", "runtime", "orchestrator"));
 const { authorizeMutation, recordMutation, satisfyGuardrail } = require(path.join(root, "lib", "runtime", "mutation-gateway"));
 const { recordArtifactReview } = require(path.join(root, "lib", "runtime", "review-service"));
 const { createMemory, listMemory, showMemory, transitionMemory } = require(path.join(root, "lib", "memory", "service"));
@@ -1475,6 +1475,27 @@ function executeRootRoute(route) {
     console.log(`Started ${result.task.id} (${result.run.id}) assigned to ${result.task.assignee || "agent"}.`);
     return;
   }
+  if (noun === "plan" && ["task", "feature", "sprint"].includes(subject) && routeArgs[0] === "--amend") {
+    const id = routeArgs[1];
+    if (!id) throw new Error(`--amend requires a ${subject.toUpperCase()}-NNN id.`);
+    const amendArgs = routeArgs.slice(2);
+    const amendValue = (flag) => amendArgs.includes(flag) ? optionValue(amendArgs, flag) : undefined;
+    const result = amendPlanArtifact(process.cwd(), subject, id, {
+      title: amendValue("--title"),
+      request: amendValue("--request"),
+      acceptance: amendArgs.includes("--acceptance") ? optionValues(amendArgs, "--acceptance") : undefined,
+      purpose: amendValue("--purpose"),
+      exitCriteria: amendArgs.includes("--exit-criteria") ? optionValues(amendArgs, "--exit-criteria") : undefined,
+      timebox: amendValue("--timebox"),
+      exitGate: amendArgs.includes("--exit-gate") ? optionValues(amendArgs, "--exit-gate") : undefined,
+      sections: optionValues(amendArgs, "--section"),
+      type: amendValue("--type"),
+      feature: amendValue("--feature"),
+      sprint: amendValue("--sprint")
+    });
+    console.log(`Amended ${result.record.id}: ${path.relative(process.cwd(), result.file)} (status remains ${result.record.status}).`);
+    return;
+  }
   if (noun === "plan" && ["task", "feature", "sprint"].includes(subject) && routeArgs[0] === "--add") {
     const label = removeOptionPairs(routeArgs.slice(1), ["--type", "--status"])
       .filter((arg) => !arg.startsWith("--"))

package/docs/COMMANDS.md

@@ -14,8 +14,11 @@ Use the installed `scrumrun` command for all normal project work. `/sc` is an op
 scrumrun plan intake <request>
 scrumrun plan intake --approve <token>
 scrumrun plan task --add|--list|--show|--run|--audit|--cancel|--retry
+scrumrun plan task --amend TASK-NNN [--title "..."] [--request "..."] [--acceptance "..."] [--section "Heading=content"] [--type fix|task|feature|docs|discovery] [--feature FEAT-NNN|null] [--sprint SPRINT-NNN|null]
 scrumrun plan sprint --add|--list|--show|--start|--complete|--block
+scrumrun plan sprint --amend SPRINT-NNN [--title "..."] [--timebox "..."] [--exit-gate "..."] [--section "Heading=content"]
 scrumrun plan feature --add|--list|--show|--activate|--complete
+scrumrun plan feature --amend FEAT-NNN [--title "..."] [--purpose "..."] [--exit-criteria "..."] [--section "Heading=content"]
 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 ...]
@@ -26,6 +29,19 @@ 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.
 
+`--amend` is the canonical way to adjust planning truth before execution — never edit an artifact Markdown file directly. Every named `--section "Heading=content"` replaces or adds one `## Heading` section, so new planning context does not need a new CLI release. Repeated `--acceptance`, `--exit-criteria`, and `--exit-gate` values become checklist items. Updating a Task's `--feature` or `--sprint` synchronizes the linked Feature/Sprint projection atomically. A Task is amendable only while `backlog` or `proposed`; after it starts, scope is historical/approved truth and follow-up work needs a new Task.
+
+## What can be changed
+
+| Artifact | Canonical operation | Why |
+| --- | --- | --- |
+| Task, Feature, Sprint | `--add`, `--amend`, lifecycle commands | Planning truth can be refined before execution. |
+| Run | transitions, `--finalize`, `--retry` | Execution history is append-only; it is never amended. |
+| Review | `--run` / `--record` | A verdict is evidence, not editable prose. Record another review if it changes. |
+| Knowledge, Decision, Insight, Dossier | create + lifecycle commands | Preserve evidence lineage; supersede/deprecate rather than rewrite confirmed truth. |
+| Guardrail | `--add` / `--retire` | Policy history must remain auditable. |
+| `state.md`, `map.md`, cache | rebuild commands | Derived projections, never manually edited. |
+
 ## Knowledge
 
 ```text

package/lib/commands/manifest.js

@@ -6,9 +6,9 @@ const nouns = Object.freeze({
   plan: {
     description: "turn intent into Features, Tasks, Sprints, and Runs",
     subjects: {
-      task: ["--add [--type fix] [--status backlog]", "--list", "--show", "--run", "--audit", "--cancel", "--retry [--reassign]", "--next", "--start [TASK-NNN]"],
-      sprint: ["--add", "--list", "--show", "--start", "--complete", "--block"],
-      feature: ["--add", "--list", "--show", "--activate", "--complete"],
+      task: ["--add [--type fix] [--status backlog]", "--amend <TASK-NNN> [--title] [--request] [--acceptance] [--section \"Heading=content\"] [--type task|fix|feature|docs|discovery] [--feature] [--sprint]", "--list", "--show", "--run", "--audit", "--cancel", "--retry [--reassign]", "--next", "--start [TASK-NNN]"],
+      sprint: ["--add", "--amend <SPRINT-NNN> [--title] [--timebox] [--exit-gate] [--section \"Heading=content\"]", "--list", "--show", "--start", "--complete", "--block"],
+      feature: ["--add", "--amend <FEAT-NNN> [--title] [--purpose] [--exit-criteria] [--section \"Heading=content\"]", "--list", "--show", "--activate", "--complete"],
       run: [
         "--list",
         "--show",

package/lib/runtime/orchestrator.js

@@ -583,7 +583,7 @@ 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 (\`scrumrun plan ${kind} --add\`).`;
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scrumrun",
-  "version": "3.0.1",
+  "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

@@ -16,6 +16,7 @@ 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;

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

@@ -36,7 +36,9 @@ Normal hot path:
 5. follow the briefing's pointers to only the relevant canonical artifacts; go deeper only when the briefing lacks what you need (`## Where to look`, `scrumrun knowledge study "<topic>"`);
 6. load `.scrumrun/core.md` when the method contract or an exceptional transition is needed.
 
-**Never write Run events by hand.** Work directly in code and the linked Task Markdown after approval, then let the one final CLI checkpoint mutate `runs/RUN-NNN.md`: `scrumrun plan run --finalize RUN-NNN`. It creates the validated transition ledger, audits the full workspace delta, and records the Guardrail results together. Do not invoke `scrumrun` 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 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.
 
@@ -163,9 +165,9 @@ Dry-run must not write project data. Apply requires a hashed inventory, byte-exa
 
 ### `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.