mandrel 2.63.0 → 2.65.0

package/.agents/scripts/lib/bootstrap/project-bootstrap.js

@@ -11,6 +11,12 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { isCommandExcluded } from '../command-header.js';
 import { detectPackageManager as detectPm } from '../detect-package-manager.js';
+import {
+  SYSTEM_PROMPT_BLOCK,
+  SYSTEM_PROMPT_ENTRY_DOC,
+  SYSTEM_PROMPT_IMPORT,
+  wireEntryDoc,
+} from './agents-md-fold.js';
 import { LEDGER_RELATIVE_PATH } from './install-ledger.js';
 import { ensureIssueForms } from './issue-forms-template.js';
 import { PHASE_GROUPS } from './manifest.js';
@@ -23,17 +29,10 @@ export const SYNC_AGENTS_COMMAND = 'node .agents/scripts/sync-claude-agents.js';
 
 export const BOOTSTRAP_COMMAND = 'node .agents/scripts/bootstrap.js';
 
-/** `CLAUDE.md` wiring keys idempotence off this exact import path. */
-export const SYSTEM_PROMPT_IMPORT = '@.agents/instructions.md';
+export { SYSTEM_PROMPT_BLOCK, SYSTEM_PROMPT_IMPORT };
 
-export const SYSTEM_PROMPT_BLOCK = `## System Prompt
-
-${SYSTEM_PROMPT_IMPORT}
-`;
-
-export const SYSTEM_PROMPT_CLAUDE_MD = `# Agent Protocols
-
-${SYSTEM_PROMPT_BLOCK}`;
+/** Install template for a fresh AGENTS.md (also the legacy CLAUDE.md one). */
+export const SYSTEM_PROMPT_AGENTS_MD = SYSTEM_PROMPT_ENTRY_DOC;
 
 export const GITIGNORE_BLOCKS = Object.freeze({
   commands: {
@@ -420,30 +419,15 @@ export function checkParity(ctx) {
 }
 
 /**
- * Ensure `CLAUDE.md` imports the system prompt — without it the framework
- * never loads on cold start. Creates, appends, or no-ops.
+ * Ensure `AGENTS.md` imports the system prompt — without it the framework
+ * never loads on cold start. A pre-existing `CLAUDE.md` is folded in first
+ * (the host would otherwise read it instead). Creates, appends, or no-ops.
  *
  * @param {object} ctx
  * @param {typeof fs} [ctx.fsImpl]
  */
 export function ensureSystemPromptWiring(ctx) {
-  const { fsImpl = fs } = ctx;
-  const target = path.join(ctx.projectRoot, 'CLAUDE.md');
-  if (!fsImpl.existsSync(target)) {
-    fsImpl.writeFileSync(target, SYSTEM_PROMPT_CLAUDE_MD, 'utf8');
-    return { action: 'created', path: target };
-  }
-  const existing = fsImpl.readFileSync(target, 'utf8');
-  if (existing.includes(SYSTEM_PROMPT_IMPORT)) {
-    return { action: 'already-present', path: target };
-  }
-  const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
-  fsImpl.writeFileSync(
-    target,
-    `${existing}${separator}\n${SYSTEM_PROMPT_BLOCK}`,
-    'utf8',
-  );
-  return { action: 'appended', path: target };
+  return wireEntryDoc(ctx.projectRoot, ctx.fsImpl);
 }
 
 /**

package/.agents/scripts/lib/config/review-chain-default.js

@@ -0,0 +1,13 @@
+/**
+ * The one default review chain: the factory's unset/empty fallback and the
+ * runtime schema's declared default. `code-review` is `optional` so hosts
+ * without the `claude` CLI close on `native` alone.
+ */
+export const DEFAULT_REVIEW_PROVIDERS = Object.freeze([
+  Object.freeze({ name: 'native' }),
+  Object.freeze({
+    name: 'code-review',
+    scopes: Object.freeze(['story']),
+    optional: true,
+  }),
+]);

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -140,7 +140,7 @@ const WORKTREE_ISOLATION_SCHEMA = {
 const MERGE_WATCH_SCHEMA = {
   type: 'object',
   description:
-    "Knobs consumed by the close-and-land merge wait (Story #4543). `mode` (Story #4698) selects the close-time merge posture. `maxWaitSeconds` bounds ONE invocation of the merge wait and its expiry returns a resumable `pending` terminal with no label mutation; `maxBudgetSeconds` bounds the CUMULATIVE wait across resumes (anchored at the PR's createdAt, so a resume does not restart the clock) and exhausting it is the genuine give-up that classifies and blocks. The 30s poll cadence and the cap of 3 behind-the-base updates are fixed.",
+    "Knobs consumed by the close-and-land merge wait (Story #4543). `mode` (Story #4698) selects the close-time merge posture. `maxWaitSeconds` bounds ONE invocation of the merge wait and its expiry returns a resumable `pending` terminal with no label mutation; `maxBudgetSeconds` bounds the CUMULATIVE wait across resumes (anchored at the PR's createdAt, so a resume does not restart the clock) and exhausting it is the genuine give-up that classifies and blocks. The poll cadence is internal (at most 30s while checks run, at most 10s once they are green and the PR is unmerged); it and the cap of 3 behind-the-base updates are not configurable.",
   properties: {
     mode: {
       type: 'string',
@@ -173,7 +173,7 @@ const ROUTING_SCHEMA = {
     roleScopedAgents: {
       type: 'boolean',
       description:
-        'Epic #4478 (M7-B). Kill-switch for the role-scoped boot contexts. When true (default), a converted delivery spawn (`story-worker`, `acceptance-critic`) boots on its own `.claude/agents/<role>.md` system prompt instead of re-paying the full CLAUDE.md @-import closure. When false, every converted spawn falls back to `subagent_type: general-purpose` — the instant, code-rollback-free per-consumer revert, and the universal escape for hosts that ignore `.claude/agents/`. The fallback is the full-closure agent that ran before M7-B, so flipping it off never drops a gate.',
+        'Epic #4478 (M7-B). Kill-switch for the role-scoped boot contexts. When true (default), a converted delivery spawn (`story-worker`, `acceptance-critic`) boots on its own `.claude/agents/<role>.md` system prompt instead of re-paying the full entry-doc (AGENTS.md or CLAUDE.md) @-import closure. When false, every converted spawn falls back to `subagent_type: general-purpose` — the instant, code-rollback-free per-consumer revert, and the universal escape for hosts that ignore `.claude/agents/`. The fallback is the full-closure agent that ran before M7-B, so flipping it off never drops a gate.',
       default: DELIVERY_ROUTING_DEFAULTS.roleScopedAgents,
     },
     ceremonyProfile: {

package/.agents/scripts/lib/config-settings-schema-quality.js

@@ -4,6 +4,7 @@
 // live in `config/gates/`.
 
 import { GATES_SCHEMA } from './config/gates/index.js';
+import { DEFAULT_REVIEW_PROVIDERS } from './config/review-chain-default.js';
 import { DEFAULT_CODE_REVIEW } from './config/runners.js';
 
 const AUTO_REFRESH_SCHEMA = {
@@ -80,9 +81,15 @@ export const CODE_REVIEW_SCHEMA = {
         properties: {
           name: {
             type: 'string',
-            enum: ['native', 'codex', 'security-review', 'ultrareview'],
+            enum: [
+              'native',
+              'code-review',
+              'codex',
+              'security-review',
+              'ultrareview',
+            ],
             description:
-              'Registered provider key. Inline: native, codex, security-review. Manual-prompt: ultrareview.',
+              'Registered provider key. Inline: native, code-review, codex, security-review. Manual-prompt: ultrareview.',
           },
           scopes: {
             type: 'array',
@@ -125,17 +132,8 @@ export const CODE_REVIEW_SCHEMA = {
         additionalProperties: false,
       },
       description:
-        'Review-provider chain (Story #2871). When unset or empty, defaults to [{ name: "native" }]. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing \'Manual review suggestions\' section. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain.',
-      default: [
-        { name: 'native' },
-        { name: 'security-review', scopes: ['story'], optional: true },
-        {
-          name: 'ultrareview',
-          scopes: ['story'],
-          manualPrompt: true,
-          when: { label: 'risk::high' },
-        },
-      ],
+        "Review-provider chain (Story #2871). When unset or empty, falls back to this default: `native` (scoped lint + MI) then an optional story-scoped `code-review` — a low-effort `claude --print` bug review whose every finding is critical and halts close before auto-merge; hosts without the `claude` CLI skip it. `security-review` and `ultrareview` are opt-in. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing 'Manual review suggestions' section. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain.",
+      default: DEFAULT_REVIEW_PROVIDERS,
     },
     autoFixSeverity: {
       type: 'string',

package/.agents/scripts/lib/doc-tiers.js

@@ -1,7 +1,7 @@
 /**
  * Doc-tier resolver: partition the repo's docs into read-tiers with byte
- * sizes for the context-budget ratchet (`alwaysLoaded` = CLAUDE.md's
- * `@`-import closure; `agentBoot` and `workflowOnDemand` are recorded, not
+ * sizes for the context-budget ratchet (`alwaysLoaded` = the host entry
+ * doc's `@`-import closure; `agentBoot` and `workflowOnDemand` are recorded, not
  * gated). A path lives only in its highest tier. Emits paths and byte
  * counts, never file contents.
  */
@@ -11,9 +11,27 @@ import path from 'node:path';
 import { resolveWorkflowClosures } from './workflow-closure.js';
 
 /**
- * @type {string}
+ * Claude Code's project-root entry precedence: it reads `CLAUDE.md` when
+ * present and falls back to `AGENTS.md` only when `CLAUDE.md` is absent.
+ *
+ * @type {string[]}
+ */
+const ENTRY_DOC_PRECEDENCE = ['CLAUDE.md', 'AGENTS.md'];
+
+/**
+ * The root entry doc the host loads, or null when neither exists.
+ *
+ * @param {string} root
+ * @param {{ fs?: FsLike }} [opts]
+ * @returns {string | null}
  */
-const ENTRY_DOC = 'CLAUDE.md';
+function resolveEntryDoc(root, { fs = nodeFs } = {}) {
+  return (
+    ENTRY_DOC_PRECEDENCE.find((name) =>
+      fs.existsSync(path.resolve(root, name)),
+    ) ?? null
+  );
+}
 
 /**
  * @type {string[]}
@@ -89,8 +107,9 @@ function fileEntry(root, rel, fs) {
  * @returns {Array<{ path: string, bytes: number }>}
  */
 export function resolveAlwaysLoadedClosure(root, { fs = nodeFs } = {}) {
-  const entryAbs = path.resolve(root, ENTRY_DOC);
-  if (!fs.existsSync(entryAbs)) return [];
+  const entry = resolveEntryDoc(root, { fs });
+  if (entry === null) return [];
+  const entryAbs = path.resolve(root, entry);
 
   const visited = new Set();
   const entries = new Map();