mandrel 2.58.0 → 2.60.0

package/.agents/scripts/run-verify.js

@@ -7,7 +7,8 @@
  *
  * Order: audit (SCA) → lint (includes docs:check + the arch-cycles ratchet) →
  * full test suite → unified baselines → the standalone ratchets
- * (dead-exports ×2, context-budget, cyclomatic, schema-references).
+ * (dead-exports ×2, context-budget, workflow-citations, cyclomatic,
+ * schema-references).
  *
  * The `audit` step runs `npm audit --audit-level=high`, matching CI's
  * "Dependency Vulnerability Audit (SCA)" gate so a local green no longer hides
@@ -33,9 +34,14 @@
  * being added here, so a green `verify` still hid both. Like their neighbours
  * they are pure-Node and cost milliseconds.
  *
- * Still NOT mirrored: `check-workflow-citations.js` and
- * `check-baseline-scope.js` run in CI's `baselines` job only —
- * `.agents/rules/known-tooling-behavior.md` entry 2 carries the current
+ * Story #5340 closed the `check-workflow-citations.js` gap the same way, once
+ * demoting it to a report made it free: it had been exempted here because
+ * `tests/check-workflow-citations.test.js` re-ran the same ratchet, so a
+ * `verify` step would have double-paid it. That test now asserts the report,
+ * not a ceiling, so the step is the only local surface that prints the count.
+ *
+ * Still NOT mirrored: `check-baseline-scope.js` runs in CI's `baselines` job
+ * only — `.agents/rules/known-tooling-behavior.md` entry 2 carries the current
  * coverage table. (`prune-baseline-orphans.js --check` used to sit in that
  * list; it no longer runs in CI at all — the un-attributed duplicate of the
  * scope gate's `extra` direction reds every open PR on inherited rows.) Nor are the CI gates this command structurally cannot
@@ -50,8 +56,8 @@ import { spawnSync } from 'node:child_process';
 import { runAsCli } from './lib/cli-utils.js';
 
 /**
- * A gate step: `node .agents/scripts/<script>` plus any extra args. Seven of
- * the ten steps share exactly that shape, so spelling it once leaves the list
+ * A gate step: `node .agents/scripts/<script>` plus any extra args. Eight of
+ * the eleven steps share exactly that shape, so spelling it once leaves the list
  * below readable as what it actually is — a gate *order* — instead of a wall
  * of spawn tuples.
  *
@@ -79,6 +85,7 @@ const STEPS = [
   gate('dead-exports', 'check-dead-exports.js'),
   gate('dead-exports-production', 'check-dead-exports.js', '--production'),
   gate('context-budget', 'check-context-budget.js'),
+  gate('workflow-citations', 'check-workflow-citations.js'),
   gate('cyclomatic', 'check-cyclomatic.js'),
   gate('schema-references', 'check-schema-references.js'),
 ];

package/.agents/scripts/single-story-init.js

@@ -70,7 +70,6 @@ import { handleRemoteVerificationFailure } from './lib/orchestration/story-init-
 import {
   STATE_LABELS,
   transitionTicketState,
-  upsertStructuredComment,
 } from './lib/orchestration/ticketing.js';
 import { createProvider } from './lib/provider-factory.js';
 import { buildProtectionCtx } from './lib/single-story-sweep/protection-ctx.js';
@@ -770,28 +769,13 @@ export async function runSingleStoryInit({
     remoteProbe: { remoteUrl: remote.remoteUrl, detail: remote.detail },
   };
 
-  // Upsert the `story-init` structured comment (no-op under --dry-run). The
-  // `agent::executing` flip already happened above, before provisioning, so the
-  // claim is label-visible during the install window (see `flipStoryToExecuting`).
-  if (!dryRun) {
-    try {
-      await upsertStructuredComment(
-        provider,
-        storyId,
-        'story-init',
-        renderSingleStoryInitComment(result),
-      );
-      progress(
-        'COMMENT',
-        `📝 Upserted story-init structured comment on #${storyId}.`,
-      );
-    } catch (err) {
-      Logger.error(
-        `[single-story-init] ⚠️ Failed to upsert story-init structured comment: ${err?.message ?? err}`,
-      );
-    }
-  }
-
+  // Story #5343 — init posts no `story-init` comment. It was one GitHub write
+  // per Story restating what its own envelope already carries; the envelope is
+  // on stdout and on disk (below), `deliver-recover.js` classifies state from
+  // labels, the PR probe and disk artifacts, and `run-scoped-config.js` reads
+  // the base-branch pin off that same envelope. The `agent::executing` flip
+  // above is what makes the claim visible during the install window.
+  //
   // Story #4685 — route the full result to a temp log and emit a single-line
   // summary carrying the fields the orchestrating agent acts on (workCwd,
   // remoteVerified). The `## Spec` names this the hot-path stdout to quiet.
@@ -820,40 +804,6 @@ export async function runSingleStoryInit({
   return { success: true, result };
 }
 
-export function renderSingleStoryInitComment(result) {
-  const payload = {
-    storyId: result.storyId,
-    epicId: null,
-    standalone: true,
-    storyBranch: result.storyBranch,
-    baseBranch: result.baseBranch,
-    runScopedConfig: result.runScopedConfig,
-    worktreeEnabled: result.worktreeEnabled,
-    workCwd: result.workCwd,
-    worktreeCreated: result.worktreeCreated,
-    dependenciesInstalled: result.dependenciesInstalled,
-    installStatus: result.installStatus,
-    remoteVerified: result.remoteVerified,
-    remoteProbe: result.remoteProbe,
-  };
-  return [
-    '## Story init (standalone)',
-    '',
-    `- **standalone:** \`true\``,
-    `- **storyBranch:** \`${result.storyBranch}\``,
-    `- **baseBranch:** \`${result.baseBranch}\``,
-    `- **workCwd:** \`${result.workCwd}\``,
-    `- **worktreeEnabled:** \`${result.worktreeEnabled}\``,
-    `- **remoteVerified:** \`${result.remoteVerified}\``,
-    `- **dependenciesInstalled:** \`${result.dependenciesInstalled}\``,
-    '',
-    '```json',
-    JSON.stringify(payload, null, 2),
-    '```',
-    '',
-  ].join('\n');
-}
-
 runAsCli(import.meta.url, runSingleStoryInit, {
   source: 'single-story-init',
   usage: {

package/.agents/scripts/stories-wave-tick.js

@@ -107,6 +107,18 @@
  * deterministic config source (`delivery.deliverRunner.concurrencyCap`) and
  * one scheduling kernel with every `/mandrel-deliver` multi-Story invocation.
  *
+ * **The cap is clamped to 1 when worktree isolation resolves off** (Story
+ * #5357). Concurrent dispatch is safe only because each Story gets its own
+ * checkout; with isolation off every Story resolves to the same `workCwd`, so
+ * two workers contend for `HEAD` and one takes the branch from under the
+ * other — the #5339/#5340 web run, where both wave-1 workers were initialised
+ * into the same tree. The clamp reads `resolveWorktreeEnabled`'s result, so all
+ * three routes to off (`CLAUDE_CODE_REMOTE=true`, `AP_WORKTREE_ENABLED=false`,
+ * `delivery.worktreeIsolation.enabled: false`) are covered by construction. It
+ * is a safety floor rather than a preference, so it is the one case where an
+ * explicit `--concurrency` does NOT win — and `capPrecedence` names
+ * `worktree-clamp` as the winning source and carries the requested value.
+ *
  * Exit codes: 0 ok · 1 input error · 2 dependency cycle (`cycleError`) ·
  * 3 wedged (`wedged`) — ready is empty, nothing is in flight, and undone
  * Stories are waiting on blockers that are not done · 4 blocked (`blocked`) —
@@ -124,7 +136,13 @@ import { readFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
 
 import { runAsCli } from './lib/cli-utils.js';
-import { getPaths, getRunners, resolveConfig } from './lib/config-resolver.js';
+import {
+  getPaths,
+  getRunners,
+  getWorktreeIsolation,
+  resolveConfig,
+  resolveWorktreeEnabled,
+} from './lib/config-resolver.js';
 import { detectCycle } from './lib/Graph.js';
 import { Logger } from './lib/Logger.js';
 import { AGENT_LABELS } from './lib/label-constants.js';
@@ -206,6 +224,13 @@ Options:
                      WINS over the configured value, and the envelope's
                      capPrecedence records that it did — including when the
                      request exceeds the configured cap.
+                     ONE EXCEPTION: when worktree isolation resolves off
+                     (CLAUDE_CODE_REMOTE=true, AP_WORKTREE_ENABLED=false, or
+                     delivery.worktreeIsolation.enabled: false), the cap is
+                     clamped to 1 and the clamp outranks this flag — every
+                     Story would otherwise run in the same checkout and two
+                     workers would contend for HEAD. capPrecedence reports
+                     source "worktree-clamp" with the requested value.
   --done <csv>       Comma-separated Story IDs already completed this run.
                      Their dependents become eligible; they are never
                      re-dispatched. Defaults to empty.
@@ -638,6 +663,15 @@ export function parseInFlight(raw) {
   return { value: num, error: null };
 }
 
+/**
+ * The per-beat cap a run is clamped to when worktree isolation resolves off
+ * (Story #5357). `delivery.deliverRunner.concurrencyCap` is a throughput
+ * preference; this is a safety floor, so it outranks even an explicit
+ * `--concurrency`. Why the two are coupled, and why the clamp is never silent:
+ * ADR `20260917-5357` in `docs/decisions.md`.
+ */
+export const WORKTREE_DISABLED_CONCURRENCY_CAP = 1;
+
 /**
  * Validate a raw `--concurrency` value into a positive integer.
  *
@@ -675,7 +709,9 @@ export function parseConcurrencyOverride(raw) {
  * @param {object} [opts.config]    Pre-resolved config (injected by tests so
  *                                   they never depend on a real `.agentrc`).
  * @param {number} [opts.override]  Validated positive integer from
- *                                   `--concurrency`; wins over config.
+ *                                   `--concurrency`; wins over config, unless
+ *                                   the worktree-isolation floor clamps it.
+ * @param {NodeJS.ProcessEnv} [opts.env] Environment (test injection).
  * @returns {number} The resolved positive-integer concurrency cap.
  */
 export function resolveConcurrencyCap(opts = {}) {
@@ -702,44 +738,115 @@ export function resolveConcurrencyCap(opts = {}) {
  * safety limit, and refusing a deliberate operator escalation would trade a
  * silent override for a silent stall.
  *
+ * **The one exception (Story #5357).** When worktree isolation resolves off,
+ * the cap is clamped to {@link WORKTREE_DISABLED_CONCURRENCY_CAP} and the
+ * clamp outranks the flag. That is not a reversal of the paragraph above: the
+ * configured cap is a preference and a flag may outrank a preference, but a
+ * shared checkout is not a preference at all. Dispatching two workers into one
+ * working tree corrupts the run whatever number either source asked for, so
+ * the floor wins — loudly, per {@link resolveWorktreeClamp}.
+ *
  * @param {object} [opts]
  * @param {string} [opts.cwd]      Repo root for config resolution.
  * @param {object} [opts.config]   Pre-resolved config (test injection).
  * @param {number} [opts.override] Validated positive integer from
  *                                 `--concurrency`.
+ * @param {NodeJS.ProcessEnv} [opts.env] Environment the worktree-isolation
+ *                                 rules read (test injection).
  * @returns {{
  *   cap: number,
- *   source: 'flag'|'config',
+ *   source: 'flag'|'config'|'worktree-clamp',
  *   configuredCap: number,
  *   requestedCap: number|null,
  *   exceedsConfigured: boolean,
  *   note: string,
  * }}
  */
-export function resolveCapPrecedence({ cwd, config, override } = {}) {
+export function resolveCapPrecedence({ cwd, config, override, env } = {}) {
   const resolved = config ?? resolveConfig({ cwd });
   const { deliverRunner } = getRunners(resolved);
   const configuredCap = deliverRunner.concurrencyCap;
-  if (override == null) {
-    return {
-      cap: configuredCap,
-      source: 'config',
-      configuredCap,
-      requestedCap: null,
-      exceedsConfigured: false,
-      note: `cap ${configuredCap} from delivery.deliverRunner.concurrencyCap (no --concurrency given)`,
-    };
-  }
-  const exceedsConfigured = override > configuredCap;
+  const requested =
+    override == null
+      ? {
+          cap: configuredCap,
+          source: 'config',
+          configuredCap,
+          requestedCap: null,
+          exceedsConfigured: false,
+          note: `cap ${configuredCap} from delivery.deliverRunner.concurrencyCap (no --concurrency given)`,
+        }
+      : {
+          cap: override,
+          source: 'flag',
+          configuredCap,
+          requestedCap: override,
+          exceedsConfigured: override > configuredCap,
+          note:
+            override > configuredCap
+              ? `cap ${override} from --concurrency, which OVERRIDES and EXCEEDS the configured delivery.deliverRunner.concurrencyCap ${configuredCap} — this run is deliberately above the project default`
+              : `cap ${override} from --concurrency, which overrides the configured delivery.deliverRunner.concurrencyCap ${configuredCap}`,
+        };
+
+  return resolveWorktreeClamp({ requested, config: resolved, env });
+}
+
+/**
+ * Apply the worktree-isolation safety floor to an already-resolved precedence
+ * record (Story #5357).
+ *
+ * **Keyed off the resolved boolean, never one env var.** `CLAUDE_CODE_REMOTE`
+ * is only one of three routes to isolation-off — `AP_WORKTREE_ENABLED=false`
+ * and `delivery.worktreeIsolation.enabled: false` are the others and are
+ * exactly as unsafe — so this reads {@link resolveWorktreeEnabled}'s result and
+ * all three are covered by construction rather than by enumeration.
+ *
+ * **The config is normalised through `getWorktreeIsolation` first**, and that
+ * is load-bearing. `resolveWorktreeEnabled` reads
+ * `Boolean(config.delivery.worktreeIsolation.enabled)` raw, so a config that
+ * simply omits the block — every test-injected partial, and any consumer who
+ * never wrote one — reads `Boolean(undefined) === false` and would be clamped
+ * as though an operator had disabled isolation. `getWorktreeIsolation` applies
+ * the framework default (`enabled: true`) the same way `resolveConfig` does for
+ * a real `.agentrc`, so the clamp fires on a deliberate off, never on an
+ * absent key.
+ *
+ * The record is emitted whenever isolation is off, **including when the
+ * requested cap was already 1**: the point is that the run's sequentiality is
+ * always attributable to the reason that forced it, not left to coincide with
+ * a preference that happened to agree.
+ *
+ * @param {object} args
+ * @param {{cap: number, source: string, configuredCap: number, requestedCap: number|null, exceedsConfigured: boolean, note: string}} args.requested
+ *   The precedence record the flag-vs-config rules produced.
+ * @param {object|null} [args.config] Resolved config.
+ * @param {NodeJS.ProcessEnv} [args.env] Environment (test injection).
+ * @returns {typeof args.requested} The record unchanged when isolation is on,
+ *   or the clamped record naming `worktree-clamp` as the winning source.
+ */
+export function resolveWorktreeClamp({ requested, config, env } = {}) {
+  const worktreeEnabled = resolveWorktreeEnabled(
+    {
+      config: { delivery: { worktreeIsolation: getWorktreeIsolation(config) } },
+    },
+    env ?? process.env,
+  );
+  if (worktreeEnabled) return requested;
+
+  const from =
+    requested.source === 'flag'
+      ? '--concurrency'
+      : 'delivery.deliverRunner.concurrencyCap';
   return {
-    cap: override,
-    source: 'flag',
-    configuredCap,
-    requestedCap: override,
-    exceedsConfigured,
-    note: exceedsConfigured
-      ? `cap ${override} from --concurrency, which OVERRIDES and EXCEEDS the configured delivery.deliverRunner.concurrencyCap ${configuredCap} — this run is deliberately above the project default`
-      : `cap ${override} from --concurrency, which overrides the configured delivery.deliverRunner.concurrencyCap ${configuredCap}`,
+    cap: WORKTREE_DISABLED_CONCURRENCY_CAP,
+    source: 'worktree-clamp',
+    configuredCap: requested.configuredCap,
+    requestedCap: requested.cap,
+    // The run is at 1, so it is not above the project default whatever was
+    // asked for — the escalation never took effect and must not be reported
+    // as though it had.
+    exceedsConfigured: false,
+    note: `cap clamped to ${WORKTREE_DISABLED_CONCURRENCY_CAP} because worktree isolation resolved OFF — requested ${requested.cap} from ${from}. Concurrent dispatch shares one checkout without per-Story worktrees, so two workers would contend for HEAD; this floor outranks an explicit --concurrency.`,
   };
 }
 
@@ -1000,6 +1107,8 @@ export function detectWedge({ nodes, doneIds, ready, inFlight }) {
  * @param {string|number} [args.inFlight] Raw --in-flight count.
  * @param {string} [args.cwd]          Repo root for config resolution.
  * @param {object} [args.config]       Pre-resolved config (test injection).
+ * @param {NodeJS.ProcessEnv} [args.env] Environment the worktree-isolation
+ *                                     clamp reads (test injection).
  * @returns {{
  *   envelope: {kind: string, ready: number[], totalStories: number, concurrencyCap: number, inFlight: number, cycleError: string|null},
  *   exitCode: number
@@ -1013,6 +1122,7 @@ export function runStoriesWaveTick({
   inFlight,
   cwd,
   config,
+  env,
 } = {}) {
   // Validate the --concurrency override before resolving config so an invalid
   // value fails fast with exit code 1 regardless of DAG validity.
@@ -1033,7 +1143,7 @@ export function runStoriesWaveTick({
     return inputErrorResult(doneError, null, inFlightValue);
   }
 
-  const capPrecedence = resolveCapPrecedence({ cwd, config, override });
+  const capPrecedence = resolveCapPrecedence({ cwd, config, override, env });
   const concurrencyCap = capPrecedence.cap;
 
   let rawJson;
@@ -1099,6 +1209,10 @@ export function runStoriesWaveTick({
  *     the run-end signal for `plan-run-epilogue.js`.
  *   - `blocked` — ids carrying `agent::blocked` (Story #4601). Non-empty means
  *     the loop must END, not poll: see `BLOCKED_EXIT_CODE`.
+ *   - `stalledDispatch` — `--dispatched` ids live state still reports as
+ *     `agent::ready`. They stay withheld; the field exists so a caller keeping
+ *     an append-only dispatched list can see an id that is pinned rather than
+ *     merely initializing (Story #5363).
  *
  * @param {object} args
  * @param {string} args.stories        Raw `--stories` CSV of Story ids.
@@ -1107,9 +1221,14 @@ export function runStoriesWaveTick({
  *   has spawned but may not yet have observed labelled.
  * @param {string} [args.cwd]          Repo root for config resolution.
  * @param {object} [args.config]       Pre-resolved config (test injection).
+ * @param {NodeJS.ProcessEnv} [args.env] Environment the worktree-isolation
+ *   clamp reads (test injection).
  * @param {Function} [args.probe]      Probe seam (test injection).
  * @param {Function} [args.context]    Provider-context seam (test injection).
- * @returns {Promise<{ envelope: object, exitCode: number }>}
+ * @returns {Promise<{ envelope: object, exitCode: number, records: object[] }>}
+ *   `records` are the probed nodes (id, dependsOn, files, body, labels) — the
+ *   bodies this beat already fetched, handed to the caller beside the envelope
+ *   rather than serialized into it.
  */
 export async function runProbedStoriesWaveTick({
   stories,
@@ -1117,6 +1236,7 @@ export async function runProbedStoriesWaveTick({
   dispatched,
   cwd,
   config,
+  env,
   probe = probeLiveState,
   context = createProbeContext,
 } = {}) {
@@ -1141,7 +1261,7 @@ export async function runProbedStoriesWaveTick({
     return inputErrorResult(dispatchedError);
   }
 
-  const capPrecedence = resolveCapPrecedence({ cwd, config, override });
+  const capPrecedence = resolveCapPrecedence({ cwd, config, override, env });
   const concurrencyCap = capPrecedence.cap;
 
   let probed;
@@ -1171,6 +1291,7 @@ export async function runProbedStoriesWaveTick({
     doneIds,
     inFlight,
     blockedIds = [],
+    stalledDispatch = [],
     foreignHeld = [],
     inFlightRecords = [],
   } = probed;
@@ -1198,12 +1319,25 @@ export async function runProbedStoriesWaveTick({
       epilogueDue,
       blocked: blockedIds,
       blockedReason: blockedReasonFor(blockedIds),
+      // Ids the caller listed in `--dispatched` that live state still reports
+      // as `agent::ready`. Withheld as in flight (that is the flag's whole
+      // job) and named here, because the same reading covers a healthy init
+      // window and a spawn that died before init — and only the caller, who
+      // owns the dispatched list, can tell those apart (Story #5363).
+      stalledDispatch,
       // Stories another operator's lease holds — withheld from dispatch this
       // beat (folded into in-flight) and surfaced so the run can report
       // "#<id> held by @<holder>" instead of dispatching into an init refusal.
       foreignHeld,
       foreignHeldReason: foreignHeldReasonFor(foreignHeld),
     },
+    // The probed nodes, beside the envelope rather than inside it. The
+    // envelope is a list of ids by design — a Story body is several KB and has
+    // no business on stdout — but the probe has already fetched every body,
+    // and the one caller that needs them (`deliver-run.js`, building each
+    // ready Story's dispatch prompt from its declared `changes[]`) would
+    // otherwise re-fetch the whole set to read what this beat already holds.
+    records: nodes,
     // A blocked Story outranks the scheduler's own verdict — including a
     // wedge, whose named blockers are moot while a human owes a decision.
     // A cycle (2) does not yield: a self-referential DAG is a planning error

package/.agents/skills/core/gates-and-baselines/reference.md

@@ -19,7 +19,6 @@ file is the roster, the per-kind command table, and the procedure.
 | `arch-cycles.json` | `npm run check:arch` |
 | `cyclomatic.json` | `npm run check:cyclomatic` |
 | `context-budget.json` | `npm run check:context-budget` |
-| `workflow-citations.json` | `npm run check:workflow-citations` |
 | `agents-loc.csv` | `npm run baseline:agents-loc` |
 
 A refresh is **not** a regression entry — it tells the ratchet that the new

package/.agents/skills/skills.index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-09-06T12:59:23.069Z",
+  "generatedAt": "2026-09-17T13:37:08.250Z",
   "generator": "generate-skills-index.js@1",
   "skills": [
     {
@@ -52,16 +52,6 @@
       "allowedTools": null,
       "vendor": null
     },
-    {
-      "name": "scope-triage",
-      "tier": "core",
-      "category": "core",
-      "path": ".agents/skills/core/scope-triage/SKILL.md",
-      "description": "Optional split-advisory for `/mandrel-plan`. Under v2 there is no epic|story routing verdict — `/mandrel-plan` always authors Stories. Use this skill only when judging whether a draft should stay one Story or legitimately split (near-zero overlap or an architectural seam).",
-      "policyCapsuleBullets": 5,
-      "allowedTools": null,
-      "vendor": null
-    },
     {
       "name": "security-and-hardening",
       "tier": "core",
@@ -97,7 +87,7 @@
       "tier": "stack",
       "category": "qa",
       "path": ".agents/skills/stack/qa/playwright/SKILL.md",
-      "description": "Robust E2E browser testing with Playwright. Use when writing browser-driven tests — leverage auto-waiting (no `waitForTimeout`), prefer user-visible locators (`getByRole`, `getByText`, `getByLabel`) over CSS/XPath, reuse `storageState` for auth, and enable trace-on-first-retry for CI debugging.",
+      "description": "Robust E2E browser testing with Playwright. Use when writing browser-driven tests — leverage auto-waiting (no `waitForTimeout`), prefer user-visible locators (`getByRole`, `getByText`, `getByLabel`) over CSS/XPath, reuse `storageState` for auth, and enable trace-on-first-retry for CI debugging. Also carries the `data-testid` contract a UI change states in its acceptance criteria.",
       "policyCapsuleBullets": 8,
       "allowedTools": null,
       "vendor": "playwright"

package/.agents/skills/stack/qa/playwright/SKILL.md

@@ -5,6 +5,8 @@ description:
   tests — leverage auto-waiting (no `waitForTimeout`), prefer user-visible
   locators (`getByRole`, `getByText`, `getByLabel`) over CSS/XPath, reuse
   `storageState` for auth, and enable trace-on-first-retry for CI debugging.
+  Also carries the `data-testid` contract a UI change states in its acceptance
+  criteria.
 vendor: playwright
 ---
 
@@ -21,6 +23,30 @@ vendor: playwright
 - Use a unique data set per test run, or tear down state explicitly, to prevent cross-test contamination.
 - Never let Playwright own the lifetime of a dev server it did not start: boot the server out-of-band, point the suite at the running origin, and set `reuseExistingServer` so `webServer` only probes readiness.
 
+## The testid contract
+
+A `data-testid` is a selector two artifacts share: the component that renders
+it and the spec that queries it. Renaming one without the other is a silent
+break — the suite still compiles, and the failure arrives as a missing element
+at run time, in CI, attributed to whichever change happened to land next.
+
+So a change touching UI (`*.tsx`, `*.astro`, `*.svelte`, `*.vue`, a components
+folder) states which side of that contract it is on, in its own acceptance
+criteria, as one of:
+
+- **`data-testid invariance: <the testids that MUST be preserved>`** — the
+  change reshapes markup and renames nothing, and the list says what the
+  reshape may not touch.
+- **`data-testid changes: <old> -> <new>, with the matching
+  tests/e2e/*.spec.ts selector updated`** — the rename is deliberate, and the
+  spec file that queries it is edited in the same change (or in one ordered
+  ahead of it, when the work is split).
+
+Renaming a testid without the matching spec edit is forbidden either way. When
+a change deliberately renames nothing, say so in its negative-scope prose too:
+a preserved set stated only once reads as an omission the next author is free
+to revise.
+
 ## Running a `webServer`-backed suite outside CI
 
 Playwright's `webServer` block **watches the process it spawned**. That

package/.agents/workflows/audit-to-stories.md

@@ -152,15 +152,17 @@ node .agents/scripts/audit-to-stories.js --emit-plan-seed \
 
 The seed renders the canonical one-pager sections — Problem Statement,
 Recommended Direction, Key Assumptions (with links to every source
-report), MVP Scope (the M proposed Stories), Key Files (so `/mandrel-plan`'s
-authoring step has concrete anchors), Grouping, Not Doing.
-
-**Grouping is the container-Epic directive.** Above 2 proposed Stories the
-seed instructs `/mandrel-plan` to group them under one Epic — a sweep is the
-clearest case for a container, since every Story shares a provenance and an
-operator usually delivers them together. It is a directive in the text, not an
-automatic write: Phase 4 above is where an operator declines it. Below the
-threshold the section says so and asks for nothing.
+report), MVP Scope (**the findings, flat**), Key Files (so `/mandrel-plan`'s
+authoring step has concrete anchors), Not Doing.
+
+**The seed states findings, not a partition.** MVP Scope used
+to render one numbered bullet per group beneath a `## Grouping` container
+directive — a plan the seed had already decided, at the grouping grain, before
+`/mandrel-plan` read a word of it. N now reaches the planner **undecided**: it
+applies its own cohesion judgment, and container grouping is `/mandrel-plan`'s
+Gate #3 call at persist, where N is known. The grouping still drives the
+**standalone-Stories** path (Phase 5b), which needs one issue payload per
+group.
 
 Chain into the existing planning entrypoint:
 
@@ -172,9 +174,10 @@ Chain into the existing planning entrypoint:
 then runs its author → persist path, as documented in its workflow.
 
 **Dedup provenance is carried mechanically — do not hand-copy it.** The seed's
-MVP Scope bullets carry each group's `audit-fingerprints` and
+MVP Scope section carries each group's `audit-fingerprints` and
 `audit-semantic-keys` footers as HTML comments (invisible in the rendered
-one-pager). `plan-persist` harvests them out of the seed on the
+one-pager, and per-group even though the visible list is flat — they are the
+identity the next sweep matches on). `plan-persist` harvests them out of the seed on the
 `plan-context.json` envelope and appends them to **every** Story body it
 persists, via `carryProvenanceFooters`
 ([`lib/findings/route-finding.js`](../scripts/lib/findings/route-finding.js)).