mandrel 2.1.0 → 2.3.0

package/.agents/scripts/lib/orchestration/story-close/phases/local-lens-review.js

@@ -0,0 +1,191 @@
+/**
+ * phases/local-lens-review.js — the Story-scope local-lens pass.
+ *
+ * Extracted from `phases/code-review.js` (Story #4603) so the review spine and
+ * the lens pass each carry one reason to change. The spine
+ * (`runStoryReviewCore`) owns the single per-close-run diff enumeration and the
+ * `runCodeReview` invocation; this module owns lens selection + materialization.
+ *
+ * Shift-left tier (Epic #4405): local concerns are cheap to decide on a single
+ * Story's diff, so the maker-blind Story-scope review runs its matched local
+ * lenses here, inside the story-close subprocess, rather than paying a deeper
+ * pass at Epic close.
+ */
+
+import {
+  runAuditSuite,
+  selectLocalLenses,
+} from '../../../audit-suite/index.js';
+import { gitSpawn } from '../../../git-utils.js';
+import { computeChangeSet } from '../../change-set.js';
+
+/**
+ * The review depth the Story-scope local-lens pass runs at. Fixed for this
+ * tier — it is not risk-scaled like the code-review pillar depth.
+ *
+ * Module-local: it is an implementation detail of {@link runLocalLensReview}
+ * (it rides out on the returned envelope's `depth` field), not a public seam.
+ * Tests assert the observable `'light'` on that envelope rather than importing
+ * the constant, so it stays off the public surface (Story #4603).
+ */
+const STORY_SCOPE_LENS_DEPTH = 'light';
+
+/**
+ * Enumerate the files changed in the `baseRef...headRef` diff. Thin adapter over
+ * the shared {@link computeChangeSet} enumerator (Story #4593) that flattens its
+ * `files: string[]|null` envelope to this phase's historical `[]`-on-failure
+ * contract: the lens roster treats "nothing changed" and "diff unknown"
+ * identically, because an unknown diff matches no `filePatterns` and therefore
+ * adds no lens work either way.
+ *
+ * Best-effort and total — never throws, mirroring the advisory posture of the
+ * surrounding review phase. Retained as the self-enumeration fallback for
+ * {@link runLocalLensReview} when no change set is injected.
+ *
+ * @param {{
+ *   baseRef: string,
+ *   headRef: string,
+ *   gitSpawnFn?: import('../../change-set.js').GitSpawnFn,
+ * }} args
+ * Module-local (Story #4603): a private fallback of {@link runLocalLensReview},
+ * exercised through that public entry point rather than imported directly, so it
+ * adds no public export a production path fails to reach.
+ *
+ * @returns {string[]} Changed file paths, or `[]` on any failure.
+ */
+function enumerateChangedFiles({ baseRef, headRef, gitSpawnFn = gitSpawn }) {
+  return computeChangeSet({ baseRef, headRef, gitSpawnFn }).files ?? [];
+}
+
+/**
+ * Resolve the change set the lens roster reads, honouring all THREE injection
+ * states (Story #4603 — the fix for #4593's single-enumeration leak).
+ *
+ * The distinction between `null` and `undefined` is load-bearing and mirrors
+ * the sibling contract in `orchestration/code-review.js#resolveInjectedChangedFiles`:
+ *
+ *   - **array**     — the caller's change set; use it verbatim.
+ *   - **`null`**    — the caller (`runStoryReviewCore`) already tried and the
+ *                     diff is unenumerable. Re-running git here would only fail
+ *                     again, so degrade straight to the fail-safe empty roster.
+ *   - **`undefined`** — nobody enumerated (standalone callers), so the shared
+ *                     enumerator runs as the fallback.
+ *
+ * The prior `Array.isArray()` discriminator collapsed `null` and `undefined`
+ * into one branch and re-spawned git on the unenumerable path, contradicting the
+ * spine's documented "the one enumeration per close run" invariant.
+ *
+ * Module-local (Story #4603): a private detail of {@link runLocalLensReview}.
+ * The three-state contract is asserted through that public entry point (does an
+ * injected `null` re-spawn git? does `undefined` self-enumerate?), so it needs
+ * no public export — keeping the fix from re-introducing the very kind of
+ * production-dead public symbol this Story's ratchet root-cause is about.
+ *
+ * @param {{
+ *   changedFiles: string[]|null|undefined,
+ *   baseRef: string,
+ *   headRef: string,
+ *   gitSpawnFn?: import('../../change-set.js').GitSpawnFn,
+ * }} args
+ * @returns {string[]}
+ */
+function resolveLensChangeSet({
+  changedFiles,
+  baseRef,
+  headRef,
+  gitSpawnFn = gitSpawn,
+}) {
+  if (changedFiles === undefined) {
+    return enumerateChangedFiles({ baseRef, headRef, gitSpawnFn });
+  }
+  return changedFiles ?? [];
+}
+
+/**
+ * Run the Story-scope local-lens pass: select the LOCAL-tier lenses whose
+ * `filePatterns` match the actual Story diff (`baseRef...headRef`) and
+ * materialize their lens-prompt bodies at `light` depth. Called only from
+ * `runStoryReviewCore`, never in the delivering child's (maker's) context, so a
+ * maker never grades its own work.
+ *
+ * A diff that matches no local lens adds **no** lens work: the roster is empty
+ * and `runAuditSuite` is never invoked. Best-effort and total — a git or
+ * materialization failure degrades to `{ skipped: true, lenses: [] }` and is
+ * logged via `progress`, matching the advisory posture the review phase already
+ * takes for provider/transport failures.
+ *
+ * Story #4593 — `changedFiles` is injected by `runStoryReviewCore`, which
+ * computes the change set once per close run and hands the same list to this
+ * pass and to `runCodeReview`. Self-enumeration is the **fallback only**, kept
+ * for standalone callers that supply no list; see {@link resolveLensChangeSet}
+ * for the three-state contract.
+ *
+ * @param {{
+ *   baseRef: string,
+ *   headRef: string,
+ *   changedFiles?: string[]|null,
+ *   progress: (tag: string, msg: string) => void,
+ *   progressTag?: string,
+ *   gitSpawnFn?: import('../../change-set.js').GitSpawnFn,
+ *   selectLocalLensesFn?: typeof selectLocalLenses,
+ *   runAuditSuiteFn?: typeof runAuditSuite,
+ * }} args
+ * @returns {Promise<{
+ *   depth: 'light',
+ *   lenses: string[],
+ *   skipped: boolean,
+ *   materialized: object|null,
+ * }>}
+ */
+export async function runLocalLensReview({
+  baseRef,
+  headRef,
+  changedFiles: injectedChangedFiles,
+  progress,
+  progressTag = 'CODE-REVIEW',
+  gitSpawnFn = gitSpawn,
+  selectLocalLensesFn = selectLocalLenses,
+  runAuditSuiteFn = runAuditSuite,
+}) {
+  const empty = {
+    depth: STORY_SCOPE_LENS_DEPTH,
+    lenses: [],
+    skipped: true,
+    materialized: null,
+  };
+  try {
+    const changedFiles = resolveLensChangeSet({
+      changedFiles: injectedChangedFiles,
+      baseRef,
+      headRef,
+      gitSpawnFn,
+    });
+    const lenses = selectLocalLensesFn({ changedFiles });
+    if (lenses.length === 0) {
+      progress(
+        progressTag,
+        'No local lens matched the Story diff — skipping the lens pass.',
+      );
+      return empty;
+    }
+    const materialized = await runAuditSuiteFn({ auditWorkflows: lenses });
+    progress(
+      progressTag,
+      `Ran ${lenses.length} local lens(es) at ${STORY_SCOPE_LENS_DEPTH} depth: ${lenses.join(', ')}.`,
+    );
+    return {
+      depth: STORY_SCOPE_LENS_DEPTH,
+      lenses,
+      skipped: false,
+      materialized,
+    };
+  } catch (err) {
+    // The lens pass is advisory: a git or materialization failure must not
+    // fail the close. Log and degrade to a skipped envelope.
+    progress(
+      progressTag,
+      `⚠️ local lens pass failed (continuing without it): ${err?.message ?? err}`,
+    );
+    return empty;
+  }
+}

