mandrel 2.64.0 → 2.66.0

package/.agents/scripts/bootstrap.js

@@ -10,7 +10,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline/promises';
 import { fileURLToPath } from 'node:url';
-
+import { stageLegacyEntryDocRemoval } from './lib/bootstrap/agents-md-fold.js';
 import {
   buildManualInstructions,
   COMMIT_SUBJECT,
@@ -716,6 +716,13 @@ async function detectCreation(answers, skipGithub) {
   return creation;
 }
 
+function projectNameFor(pn, projects) {
+  const match = projects.find((p) => p.value === pn);
+  if (!match) return '(unknown)';
+  const m = /^(.*)\s+\(#\d+\)$/.exec(match.label);
+  return m ? m[1] : match.label;
+}
+
 /**
  * `{ name, number }` for the summary; the picker stores only the number, so
  * an existing project's name is looked up.
@@ -723,20 +730,78 @@ async function detectCreation(answers, skipGithub) {
 function resolveProjectDisplay(answers, skipGithub, projectsList) {
   const pn = answers.projectNumber;
   if (!pn) return { name: '(skip)', number: '(skip)' };
-  if (/^\d+$/.test(pn)) {
-    let name = '(unknown)';
-    if (!skipGithub) {
-      const projects =
-        projectsList ?? safeList(() => listProjects({ owner: answers.owner }));
-      const match = projects.find((p) => p.value === pn);
-      if (match) {
-        const m = /^(.*)\s+\(#\d+\)$/.exec(match.label);
-        name = m ? m[1] : match.label;
-      }
+  if (!/^\d+$/.test(pn)) return { name: pn, number: '(new)' };
+  if (skipGithub) return { name: '(unknown)', number: pn };
+  const projects =
+    projectsList ?? safeList(() => listProjects({ owner: answers.owner }));
+  return { name: projectNameFor(pn, projects), number: pn };
+}
+
+/** Opt-ins default off; dry-run resolves them without prompting. */
+const OPT_INS = Object.freeze([
+  {
+    key: 'withProjectBoard',
+    flag: 'with-project-board',
+    prompt: 'Set up project board fields (Status, custom)?',
+  },
+  {
+    key: 'withIssueForms',
+    flag: 'with-issue-forms',
+    prompt: 'Generate GitHub Issue Form templates?',
+  },
+  {
+    key: 'withQuality',
+    flag: 'with-quality',
+    prompt:
+      'Install local quality gates (pre-commit hook + quality:preview/watch scripts)?',
+  },
+]);
+
+async function resolveOptIns(state) {
+  const optIns = {};
+  for (const { key, flag, prompt } of OPT_INS) {
+    let on = Boolean(state.flags[flag]);
+    if (!state.flags['dry-run'] && !on) {
+      on = await confirmYesNo(prompt, state.interactive, false);
     }
-    return { name, number: pn };
+    optIns[key] = on;
+  }
+  return optIns;
+}
+
+async function approveCreation(state, creation) {
+  if (state.flags['dry-run'] || !(creation.newRepo || creation.newProject)) {
+    return true;
   }
-  return { name: pn, number: '(new)' };
+  return confirmYesNo(
+    'Create the new GitHub repo/project listed above?',
+    state.interactive,
+  );
+}
+
+async function confirmSummary(state, answers, creation, projectsList) {
+  const skipGithub = Boolean(state.flags['skip-github']);
+  const project = resolveProjectDisplay(answers, skipGithub, projectsList);
+  Logger.info(
+    renderAnswerSummary(
+      answers,
+      creation,
+      project,
+      state.gitInitialized,
+      resolveRepoVisibility(state.flags),
+    ),
+  );
+  return confirmYesNo('Is this correct?', state.interactive);
+}
+
+/** Owner repo/project lists, fetched once for pickers and summary. */
+function fetchPickerLists(state, skipGithub) {
+  const owner = resolveOwnerForPicker(state.defaults, state.flags);
+  if (skipGithub || !owner) return { reposList: [], projectsList: [] };
+  return {
+    reposList: safeList(() => listRepos({ owner }).map(bareRepoName)),
+    projectsList: safeList(() => listProjects({ owner })),
+  };
 }
 
 /**
@@ -745,22 +810,16 @@ function resolveProjectDisplay(answers, skipGithub, projectsList) {
  */
 export async function collectAndConfirm(state) {
   const skipGithub = Boolean(state.flags['skip-github']);
-  const owner = resolveOwnerForPicker(state.defaults, state.flags);
-  // Fetched once for pickers and summary, so the name never needs a second call.
-  const reposList =
-    !skipGithub && owner
-      ? safeList(() => listRepos({ owner }).map(bareRepoName))
-      : [];
-  const projectsList =
-    !skipGithub && owner ? safeList(() => listProjects({ owner })) : [];
-
+  const lists = fetchPickerLists(state, skipGithub);
   let silentAccept = state.silentAccept;
   for (;;) {
     const { answers, missing } = await collectAnswers({
-      questions: buildQuestions(state.defaults, state.flags, process.env, {
-        reposList,
-        projectsList,
-      }),
+      questions: buildQuestions(
+        state.defaults,
+        state.flags,
+        process.env,
+        lists,
+      ),
       flags: state.flags,
       interactive: state.interactive,
       assumeYes: state.assumeYes,
@@ -775,78 +834,24 @@ export async function collectAndConfirm(state) {
       );
       return { ok: false, exit: 1 };
     }
-    if (!answers.operatorHandle) answers.operatorHandle = answers.owner;
-    answers.operatorHandle = normalizeHandleAnswer(answers.operatorHandle);
+    answers.operatorHandle = normalizeHandleAnswer(
+      answers.operatorHandle || answers.owner,
+    );
 
     const creation = await detectCreation(answers, skipGithub);
-    const project = resolveProjectDisplay(answers, skipGithub, projectsList);
-    Logger.info(
-      renderAnswerSummary(
-        answers,
-        creation,
-        project,
-        state.gitInitialized,
-        resolveRepoVisibility(state.flags),
-      ),
-    );
-    const correct = await confirmYesNo('Is this correct?', state.interactive);
-    if (!correct) {
+    if (!(await confirmSummary(state, answers, creation, lists.projectsList))) {
       Logger.info('[Bootstrap] Okay — let’s try again.');
       silentAccept = [];
       continue;
     }
-
-    if (!state.flags['dry-run'] && (creation.newRepo || creation.newProject)) {
-      const approved = await confirmYesNo(
-        'Create the new GitHub repo/project listed above?',
-        state.interactive,
-      );
-      if (!approved) {
-        Logger.error(
-          '[Bootstrap] Creation declined — cannot continue without the repo/project. Exiting.',
-        );
-        return { ok: false, exit: 1 };
-      }
-    }
-
-    // Opt-ins default off; dry-run resolves them without prompting.
-    let withProjectBoard = Boolean(state.flags['with-project-board']);
-    if (!state.flags['dry-run'] && !withProjectBoard) {
-      withProjectBoard = await confirmYesNo(
-        'Set up project board fields (Status, custom)?',
-        state.interactive,
-        false,
-      );
-    }
-
-    let withIssueForms = Boolean(state.flags['with-issue-forms']);
-    if (!state.flags['dry-run'] && !withIssueForms) {
-      withIssueForms = await confirmYesNo(
-        'Generate GitHub Issue Form templates?',
-        state.interactive,
-        false,
-      );
-    }
-
-    let withQuality = Boolean(state.flags['with-quality']);
-    if (!state.flags['dry-run'] && !withQuality) {
-      withQuality = await confirmYesNo(
-        'Install local quality gates (pre-commit hook + quality:preview/watch scripts)?',
-        state.interactive,
-        false,
+    if (!(await approveCreation(state, creation))) {
+      Logger.error(
+        '[Bootstrap] Creation declined — cannot continue without the repo/project. Exiting.',
       );
+      return { ok: false, exit: 1 };
     }
-
-    return {
-      ok: true,
-      payload: {
-        answers,
-        creation,
-        withProjectBoard,
-        withIssueForms,
-        withQuality,
-      },
-    };
+    const optIns = await resolveOptIns(state);
+    return { ok: true, payload: { answers, creation, ...optIns } };
   }
 }
 
@@ -1068,7 +1073,13 @@ export async function offerCommitPush(state, deps = {}) {
     return { ok: true, payload: { commitPush: { action: 'declined' } } };
   }
 
-  const staged = stageBootstrapFiles({ projectRoot: cwd, runGit: runGitImpl });
+  const added = stageBootstrapFiles({ projectRoot: cwd, runGit: runGitImpl });
+  // The folded-away CLAUDE.md deletion rides the same commit.
+  const staged = stageLegacyEntryDocRemoval({
+    projectRoot: cwd,
+    runGit: runGitImpl,
+    after: added,
+  });
   if (!staged.ok) {
     Logger.warn(`[Bootstrap] Could not stage the wiring: ${staged.error}`);
     Logger.info(`\n[Bootstrap] ${instructions}`);

package/.agents/scripts/check-context-budget.js

@@ -1,6 +1,6 @@
 /**
  * CLI: ratchet gate for documentation context bytes against
- * `baselines/context-budget.json`. Measures `alwaysLoaded` (the `CLAUDE.md`
+ * `baselines/context-budget.json`. Measures `alwaysLoaded` (the entry-doc
  * `@`-import closure), `mandatoryRead` (`project.docsContextFiles`) and
  * `workflow` (entry points + `mandatoryReads:` closure).
  *

package/.agents/scripts/lib/ITicketingProvider.js

@@ -105,9 +105,7 @@ export class ITicketingProvider {
   }
 
   /**
-   * Resolve a container parent in one call. Returns `null` (never throws) when
-   * there is no parent or the backend cannot answer, so a degraded lookup
-   * never fails a lifecycle edge.
+   * `null` means "no parent"; throws when the lookup cannot answer.
    *
    * @param {number} _number
    * @returns {Promise<object|null>}

package/.agents/scripts/lib/audit-suite/findings.js

@@ -1,27 +1,11 @@
 /**
- * Findings severity histogram and per-component baseline rollup deltas.
+ * The surviving-Critical halting rule and per-component baseline rollup deltas.
  * Deltas are per rollup, not per row: row churn that moves no rollup is noise.
  * Pure, no I/O.
  */
 
 import { groupRows, resolveComponents } from '../baselines/components.js';
 
-/**
- * Non-standard severities are ignored.
- *
- * @param {Array<{ severity?: string }>|null|undefined} findings
- * @returns {{ critical: number, high: number, medium: number, low: number }}
- */
-export function aggregateSummary(findings) {
-  const summary = { critical: 0, high: 0, medium: 0, low: 0 };
-  for (const finding of findings ?? []) {
-    if (Object.hasOwn(summary, finding.severity)) {
-      summary[finding.severity] += 1;
-    }
-  }
-  return summary;
-}
-
 /**
  * The single halting rule: a surviving Critical finding halts delivery. Every
  * consumer routes through this rather than re-deriving `critical > 0`.

package/.agents/scripts/lib/audit-suite/frontmatter.js

@@ -8,8 +8,6 @@
 // biome-ignore-start lint/complexity/useRegexLiterals: typhonjs-escomplex MI workaround
 const FRONTMATTER_RE = new RegExp(String.raw`^---\r?\n([\s\S]*?)\r?\n---\r?\n`);
 const NEWLINE_SPLIT_RE = new RegExp(String.raw`\r?\n`);
-const PARAGRAPH_SPLIT_RE = new RegExp(String.raw`\r?\n\s*\r?\n`);
-const COLLAPSE_WS_RE = new RegExp(String.raw`\s+`, 'g');
 const SENTENCE_RE = new RegExp(String.raw`[^.!?\n]+[.!?]+`, 'g');
 // biome-ignore-end lint/complexity/useRegexLiterals: typhonjs-escomplex MI workaround
 
@@ -42,22 +40,6 @@ export function extractFrontmatter(content) {
   return fm;
 }
 
-/**
- * @param {string} content
- * @returns {string}
- */
-export function firstProseParagraph(content) {
-  const stripped = content.replace(FRONTMATTER_RE, '');
-  for (const block of stripped.split(PARAGRAPH_SPLIT_RE)) {
-    const trimmed = block.trim();
-    if (!trimmed) continue;
-    if (trimmed.startsWith('#')) continue;
-    if (trimmed.startsWith('---')) continue;
-    return trimmed.replace(COLLAPSE_WS_RE, ' ');
-  }
-  return '';
-}
-
 /**
  * @param {string} text
  * @returns {string}
@@ -74,13 +56,3 @@ export function clampSummary(text) {
   }
   return result;
 }
-
-/**
- * @param {string} content
- * @returns {string}
- */
-export function summarizeWorkflow(content) {
-  const fm = extractFrontmatter(content);
-  const candidate = fm.description?.trim() || firstProseParagraph(content);
-  return clampSummary(candidate);
-}

package/.agents/scripts/lib/audit-suite/index.js

@@ -7,16 +7,10 @@ export {
   readAuditRules,
 } from './checklist-threading.js';
 export { buildDispatchChecklist } from './dispatch-checklist.js';
-export {
-  countChangedLines,
-  evaluateLensDiffFloor,
-} from './lens-diff-floor.js';
-export { runAuditSuite } from './runner.js';
 export {
   LENS_TIERS,
   matchesAnyFilePattern,
   matchesFilePattern,
   resolveLensTier,
   selectAudits,
-  selectLocalLenses,
 } from './selector.js';

package/.agents/scripts/lib/audit-suite/selector.js

@@ -45,37 +45,6 @@ export function resolveLensTier(lens) {
   return scope;
 }
 
-/**
- * Local-tier lenses whose `filePatterns` hit the change set (not
- * {@link selectAudits}, which would widen it with keyword matches).
- *
- * @param {{
- *   changedFiles?: string[],
- *   injectedRules?: { audits?: Record<string, object> },
- *   resolveLensTierFn?: typeof resolveLensTier,
- * }} [params]
- * @returns {string[]} The matched local-lens identifiers, in manifest order.
- */
-export function selectLocalLenses({
-  changedFiles,
-  injectedRules,
-  resolveLensTierFn = resolveLensTier,
-} = {}) {
-  const files = Array.isArray(changedFiles) ? changedFiles : [];
-  if (files.length === 0) return [];
-
-  const rules = injectedRules ?? readAuditRulesSync();
-  const selected = [];
-  for (const [lens, entry] of Object.entries(rules.audits ?? {})) {
-    if (resolveLensTierFn(lens) !== 'local') continue;
-    const patterns = entry?.triggers?.filePatterns ?? [];
-    if (matchesAnyFilePattern(patterns, files)) {
-      selected.push(lens);
-    }
-  }
-  return selected;
-}
-
 /**
  * Manifest `sensitivePaths` classes the change set touches (review depth).
  *

package/.agents/scripts/lib/baselines/duplication-scanner.js

@@ -5,24 +5,33 @@
 import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
+import { resolveDependencyVersion } from '../dependency-version.js';
 
 const DEFAULT_MIN_TOKENS = 50;
 const DEFAULT_FORMATS = Object.freeze(['javascript']);
 
 const require = createRequire(import.meta.url);
 
+/** jscpd 5 is a Rust rewrite with no Node API; only major 4 exposes one. */
+const SUPPORTED_JSCPD_MAJOR = '^4';
+
 /**
  * Lazy CJS load: jscpd's ESM entry has a broken transitive `colors/safe`
  * specifier under strict ESM resolution, and importers that never scan should
  * not pay the load.
  *
+ * No `detectClones` means an unsupported major, not a missing install.
+ *
+ * @param {NodeJS.Require} [requireFn] substitutes the module resolver
  * @returns {(opts: object) => Promise<Array<object>>}
  */
-export function resolveDetectClones() {
-  const jscpd = require('jscpd');
-  if (typeof jscpd.detectClones !== 'function') {
+export function resolveDetectClones(requireFn = require) {
+  const jscpd = requireFn('jscpd');
+  if (typeof jscpd?.detectClones !== 'function') {
+    const version = resolveDependencyVersion('jscpd', requireFn) ?? 'unknown';
     throw new Error(
-      "[Duplication] jscpd.detectClones is not available — run 'npm install'",
+      `[Duplication] jscpd ${version} exposes no detectClones Node API — ` +
+        `the duplication gate supports jscpd ${SUPPORTED_JSCPD_MAJOR}; install jscpd@${SUPPORTED_JSCPD_MAJOR}`,
     );
   }
   return jscpd.detectClones;
@@ -44,6 +53,9 @@ export function relativisePath(sourceId, cwd) {
 }
 
 /**
+ * A side with `end.line < start.line` counts nothing: its real span is
+ * unrecoverable, and widening it recorded hundreds of phantom lines.
+ *
  * @param {{ start?: { line?: number }, end?: { line?: number } }} dup
  * @returns {Array<number>} the 1-based line numbers the clone covers
  */
@@ -51,10 +63,8 @@ function cloneLineNumbers(dup) {
   const start = dup?.start?.line;
   const end = dup?.end?.line;
   if (!Number.isInteger(start) || !Number.isInteger(end)) return [];
-  const lo = Math.min(start, end);
-  const hi = Math.max(start, end);
   const lines = [];
-  for (let n = lo; n <= hi; n += 1) lines.push(n);
+  for (let n = start; n <= end; n += 1) lines.push(n);
   return lines;
 }
 

package/.agents/scripts/lib/bootstrap/agents-md-fold.js

@@ -0,0 +1,156 @@
+/**
+ * CLAUDE.md → AGENTS.md fold for bootstrap and the update migration: a
+ * surviving CLAUDE.md would shadow AGENTS.md, since the host prefers it.
+ *
+ * @module bootstrap/agents-md-fold
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Entry-doc wiring keys idempotence off this exact import path. */
+export const SYSTEM_PROMPT_IMPORT = '@.agents/instructions.md';
+
+export const SYSTEM_PROMPT_BLOCK = `## System Prompt
+
+${SYSTEM_PROMPT_IMPORT}
+`;
+
+/** Install template for a fresh entry doc. */
+export const SYSTEM_PROMPT_ENTRY_DOC = `# Agent Protocols
+
+${SYSTEM_PROMPT_BLOCK}`;
+
+const ENTRY_DOC = 'AGENTS.md';
+export const LEGACY_ENTRY_DOC = 'CLAUDE.md';
+
+const SELF_IMPORT = '@AGENTS.md';
+
+/** @type {readonly string[]} */
+const BOOTSTRAP_REMOVED_PATHS = Object.freeze([LEGACY_ENTRY_DOC]);
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function withTrailingNewline(text) {
+  return text.length === 0 || text.endsWith('\n') ? text : `${text}\n`;
+}
+
+/**
+ * Keep the first system-prompt import line, drop every later one.
+ *
+ * @param {string[]} lines
+ * @returns {string[]}
+ */
+function dedupeImport(lines) {
+  let seen = false;
+  return lines.filter((line) => {
+    if (line.trim() !== SYSTEM_PROMPT_IMPORT) return true;
+    if (seen) return false;
+    seen = true;
+    return true;
+  });
+}
+
+/**
+ * `agents` null means AGENTS.md is absent.
+ *
+ * @param {{ claude: string, agents?: string|null }} input
+ * @returns {string} the resulting AGENTS.md content
+ */
+function foldEntryDocs({ claude, agents = null }) {
+  const claudeBody = claude
+    .split('\n')
+    .filter((line) => line.trim() !== SELF_IMPORT)
+    .join('\n');
+  const combined =
+    typeof agents === 'string'
+      ? `${withTrailingNewline(agents)}\n${claudeBody}`
+      : claudeBody;
+  const lines = dedupeImport(combined.split('\n'));
+  let result = withTrailingNewline(lines.join('\n'));
+  if (!lines.some((line) => line.trim() === SYSTEM_PROMPT_IMPORT)) {
+    result =
+      result.trim().length === 0
+        ? SYSTEM_PROMPT_ENTRY_DOC
+        : `${result}\n${SYSTEM_PROMPT_BLOCK}`;
+  }
+  return result;
+}
+
+/**
+ * Fold a root CLAUDE.md into AGENTS.md on disk and delete CLAUDE.md. No-op
+ * when CLAUDE.md is absent, so a second pass mutates nothing.
+ *
+ * @param {string} projectRoot
+ * @param {typeof fs} [fsImpl]
+ * @returns {{ action: 'folded'|'none', path: string }}
+ */
+export function foldClaudeMdIntoAgentsMd(projectRoot, fsImpl = fs) {
+  const claudePath = path.join(projectRoot, LEGACY_ENTRY_DOC);
+  const agentsPath = path.join(projectRoot, ENTRY_DOC);
+  if (!fsImpl.existsSync(claudePath)) {
+    return { action: 'none', path: agentsPath };
+  }
+  const claude = fsImpl.readFileSync(claudePath, 'utf8');
+  const agents = fsImpl.existsSync(agentsPath)
+    ? fsImpl.readFileSync(agentsPath, 'utf8')
+    : null;
+  fsImpl.writeFileSync(agentsPath, foldEntryDocs({ claude, agents }), 'utf8');
+  fsImpl.rmSync(claudePath, { force: true });
+  return { action: 'folded', path: agentsPath };
+}
+
+/**
+ * Wire the system-prompt import into AGENTS.md, folding a CLAUDE.md in first.
+ * Creates, folds, appends, or no-ops.
+ *
+ * @param {string} projectRoot
+ * @param {typeof fs} [fsImpl]
+ * @returns {{ action: 'created'|'folded'|'appended'|'already-present', path: string }}
+ */
+export function wireEntryDoc(projectRoot, fsImpl = fs) {
+  const folded = foldClaudeMdIntoAgentsMd(projectRoot, fsImpl);
+  const target = folded.path;
+  if (folded.action === 'folded') return folded;
+  if (!fsImpl.existsSync(target)) {
+    fsImpl.writeFileSync(target, SYSTEM_PROMPT_ENTRY_DOC, '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 };
+}
+
+/**
+ * Stage removal of folded-away entry docs; a failed `after` passes through.
+ *
+ * @param {{ after?: { ok: boolean, error?: string }, projectRoot: string, runGit: (args: string[], cwd: string) => { ok: boolean, stderr?: string }, fsImpl?: typeof fs }} args
+ * @returns {{ ok: boolean, error?: string, removed: string[] }}
+ */
+export function stageLegacyEntryDocRemoval({
+  projectRoot,
+  runGit,
+  fsImpl = fs,
+  after = { ok: true },
+}) {
+  if (!after.ok) return after;
+  const removed = BOOTSTRAP_REMOVED_PATHS.filter(
+    (rel) => !fsImpl.existsSync(path.join(projectRoot, rel)),
+  );
+  if (removed.length === 0) return { ok: true, removed };
+  const result = runGit(
+    ['rm', '--cached', '--ignore-unmatch', '--quiet', '--', ...removed],
+    projectRoot,
+  );
+  return { ok: result.ok, error: result.stderr || 'git rm failed', removed };
+}

package/.agents/scripts/lib/bootstrap/commit-push.js

@@ -19,7 +19,7 @@ import path from 'node:path';
 export const BOOTSTRAP_COMMIT_PATHS = Object.freeze([
   '.agents',
   '.agentrc.json',
-  'CLAUDE.md',
+  'AGENTS.md',
   '.claude/settings.json',
   '.gitignore',
   'package.json',

package/.agents/scripts/lib/bootstrap/manifest.js

@@ -62,10 +62,10 @@ export function buildMutationManifest(ctx = {}) {
   entries.push(
     {
       phaseGroup: PHASE_GROUPS.IDE_WIRING,
-      target: rel('CLAUDE.md'),
+      target: rel('AGENTS.md'),
       action: 'merge',
       detail:
-        'Wire the @.agents/instructions.md system-prompt import so Claude Code hydrates the framework on cold start.',
+        'Wire the @.agents/instructions.md system-prompt import into AGENTS.md (folding any CLAUDE.md into it) so Claude Code hydrates the framework on cold start.',
       reversible: true,
     },
     {