mandrel 2.63.0 → 2.65.0

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

@@ -138,38 +138,29 @@ export class IssuesGateway {
 
   /**
    * Resolve an issue's container parent in one request via `Issue.parent`.
-   * Never throws: no parent, an odd shape, or sub-issues being unavailable all
-   * return `null`, leaving the caller's checklist fallback to run.
+   * `null` means "no parent"; a degraded lookup throws after retries.
    *
    * @param {number} number Issue number whose parent to resolve.
    * @returns {Promise<object|null>} Mapped parent ticket, or null.
+   * @throws {Error} When the lookup degrades.
    * @field-manifest GraphQL Issue.parent: number, id, title, body, state,
    *                 labels.nodes.name, assignees.nodes.login
    */
   async getParentIssue(number) {
     const issueNumber = Number(number);
     if (!Number.isInteger(issueNumber) || issueNumber <= 0) return null;
-    let data;
-    try {
-      data = await withTransientRetry(
-        () =>
-          this.ghGraphql(
-            PARENT_ISSUE_QUERY,
-            { owner: this.owner, repo: this.repo, number: issueNumber },
-            { headers: { 'GraphQL-Features': 'sub_issues' } },
-          ),
-        {
-          label: `getParentIssue #${issueNumber}`,
-          onRetry: defaultRetryWarn,
-        },
-      );
-    } catch (err) {
-      Logger.warn(
-        `[GitHubProvider] parent lookup for #${issueNumber} degraded to none ` +
-          `(${err?.message ?? err}).`,
-      );
-      return null;
-    }
+    const data = await withTransientRetry(
+      () =>
+        this.ghGraphql(
+          PARENT_ISSUE_QUERY,
+          { owner: this.owner, repo: this.repo, number: issueNumber },
+          { headers: { 'GraphQL-Features': 'sub_issues' } },
+        ),
+      {
+        label: `getParentIssue #${issueNumber}`,
+        onRetry: defaultRetryWarn,
+      },
+    );
     return subIssueNodeToTicket(data?.repository?.issue?.parent ?? null);
   }
 

package/.agents/scripts/sync-claude-agents.js

@@ -4,7 +4,7 @@
  * Project `.agents/agents/` and `.agents/local/agents/` into a flat
  * `.claude/agents/` tree — the sibling of `sync-claude-commands.js`, with the
  * same payload-wins shadowing and orphan-reap. A role agent runs on its own
- * system prompt (no `CLAUDE.md` closure), which is the point of routing to it.
+ * system prompt (no entry-doc `@`-import closure), which is the point of routing to it.
  */
 
 // cli-opt-out: top-level-await script with no main() function — runAsCli wraps an async main, which doesn't apply here.

package/.agents/workflows/audit-quality.md

@@ -12,7 +12,8 @@ the Story under audit. The shared lens machinery lives in
 `{{auditOutputDir}}/audit-quality-results.md`. Each finding carries a
 **Category:** (`Flakiness | Coverage | Performance | Mocking | Test Plans`); the
 report adds a **Test Strategy Assessment** table (Unit / Integration / E2E /
-Test Plans: Healthy / Needs Work / Missing).
+Test Plans / Property-Based Testing: Healthy / Needs Work / Missing, or `N/A`
+for Property-Based Testing when no module is a candidate).
 
 ## Scope
 
@@ -130,6 +131,36 @@ Evaluate the gathered context against the following test quality dimensions:
    finding here. Route the *architectural* framing of the same defect to
    [`audit-architecture`](audit-architecture.md)'s Shipped-But-Never-Wired
    dimension; this lens owns the **missing-test** framing.
