mandrel 1.77.0 → 1.79.0

package/.agents/scripts/lib/loop-units/validate-loop-unit.js

@@ -0,0 +1,197 @@
+/**
+ * lib/loop-units/validate-loop-unit.js — loop-unit frontmatter validator.
+ *
+ * Parses a loop-unit markdown file's YAML frontmatter and AJV-validates
+ * it against `.agents/schemas/loop-unit.schema.json` (Ajv2020). Mirrors
+ * the validation pattern established by `lib/spec/loader.js` (Ajv2020 +
+ * ajv-formats + js-yaml, cached compiled validator, normalised
+ * `{ path, message }` issues).
+ *
+ * A "loop unit" is a markdown file under `.agents/workflows/loops/` whose
+ * leading `---`-fenced YAML frontmatter block defines a recurring unit of
+ * work (cadence, goal, conditional verify, round cap, exhaustion policy).
+ *
+ * Public surface:
+ *   • `parseFrontmatter(source)` → extracts and YAML-parses the leading
+ *     `---`-fenced block. Returns the parsed object (or `{}` for an empty
+ *     block). Throws `LoopUnitParseError` when the block is absent or the
+ *     YAML does not parse.
+ *   • `validateLoopUnit(filePath, opts?)` → reads the file, parses its
+ *     frontmatter, validates against the schema, and returns
+ *     `{ valid, issues, data }`. `issues` is an array of
+ *     `{ path, message }` (empty when valid). Never throws on a *validation*
+ *     failure — it reports it via `valid: false` — but does throw
+ *     `LoopUnitParseError` for an unreadable file or unparseable
+ *     frontmatter so callers can distinguish "structurally broken file"
+ *     from "schema-invalid unit".
+ *
+ * The module makes no GitHub calls and no process mutations; it is pure
+ * file I/O + schema validation. The `opts` bag accepts `{ schemaPath, fs }`
+ * so tests can point at a sandbox schema without monkey-patching globals.
+ */
+
+import {
+  existsSync as defaultExistsSync,
+  readFileSync as defaultReadFileSync,
+} from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import yaml from 'js-yaml';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// scripts/lib/loop-units/ → scripts/lib/ → scripts/ → .agents/
+const PROJECT_AGENTS_DIR = path.resolve(__dirname, '..', '..', '..');
+export const DEFAULT_SCHEMA_PATH = path.join(
+  PROJECT_AGENTS_DIR,
+  'schemas',
+  'loop-unit.schema.json',
+);
+
+const defaultFsAdapter = Object.freeze({
+  existsSync: defaultExistsSync,
+  readFileSync: defaultReadFileSync,
+});
+
+let cachedValidator = null;
+let cachedValidatorKey = null;
+
+/**
+ * Compile (and cache) the Ajv2020 validator for the loop-unit schema.
+ * Cached by absolute schema path so tests can swap to a sandbox schema.
+ *
+ * @param {string} schemaPath
+ * @param {{ readFileSync: typeof defaultReadFileSync }} fs
+ * @returns {(data: unknown) => boolean}
+ */
+function getValidator(schemaPath, fs) {
+  if (cachedValidator && cachedValidatorKey === schemaPath) {
+    return cachedValidator;
+  }
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+  cachedValidator = ajv.compile(schema);
+  cachedValidatorKey = schemaPath;
+  return cachedValidator;
+}
+
+/**
+ * Raised when a loop-unit file cannot be read, has no YAML frontmatter
+ * block, or the frontmatter does not parse as YAML.
+ */
+export class LoopUnitParseError extends Error {
+  /**
+   * @param {string} filePath
+   * @param {string} reason
+   */
+  constructor(filePath, reason) {
+    super(`Loop unit ${filePath} could not be parsed: ${reason}`);
+    this.name = 'LoopUnitParseError';
+    this.filePath = filePath;
+    this.reason = reason;
+  }
+}
+
+// Leading `---`-fenced YAML block. Tolerates CRLF and a leading BOM. The
+// closing fence is a `---` (or `...`) on its own line.
+const FRONTMATTER_RE = /^?---\r?\n([\s\S]*?)\r?\n(?:---|\.\.\.)\s*(?:\r?\n|$)/;
+
+/**
+ * Extract and YAML-parse the leading `---`-fenced frontmatter block from a
+ * markdown source string.
+ *
+ * @param {string} source        raw file contents
+ * @param {string} [filePath]    used only for error messages
+ * @returns {object}             the parsed frontmatter object (`{}` if empty)
+ * @throws {LoopUnitParseError}  when no fence is present or the YAML fails
+ */
+export function parseFrontmatter(source, filePath = '<string>') {
+  const match = FRONTMATTER_RE.exec(source);
+  if (!match) {
+    throw new LoopUnitParseError(
+      filePath,
+      'no YAML frontmatter block (expected a leading "---" fence)',
+    );
+  }
+  let parsed;
+  try {
+    parsed = yaml.load(match[1], { filename: filePath });
+  } catch (err) {
+    throw new LoopUnitParseError(
+      filePath,
+      `frontmatter is not valid YAML: ${err.message}`,
+    );
+  }
+  if (parsed == null) return {};
+  if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new LoopUnitParseError(
+      filePath,
+      'frontmatter must be a YAML mapping',
+    );
+  }
+  return parsed;
+}
+
+/**
+ * Convert Ajv's error array into a `{ path, message }` shape. For
+ * `required` errors Ajv leaves the missing property in
+ * `params.missingProperty` rather than the instance path, so we append it
+ * so the caller sees `/loop/verify` instead of `/loop` and the message
+ * names the missing field.
+ *
+ * @param {Array<{instancePath:string,message:string,keyword:string,params?:Record<string,unknown>}>} ajvErrors
+ * @returns {Array<{path:string,message:string}>}
+ */
+function normaliseAjvErrors(ajvErrors) {
+  return (ajvErrors ?? []).map((err) => {
+    let p = err.instancePath || '/';
+    let message = err.message ?? 'validation failed';
+    if (
+      err.keyword === 'required' &&
+      typeof err.params?.missingProperty === 'string'
+    ) {
+      const sep = p === '/' ? '' : '/';
+      p = `${p}${sep}${err.params.missingProperty}`;
+      message = `must have required property '${err.params.missingProperty}'`;
+    }
+    return { path: p, message };
+  });
+}
+
+/**
+ * Read, parse, and schema-validate a loop-unit markdown file.
+ *
+ * @param {string} filePath
+ * @param {{ schemaPath?: string, fs?: typeof defaultFsAdapter }} [opts]
+ * @returns {{ valid: boolean, issues: Array<{path:string,message:string}>, data: object }}
+ * @throws {LoopUnitParseError} when the file is unreadable or its
+ *   frontmatter is missing/unparseable.
+ */
+export function validateLoopUnit(filePath, opts = {}) {
+  const fs = opts.fs ?? defaultFsAdapter;
+  const schemaPath = opts.schemaPath ?? DEFAULT_SCHEMA_PATH;
+
+  if (!fs.existsSync(filePath)) {
+    throw new LoopUnitParseError(filePath, 'file does not exist');
+  }
+
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    throw new LoopUnitParseError(filePath, `unreadable: ${err.message}`);
+  }
+
+  const data = parseFrontmatter(raw, filePath);
+  const validate = getValidator(schemaPath, fs);
+  const ok = validate(data);
+
+  return {
+    valid: ok,
+    issues: ok ? [] : normaliseAjvErrors(validate.errors),
+    data,
+  };
+}

