mandrel 2.58.0 → 2.60.0

package/.agents/scripts/lib/runtime-deps/parser-major.js

@@ -0,0 +1,110 @@
+/**
+ * runtime-deps/parser-major — which `@babel/parser` major the complexity
+ * kernel can actually parse with, and how to say so when it is wrong.
+ *
+ * Its own module because two very different callers need the same answer and
+ * neither should drag the other in: the kernel asserts it at load, and
+ * `mandrel doctor` reports it to a consumer. Importing the kernel into doctor
+ * to ask one version question would pull the whole metric core and install the
+ * AST compatibility patch as a side effect.
+ *
+ * `.agents/` materializes into the consumer's repository root, so
+ * `@babel/parser` resolves from *their* `node_modules`. A range in
+ * `runtime-deps.json` documents the requirement; it cannot enforce it. This is
+ * the enforcement.
+ *
+ * @module lib/runtime-deps/parser-major
+ */
+
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+
+/**
+ * The only `@babel/parser` major the kernel supports.
+ *
+ * Module-local, with `describeParserMajorError` as the single public door:
+ * every caller wants the verdict and the remedy, not the number.
+ *
+ * 8.x removed several plugin names from the kernel's fixed list (they became
+ * default syntax), so it does not merely warn — it throws on the plugin list
+ * itself. Adopting it is a deliberate change with a baseline recut attached,
+ * not something to absorb from a consumer's resolution.
+ */
+const SUPPORTED_PARSER_MAJOR = 7;
+
+/** Package whose resolved major gates the kernel. */
+const PARSER_PACKAGE = '@babel/parser';
+
+/** Memoised resolved parser version: `undefined` unread, `null` unresolvable. */
+let parserVersion;
+
+/**
+ * Read the resolved `@babel/parser` version from its own manifest.
+ *
+ * The package exports no version, so its `package.json` is the only source.
+ * This is the one non-static resolution in the file and it deliberately
+ * targets a manifest rather than code: `@babel/parser` itself is reached by a
+ * static import above, so it is declared and preflighted like every other
+ * dependency.
+ *
+ * @returns {string|null} The resolved version, or `null` when the manifest
+ *   cannot be read (a layout that hides `package.json` behind `exports`, say).
+ */
+function resolveParserVersion() {
+  if (parserVersion !== undefined) return parserVersion;
+  try {
+    const require = createRequire(import.meta.url);
+    const manifest = require.resolve(`${PARSER_PACKAGE}/package.json`);
+    const parsed = JSON.parse(fs.readFileSync(manifest, 'utf-8'));
+    parserVersion = typeof parsed?.version === 'string' ? parsed.version : null;
+  } catch {
+    parserVersion = null;
+  }
+  return parserVersion;
+}
+
+/**
+ * The resolved parser's major version.
+ *
+ * @returns {number|null} `null` when the version could not be resolved or
+ *   does not lead with an integer.
+ */
+function resolveParserMajor() {
+  const version = resolveParserVersion();
+  if (version === null) return null;
+  const major = Number.parseInt(version, 10);
+  return Number.isInteger(major) ? major : null;
+}
+
+/**
+ * Describe the resolved-parser problem, if there is one.
+ *
+ * Single-sourced so the load-time assertion below and the preflight guard
+ * (`runtime-deps/ensure-installed.js`) emit the *same* named, actionable
+ * message — the point of AC-5 is that a consumer never meets this as a
+ * plugin-list syntax error mid-scan.
+ *
+ * An unresolvable version is **not** a problem: a consumer layout that hides
+ * the manifest still resolves the parser itself, and refusing to score would
+ * be a worse answer than scoring with an unverified parser. Only a
+ * *known-wrong* major is reported.
+ *
+ * @param {{major?: number|null, version?: string|null}} [resolved] Overrides
+ *   the resolved parser, so the message a consumer on an unsupported major
+ *   would read is assertable without installing one.
+ * @returns {string|null} The message, or `null` when the resolved parser is
+ *   supported (or its version is unknowable).
+ */
+export function describeParserMajorError(resolved = {}) {
+  const { major = resolveParserMajor(), version = resolveParserVersion() } =
+    resolved;
+  if (major === null || major === SUPPORTED_PARSER_MAJOR) return null;
+  return (
+    `unsupported ${PARSER_PACKAGE} major: resolved ${version}, ` +
+    `the complexity kernel requires ${SUPPORTED_PARSER_MAJOR}.x. It parses ` +
+    `with a fixed plugin list that later majors reject, so CRAP and ` +
+    `maintainability scoring would fail mid-scan with an opaque plugin-list ` +
+    `error. Declare "${PARSER_PACKAGE}": "^${SUPPORTED_PARSER_MAJOR}" in ` +
+    `your package.json (see .agents/runtime-deps.json).`
+  );
+}