package/.agents/scripts/lib/orchestration/story-close/phases/review-core.js

@@ -0,0 +1,120 @@
+/**
+ * phases/review-core.js — the shared Story-scope review spine.
+ *
+ * Extracted from `phases/code-review.js` (Story #4603). `runStoryReviewCore` is
+ * the one implementation both close paths call `runCodeReview` through — the
+ * epic-attached phase (`code-review.js#runStoryCodeReview`) and the standalone
+ * v2 path (`single-story-close/phases/code-review.js#runStoryScopeReview`) —
+ * so it belongs to neither and lives here rather than inside one path's phase
+ * file (Story #3653 established the shared-spine contract).
+ */
+
+import { gitSpawn } from '../../../git-utils.js';
+import { computeChangeSet } from '../../change-set.js';
+import { runCodeReview } from '../../code-review.js';
+import { runLocalLensReview } from './local-lens-review.js';
+
+/**
+ * Invoke `runCodeReviewFn` with the canonical Story-scope envelope and return
+ * the raw result.
+ *
+ * The caller is responsible for error handling and result interpretation —
+ * this function propagates throws rather than swallowing them, because the
+ * two callers have different advisory postures:
+ *
+ *   - Epic-attached close: swallows throws (non-blocking advisory, same as
+ *     `refresh.js`).
+ *   - Standalone close: propagates throws (a review failure stops the close).
+ *
+ * Review depth is not passed in: `runCodeReview` derives it from the changed
+ * files — their sensitive-path intersection plus their count (Story #4542, which
+ * retired the planner-authored risk envelope this spine used to forward). Depth
+ * remains an **input-only** signal: it tells the provider how thorough to be and
+ * never alters the review's output envelope or the posted structured-comment
+ * body.
+ *
+ * Story #4593 — this spine is the **single injection point** for the change set.
+ * It enumerates `baseRef...headRef` exactly once via {@link computeChangeSet}
+ * and threads the resulting list into both the local-lens pass and
+ * `runCodeReview`, which otherwise each enumerated the diff for themselves. Both
+ * consumers ultimately route through `deriveChangeLevel`, so feeding them one
+ * list is what makes the lens roster and the review depth provably agree about
+ * what changed — even when a commit lands between the two calls.
+ *
+ * Story #4603 — the invariant now holds on the failure path too: an unenumerable
+ * diff injects an explicit `null`, and both consumers distinguish that from
+ * `undefined` ("nobody enumerated") rather than re-spawning git.
+ *
+ * @param {{
+ *   storyId: number|string,
+ *   baseRef: string,
+ *   headRef: string,
+ *   commentTargetId?: number|null,
+ *   provider: object,
+ *   progress: (tag: string, msg: string) => void,
+ *   progressTag?: string,
+ *   gitSpawnFn?: import('../../change-set.js').GitSpawnFn,
+ *   computeChangeSetFn?: typeof computeChangeSet,
+ *   runCodeReviewFn?: typeof runCodeReview,
+ *   runLocalLensReviewFn?: typeof runLocalLensReview,
+ * }} args
+ * @returns {Promise<object>} Raw result envelope from `runCodeReview`, augmented
+ *   with a `localLensReview` field carrying the Story-scope local-lens pass
+ *   outcome (Epic #4405, Story #4409) and the `changeSet` this run computed
+ *   (Story #4593).
+ */
+export async function runStoryReviewCore({
+  storyId,
+  baseRef,
+  headRef,
+  commentTargetId = null,
+  provider,
+  progress,
+  progressTag = 'CODE-REVIEW',
+  gitSpawnFn = gitSpawn,
+  computeChangeSetFn = computeChangeSet,
+  runCodeReviewFn = runCodeReview,
+  runLocalLensReviewFn = runLocalLensReview,
+}) {
+  const storyIdNum = Number(storyId);
+
+  // The one enumeration per close run. Every consumer below is injected from
+  // this list; none of them re-derives the diff. `files` is `null` when the
+  // diff is unenumerable — an explicit "already tried" signal both consumers
+  // honour without retrying (Story #4603).
+  const changeSet = computeChangeSetFn({ baseRef, headRef, gitSpawnFn });
+
+  const opts = {
+    scope: 'story',
+    ticketId: storyIdNum,
+    baseRef,
+    headRef,
+    provider,
+    changedFiles: changeSet.files,
+    gitSpawnFn,
+    logger: {
+      info: (m) => progress(progressTag, m),
+      warn: (m) => progress(progressTag, `⚠️ ${m}`),
+    },
+  };
+  if (commentTargetId != null) {
+    opts.commentTargetId = commentTargetId;
+  }
+
+  // Shift-left local-lens pass (Epic #4405). Runs matched local lenses at
+  // `light` depth against the actual Story diff, inside this close-subprocess
+  // spine so the maker never grades its own work. Advisory — it never blocks
+  // the close and its outcome rides on the returned envelope for downstream
+  // consumers.
+  const localLensReview = await runLocalLensReviewFn({
+    baseRef,
+    headRef,
+    changedFiles: changeSet.files,
+    progress,
+    progressTag,
+    gitSpawnFn,
+  });
+
+  const result = await runCodeReviewFn(opts);
+  return { ...result, localLensReview, changeSet };
+}

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

