scrumrun 3.1.1 → 3.1.2

package/CHANGELOG.md

@@ -4,11 +4,18 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+## 3.1.2 - 2026-08-31
+
+### Fixed
+
+- **Mechanical strict-audit gate.** The CLI now refuses Task start/retry and every Run state transition unless `--strict` is explicitly present. This prevents a normal agent loop from creating failed/blocked administrative Runs even if it ignores the Markdown-first guidance.
+
 ## 3.1.1 - 2026-08-31
 
 ### Fixed
 
 - **No strict-Run commands in daily work.** Generated Core and agent instructions now explicitly prohibit `plan run --fail|--block|--retry|--finalize|--complete|--validate` and `plan task --start` in normal operation. A legacy Run incorrectly failed for administrative reasons stays as history; the Task's direct Markdown handoff records the real result.
+- **CLI backstop.** Task start/retry and Run state-changing commands now require an explicit `--strict`, so an agent that ignores the guidance cannot accidentally create another failed/blocked administrative Run.
 
 ## 3.1.0 - 2026-08-31
 

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.1.1` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+**Package:** `3.1.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).
 
@@ -101,6 +101,8 @@ scrumrun review release --run
 
 `update --project` refreshes packaged `core.md` and recognized generated `AGENTS.md` with a local byte-exact backup before replacing them. The CLI can still generate/validate Task, Feature, Sprint, and Run records when desired, but it must never become a routine blocker.
 
+For extra protection, CLI Task start/retry and every Run state transition require `--strict`. This prevents accidental administrative failures in the normal Markdown-first workflow.
+
 Each optional structured Run contains a machine-validated event ledger. It remains useful for strict audit/release work, but daily history can stay as concise, human-readable Task handoff Markdown.
 
 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