package/.agents/scripts/lib/mandrel-catalog.js

@@ -140,6 +140,42 @@ export function buildCatalog(workflowsDir) {
   return catalog;
 }
 
+/**
+ * Build the loop-unit catalog from a workflows directory's `loops/`
+ * namespace. Loop units live at `.agents/workflows/loops/<name>.md` and
+ * project to the namespaced `/loops:<name>` slash command (Story #4289).
+ * They are catalogued separately from the flat top-level commands because
+ * they carry a distinct invocation form.
+ *
+ * Returns an empty array when the `loops/` subdirectory is absent (the
+ * common case before the starter loops land in a later Story) — an absent
+ * namespace is a clean "no loop units", not an error.
+ *
+ * @param {string} workflowsDir — absolute path to `.agents/workflows/`.
+ * @returns {Array<{ name: string, description: string | null, vague: boolean }>}
+ */
+export function buildLoopCatalog(workflowsDir) {
+  const loopsDir = path.join(workflowsDir, 'loops');
+  if (!fs.existsSync(loopsDir)) return [];
+  const entries = fs.readdirSync(loopsDir, { withFileTypes: true });
+  const catalog = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (!entry.name.endsWith('.md')) continue;
+    if (entry.name === 'README.md') continue;
+    const filePath = path.join(loopsDir, entry.name);
+    const source = fs.readFileSync(filePath, 'utf8');
+    const description = extractDescription(source);
+    catalog.push({
+      name: entry.name.replace(/\.md$/, ''),
+      description,
+      vague: isVagueDescription(description),
+    });
+  }
+  catalog.sort((a, b) => a.name.localeCompare(b.name));
+  return catalog;
+}
+
 /**
  * Render the catalog as a plain-markdown bullet list. Kept as a
  * lightweight alternative rendering of the same catalog backend that

package/.agents/scripts/lib/orchestration/epic-plan-decompose/phases/context.js

@@ -22,9 +22,13 @@ import { applyBudget } from '../../planning-context-budget.js';
 
 export function buildDecomposerSystemPrompt(
   heuristics = [],
-  { maxTickets, maxTokenBudget } = {},
+  { maxTickets, maxTokenBudget, epicId } = {},
 ) {
-  const base = renderDecomposerSystemPrompt({ maxTickets, maxTokenBudget });
+  const base = renderDecomposerSystemPrompt({
+    maxTickets,
+    maxTokenBudget,
+    epicId,
+  });
   const heuristicsStr =
     heuristics.length > 0
       ? `### RISK HEURISTICS (planning metadata if any apply):\n- ${heuristics.join('\n- ')}`
@@ -121,6 +125,7 @@ export async function buildDecompositionContext(
   const systemPrompt = buildDecomposerSystemPrompt(heuristics, {
     maxTickets,
     maxTokenBudget,
+    epicId,
   });
 
   const budgeted = applyBudget(

package/.agents/scripts/lib/orchestration/epic-spec-reconciler-diff.js

@@ -80,6 +80,7 @@
  *     issue with an empty body.
  */
 