@@ -165,13 +165,35 @@ function stripListMarker(line) {
   return line.replace(/^-\s+(?:\[\s*[xX ]?\s*\]\s+)?/, '').trim();
 }
 
+// Humanized PathEntry bullet (Story #4600): `path` — assumption. This is the
+// shape serialize() now emits for `## Changes` / `## References`; the legacy
+// inline-JSON object bullet remains accepted at parse time indefinitely (live
+// issue bodies are never rewritten).
+const HUMANIZED_PATH_ENTRY_RE = /^`([^`]+)`\s+—\s+(\S+)$/;
+
+// 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.
+const AC_PREFIX_RE = /^AC-\d+:\s+/;
+
+// Visible wide-rationale line (Story #4600): `> **Wide:** <reason>` rendered
+// under `## Goal`. Presentation only — the `<!-- meta -->` block stays the
+// canonical machine carrier, so the parser skips this line wherever it
+// appears (same treatment as the authored-provenance marker).
+const WIDE_MARKER_LINE_RE = /^>\s*\*\*Wide:\*\*/;
+
 /**
  * Parse a single `changes` / `references` bullet into a `PathEntry`.
  *
- * Object form: `{ path: "...", assumption: "creates" }` (stored as
- * `- { "path": "...", "assumption": "..." }` or just recognized from the
- * structured body directly — when deserializing from a structured object
- * that was never serialized to markdown, the entry arrives as-is).
+ * Accepted markdown shapes (both parsed indefinitely — live issue bodies
+ * are never rewritten):
+ *   - Humanized bullet (canonical serialize() output since Story #4600):
+ *     `` `src/x.js` — refactors-existing ``
+ *   - Legacy inline-JSON object bullet:
+ *     `- { "path": "...", "assumption": "..." }`
+ *
+ * A structured object entry (from a parsed JSON body that was never
+ * serialized to markdown) arrives as-is and is validated directly.
  *
  * @param {string|object} raw
  * @param {string[]} warnings
@@ -197,6 +219,21 @@ function parsePathEntry(raw, warnings) {
   const str = typeof raw === 'string' ? raw.trim() : String(raw).trim();
   if (str.length === 0) return null;
 
+  // Humanized bullet shape (the canonical serialize() output since
+  // Story #4600): `path` — assumption.
+  const humanized = str.match(HUMANIZED_PATH_ENTRY_RE);
+  if (humanized) {
+    const path = humanized[1].trim();
+    if (path.length > 0 && FILE_ASSUMPTION_VALUES.includes(humanized[2])) {
+      return { path, assumption: humanized[2] };
+    }
+    // Recognized the humanized shape but the fields are invalid: fail closed.
+    throw new StoryBodyParseError(
+      `changes/references entry is a humanized bullet but not a valid PathEntry: ${str.slice(0, 120)}`,
+      { field: 'changes', raw: str },
+    );
+  }
+
   // Try to detect inline JSON object shape: `{ "path": "...", "assumption": "..." }`
   if (str.startsWith('{')) {
     try {
@@ -433,6 +470,14 @@ function splitSections(markdown) {
       continue;
     }
 
+    // The visible `> **Wide:** <reason>` rationale line is presentation only
+    // (Story #4600): the meta block remains the canonical carrier for
+    // `wide.reason`, so this line must not bleed into the goal (or any other)
+    // section. Skip it wherever it appears.
+    if (WIDE_MARKER_LINE_RE.test(line)) {
+      continue;
+    }
+
     if (inPreamble) {
       preambleLines.push(line);
     } else if (currentSection !== null) {
@@ -637,7 +682,11 @@ export function parse(input) {
     sections.get('changes') ?? [],
     warnings,
   );
-  const acceptance = parseTextListSection(sections.get('acceptance') ?? []);
+  // The AC-<n> checkbox prefix is presentation-only (Story #4600): strip it
+  // so acceptance[] round-trips byte-identical to the authored array.
+  const acceptance = parseTextListSection(sections.get('acceptance') ?? []).map(
+    (a) => a.replace(AC_PREFIX_RE, ''),
+  );
   const verify = parseTextListSection(sections.get('verify') ?? []);
   const references = parsePathEntrySection(
     sections.get('references') ?? [],
@@ -820,8 +869,10 @@ function parseStructuredObject(obj) {
  */
 function serializePathEntry(entry) {
   if (typeof entry === 'string') return entry;
-  // Canonical object form: render as JSON inline for round-trip fidelity.
-  return JSON.stringify({ path: entry.path, assumption: entry.assumption });
+  // 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}`;
 }
 
 /**
@@ -845,6 +896,18 @@ const SERIALIZE_SECTIONS = [
         ? `## Goal\n${goal.trim()}`
         : null,
   },
+  {
+    // Visible wide-rationale line (Story #4600), rendered directly under
+    // `## Goal`. Presentation only: the `<!-- meta -->` block remains the
+    // canonical machine carrier and the parser skips this line, so `wide`
+    // round-trips through the meta block alone. Absent/invalid wide emits
+    // nothing, keeping every non-wide body byte-identical to before.
+    field: 'wide',
+    render: (wide) => {
+      const normalized = normalizeWide(wide);
+      return normalized === null ? null : `> **Wide:** ${normalized.reason}`;
+    },
+  },
   {
     // Optional v2 intra-Story delivery slice plan. Single-token `## Slicing`
     // heading (recognized by the `[\w-]+` field-heading regex). Verbatim text
@@ -873,10 +936,14 @@ const SERIALIZE_SECTIONS = [
         : null,
   },
   {
+    // Each checkbox carries a stable 1-based `AC-<n>:` handle (Story #4600)
+    // so humans and reviewers can reference criteria by number. The prefix
+    // is presentation-only — parse() strips it, and validators compare the
+    // top-level acceptance[] array, so numbering never affects gating.
     field: 'acceptance',
     render: (acceptance) =>
       Array.isArray(acceptance) && acceptance.length > 0
-        ? `## Acceptance\n${acceptance.map((a) => `- [ ] ${a}`).join('\n')}`
+        ? `## Acceptance\n${acceptance.map((a, i) => `- [ ] AC-${i + 1}: ${a}`).join('\n')}`
         : null,
   },
   {

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

@@ -26,9 +26,8 @@ import {
  */
 export function renderDecomposerSystemPrompt({
   maxTickets = LIMITS_DEFAULTS.maxTickets,
-  epicId = null,
 } = {}) {
-  return render2TierPrompt({ maxTickets, epicId });
+  return render2TierPrompt({ maxTickets });
 }
 
 /**
@@ -37,7 +36,7 @@ export function renderDecomposerSystemPrompt({
  * on the Story body so the executing agent has everything it needs in one
  * ticket. Thematic grouping lives as prose in the Epic body / Tech Spec.
  */
