mandrel 1.86.0 → 1.87.0

package/.agents/instructions.md

@@ -334,6 +334,13 @@ budget grounds.
   spawns (search, doc regeneration, lint, log triage) and keep
   **implementation and design** work on the default capability; name no
   specific model — let the host and operator own the concrete mapping.
+  **Depth compounds the cost.** Sub-agents now carry the `Agent` tool and
+  can nest further (verified depth 2, announced max depth 5; see
+  [#2870](https://github.com/dsj1984/mandrel/issues/2870)), so this
+  spend-per-spawn caution is not one-level — **every** nesting level
+  re-pays the full always-loaded context. Weigh the whole subtree's cost,
+  not just the immediate spawn, before opening a deeper orchestration
+  level, and stay within the supported depth envelope.
 - **Anti-Laziness:** NEVER use placeholder comments like
   `// ... existing code ...`, `/* rest of file */`, or
   `// implementation here`. You MUST output the ENTIRE file or the ENTIRE

package/.agents/rules/git-conventions.md

@@ -142,7 +142,19 @@ operator intervention:
   candidate with unpushed work, a dirty worktree, or a still-open parent
   ticket. A branch a flow leaves behind (e.g. a `/git-deliver` feature branch
   whose PR merges out of band) is therefore reaped automatically at the next
-  workflow boot, not left for the operator to sweep by hand.
+  workflow boot, not left for the operator to sweep by hand. `boot-sweep.js`
+  defaults its `--include` glob to `story-*` — a bare invocation only sweeps
+  Story branches; `/plan` and `/git-deliver` widen the scope to their own
+  branch namespaces (`epic/*`, `feat/*`, `fix/*`, `chore/*`, `docs/*`,
+  `refactor/*`) by passing `--include` explicitly at their boot call site.
+  A branch the planner detects only via the weaker content-equivalence
+  signal (`detectedBy: 'content-merged'`, Story #4395's
+  `git merge-tree --write-tree` probe — content already landed in the base
+  branch by another route, such as a squash-merged Epic PR, with no merged
+  PR or git ancestry of its own) is **never** reaped by the boot sweep: it
+  is report-only, surfaced under `contentMerged` in the result envelope and
+  a routing hint in the summary line (Story #4396), so the operator can
+  send it to `/git-cleanup` for a confirmed, eyeballed reap.
 - **`/git-cleanup` is recovery, not routine.** Run it by hand only to recover
   an unusual state the automated hygiene does not cover — triaging stashes,
   reaping across non-standard branch namespaces, or `--remote` pruning after a

package/.agents/scripts/boot-sweep.js

@@ -17,6 +17,17 @@
  * is swallowed and reported in the result envelope, never thrown, so a
  * caller can wire it into a boot path without risking the host run.
  *
+ * **Content-merged branches are report-only (Story #4396).** The planner
+ * also surfaces branches whose content already landed in the base branch
+ * by another route (a squash-merged Epic PR, a renamed head, a manual
+ * squash merge) via `detectedBy: 'content-merged'` (Story #4395's
+ * `git merge-tree --write-tree` probe) — a weaker signal than a merged PR
+ * or git ancestry, since no CI/GitHub merge check ever validated that
+ * branch's exact diff. This sweep never reaps on that signal alone; it
+ * surfaces the branches under `contentMerged` in the result envelope (and
+ * a routing hint in the human summary) so the operator can send them to
+ * `/git-cleanup` for a confirmed, eyeballed reap.
+ *
  * Usage:
  *   node .agents/scripts/boot-sweep.js [--include <glob>...] \
  *     [--exclude <glob>...] [--current <branch>] [--base <branch>] \
@@ -42,6 +53,10 @@ Runs the protected merged-branch boot sweep non-interactively: reaps every
 local branch whose PR is MERGED and whose HEAD matches the merged headRefOid,
 skipping any candidate the protection partition flags (unpushed work, dirty
 worktree, still-open parent Story), then fast-forwards the base branch.
+Branches detected only via the weaker content-equivalence signal
+(detectedBy: 'content-merged') are never reaped here — they are reported
+under "contentMerged" (and a routing hint in the summary line) for the
+operator to send to /git-cleanup.
 
 Options:
   --include <glob>     Branch glob to sweep (repeatable). Default: story-*
@@ -136,11 +151,31 @@ export async function runBootSweep({
       localDeleted: 0,
       remoteDeleted: 0,
       protected: [],
+      contentMerged: [],
       failures: [],
     };
   }
 }
 
+/**
+ * Build the human-readable one-line summary for a sweep result envelope.
+ * Exported for unit tests (Story #4396). A zero `contentMerged` count keeps
+ * the pre-Story #4396 line byte-identical (silent no-op summary); a nonzero
+ * count appends a routing hint pointing the operator at `/git-cleanup`.
+ *
+ * @param {{ localDeleted: number, remoteDeleted: number, protected?: Array, contentMerged?: Array }} result
+ * @returns {string}
+ */
+export function buildSummaryLine(result) {
+  const protectedCount = result.protected?.length ?? 0;
+  const contentMergedCount = result.contentMerged?.length ?? 0;
+  const contentMergedSuffix =
+    contentMergedCount > 0
+      ? `; ${contentMergedCount} content-merged branch(es) left for /git-cleanup`
+      : '';
+  return `[boot-sweep] reaped ${result.localDeleted} local + ${result.remoteDeleted} remote; protected ${protectedCount}${contentMergedSuffix}.`;
+}
+
 async function main() {
   const { values } = parseArgs({
     options: {
@@ -173,10 +208,7 @@ async function main() {
   if (values.json) {
     Logger.info(JSON.stringify(result, null, 2));
   } else {
-    const protectedCount = result.protected?.length ?? 0;
-    Logger.info(
-      `[boot-sweep] reaped ${result.localDeleted} local + ${result.remoteDeleted} remote; protected ${protectedCount}.`,
-    );
+    Logger.info(buildSummaryLine(result));
   }
 }
 

package/.agents/scripts/git-cleanup.js

@@ -55,11 +55,14 @@ import {
   computeProtectedSet,
 } from './lib/orchestration/git-cleanup/phases/filters.js';
 import {
+  branchLastCommitAt,
   branchTipSha,
   classifyLatestPr,
   probeAllPrs,
+  probeContentEquivalent,
   probeLatestPr,
   probeMergedPr,
+  refExists,
 } from './lib/orchestration/git-cleanup/phases/git-probes.js';
 import { parseCleanupArgs } from './lib/orchestration/git-cleanup/phases/parse-args.js';
 import {
@@ -74,6 +77,7 @@ import {
   renderExecutionLine,
   renderExecutionSummary,
   renderLatestPrSkipLine,
+  renderNotMergedSkipLine,
   renderPruneLine,
 } from './lib/orchestration/git-cleanup/phases/render.js';
 import {
@@ -86,6 +90,7 @@ import {
 
 // Public surface preserved for tests + `single-story-sweep.js`.
 export {
+  branchLastCommitAt,
   branchTipSha,
   buildAllowlistDecider,
   buildGlobFilter,
@@ -105,13 +110,16 @@ export {
   planFastForward,
   planStashes,
   probeAllPrs,
+  probeContentEquivalent,
   probeLatestPr,
   probeMergedPr,
+  refExists,
   renderDeferredLine,
   renderDryRun,
   renderExecutionLine,
   renderExecutionSummary,
   renderLatestPrSkipLine,
+  renderNotMergedSkipLine,
   renderPruneLine,
   stashRefIndex,
 };

package/.agents/scripts/lib/checks/subagent-agent-tool-required.js

@@ -1,30 +1,44 @@
 /**
- * subagent-agent-tool-required — refuse-and-print check.
+ * subagent-agent-tool-required — supported-depth guard (refuse-and-print).
  *
- * Detects sub-agent workflow definitions that declare access to the
- * `Agent` tool (or otherwise document nested Agent dispatch). Nested
- * Agent dispatch is not supported in this Claude Code, so any
- * wave-runner-as-sub-agent or cascading fan-out design that declares
- * `Agent` in its tool list will silently fail at runtime. The remediation
- * is to flatten the fan-out back to the host agent and run sub-agents at
- * one level only.
+ * Nested `Agent` dispatch from a sub-agent is **supported** on this Claude
+ * Code build (verified depth 2, announced max depth 5 — Claude Code
+ * 2.1.202, re-spiked 2026-07-08; see Epic #4385 / watch #2870). A level-1
+ * sub-agent carries `Agent` in its primary toolset and can spawn a working
+ * level-2 sub-agent. Declaring `Agent` in a sub-agent workflow is therefore
+ * a legitimate design choice, **not** an automatic runtime failure.
+ *
+ * What this check guards is the one case that still fails: a fan-out whose
+ * declared nesting depth exceeds the announced/supported ceiling. A dispatch
+ * chain deeper than the harness supports will silently fail at runtime, so a
+ * workflow that declares `Agent` together with a `nesting-depth` beyond the
+ * ceiling is flagged as a blocker. A sub-agent that declares `Agent` at a
+ * supported depth (the common case — an undeclared depth is treated as the
+ * shallow level-1 fan-out) produces no finding.
+ *
+ * This inverts the historical guard (Story #4387): the check used to refuse
+ * `Agent` in *any* sub-agent workflow on the now-false rationale that
+ * sub-agents cannot dispatch. It no longer strips a real capability; it only
+ * catches an over-deep fan-out. The self-healing surface is preserved — it is
+ * re-scoped, not removed.
  *
  * Scope: 'epic-deliver', 'retro'. Surfaces as a blocker at preflight for
  * `epic-deliver` (the fan-out site) and as audit signal at retro.
  *
- * The check is `refuse-and-print` — auto-rewriting a workflow's tool
- * list would silently change runtime behavior in ways the operator may
- * not have intended (the workflow's logic may depend on the missing
- * tool). The fixCommand cites the flatten-fan-out remediation pattern.
+ * The check is `refuse-and-print` — auto-rewriting a workflow's declared
+ * depth or tool list would silently change runtime behavior in ways the
+ * operator may not have intended. The fixCommand explains how to bring the
+ * fan-out back under the ceiling (reduce the declared depth or split the
+ * deepest level out), and is explicit that stripping `Agent` is NOT the fix.
  *
- * Implementation note: we scan `.agents/workflows/*.md` for workflow
- * files whose frontmatter or body identifies them as a sub-agent role
- * AND whose `tools:` declaration includes `Agent`. The marker for
- * "sub-agent" is the phrase `sub-agent` appearing in the description /
- * overview region. This keeps the check stable while the workflow
- * surface evolves — the project doesn't yet have a structured
- * `role: sub-agent` frontmatter field, and the textual marker is what
- * the human contributors actually grep for.
+ * Implementation note: we scan `.agents/workflows/*.md` for workflow files
+ * whose frontmatter or body identifies them as a sub-agent role AND whose
+ * `tools:` declaration includes `Agent`, then read the workflow's declared
+ * `nesting-depth`. The marker for "sub-agent" is the phrase `sub-agent`
+ * appearing in the description / overview region. The depth is read from a
+ * `nesting-depth:` (or `agent-depth:`) frontmatter field, or a
+ * `<!-- nesting-depth: N -->` body marker; an absent declaration is treated
+ * as depth 1 (a single, shallow fan-out level).
  */
 
 import { readdirSync, readFileSync } from 'node:fs';
@@ -32,6 +46,17 @@ import path from 'node:path';
 
 const WORKFLOWS_DIR_DEFAULT = path.join('.agents', 'workflows');
 
+/**
+ * Announced maximum nesting depth the Claude Code harness supports for
+ * sub-agent fan-out. Depth 2 is independently verified; depths 3–5 are
+ * announced but not yet re-spiked (Epic #4385 / watch #2870). A workflow
+ * declaring a fan-out deeper than this ceiling is flagged. Operators can pin
+ * a stricter (or, once verified, looser) ceiling via `state.supportedDepth`.
+ *
+ * @type {number}
+ */
+export const ANNOUNCED_MAX_DEPTH = 5;
+
 /**
  * Walk a workflow directory and return absolute `.md` file paths
  * (non-recursive — the workflows surface is one level deep; helpers/
@@ -127,17 +152,57 @@ function findAgentToolDeclaration(parts) {
   return null;
 }
 
+/**
+ * Parse the workflow's declared nesting depth. A sub-agent that declares
+ * `Agent` may also declare how deep its fan-out reaches via a
+ * `nesting-depth:` (or `agent-depth:`) frontmatter field, or a
+ * `<!-- nesting-depth: N -->` marker in the body. Returns the integer
+ * depth, or `null` when no depth is declared (the caller treats an absent
+ * declaration as the shallow level-1 fan-out).
+ *
+ * @param {{ frontmatter: string, body: string }} parts
+ * @returns {number | null}
+ */
+function parseDeclaredDepth(parts) {
+  const { frontmatter, body } = parts;
+  const fmMatch = frontmatter.match(
+    /^[ \t]*(?:nesting-depth|agent-depth)\s*:\s*(\d+)\s*$/m,
+  );
+  if (fmMatch) return Number.parseInt(fmMatch[1], 10);
+  const bodyMatch = body.match(
+    /<!--\s*(?:nesting-depth|agent-depth)\s*:\s*(\d+)\s*-->/,
+  );
+  if (bodyMatch) return Number.parseInt(bodyMatch[1], 10);
+  return null;
+}
+
+/**
+ * Resolve the supported depth ceiling for a detect run. Operators may pin a
+ * stricter (or, once verified, looser) ceiling via `state.supportedDepth`;
+ * an unset or non-positive-integer override falls back to the announced max.
+ *
+ * @param {{ supportedDepth?: unknown } | null | undefined} state
+ * @returns {number}
+ */
+function resolveCeiling(state) {
+  const override = state?.supportedDepth;
+  if (Number.isInteger(override) && override > 0) return override;
+  return ANNOUNCED_MAX_DEPTH;
+}
+
 const FIX_COMMAND = [
-  '# Flatten fan-out to the host. Sub-agents cannot dispatch other agents.',
-  "# Remove the `Agent` entry from this workflow's `tools:` declaration,",
-  '# move any fan-out logic up to the parent / host invocation, and have',
-  '# the parent dispatch the leaf sub-agents directly.',
+  '# Nested Agent dispatch IS supported (verified depth 2, announced max 5 —',
+  '# Claude Code 2.1.202). This workflow declares a fan-out deeper than the',
+  '# supported ceiling, so the deepest dispatch chain will fail at runtime.',
   '#',
-  '# Pattern (host workflow):',
-  '#   for each child: Agent(prompt=<child workflow>, args=<id>)',
+  '# Bring the fan-out back under the ceiling — either:',
+  '#   1. Lower the declared `nesting-depth` to <= the supported ceiling, or',
+  '#   2. Split the deepest level out to a shallower sibling fan-out so no',
+  '#      single dispatch chain exceeds the supported depth.',
   '#',
-  '# Pattern (sub-agent workflow):',
-  '#   tools: [Bash, Read, Edit, Grep, Glob, Write]   # NO Agent',
+  '# Do NOT strip `Agent` from the tool list to silence this. Sub-agents CAN',
+  '# dispatch nested agents at a supported depth; removing the tool would',
+  '# disable a legitimate capability, not fix the depth overflow.',
 ].join('\n');
 
 export default {
@@ -149,6 +214,7 @@ export default {
   detect(state) {
     const cwd = state?.cwd ?? process.cwd();
     const root = state?.scanRoot ?? path.join(cwd, WORKFLOWS_DIR_DEFAULT);
+    const ceiling = resolveCeiling(state);
     const files = listWorkflowFiles(root);
     const offences = [];
     for (const file of files) {
@@ -162,18 +228,29 @@ export default {
       const parts = splitFrontmatter(src);
       const where = findAgentToolDeclaration(parts);
       if (!where) continue;
+      // Declaring `Agent` is legitimate. Only a fan-out deeper than the
+      // supported ceiling is a runtime hazard; an undeclared depth is the
+      // shallow level-1 fan-out and always within the ceiling.
+      const depth = parseDeclaredDepth(parts) ?? 1;
+      if (depth <= ceiling) continue;
       offences.push({
         file: path.relative(root, file).replace(/\\/g, '/'),
         where,
+        depth,
       });
     }
     if (offences.length === 0) return null;
-    const detail = offences.map((o) => `${o.file} — ${o.where}`).join('\n');
+    const detail = offences
+      .map(
+        (o) =>
+          `${o.file} — declares Agent at nesting-depth ${o.depth} (exceeds supported ceiling ${ceiling}); ${o.where}`,
+      )
+      .join('\n');
     return {
       id: 'subagent-agent-tool-required',
       severity: 'blocker',
       scope: state?.scope ?? 'epic-deliver',
-      summary: `${offences.length} sub-agent workflow(s) declare Agent in their tool list — nested Agent dispatch is unsupported`,
+      summary: `${offences.length} sub-agent workflow(s) declare an Agent fan-out deeper than the supported nesting ceiling (${ceiling})`,
       detail,
       fixCommand: FIX_COMMAND,
       autoCorrectable: false,

package/.agents/scripts/lib/epic-plan-ideation.js

@@ -13,6 +13,10 @@
  * mock the provider call without touching the GitHub HTTP client.
  */
 
+import {
+  extractFrameworkStamp,
+  stampFrameworkVersion,
+} from './framework-version.js';
 import { TYPE_LABELS } from './label-constants.js';
 
 // Canonical section keys match the rendered template at
@@ -113,24 +117,33 @@ export function parseOnePager(onePager) {
  * sections are rendered as `_(not specified)_` so the operator can spot
  * gaps during the HITL review (Phase 3).
  *
+ * Story #4382 — the rendered body is stamped with the Mandrel framework
+ * version + authoring date (hidden `mandrel_version` / `authored_at` meta
+ * field + a visible `> 🏷️ Authored with Mandrel …` marker) via
+ * {@link stampFrameworkVersion}. Pass `stamp` to preserve a
+ * previously-authored version on re-render (the Epic edit path does this);
+ * omit it to stamp the running version and today's date.
+ *
  * @param {{
  *   onePager: string,
  *   template: string,
+ *   stamp?: { version?: string, authoredAt?: string },
  * }} args
  * @returns {{ title: string, body: string }}
  */
-export function renderEpicBody({ onePager, template }) {
+export function renderEpicBody({ onePager, template, stamp }) {
   if (!template || typeof template !== 'string') {
     throw new Error('renderEpicBody: template must be a non-empty string');
   }
   const parsed = parseOnePager(onePager);
 
-  const body = template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+  const rendered = template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
     if (key === 'title') return parsed.title;
     const value = parsed[key];
     return value && value.length > 0 ? value : '_(not specified)_';
   });
 
+  const body = stampFrameworkVersion(rendered, stamp ?? {});
   return { title: parsed.title, body };
 }
 
@@ -226,7 +239,15 @@ export async function updateEpicFromOnePager({
     );
   }
 
-  const { title, body } = renderEpicBody({ onePager, template });
+  // Story #4382 — preserve the originally-authored version stamp on edit
+  // rather than bumping it to whatever version is running now. When the
+  // current body carries no stamp (legacy Epic), a fresh stamp is applied.
+  const priorStamp = extractFrameworkStamp(currentBody ?? '');
+  const stamp = priorStamp
+    ? { version: priorStamp.version, authoredAt: priorStamp.authoredAt }
+    : undefined;
+
+  const { title, body } = renderEpicBody({ onePager, template, stamp });
 
   if (typeof currentBody === 'string' && currentBody === body) {
     return { epicId, title, body, changed: false };

package/.agents/scripts/lib/framework-version.js

@@ -0,0 +1,210 @@
+// .agents/scripts/lib/framework-version.js
+/**
+ * framework-version.js — single source of truth for the running Mandrel
+ * framework version and the ticket-body authoring stamp.
+ *
+ * Two concerns live here:
+ *
+ * 1. **Version resolution.** Under npm distribution the root `package.json`
+ *    is the canonical version marker. {@link resolveFrameworkVersion} reads it
+ *    and degrades to `'unknown'` (never throws) so a missing/unreadable
+ *    manifest can never crash an authoring or hydration path. The private
+ *    `getVersion()` in `lib/orchestration/context-hydration-engine.js`
+ *    delegates here (DRY — one manifest reader).
+ *
+ * 2. **Ticket-body stamp.** Epics and Stories are stamped **once at authoring
+ *    time** with the running version and the authoring date, via a hybrid
+ *    surface:
+ *      - a hidden machine-readable field in the trailing
+ *        `<!-- meta: {"mandrel_version":"…","authored_at":"…"} -->` block
+ *        (the source of truth, queryable by tooling), and
+ *      - a single visible footer line
+ *        `> 🏷️ Authored with Mandrel v<version> · <YYYY-MM-DD>` so a human
+ *        reading the raw GitHub issue sees the provenance without any tooling.
+ *
+ *    The stamp is **immutable**: {@link stampFrameworkVersion} is a no-op when
+ *    the body already carries a `mandrel_version`, so a later re-render or
+ *    Epic-body edit preserves the originally-authored version verbatim rather
+ *    than bumping it to whatever version happens to be running.
+ *
+ * This module imports only Node builtins so it can be pulled in from the
+ * story-body serializer, the ticket provider, and the Epic ideation renderer
+ * without risking an import cycle.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Returned when the package manifest is absent or unreadable. */
+export const FALLBACK_VERSION = 'unknown';
+
+/**
+ * Trailing machine-metadata comment block: `<!-- meta: {...} -->`. Mirrors the
+ * regex the Story-body parser uses so both surfaces recognise the same block.
+ */
+const META_BLOCK_RE = /<!--\s*meta:\s*(\{[\s\S]*?\})\s*-->/;
+
+/**
+ * The visible authoring marker line. A blockquote so GitHub renders it as a
+ * callout. Used both to detect an already-emitted marker (for the strip step)
+ * and, in the Story-body parser, to skip the line during section parsing so it
+ * never pollutes the last structured section.
+ */
+export const AUTHORED_MARKER_LINE_RE = /^\s*>\s*🏷️\s+Authored with Mandrel\b/;
+
+/**
+ * Compute the default path to the root `package.json`. This module ships inside
+ * the `mandrel` package at `<pkgRoot>/.agents/scripts/lib/framework-version.js`,
+ * so the manifest sits three directories up — the same layout in the dev repo
+ * and the published tarball.
+ *
+ * @returns {string}
+ */
+function defaultPkgPath() {
+  const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(moduleDir, '../../..', 'package.json');
+}
+
+/**
+ * Resolve the running framework version from the root `package.json`. Degrades
+ * to {@link FALLBACK_VERSION} (never throws) on any read or parse failure so a
+ * missing/unreadable manifest can never crash an authoring or hydration path.
+ *
+ * @param {{ pkgPath?: string }} [opts] - `pkgPath` override (test seam).
+ * @returns {string}
+ */
+export function resolveFrameworkVersion({ pkgPath } = {}) {
+  try {
+    const resolved = typeof pkgPath === 'string' ? pkgPath : defaultPkgPath();
+    const parsed = JSON.parse(fs.readFileSync(resolved, 'utf8'));
+    return typeof parsed.version === 'string' && parsed.version.trim()
+      ? parsed.version.trim()
+      : FALLBACK_VERSION;
+  } catch {
+    return FALLBACK_VERSION;
+  }
+}
+
+/**
+ * Format an authoring date as `YYYY-MM-DD` (UTC). Matches the date shape the
+ * rest of the authoring path uses (e.g. `qa-session`).
+ *
+ * @param {Date} [date=new Date()]
+ * @returns {string}
+ */
+export function formatAuthoredDate(date = new Date()) {
+  const d =
+    date instanceof Date && !Number.isNaN(date.getTime()) ? date : new Date();
+  return d.toISOString().slice(0, 10);
+}
+
+/**
+ * Build the visible authoring marker line for a given stamp. Centralised so
+ * the string is byte-identical across the two producers (the Story-body
+ * serializer and {@link stampFrameworkVersion}).
+ *
+ * @param {{ version: string, authoredAt: string }} stamp
+ * @returns {string}
+ */
+export function authoredMarkerLine({ version, authoredAt }) {
+  return `> 🏷️ Authored with Mandrel v${version} · ${authoredAt}`;
+}
+
+/**
+ * Read the framework stamp from a body's trailing meta block. Returns
+ * `{ version, authoredAt }` when a non-empty `mandrel_version` is present, or
+ * `null` when the body carries no stamp (or the meta block is malformed).
+ * `authoredAt` is `null` when the version is present but the date is absent.
+ *
+ * @param {string} markdown
+ * @returns {{ version: string, authoredAt: string|null }|null}
+ */
+export function extractFrameworkStamp(markdown) {
+  if (typeof markdown !== 'string') return null;
+  const match = markdown.match(META_BLOCK_RE);
+  if (!match) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(match[1]);
+  } catch {
+    return null;
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return null;
+  }
+  const version =
+    typeof parsed.mandrel_version === 'string' && parsed.mandrel_version.trim()
+      ? parsed.mandrel_version.trim()
+      : null;
+  if (version === null) return null;
+  const authoredAt =
+    typeof parsed.authored_at === 'string' && parsed.authored_at.trim()
+      ? parsed.authored_at.trim()
+      : null;
+  return { version, authoredAt };
+}
+
+/**
+ * Stamp a ticket body (Epic or Story markdown) with the framework version and
+ * authoring date — **once**. When the body already carries a `mandrel_version`
+ * the body is returned verbatim (immutability: never re-derive or bump an
+ * already-authored stamp). Otherwise the version keys are merged into (or
+ * create) the trailing `<!-- meta -->` block — appended **last** so the key
+ * order stays stable with the Story-body serializer — and the visible marker
+ * line is (re)emitted just above it.
+ *
+ * The `version` / `authoredAt` overrides let a caller (e.g. the Epic edit path)
+ * preserve a previously-authored stamp; both default to the running version and
+ * today's date when omitted.
+ *
+ * @param {string} markdown
+ * @param {{ version?: string, authoredAt?: string }} [stamp]
+ * @returns {string}
+ */
+export function stampFrameworkVersion(markdown, stamp = {}) {
+  const body = typeof markdown === 'string' ? markdown : '';
+
+  // Immutability: a body that already carries a version is preserved verbatim.
+  if (extractFrameworkStamp(body) !== null) return body;
+
+  const version =
+    typeof stamp?.version === 'string' && stamp.version.trim()
+      ? stamp.version.trim()
+      : resolveFrameworkVersion();
+  const authoredAt =
+    typeof stamp?.authoredAt === 'string' && stamp.authoredAt.trim()
+      ? stamp.authoredAt.trim()
+      : formatAuthoredDate();
+
+  // Merge into any existing (version-less) meta block, appending the version
+  // keys last for stable key order.
+  const metaMatch = body.match(META_BLOCK_RE);
+  const meta = {};
+  if (metaMatch) {
+    try {
+      const parsed = JSON.parse(metaMatch[1]);
+      if (
+        parsed !== null &&
+        typeof parsed === 'object' &&
+        !Array.isArray(parsed)
+      ) {
+        Object.assign(meta, parsed);
+      }
+    } catch {
+      // Malformed meta comment — drop it and re-emit a clean block.
+    }
+  }
+  meta.mandrel_version = version;
+  meta.authored_at = authoredAt;
+
+  // Strip any existing meta block / marker so both re-append canonically.
+  const head = body
+    .replace(META_BLOCK_RE, '')
+    .replace(new RegExp(AUTHORED_MARKER_LINE_RE.source, 'm'), '')
+    .replace(/\n{3,}/g, '\n\n')
+    .trimEnd();
+
+  const marker = authoredMarkerLine({ version, authoredAt });
+  return `${head}\n\n${marker}\n\n<!-- meta: ${JSON.stringify(meta)} -->`;
+}