+import { composeStoryBody } from '../../providers/github/tickets.js';
 import { assertPlanLabelAllowList } from './epic-spec-reconciler-discriminator.js';
 import {
   closeOp,
@@ -208,34 +209,6 @@ function stripFooter(body) {
   return value.replace(ORCHESTRATOR_FOOTER_RE, '').replace(/\s+$/, '');
 }
 
-/**
- * Render the canonical orchestrator footer (no leading newline). Format
- * matches the byte-stable shape that the cascade-reading consumers
- * (story-init, dispatcher, manifest, close-gate) parse line-anchored:
- *
- *   ---
- *   parent: #<parentId>
- *   [Epic: #<epicId>]            // only when epicId !== parentId
- *
- *   [blocked by #<dep>]          // one per dependency
- *
- * @param {{parentId: number, epicId?: number, dependencies?: number[]}} opts
- * @returns {string}
- */
-function renderFooter({ parentId, epicId, dependencies = [] }) {
-  const lines = ['---', `parent: #${parentId}`];
-  if (epicId !== undefined && epicId !== null && epicId !== parentId) {
-    lines.push(`Epic: #${epicId}`);
-  }
-  if (dependencies.length > 0) {
-    lines.push('');
-    for (const dep of dependencies) {
-      lines.push(`blocked by #${dep}`);
-    }
-  }
-  return lines.join('\n');
-}
-
 /**
  * Compose the canonical orchestrator footer onto a spec body for non-epic
  * entities. Resolves `parentSlug`/`dependsOn` slugs against the running
@@ -246,12 +219,19 @@ function renderFooter({ parentId, epicId, dependencies = [] }) {
  * the YAML spec writes just the description, silently stripping
  * `parent: #N` / `Epic: #M` / `blocked by #X` and breaking the cascade.
  *
- * Story #3185 — the footer compose/strip logic is inlined here rather
- * than reused from the legacy Task-body renderer module. That renderer
- * was removed, so the diff engine carries its own footer shape. The shape
- * is byte-identical to the legacy renderer's `parent: #<n>` /
- * `Epic: #<m>` / `blocked by #<x>` output so cascade-readers continue
- * to parse it unchanged.
+ * Story #4300 — the footer rendering is single-sourced from
+ * `composeStoryBody` (`providers/github/tickets.js`), the same helper the
+ * CREATE path (`epic-spec-reconciler-apply.js` → `provider.createTicket`)
+ * uses. Story #3185 previously inlined a parallel `renderFooter` here to
+ * avoid depending on the (now-removed) legacy Task-body renderer; that
+ * inlined copy silently diverged from `composeStoryBody` by gating the
+ * `Epic: #<id>` line on `epicId !== parentId` — a 3-tier-era condition
+ * that is always false under the 2-tier hierarchy (a Story's parent IS
+ * the Epic), so force re-decompose (`/plan --force`, which routes through
+ * this UPDATE path) silently dropped `Epic: #<id>` from every refreshed
+ * Story body and broke `story-init.js`'s hierarchy resolution. Importing
+ * `composeStoryBody` directly makes that divergence structurally
+ * impossible going forward.
  *
  * @param {{entity: string, parentSlug?: string|null, dependsOn?: string[]}} specEntity
  * @param {string} specBody
@@ -284,8 +264,7 @@ function composeBodyWithFooter(specEntity, specBody, ctx) {
   // included) or emits a canonical-form body. With the strip, the
   // function is idempotent against its own output.
   const head = stripFooter(specBody);
-  const footer = renderFooter({ parentId, epicId, dependencies });
-  return `${head}\n\n${footer}`;
+  return composeStoryBody({ body: head, parentId, epicId, dependencies });
 }
 
 /**

package/.agents/scripts/lib/orchestration/lifecycle/emit-loop-tick.js

@@ -0,0 +1,183 @@
+/**
+ * emit-loop-tick.js — Story #4287 (Epic #4284).
+ *
+ * Programmatic helper that emits a single `loop.tick` lifecycle event
+ * THROUGH the lifecycle bus so a host-driven loop (e.g. a `/loop`-style
+ * recurring command or a long-running poll) lands a per-pass record in
+ * the on-disk ledger the `/deliver` idle watchdog already scans. The
+ * record is what keeps a host loop from running silently: each round
+ * appends an inspectable `emitted` line a reconciler can read for
+ * forward-progress evidence.
+ *
+ * Distinct from `story.heartbeat` (emit-story-heartbeat.js): the
+ * heartbeat carries Story-phase info for a single in-flight Story and is
+ * always Epic-scoped (its ledger path is `epicLedgerPath(epicId)`). A
+ * host loop is not bound to a Story tier, so `loop.tick` carries a
+ * free-form `loopName`, a monotonic `round` counter, the loop's
+ * configured `cadence` label, and a per-round `status` instead. Keeping
+ * the two events separate means a loop tick never masquerades as Story
+ * progress (and vice versa).
+ *
+ * Bus path (Story acceptance: "Emitting a loop.tick event THROUGH the
+ * lifecycle bus appends a record to the per-run ledger"): this helper
+ * constructs a `Bus`, registers a `LedgerWriter` against it, and calls
+ * `bus.emit('loop.tick', payload)`. The bus validates the payload against
+ * `loop.tick.schema.json` before any listener runs, and the
+ * LedgerWriter's privileged `onEmitted` hook lands the `emitted` record
+ * on disk — exactly the same persistence path every other lifecycle
+ * event flows through. The helper does NOT bypass the bus with a direct
+ * `appendFileSync`; routing through the bus is what gives the record its
+ * schema-validated, seqId-stamped guarantee.
+ *
+ * Schema contract (loop.tick.schema.json):
+ *   { event, loopName, round, cadence, status, timestamp }
+ *
+ * The schema declares `additionalProperties: false`, so this emitter's
+ * signature is deliberately narrow: only the schema-allowed fields are
+ * accepted. `status` is one of running|done|blocked.
+ *
+ * Ledger path resolution: a caller supplies EITHER an explicit
+ * `ledgerPath` (the host-loop case — the loop owns where its ledger
+ * lives) OR an `epicId`, in which case the canonical
+ * `epicLedgerPath(epicId)` is used so an Epic-scoped loop's ticks land
+ * in the same `temp/epic-<id>/lifecycle.ndjson` the rest of the run
+ * reads. Exactly one of the two MUST be supplied.
+ */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { epicLedgerPath } from '../../config/temp-paths.js';
+import { createBus } from './bus.js';
+import { createLedgerWriter } from './ledger-writer.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_DIR = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  '..',
+  'schemas',
+  'lifecycle',
+);
+
+const VALID_STATUSES = new Set(['running', 'done', 'blocked']);
+
+/**
+ * Parse `temp/epic-<id>/lifecycle.ndjson` (or any
+ * `<dir>/epic-<id>/lifecycle.ndjson`) back into `{ tempRoot, epicId }`
+ * so a LedgerWriter — which is constructed from `{ epicId, tempRoot }`
+ * rather than a raw path — can be bound to the supplied ledger path.
+ *
+ * The LedgerWriter intentionally re-derives the ledger path from its
+ * `tempRoot` + `epicId` (so it can recreate the directory if a listener
+ * moves it mid-run), so we decompose the path the caller gave us into
+ * those two parts here.
+ *
+ * @param {string} ledgerPath
+ * @returns {{ tempRoot: string, epicId: number }}
+ */
+function decomposeLedgerPath(ledgerPath) {
+  const epicDir = path.dirname(ledgerPath);
+  const tempRoot = path.dirname(epicDir);
+  const epicDirName = path.basename(epicDir);
+  const m = /^epic-(\d+)$/.exec(epicDirName);
+  if (!m) {
+    throw new Error(
+      `emitLoopTick: ledgerPath does not match <tempRoot>/epic-<id>/lifecycle.ndjson layout (got ${ledgerPath})`,
+    );
+  }
+  const epicId = Number.parseInt(m[1], 10);
+  return { tempRoot, epicId };
+}
+
+/**
+ * Emit exactly one `loop.tick` event through the lifecycle bus, landing
+ * an `emitted` (and `completed`) NDJSON record in the resolved ledger.
+ *
+ * @param {object} opts
+ * @param {string} opts.loopName     Free-form loop identifier (non-empty).
+ * @param {number} opts.round        Monotonic pass counter (integer >= 0).
+ * @param {string} opts.cadence      Configured interval label, e.g. '5m'.
+ * @param {string} [opts.status='running']
+ *                                   One of running|done|blocked.
+ * @param {string} [opts.timestamp]  ISO-8601 wall clock. Defaults to now().
+ * @param {number} [opts.epicId]     When supplied (and no `ledgerPath`),
+ *                                   the canonical `epicLedgerPath(epicId)`
+ *                                   is used for the ledger.
+ * @param {object} [opts.config]     Optional resolved config for tempRoot
+ *                                   (only consulted on the `epicId` path).
+ * @param {string} [opts.ledgerPath] Explicit ledger path (host-loop case).
+ *                                   Mutually exclusive with `epicId`.
+ * @returns {Promise<{ ledgerPath: string, payload: object, seqId: number }>}
+ */
+export async function emitLoopTick(opts) {
+  const {
+    loopName,
+    round,
+    cadence,
+    status = 'running',
+    timestamp = new Date().toISOString(),
+    epicId,
+    config,
+    ledgerPath: ledgerPathOverride,
+  } = opts ?? {};
+
+  if (typeof loopName !== 'string' || loopName.length === 0) {
+    throw new Error('emitLoopTick: loopName must be a non-empty string');
+  }
+  if (!Number.isInteger(round) || round < 0) {
+    throw new Error('emitLoopTick: round must be a non-negative integer');
+  }
+  if (typeof cadence !== 'string' || cadence.length === 0) {
+    throw new Error('emitLoopTick: cadence must be a non-empty string');
+  }
+  if (!VALID_STATUSES.has(status)) {
+    throw new Error(
+      `emitLoopTick: status "${status}" must be one of: ${[...VALID_STATUSES].join(', ')}`,
+    );
+  }
+
+  const hasEpicId = epicId !== undefined;
+  const hasLedgerPath = ledgerPathOverride !== undefined;
+  if (hasEpicId === hasLedgerPath) {
+    throw new Error('emitLoopTick: supply exactly one of epicId or ledgerPath');
+  }
+
+  let ledgerPath;
+  if (hasLedgerPath) {
+    if (
+      typeof ledgerPathOverride !== 'string' ||
+      ledgerPathOverride.length === 0
+    ) {
+      throw new Error('emitLoopTick: ledgerPath must be a non-empty string');
+    }
+    ledgerPath = ledgerPathOverride;
+  } else {
+    if (!Number.isInteger(epicId) || epicId < 1) {
+      throw new Error('emitLoopTick: epicId must be a positive integer');
+    }
+    ledgerPath = epicLedgerPath(epicId, config);
+  }
+
+  const payload = {
+    event: 'loop.tick',
+    loopName,
+    round,
+    cadence,
+    status,
+    timestamp,
+  };
+
+  // Route through the bus so the payload is schema-validated and the
+  // LedgerWriter's privileged onEmitted hook persists the record — the
+  // same path every lifecycle event flows through.
+  const { tempRoot, epicId: ledgerEpicId } = decomposeLedgerPath(ledgerPath);
+  const bus = createBus({ schemaDir: SCHEMA_DIR });
+  const writer = createLedgerWriter({ epicId: ledgerEpicId, tempRoot });
+  writer.register(bus);
+
+  const { seqId } = await bus.emit('loop.tick', payload);
+  return { ledgerPath: writer.ledgerPath, payload, seqId };
+}

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

