mandrel 2.31.0 → 2.33.0

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

@@ -0,0 +1,97 @@
+/**
+ * footer-block.js — the Story body's `---` footer grammar.
+ *
+ * A Story body is prose an operator edits. Its **declared dependency edges**
+ * are not: they live in a footer block, in one exact line shape, and that
+ * distinction is the whole safety property. An unanchored whole-body scan
+ * (what `parseBlockedBy` used to be) turned any sentence that merely mentioned
+ * a blocker into a real dispatch gate — an example, a changelog note, an
+ * acceptance criterion quoting the phrase — and withheld the Story until an
+ * unrelated issue closed.
+ *
+ * This module is the single home for that grammar. Both readers go through it:
+ * `lib/story-body/story-body.js` (what a body round-trips as `depends_on`) and
+ * `lib/dependency-parser.js` (what gates dispatch). Sharing one implementation
+ * is what keeps them from drifting apart into two different answers about the
+ * same body.
+ *
+ * @module lib/story-body/footer-block
+ */
+
+/**
+ * The one line shape that declares a dependency edge: `blocked by #N` alone on
+ * its own line inside the footer block. Anchored at both ends deliberately —
+ * `depends on #N`, `Blocked by: #N`, and `blocked by #N once X lands` all
+ * declare nothing.
+ */
+const FOOTER_BLOCKED_BY_LINE_RE = /^blocked by\s+(#\d+)$/i;
+
+/** A `---` rule on its own line. */
+const FOOTER_RULE_RE = /^---\s*$/;
+
+/** Footer keys that qualify a bare `---` rule as the footer separator. */
+const FOOTER_KEY_RE = /^(parent:|Epic:|blocked by)/im;
+
+/**
+ * True when line `index` opens the footer block: a `---` on its own line whose
+ * remaining lines start with a recognised footer key (`parent:`, `Epic:`,
+ * `blocked by`). A `---` opening a thematic break or a table mid-body is
+ * therefore not mistaken for the footer.
+ *
+ * @param {string} line
+ * @param {string[]} lines
+ * @param {number} index
+ * @returns {boolean}
+ */
+export function isFooterSeparator(line, lines, index) {
+  if (!FOOTER_RULE_RE.test(line)) return false;
+  return FOOTER_KEY_RE.test(lines.slice(index + 1).join('\n'));
+}
+
+/**
+ * Return the footer block of a body — everything after the footer separator —
+ * or `''` when the body carries no footer.
+ *
+ * Module-private: `parseFooterBlockedByIds` is its only caller. The body
+ * parser splits its own sections and reaches for `parseFooterBlockedByRefs`
+ * with the footer it already has, so exporting this would ship a symbol with
+ * no consumer.
+ *
+ * @param {string} body
+ * @returns {string}
+ */
+function extractFooterBlock(body) {
+  if (!body) return '';
+  const lines = String(body).split('\n');
+  const start = lines.findIndex((line, i) => isFooterSeparator(line, lines, i));
+  return start === -1 ? '' : lines.slice(start + 1).join('\n');
+}
+
+/**
+ * Extract the `blocked by #N` refs from an already-split footer block, as the
+ * `"#N"` strings a Story body's `depends_on` field round-trips.
+ *
+ * @param {string} footerBlock
+ * @returns {string[]}
+ */
+export function parseFooterBlockedByRefs(footerBlock) {
+  if (!footerBlock) return [];
+  return String(footerBlock)
+    .split('\n')
+    .map((line) => line.trim().match(FOOTER_BLOCKED_BY_LINE_RE)?.[1])
+    .filter((ref) => typeof ref === 'string');
+}
+
+/**
+ * Parse a body's declared blocker issue **numbers**, deduped — the
+ * dispatch-edge view of the same footer the body parser reads.
+ *
+ * @param {string} body
+ * @returns {number[]}
+ */
+export function parseFooterBlockedByIds(body) {
+  const ids = parseFooterBlockedByRefs(extractFooterBlock(body)).map((ref) =>
+    Number.parseInt(ref.slice(1), 10),
+  );
+  return [...new Set(ids)];
+}

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

@@ -21,7 +21,6 @@
  *   wide:                { reason } | null,// declared-wide footprint (optional)
  *   reason_to_exist:     string | null,    // one-sentence cohesion reason (optional)
  *   depends_on:          string[],         // blocker story slugs or #ids
- *   estimated_test_files: number | null,   // absent → null (informational)
  * }
  * ```
  *
@@ -49,6 +48,7 @@ import {
 } from '../framework-version.js';
 import { FILE_ASSUMPTION_VALUES } from '../orchestration/file-assumption-enum.js';
 import { suggestPathEntryFix } from './body-format-lints.js';
+import { isFooterSeparator, parseFooterBlockedByRefs } from './footer-block.js';
 
 // ---------------------------------------------------------------------------
 // Public types (JSDoc only — no runtime schema file)
@@ -79,7 +79,6 @@ import { suggestPathEntryFix } from './body-format-lints.js';
  * @property {{ reason: string }|null} wide      - Declared-wide footprint (reason), or null.
  * @property {string|null}   reason_to_exist     - One-sentence cohesion reason ("why this Story exists"), or null.
  * @property {string[]}      depends_on          - Blocking story slugs / issue refs.
- * @property {number|null}   estimated_test_files - Test surface count or null.
  * @property {string|null}   mandrel_version     - Framework version stamped at authoring, or null.
  * @property {string|null}   authored_at         - Authoring date (YYYY-MM-DD) stamped at authoring, or null.
  */
@@ -315,16 +314,15 @@ function pathEntryFixIt(raw) {
  * Extract the `blocked by #N` lines from the footer block (text after
  * the last `---` separator). Returns an array of "#N" strings.
  *