package/.agents/scripts/lib/runtime-deps/preflight.js

@@ -1,9 +1,11 @@
 /**
- * runtime-deps/preflight — pure helpers for the dependency-presence check.
+ * runtime-deps/preflight — pure helpers for the dependency-presence check's
+ * *messaging* half.
  *
- * These functions hold no side effects so they are unit-testable in
- * isolation: `checkRuntimeDeps` takes an injected `resolve` seam,
- * `detectPackageManager` takes an injected `exists` seam, and
+ * The check itself moved to `dep-resolution.js`, which owns resolving a
+ * declared dependency, judging its major, and explaining a mismatch. What is
+ * left here holds no side effects and stays unit-testable in isolation:
+ * `detectPackageManager` takes an injected `exists` seam and
  * `formatMissingDepsMessage` is a pure string builder. The side-effecting
  * guard that wires them to the real process lives in `ensure-installed.js`.
  *
@@ -14,27 +16,6 @@
 import fs from 'node:fs';
 import { detectPackageManager as detectPm } from '../detect-package-manager.js';
 
-/**
- * Resolve each required package via the injected `resolve` seam and collect
- * the ones that fail. `resolve` is typically `require.resolve` bound to the
- * framework module location; it throws `MODULE_NOT_FOUND` when a package is
- * absent from the resolvable `node_modules`.
- *
- * @param {{ required: string[], resolve: (specifier: string) => string }} opts
- * @returns {{ ok: boolean, missing: string[] }}
- */
-export function checkRuntimeDeps({ required, resolve }) {
-  const missing = [];
-  for (const dep of required) {
-    try {
-      resolve(dep);
-    } catch {
-      missing.push(dep);
-    }
-  }
-  return { ok: missing.length === 0, missing };
-}
-
 /**
  * Detect the consumer's package manager from lockfile presence so the
  * remediation message names the right install command. Defaults to `npm`.

package/.agents/scripts/lib/runtime-deps/scan-imports.js

@@ -71,6 +71,51 @@ const STATIC_FROM =
 const SIDE_EFFECT = /^\s*import\s*['"]([^'"]+)['"]/gm;
 // `require(...)` and dynamic `import(...)` may appear mid-expression.
 const CALL_FORM = /\b(?:require|import)\s*\(\s*['"]([^'"]+)['"]/g;
+// Names bound to a `createRequire(...)` result, e.g.
+// `const fromReader = createRequire(x)`. Such a binding is a require function
+// under a different name, so calls through it are real runtime imports that
+// `CALL_FORM` cannot see — it matches the literal callees `require`/`import`.
+// A module reached only that way would be an undeclared, unpreflighted
+// dependency that this scanner reported as absent.
+const REQUIRE_ALIAS =
+  /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*createRequire\s*\(/g;
+
+/**
+ * Build a matcher for calls through `createRequire`-bound identifiers.
+ *
+ * Returns `null` when the source binds none, so the common case adds no pass.
+ * Aliases named `require` need no entry — `CALL_FORM` already covers them.
+ *
+ * @param {string} cleaned Comment-stripped source.
+ * @returns {RegExp|null}
+ */
+function aliasedRequireMatcher(cleaned) {
+  REQUIRE_ALIAS.lastIndex = 0;
+  const names = new Set();
+  let m = REQUIRE_ALIAS.exec(cleaned);
+  while (m !== null) {
+    if (m[1] !== 'require') names.add(m[1]);
+    m = REQUIRE_ALIAS.exec(cleaned);
+  }
+  if (names.size === 0) return null;
+  const alternation = [...names]
+    .map((n) => n.replace(/[$]/g, '\\$$'))
+    .join('|');
+  return new RegExp(`\\b(?:${alternation})\\s*\\(\\s*['"]([^'"]+)['"]`, 'g');
+}
+
+/**
+ * The specifier patterns to run over one source: the three fixed forms, plus
+ * an alias matcher when the source binds a `createRequire` result.
+ *
+ * @param {string} cleaned Comment-stripped source.
+ * @returns {RegExp[]}
+ */
+function specifierMatchers(cleaned) {
+  const aliased = aliasedRequireMatcher(cleaned);
+  if (!aliased) return [STATIC_FROM, SIDE_EFFECT, CALL_FORM];
+  return [STATIC_FROM, SIDE_EFFECT, CALL_FORM, aliased];
+}
 
 /**
  * Extract the set of third-party top-level package names imported by a
@@ -82,7 +127,7 @@ const CALL_FORM = /\b(?:require|import)\s*\(\s*['"]([^'"]+)['"]/g;
 export function extractThirdPartyImports(source) {
   const found = new Set();
   const cleaned = stripJsComments(source);
-  for (const re of [STATIC_FROM, SIDE_EFFECT, CALL_FORM]) {
+  for (const re of specifierMatchers(cleaned)) {
     re.lastIndex = 0;
     let match = re.exec(cleaned);
     while (match !== null) {

package/.agents/scripts/lib/skills/walk-skill-files.js

@@ -41,7 +41,7 @@ export const LOCAL_SKILLS_SEGMENTS = Object.freeze([
 
 /**
  * A skill id is the tier-relative path naming a skill — e.g.
- * `core/scope-triage` or `stack/qa/playwright`. It is the value that
+ * `core/test-first` or `stack/qa/playwright`. It is the value that
  * appears in `skills.index.json` minus the root prefix, and the value a
  * `qa.environments.*.signInSeam.skill` seam carries.
  *

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

@@ -24,10 +24,11 @@ import { BODY_FORMAT_LINTS } from '../story-body/body-format-lints.js';
  *     no verify-tier suffix — every one of those either scored a shape the
  *     authoring model already judges or prescribed a proxy that became the
  *     goal.
- *   - **The N>1 rules** ({@link renderStorySplitRules}) — the schedule and
- *     partition rules that only mean anything once a draft has siblings:
- *     every Story must earn its slot in the wave schedule, and every
- *     acceptance criterion belongs to exactly one Story.
+ *   - **The N>1 rules** ({@link renderStorySplitRules}) — the schedule rules
+ *     that only mean anything once a draft has siblings: every Story must
+ *     earn its slot in the wave schedule, and no same-wave pair may collide
+ *     on a declared path (Story #5332 replaced the acceptance partition with
+ *     the dispatcher's own collision predicate, armed as a refusal).
  *   - **The tickets-mode rules** ({@link ticketsModePromptField}, Story
  *     #5323) — what to re-derive rather than carry when the seed is an
  *     existing ticket whose body is already in Story shape.
@@ -116,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
@@ -135,10 +137,10 @@ 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. Not a fan-out table and not a duplicate of Acceptance.
-- **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.
-- **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). Aim for **three to six** items: fewer than three usually means the outcome is under-specified; more than six usually means acceptance is re-listing the footprint or the mechanical checks that belong in \`verify[]\`. 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.
+- **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 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. 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.
 
@@ -171,27 +173,18 @@ ${advisoryCaveat}
 
 **Decompose at deliverable granularity, not module/task level.** ${granularityDefinition}
 
-The only sizing question is **cohesion**: *is this one coherent change with one reason to exist?* There is no ceiling on a Story's footprint, Spec length or acceptance count — a broad contract cutover is one Story when every changed site changes for the same reason. Frontier models one-shot capability-sized work in a single pass; do not fragment a coherent capability into dependent slices to stay "small", and do not pad a Story with adjacent work to look "complete".
+The only sizing question is **cohesion**: *is this one coherent change with one reason to exist?* There is no target, floor or ceiling on a Story's footprint, Spec length or acceptance count, and a long acceptance list is a description of a broad capability, never a reason to split. A broad contract cutover is one Story when every changed site changes for the same reason. Frontier models one-shot capability-sized work in a single pass; do not fragment a coherent capability into dependent slices to stay "small", and do not pad a Story with adjacent work to look "complete".
 
 ${envelopeFloor}
 
-- **One Story = one coherent change with one reason to exist.** If you cannot state that reason in a sentence, the Story is probably two Stories — or two Stories that should be one.
+- **One Story = one coherent change with one reason to exist.**
+- **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}
-- **Split independent, parallelizable work** into sibling Stories — but only when the pieces genuinely have separate reasons to exist.
 
-#### 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.
@@ -201,7 +194,7 @@ IMPORTANT DEPENDENCY RULE: Story-to-Story dependencies are expressed via \`depen
 /**
  * The rules that only apply once a draft has more than one Story: the
  * delivery-schedule simulation that makes each Story earn its slot, and the
- * acceptance partition persist enforces at N>1.
+ * same-wave collision refusal persist enforces at N>1.
  *
  * @returns {string}
  */
