mandrel 2.55.0 → 2.57.0

package/.agents/schemas/agentrc.schema.json

@@ -169,6 +169,25 @@
           "description": "Default `timeoutMs` applied to every `gh` subprocess the provider facade spawns, so a stalled socket or long-poll cannot hang an orchestration indefinitely. A `GhExecTimeoutError` from a hit ceiling is classified `transient` and retried by `withTransientRetry`. Story #2860.",
           "default": 60000
         },
+        "followUpRepos": {
+          "type": "object",
+          "description": "Repository slugs for the non-consumer follow-up ownership buckets, used when a CI gap, retro proposal, or audit finding belongs to someone other than the repo that surfaced it.",
+          "properties": {
+            "framework": {
+              "type": "string",
+              "pattern": "^[^/\\s]+/[^/\\s]+$",
+              "description": "`<owner>/<repo>` that owns framework-level defects. Defaults to the Mandrel mirror — the one bucket with a knowable default.",
+              "default": "dsj1984/mandrel"
+            },
+            "platform": {
+              "type": ["string", "null"],
+              "pattern": "^[^/\\s]+/[^/\\s]+$",
+              "description": "`<owner>/<repo>` for a shared platform or infrastructure tracker (a shared base config, a runner fleet, a cross-repo toolchain). No default — nothing can guess a shared repo. Left unset, platform-owned findings file locally and say so.",
+              "default": null
+            }
+          },
+          "additionalProperties": false
+        },
         "branchProtection": {
           "type": "object",
           "description": "Branch-protection stance applied to `project.baseBranch` by the GitHub bootstrap, and reproduced locally before every push.",
@@ -308,145 +327,21 @@
     },
     "planning": {
       "type": "object",
-      "description": "Inputs to `/mandrel-plan`: risk escalation heuristics, ceremony-lite routing, the memory-hygiene advisory thresholds, and the cross-Story conflict-finding severity gates.",
+      "description": "Inputs to `/mandrel-plan`: the memory-hygiene advisory ceiling and the opt-in navigability reachability gate.",
       "properties": {
-        "riskHeuristics": {
-          "oneOf": [
-            {
-              "type": "array",
-              "items": {
-                "type": "string"
-              }
-            },
-            {
-              "type": "object",
-              "properties": {
-                "append": {
-                  "type": "array",
-                  "items": {
-                    "type": "string"
-                  }
-                },
-                "prepend": {
-                  "type": "array",
-                  "items": {
-                    "type": "string"
-                  }
-                }
-              },
-              "additionalProperties": false
-            }
-          ],
-          "description": "Prose heuristics the planner escalates a Story against. A plain array replaces the framework list; the `{ append, prepend }` extender form deep-merges with it.",
-          "default": [
-            "Destructive or irreversible data mutations (dropping tables, deleting rows without soft-delete or backup, truncating production state).",
-            "Modifications to shared security or auth infrastructure (IAM policies, auth middleware, session or token handling, secret rotation).",
-            "Changes to CI/CD, deployment pipelines, or release gating that could disable safety checks or ship unverified code to production.",
-            "Monorepo-wide AST or text replacements touching overlapping files in parallel (catastrophic merge-conflict risk across concurrent agents).",
-            "Schema migrations that rewrite existing rows or drop columns without a backfill or rollback plan."
-          ]
-        },
-        "complexityGate": {
-          "type": "object",
-          "description": "Shape-derived ceremony-lite complexity routing. A lite claim is validated against the authored Story shape at persist and re-derived from the Story body at dispatch; conservative (full on any doubt). Never relaxes the Story-ticket / PR-to-main / repo-gates / security-baseline non-negotiables.",
-          "properties": {
-            "enabled": {
-              "type": "boolean",
-              "description": "Master switch. When false, lite routing is disabled everywhere: persist refuses lite claims and dispatch always takes the sub-agent path. Default true."
-            },
-            "maxArtifacts": {
-              "type": "integer",
-              "minimum": 0,
-              "description": "Enumerated-artifact threshold reported by the plan-context complexity signals. An input signal for the planner verdict — carries no routing authority. Default 1."
-            }
-          },
-          "additionalProperties": false
-        },
         "memoryPool": {
           "type": "object",
-          "description": "Thresholds for the memory-hygiene advisory `/mandrel-plan` surfaces at Gate #1. Advisory only: it recommends `/memory-consolidate` and never gates, reroutes, or mutates the memory pool.",
+          "description": "Threshold for the memory-hygiene advisory `/mandrel-plan` surfaces at Gate #1. Advisory only: it recommends `/memory-consolidate` and never gates, reroutes, or mutates the memory pool.",
           "properties": {
-            "staleAfterDays": {
-              "type": "integer",
-              "minimum": 1,
-              "description": "Recommend a consolidation pass once the pool's stamp is older than this many days. Default 30.",
-              "default": 30
-            },
-            "growthDelta": {
-              "type": "integer",
-              "minimum": 1,
-              "description": "Recommend a consolidation pass once this many entries have been written since the last one. Measured against the entry count the last pass stamped, so a stamp predating that field leaves growth unmeasured and only the age threshold applies. Default 25.",
-              "default": 25
-            },
             "indexByteCeiling": {
               "type": "integer",
               "minimum": 1,
-              "description": "Recommend a consolidation pass once the pool's `MEMORY.md` index exceeds this many bytes. Independent of the age and growth thresholds: the harness truncates the index it loads into each session at its own byte cap, so an oversized index is a loss already happening — every entry listed after the cut is invisible — rather than a hygiene forecast. Default 24576, the harness cap itself.",
+              "description": "Recommend a consolidation pass once the pool's `MEMORY.md` index exceeds this many bytes. The harness truncates the index it loads into each session at its own byte cap, so an oversized index is a loss already happening — every entry listed after the cut is invisible — rather than a hygiene forecast. Default 24576, the harness cap itself.",
               "default": 24576
             }
           },
           "additionalProperties": false
         },
-        "failOnSharedEditors": {
-          "type": "boolean",
-          "description": "When true, upgrade shared-editor conflict findings to hard errors (default false — advisory soft findings only).",
-          "default": false
-        },
-        "requireExplicitCrossStoryDeps": {
-          "type": "boolean",
-          "description": "When true, upgrade implicit cross-Story dependency findings to hard errors (default false — advisory soft findings only).",
-          "default": false
-        },
-        "crossCuttingRegistries": {
-          "oneOf": [
-            {
-              "type": "array",
-              "items": {
-                "type": "string"
-              }
-            },
-            {
-              "type": "object",
-              "properties": {
-                "append": {
-                  "type": "array",
-                  "items": {
-                    "type": "string"
-                  }
-                },
-                "prepend": {
-                  "type": "array",
-                  "items": {
-                    "type": "string"
-                  }
-                }
-              },
-              "additionalProperties": false
-            }
-          ],
-          "description": "Registry path patterns whose concurrent edits across Stories are flagged as conflicts. Defaults to the framework listener/handler index patterns when omitted.",
-          "default": [
-            "lib/orchestration/lifecycle/listeners/index.js",
-            "**/listeners/index.js",
-            "**/handlers/index.js"
-          ]
-        },
-        "failOnRegistryConflicts": {
-          "type": "boolean",
-          "description": "When true, upgrade cross-cutting registry conflict findings to hard errors (default false).",
-          "default": false
-        },
-        "failOnLargeFanOut": {
-          "type": "boolean",
-          "description": "When true, upgrade fan-out-warning findings (delete blast radius) to hard errors (default false — soft advisory).",
-          "default": false
-        },
-        "largeFanOutThreshold": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Call-site count above which a Story that deletes a module emits a fan-out-warning. Counts base-branch references to the deleted path basename. Soft by default; does not size or reject Stories. Default 10.",
-          "default": 10
-        },
         "navigation": {
           "type": "object",
           "description": "Opt-in navigability reachability gate. Absent or empty routeGlobs is a silent no-op.",
@@ -475,7 +370,7 @@
     },
     "delivery": {
       "type": "object",
-      "description": "Everything `/mandrel-deliver` and `single-story-close` consume: execution timeouts, worktree isolation, runner concurrency, docs freshness, signals, quality gates, merge/CI watch, review ceremony, and the feedback loop.",
+      "description": "Everything `/mandrel-deliver` and `single-story-close` consume: execution timeouts, worktree isolation, runner concurrency, docs freshness, quality gates, merge/CI watch, review ceremony, and the feedback loop.",
       "properties": {
         "execution": {
           "type": "object",
@@ -652,39 +547,6 @@
             }
           ]
         },
-        "signals": {
-          "type": "object",
-          "description": "Detector thresholds for the surviving performance-signal categories. Each block is shallow-merged by the resolver.",
-          "properties": {
-            "rework": {
-              "type": "object",
-              "description": "Rework detector — repeated edits to one file in a run.",
-              "properties": {
-                "editsPerFile": {
-                  "type": "integer",
-                  "minimum": 1,
-                  "description": "Edits to a single file within one run that trip the rework signal.",
-                  "default": 5
-                }
-              },
-              "additionalProperties": false
-            },
-            "retry": {
-              "type": "object",
-              "description": "Retry detector — the same command failing repeatedly.",
-              "properties": {
-                "repeatCount": {
-                  "type": "integer",
-                  "minimum": 1,
-                  "description": "Repeats of an identical failing command that trip the retry signal.",
-                  "default": 3
-                }
-              },
-              "additionalProperties": false
-            }
-          },
-          "additionalProperties": false
-        },
         "quality": {
           "type": "object",
           "description": "Quality-gate configuration. Every gate lives under `gates.<tier>` and shares the same `{ enabled, baselinePath, tolerance, floors, components }` base; shared scoping lives at this block root.",
@@ -1591,12 +1453,6 @@
                   "description": "Cyclomatic complexity at which a new or changed method is flagged for a refactor look.",
                   "default": 8
                 },
-                "cyclomaticMustFix": {
-                  "type": "integer",
-                  "minimum": 1,
-                  "description": "Cyclomatic complexity at which a new or changed method must be decomposed before the diff closes.",
-                  "default": 12
-                },
                 "requireSiblingTest": {
                   "type": "boolean",
                   "description": "When true, a new source file with no colocated sibling test is reported by the guardrails pass.",
@@ -1838,12 +1694,6 @@
               "description": "Maximum auto-fix retry attempts per finding in /mandrel-deliver Phase 5 (code-review). 0 disables auto-fix. Default 3.",
               "default": 3
             },
-            "maxFixScopeFiles": {
-              "type": "integer",
-              "minimum": 1,
-              "description": "Maximum file count a single auto-fix may modify before escalating to agent::blocked. Default 5.",
-              "default": 5
-            },
             "autoFixSeverity": {
               "type": "string",
               "enum": ["high", "medium"],
@@ -1879,12 +1729,12 @@
         },
         "acceptanceEval": {
           "type": "object",
-          "description": "Story #3819. Bounded per-Story acceptance self-eval loop. After the implementation commits land and before the Story-implementation phase flips to `closing`, an independent (fresh-context) critic pass scores the caller-injected change set against each inline `acceptance[]` item, redrafts the unmet items, and re-evaluates — capped at `maxRounds` redraft rounds, then escalates to `agent::blocked` when criteria remain unmet. There is no `enabled` flag: the loop is a hard cutover (always on).",
+          "description": "Story #3819. Bounded per-Story acceptance self-eval loop. After the implementation commits land and before the Story-implementation phase flips to `closing`, an independent (fresh-context) critic pass scores the caller-injected change set against each inline `acceptance[]` item, redrafts the unmet items, and re-evaluates — capped at `maxRounds` redraft rounds (0 = scored once, no redraft), then escalates to `agent::blocked` when criteria remain unmet. There is no `enabled` flag: the scoring pass is a hard cutover (always on).",
           "properties": {
             "maxRounds": {
               "type": "integer",
-              "minimum": 1,
-              "description": "Maximum number of redraft rounds before escalation. Default 2; clamped into [1, hard ceiling] by lib/config/acceptance-eval.js so the cap can never be disabled (maxRounds: 0 clamps up to 1).",
+              "minimum": 0,
+              "description": "Maximum number of redraft rounds before escalation. Default 2; 0 means the verdict is scored once with no redraft round (Story #5313 dropped the hard ceiling and the floor-of-one clamp).",
               "default": 2
             }
           },
@@ -1993,24 +1843,17 @@
         },
         "routing": {
           "type": "object",
-          "description": "v2 delivery-spawn routing: role-scoped boot contexts and maker-checker sampling. The v1 singleDelivery epic-route kill-switch was removed in Stage 6.",
+          "description": "v2 delivery-spawn routing: role-scoped boot contexts and the ceremony profile. The v1 singleDelivery epic-route kill-switch was removed in Stage 6; the freshCriticSampleRate sampling floor was retired in Story #5313.",
           "properties": {
             "roleScopedAgents": {
               "type": "boolean",
               "description": "Epic #4478 (M7-B). Kill-switch for the role-scoped boot contexts. When true (default), a converted delivery spawn (`story-worker`, `acceptance-critic`) boots on its own `.claude/agents/<role>.md` system prompt instead of re-paying the full CLAUDE.md @-import closure. When false, every converted spawn falls back to `subagent_type: general-purpose` — the instant, code-rollback-free per-consumer revert, and the universal escape for hosts that ignore `.claude/agents/`. The fallback is the full-closure agent that ran before M7-B, so flipping it off never drops a gate.",
               "default": true
             },
-            "freshCriticSampleRate": {
-              "type": "number",
-              "minimum": 0,
-              "maximum": 1,
-              "description": "Epic #4478 (M7-B, Part 2). Maker-checker sampling floor. Under the standard profile, a change set touching no sensitive path routes its acceptance clusters down the contract-identical inline critic path, but this fraction of them is still forced through a fresh-context critic so a low derived level never means zero independent checking. Clamped to [0, 1]; 0 disables the floor, 1 forces every cluster fresh. Consumed by resolveCeremonyForRisk (lib/orchestration/ceremony-routing.js).",
-              "default": 0.2
-            },
             "ceremonyProfile": {
               "type": "string",
               "enum": ["minimal", "standard", "strict"],
-              "description": "Acceptance-ceremony depth. minimal = always inline critic; strict = always fresh-context critic; standard (default) = routed off the change level derived from the Story diff, with the maker-checker sampling floor.",
+              "description": "Acceptance-ceremony depth. minimal = always inline critic; strict = always fresh-context critic; standard (default) = routed off the change level derived from the Story diff: high or underivable → fresh, low → inline.",
               "default": "standard"
             },
             "closeAndLand": {

package/.agents/schemas/story-deliver-terminal.schema.json

@@ -161,7 +161,7 @@
           "type": "array",
           "minItems": 1,
           "items": { "type": "string", "minLength": 1 },
-          "description": "The gate's reasons verbatim — the same strings the ask-operator path prints, so attended and unattended over-scope explain themselves identically."
+          "description": "The gate's reasons verbatim — the same strings the gate logs, so an escalation explains itself identically on every surface."
         },
         "created": {
           "type": "object",

package/.agents/scripts/acceptance-eval.js

@@ -17,8 +17,8 @@
  *   1. Validate the verdict file against the verdict JSON Schema (a
  *      malformed verdict is a hard error — the loop refuses to guess).
  *   2. Decide `proceed | redraft | block` from the per-criterion verdicts
- *      and the resolved, undisableable round cap
- *      (`delivery.acceptanceEval.maxRounds`, clamped to `[1, ceiling]`).
+ *      and the resolved redraft budget (`delivery.acceptanceEval.maxRounds`;
+ *      `0` means the verdict is scored once with no redraft round).
  *   3. Emit one per-criterion `acceptance-eval` signal into the retro /
  *      feedback substrate so the retro and `/mandrel-plan` Phase 0 feedback
  *      fetch can see which acceptance items needed rework and the round
@@ -46,14 +46,19 @@
  * the caller into ONE verdict — `criteria[]` in acceptance-array order — and
  * scored here exactly once. Invoking the gate per cluster instead would burn
  * one Story-level round per cluster (distinct fingerprints defeat the replay
- * guard) and race the `signals.ndjson` round ledger. `--expected-criteria`
- * makes that contract enforceable: a partial (single-cluster) verdict is
- * rejected before scoring, so the mistake costs no round.
+ * guard) and race the `signals.ndjson` round ledger. The gate reads the
+ * Story's own `acceptance[]` count off its body (Story #5313) and rejects a
+ * verdict whose `criteria[]` length differs **before** scoring, so the
+ * mistake costs no round. `--expected-criteria` is still accepted but is
+ * redundant with the derived count: when both are known they must agree.
+ * An inline-owned verdict is one file scored in one call — the cluster
+ * merge applies only to fresh critics.
  *
  * CLI:
  *   --story <id>              Story ID (required).
  *   --verdict <path>          Path to the round's verdict JSON (required).
- *   --expected-criteria <n>   Reject a verdict not covering exactly n criteria.
+ *   --expected-criteria <n>   Optional; must equal the Story's acceptance[]
+ *                             count when the body is readable.
  *   --no-signal               Suppress the signal emit (tests).
  *
  * Stdout: a single JSON envelope
@@ -93,6 +98,8 @@ import {
   FULL_SUITE_SHAPE_WARNING,
   isFullSuiteCommand,
 } from './lib/orchestration/verify-credit.js';
+import { createProvider } from './lib/provider-factory.js';
+import { parse as parseStoryBody } from './lib/story-body/story-body.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -181,10 +188,84 @@ const MERGE_CONTRACT =
   "merge every cluster's records into a single criteria[] in acceptance[] order, " +
   'one per acceptance item, before scoring.';
 
+/**
+ * Read the Story's `acceptance[]` count off its body (Story #5313), so the
+ * coverage assertion no longer depends on the caller restating a number it
+ * already read. Total: any failure — no provider, an unreadable ticket, an
+ * unparseable body — yields `null`, which routes the caller to the flag (when
+ * passed) and otherwise to a stated, logged skip. It never manufactures a
+ * count.
+ *
+ * @param {{ storyId: number, config: object }} args
+ * @param {{ createProviderFn?: typeof createProvider, parseBodyFn?: typeof parseStoryBody }} [deps]
+ * @returns {Promise<number|null>}
+ */
+export async function readStoryAcceptanceCount(
+  { storyId, config },
+  { createProviderFn = createProvider, parseBodyFn = parseStoryBody } = {},
+) {
+  try {
+    const ticket = await createProviderFn(config).getTicket(storyId);
+    const body = typeof ticket?.body === 'string' ? ticket.body : null;
+    if (body === null) return null;
+    const acceptance = parseBodyFn(body)?.body?.acceptance;
+    return Array.isArray(acceptance) && acceptance.length > 0
+      ? acceptance.length
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reconcile the body-derived count with the optional flag (Story #5313): the
+ * derived count is authoritative; a flag that disagrees with it is a wiring
+ * error worth failing on rather than a value to prefer silently.
+ *
+ * @param {{ derived: number|null, flagged: number|null }} args
+ * @returns {number|null}
+ */
+export function reconcileExpectedCriteria({ derived, flagged }) {
+  if (derived === null) return flagged;
+  if (flagged !== null && flagged !== derived) {
+    throw new Error(
+      `acceptance-eval: --expected-criteria ${flagged} disagrees with the Story's acceptance[] count (${derived}); drop the flag — the gate reads the count itself.`,
+    );
+  }
+  return derived;
+}
+
+/**
+ * The count the coverage assertion runs against: the body-derived count,
+ * reconciled with the optional flag, with a stated skip when neither is
+ * readable (Story #5313). Split out of `runAcceptanceEvalCli` so the CLI
+ * body's own branching stays inside its committed cyclomatic budget.
+ *
+ * @param {{ storyId: number, config: object, flagged: number|null, readAcceptanceCountImpl: typeof readStoryAcceptanceCount, logger: { warn?: Function } }} args
+ * @returns {Promise<number|null>}
+ */
+async function resolveExpectedCriteriaCount({
+  storyId,
+  config,
+  flagged,
+  readAcceptanceCountImpl,
+  logger,
+}) {
+  const derived = await readAcceptanceCountImpl({ storyId, config });
+  const expected = reconcileExpectedCriteria({ derived, flagged });
+  if (expected === null) {
+    logger.warn?.(
+      '[acceptance-eval] ⚠ the Story acceptance[] count could not be read and no --expected-criteria was passed — the coverage assertion is skipped for this round.',
+    );
+  }
+  return expected;
+}
+
 /**
  * Resolve the optional `--expected-criteria` flag to a positive integer, or
- * `null` when the flag is absent (which preserves the pre-#4951 behaviour
- * exactly — no coverage assertion is made).
+ * `null` when the flag is absent. Since Story #5313 the gate derives the
+ * count from the Story body; the flag remains accepted for callers that
+ * still pass it and is checked against the derived value.
  *
  * Exported for tests.
  *
@@ -225,7 +306,7 @@ export function assertCriteriaCoverage(verdict, expectedCriteria) {
   const actual = Array.isArray(verdict?.criteria) ? verdict.criteria.length : 0;
   if (actual === expectedCriteria) return;
   throw new Error(
-    `acceptance-eval: verdict covers ${actual} criteria but --expected-criteria is ${expectedCriteria}. ` +
+    `acceptance-eval: verdict covers ${actual} criteria but the Story's acceptance[] count is ${expectedCriteria}. ` +
       `${MERGE_CONTRACT} No round was consumed.`,
   );
 }
@@ -409,6 +490,7 @@ export async function runAcceptanceEval(
  *   resolveConfigImpl?: typeof resolveConfig,
  *   validateVerdictImpl?: typeof validateVerdict,
  *   runAcceptanceEvalImpl?: typeof runAcceptanceEval,
+ *   readAcceptanceCountImpl?: typeof readStoryAcceptanceCount,
  *   logger?: { info: Function, warn?: Function },
  * }} [deps]
  * @returns {Promise<object>} the emitted envelope.
@@ -422,11 +504,12 @@ export async function runAcceptanceEvalCli(
     resolveConfigImpl = resolveConfig,
     validateVerdictImpl = validateVerdict,
     runAcceptanceEvalImpl = runAcceptanceEval,
+    readAcceptanceCountImpl = readStoryAcceptanceCount,
     logger = Logger,
   } = deps;
   const { storyId, verdictPath, expectedCriteria, emitSignal } =
     parseCliArgs(argv);
-  const expected = resolveExpectedCriteria(expectedCriteria);
+  const flagged = resolveExpectedCriteria(expectedCriteria);
 
   if (!storyId) {
     throw new Error(
@@ -461,9 +544,17 @@ export async function runAcceptanceEvalCli(
 
   const verdict = validateVerdictImpl(parsed);
 
-  // Story #4951: a merged verdict must cover every acceptance[] item. This
-  // runs before the round ledger is touched, so a partial cluster verdict is
-  // a free mistake.
+  // Story #4951 / #5313: a merged verdict must cover every acceptance[] item,
+  // and the count comes from the Story body itself. This runs before the
+  // round ledger is touched, so a partial cluster verdict is a free mistake.
+  const config = resolveConfigImpl();
+  const expected = await resolveExpectedCriteriaCount({
+    storyId,
+    config,
+    flagged,
+    readAcceptanceCountImpl,
+    logger,
+  });
   assertCriteriaCoverage(verdict, expected);
 
   // A verdict whose embedded storyId disagrees with the CLI flag is a
@@ -479,7 +570,6 @@ export async function runAcceptanceEvalCli(
   // caller that injects its own scorer.
   warnOnFullSuiteVerify(verdict, logger);
 
-  const config = resolveConfigImpl();
   const { envelope, exitCode } = await runAcceptanceEvalImpl({
     storyId,
     verdict,
@@ -522,9 +612,9 @@ runAsCli(import.meta.url, main, {
       ['--verdict <path>', 'Path to the authored verdict JSON (required).'],
       [
         '--expected-criteria <n>',
-        'Reject — before scoring, consuming no round — a verdict whose criteria[] ' +
-          "length is not n. Pass the Story's acceptance[] count so a partial " +
-          'cluster verdict cannot be scored as the round.',
+        "Optional and redundant since Story #5313: the gate reads the Story's " +
+          'acceptance[] count itself and rejects a shorter verdict before ' +
+          'scoring. When passed it must agree with that count.',
       ],
       [
         '--no-signal',