+ * Delegates to `./footer-block.js`, which owns the footer-block grammar
+ * (Story #5046) so the body parser and the dispatch-edge parser cannot
+ * disagree about what declares an edge.
+ *
  * @param {string} footerBlock
  * @returns {string[]}
  */
 function extractBlockedBy(footerBlock) {
-  const deps = [];
-  for (const line of footerBlock.split('\n')) {
-    const m = line.trim().match(/^blocked by\s+(#\d+)$/i);
-    if (m) deps.push(m[1]);
-  }
-  return deps;
+  return parseFooterBlockedByRefs(footerBlock);
 }
 
 // Matches any trailing `<!-- meta: … -->` block. Object payloads are the
@@ -334,7 +332,7 @@ const META_BLOCK_RE = /<!--\s*meta:\s*([\s\S]*?)\s*-->/;
 const META_OBJECT_RE = /<!--\s*meta:\s*(\{[\s\S]*?\})\s*-->/;
 
 /**
- * Extract the `wide` / `estimated_test_files` fields from the trailing
+ * Extract the `wide` / `reason_to_exist` fields from the trailing
  * `<!-- meta: {...} -->` comment block written by {@link serialize}. Returns
  * canonical-shaped values (null when absent or malformed) so the parser
  * round-trips the meta block faithfully.
@@ -350,13 +348,12 @@ const META_OBJECT_RE = /<!--\s*meta:\s*(\{[\s\S]*?\})\s*-->/;
  * rather than dropping or re-deriving it.
  *
  * @param {string} markdown
- * @returns {{ wide: { reason: string }|null, reason_to_exist: string|null, estimated_test_files: number|null, mandrel_version: string|null, authored_at: string|null }}
+ * @returns {{ wide: { reason: string }|null, reason_to_exist: string|null, mandrel_version: string|null, authored_at: string|null }}
  */
 function extractMeta(markdown) {
   const result = {
     wide: null,
     reason_to_exist: null,
-    estimated_test_files: null,
     mandrel_version: null,
     authored_at: null,
   };
@@ -377,9 +374,6 @@ function extractMeta(markdown) {
 
   result.wide = normalizeWide(parsed.wide);
   result.reason_to_exist = normalizeReasonToExist(parsed.reason_to_exist);
-  if (typeof parsed.estimated_test_files === 'number') {
-    result.estimated_test_files = parsed.estimated_test_files;
-  }
   if (
     typeof parsed.mandrel_version === 'string' &&
     parsed.mandrel_version.trim()
@@ -497,22 +491,6 @@ function splitSections(markdown) {
   return { sections, footer, preamble };
 }
 
-/**
- * True when line `index` opens the footer block: a `---` on its own line
- * whose remaining lines start with a recognised footer key (`parent:`,
- * `Epic:`, `blocked by`).
- *
- * @param {string} line
- * @param {string[]} lines
- * @param {number} index
- * @returns {boolean}
- */
-function isFooterSeparator(line, lines, index) {
-  if (!/^---\s*$/.test(line)) return false;
-  const remaining = lines.slice(index + 1).join('\n');
-  return /^(parent:|Epic:|blocked by)/im.test(remaining);
-}
-
 /**
  * True for a non-canonical markdown heading that TERMINATES the current
  * structured section. Trailing extended content a producer appends after the
@@ -579,7 +557,6 @@ function isMachineMarkerLine(line) {
 function parseUnstructuredBody(input, preamble, footer) {
   const warnings = [
     'unstructured-body: no structured sections found; returning minimal body from preamble text.',
-    'test-surface-unestimated: estimated_test_files not present.',
   ];
   const body = {
     goal: preamble || input.trim(),
@@ -593,7 +570,6 @@ function parseUnstructuredBody(input, preamble, footer) {
     wide: null,
     reason_to_exist: null,
     depends_on: extractBlockedBy(footer),
-    estimated_test_files: null,
     mandrel_version: null,
     authored_at: null,
   };
@@ -688,11 +664,6 @@ function parseTextListSection(lines) {
  * `result.warnings` to detect legacy path entries that should be
  * migrated.
  *
- * Informational finding emitted on `result.warnings`:
- * - `test-surface-unestimated` — when `estimated_test_files` is absent
- *   from both a structured body and the markdown. Callers that care about
- *   test-surface coverage SHOULD surface this to the operator.
- *
  * @param {string|object} input - Markdown string or already-structured body object.
  * @returns {ParseResult}
  * @throws {StoryBodyParseError} When the body is structurally unrecoverable.
@@ -765,20 +736,16 @@ export function parse(input) {
   const non_goals = parseTextListSection(sections.get('non_goals') ?? []);
   const dependsOn = extractBlockedBy(footer);
 
-  // --- Recover wide / estimated_test_files from the meta block ---
+  // --- Recover wide / reason_to_exist / provenance from the meta block ---
   // serialize() writes these into a trailing `<!-- meta: {...} -->` comment
   // so round-trips preserve them. Absent meta block → canonical null defaults.
+  // Unknown keys are ignored, so a body carrying a retired meta field parses
+  // clean and simply drops it.
   const meta = extractMeta(input);
-  const estimated_test_files = meta.estimated_test_files;
   const wide = meta.wide;
   const reason_to_exist = meta.reason_to_exist;
   const mandrel_version = meta.mandrel_version;
   const authored_at = meta.authored_at;
-  if (estimated_test_files === null) {
-    warnings.push(
-      'test-surface-unestimated: estimated_test_files not present.',
-    );
-  }
 
   const body = {
     goal,
@@ -792,7 +759,6 @@ export function parse(input) {
     wide,
     reason_to_exist,
     depends_on: dependsOn,
-    estimated_test_files,
     mandrel_version,
     authored_at,
   };
@@ -834,13 +800,6 @@ function parseStructuredObject(obj) {
     body[name] = STRUCTURED_FIELD_NORMALIZERS[kind](obj[name], warnings);
   }
 
-  // estimated_test_files is the one warning-coupled scalar: absent (== null)
-  // warns; a non-number, non-null value stays null silently.
-  body.estimated_test_files = normalizeEstimatedTestFiles(
-    obj.estimated_test_files,
-    warnings,
-  );
-
   // Provenance stamp (preserved verbatim; never re-derived here).
   body.mandrel_version = normalizeProvenanceString(obj.mandrel_version);
   body.authored_at = normalizeProvenanceString(obj.authored_at);
@@ -917,25 +876,6 @@ const STRUCTURED_FIELD_NORMALIZERS = {
   reasonToExist: (raw) => normalizeReasonToExist(raw),
 };
 
-/**
- * Normalize `estimated_test_files`: a number passes through; an absent
- * (`null`/`undefined`) value warns `test-surface-unestimated`; any other
- * value stays `null` silently.
- *
- * @param {unknown} raw
- * @param {string[]} warnings
- * @returns {number|null}
- */
-function normalizeEstimatedTestFiles(raw, warnings) {
-  if (typeof raw === 'number') return raw;
-  if (raw == null) {
-    warnings.push(
-      'test-surface-unestimated: estimated_test_files not present.',
-    );
-  }
-  return null;
-}
-
 /**
  * Normalize a provenance stamp field (`mandrel_version` / `authored_at`) to
  * a non-empty trimmed string or `null`.
@@ -1066,11 +1006,11 @@ const SERIALIZE_SECTIONS = [
 
 /**
  * Build the trailing `<!-- meta: {...} -->` block carrying the fields that
- * have no human-readable section (`wide`, `reason_to_exist`,
- * `estimated_test_files`). Returns the empty string when no meta field is
- * present so {@link serialize} appends nothing.
+ * have no human-readable section (`wide`, `reason_to_exist`). Returns the
+ * empty string when no meta field is present so {@link serialize} appends
+ * nothing.
  *
- * Key insertion order (`wide` → `reason_to_exist` → `estimated_test_files` →
+ * Key insertion order (`wide` → `reason_to_exist` →
  * `mandrel_version` → `authored_at`) is load-bearing: it fixes the serialized
  * JSON byte sequence the parser's meta round-trip and the unit suite assert
  * against. The provenance stamp keys are appended **last** so every
@@ -1089,9 +1029,6 @@ function serializeMetaBlock(body) {
   if (reasonToExist !== null) {
     metaFields.reason_to_exist = reasonToExist;
   }
-  if (typeof body.estimated_test_files === 'number') {
-    metaFields.estimated_test_files = body.estimated_test_files;
-  }
   if (typeof body.mandrel_version === 'string' && body.mandrel_version.trim()) {
     metaFields.mandrel_version = body.mandrel_version.trim();
   }
@@ -1153,9 +1090,9 @@ function serializeFooter(body, opts) {
  * `## Goal`, `## Slicing`, `## Spec`, `## Changes`, `## Acceptance`,
  * `## Verify`, `## References`, `## Non-Goals` (each omitted when empty).
  *
- * `wide`, `reason_to_exist`, and `estimated_test_files` are emitted as a
- * fenced `<!-- meta -->` comment block so round-trips preserve them without
- * polluting the human-readable body.
+ * `wide` and `reason_to_exist` are emitted as a fenced `<!-- meta -->`
+ * comment block so round-trips preserve them without polluting the
+ * human-readable body.
  *
  * @param {StoryBody} body
  * @param {SerializeOptions} [opts]

package/.agents/scripts/lib/temp-retention.js

@@ -31,7 +31,7 @@
  * ## Keep-class
  *
  * `signals.ndjson` is the artifact whose value *starts* when the run ends —
- * `signals-view`, `acceptance-eval`, and the loop-health check all read it
+ * `acceptance-eval` and the loop-health check both read it
  * long after the Story merged. It is excluded twice over: it is not in the
  * evidence basename allowlist, and {@link KEEP_BASENAMES} is re-checked at
  * the deletion site. Defence in depth is warranted for the one file whose

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

@@ -109,7 +109,7 @@ You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown
 **Slug format**: \`^[a-z0-9][a-z0-9-]*$\` — hyphen-case only. Underscores are rejected by the validator.
 
 ### STORY BODY SCHEMA (REQUIRED FOR EVERY STORY):
-\`body\` is either the serialized markdown **string** (the section format below) or a **structured object** carrying the same fields (\`goal\`, optional \`slicing\` / \`spec\`, \`changes\`, optional \`non_goals\` / \`wide\` / \`reason_to_exist\` / \`estimated_test_files\`) — persist parses either shape and serializes the canonical markdown itself, so you never need to read \`story-body.js\` or hand-assemble the markdown (the \`stories.template.json\` file emitted next to the plan-context envelope is a ready-to-fill structured-object skeleton). Stories are consumed by non-interactive sub-agents that must self-verify from the Story ticket alone — so the ticket must carry everything an agent needs to execute and self-verify.
+\`body\` is either the serialized markdown **string** (the section format below) or a **structured object** carrying the same fields (\`goal\`, optional \`slicing\` / \`spec\`, \`changes\`, optional \`non_goals\` / \`wide\` / \`reason_to_exist\`) — persist parses either shape and serializes the canonical markdown itself, so you never need to read \`story-body.js\` or hand-assemble the markdown (the \`stories.template.json\` file emitted next to the plan-context envelope is a ready-to-fill structured-object skeleton). Stories are consumed by non-interactive sub-agents that must self-verify from the Story ticket alone — so the ticket must carry everything an agent needs to execute and self-verify.
 
 The \`acceptance[]\` and \`verify[]\` arrays live at the **top level** of the Story ticket object — that is the machine contract the validator reads. Author each list **once, at top level**, and **omit** the \`## Acceptance\` / \`## Verify\` sections from the authored \`body\` string: persist syncs the top-level arrays into those sections so the GitHub issue stays a complete executable document. The validator resolves both fields from the top level, so an omitted section is the expected shape, not a violation.
 
@@ -151,7 +151,6 @@ The **persisted** \`body\` renders these markdown sections (in order) — you au
 - **acceptance** (top-level array on the ticket object): Items MUST be observable from outside the agent. Acceptable shapes: a specific command exits 0, a file exists at a given path, a snapshot test matches, a \`data-testid\` resolves under a given selector, a row count in a fixture matches. UNACCEPTABLE: "verify by reading the diff", "looks good", "matches the spec" — push these down into a \`verify\` command instead.
 - **verify** (top-level array on the ticket object): Each entry MUST name a testing tier in parentheses, drawn from \`unit\` / \`contract\` / \`e2e\` / \`validate\`. Example: \`npm run test -- src/x.test.ts (unit)\`, \`npm run validate (validate)\`. Stories with zero verify entries SHOULD fail validation; if a story is genuinely unverifiable in isolation (e.g., a copy edit auditor will eyeball), the literal entry \`manual:<reason>\` is allowed so the absence is intentional, not lazy. Manual entries without a reason are rejected.
 - **reason to exist** (REQUIRED, encoded as the \`reason_to_exist\` field of the \`<!-- meta: {...} -->\` comment appended to the serialized body string — NOT a top-level ticket field): One sentence stating the single coherent reason this Story exists, distinct from its broader \`## Goal\` prose. Every Story MUST carry a non-empty \`reason_to_exist\`; it is the machine-checkable form of the cohesion rule (**one Story = one coherent change with one reason to exist**) and the \`epic-plan-consolidate\` critic flags any Story whose body carries no non-empty reason to exist. Encode it as \`<!-- meta: {"reason_to_exist": "..."} -->\`.
-- **estimated_test_files** (optional, encoded in the \`<!-- meta: {...} -->\` comment appended to the serialized body string — NOT a top-level ticket field): Integer estimate of how many test files this Story creates or modifies. Omit when the number is not estimable. Informational only — it does not gate the decompose.
 - **Observed-behavior claims open with \`Current state (verified <date>)\`.** Any Spec claim about how the codebase behaves today MUST open with that preamble (e.g. \`Current state (verified 2026-07-17): …\`) so a reader can tell a verified observation from an assumption, and can tell when the observation went stale.
 - **Intent-then-proxy acceptance shape.** When an acceptance item verifies through a proxy check (a grep, a file-exists probe, an exit-code test), state the intent clause before the proxy check — what outcome the check stands in for — so the proxy never becomes the goal (e.g. "the workflow names hygiene findings as re-author input: \`grep -n "textHygiene" …\` exits 0").
 - **Slicing checkpoints are one line each.** Each \`## Slicing\` checkpoint is a single line naming the checkpoint; implementation detail lives in \`## Spec\`, never duplicated into Slicing. A Slicing section outweighing its Spec is a defect the text-hygiene lint flags.
@@ -171,7 +170,7 @@ The Story is executed by a frontier-model deliverer that reads the codebase itse
 
 #### DETERMINISTIC BODY-FORMAT LINTS — author lint-clean by construction:
 
-Persist enforces the deterministic body-format rules below and **rejects** an authored body that violates any of them. Author every Story to satisfy all of them on the FIRST draft — each rule is stated example-first so there is nothing to discover by trial-and-error. The two auto-fixable rules (\`changes-path-entry-shape\`, \`verify-tier-suffix\`) also emit the corrected form in the dry-run failure output, but authoring them right up front avoids the round-trip entirely.
+Persist enforces the deterministic body-format rules below and **rejects** an authored body that violates any of them. Author every Story to satisfy all of them on the FIRST draft — each rule is stated example-first so there is nothing to discover by trial-and-error. \`verify-tier-suffix\` is the one rule persist repairs for you: when the tier is unambiguously inferable from the command, persist appends it and proceeds; when it is not, the entry is still rejected and you must choose the tier. \`changes-path-entry-shape\` emits the corrected form in the dry-run failure output but is never applied for you.
 
 ${bodyFormatLintChecklist}
 
@@ -231,35 +230,38 @@ Declaring \`wide\` with a non-empty reason **lifts the hard session-mass rejecti
 
 #### UI / TESTID INVARIANCE (per CLAUDE.md safety rule):
 
-- Stories that touch UI (\`*.tsx\`, \`*.astro\`, \`*.svelte\`, \`*.vue\`, components folders) MUST end \`changes\` with one of:
-  - \`data-testid invariance: <list of testids that MUST be preserved>\`, or
-  - \`data-testid changes: <old> -> <new>\` paired with a corresponding \`tests/e2e/*.spec.ts\` edit in the same story or a depends_on Story.
+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 Epic body"]\`. Silence on style sourcing is a smell.
+- 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.
 
-### WAVE-0 BDD SCAFFOLD STORY (features-first; emit when the Acceptance Spec has \`new\`-disposition rows):
-The Acceptance Spec's AC table (columns \`AC ID | Outcome | Feature File | Scenario | Disposition\`) tags each row's \`Disposition\` with one of \`new | updated | unchanged\`. A \`new\` row names a \`.feature\` file + scenario that does NOT yet exist on \`main\`. The framework is features-first: implementing Stories reference those \`.feature\` paths in their \`verify[]\` lines, so the files MUST already exist when those Stories run — otherwise verification fails mid-delivery on a missing file. (These Gherkin \`.feature\` files are BDD artifacts, unrelated to any ticket tier.)
+### WAVE-0 BDD SCAFFOLD STORY (features-first; emit when your plan verifies against a scenario that does not exist yet):
+The plan-context envelope's \`bddScenarios\` field is the index of Gherkin scenarios that **already exist on \`main\`** — one row per scenario, carrying its \`.feature\` file path, line, scenario title and tags. It is the live signal for this rule: a \`.feature\` path + scenario your plan needs but that appears in no \`bddScenarios\` row does not exist yet. The framework is features-first: implementing Stories reference those \`.feature\` paths in their \`verify[]\` lines, so the files MUST already exist when those Stories run — otherwise verification fails mid-delivery on a missing file.
 
-When the Acceptance Spec contains **one or more \`Disposition: new\` rows**, you MUST emit **exactly one** dedicated wave-0 scaffold Story whose sole job is to create the \`.feature\` files with \`@skip\`-tagged scenarios BEFORE any implementation Story runs:
+When **one or more** \`.feature\` scenarios your plan verifies against are absent from \`bddScenarios\`, you MUST emit **exactly one** dedicated wave-0 scaffold Story whose sole job is to create those \`.feature\` files with \`@skip\`-tagged scenarios BEFORE any implementation Story runs:
 
 - **goal**: contains the literal token \`bdd-scaffold\` (e.g. "bdd-scaffold: create the @skip-tagged feature files the implementation Stories verify against").
 - **depends_on**: EMPTY (\`[]\`) — it runs first, in wave 0.
-- **changes**: one entry per distinct \`.feature\` file named in a \`new\` row, each \`{ "path": "<feature file path>", "assumption": "creates" }\`.
+- **changes**: one entry per distinct absent \`.feature\` file, each \`{ "path": "<feature file path>", "assumption": "creates" }\`.
 - **acceptance**: MUST assert (a) every new \`.feature\` file exists AND (b) every new scenario within them carries an \`@skip\` tag. Keep these observable (a grep/validate command exits 0, a file exists at a path).
 - **verify**: a grep/validate command (tier \`validate\`), NOT an e2e runner — verifying that a file exists with the required tags needs no browser/playwright run. Example: \`grep -rL '@skip' tests/features/<area>/*.feature (validate)\` paired with an existence check.
 - Each implementation Story whose \`verify[]\` references one of these scaffolded \`.feature\` paths MUST \`depends_on\` the scaffold Story (so the scaffold lands in an earlier wave). Omitting the link trips the soft \`missing-bdd-scaffold\` validator finding.
 
-When the Acceptance Spec contains **zero \`new\`-disposition rows** (every row is \`updated\` or \`unchanged\`), do NOT emit a scaffold Story — there is nothing to create.
+When every scenario your plan verifies against is already present in \`bddScenarios\`, do NOT emit a scaffold Story — there is nothing to create.
 
 ### SCOPE-OVERLAP FLAGGING (docs/runbook downstream of config work):
-When a "docs update" / "runbook" / "README" Story appears downstream of an earlier Story in the same Epic whose AC already covers updating the same document (e.g. a "config + runbook" Story followed by a "docs" Story touching the same runbook), the downstream Story's deliverable may be fully absorbed by the earlier Story. Flag the risk directly in the Story's top-level \`acceptance\` array by appending an item of the form:
+When a "docs update" / "runbook" / "README" Story appears downstream of an earlier Story in the same plan whose AC already covers updating the same document (e.g. a "config + runbook" Story followed by a "docs" Story touching the same runbook), the downstream Story's deliverable may be fully absorbed by the earlier Story. Flag the risk directly in the Story's top-level \`acceptance\` array by appending an item of the form:
 "Scope verification note: this story's deliverable may already be satisfied by Story #<slug-or-id>'s AC — before implementing, \`git diff main -- <path>\` against the upstream Story branch and confirm whether a substantive edit is still required, or whether only a cross-reference remains."
 This prevents the executing agent from redoing work the upstream Story already merged.
 
-CRITICAL: Dependencies should follow execution blockers. Stories attach directly to the Epic — never emit a 'parent_slug' field.
+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.
 
 ### REVIEWABILITY BUDGET (Story #2798):

package/.agents/scripts/lib/ticket-body-sections.js

@@ -53,11 +53,10 @@ export const TICKET_BODY_SECTIONS = Object.freeze({
 export const ACCEPTANCE_TABLE_HEADING = '## Acceptance Table';
 
 /**
- * Regex matching the Tech Spec's required opening heading (same variants
- * `spec-section-validator.js` accepts). Exported so it is the single
- * source of truth for this pattern — `spec-section-validator.js`,
- * `consolidation-precondition.js` all import
- * it rather than each carrying their own copy.
+ * Regex matching the Tech Spec's `## Delivery Slicing` heading, tolerating
+ * the `Delivery ` qualifier and casing variants. Exported so it is the single
+ * source of truth for this pattern — `consolidation-precondition.js` imports
+ * it rather than carrying its own copy.
  */
 export const DELIVERY_SLICING_RE = /^##\s+(?:Delivery\s+)?Slicing\s*$/im;