+8. **Property-Based Coverage — Invariants Tested Only by Examples.** Flag a
+   module whose correctness rests on an invariant but whose tests are all
+   hand-picked examples, which structurally cannot reach the inputs nobody
+   thought to pick. A module is a candidate **only** on code evidence: a
+   documented invariant or "never"/"always" claim in a header comment; an
+   explicit state machine or status/label transition table; an
+   encode/decode, parse/serialize or normalise pair (round-trip); a
+   merge/dedup/sort/scheduler function; bounded-concurrency or retry
+   coordination over async I/O; or an idempotency claim. A module with no
+   stated or implied invariant is **never** a finding. Rank candidates by
+   Step 0's churn × coverage gap and cite their `baselines/` coverage/CRAP row
+   where one exists.
+
+   - **Toolchain by ecosystem, never one library.** Detect an existing
+     property-testing library from the consumer's manifests (e.g.
+     `fast-check` for JS/TS, `hypothesis` for Python, `proptest`/`quickcheck`
+     for Rust, `jqwik` for the JVM, `rapid`/`gopter` for Go); recommend the
+     ecosystem-idiomatic one only when none is present.
+   - Severity: an async/concurrency coordinator, or a guard whose
+     invariant protects an irreversible write, tested only by examples →
+     **High**; any other invariant-bearing module with example-only tests →
+     **Medium**; toolchain absent with no High/Medium candidate → **one Low**
+     roll-up finding, not one per module.
+   - Category: file under `Coverage`. A property test whose seed is
+     neither pinned nor printed on failure goes under `Flakiness`: a red that
+     cannot be reproduced breaks the reproducibility the rubric demands.
+   - **Name the property.** Each finding states the invariant as a testable
+     property (e.g. `decode(encode(x)) === x`; "no transition leaves a
+     terminal state") plus its generator shape (the input domain to draw
+     from) — never a bare "add property tests".
 
 ## Constraint (lens-specific carve-out)
 
@@ -150,10 +181,14 @@ table:
 
 ## Test Strategy Assessment
 
