mandrel 1.86.0 → 1.87.0

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.

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

@@ -31,7 +31,12 @@ allowed_tools:
 Senior Engineer + Architect, acting as a **fresh-context pre-mortem critic** —
 deliberately *separate* from `epic-plan-decompose-author` (the generator) and
 `epic-plan-consolidate` (the scope-preserving merge critic) so it is a
-fresh-context, code-reading review, not a same-pass self-critique.
+fresh-context, code-reading 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.5, rather than activating it inline in the authoring turn — the sub-agent does
+not inherit the authoring conversation, so its code-reading review is
+independent of the draft it grades.
 
 > **Read [`examples.md`](./examples.md) on demand** for the extended rationale:
 > why this critic opens the actual cited code, why it is additive-recommendation
@@ -52,7 +57,8 @@ surfaces reaches GitHub unreviewed.
 
 ## Inputs
 
-The workflow 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** (or consolidated) Story
   array. This is the pre-mortem subject.

package/.agents/skills/skills.index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-07-04T23:12:38.376Z",
+  "generatedAt": "2026-07-08T12:24:41.101Z",
   "generator": "generate-skills-index.js@1",
   "skills": [
     {
@@ -377,8 +377,8 @@
       "tier": "stack",
       "category": "architecture",
       "path": ".agents/skills/stack/architecture/subagent-orchestration/SKILL.md",
-      "description": "Coordinates complex tasks via task-isolated subagents. Use when one objective is too large for a single agent or when independent work streams should run concurrently with minimal context bleed. One objective per subagent; summarize before returning to keep the main context window clean.",
-      "policyCapsuleBullets": 7,
+      "description": "Coordinates complex tasks via task-isolated subagents. Use when one objective is too large for a single agent or when independent work streams should run concurrently with minimal context bleed. One objective per subagent; summarize before returning to keep the orchestrator's context window clean. Applies recursively — an orchestrator at any supported nesting depth applies the same policy to its own children.",
+      "policyCapsuleBullets": 8,
       "allowedTools": null,
       "vendor": null
     },

package/.agents/skills/stack/architecture/subagent-orchestration/SKILL.md

@@ -4,11 +4,33 @@ description:
   Coordinates complex tasks via task-isolated subagents. Use when one objective
   is too large for a single agent or when independent work streams should run
   concurrently with minimal context bleed. One objective per subagent;
-  summarize before returning to keep the main context window clean.
+  summarize before returning to keep the orchestrator's context window clean.
+  Applies recursively — an orchestrator at any supported nesting depth applies
+  the same policy to its own children.
 ---
 
 # Skill: Subagent Orchestration
 
+## Recursive orchestration model
+
+This skill describes **recursive orchestration**, not a fixed two-tier
+"main agent vs. subagents" split. An **orchestrator** is any agent that
+dispatches sub-agents; a sub-agent is itself an orchestrator over its own
+children. The Claude Code harness carries the `Agent` tool into sub-agents
+(verified nesting depth 2, announced max depth 5; see
+[#2870](https://github.com/dsj1984/mandrel/issues/2870)), so the same
+one-objective / verify / parallelize policy applies **at every level** —
+substitute "orchestrator" for "main agent" and "child" for "subagent"
+throughout and the rules hold unchanged. Keeping a given dispatch level
+flat remains a legitimate **design choice** (e.g. the `/deliver` wave
+loop), but it is no longer forced by a harness limitation.
+
+The cost caution compounds with depth: every nesting level re-pays the
+full always-loaded context, so an orchestrator MUST weigh the depth it
+opens against its budget (see
+[`instructions.md` § 4](../../../../instructions.md)) and stay within the
+supported depth envelope.
+
 ## Policy Capsule
 
 - Dispatch one objective per subagent; never bundle unrelated goals into a single delegation.
@@ -16,11 +38,13 @@ description:
 - Specify the expected return format explicitly (JSON summary, diff, bullet list) in every handoff.
 - Verify the subagent's output before incorporating it; treat returned artifacts as untrusted until checked.
 - Run non-dependent subagents in parallel; serialize only when one subagent's output is required input for another.
-- Require a concise summary back from each subagent to keep the main context window clean.
+- Require a concise summary back from each subagent to keep the orchestrator's context window clean.
 - Investigate subagent failures rather than retrying blindly with the same prompt.
+- Respect the nesting depth budget; each level opened re-pays the always-loaded context, so orchestrate deeper only when the isolation or parallelism gain justifies the cost.
 
 Internal protocol for managing complex tasks through the creation and
-coordination of subagents.
+coordination of subagents, applied recursively by the orchestrator at any
+supported depth.
 
 ## 1. Core Principles
 
@@ -28,8 +52,11 @@ coordination of subagents.
   with multiple unrelated tasks.
 - **Minimal Context:** Provide only the necessary context (files, docs, specific
   goal) to keep the subagent focused and token-efficient.
-- **Verification:** The main agent must always verify the subagent's output
-  before incorporating it into the final solution.
+- **Verification:** The orchestrator must always verify each child's output
+  before incorporating it into its own result — at every level of the tree.
+- **Depth Awareness:** Orchestration is recursive; before opening a deeper
+  level, confirm the work justifies re-paying the always-loaded context and
+  that the nesting stays within the supported depth envelope.
 
 ## 2. Operation Standards
 
@@ -38,11 +65,12 @@ coordination of subagents.
 - **Error Handling:** If a subagent fails or returns an ambiguous result,
   investigate the failure rather than retrying blindly.
 - **Parallelism:** Use subagents to perform non-dependent tasks concurrently
-  (e.g., auditing three different modules simultaneously).
+  (e.g., auditing three different modules simultaneously). A child that is
+  itself an orchestrator may parallelize its own sub-units the same way.
 
 ## 3. Best Practices
 
-- **State Sync:** Ensure the main agent's mental model remains the source of
+- **State Sync:** Ensure the orchestrator's mental model remains the source of
   truth if multiple subagents modify the codebase.
 - **Summarization:** Require subagents to provide a concise summary of their
-  findings to prevent the main context window from being flooded.
+  findings to prevent the orchestrator's context window from being flooded.

package/.agents/workflows/git-cleanup.md

@@ -18,11 +18,17 @@ confirmation:
 3. **reap merged local branches** — the existing squash-aware
    `gh pr list --state merged` + `git branch --merged <base>` sweep,
    with attached worktrees removed first. Optionally also deletes the
-   `origin/<branch>` ref when `--remote` is passed. With `--remote`,
-   the planner additionally enumerates `refs/remotes/origin/*` and
-   reaps any **remote-only** merged branches — branches whose local
-   ref is already gone (or never existed) but whose `origin/<branch>`
-   still points at a merged PR.
+   `origin/<branch>` ref when `--remote` is passed. Every default run
+   also **enumerates** `refs/remotes/origin/*` and reports any
+   **remote-only** merged branches — branches whose local ref is
+   already gone (or never existed) but whose `origin/<branch>` still
+   points at a merged PR — even without `--remote`; `--remote` is still
+   required to *delete* them. A third branch, whose content already
+   landed in `<base>` by another route (a squash-merged Epic PR, a
+   cherry-pick, a manual `merge --squash`), is caught by a
+   **content-equivalence probe** (`git merge-tree --write-tree`,
+   git ≥ 2.38) even when it has no merged PR of its own and is not a
+   git ancestor of `<base>`.
 4. **triage `git stash` entries** — list every stash and prompt for
    `drop / keep / quit` per entry (or pass `--drop-stashes <ref>` for
    non-interactive use).
@@ -150,6 +156,10 @@ programmatic consumption:
       "detectedBy": "gh"
     }
   ],
+  "skipped": [
+    { "branch": "story-4200", "reason": "not-merged", "lastCommitAt": "2026-05-01T00:00:00Z" }
+  ],
+  "ghDegraded": false,
   "worktrees": [{ "path": "C:/repo/.worktrees/fix-foo", "ok": true, "dirty": false }],
   "local":  [{ "branch": "fix/foo", "ok": true, "alreadyGone": false }],
   "remote": [{ "branch": "fix/foo", "ok": true, "alreadyGone": true }],
@@ -200,18 +210,51 @@ follow-up prune when `--remote` is set, so passing both is idempotent
 
 ### branches
 
-The merged-branch sweep semantics:
-
-- A branch is a candidate iff it is not `<base>`, not the current
-  HEAD, not in `git config branch.protectedBranches`, and either has a
-  merged PR (`gh pr list --head <branch> --state merged`) or appears in
-  `git branch --merged <base>`.
+The merged-branch sweep recognizes three detection signals, in order:
+
+1. **`detectedBy: 'gh'`** — the branch has a merged PR
+   (`gh pr list --head <branch> --state all`, classified by the
+   **latest** PR's state).
+2. **`detectedBy: 'git-merged'`** — the branch is a git ancestor of
+   `<base>` (`git branch --merged <base>`), or of `origin/<base>` when
+   that remote-tracking ref exists (unioned so a stale local `<base>` —
+   fast-forward phase skipped, or `--branches` run alone — no longer
+   hides a branch already merged on the remote).
+3. **`detectedBy: 'content-merged'`** (Story #4395) — the branch has no
+   reapable PR verdict and is not an ancestor of `<base>` under either
+   anchor, but simulating the merge via
+   `git merge-tree --write-tree <base> <branch>` (git ≥ 2.38) produces a
+   tree identical to `<base>`'s own tree — i.e. applying the branch's
+   changes on top of `<base>` is a content no-op. This catches
+   `story-<id>` branches merged into `epic/<id>` whose Epic PR
+   **squash-merged** to `main` (the story commits are not ancestors of
+   `main` and the story branch usually has no PR of its own), and any
+   other branch whose content landed via a different route (a renamed
+   head, a cherry-pick, a manual `merge --squash`). When git rejects
+   `--write-tree` (git < 2.38) or the simulated merge conflicts, the
+   probe is inconclusive and the branch keeps its existing `not-merged`
+   skip — the signal never guesses. `content-merged` candidates render
+   with a "weaker signal — verify before deleting" annotation in the
+   dry-run list and are called out separately in the confirmation
+   prompt, since — unlike a merged PR or git ancestry — no CI or GitHub
+   merge check ever validated this branch's exact diff.
+
+Other candidate semantics:
+
+- A branch is a candidate iff it is not `<base>`, not the current HEAD,
+  not in `git config branch.protectedBranches`, and matches one of the
+  three signals above.
 - When a candidate has an attached worktree, the worktree is removed
   (force if dirty) **before** `git branch -D`, mirroring the pattern in
   [`worktree-lifecycle.md`](helpers/worktree-lifecycle.md).
 - `--remote` is required on top of `--execute` to touch `origin/`.
+- A throwing `gh` runner (auth failure, rate limit, missing binary) no
+  longer aborts the run: the branches phase logs one warning and
+  continues with the git-only signals (ancestry + content-equivalence).
+  The JSON envelope's `ghDegraded: true` records that this happened for
+  the run, and the dry-run text carries a matching warning line.
 
-The skip taxonomy distinguishes two unreapable cases:
+The skip taxonomy:
 
 - `reason: 'protected'` — the base branch or a name in
   `git config branch.protectedBranches`. Not reapable; ignore.
@@ -219,15 +262,26 @@ The skip taxonomy distinguishes two unreapable cases:
   `git checkout <base>`. The dry-run output surfaces a remediation
   hint so the operator sees the recovery path without having to look
   in the JSON envelope.
-
-The `--remote` flag also opts the planner into a **remote-only
+- `reason: 'tip-diverged-from-merge'` — the latest PR merged, but the
+  branch's tip has since moved past the merged commit (a post-merge
+  force-push). The dry-run line names both SHAs and a remediation hint
+  (delete manually via `git branch -D <branch>`, or push the follow-up
+  commit).
+- `reason: 'not-merged'` — none of the three detection signals matched.
+  Previously silent; the dry-run output now lists every surviving
+  `not-merged` branch as a one-line-per-branch summary with its
+  last-commit age, so the operator can see why a leftover branch isn't
+  reaped instead of hunting for it by hand.
+
+Every default run also opts the planner into a **remote-only
 enumeration pass**: in addition to walking `refs/heads/*`, the planner
 also walks `refs/remotes/origin/*` and emits candidates for any branch
 that exists on `origin` with a merged PR but has no local ref. These
-candidates carry `detectedBy: 'remote-only'` and `localExists: false`,
-and the executor runs only the `git push --delete origin/<branch>`
-path for them (no local `git branch -D` is attempted — there is no
-local branch to delete).
+candidates carry `detectedBy: 'remote-only'` and `localExists: false`
+and are always shown in the dry-run list; **deleting** them (via the
+`git push --delete origin/<branch>` path — no local `git branch -D` is
+attempted, since there is no local branch) still requires `--remote` on
+top of `--execute`, unchanged.
 
 ### stashes