-function render2TierPrompt({ maxTickets, epicId = null }) {
+function render2TierPrompt({ maxTickets }) {
   // v2 Stage 3: default-single — emit one Story unless the split policy clears.
   // Capacity thresholds are sourced from the single DEFAULT_MODEL_CAPACITY
   // constant (ticket-validator-sizing.js) so the prompt and the validator
@@ -64,13 +63,6 @@ function render2TierPrompt({ maxTickets, epicId = null }) {
     advisoryCaveat,
     newFileContract,
   } = AUTHORING_ALTITUDE_GUIDANCE;
-  // The namespaced AC-tag token the wave-0 BDD scaffold section below must
-  // require on every scaffolded scenario (Story #4301). When the Epic ID is
-  // known at render time, interpolate the concrete tag so the author has no
-  // placeholder to get wrong; otherwise fall back to the documented pattern.
-  const acTagExample = Number.isInteger(epicId)
-    ? `@epic-${epicId}-ac-1`
-    : '@epic-<id>-ac-N';
   return `You are an expert Senior Project Manager and Orchestrator.
 Your job is to turn a plan seed / Tech Spec into a Story ticket array for an AI Agent to execute.
 
@@ -154,6 +146,10 @@ The serialized \`body\` string renders these markdown sections (in order):
 - **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.
+- **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. Resolve the unknown before authoring, or restate it as a declarative Key Assumption the agent can act on.
 - **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.
 
 #### AUTHORING ALTITUDE — BINDING ACCEPTANCE vs ADVISORY CHANGES:
@@ -229,9 +225,8 @@ When the Acceptance Spec contains **one or more \`Disposition: new\` rows**, you
 - **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" }\`.
-- **acceptance**: MUST assert (a) every new \`.feature\` file exists, (b) every new scenario within them carries an \`@skip\` tag, AND (c) every new scenario also carries its **namespaced per-Epic AC tag** \`${acTagExample}\` (one tag per AC ID the scenario satisfies — see below). Keep these observable (a grep/validate command exits 0, a file exists at a path).
-- **Namespaced AC tag is REQUIRED at scaffold time, not only at de-skip time.** Phase 7 finalize's \`acceptance-spec-reconciler.js\` matches AC IDs only against \`@epic-<id>-ac-*\` / \`@pending\` tags in \`tests/features/**\` — a bare \`@ac-N\` tag is deliberately ignored to prevent cross-Epic collision. A scaffolded scenario that carries \`@skip\` but omits \`@epic-<id>-ac-N\` reads as \`missing[]\` at finalize and aborts the close even after the implementation Story de-skips it, because the tag was never added. Tag each scenario with both \`@skip\` AND \`${acTagExample}\` (substituting the AC's own number) in this SAME wave-0 pass — do not defer the AC tag to the later de-skip edit.
-- **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, AND a check that every new AC ID's namespaced tag (\`${acTagExample}\`) appears in the scaffolded files, e.g. \`grep -q '${acTagExample}' tests/features/<area>/<file>.feature (validate)\` for each new AC row.
+- **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.