mandrel 2.59.0 → 2.60.0

package/.agents/scripts/lib/orchestration/ticketing/reads.js

@@ -77,20 +77,19 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   'follow-ups',
   // v2 plan-run epilogue artifacts (posted on the primary Story)
   'plan-run-audit-roster',
-  'plan-run-sibling-coherence',
   'epic-run-state',
   'epic-run-progress',
   'epic-plan-state',
   // `parked-follow-ons` retired in Story #5114 with the module that was its
-  // only writer. A kind the reader still recognises but nothing emits is the
-  // same dead wiring in a new place.
+  // only writer, and `plan-run-sibling-coherence` in Story #5341 with the
+  // epilogue step that was its. Story #5367 retired two more on the same
+  // rule: `story-init` (its write went away in #5343 — the receipt is read
+  // off disk now) and `model-attribution` (its writer went with the per-Task
+  // progress writer in #3157, and its reader modules are deleted). A kind the
+  // reader still recognises but nothing emits is the same dead wiring in a
+  // new place.
   // Story #566 — per-phase wall-clock summary posted by single-story-close.js.
   'phase-timings',
-  // Story #831 — story-init upserts a `story-init` comment that
-  // surfaces `dependenciesInstalled` (and the underlying installStatus) so
-  // downstream workflow steps don't have to infer install state from
-  // node_modules presence.
-  'story-init',
   // Story #2128 — Phase 6 Epic Clarity Gate (CLI retired). Historical
   // `clarity-gate-update` comments may still exist on older tickets.
   'clarity-gate-update',
@@ -100,16 +99,6 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // operator can correct drift before Phase 8 decomposes from a stale
   // spec. Advisory: the run continues regardless of the report contents.
   'spec-freshness',
-  // Story #2813 — the per-Task progress writer (since retired under
-  // #3157) upserted a `model-attribution` comment on a Task ticket at
-  // the moment it transitioned to `agent::executing`, recording which
-  // Claude model was actively executing the work. One entry per Task
-  // (upsert is idempotent across resume re-runs). Story- and Epic-level
-  // rollups are computed at query time by `rollupModelAttribution` in
-  // `lib/orchestration/model-attribution.js` — no Story/Epic-scope
-  // emissions are written. Schema:
-  // `.agents/schemas/model-attribution.schema.json`.
-  'model-attribution',
   // Story #2894 — `finalize/post-handoff-comment.js` upserts an
   // `epic-handoff` comment on the Epic at the end of the bus-owned
   // finalize flow (after `open-or-locate-pr`
@@ -157,13 +146,13 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // `graduator="<name>"` attr so independent graduators do not clobber each
   // other's comment; re-runs upsert in place.
   'cross-repo-deferred',
-  // Epic #4474 (PR3) / v2 Stage 3 — `plan-persist.js` upserts a single
-  // `plan-summary` comment on the primary Story at terminal persist
-  // success, carrying risk / routing receipts and the depends_on order
-  // table. One entry per plan; a re-persist upserts in place.
-  'plan-summary',
-  // v2 Stage 3 — flat Story persist checkpoint on every created Story
-  // (replaces epic-plan-state for new plans). plan-summary stays primary-only.
+  // v2 Stage 3 — the flat Story persist comment on every created Story
+  // (replaces epic-plan-state for new plans). Since Story #5343 it is the
+  // ONLY comment persist posts: the primary-Story-only `plan-summary` marker
+  // was retired and its content — story set, delivery order, deliver command
+  // — rides this marker on every Story. Story #5367 deleted the machine
+  // checkpoint that used to lead the body; the marker remains, and it is what
+  // makes a re-persist upsert in place.
   'story-plan-state',
   // Story #4535 — `plan-persist.js` upserts a `superseded-by` comment on
   // each `/mandrel-plan --tickets` source issue at persist time, naming the single

package/.agents/scripts/lib/story-body/body-format-lints.js