@@ -23,6 +23,15 @@ import {
 /**
  * Parse the `Epic: #N` and `parent: #N` references from a Story body.
  *
+ * Story #4300 (defense-in-depth): under the 2-tier hierarchy
+ * (Epic → Story) a Story's `parent: #N` marker always IS the parent
+ * Epic, so when the `Epic: #N` line is missing — e.g. a Story body
+ * refreshed by the reconciler's UPDATE op before Story #4300's
+ * single-sourced footer rendering landed — `epicId` falls back to the
+ * resolved `parentId` rather than reporting `null` and aborting
+ * delivery. A body that carries neither marker still resolves
+ * `epicId: null` (no parent to fall back to).
+ *
  * @param {string} body  Raw Story body Markdown.
  * @returns {{ epicId: number|null, parentId: number|null }}
  */
@@ -30,10 +39,9 @@ export function resolveStoryHierarchy(body) {
   const source = body ?? '';
   const epicMatch = source.match(/(?:^\s*epic:\s*#(\d+))/im);
   const parentMatch = source.match(/(?:^\s*parent:\s*#(\d+))/im);
-  return {
-    epicId: epicMatch ? Number.parseInt(epicMatch[1], 10) : null,
-    parentId: parentMatch ? Number.parseInt(parentMatch[1], 10) : null,
-  };
+  const parentId = parentMatch ? Number.parseInt(parentMatch[1], 10) : null;
+  const epicId = epicMatch ? Number.parseInt(epicMatch[1], 10) : parentId;
+  return { epicId, parentId };
 }
 
 /**

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

@@ -36,8 +36,9 @@ import {
 export function renderDecomposerSystemPrompt({
   maxTickets = LIMITS_DEFAULTS.maxTickets,
   maxTokenBudget = LIMITS_DEFAULTS.maxTokenBudget,
+  epicId = null,
 } = {}) {
-  return render2TierPrompt({ maxTickets, maxTokenBudget });
+  return render2TierPrompt({ maxTickets, maxTokenBudget, epicId });
 }
 
 /**
@@ -46,7 +47,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, maxTokenBudget }) {
+function render2TierPrompt({ maxTickets, maxTokenBudget, epicId = null }) {
   // Sizing thresholds are sourced from the single DEFAULT_TASK_SIZING constant
   // (ticket-validator-sizing.js) so the prompt and the validator cannot drift.
   const { softFiles, hardFiles, maxAcceptance, softAcceptanceCount } =
@@ -66,6 +67,13 @@ function render2TierPrompt({ maxTickets, maxTokenBudget }) {
     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 take a Product Requirements Document (PRD) and a Technical Specification and decompose them into a flat list of Story tickets for an AI Agent to execute.
 
@@ -96,7 +104,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.
+**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\` MUST be a **string** — the serialized markdown produced by \`serialize()\` from \`lib/story-body/story-body.js\`. Do NOT emit \`body\` as a JSON object: an object body throws \`StoryBodyParseError\` in the reconciler (Story #3302) and is discarded by the GitHub provider, producing an empty issue body. 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.
@@ -196,8 +204,9 @@ 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, 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 a tag needs no browser/playwright run. Example: \`grep -rL '@skip' tests/features/<area>/*.feature (validate)\` paired with an existence check.
+- **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.
 - 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.

package/.agents/scripts/providers/github/branch-protection.js

@@ -13,8 +13,8 @@
  * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
  */
 
+import { withTransientRetry } from './errors.js';
 import { parseApiJson } from './request-helpers.js';
-import { withTransientRetry } from './transient-retry.js';
 
 /**
  * Detect a 404 across both error surfaces: