mandrel 1.86.0 → 1.88.0

package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js

@@ -344,7 +344,91 @@ export function branchTipSha({
   return res.status !== 0 ? null : validSha(firstLsRemoteSha(res.stdout));
 }
 
-export const __testing = { validSha, firstLsRemoteSha };
+/* node:coverage ignore next */
+// Story #4395: ancestry-anchor freshness check. `planCleanup` calls this
+// before unioning `git branch --merged origin/<base>` into the ancestry
+// signal so a stale local `<base>` (fast-forward phase skipped or
+// `--branches` run alone) doesn't hide a branch that's already merged on
+// the remote.
+export function refExists(cwd, ref) {
+  const res = gitSpawn(cwd, 'rev-parse', '--verify', '--quiet', ref);
+  return res.status === 0;
+}
+
+/* node:coverage ignore next */
+// Story #4395: last-commit timestamp for the dry-run `not-merged`
+// skip-visibility line (branch name + last-commit age).
+export function branchLastCommitAt(cwd, branch) {
+  const res = gitSpawn(
+    cwd,
+    'log',
+    '-1',
+    '--format=%cI',
+    `refs/heads/${branch}`,
+    '--',
+  );
+  if (res.status !== 0) return null;
+  return res.stdout.trim() || null;
+}
+
+/**
+ * First non-empty trimmed stdout line — the resulting tree OID on a clean
+ * `git merge-tree --write-tree` run.
+ *
+ * @param {string} stdout
+ * @returns {string}
+ */
+function firstStdoutLine(stdout) {
+  const first = (stdout ?? '')
+    .split('\n')
+    .map((l) => l.trim())
+    .find(Boolean);
+  return first ?? '';
+}
+
+/**
+ * Probe content-equivalence between `base` and `branch` via
+ * `git merge-tree --write-tree <base> <branch>` (git >= 2.38, Story #4395).
+ *
+ * A clean merge (exit 0) whose resulting tree OID equals `<base>`'s own
+ * tree OID means applying `branch`'s changes on top of `base` is a no-op —
+ * `branch`'s content already lives in `base` by another route (a
+ * squash-merged Epic PR, a cherry-pick, a manual `merge --squash`) that
+ * neither the PR probe nor the ancestry check can see.
+ *
+ * Both the "unsupported" case (git < 2.38 rejects `--write-tree`) and the
+ * "real conflict" case (branch and base diverge and cannot auto-merge)
+ * surface as a non-zero exit. This probe treats them identically — the
+ * signal is inconclusive, so the caller keeps the branch's current
+ * `not-merged` classification rather than guessing.
+ *
+ * @param {{ cwd: string, base: string, branch: string, spawn?: typeof gitSpawn }} args
+ * @returns {{ supported: false } | { supported: true, equivalent: boolean }}
+ */
+export function probeContentEquivalent({
+  cwd,
+  base,
+  branch,
+  spawn = gitSpawn,
+}) {
+  const merged = spawn(cwd, 'merge-tree', '--write-tree', base, branch);
+  if (merged.status !== 0) return { supported: false };
+  const mergedTree = validSha(firstStdoutLine(merged.stdout));
+  if (!mergedTree) return { supported: false };
+  const baseTreeRes = spawn(
+    cwd,
+    'rev-parse',
+    '--verify',
+    '--quiet',
+    `${base}^{tree}`,
+  );
+  if (baseTreeRes.status !== 0) return { supported: false };
+  const baseTree = validSha(baseTreeRes.stdout);
+  if (!baseTree) return { supported: false };
+  return { supported: true, equivalent: mergedTree === baseTree };
+}
+
+export const __testing = { validSha, firstLsRemoteSha, firstStdoutLine };
 
 /**
  * Pure-ish: classify a latest-PR probe row into a planner verdict.

package/.agents/scripts/lib/orchestration/git-cleanup/phases/phase-drivers.js

@@ -190,6 +190,22 @@ export async function runPrunePhase(opts, cwd) {
 // Branch phase
 // =====================================================================
 
+/**
+ * Count of a plan's *actionable* candidates — the ones `executeCleanup`
+ * will actually delete given the current `--remote` setting. Story #4395
+ * always enumerates remote-only candidates in `plan.candidates` (so the
+ * operator sees them in the dry-run list), but their deletion still
+ * requires `--remote`; without it, `executeCleanup` no-ops on every
+ * `localExists: false` candidate. Counting only the actionable subset
+ * keeps the "no-candidates" short-circuit and the confirmation prompt's
+ * "Reap N" count honest about what will actually happen.
+ */
+function countActionableCandidates(candidates, remote) {
+  return remote
+    ? candidates.length
+    : candidates.filter((c) => c.localExists !== false).length;
+}
+
 /**
  * Pure: decide what the branch-reap phase should do given the plan.
  *
@@ -209,7 +225,11 @@ export function decideBranchPhase(state) {
   if (opts.dryRun) {
     return { kind: 'dry-run', plan, result: { plan, result: null } };
   }
-  if (plan.candidates.length === 0) {
+  const actionableCount = countActionableCandidates(
+    plan.candidates,
+    opts.remote,
+  );
+  if (actionableCount === 0) {
     return { kind: 'no-candidates', plan, result: { plan, result: null } };
   }
   const executeArgs = {
@@ -218,10 +238,17 @@ export function decideBranchPhase(state) {
     remote: opts.remote,
   };
   if (!opts.yes) {
+    const contentMergedCount = plan.candidates.filter(
+      (c) => c.detectedBy === 'content-merged',
+    ).length;
+    const weakSignalNote =
+      contentMergedCount > 0
+        ? ` (${contentMergedCount} content-merged — weaker signal, verify before confirming)`
+        : '';
     return {
       kind: 'prompt-then-execute',
       plan,
-      promptMessage: `${TAG} Reap ${plan.candidates.length} merged branch(es)${opts.remote ? ' (including origin)' : ''}?`,
+      promptMessage: `${TAG} Reap ${actionableCount} merged branch(es)${opts.remote ? ' (including origin)' : ''}${weakSignalNote}?`,
       declinedResult: { plan, result: null, declined: true },
       executeArgs,
     };
@@ -254,11 +281,15 @@ export async function runBranchPhase(opts, cwd, baseBranch) {
     include: opts.include,
     exclude: opts.exclude,
   });
+  // Story #4395: always enumerate remote-only merged branches so the
+  // dry-run / prompt shows them without requiring `--remote`. Deletion of
+  // a remote-only candidate still requires `--remote` — `executeCleanup`
+  // no-ops on `localExists: false` candidates otherwise (unchanged).
   const plan = planCleanup({
     cwd,
     baseBranch,
     filter,
-    includeRemoteOnly: opts.remote === true,
+    includeRemoteOnly: true,
   });
   emitDryRunHuman(plan, baseBranch);
   const action = decideBranchPhase({ plan, opts, cwd });

package/.agents/scripts/lib/orchestration/git-cleanup/phases/render.js

@@ -9,10 +9,61 @@
  */
 
 const TAG = '[git-cleanup]';
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Pure: format a last-commit ISO timestamp as a short relative-age string
+ * for the `not-merged` skip-visibility line (Story #4395). Returns
+ * `'unknown'` when `iso` is missing or unparseable — a branch whose commit
+ * date could not be resolved (e.g. `gh`-degraded run, deleted ref) still
+ * gets a line, just without an age.
+ *
+ * @param {string|null|undefined} iso
+ * @param {number} now  Epoch-ms reference clock (injectable for tests).
+ * @returns {string}
+ */
+function formatCommitAge(iso, now) {
+  if (!iso) return 'unknown';
+  const then = Date.parse(iso);
+  if (!Number.isFinite(then)) return 'unknown';
+  const days = Math.max(0, Math.floor((now - then) / DAY_MS));
+  if (days === 0) return 'today';
+  if (days === 1) return '1 day ago';
+  return `${days} days ago`;
+}
+
+/**
+ * Pure: render a single `not-merged` skip-visibility line (Story #4395).
+ * `renderDryRun` previously kept `not-merged` survivors silent; this
+ * surfaces each one with its last-commit age so the operator can see why
+ * a leftover branch isn't reaped instead of hunting for it by hand.
+ *
+ * @param {{ branch: string, reason: string, lastCommitAt?: string|null }} skip
+ * @param {{ now?: number }} [opts]
+ * @returns {string | null}
+ */
+export function renderNotMergedSkipLine(skip, opts = {}) {
+  if (!skip || skip.reason !== 'not-merged') return null;
+  const now = opts.now ?? Date.now();
+  const age = formatCommitAge(skip.lastCommitAt, now);
+  return `${TAG} ⏭️  ${skip.branch} skipped — not merged (last commit: ${age})`;
+}
+
+/**
+ * Pure: render a single content-merged candidate annotation line
+ * (Story #4395). `content-merged` is a weaker signal than a merged PR or
+ * git ancestry — this note lets the operator tell it apart in both the
+ * dry-run list and the confirmation prompt.
+ */
+function contentMergedNote(candidate) {
+  return candidate.detectedBy === 'content-merged'
+    ? ' (weaker signal — verify before deleting)'
+    : '';
+}
 
 /** Pure: render the dry-run plan as the operator-facing text block. */
 export function renderDryRun(plan, opts = {}) {
-  const { baseBranch = null } = opts;
+  const { baseBranch = null, now } = opts;
   const lines = [
     `${TAG} DRY RUN (nothing deleted) — ${plan.candidates.length} candidate(s)`,
   ];
@@ -23,7 +74,9 @@ export function renderDryRun(plan, opts = {}) {
       const pr = c.prNumber ? `PR #${c.prNumber}` : c.detectedBy;
       const wt = c.hasWorktree ? ` (worktree: ${c.worktreePath})` : '';
       const remoteOnly = c.localExists === false ? ' (remote-only)' : '';
-      lines.push(`  • ${c.branch} — ${pr}${wt}${remoteOnly}`);
+      lines.push(
+        `  • ${c.branch} — ${pr}${wt}${remoteOnly}${contentMergedNote(c)}`,
+      );
     }
   }
   const skipped = plan.skipped ?? [];
@@ -40,6 +93,15 @@ export function renderDryRun(plan, opts = {}) {
     const line = renderLatestPrSkipLine(skip);
     if (line) lines.push(line);
   }
+  for (const skip of skipped) {
+    const line = renderNotMergedSkipLine(skip, { now });
+    if (line) lines.push(line);
+  }
+  if (plan.ghDegraded) {
+    lines.push(
+      `${TAG} ⚠️ gh probe degraded — candidates rely on git-only signals (ancestry + content-equivalence) for this run`,
+    );
+  }
   return lines;
 }
 
@@ -47,7 +109,8 @@ export function renderDryRun(plan, opts = {}) {
  * Pure: render a single latest-PR-state skip line. Returns null when the
  * skip reason is not one of the latest-PR family — `renderDryRun` filters
  * by truthy return value so unrelated skip reasons (`protected`,
- * `current-head`, `filtered`, `not-merged`) stay quiet.
+ * `current-head`, `filtered`) stay quiet here. `not-merged` gets its own
+ * renderer ({@link renderNotMergedSkipLine}).
  *
  * @param {{ branch: string, reason: string, prNumber?: number, tipSha?: string, mergedSha?: string }} skip
  * @returns {string | null}
@@ -64,7 +127,10 @@ export function renderLatestPrSkipLine(skip) {
   if (skip.reason === 'tip-diverged-from-merge') {
     const tip = skip.tipSha ? skip.tipSha.slice(0, 7) : '<unknown>';
     const merged = skip.mergedSha ? skip.mergedSha.slice(0, 7) : '<unknown>';
-    return `${TAG} ⏭️  ${skip.branch} skipped — tip ${tip} diverges from ${prRef}'s merged ${merged} (post-merge force-push)`;
+    return (
+      `${TAG} ⏭️  ${skip.branch} skipped — tip ${tip} diverges from ${prRef}'s merged ${merged} (post-merge force-push); ` +
+      `resolve by deleting manually (\`git branch -D ${skip.branch}\`) or pushing the follow-up commit`
+    );
   }
   if (skip.reason === 'latest-pr-unknown-state') {
     return `${TAG} ⏭️  ${skip.branch} skipped — ${prRef} has an unrecognized state`;
@@ -160,6 +226,7 @@ export function buildJsonEnvelope({
     baseBranch,
     candidates: plan.candidates,
     skipped: plan.skipped,
+    ghDegraded: plan.ghDegraded ?? false,
     worktrees: r.worktrees,
     local: r.local,
     remote: r.remote,

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

@@ -28,6 +28,16 @@
  *            lockfile around plan + execute. On lock contention the
  *            sweep is skipped (the host continues — same contract as a
  *            plan failure).
+ *   - 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.
@@ -81,6 +91,7 @@ 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,
@@ -137,6 +148,7 @@ export async function sweepMergedBranches({
         localDeleted: 0,
         remoteDeleted: 0,
         protected: [],
+        contentMerged: [],
         failures: [],
       };
     }
@@ -213,6 +225,31 @@ export function sweepMergedStoryBranches(args = {}) {
   });
 }
 
+/**
+ * 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 engine can stay focused on the lock and fast-forward wrappers.
@@ -240,7 +277,18 @@ async function runSweepUnderLock({
     return zeroResult({ error: `plan: ${msg}` });
   }
 
-  if (plan.candidates.length === 0) {
+  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,
@@ -249,12 +297,13 @@ async function runSweepUnderLock({
       localDeleted: 0,
       remoteDeleted: 0,
       protected: [],
+      contentMerged,
       failures: [],
     };
   }
 
   const { reapable, protectedList } = await partitionCandidates({
-    candidates: plan.candidates,
+    candidates: reapCandidates,
     protectionFn,
     protectionCtx,
     log,
@@ -263,15 +312,16 @@ async function runSweepUnderLock({
 
   if (reapable.length === 0) {
     log.info(
-      `${logTag} 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: [],
     };
   }
@@ -279,7 +329,8 @@ async function runSweepUnderLock({
   return executeReap({
     reapable,
     protectedList,
-    candidateCount: plan.candidates.length,
+    contentMerged,
+    candidateCount: reapCandidates.length,
     cwd,
     executeCleanupFn,
     log,
@@ -295,6 +346,7 @@ async function runSweepUnderLock({
 function executeReap({
   reapable,
   protectedList,
+  contentMerged,
   candidateCount,
   cwd,
   executeCleanupFn,
@@ -314,6 +366,7 @@ function executeReap({
       localDeleted: 0,
       remoteDeleted: 0,
       protected: protectedList,
+      contentMerged,
       failures: [{ branch: null, scope: 'execute', stderr: msg }],
       error: `execute: ${msg}`,
     };
@@ -346,6 +399,7 @@ function executeReap({
     localDeleted,
     remoteDeleted,
     protected: protectedList,
+    contentMerged,
     failures: result.failures,
   };
 }
@@ -450,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)
   );

package/.agents/scripts/providers/github/tickets.js

@@ -22,6 +22,7 @@
  */
 
 import { parseBlockedBy, parseBlocks } from '../../lib/dependency-parser.js';
+import { stampFrameworkVersion } from '../../lib/framework-version.js';
 import { Logger } from '../../lib/Logger.js';
 import { TYPE_LABELS } from '../../lib/label-constants.js';
 import { addIssueToBoard } from './board-add.js';
@@ -56,11 +57,20 @@ const SEARCH_PAGE_CAP = 10;
  * arrays on the Story body authored by the decomposer; there is no
  * server-side rendering of a four-section payload at create time.
  *
+ * Story #4382 — this is also where a Story body is stamped, once, with the
+ * running Mandrel framework version and authoring date (hidden `mandrel_version`
+ * / `authored_at` meta field + a visible `> 🏷️ Authored with Mandrel …`
+ * marker) via {@link stampFrameworkVersion}. The stamp is immutable: a body
+ * that already carries a version (e.g. a reconciler re-create) is preserved
+ * verbatim. The `stamp` override exists for deterministic tests; production
+ * callers omit it so the running version and today's date are used.
+ *
  * @param {{
  *   body: string,
  *   parentId: number,
  *   epicId?: number,
  *   dependencies?: number[],
+ *   stamp?: { version?: string, authoredAt?: string } | false,
  * }} opts
  * @returns {string}
  *
@@ -75,8 +85,15 @@ export function composeStoryBody({
   parentId,
   epicId,
   dependencies = [],
+  stamp,
 }) {
-  const head = typeof body === 'string' ? body : '';
+  const rawHead = typeof body === 'string' ? body : '';
+  // `stamp === false` → footer-only recomposition: the caller (the reconciler
+  // UPDATE/diff path) owns stamp preservation itself and must NOT introduce a
+  // fresh authoring stamp, which would churn or bump the version on every
+  // reconcile. Every other call is a create — stamp once (immutably).
+  const head =
+    stamp === false ? rawHead : stampFrameworkVersion(rawHead, stamp ?? {});
   const lines = ['---', `parent: #${parentId}`];
   if (epicId !== undefined && epicId !== null) {
     lines.push(`Epic: #${epicId}`);

package/.agents/skills/core/epic-plan-consolidate/SKILL.md

@@ -32,6 +32,11 @@ allowed_tools:
 Senior Project Manager + Orchestrator, acting as a **holistic critic** with
 fresh context — deliberately *separate* from `epic-plan-decompose-author` (the
 generator) so the pass is a fresh-context review, not a same-pass self-critique.
+The `/plan` workflow delivers that fresh context by **dispatching this skill
+inside a genuine sub-agent** (`Agent` tool, `subagent_type: general-purpose`) at
+Phase 8.3, rather than activating it inline in the authoring turn — the
+sub-agent does not inherit the conversation that authored the draft, so the
+critic cannot grade its own homework.
 
 > **Read [`examples.md`](./examples.md) on demand** for the extended rationale:
 > why this critic runs with fresh context, why scope conservation is your
@@ -50,8 +55,8 @@ emit a plan the validator would reject.
 
 ## Inputs
 
-The dispatcher passes the Epic ID as the Skill argument. The Skill itself
-reads:
+The `/plan` workflow dispatches this skill inside a fresh-context sub-agent,
+passing the Epic ID as the Skill argument. The Skill itself reads:
 
 - `temp/epic-<Epic_ID>/tickets.json` — the **draft** Story array the
   `epic-plan-decompose-author` Skill wrote. This is the consolidation input.