-| Layer               | Status                           | Notes          |
-| ------------------- | -------------------------------- | -------------- |
-| Unit Testing        | [Healthy / Needs Work / Missing] | [Brief reason] |
-| Integration Testing | [Healthy / Needs Work / Missing] | [Brief reason] |
-| E2E Testing         | [Healthy / Needs Work / Missing] | [Brief reason] |
-| Test Plans          | [Healthy / Needs Work / Missing] | [Brief reason] |
+| Layer                  | Status                                 | Notes          |
+| ---------------------- | -------------------------------------- | -------------- |
+| Unit Testing           | [Healthy / Needs Work / Missing]       | [Brief reason] |
+| Integration Testing    | [Healthy / Needs Work / Missing]       | [Brief reason] |
+| E2E Testing            | [Healthy / Needs Work / Missing]       | [Brief reason] |
+| Test Plans             | [Healthy / Needs Work / Missing]       | [Brief reason] |
+| Property-Based Testing | [Healthy / Needs Work / Missing / N/A] | [Brief reason] |
 ```
+
+`Property-Based Testing` reads `N/A` when the repo has no candidate module
+(dimension 8), so a repo with no invariant-bearing code is not nagged.

package/.agents/workflows/helpers/acceptance-self-eval.md

@@ -69,7 +69,7 @@ per-criterion, mid-delivery, and evaluates the actual work product.
    > `delivery.routing.roleScopedAgents` is enabled (the **default**), use
    > `subagent_type: acceptance-critic`: it boots on the role-scoped
    > [`acceptance-critic`](../../agents/acceptance-critic.md) context (its own
-   > system prompt, no `CLAUDE.md` @-closure) carrying the maker-blind
+   > system prompt, no entry-doc @-closure) carrying the maker-blind
    > invariant and the verdict schema standalone. With the kill-switch off
    > (`roleScopedAgents: false`), fall back to
    > `subagent_type: general-purpose`. This loop already runs inside a Story

package/.agents/workflows/helpers/code-review.md

@@ -74,8 +74,8 @@ How each tier changes the review protocol:
   adversarial pass over the diff hunting for integration regressions and
   security-relevant edges before findings are finalized.
 
-The LLM-backed review providers (codex, security-review, ultrareview) render
-the resolved `depth` into the prompt/instructions they emit so the underlying
+The LLM-backed review providers (code-review, codex, security-review,
+ultrareview) render the resolved `depth` into the prompt/instructions they emit so the underlying
 model actually changes thoroughness. The native provider deliberately ignores
 `depth` — its mechanical lint + maintainability sweep already scales with diff
 size, and there is no "review harder" knob a deterministic scorer can turn (its
@@ -110,44 +110,21 @@ The pipeline will:
 - Run a focused lint check on the change set.
 - Post a structured summary report to the `[TICKET_ID]` issue.
 
-### Step 1a — Story-scope local-lens pass (`scope: story` only)
-
-When `scope === 'story'`, the shared review spine
-[`runStoryReviewCore`](../../scripts/lib/orchestration/story-close/phases/review-core.js)
-runs a **shift-left local-lens pass** in the same close subprocess, *before*
-returning the review envelope. It:
-
-1. Enumerates the actual Story diff (`baseRef...headRef` via
-   `git diff --name-only`).
-2. Selects the **local-tier** lenses that own a concern decidable from a single
-   Story's diff — `resolveLensTier(lens) === 'local'` **plus** the pure
-   `matchesAnyFilePattern` matcher against the diff (the audit-suite SDK's
-   [`selectLocalLenses`](../../scripts/lib/audit-suite/selector.js)). This is
-   deliberately **not** `selectAudits`: `selectAudits` unions in keyword and
-   gate matches and has no per-tier gate, so it would widen the roster past the
-   footprint-matched local set this tier owns.
-3. Materializes the matched roster at **`light`** depth
-   (`STORY_SCOPE_LENS_DEPTH`) via `runAuditSuite`, surfacing the outcome on the
-   review envelope's `localLensReview` field.
-
-A diff that matches no local lens adds **no** lens work (the roster is empty and
-`runAuditSuite` is never invoked). The pass is advisory and best-effort: a git
-or materialization failure degrades to a skipped envelope and never blocks the
-close.
-
-The live close entry point —
-[`runStoryScopeReview`](../../scripts/lib/orchestration/single-story-close/phases/code-review.js)
-— reaches this pass through the shared `runStoryReviewCore` spine. Because
-the pass lives inside the close subprocess (invoked after the delivering
-child exits), it honors the maker-blind invariant above: a maker never runs
-its own local-lens review.
+### Story scope runs no lens pass
+
+Close runs **no** audit-lens pass of its own (Story #5416 retired it: it
+materialized prompt files no workflow read, then armed auto-merge without
+waiting). The Story-scope review is this pipeline plus CI. Local-tier lens
+concerns are covered shift-left by the write-time authoring checklists
+threaded into the Story prompt; the on-demand `/audit-*` workflows remain the
+way to run a full lens over a change.
 
 ## Step 2 — Review Pillars
 
 For each changed file, execute a strict review against four pillars. The
 second pillar (**Integration Review**) deliberately defers the security /
 performance / quality / coverage sweeps to the change-set-scoped lenses —
-those ran shift-left in the Story-scope local-lens pass (Step 1a).
+those are covered shift-left by the write-time lens checklists.
 Re-walking those sweeps a second time in this pillar is duplication, not
 defense-in-depth.
 
@@ -173,9 +150,9 @@ Does the implementation match the Story's acceptance criteria and folded Spec?
 
 The diff under review is `baseRef..headRef`
 (`main..story-<storyId>`, or the configured base branch to the Story
-branch). The Story-scope local-lens pass (Step 1a) has already covered the
-local-tier concerns. Lens findings and pillar findings share the single
-`verification-results` comment this pass posts. The
+branch). The write-time lens checklists have already covered the local-tier
+concerns. Pillar findings land in the single `verification-results` comment
+this pass posts. The
 integration view here focuses on cross-cutting ripple within the Story and
 contract drift against the base branch. Look for:
 
@@ -260,7 +237,7 @@ prior baseline before merging.
 
 Findings are **persisted as a `verification-results` structured comment on
 the `[TICKET_ID]` issue** by `runCodeReview` (the unified findings contract —
-this single comment carries the Story-scope lens findings). The target
+this single comment carries the Story-scope review findings). The target
 ticket is the Story. The comment
 is idempotent — re-runs replace the prior one — and its body includes
 severity-tier counts plus the full findings list so downstream workflows

package/.agents/workflows/helpers/deliver-reference.md

@@ -175,7 +175,7 @@ into batches of `cap` and dispatch each batch in its own turn.
 exposes agent dispatch, spawn each ready Story as its own
 `subagent_type: story-worker` sub-agent — it boots on the role-scoped
 [`story-worker`](../../agents/story-worker.md) context (its own system prompt, no
-`CLAUDE.md` @-closure) carrying the load-bearing delivery MUSTs standalone. The
+entry-doc @-closure) carrying the load-bearing delivery MUSTs standalone. The
 sub-agent executes [`deliver-story.md`](deliver-story.md) Steps 0–2.5
 (init → implement → acceptance self-eval → **push**) and stops there; **you**
 own Step 3, serialized — see `/mandrel-deliver` § Closing what the workers hand back.
@@ -291,7 +291,9 @@ confirm instead (`captureStoryFollowUps`).
   reopen the issue.
 - The parent lookup resolves the native parent edge in **one** call
   (`getParentIssue`), falling back to a `type::epic` scan for a child linked by
-  checklist alone. Children are the body checklist **union** the native
+  checklist alone. An authoritative "no parent" narrows that scan to Epics
+  whose body checklist names the Story (no per-Epic native read); only a
+  degraded lookup reads every scanned Epic's native children. Children are the body checklist **union** the native
   sub-issue edges — the same reader `/mandrel-deliver`'s expansion uses.
 - A checklist row citing an id that resolves to nothing is **dropped with a
   warning** when the native read succeeded; an unresolvable *native* edge

package/.agents/workflows/helpers/deliver-story.md

@@ -72,6 +72,9 @@ One branch, one PR to `main`, commits against the inline `acceptance[]` /
 1. Read the Story body; its acceptance criteria are the contract. Docs are
    digest-first; read a caller-provided `checklistPath` first, and walk any
    `## Slicing` rows as **intra-session checkpoints** (reference § Step 1).
