scrumrun 3.0.1 → 3.0.3

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+## 3.0.3 - 2026-08-31
+
+### Fixed
+
+- **Scoped validation, not test bureaucracy.** New Tasks now state that only checks explicitly required by the owner, Acceptance Criteria, or an active Guardrail can block completion. Missing optional E2E/integration/review coverage is recorded as a follow-up or risk rather than turning a validated delivery into a failed Run. Generated agent instructions and the method contract enforce the same rule.
+
+## 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.
@@ -181,6 +183,7 @@ Rules:
 - the Run ledger is operational history; Task synchronizes current status without copying the Run event;
 - validation, learning, completion, failure, block, and resume require a reason or evidence;
 - validation must match the risk and acceptance criteria;
+- tests, reviews, and environments are completion gates only when explicitly required by the owner, the Task's Acceptance Criteria, or an active Guardrail; missing optional coverage is a follow-up/risk, never a reason by itself to fail or block an otherwise accepted Task;
 - each Task declares its `## Acceptance Criteria` before execution; check them off as evidence, never mark done on vibes;
 - configured reviews run before completion;
 - every deferred policy result is persisted as a Run Guardrail obligation;

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.3` · **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).
 
@@ -91,7 +91,19 @@ Every approved Task carries an `## Acceptance Criteria` section so "done" is def
 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.
+The checkpoint validates the complete delta, policy, protected paths, secret boundary, Task summary, and every applicable Guardrail before writing the Run ledger and synchronizing the Task. Failed retries remain available as separate Runs. Tests, reviews, and environments are a completion gate only when the owner, Acceptance Criteria, or an active Guardrail explicitly requires them; an optional missing E2E suite is a follow-up/risk, not a failed Task.
+
+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.
 

package/SPEC.md

@@ -200,7 +200,7 @@ RECEIVED
 
 Everything through `AWAITING_APPROVAL` is read-only. It may exist in process memory or ignored cache only. A valid approval token binds the normalized request, policy result, classification, risk, issuance time, canonical context fingerprint, and complete workspace fingerprint. Canonical or source drift after planning invalidates approval.
 
-Approval atomically creates one Task and its first Run. If either write fails, neither may remain. Project changes after planning invalidate the token. Reusing a successfully consumed token is idempotent.
+Approval atomically creates one Task and its first Run. If either write fails, neither may remain. Project changes after planning invalidate the token. Reusing a successfully consumed token is idempotent. Tests, reviews, and environments are completion gates only when explicitly required by the owner, the Task's Acceptance Criteria, or an active Guardrail; missing optional coverage is a documented follow-up/risk, not a failure by itself.
 
 The approved Run binds the exact Guardrail-policy fingerprint and a canonical workspace baseline. Every post-approval `deferred` check becomes an append-only Guardrail obligation. In the normal session path, agents work directly and one final checkpoint verifies the complete baseline-to-final delta: policy freshness, read-only boundaries, symlink safety, scannability, newly introduced secret-like content, and evidence for every Guardrail. Missing or unverifiable evidence fails closed. Strict teams may opt into short-lived, path-scoped permits and per-edit recording; those commands add stronger intermediate control but are not required for normal execution.
 

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,21 @@ 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.
+
+Every new Task starts with a `## Validation Scope`: only checks explicitly required by the owner, Acceptance Criteria, or an active Guardrail block completion. Missing optional E2E, integration, or review coverage belongs in a follow-up/risk note; it must not be used to mark the Run failed.
+
+## 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

@@ -57,7 +57,7 @@ function sprintBody(title, request, created, taskId) {
 function buildTaskBody(request, classification, approvalId, fingerprint, risk, previewSection, links = {}) {
   const featureSection = links.feature ? `\n## Feature\n\n- ${links.feature}\n` : "";
   const sprintSection = links.sprint ? `\n## Sprint\n\n- ${links.sprint}\n` : "";
-  return `# ${titleFor(request)}\n\n## Request\n\n${request}\n\n## Acceptance Criteria\n\n- [ ] _Define what "done" means before execution._\n${previewSection}${featureSection}${sprintSection}\n## Classification\n\n- Type: ${classification.type}\n- Reason: ${classification.reason}\n- Risk: ${risk.level}\n\n## Approval\n\n- Explicit approval token: ${approvalId}\n- Context fingerprint: ${fingerprint}`;
+  return `# ${titleFor(request)}\n\n## Request\n\n${request}\n\n## Acceptance Criteria\n\n- [ ] _Define what "done" means before execution._\n\n## Validation Scope\n\n- Required: validate the stated Acceptance Criteria and active Guardrails proportionately to risk.\n- Non-blocking: tests, reviews, or environments not explicitly required by the owner, Acceptance Criteria, or an active Guardrail. Record a material coverage gap as a follow-up; do not fail the Task solely because that optional check was not run.\n${previewSection}${featureSection}${sprintSection}\n## Classification\n\n- Type: ${classification.type}\n- Reason: ${classification.reason}\n- Risk: ${risk.level}\n\n## Approval\n\n- Explicit approval token: ${approvalId}\n- Context fingerprint: ${fingerprint}`;
 }
 
 function stateFingerprint(repository) {
@@ -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.3",
   "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,8 @@ 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;
+- validation is scoped: only a test/review/environment explicitly required by the owner, the Task's Acceptance Criteria, or an active Guardrail can block completion; a missing optional E2E suite is a documented follow-up/risk, never a reason to fail an otherwise accepted Task;
+- 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.
 
@@ -102,7 +104,7 @@ During execution:
 2. preserve existing owner work and unrelated dirty files;
 3. define or confirm the Task's `## Acceptance Criteria` before execution and check them off as evidence;
 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;
+5. validate in proportion to risk and against the acceptance criteria. Tests, reviews, and environments are required only when the owner, Acceptance Criteria, or an active Guardrail says so. Do not fail or block an otherwise accepted Task merely because an optional E2E/integration suite does not exist or was not run; record a material coverage gap as a follow-up/risk instead;
 6. run configured reviewers when a Guardrail requires one;
 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.
@@ -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.