mandrel 1.85.0 → 1.87.0

package/.agents/scripts/lib/single-story-sweep.js

@@ -1,27 +1,51 @@
 /**
- * single-story-sweep.js — Sweep merged `story-*` branches at init.
+ * single-story-sweep.js — the scope-agnostic merged-branch sweep engine
+ * plus the `story-*` boot-sweep preset.
  *
- * Wraps `git-cleanup-branches.js` with a fixed policy tuned for the
- * `/single-story-deliver` boot path:
+ * `sweepMergedBranches` is the single reap engine every boot cleanup
+ * path routes through. It sits directly over the `git-cleanup` phase
+ * library (`planCleanup` / `executeCleanup` / `executeFastForward` /
+ * `buildGlobFilter`) and the shared `evaluateProtection` guard set, so
+ * no reap path re-implements the `git branch -D` / `git merge --ff-only`
+ * primitives:
  *
- *   - Scope: `story-*` only (never touches `epic/*`, `story/<id>/*`, etc.).
- *   - Mode:  --execute --remote (delete local + origin + prune trackers).
- *   - Skip:  the current run's `storyBranch` is always excluded, even if a
- *            stale PR for the same id were already merged.
+ *   - Scope: caller-supplied `include` / `exclude` globs (via
+ *            `buildGlobFilter`). The story preset pins `story-*`.
+ *   - Reap:  merged local branches whose PR HEAD SHA equals the merged
+ *            `headRefOid`, deleted local + origin with tracking-ref
+ *            prune (`executeCleanup` in `--remote` mode).
  *   - Protection (Story #2011): each candidate is filtered through
  *            `evaluateProtection` before reaching `executeCleanup`. A
  *            candidate is protected (not reaped) when its branch HEAD
  *            differs from the PR's `headRefOid` (unpushed work), when
  *            its worktree has uncommitted edits, or when the parent
  *            Story ticket is not in a terminal state. Protected
- *            candidates surface in the result envelope under
- *            `protected` so the operator can see what was skipped.
+ *            candidates surface under `protected`.
+ *   - Fast-forward (opt-in via `fastForward: true`): fast-forward the
+ *            base branch through `executeFastForward` after the reap.
+ *            Best-effort — a failed fast-forward never fails the sweep.
  *   - Concurrency (Story #2011): the sweep acquires a process-scoped
  *            lockfile around plan + execute. On lock contention the
- *            sweep is skipped (init continues — same contract as a
+ *            sweep is skipped (the host continues — same contract as a
  *            plan failure).
- *   - Errors are caught and surfaced in the envelope. The caller MUST NOT
- *            propagate sweep failures — story init proceeds either way.
+ *   - Content-merged (Story #4396, report-only): a plan candidate the
+ *            `git-cleanup` planner classified `detectedBy: 'content-merged'`
+ *            (Story #4395's `git merge-tree --write-tree` content-equivalence
+ *            probe) is a **weaker** signal than a merged PR or git ancestry —
+ *            no CI/GitHub merge check ever validated its exact diff. This
+ *            engine never reaps on that signal alone: content-merged
+ *            candidates are pulled out of the plan before protection +
+ *            execute and surfaced under `contentMerged` in the envelope so
+ *            the operator can route them to `/git-cleanup` for a confirmed,
+ *            eyeballed reap.
+ *   - Never touches the stash stack.
+ *   - Errors are caught and surfaced in the envelope. Callers MUST NOT
+ *            propagate sweep failures — the host proceeds either way.
+ *
+ * `sweepMergedStoryBranches` is a thin preset over the engine tuned for
+ * the boot path (`include: story-*`, `exclude: <current story branch>`,
+ * `fastForward: false`). Its exported name, signature, and result
+ * envelope are unchanged from the pre-engine implementation.
  *
  * Re-exports the same `planCleanup` / `executeCleanup` injection seams so
  * tests can stub git/`gh` without touching the CLI.
@@ -30,7 +54,9 @@
 import {
   buildGlobFilter,
   executeCleanup as defaultExecuteCleanup,
+  executeFastForward as defaultExecuteFastForward,
   planCleanup as defaultPlanCleanup,
+  planFastForward as defaultPlanFastForward,
 } from '../git-cleanup.js';
 import { evaluateProtection as defaultEvaluateProtection } from './single-story-sweep/protection.js';
 import { acquireSweepLock as defaultAcquireSweepLock } from './single-story-sweep/sweep-lock.js';
@@ -38,15 +64,20 @@ import { acquireSweepLock as defaultAcquireSweepLock } from './single-story-swee
 const STORY_BRANCH_INCLUDE = 'story-*';
 
 /**
- * Sweep merged `story-*` branches in `cwd`.
+ * Scope-agnostic merged-branch sweep engine.
  *
  * @param {{
  *   cwd: string,
  *   baseBranch: string,
- *   currentStoryBranch: string,
+ *   include?: string[],
+ *   exclude?: string[],
+ *   fastForward?: boolean,
  *   logger?: { info?: (m: string) => void, warn?: (m: string) => void },
+ *   logTag?: string,
  *   planCleanupFn?: typeof defaultPlanCleanup,
  *   executeCleanupFn?: typeof defaultExecuteCleanup,
+ *   planFastForwardFn?: typeof defaultPlanFastForward,
+ *   executeFastForwardFn?: typeof defaultExecuteFastForward,
  *   protectionFn?: typeof defaultEvaluateProtection,
  *   protectionCtx?: object,
  *   acquireLockFn?: typeof defaultAcquireSweepLock,
@@ -60,18 +91,25 @@ const STORY_BRANCH_INCLUDE = 'story-*';
  *   localDeleted: number,
  *   remoteDeleted: number,
  *   protected: Array<{ branch: string, reason: string, worktreePath?: string|null }>,
+ *   contentMerged: Array<{ branch: string, worktreePath: string|null }>,
  *   failures: Array<{ branch: string|null, scope: string, stderr?: string }>,
+ *   fastForward?: object,
  *   error?: string,
  *   reason?: string,
  * }>}
  */