+   After a context summary, re-derive progress from `git log` on
+   `story-<id>` against the `## Slicing` rows (each checkpoint is a commit
+   boundary) before continuing.
 2. Implement and commit on the Story branch, iterating with quick advisory
    gates (`typecheck`, `lint`, scoped tests) — the full chain runs in Step 3,
    and the **one** full-suite run at Step 2.5.

package/.agents/workflows/helpers/plan-reference.md

@@ -100,19 +100,20 @@ not re-deriving which assumptions were really the agent's to make.
 
 ## Gate #1 → the one advisory line
 
-Gate #1 stops for exactly two things — the sharpened plan intent and any HITL
-unknown — and everything else the envelope surfaced collapses to **one
-advisory line** beneath it. Nothing on that line stops the run,
-reroutes it, or is invoked by `/mandrel-plan`; each item names something the
-operator may prefer to do instead, and the run proceeds either way. Under
+Gate #1 stops only when there is at least one HITL unknown or
+`duplicates[]` is non-empty; otherwise the run announces the sharpened plan
+intent plus the advisory line and continues to authoring. Everything else the
+envelope surfaced collapses to **one advisory line** beneath the gate.
+Nothing on that line reroutes the run or is invoked by `/mandrel-plan`; each
+item names something the operator may prefer to do instead. Under
 `--yes` the line is recorded and planning continues — an unattended run has
 nobody to take an offer.
 
 The line names, in order, whichever of these the envelope carries:
 
 - **`duplicates[]`** — open Stories the seed resembles (never Epics). Name
-  the top one or two by id and title; a plan that duplicates open work is
-  still the operator's call.
+  the top one or two by id and title. A plan that duplicates open work is
+  still the operator's call, so a non-empty list also stops Gate #1.
 - **Open `intake` rows** (`priorFeedback`) — CI-gap intake filings written by
   [`file-ci-gap.js`](../../scripts/file-ci-gap.js) when a delivery reached an
   Option-2 verdict in [`ci-remediation.md`](../../rules/ci-remediation.md).
@@ -339,7 +340,7 @@ On `dispatch: true`, dispatch **one fresh-context, maker-blind sub-agent**.
 When `delivery.routing.roleScopedAgents` is enabled (the **default**), use
 `subagent_type: plan-critic` — it boots on the role-scoped
 [`plan-critic`](../../agents/plan-critic.md) context (its own system prompt,
-no `CLAUDE.md` @-closure) that carries the maker-blind invariant, the
+no entry-doc @-closure) that carries the maker-blind invariant, the
 `pre-mortem` charter, and the output shape standalone. When the kill-switch
 is off (`roleScopedAgents: false`) or the host cannot spawn at this depth,
 fall back to a generic sub-agent and hand it the same charter. Either way the

package/.agents/workflows/mandrel-deliver.md

@@ -76,7 +76,8 @@ to an attended run.
    it cannot read — a missing gate would co-dispatch against an unlanded
    blocker.
 
-2. **Confirm (N>1).** Present the order; wait unless `--yes`.
+2. **Announce (N>1).** Present the resolved order and proceed — do not wait
+   for confirmation; the operator can interject mid-run to change it.
 
 3. **Run the beat.** One command per beat, repeated until the envelope reports
    the run `done`:

package/.agents/workflows/mandrel-plan.md