@@ -1308,6 +1308,7 @@ function runTransitionOptions(args) {
   let summary = null;
   for (let index = 2; index < args.length; index++) {
     const token = args[index];
+    if (token === "--strict") continue;
     const value = args[index + 1] && !args[index + 1].startsWith("--") ? args[index + 1] : null;
     if (token === "--note" || token === "--actor" || token === "--at" || token === "--evidence" || token === "--summary" || evidenceFlags.has(token)) {
       if (!value) throw new Error(`${token} requires a value.`);
@@ -1333,6 +1334,11 @@ function runTransitionOptions(args) {
   return { note: note || noteParts.join(" ").trim() || null, evidence, actor, occurredAt, summary };
 }
 
+function requireStrictAudit(args, action) {
+  if (args.includes("--strict")) return;
+  throw new Error(`${action} is disabled in Markdown-first daily work. Update the Task Markdown directly; use --strict only for an owner-requested audit.`);
+}
+
 function removeOptionPairs(args, names) {
   const hidden = new Set(names);
   const next = [];
@@ -1470,6 +1476,7 @@ function executeRootRoute(route) {
     return;
   }
   if (noun === "plan" && subject === "task" && routeArgs[0] === "--retry") {
+    requireStrictAudit(routeArgs, "Task retry");
     const result = retryTask(process.cwd(), routeArgs[1], { reassign: routeArgs.includes("--reassign") });
     console.log(`Created retry ${result.run.id} for ${result.task.id} (attempt ${result.run.attempt}).`);
     return;
@@ -1486,6 +1493,7 @@ function executeRootRoute(route) {
     return;
   }
   if (noun === "plan" && subject === "task" && routeArgs[0] === "--start") {
+    requireStrictAudit(routeArgs, "Task start");
     let target = routeArgs[1];
     if (!target) {
       const repository = new ArtifactRepository(projectFile());
@@ -1610,9 +1618,10 @@ function executeRootRoute(route) {
   }
   if (noun === "plan" && subject === "run") {
     if (routeArgs[0] === "--finalize") {
+      requireStrictAudit(routeArgs, "Run finalization");
       const runId = routeArgs[1];
       if (!runId) throw new Error("--finalize requires RUN-NNN.");
-      const result = finalizeRun(process.cwd(), runId, runTransitionOptions(routeArgs.slice(2)));
+      const result = finalizeRun(process.cwd(), runId, runTransitionOptions(routeArgs));
       console.log(`${result.run.id}: completed; ${result.task.id}: completed. Final session audit verified ${result.changes} change(s).`);
       if (result.resolved.length) console.log(`Guardrails verified: ${result.resolved.join(", ")}.`);
       if (result.learning && result.learning.created.length) console.log(`Learning candidates: ${result.learning.created.join(", ")}.`);
@@ -1654,6 +1663,7 @@ function executeRootRoute(route) {
       "--block": "blocked"
     };
     if (transitions[routeArgs[0]]) {
+      requireStrictAudit(routeArgs, `Run transition ${routeArgs[0]}`);
       const result = transitionRun(process.cwd(), routeArgs[1], transitions[routeArgs[0]], runTransitionOptions(routeArgs));
       console.log(`${result.run.id}: ${result.run.status}; ${result.task.id}: ${result.task.status}.`);
       if (result.learning) {

package/docs/COMMANDS.md

@@ -13,14 +13,14 @@ Use `.scrumrun/` Markdown for normal project work. `/sc` and the installed CLI a
 ```text
 scrumrun plan intake <request>
 scrumrun plan intake --approve <token>
-scrumrun plan task --add|--list|--show|--run|--audit|--cancel|--retry
+scrumrun plan task --add|--list|--show|--run|--audit|--cancel|--retry --strict
 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 --list|--show|--validate|--learn|--complete|--resume|--fail|--block --strict [--note] [typed evidence flags]
+scrumrun plan run --finalize RUN-NNN --strict [--summary "technical recap"] [--note]
 scrumrun plan run --authorize-mutation RUN-NNN --path <relative-path> [--path ...]
 scrumrun plan run --record-mutation RUN-NNN --permit MUT-id [--note] [--actor]
 scrumrun plan run --satisfy-guardrail RUN-NNN --guardrail GR-NNN [typed evidence flags]
@@ -29,6 +29,8 @@ scrumrun plan challenge <question>
 
 Normal execution is Markdown-first: after approval, work in code and the relevant Task Markdown, then record the Technical Summary and any Follow-ups directly. A Run/`--finalize` checkpoint is optional strict audit, never a prerequisite. Mutation permits are available only for explicitly requested strict mode.
 
+The CLI refuses Task start/retry and all Run state changes unless `--strict` is present. This prevents an agent from accidentally manufacturing a failed/blocked retry during normal work; `--strict` is for an owner-requested audit only.
+
 `--amend` is an optional structured helper. The Markdown-first workflow may adjust Task/Feature/Sprint content directly, preserving a useful handoff. Use the CLI when atomic relation synchronization or machine audit is valuable; do not let status vocabulary or missing relations stop approved work.
 
 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.

package/lib/commands/manifest.js

@@ -6,7 +6,7 @@ const nouns = Object.freeze({
   plan: {
     description: "turn intent into Features, Tasks, Sprints, and Runs",
     subjects: {
-      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]"],
+      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] --strict", "--next", "--start [TASK-NNN] --strict"],
       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: [
@@ -15,16 +15,16 @@ const nouns = Object.freeze({
         "--render <RUN-NNN>",
         "--stats [--task <TASK-NNN>] [--feature <FEAT-NNN>] [--sprint <SPRINT-NNN>] [--json]",
         "--normalize-legacy [--dry-run]",
-        "--finalize <RUN-NNN> [--summary \"technical recap\"] [--note]",
+        "--finalize <RUN-NNN> --strict [--summary \"technical recap\"] [--note]",
         "--authorize-mutation <RUN-NNN> --path <relative-path>",
         "--record-mutation <RUN-NNN> --permit <MUT-id> [--note] [--actor]",
         "--satisfy-guardrail <RUN-NNN> --guardrail <GR-NNN> [--note] [--evidence] [--review] [--migration] [--actor]",
-        "--validate [--note] [--evidence] [--command] [--test] [--file] [--review] [--actor] [--at]",
-        "--learn [--note] [--evidence] [--decision] [--insight] [--file] [--actor] [--at]",
-        "--complete [--note] [--evidence] [--review] [--test] [--file] [--actor] [--at] [--summary \"technical recap for future tasks\"]",
-        "--resume [--note] [--evidence] [--risk] [--actor] [--at]",
-        "--fail [--note] [--evidence] [--risk] [--test] [--actor] [--at]",
-        "--block [--note] [--evidence] [--risk] [--actor] [--at]"
+        "--validate --strict [--note] [--evidence] [--command] [--test] [--file] [--review] [--actor] [--at]",
+        "--learn --strict [--note] [--evidence] [--decision] [--insight] [--file] [--actor] [--at]",
+        "--complete --strict [--note] [--evidence] [--review] [--test] [--file] [--actor] [--at] [--summary \"technical recap for future tasks\"]",
+        "--resume --strict [--note] [--evidence] [--risk] [--actor] [--at]",
+        "--fail --strict [--note] [--evidence] [--risk] [--test] [--actor] [--at]",
+        "--block --strict [--note] [--evidence] [--risk] [--actor] [--at]"
       ],
       intake: ["<request>", "--request", "--approve", "--plain", "--json", "--type <fix|task|feature|docs|discovery>", "--preview \"technical summary\""],
       challenge: ["<question>"]

package/package.json

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