@@ -22,7 +22,10 @@
  *
  * Story #5312 deleted the `verify-tier-suffix` / `verify-manual-reason` lints
  * with the tier suffix itself: a `verify[]` entry is any command, and the
- * `manual:<reason>` escape is gone with the rule it escaped.
+ * `manual:<reason>` escape is gone with the rule it escaped. Story #5342
+ * deleted `verify-non-empty`: an empty `verify[]` is a dry-run warning, not a
+ * refusal, so it is no longer a rejecting lint — this registry carries only
+ * the rules that still refuse.
  *
  * Import hygiene: this module imports only the cycle-free
  * `file-assumption-enum.js` leaf. It must NOT import `story-body.js` or
@@ -40,6 +43,53 @@ import { FILE_ASSUMPTION_VALUES } from '../orchestration/file-assumption-enum.js
  */
 const DEFAULT_SUGGESTED_ASSUMPTION = 'refactors-existing';
 
+/**
+ * The bare-path bullet grammar (Story #5342, widened by Story #5361) — the
+ * **one** definition of what a `## Changes` / `## References` bullet has to
+ * look like to be a path rather than prose.
+ *
+ * It lives here, in the cycle-free lint leaf, because two consumers need the
+ * identical judgment and neither may import the other: the story-body parser
+ * (`story-body.js#parsePathEntry`) and the persist repair pass
+ * (`plan-persist/changes-repair.js`). They carried a copy each, and the
+ * copies drifted.
+ *
+ * A bullet is a path when it is a single token git could track: any run of
+ * non-whitespace, optionally wrapped in a matched pair of backticks. That
+ * admits the shapes the earlier `[\w@*-]*[/.][\w@./*-]+` class refused
+ * outright — route-segment paths (`app/[slug]/page.tsx`,
+ * `app/(marketing)/page.tsx`, `src/routes/$id.svelte`) and extensionless
+ * top-level files (`Makefile`) — while still refusing prose, since
+ * whitespace is the one thing that reliably marks a sentence.
+ */
+const BARE_PATH_TOKEN_RE = /^(?:`([^\s`]+)`|([^\s`]+))$/;
+
+/**
+ * Read the bare path token out of a bullet, or `null` when the bullet is not
+ * one single token.
+ *
+ * @param {unknown} raw
+ * @returns {string|null} The path, with any wrapping backticks peeled.
+ */
+export function matchBarePathToken(raw) {
+  if (typeof raw !== 'string') return null;
+  const match = raw.trim().match(BARE_PATH_TOKEN_RE);
+  return match ? (match[1] ?? match[2]) : null;
+}
+
+/**
+ * Whether a rejected bullet is prose — it carries whitespace, so no path
+ * grammar could ever have admitted it. The counterpart failure is a
+ * single token that still names no usable path; the two get different
+ * refusals because they need different fixes.
+ *
+ * @param {unknown} raw
+ * @returns {boolean}
+ */
+export function isProseBullet(raw) {
+  return typeof raw === 'string' && /\s/.test(raw.trim());
+}
+
 // A token that looks like a file path / glob / module id: it carries a `/` or a
 // `.`-separated segment. Deliberately loose — the suggestion is best-effort, and
 // a false positive only produces an unhelpful (still-valid) fix-it string.
@@ -114,10 +164,13 @@ export const BODY_FORMAT_LINTS = Object.freeze([
   {
     id: 'changes-path-entry-shape',
     summary:
-      'Every `## Changes` / `## References` bullet MUST be a `{ path, assumption }` object (assumption ∈ ' +
-      `${FILE_ASSUMPTION_VALUES.join(' | ')}); plain path strings are rejected.`,
-    badExample: '- src/app.js',
-    goodExample: '- {"path": "src/app.js", "assumption": "refactors-existing"}',
+      'Every `## Changes` / `## References` bullet MUST name a path — a bare ' +
+      'path string is the default form and persist derives its assumption by ' +
+      'probing the base branch. Use the `{ path, assumption }` object ' +
+      `(assumption ∈ ${FILE_ASSUMPTION_VALUES.join(' | ')}) only to pin one ` +
+      'yourself; `deletes` always needs it. Prose bullets are rejected.',
+    badExample: '- the routing module and its tests',
+    goodExample: '- src/app.js',
     autoFixable: true,
   },
   {
@@ -127,13 +180,6 @@ export const BODY_FORMAT_LINTS = Object.freeze([
     goodExample: '- {"path": "src/app.js", "assumption": "creates"}',
     autoFixable: false,
   },
-  {
-    id: 'verify-non-empty',
-    summary: 'A Story MUST list at least one `verify[]` entry.',
-    badExample: '"verify": []',
-    goodExample: '"verify": ["npm run validate"]',
-    autoFixable: false,
-  },
   {
     id: 'acceptance-non-empty',
     summary:

package/.agents/scripts/lib/story-body/story-body.js

@@ -41,7 +41,11 @@
  */
 
 import { FILE_ASSUMPTION_VALUES } from '../orchestration/file-assumption-enum.js';
-import { suggestPathEntryFix } from './body-format-lints.js';
+import {
+  isProseBullet,
+  matchBarePathToken,
+  suggestPathEntryFix,
+} from './body-format-lints.js';
 import { isFooterSeparator, parseFooterBlockedByRefs } from './footer-block.js';
 
 // ---------------------------------------------------------------------------
@@ -161,6 +165,14 @@ function stripListMarker(line) {
 // issue bodies are never rewritten).
 const HUMANIZED_PATH_ENTRY_RE = /^`([^`]+)`\s+—\s+(\S+)$/;
 
+// Bare path bullet (Story #5342): `src/app.js` or `` `src/app.js` `` with no
+// assumption. The assumption is a fact about the base branch, not a thing the
+// author knows better than a probe does, so the default authored form omits
+// it and persist derives it. The grammar itself — a single whitespace-free
+// token, so prose bullets do not match and are still rejected — is
+// `body-format-lints.js#matchBarePathToken`, the one definition the persist
+// repair pass scores against too (Story #5361).
+
 // AC-<n> presentation prefix on acceptance checkboxes (Story #4600). The
 // numbering is a stable 1-based human handle only — parse() strips it so the
 // top-level acceptance[] machine contract round-trips byte-identical.
@@ -189,8 +201,10 @@ const META_BLOCK_RE = /<!--\s*meta:[\s\S]*?-->/;
 /**
  * Parse a single `changes` / `references` bullet into a `PathEntry`.
  *
- * Accepted markdown shapes (both parsed indefinitely — live issue bodies
+ * Accepted markdown shapes (all parsed indefinitely — live issue bodies
  * are never rewritten):
+ *   - Bare path (the default authored form since Story #5342):
+ *     `` `src/x.js` `` or `src/x.js`, parsed with `assumption: null`
  *   - Humanized bullet (canonical serialize() output since Story #4600):
  *     `` `src/x.js` — refactors-existing ``
  *   - Legacy inline-JSON object bullet:
@@ -209,18 +223,65 @@ function parsePathEntry(raw, warnings) {
     return pathEntryFromObject(raw);
   }
 
-  const str = typeof raw === 'string' ? raw.trim() : String(raw).trim();
+  const str = String(raw).trim();
   if (str.length === 0) return null;
 
   const entry = pathEntryFromHumanized(str) ?? pathEntryFromInlineJson(str);
   if (entry) return entry;
+  return pathEntryFromBare(str);
+}
+
+/**
+ * Parse the bare path bullet — the default authored form since Story #5342 —
+ * or refuse the bullet. This is the last shape `parsePathEntry` tries, so it
+ * owns the rejection too.
+ *
+ * `assumption: null` records only what the author said; persist derives the
+ * rest by probing the base branch. A `{`-leading string reached here because
+ * it failed to parse as the inline JSON object it announced itself as, so it
+ * is malformed JSON rather than a path and keeps failing closed.
+ *
+ * Story #5361: the two failures need different fixes, so they get different
+ * refusals — rewrite a sentence as a path, versus fix a token that is not one.
+ *
+ * @param {string} str
+ * @returns {PathEntry}
+ */
+function pathEntryFromBare(str) {
+  const bare = str.startsWith('{') ? null : matchBarePathToken(str);
+  if (bare !== null) return { path: bare, assumption: null };
 
+  const shape = isProseBullet(str)
+    ? 'is prose, not a path'
+    : 'names no usable path';
   throw new StoryBodyParseError(
-    `changes/references entry must be a { path, assumption } object; plain string bullets are no longer accepted: ${str.slice(0, 120)}${pathEntryFixIt(str)}`,
+    `changes/references entry ${shape} — a bullet must be a single ` +
+      `whitespace-free path token, or a { path, assumption } object: ` +
+      `${str.slice(0, 120)}${pathEntryFixIt(str)}`,
     { field: 'changes', raw: str },
   );
 }
 
+/**
+ * Read the assumption a raw entry declares, collapsing the three cases the
+ * parser has to tell apart into one value:
+ *
+ *   - a canonical `FILE_ASSUMPTION_VALUES` member — the author pinned one;
+ *   - `null` — the author named no assumption at all. Since Story #5342 that
+ *     is the **bare form**, and persist derives the value by probing the base
+ *     branch rather than the author guessing it;
+ *   - `undefined` — the author named something that is not an assumption.
+ *     Distinct from absent on purpose: a typo must fail closed where an
+ *     omission is the default shape.
+ *
+ * @param {unknown} raw
+ * @returns {string|null|undefined}
+ */
+function readAssumption(raw) {
+  if (FILE_ASSUMPTION_VALUES.includes(raw)) return raw;
+  return raw == null ? null : undefined;
+}
+
 /**
  * Validate an already-structured `{ path, assumption }` object. Fails closed
  * on a malformed object.
@@ -229,12 +290,10 @@ function parsePathEntry(raw, warnings) {
  * @returns {PathEntry}
  */
 function pathEntryFromObject(raw) {
-  if (
-    typeof raw.path === 'string' &&
-    raw.path.trim().length > 0 &&
-    FILE_ASSUMPTION_VALUES.includes(raw.assumption)
-  ) {
-    return { path: raw.path.trim(), assumption: raw.assumption };
+  const path = typeof raw.path === 'string' ? raw.path.trim() : '';
+  const assumption = readAssumption(raw.assumption);
+  if (path !== '' && assumption !== undefined) {
+    return { path, assumption };
   }
   // Malformed object: fail closed.
   throw new StoryBodyParseError(
@@ -270,8 +329,9 @@ function pathEntryFromHumanized(str) {
  * Parse the legacy inline-JSON object bullet:
  * `{ "path": "...", "assumption": "..." }`. Returns `null` when the line is
  * not a JSON object at all (including a JSON parse failure — the caller then
- * rejects the plain-string form); fails closed when it parses to an object
- * without valid PathEntry fields.
+ * tries the bare-path form and finally rejects the bullet); delegates the
+ * field check to {@link pathEntryFromObject}, which is the same judgment on
+ * the same shape and fails closed the same way.
  *
  * @param {string} str
  * @returns {PathEntry|null}
@@ -282,21 +342,12 @@ function pathEntryFromInlineJson(str) {
   try {
     parsed = JSON.parse(str);
   } catch {
-    // JSON parse failed — the caller rejects the plain-string form.
+    // JSON parse failed — the caller falls through to the bare-path form.
     return null;
   }
-  if (typeof parsed !== 'object' || parsed === null) return null;
-  if (
-    typeof parsed.path === 'string' &&
-    FILE_ASSUMPTION_VALUES.includes(parsed.assumption)
-  ) {
-    return { path: parsed.path.trim(), assumption: parsed.assumption };
-  }
-  // Parsed successfully as JSON object but has invalid fields — fail closed.
-  throw new StoryBodyParseError(
-    `changes/references entry is a JSON object but not a valid PathEntry: ${str}`,
-    { field: 'changes', raw: str },
-  );
+  return parsed !== null && typeof parsed === 'object'
+    ? pathEntryFromObject(parsed)
+    : null;
 }
 
 /**
@@ -789,10 +840,13 @@ const STRUCTURED_FIELD_NORMALIZERS = {
  */
 function serializePathEntry(entry) {
   if (typeof entry === 'string') return entry;
-  // Canonical object form (Story #4600): render as a human-readable bullet —
-  // path in backticks, em-dash, assumption. parsePathEntry recognizes this
-  // shape (and the legacy inline-JSON shape) for round-trip fidelity.
-  return `\`${entry.path}\` — ${entry.assumption}`;
+  // Canonical object form (Story #4600): a human-readable bullet — path in
+  // backticks, em-dash, assumption. parsePathEntry recognizes this shape (and
+  // the legacy inline-JSON one) for round-trip fidelity. Story #5342: a bare
+  // entry — a path the author wrote with no assumption — serializes back bare
+  // rather than silently acquiring a derivation they never made; persist
+  // fills it in by probing base before it writes a body.
+  return [`\`${entry.path}\``, entry.assumption].filter(Boolean).join(' — ');
 }
 
 /**

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -117,7 +117,8 @@ The **persisted** \`body\` renders these markdown sections (in order) — you au
     <optional technical approach at contract level — do NOT restate Goal / Acceptance / Verify>
 
     ## Changes
-    - {"path": "<file path>", "assumption": "creates" | "refactors-existing" | "deletes"}
+    - <file path>
+    - {"path": "<file path>", "assumption": "deletes"}
     - ...
 
     ## Acceptance          <-- synthesized by persist from acceptance[]; do not author
@@ -137,9 +138,9 @@ The **persisted** \`body\` renders these markdown sections (in order) — you au
 - **goal** (in body string): One sentence stating WHY this Story exists.
 - **spec** (optional, in body string as \`## Spec\`): The technical approach at the altitude the SPEC PROSE CONTRACT below fixes — contract and invariants, never implementation narration. Write as much as the work needs and no more; persist keeps Specs inline at any length and never writes them under \`docs/\`.
 - **slicing** (optional): Ordered intra-session checkpoints for one Story, one line each. A checkpoint is a **stage of the work** — a commit boundary the deliverer passes through inside one session, stated as the step it performs. An acceptance item is a **state of the codebase** a PR reviewer confirms once the Story has landed. The same Story therefore carries both: the checkpoints say in what order it is built, \`acceptance[]\` says what must then be true. Never a fan-out table, never a second acceptance list, and never sibling tickets — a broad sweep with many stages is still one Story, sliced here.
-- **changes** (in body string): Each entry is an object \`{ path, assumption }\` where \`assumption\` is one of \`creates | refactors-existing | deletes\`. **Name the files the deliverer authors, and omit generated artifacts** — quality baselines, generated test indexes, migration journals, lockfiles and the like are regenerated by the work itself, the refresh is a close-gate concern, and declaring one needlessly reserves a footprint that serializes sibling Stories at dispatch. Acceptable path shapes include explicit files (\`src/components/Foo.tsx\`), glob patterns (\`tests/e2e/*.spec.ts\`, \`**/*.astro\`), and module identifiers that resolve to files. Use \`refactors-existing\` for in-place edits to a file already on \`main\`; \`creates\` for net-new files; \`deletes\` for removals. Persist probes every path against the base branch and repairs a plain-string bullet or a trailing parenthetical into the object form for you; a \`creates\` on an existing path or a \`refactors-existing\` on an absent one is a dry-run warning, and only a \`deletes\` naming an absent path is refused.
+- **changes** (in body string): Each entry is a **bare path string** — the default form; persist derives its assumption by probing the base branch and reports the derivation. Use the object form \`{ path, assumption }\` (\`assumption\` one of \`creates | refactors-existing | deletes\`) only to pin one yourself, and always for a \`deletes\`, which a bare path can never express. **Name the files the deliverer authors, and omit generated artifacts** — quality baselines, generated test indexes, migration journals, lockfiles and the like are regenerated by the work itself, the refresh is a close-gate concern, and declaring one needlessly reserves a footprint that serializes sibling Stories at dispatch. Acceptable path shapes include explicit files (\`src/components/Foo.tsx\`), glob patterns (\`tests/e2e/*.spec.ts\`, \`**/*.astro\`), and module identifiers that resolve to files. Pin \`refactors-existing\` for an in-place edit, \`creates\` for a net-new file, \`deletes\` for a removal, whenever the probe would get it wrong. Persist probes every path against the base branch and derives the assumption for you, so a \`creates\` on an existing path or a \`refactors-existing\` on an absent one is a dry-run warning; only a \`deletes\` naming an absent path is refused.
 - **acceptance** (top-level array on the ticket object): Each item is an **outcome a PR reviewer can confirm from the diff and the verify output** — what is true of the codebase once the Story lands, stated at the altitude of the capability (a command that now exits 0 against a named input, a behavior a named test now asserts, a config that now fails validation on a retired key, a document that now records a decision). State as many outcomes as the capability has and no more — the list has no target, floor or ceiling, and a long one is never a reason to split the Story. Push grep-shaped probes, file-exists checks and exit-code tests down into \`verify[]\`; never pin an internal helper name or a private file path into an acceptance item the advisory \`changes[]\` is free to reshape. UNACCEPTABLE: "verify by reading the diff", "looks good", "matches the spec".
-- **verify** (top-level array on the ticket object): The **mechanical checks** — exact commands or test paths the deliverer runs and the acceptance critic consumes as evidence: \`node --test tests/x.test.js\`, \`npm run lint\`, \`npm run validate\`, a scoped grep. Every acceptance item should be confirmable from at least one verify entry's output plus the diff. Stories with zero verify entries fail validation.
+- **verify** (top-level array on the ticket object): The **mechanical checks** — exact commands or test paths the deliverer runs and the acceptance critic consumes as evidence: \`node --test tests/x.test.js\`, \`npm run lint\`, \`npm run validate\`, a scoped grep. Every acceptance item should be confirmable from at least one verify entry's output plus the diff. A Story with no verify entry is warned about, not rejected — but the critic then has nothing to read as evidence, so author the commands.
 - **Bodies record decisions, never questions to the operator.** Never persist an open question ("Flag if…", "TBD", "confirm with the operator") into a Story body — the executing sub-agent is non-interactive and cannot answer it, and the dry-run warns on every one it finds. Triage each unknown by who can resolve it: an AFK-shaped unknown (a fact in docs, a third-party API surface, observable repo behavior) MUST be resolved by your own research before authoring — never restated as an assumption; only a HITL-shaped unknown (a genuine product or architecture call the operator owns) may be restated as a declarative Key Assumption the agent can act on, stating the default chosen (a decision-made-by-default).
 - **non_goals** (OPTIONAL, in body string as the \`## Non-Goals\` section): A short list of capabilities or changes this Story explicitly does NOT deliver — an advisory negative-scope bound that fences the executing agent away from adjacent work. It is **advisory and NON-GATING**: the validator does not require, count, or reject on it, and an absent or empty section renders nothing. Use the EXACT single-word hyphenated heading spelling \`## Non-Goals\` (a space-separated heading like \`## Out of Scope\` is NOT recognized by the parser and will be dropped). Reach for it when a Story's negative boundary is non-obvious from its \`acceptance[]\` alone; omit it otherwise.
 
@@ -180,19 +181,10 @@ ${envelopeFloor}
 - **A remediation sweep over one subsystem is one Story.** A batch of findings in the same subsystem shares one reason to exist — the subsystem is wrong — so it arrives as one Story whose \`## Slicing\` checkpoints carry the stages, not as one Story per finding.
 - ${singleConsumerRule}
 
-#### UI / TESTID INVARIANCE (per CLAUDE.md safety rule):
+#### UI AND COPY WORK — where the contract is written down:
 
-Every \`changes[]\` entry is a \`{ path, assumption }\` object — a prose bullet there is rejected by the parser, so the testid contract is carried where prose belongs:
-
-- Stories that touch UI (\`*.tsx\`, \`*.astro\`, \`*.svelte\`, \`*.vue\`, components folders) MUST carry the testid contract as a top-level \`acceptance[]\` item, one of:
-  - \`"data-testid invariance: <list of testids that MUST be preserved>"\`, or
-  - \`"data-testid changes: <old> -> <new>, with the matching tests/e2e/*.spec.ts selector updated"\` — paired with that \`tests/e2e/*.spec.ts\` file in \`changes[]\`, in the same Story or a depends_on Story.
-- State the preserved-testid set in \`## Non-Goals\` prose as well when the Story deliberately renames nothing.
-- Renaming a testid without the matching e2e edit is FORBIDDEN.
-
-#### BRAND / COPY / STYLE WORK:
-
-- Stories that touch user-visible copy, brand assets, or visual style MUST cite the relevant section of \`docs/style-guide.md\` in \`acceptance\` (e.g. \`"acceptance": ["Hero copy matches docs/style-guide.md §3 (voice & tone)"]\`). If \`docs/style-guide.md\` does not exist or has no relevant section, state that explicitly: \`"acceptance": ["docs/style-guide.md absent — copy reviewed against the inline brand brief in the plan seed"]\`. Silence on style sourcing is a smell.
+- A Story touching UI (\`*.tsx\`, \`*.astro\`, \`*.svelte\`, \`*.vue\`, a components folder) states the \`data-testid\` contract in \`acceptance[]\` per the testid contract in \`.agents/skills/stack/qa/playwright/SKILL.md\`.
+- A Story touching user-visible copy, brand assets or visual style cites the relevant section of \`docs/style-guide.md\` in \`acceptance[]\` when that file exists.
 
 CRITICAL: Dependencies should follow execution blockers. There is no parent ticket — never emit a 'parent_slug' field.
 IMPORTANT DEPENDENCY RULE: Story-to-Story dependencies are expressed via \`depends_on\` (one Story depends_on another Story's slug). Use this to express execution ordering across the plan.

package/.agents/scripts/lib/wave-runner/live-probe.js

@@ -101,22 +101,37 @@ import { classifyStory, storyIdOf } from './ready-set.js';
  * Ids outside the probed set are ignored: they are not part of this run and
  * must not consume its cap.
  *
+ * The second arm is also reported on its own, as `unlabelled`. A claimed id
+ * that still reads `agent::ready` is in flight either because its init is
+ * still running or because the spawn that claimed it never started one, and
+ * those two are indistinguishable here — but only the second pins the id in
+ * the caller's ledger forever. Live state cannot tell them apart; the operator
+ * can, so the fact is surfaced rather than acted on (Story #5363).
+ *
  * @param {Array<{id?: number, number?: number, labels?: string[], state?: string}>} storyRecords
  * @param {Iterable<number>} [dispatched] Ids the host has spawned.
- * @returns {Set<number>} In-flight Story ids.
+ * @returns {{inFlight: Set<number>, unlabelled: Set<number>}} In-flight Story
+ *   ids, and the subset of them claimed by the caller that live state still
+ *   reports as `agent::ready`.
  */
 function deriveInFlightIds(storyRecords, dispatched = []) {
   const claimed = new Set(dispatched);
-  const inFlight = new Set();
+  // Bucketed by live class rather than tested twice. The admission rule is
+  // unchanged; it is only that the `ready` bucket IS the claimed-but-unlabelled
+  // set, since `ready` is the one class the rule admits on the caller's claim.
+  const byClass = { executing: new Set(), ready: new Set() };
   for (const rec of storyRecords) {
     const id = storyIdOf(rec);
     if (id === null) continue;
     const cls = classifyStory(rec);
     if (cls === 'executing' || (claimed.has(id) && cls === 'ready')) {
-      inFlight.add(id);
+      byClass[cls].add(id);
     }
   }
-  return inFlight;
+  return {
+    inFlight: new Set([...byClass.executing, ...byClass.ready]),
+    unlabelled: byClass.ready,
+  };
 }
 
 /**
@@ -251,6 +266,7 @@ export function createProbeContext({
  *   doneIds: Set<number>,
  *   inFlight: number,
  *   blockedIds: number[],
+ *   stalledDispatch: number[],
  *   foreignHeld: Array<{id: number, holder: string}>
  * }>}
  */
@@ -294,7 +310,10 @@ export async function probeLiveState({
   // They are consumed in-process by `planReadySet` and never serialized into
   // the beat envelope, which stays a list of ids.
   const bodyById = new Map(stories.map((s) => [s.id, s.body ?? '']));
-  const inFlightIds = deriveInFlightIds(stories, dispatched);
+  const { inFlight: inFlightIds, unlabelled } = deriveInFlightIds(
+    stories,
+    dispatched,
+  );
   // A Story another operator's lease holds occupies a (global) dispatch slot
   // just like an in-flight one: fold it into the in-flight set so it is both
   // withheld (via the projected label) and excluded from a false wedge, but
@@ -322,6 +341,13 @@ export async function probeLiveState({
     doneIds: new Set(envelope.done),
     inFlight: inFlightIds.size,
     blockedIds: deriveBlockedIds(stories),
+    // Claimed by the caller, still labelled `agent::ready`: a live init window
+    // or a spawn that never reached one. Reported, never released here. A
+    // foreign lease is its own withhold reason and outranks the claim, so it
+    // is subtracted — one Story must not carry two recoveries.
+    stalledDispatch: [...unlabelled]
+      .filter((id) => !foreignHeld.has(id))
+      .sort((a, b) => a - b),
     foreignHeld: [...foreignHeld].map(([id, holder]) => ({ id, holder })),
   };
 }

package/.agents/scripts/merge-baseline.js

@@ -36,9 +36,8 @@
  *
  * ## Not every `baselines/*.json` is an envelope
  *
- * That glob also matches arch-cycles, cyclomatic, dead-exports, audit-ledger,
- * context-budget and workflow-citations — files with their own shapes and no
- * row identity. Anything whose `$schema` is not a known per-kind envelope is
+ * That glob also matches arch-cycles, cyclomatic, dead-exports, audit-ledger
+ * and context-budget — files with their own shapes and no row identity. Anything whose `$schema` is not a known per-kind envelope is
  * handed straight back to `git merge-file`, so registering the driver cannot
  * change their behaviour.
  */
@@ -164,8 +163,8 @@ function delegateToGit(basePath, oursPath, theirsPath) {
  *     `git merge-file` even though `.gitattributes` routes them here, so the
  *     attribute promised a row merge the driver never performed.
  *
- * Anything else — arch-cycles, audit-ledger, context-budget,
- * workflow-citations — resolves `null` and is handed back to git unchanged.
+ * Anything else — arch-cycles, audit-ledger, context-budget — resolves `null`
+ * and is handed back to git unchanged.
  *
  * @param {unknown} ours
  * @param {unknown} theirs