scrumrun 3.1.0 → 3.1.2

package/CHANGELOG.md

@@ -4,6 +4,19 @@ 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
 
 ### Changed

package/CORE.md

@@ -90,6 +90,8 @@ AGENTS.md
 
 **Block only on real constraints.** An agent must stop for an explicit active Guardrail, secret/security risk, destructive action without approval, or an unmet required Acceptance Criterion. It must not manufacture a failed/blocked Run because optional E2E coverage, an optional reviewer, or a non-required environment is unavailable; record meaningful gaps in `## Follow-ups` or a risk note.
 
+**Normal operation never mutates Run state through the CLI.** Do not call `plan run --fail|--block|--retry|--finalize|--complete|--validate` or `plan task --start` in daily work. Those are owner-requested strict audit tools only. When a legacy Run already has the wrong administrative outcome, preserve it as history and correct the delivery record directly in the Task's Technical Summary and Follow-ups.
+
 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.1.0` · **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/lib/commands/render.js

@@ -36,6 +36,7 @@ ${grammarLines().join("\n")}
 - Evaluate active Guardrails as \`passed\`, \`blocked\`, or \`deferred\`; cite exact \`GR-NNN\` ids and keep deferred execution gates visible.
 - Block only for an explicit Guardrail, secret/security risk, destructive action without approval, or an unmet required Acceptance Criterion. Optional unrun E2E/review coverage is a follow-up/risk, not a failed Run.
 - Use the CLI only for \`init\`, \`update --project\`, \`migrate\`, \`repair\`, \`doctor\`, reports, or release checks. Do not invoke \`npx scrumrun@latest\` during execution.
+- Never invoke \`plan run --fail|--block|--retry|--finalize|--complete|--validate\` or \`plan task --start\` during normal work. These optional strict-audit commands must not decide a Task outcome.
 - Strict per-path Mutation Gateway permits and ledger finalization remain available only when the owner explicitly requests strict execution.
 - Knowledge/Decision/Insight records require evidence; AI-proposed Insights remain \`candidate\` until confirmed.
 - Never print vault values or write before approval.

package/package.json

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

package/templates/project/AGENTS.md

@@ -23,6 +23,7 @@ After approval:
 - record a `## Technical Summary` at completion so the next agent inherits what was done; record optional missing coverage in `## Follow-ups`;
 - work directly in code and Task Markdown after approval; do not call `npx scrumrun@latest` or normal `scrumrun plan/run` commands during execution;
 - use the CLI only for `init`, `update --project`, `migrate`, `repair`, `doctor`, reports, or release checks. It audits/repairs the folder; it does not own the daily workflow;
+- never invoke `plan run --fail`, `--block`, `--retry`, `--finalize`, `--complete`, `--validate`, or `plan task --start` in normal work. A failed legacy Run due to administrative state remains historical; write the corrected delivery outcome directly in the Task instead;
 - learning proposes evidence-backed Knowledge, Decisions, or candidate Insights when the work reveals reusable context;
 - guardrails remain mandatory: stop only for an explicit Guardrail, security/secret risk, destructive action without approval, or an unmet required Acceptance Criterion. Status vocabulary, missing Runs, unavailable optional tests, and stale generated state are warnings to reconcile, not blockers.
 

package/templates/project-lean/AGENTS.md

@@ -18,3 +18,5 @@ Guardrails are mandatory, but administrative state is not: block only for an exp
 `.scrumrun/guardrails.md` is canonical policy. Never bypass it, overwrite owner work, auto-confirm AI knowledge, auto-migrate v1 state, or print vault values.
 
 Use the installed CLI only for `init`, `update --project`, `migrate`, `repair`, `doctor`, reports, and release checks. For daily product work, follow `.scrumrun/core.md` and edit the relevant Markdown directly.
+
+Never invoke `plan run --fail`, `--block`, `--retry`, `--finalize`, `--complete`, `--validate`, or `plan task --start` during normal work. If an old Run says failed for an administrative reason, leave it as history and record the actual delivered outcome in the Task's Technical Summary and Follow-ups.

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

@@ -40,6 +40,8 @@ Normal hot path:
 
 **Do not block on administrative state.** A missing/invalid Run, legacy status vocabulary, stale generated view, or optional unrun test is a warning to reconcile in Markdown, not a reason to refuse productive work. Block only for an explicit Guardrail, security/secret risk, destructive action without approval, or an unmet required Acceptance Criterion. Optional E2E/integration/review coverage belongs in `## Follow-ups` or a risk note, never in a fabricated failed Run.
 
+**Normal-operation command ban.** Do not invoke `scrumrun plan run --fail`, `--block`, `--retry`, `--finalize`, `--complete`, `--validate`, or `scrumrun plan task --start` during ordinary work. Those are optional strict-audit tools and cannot be used to decide whether a Task is delivered. If an old Run is already failed for an administrative reason, leave it as historical evidence, continue the Task directly, and write the corrected outcome in the Task's Technical Summary and Follow-ups.
+
 Lean mode is a read policy, not an incomplete store. Generated files and `.scrumrun/.cache/` are never authoritative.
 
 Generated state and semantic indexes use a metadata-watch fast path with a full content-hash fallback. Treat cache-schema mismatch as a request to rebuild the disposable projection, never as permission to rewrite canonical Markdown.
@@ -55,7 +57,7 @@ For a v1 project without canonical v2 artifacts, recommend `scrumrun migrate --t
 - Memory — what was learned and why: `K-NNN`, `DEC-NNN`, `INS-NNN`, and dossiers.
 - Review (`REV-NNN`) — evidence from a scoped quality gate.
 
-Never create a Sprint merely because work exists. A standalone Task is valid. A retry creates a new Run and preserves the failed/blocked prior Run.
+Never create a Sprint merely because work exists. A standalone Task is valid. Strict audit retries preserve their prior Runs, but retries are never part of the normal workflow.
 
 ## Request pipeline
 
@@ -111,11 +113,11 @@ During 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 `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`.
+When work remains queued, the briefing may name the next backlog Task. The owner starts it through natural-language approval; do not call CLI start/retry commands to manufacture operational state. Each agent may record its identity in the Task handoff when useful.
 
 Every explicit Guardrail remains mandatory. In strict mode, the CLI final checkpoint fails closed on policy drift, protected-path changes, unsafe symlinks, unscannable content, newly introduced secret-like content, or missing Guardrail Evidence. The ignored permit cache is disposable; deleting it invalidates outstanding strict-mode permits and never creates authority.
 
-Run is the sole operational-history authority. Task synchronizes current status without copying Run events. Validation, learning, completion, failure, block, and resume require a reason or structured evidence; completion also requires evidenced validation and learning. Early v2 prose Runs are migrated explicitly, with deterministic chains recovered and uncertain history represented as an evidenced snapshot.
+Task Markdown is the daily operational handoff authority. A structured Run is optional strict audit history only. Early v2 prose Runs may be repaired/migrated explicitly, but their state never overrides the Task's direct handoff or blocks approved work.
 
 Linked canonical writes use the ignored durable transaction journal. An interrupted prepared mutation rolls back before the next approved mutation; a committed journal is verified and finalized. Audit remains read-only and reports pending recovery. Use `doctor --recover` only when explicitly requested, and never overwrite bytes changed after interruption.