-export async function sweepMergedStoryBranches({
+export async function sweepMergedBranches({
   cwd,
   baseBranch,
-  currentStoryBranch,
+  include = ['*'],
+  exclude = [],
+  fastForward = false,
   logger = {},
+  logTag = '[sweep]',
   planCleanupFn = defaultPlanCleanup,
   executeCleanupFn = defaultExecuteCleanup,
+  planFastForwardFn = defaultPlanFastForward,
+  executeFastForwardFn = defaultExecuteFastForward,
   protectionFn = defaultEvaluateProtection,
   protectionCtx = null,
   acquireLockFn = defaultAcquireSweepLock,
@@ -92,16 +130,13 @@ export async function sweepMergedStoryBranches({
 
   // Optional lock acquisition. Skip silently when no lockPath is
   // supplied (e.g. unit tests, callers that opt out). Contention is
-  // non-fatal — return a skipped result and let init continue.
+  // non-fatal — return a skipped result and let the host continue.
   let releaseLock = () => {};
   if (lockPath) {
-    const lockResult = acquireLockFn({
-      lockPath,
-      timeoutMs: lockTimeoutMs,
-    });
+    const lockResult = acquireLockFn({ lockPath, timeoutMs: lockTimeoutMs });
     if (!lockResult.acquired) {
       log.warn(
-        `[single-story-sweep] lock not acquired (${lockResult.reason}${
+        `${logTag} lock not acquired (${lockResult.reason}${
           lockResult.detail ? `: ${lockResult.detail}` : ''
         }); skipping sweep.`,
       );
@@ -113,6 +148,7 @@ export async function sweepMergedStoryBranches({
         localDeleted: 0,
         remoteDeleted: 0,
         protected: [],
+        contentMerged: [],
         failures: [],
       };
     }
@@ -120,16 +156,28 @@ export async function sweepMergedStoryBranches({
   }
 
   try {
-    return await runSweepUnderLock({
+    const reap = await runSweepUnderLock({
       cwd,
       baseBranch,
-      currentStoryBranch,
+      include,
+      exclude,
       log,
+      logTag,
       planCleanupFn,
       executeCleanupFn,
       protectionFn,
       protectionCtx,
     });
+    if (!fastForward) return reap;
+    const ff = runFastForwardStep({
+      cwd,
+      baseBranch,
+      log,
+      logTag,
+      planFastForwardFn,
+      executeFastForwardFn,
+    });
+    return { ...reap, fastForward: ff };
   } finally {
     try {
       releaseLock();
@@ -139,41 +187,109 @@ export async function sweepMergedStoryBranches({
   }
 }
 
+/**
+ * Sweep merged `story-*` branches in `cwd`. Preset over
+ * {@link sweepMergedBranches} for the boot path: it pins the `story-*`
+ * include glob, excludes the current run's `currentStoryBranch`, and
+ * keeps `fastForward` off (the boot caller fast-forwards the base branch
+ * separately). Exported name, signature, and result-envelope shape are
+ * unchanged from the pre-engine implementation.
+ *
+ * @param {{
+ *   cwd: string,
+ *   baseBranch: string,
+ *   currentStoryBranch: string,
+ *   logger?: { info?: (m: string) => void, warn?: (m: string) => void },
+ *   planCleanupFn?: typeof defaultPlanCleanup,
+ *   executeCleanupFn?: typeof defaultExecuteCleanup,
+ *   protectionFn?: typeof defaultEvaluateProtection,
+ *   protectionCtx?: object,
+ *   acquireLockFn?: typeof defaultAcquireSweepLock,
+ *   lockPath?: string|null,
+ *   lockTimeoutMs?: number,
+ * }} args
+ * @returns {Promise<object>} the {@link sweepMergedBranches} envelope.
+ */
+export function sweepMergedStoryBranches(args = {}) {
+  const { currentStoryBranch } = args;
+  const exclude =
+    typeof currentStoryBranch === 'string' && currentStoryBranch.length > 0
+      ? [currentStoryBranch]
+      : [];
+  return sweepMergedBranches({
+    ...args,
+    include: [STORY_BRANCH_INCLUDE],
+    exclude,
+    fastForward: false,
+    logTag: '[single-story-sweep]',
+  });
+}
+
+/**
+ * Split a plan's candidates into the reapable set and the report-only
+ * `content-merged` set (Story #4396). A candidate the `git-cleanup`
+ * planner classified `detectedBy: 'content-merged'` (Story #4395's
+ * `git merge-tree --write-tree` probe) never reaches protection or
+ * `executeCleanup` — it is a weaker signal than a merged PR or git
+ * ancestry, so the engine only reports it for the operator to route to
+ * `/git-cleanup`.
+ */
+function partitionContentMerged(candidates) {
+  const contentMerged = [];
+  const reapCandidates = [];
+  for (const candidate of candidates) {
+    if (candidate.detectedBy === 'content-merged') {
+      contentMerged.push({
+        branch: candidate.branch,
+        worktreePath: candidate.worktreePath ?? null,
+      });
+    } else {
+      reapCandidates.push(candidate);
+    }
+  }
+  return { contentMerged, reapCandidates };
+}
+
 /**
  * Inner: the plan + protect + execute pipeline. Kept separate so the
- * outer `sweepMergedStoryBranches` can stay focused on the lock
- * acquire/release wrapper.
+ * outer engine can stay focused on the lock and fast-forward wrappers.
  */
 async function runSweepUnderLock({
   cwd,
   baseBranch,
-  currentStoryBranch,
+  include,
+  exclude,
   log,
+  logTag,
   planCleanupFn,
   executeCleanupFn,
   protectionFn,
   protectionCtx,
 }) {
-  const exclude =
-    typeof currentStoryBranch === 'string' && currentStoryBranch.length > 0
-      ? [currentStoryBranch]
-      : [];
-  const filter = buildGlobFilter({
-    include: [STORY_BRANCH_INCLUDE],
-    exclude,
-  });
+  const filter = buildGlobFilter({ include, exclude });
 
   let plan;
   try {
     plan = planCleanupFn({ cwd, baseBranch, filter });
   } catch (err) {
     const msg = err?.message ?? String(err);
-    log.warn(`[single-story-sweep] plan failed: ${msg}`);
+    log.warn(`${logTag} plan failed: ${msg}`);
     return zeroResult({ error: `plan: ${msg}` });
   }
 
-  if (plan.candidates.length === 0) {
-    log.info('[single-story-sweep] no merged story branches to reap.');
+  const { contentMerged, reapCandidates } = partitionContentMerged(
+    plan.candidates,
+  );
+  if (contentMerged.length > 0) {
+    log.info(
+      `${logTag} ${contentMerged.length} content-merged branch(es) detected (report-only, not reaped): ${contentMerged
+        .map((c) => c.branch)
+        .join(', ')}.`,
+    );
+  }
+
+  if (reapCandidates.length === 0) {
+    log.info(`${logTag} no merged branches to reap.`);
     return {
       ok: true,
       skipped: false,
@@ -181,49 +297,76 @@ async function runSweepUnderLock({
       localDeleted: 0,
       remoteDeleted: 0,
       protected: [],
+      contentMerged,
       failures: [],
     };
   }
 
   const { reapable, protectedList } = await partitionCandidates({
-    candidates: plan.candidates,
+    candidates: reapCandidates,
     protectionFn,
     protectionCtx,
     log,
+    logTag,
   });
 
   if (reapable.length === 0) {
     log.info(
-      `[single-story-sweep] all ${plan.candidates.length} candidate(s) protected; no reap.`,
+      `${logTag} all ${reapCandidates.length} candidate(s) protected; no reap.`,
     );
     return {
       ok: true,
       skipped: false,
-      candidates: plan.candidates.length,
+      candidates: reapCandidates.length,
       localDeleted: 0,
       remoteDeleted: 0,
       protected: protectedList,
+      contentMerged,
       failures: [],
     };
   }
 
+  return executeReap({
+    reapable,
+    protectedList,
+    contentMerged,
+    candidateCount: reapCandidates.length,
+    cwd,
+    executeCleanupFn,
+    log,
+    logTag,
+  });
+}
+
+/**
+ * Execute the reap plan for the reapable candidates and shape the result
+ * envelope. Split out of {@link runSweepUnderLock} so each function keeps
+ * a single responsibility.
+ */
+function executeReap({
+  reapable,
+  protectedList,
+  contentMerged,
+  candidateCount,
+  cwd,
+  executeCleanupFn,
+  log,
+  logTag,
+}) {
   let result;
   try {
-    result = executeCleanupFn({
-      candidates: reapable,
-      cwd,
-      remote: true,
-    });
+    result = executeCleanupFn({ candidates: reapable, cwd, remote: true });
   } catch (err) {
     const msg = err?.message ?? String(err);
-    log.warn(`[single-story-sweep] execute failed: ${msg}`);
+    log.warn(`${logTag} execute failed: ${msg}`);
     return {
       ok: false,
       skipped: false,
-      candidates: plan.candidates.length,
+      candidates: candidateCount,
       localDeleted: 0,
       remoteDeleted: 0,
       protected: protectedList,
+      contentMerged,
       failures: [{ branch: null, scope: 'execute', stderr: msg }],
       error: `execute: ${msg}`,
     };
@@ -241,25 +384,64 @@ async function runSweepUnderLock({
   const summary = `${localDeleted} local + ${remoteDeleted} remote${protectedSummary}`;
   if (result.ok) {
     log.info(
-      `[single-story-sweep] reaped ${summary}${reapedBranches ? ` [${reapedBranches}]` : ''}.`,
+      `${logTag} reaped ${summary}${reapedBranches ? ` [${reapedBranches}]` : ''}.`,
     );
   } else {
     log.warn(
-      `[single-story-sweep] reaped ${summary} with ${result.failures.length} failure(s) — init continues.`,
+      `${logTag} reaped ${summary} with ${result.failures.length} failure(s) — host continues.`,
     );
   }
 
   return {
     ok: result.ok,
     skipped: false,
-    candidates: plan.candidates.length,
+    candidates: candidateCount,
     localDeleted,
     remoteDeleted,
     protected: protectedList,
+    contentMerged,
     failures: result.failures,
   };
 }
 
+/**
+ * Best-effort fast-forward of the base branch through the git-cleanup
+ * fast-forward phase. Never throws — a failed fast-forward is logged and
+ * returned as `{ ok: false, error }` but must never fail the sweep.
+ */
+function runFastForwardStep({
+  cwd,
+  baseBranch,
+  log,
+  logTag,
+  planFastForwardFn,
+  executeFastForwardFn,
+}) {
+  try {
+    const plan = planFastForwardFn({ cwd, baseBranch });
+    const ff = executeFastForwardFn({
+      cwd,
+      baseBranch,
+      plan,
+      logger: {
+        info: (m) => log.info(m.replace(/^\[git-cleanup\]\s*/, `${logTag} `)),
+        warn: (m) => log.warn(m.replace(/^\[git-cleanup\]\s*/, `${logTag} `)),
+      },
+    });
+    return {
+      ok: ff.ok !== false,
+      applied: !!ff.applied,
+      skipped: !!ff.skipped,
+      behind: ff.behind ?? null,
+      reason: ff.reason ?? null,
+    };
+  } catch (err) {
+    const msg = err?.message ?? String(err);
+    log.warn(`${logTag} fast-forward failed: ${msg}`);
+    return { ok: false, applied: false, skipped: false, error: msg };
+  }
+}
+
 /**
  * Iterate plan candidates and split them into `reapable` (safe to pass
  * to executeCleanup) and `protectedList` (skipped, with a reason).
@@ -270,14 +452,15 @@ async function runSweepUnderLock({
  *
  * When no `protectionCtx` is supplied (legacy callers, unit tests),
  * the protection check is bypassed entirely and every candidate is
- * reapable. The CLI surface in `single-story-init.js` always supplies
- * a ctx, so this fallback never fires in production.
+ * reapable. The boot-path CLI surfaces always supply a ctx, so this
+ * fallback never fires in production.
  */
 async function partitionCandidates({
   candidates,
   protectionFn,
   protectionCtx,
   log,
+  logTag,
 }) {
   const reapable = [];
   const protectedList = [];
@@ -291,7 +474,7 @@ async function partitionCandidates({
       verdict = await protectionFn({ candidate, ctx: protectionCtx });
     } catch (err) {
       const reason = `protection-eval-error: ${err?.message ?? err}`;
-      log.warn(`[single-story-sweep] protected ${candidate.branch}: ${reason}`);
+      log.warn(`${logTag} protected ${candidate.branch}: ${reason}`);
       protectedList.push({
         branch: candidate.branch,
         reason,
@@ -300,9 +483,7 @@ async function partitionCandidates({
       continue;
     }
     if (verdict?.protected) {
-      log.info(
-        `[single-story-sweep] protected ${candidate.branch}: ${verdict.reason}`,
-      );
+      log.info(`${logTag} protected ${candidate.branch}: ${verdict.reason}`);
       protectedList.push({
         branch: candidate.branch,
         reason: verdict.reason ?? 'unknown',
@@ -323,6 +504,7 @@ function zeroResult({ error }) {
     localDeleted: 0,
     remoteDeleted: 0,
     protected: [],
+    contentMerged: [],
     failures: [],
     error,
   };

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

@@ -42,6 +42,10 @@
  * @module story-body
  */
 
+import {
+  AUTHORED_MARKER_LINE_RE,
+  authoredMarkerLine,
+} from '../framework-version.js';
 import { FILE_ASSUMPTION_VALUES } from '../orchestration/file-assumption-enum.js';
 
 // ---------------------------------------------------------------------------
@@ -75,6 +79,8 @@ import { FILE_ASSUMPTION_VALUES } from '../orchestration/file-assumption-enum.js
  * @property {string|null}   reason_to_exist     - One-sentence cohesion reason ("why this Story exists"), or null.
  * @property {string[]}      depends_on          - Blocking story slugs / issue refs.
  * @property {number|null}   estimated_test_files - Test surface count or null.
+ * @property {string|null}   mandrel_version     - Framework version stamped at authoring, or null.
+ * @property {string|null}   authored_at         - Authoring date (YYYY-MM-DD) stamped at authoring, or null.
  */
 
 /**
@@ -253,14 +259,21 @@ const META_BLOCK_RE = /<!--\s*meta:\s*(\{[\s\S]*?\})\s*-->/;
  * otherwise-valid Story body. A parse failure degrades to the absent-meta
  * defaults instead of throwing.
  *
+ * The `mandrel_version` / `authored_at` provenance stamp (written once at
+ * authoring time by the ticket-creation path) is recovered here too so a later
+ * `parse → serialize` preserves the originally-authored version verbatim
+ * rather than dropping or re-deriving it.
+ *
  * @param {string} markdown
- * @returns {{ wide: { reason: string }|null, reason_to_exist: string|null, estimated_test_files: number|null }}
+ * @returns {{ wide: { reason: string }|null, reason_to_exist: string|null, estimated_test_files: number|null, mandrel_version: string|null, authored_at: string|null }}
  */
 function extractMeta(markdown) {
   const result = {
     wide: null,
     reason_to_exist: null,
     estimated_test_files: null,
+    mandrel_version: null,
+    authored_at: null,
   };
   const match = markdown.match(META_BLOCK_RE);
   if (!match) return result;
@@ -279,6 +292,15 @@ function extractMeta(markdown) {
   if (typeof parsed.estimated_test_files === 'number') {
     result.estimated_test_files = parsed.estimated_test_files;
   }
+  if (
+    typeof parsed.mandrel_version === 'string' &&
+    parsed.mandrel_version.trim()
+  ) {
+    result.mandrel_version = parsed.mandrel_version.trim();
+  }
+  if (typeof parsed.authored_at === 'string' && parsed.authored_at.trim()) {
+    result.authored_at = parsed.authored_at.trim();
+  }
   return result;
 }
 
@@ -409,6 +431,14 @@ function splitSections(markdown) {
       continue;
     }
 
+    // The visible `> 🏷️ Authored with Mandrel …` provenance marker is
+    // machine-managed metadata too (emitted alongside the meta block by the
+    // authoring path). Skip it so it never bleeds into the trailing structured
+    // section (e.g. `## Verify`); the value round-trips via the meta block.
+    if (AUTHORED_MARKER_LINE_RE.test(line)) {
+      continue;
+    }
+
     if (inPreamble) {
       preambleLines.push(line);
     } else if (currentSection !== null) {
@@ -456,6 +486,8 @@ function parseLegacyStringBody(input, preamble, footer) {
     reason_to_exist: null,
     depends_on: extractBlockedBy(footer),
     estimated_test_files: null,
+    mandrel_version: null,
+    authored_at: null,
   };
   return {
     body,
@@ -602,6 +634,8 @@ export function parse(input) {
   const estimated_test_files = meta.estimated_test_files;
   const wide = meta.wide;
   const reason_to_exist = meta.reason_to_exist;
+  const mandrel_version = meta.mandrel_version;
+  const authored_at = meta.authored_at;
   if (estimated_test_files === null) {
     warnings.push(
       'test-surface-unestimated: estimated_test_files not present.',
@@ -619,6 +653,8 @@ export function parse(input) {
     reason_to_exist,
     depends_on: dependsOn,
     estimated_test_files,
+    mandrel_version,
+    authored_at,
   };
 
   return {
@@ -699,6 +735,16 @@ function parseStructuredObject(obj) {
     );
   }
 
+  // Provenance stamp (preserved verbatim; never re-derived here).
+  const mandrel_version =
+    typeof obj.mandrel_version === 'string' && obj.mandrel_version.trim()
+      ? obj.mandrel_version.trim()
+      : null;
+  const authored_at =
+    typeof obj.authored_at === 'string' && obj.authored_at.trim()
+      ? obj.authored_at.trim()
+      : null;
+
   const body = {
     goal,
     changes,
@@ -710,6 +756,8 @@ function parseStructuredObject(obj) {
     reason_to_exist,
     depends_on,
     estimated_test_files,
+    mandrel_version,
+    authored_at,
   };
 
   return {
@@ -812,9 +860,11 @@ const SERIALIZE_SECTIONS = [
  * `estimated_test_files`). Returns the empty string when no meta field is
  * present so {@link serialize} appends nothing.
  *
- * Key insertion order (`wide` → `reason_to_exist` → `estimated_test_files`)
- * is load-bearing: it fixes the serialized JSON byte sequence the parser's
- * meta round-trip and the unit suite assert against.
+ * Key insertion order (`wide` → `reason_to_exist` → `estimated_test_files` →
+ * `mandrel_version` → `authored_at`) is load-bearing: it fixes the serialized
+ * JSON byte sequence the parser's meta round-trip and the unit suite assert
+ * against. The provenance stamp keys are appended **last** so every
+ * pre-existing (stamp-less) body serialises byte-identically to before.
  *
  * @param {StoryBody} body
  * @returns {string}
@@ -832,10 +882,36 @@ function serializeMetaBlock(body) {
   if (typeof body.estimated_test_files === 'number') {
     metaFields.estimated_test_files = body.estimated_test_files;
   }
+  if (typeof body.mandrel_version === 'string' && body.mandrel_version.trim()) {
+    metaFields.mandrel_version = body.mandrel_version.trim();
+  }
+  if (typeof body.authored_at === 'string' && body.authored_at.trim()) {
+    metaFields.authored_at = body.authored_at.trim();
+  }
   if (Object.keys(metaFields).length === 0) return '';
   return `\n\n<!-- meta: ${JSON.stringify(metaFields)} -->`;
 }
 
+/**
+ * Build the visible `> 🏷️ Authored with Mandrel v<version> · <date>` marker
+ * line when the body carries a complete provenance stamp
+ * (`mandrel_version` + `authored_at`). Emitted just above the meta block so it
+ * round-trips with the hidden field. Returns the empty string when either
+ * field is absent, so every pre-existing (stamp-less) body serialises
+ * byte-identically to before.
+ *
+ * @param {StoryBody} body
+ * @returns {string}
+ */
+function serializeAuthoredMarker(body) {
+  const version =
+    typeof body.mandrel_version === 'string' ? body.mandrel_version.trim() : '';
+  const authoredAt =
+    typeof body.authored_at === 'string' ? body.authored_at.trim() : '';
+  if (!version || !authoredAt) return '';
+  return `\n\n${authoredMarkerLine({ version, authoredAt })}`;
+}
+
 /**
  * Build the optional `---` footer block (`parent` / `Epic` / `blocked by`
  * lines). Returns the empty string when `opts.includeFooter` is falsy.
@@ -888,6 +964,7 @@ export function serialize(body, opts = {}) {
 
   return (
     sections.join('\n\n') +
+    serializeAuthoredMarker(body) +
     serializeMetaBlock(body) +
     serializeFooter(body, opts)
   );