@@ -213,16 +206,18 @@ You are splitting past the default-single policy, so simulate the delivery sched
 1. **Build the wave schedule.** A Story runs only after every \`depends_on\` completes, and two Stories that name the same file in \`changes[]\` cannot run in the same wave (the scheduler serializes file-overlapping Stories even when no \`depends_on\` edge links them).
 2. **Every Story must earn its slot** by at least one of:
    - **(a) parallelism** — it actually runs concurrently with a sibling in the schedule you just built ("logically independent" does not count; *schedule*-independent does);
-   - **(b) risk isolation** — it isolates a consumer-facing behavior change or high-risk cutover into its own reviewable, revertable unit;
-   - **(c) cohesion break** — merged into its neighbor it would no longer be one coherent change with one reason to exist.
-3. **A dependent link with none of those justifications merges into its consumer.** This generalizes the single-consumer merge rule from pairs to chains: N Stories that deliver no faster than one Story pay N delivery sessions (branch, PR, review, CI) for nothing.
+   - **(b) cohesion break** — merged into its neighbor it would no longer be one coherent change with one reason to exist.
+3. **A dependent link with neither of those justifications merges into its consumer.** This generalizes the single-consumer merge rule from pairs to chains: N Stories that deliver no faster than one Story pay N delivery sessions (branch, PR, review, CI) for nothing.
 4. **When one file appears in the \`changes[]\` of most of your Stories, the slicing axis cuts across a shared seam** — merge the Stories that co-edit it, or re-slice along the seam so each Story owns its files.
 
-#### ACCEPTANCE PARTITION (persist-enforced at N>1):
+#### THE COLLISION REFUSAL (persist-enforced at N>1):
+
+Persist runs the **dispatcher's own** collision predicate pairwise over your draft, before it creates a single issue, and **refuses** the plan when any two same-wave Stories collide — both declaring a path in \`changes[]\`, or one declaring a glob that covers the other's path. Such a pair cannot be co-dispatched, so the split buys no parallelism and costs a delivery session. Two remedies, both yours to choose at authoring time:
+
+- **Merge the pair** into the one Story they already are, with \`## Slicing\` checkpoints for the stages; or
+- **Order them** with \`depends_on\` so they sit in different waves, when they genuinely have separate reasons to exist.
 
-- Every acceptance criterion of the plan belongs to **exactly one** Story — no criterion is shared, and none is dropped. Persist refuses a draft whose criteria overlap or leave a plan-level criterion unclaimed.
-- Each Story carries its **own** \`## Spec\`; a shared \`techspec.md\` cannot be folded into N>1 Stories.
-- Express ordering with \`depends_on\` (a sibling slug, or \`#<id>\` for an open Story from an earlier plan). A Story whose \`verify[]\` runs against a file a sibling creates MUST \`depends_on\` that sibling, so the file exists when verification runs.`;
+Each Story carries its **own** \`## Spec\`; a shared \`techspec.md\` cannot be folded into N>1 Stories. Express ordering with \`depends_on\` (a sibling slug, or \`#<id>\` for an open Story from an earlier plan). A Story whose \`verify[]\` runs against a file a sibling creates MUST \`depends_on\` that sibling, so the file exists when verification runs.`;
 }
 
 /**
@@ -244,7 +239,7 @@ function renderStoryTicketsRules() {
 
 You are planning from one or more existing tickets. Read them for **what the work is** — the problem, the constraints, the commands that verify it — and re-derive everything else. Specifically:
 
-1. **Re-derive \`acceptance[]\` from the goal.** Do not copy the source's \`## Acceptance\` list, and never carry its \`AC-<n>:\` handles — the body renderer numbers the checkboxes itself, so a copied handle renders doubled. A source ticket carrying fifteen criteria is telling you its acceptance was over-specified, not that yours must be: state the three to six outcomes a PR reviewer can confirm, and let the rest fall to \`verify[]\`.
+1. **Re-derive \`acceptance[]\` from the goal.** Do not copy the source's \`## Acceptance\` list, and never carry its \`AC-<n>:\` handles — the body renderer numbers the checkboxes itself, so a copied handle renders doubled. A source ticket carrying fifteen criteria is telling you its acceptance was over-specified, not that yours must be: state the outcomes a PR reviewer can confirm, and let the mechanical checks fall to \`verify[]\`.
 2. **A mechanical check is a \`verify[]\` command, not an acceptance item.** "Baselines refreshed", "lint exits 0", "the generated index is regenerated", "the quality gate passes" are commands the deliverer runs and the critic reads as evidence. Carrying them as acceptance items inflates the binding contract with work every close already gates.
 3. **Read the source's \`verify[]\` for the commands it names, not for its shape.** Take the test paths and scripts; drop any trailing tier suffix (\`(unit)\`, \`(contract)\`, \`(e2e)\`, \`(validate)\`) and any \`manual:<reason>\` escape — a verify entry is a bare command.
 4. **Re-derive the footprint against the tree as it is now.** The source ticket's \`## Changes\` predicted a repository that has since moved; probe the paths you cite and omit the generated artifacts it listed.