mandrel 1.78.0 → 1.79.0

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/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/skills/core/epic-plan-decompose-author/SKILL.md

@@ -290,13 +290,14 @@ When the Acceptance Spec contains **one or more `Disposition: new` rows**, you M
 - **goal** (in body string): contains the literal token `bdd-scaffold`.
 - **depends_on**: EMPTY (`[]`) — the scaffold runs first, in wave 0.
 - **changes** (in body string): one `{ path, assumption: "creates" }` entry per distinct `.feature` file named in a `new` row.
-- **acceptance** (top-level array): MUST assert (a) every new `.feature` file exists, and (b) every new scenario within them carries an `@skip` tag. Keep items observable (a command exits 0; a file exists at a path).
-- **verify** (top-level array): a grep/validate command (tier `validate`), NOT an e2e runner — verifying that a file exists with a tag needs no browser/playwright run.
+- **acceptance** (top-level array): 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** `@epic-<id>-ac-N` (one tag per AC ID the scenario satisfies). Keep items observable (a command exits 0; a file exists at a path).
+- **The 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 under `tests/features/**` — a bare `@ac-N` tag is deliberately ignored to prevent cross-Epic collision (Story #3362). A scaffolded scenario carrying `@skip` but no `@epic-<id>-ac-N` tag reads as `missing[]` at finalize and throws, aborting close, even after the implementation Story de-skips it — the tag was never added in either pass. Tag each scenario with both `@skip` AND `@epic-<id>-ac-N` (substituting the Epic's real ID and the scenario's own AC number) in this SAME wave-0 commit; do not defer the AC tag to the later de-skip edit.
+- **verify** (top-level array): a grep/validate command (tier `validate`), NOT an e2e runner — verifying that a file exists with the required tags needs no browser/playwright run. Include a check that each new AC ID's namespaced tag is present in the scaffolded files, alongside the `@skip` check.
 - Each implementation Story whose `verify[]` references a scaffolded `.feature` path MUST add `depends_on: ["<scaffold-slug>"]` so the scaffold lands in an earlier wave. Omitting the link trips the soft `missing-bdd-scaffold` finding in `ticket-validator-conflicts.js` (advisory, not a hard block).
 
 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.
 
-**Worked example.** Acceptance Spec with two `new` rows (`AC-1` -> `tests/features/billing/invoice.feature`, `AC-2` -> `tests/features/billing/refund.feature`). The scaffold Story below uses a serialized string `body`, top-level `acceptance`/`verify` arrays, and an empty `depends_on`:
+**Worked example.** Epic #42, Acceptance Spec with two `new` rows (`AC-1` -> `tests/features/billing/invoice.feature`, `AC-2` -> `tests/features/billing/refund.feature`). The scaffold Story below uses a serialized string `body`, top-level `acceptance`/`verify` arrays, an empty `depends_on`, and tags each scenario with both `@skip` and its namespaced `@epic-42-ac-N` tag:
 
     {
       "slug": "scaffold-billing-feature-files",
@@ -306,16 +307,18 @@ When the Acceptance Spec contains **zero `new`-disposition rows** (every row is
       "labels": ["type::story", "persona::qa-engineer"],
       "acceptance": [
         "tests/features/billing/invoice.feature and tests/features/billing/refund.feature both exist on the branch",
-        "every Scenario in the two new feature files is preceded by an @skip tag (grep for un-skipped scenarios returns zero matches)"
+        "every Scenario in the two new feature files is preceded by an @skip tag (grep for un-skipped scenarios returns zero matches)",
+        "the invoice.feature scenario carries @epic-42-ac-1 and the refund.feature scenario carries @epic-42-ac-2"
       ],
       "verify": [
         "test -f tests/features/billing/invoice.feature && test -f tests/features/billing/refund.feature (validate)",
-        "test -z \"$(grep -rL '@skip' tests/features/billing/*.feature)\" (validate)"
+        "test -z \"$(grep -rL '@skip' tests/features/billing/*.feature)\" (validate)",
+        "grep -q '@epic-42-ac-1' tests/features/billing/invoice.feature && grep -q '@epic-42-ac-2' tests/features/billing/refund.feature (validate)"
       ],
-      "body": "## Goal\nbdd-scaffold: create the @skip-tagged feature files the billing-flows implementation Stories verify against, so wave-0 lands them before any implementation Story runs.\n\n## Changes\n- {\"path\": \"tests/features/billing/invoice.feature\", \"assumption\": \"creates\"}\n- {\"path\": \"tests/features/billing/refund.feature\", \"assumption\": \"creates\"}\n\n## Acceptance\n- [ ] tests/features/billing/invoice.feature and tests/features/billing/refund.feature both exist on the branch\n- [ ] every Scenario in the two new feature files is preceded by an @skip tag\n\n## Verify\n- test -f tests/features/billing/invoice.feature && test -f tests/features/billing/refund.feature (validate)\n- test -z \"$(grep -rL '@skip' tests/features/billing/*.feature)\" (validate)\n"
+      "body": "## Goal\nbdd-scaffold: create the @skip-tagged, @epic-42-ac-N-tagged feature files the billing-flows implementation Stories verify against, so wave-0 lands them before any implementation Story runs.\n\n## Changes\n- {\"path\": \"tests/features/billing/invoice.feature\", \"assumption\": \"creates\"}\n- {\"path\": \"tests/features/billing/refund.feature\", \"assumption\": \"creates\"}\n\n## Acceptance\n- [ ] tests/features/billing/invoice.feature and tests/features/billing/refund.feature both exist on the branch\n- [ ] every Scenario in the two new feature files is preceded by an @skip tag\n- [ ] the invoice.feature scenario carries @epic-42-ac-1 and the refund.feature scenario carries @epic-42-ac-2\n\n## Verify\n- test -f tests/features/billing/invoice.feature && test -f tests/features/billing/refund.feature (validate)\n- test -z \"$(grep -rL '@skip' tests/features/billing/*.feature)\" (validate)\n- grep -q '@epic-42-ac-1' tests/features/billing/invoice.feature && grep -q '@epic-42-ac-2' tests/features/billing/refund.feature (validate)\n"
     }
 
-The implementation Stories that later un-skip and flesh out these scenarios each carry `depends_on: ["scaffold-billing-feature-files"]`, placing them in a later wave than the scaffold.
+The implementation Stories that later un-skip and flesh out these scenarios each carry `depends_on: ["scaffold-billing-feature-files"]`, placing them in a later wave than the scaffold. They MUST NOT add the `@epic-42-ac-N` tag themselves — it is already present from the scaffold pass; their job is to remove `@skip` once the scenario passes.
 
 ### SCOPE-OVERLAP FLAGGING (docs/runbook downstream of config work)
 

package/docs/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.79.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.78.0...mandrel-v1.79.0) (2026-06-30)
+
+
+### Fixed
+
+* **decompose-author:** require namespaced [@epic](https://github.com/epic)-<id>-ac-N tag on wave-0 BDD scaffold scenarios (refs [#4301](https://github.com/dsj1984/mandrel/issues/4301)) ([#4304](https://github.com/dsj1984/mandrel/issues/4304)) ([c97d45e](https://github.com/dsj1984/mandrel/commit/c97d45e806a72a8511995d8f606b5be2ef486315))
+* **reconciler:** single-source the parent/Epic body trailer so force re-decompose retains Epic: #<id> (refs [#4300](https://github.com/dsj1984/mandrel/issues/4300)) ([#4303](https://github.com/dsj1984/mandrel/issues/4303)) ([a8e78a9](https://github.com/dsj1984/mandrel/commit/a8e78a9fd946e6f532a59df9cd37237e0d046b2d))
+
 ## [1.78.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.77.0...mandrel-v1.78.0) (2026-06-24)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "1.78.0",
+  "version": "1.79.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",