@@ -71,13 +71,16 @@ assumed; a **HITL** unknown goes to Gate #1. Under `--yes` do not ask free-form
 operator questions — AFK unknowns are still researched; only HITL unknowns land
 in Key Assumptions, each a decision-made-by-default.
 
-**Gate #1** — STOP for exactly two things: confirm the sharpened plan intent,
-and settle any HITL unknown the operator owns. Everything else the envelope
-surfaced — `duplicates[]`, open `intake` rows, a truthy
-`memoryPoolAdvisory.recommend`, a truthy `complexitySignals.uiSurface` naming
-[`/prototype`](prototype.md) (never invoke it here) — collapses to
-**one advisory line** under the gate; none of it stops the run or reroutes
-it ([ref](helpers/plan-reference.md)). Under `--yes`, auto-proceed.
+**Gate #1** — STOP only when a HITL unknown the operator owns exists or
+`duplicates[]` is non-empty (planning a duplicate of open work stays the
+operator's call): confirm the sharpened plan intent and settle it. Otherwise
+announce the sharpened intent and the advisory line, and continue to
+authoring. Everything else the envelope surfaced — `duplicates[]`, open
+`intake` rows, a truthy `memoryPoolAdvisory.recommend`, a truthy
+`complexitySignals.uiSurface` naming [`/prototype`](prototype.md) (never
+invoke it here) — collapses to **one advisory line** under the gate, which
+never reroutes the run ([ref](helpers/plan-reference.md)).
+Under `--yes`, auto-proceed.
 
 ### 2. Author
 

package/.agents/workflows/mandrel-update.md

@@ -200,13 +200,15 @@ non-optional.
 
 ## Step 4 — Review the surfaced changelog and update consumer-side guidance
 
-Framework upgrades change behaviour the consumer's own `AGENTS.md` /
-`CLAUDE.md` and runbooks often encode. Step 1 already printed the changelog
+Framework upgrades change behaviour the consumer's own `AGENTS.md` and
+runbooks often encode. Step 1 already printed the changelog
 for the applied range — that output is your source of truth (re-read the
 transcript or the GitHub Releases page if it scrolled past). For each entry
 between the installed and target versions:
 
-1. **Consumer `AGENTS.md` / `CLAUDE.md`.** Update instructions so a fresh
+1. **Consumer `AGENTS.md`.** It is the entry doc — `mandrel update` folds a
+   root `CLAUDE.md` into it and deletes `CLAUDE.md`, so reconcile the folded
+   content here. Update instructions so a fresh
    agent reading them in isolation produces output that passes the
    framework's new validators; remove or rewrite instructions that
    contradict a tightened rule.

package/docs/CHANGELOG.md

@@ -15,6 +15,44 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.65.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.64.0...mandrel-v2.65.0) (2026-09-24)
+
+
+### ⚠ BREAKING CHANGES
+
+* consumers must run Claude Code >= 2.1.277, which loads a root AGENTS.md; `mandrel update` folds the root CLAUDE.md into AGENTS.md and deletes CLAUDE.md.
+
+### Added
+
+* add a low-effort model bug review to close and pin role-agent effort ([#5426](https://github.com/dsj1984/mandrel/issues/5426)) ([#5431](https://github.com/dsj1984/mandrel/issues/5431)) ([ec39643](https://github.com/dsj1984/mandrel/commit/ec3964390210e140ebaa324bbfe27b67fd470fa4))
+* **audit-quality:** add a property-based coverage dimension (refs [#5425](https://github.com/dsj1984/mandrel/issues/5425)) ([#5428](https://github.com/dsj1984/mandrel/issues/5428)) ([f78fd62](https://github.com/dsj1984/mandrel/commit/f78fd62edda9060580b1cbacaec1cc82875040d1))
+* cut consumers over to AGENTS.md: bootstrap wiring, CLAUDE.md fold migration, uninstall revert, Claude Code version doctor check ([#5410](https://github.com/dsj1984/mandrel/issues/5410)) ([#5411](https://github.com/dsj1984/mandrel/issues/5411)) ([df69d59](https://github.com/dsj1984/mandrel/commit/df69d59e7ced7342f321b8435ab50b317655f7f3))
+* make AGENTS.md mandrel's always-loaded entry doc: host-faithful closure resolver, delete CLAUDE.md, rewrite AGENTS.md ([#5409](https://github.com/dsj1984/mandrel/issues/5409)) ([#5413](https://github.com/dsj1984/mandrel/issues/5413)) ([929e5bb](https://github.com/dsj1984/mandrel/commit/929e5bb6834e1a25152163ac34a87d327034ce05))
+* trim legacy story-author scaffolding and drop two needless workflow stops ([#5427](https://github.com/dsj1984/mandrel/issues/5427)) ([#5429](https://github.com/dsj1984/mandrel/issues/5429)) ([7b39d36](https://github.com/dsj1984/mandrel/commit/7b39d3637b4911ad7122d6cbaef3c19c88704101))
+
+
+### Fixed
+
+* merge wait: fail fast on a red required check without waiting for unrelated jobs ([#5415](https://github.com/dsj1984/mandrel/issues/5415)) ([#5420](https://github.com/dsj1984/mandrel/issues/5420)) ([381d8ff](https://github.com/dsj1984/mandrel/commit/381d8ff4145ec3210d984936904368d51cde426a))
+
+
+### Performance
+
+* close: per-phase timing, faster merge observation, concurrent post-land GitHub steps ([#5417](https://github.com/dsj1984/mandrel/issues/5417)) ([#5423](https://github.com/dsj1984/mandrel/issues/5423)) ([2d3c537](https://github.com/dsj1984/mandrel/commit/2d3c5373402ad0e212951b70ca2880204da3a8f3))
+* epic rollup: stop reading every Epic's sub-issues when a Story has no native parent ([#5414](https://github.com/dsj1984/mandrel/issues/5414)) ([#5419](https://github.com/dsj1984/mandrel/issues/5419)) ([025c650](https://github.com/dsj1984/mandrel/commit/025c650409a757b47be9847a4584e5e45fdef8e8))
+
+
+### Changed
+
+* retire the Story-scope local-lens pass from close ([#5416](https://github.com/dsj1984/mandrel/issues/5416)) ([#5422](https://github.com/dsj1984/mandrel/issues/5422)) ([ecd86da](https://github.com/dsj1984/mandrel/commit/ecd86daa1a9d1ddff7f58e7f832e491a9c58cb68))
+
+## [2.64.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.63.0...mandrel-v2.64.0) (2026-09-19)
+
+
+### Fixed
+
+* close-and-land: a checks-failed stop disarms auto-merge and writes the CI digest ([#5405](https://github.com/dsj1984/mandrel/issues/5405)) ([#5406](https://github.com/dsj1984/mandrel/issues/5406)) ([5819d52](https://github.com/dsj1984/mandrel/commit/5819d52a834a6973b3e138961d9735e477f6cb48))
+
 ## [2.63.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.62.0...mandrel-v2.63.0) (2026-09-18)
 
 

package/lib/cli/claude-code-version.js

@@ -0,0 +1,73 @@
+// lib/cli/claude-code-version.js
+/**
+ * `mandrel doctor` check `claude-code-version`: an AGENTS.md-only project
+ * needs a Claude Code host that loads AGENTS.md at all. Below the floor the
+ * framework never hydrates, so the check fails. A missing `claude` binary,
+ * unparseable output, or a project still carrying CLAUDE.md skips with
+ * `ok: true` so headless/CI hosts are never blocked. The `claude --version`
+ * spawn is injected by the registry (fixed argv, never user input); with no
+ * runner the check skips.
+ *
+ * @module cli/claude-code-version
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { compareVersions } from './version-helpers.js';
+
+/** Oldest Claude Code release that loads a root AGENTS.md. */
+export const CLAUDE_CODE_AGENTS_MD_FLOOR = '2.1.277';
+
+/**
+ * @param {string} text
+ * @returns {string|null} the leading `x.y.z`, or null
+ */
+export function parseClaudeVersion(text) {
+  const match = /^\s*v?(\d+\.\d+\.\d+)/.exec(text ?? '');
+  return match ? match[1] : null;
+}
+
+/**
+ * @param {{
+ *   projectRoot?: string,
+ *   cwd?: () => string,
+ *   existsSync?: (p: string) => boolean,
+ *   runClaude?: () => { status: number|null, stdout: string, error?: NodeJS.ErrnoException },
+ * }} [opts]
+ * @returns {{ ok: boolean, detail: string, remedy?: string }}
+ */
+export function runClaudeCodeVersion({
+  projectRoot,
+  cwd = () => process.cwd(),
+  existsSync = fs.existsSync,
+  runClaude = () => ({ status: null, stdout: '', error: new Error('none') }),
+} = {}) {
+  const root = projectRoot ?? cwd();
+  if (existsSync(path.join(root, 'CLAUDE.md'))) {
+    return { ok: true, detail: 'skipped: CLAUDE.md present' };
+  }
+  if (!existsSync(path.join(root, 'AGENTS.md'))) {
+    return { ok: true, detail: 'skipped: no AGENTS.md' };
+  }
+  const r = runClaude();
+  if (r.error || r.status !== 0) {
+    return { ok: true, detail: 'skipped: claude not found on PATH' };
+  }
+  const version = parseClaudeVersion(r.stdout);
+  if (!version) {
+    return {
+      ok: true,
+      detail: 'skipped: unparseable `claude --version` output',
+    };
+  }
+  const detail = `Claude Code ${version} (required >=${CLAUDE_CODE_AGENTS_MD_FLOOR} to load AGENTS.md)`;
+  if (compareVersions(version, CLAUDE_CODE_AGENTS_MD_FLOOR) >= 0) {
+    return { ok: true, detail };
+  }
+  return {
+    ok: false,
+    detail,
+    remedy: `Upgrade Claude Code to >=${CLAUDE_CODE_AGENTS_MD_FLOOR} (e.g. \`claude update\`) — older hosts do not load AGENTS.md, so the framework never hydrates.`,
+  };
+}

package/lib/cli/doctor.js

@@ -54,7 +54,7 @@ function formatSummary(passed, total) {
 }
 
 /**
- * Informational line for the `CLAUDE.md` always-loaded closure (file count,
+ * Informational line for the host entry doc's always-loaded closure (file count,
  * KB). Never counted toward the verdict; a resolve failure degrades to a
  * neutral line.
  *
@@ -73,7 +73,7 @@ export function formatClosureReport({
     return `ℹ  ${label}  always-loaded closure unavailable\n`;
   }
   if (files.length === 0) {
-    return `ℹ  ${label}  no CLAUDE.md closure found\n`;
+    return `ℹ  ${label}  no entry-doc closure found (CLAUDE.md or AGENTS.md)\n`;
   }
   const kb = (tierTotalBytes(files) / 1024).toFixed(1);
   return `ℹ  ${label}  ${files.length} file(s), ${kb} KB always-loaded\n`;

package/lib/cli/registry.js

@@ -28,6 +28,7 @@ import { isCommandExcluded } from '../../.agents/scripts/lib/command-header.js';
 import { getDeliveryRouting } from '../../.agents/scripts/lib/config/delivery-routing.js';
 import { isResolvable } from '../../.agents/scripts/lib/runtime-deps/dep-resolution.js';
 import { describeParserMajorError } from '../../.agents/scripts/lib/runtime-deps/parser-major.js';
+import { runClaudeCodeVersion } from './claude-code-version.js';
 import {
   defaultResolvePackageRoot,
   listFiles as listPayloadFiles,
@@ -958,6 +959,14 @@ export const registry = [
     name: 'agents-drift',
     run: (opts) => runAgentsDrift(opts),
   },
+  {
+    name: 'claude-code-version',
+    run: (opts) =>
+      runClaudeCodeVersion({
+        runClaude: () => spawn('claude', ['--version'], { timeout: 10_000 }),
+        ...opts,
+      }),
+  },
   {
     name: 'merge-driver',
     run: (opts) => runMergeDriver(opts),

package/lib/cli/uninstall.js

@@ -21,8 +21,8 @@ import {
   BOOTSTRAP_COMMAND,
   GITIGNORE_BLOCKS,
   SYNC_COMMAND,
+  SYSTEM_PROMPT_AGENTS_MD,
   SYSTEM_PROMPT_BLOCK,
-  SYSTEM_PROMPT_CLAUDE_MD,
   SYSTEM_PROMPT_IMPORT,
 } from '../../.agents/scripts/lib/bootstrap/project-bootstrap.js';
 import {
@@ -60,17 +60,17 @@ const FRAMEWORK_NPM_SCRIPTS = Object.freeze({
  */
 
 /**
- * Strip the system-prompt import block from `CLAUDE.md`. The file is deleted
- * only when byte-identical to the install template — a heading-only heuristic
- * would delete an operator's all-headings file.
+ * Strip the system-prompt import block from a root entry doc. The file is
+ * deleted only when byte-identical to the install template — a heading-only
+ * heuristic would delete an operator's all-headings file.
  *
+ * @param {string} rel - `AGENTS.md`, or a legacy un-migrated `CLAUDE.md`.
  * @param {string} projectRoot
  * @param {typeof fs} fsImpl
  * @returns {ReversalOutcome}
  */
-function revertClaudeMd(projectRoot, fsImpl) {
-  const target = path.join(projectRoot, 'CLAUDE.md');
-  const rel = 'CLAUDE.md';
+function revertEntryDoc(rel, projectRoot, fsImpl) {
+  const target = path.join(projectRoot, rel);
   if (!fsImpl.existsSync(target)) {
     return { kind: 'skipped', target: rel, detail: 'file absent' };
   }
@@ -78,12 +78,12 @@ function revertClaudeMd(projectRoot, fsImpl) {
   if (!original.includes(SYSTEM_PROMPT_IMPORT)) {
     return { kind: 'skipped', target: rel, detail: 'import already absent' };
   }
-  if (original.trim() === SYSTEM_PROMPT_CLAUDE_MD.trim()) {
+  if (original.trim() === SYSTEM_PROMPT_AGENTS_MD.trim()) {
     fsImpl.rmSync(target, { force: true });
     return {
       kind: 'reverted',
       target: rel,
-      detail: 'removed install-created CLAUDE.md',
+      detail: `removed install-created ${rel}`,
     };
   }
   // Full block first, then the bare import line for a hand-edited block.
@@ -109,6 +109,33 @@ function revertClaudeMd(projectRoot, fsImpl) {
   };
 }
 
+/**
+ * @param {string} projectRoot
+ * @param {typeof fs} fsImpl
+ * @returns {ReversalOutcome}
+ */
+function revertAgentsMd(projectRoot, fsImpl) {
+  return revertEntryDoc('AGENTS.md', projectRoot, fsImpl);
+}
+
+/**
+ * Pre-2.65 ledgers name CLAUDE.md. An un-migrated CLAUDE.md reverts as
+ * before; once the update migration folded it away, the wiring lives in
+ * AGENTS.md, so that is reverted instead. CLAUDE.md is never recreated.
+ *
+ * @param {string} projectRoot
+ * @param {typeof fs} fsImpl
+ * @returns {ReversalOutcome}
+ */
+function revertClaudeMd(projectRoot, fsImpl) {
+  const legacy = fsImpl.existsSync(path.join(projectRoot, 'CLAUDE.md'));
+  return revertEntryDoc(
+    legacy ? 'CLAUDE.md' : 'AGENTS.md',
+    projectRoot,
+    fsImpl,
+  );
+}
+
 /**
  * Splice the sync hook and any legacy plugin-enablement keys out of
  * `.claude/settings.json`, keeping everything else; delete the file if empty.
@@ -405,6 +432,7 @@ function revertPreCommitHook(projectRoot, fsImpl) {
  * @type {Readonly<Record<string, (root: string, fsImpl: typeof fs, executedAction?: string) => ReversalOutcome>>}
  */
 const REVERSAL_BY_TARGET = Object.freeze({
+  'AGENTS.md': revertAgentsMd,
   'CLAUDE.md': revertClaudeMd,
   '.claude/settings.json': revertClaudeSettings,
   '.claude/plugins/mandrel': revertClaudeCommands,

package/lib/migrations/index.js

@@ -16,6 +16,7 @@ import { retireDeliveryLimitKnobs } from './steps/2.57.0-retire-delivery-limit-k
 import { retirePlanningLimitKnobs } from './steps/2.57.0-retire-planning-limit-knobs.js';
 import { retireAuditResultsAutoFile } from './steps/2.60.0-retire-audit-results-autofile.js';
 import { baselineMergeQueueShape } from './steps/2.63.0-baseline-merge-queue-shape.js';
+import { foldClaudeMdIntoAgentsMdStep } from './steps/2.65.0-fold-claude-md-into-agents-md.js';
 import { stripRemovedAgentrcKeys } from './steps/strip-removed-agentrc-keys.js';
 
 /**
@@ -40,6 +41,7 @@ export const migrations = [
   retireAuditResultsAutoFile,
   stripRemovedAgentrcKeys,
   baselineMergeQueueShape,
+  foldClaudeMdIntoAgentsMdStep,
 ];
 
 export { compareVersions };