mandrel 2.63.0 → 2.65.0

package/lib/migrations/steps/2.65.0-fold-claude-md-into-agents-md.js

@@ -0,0 +1,38 @@
+// lib/migrations/steps/2.65.0-fold-claude-md-into-agents-md.js
+/**
+ * Fold a consumer's root CLAUDE.md into AGENTS.md and delete CLAUDE.md.
+ * The host reads CLAUDE.md exclusively whenever it exists, so a surviving one
+ * would shadow the AGENTS.md wiring. Shares the bootstrap fold contract.
+ */
+
+import nodeFs from 'node:fs';
+import path from 'node:path';
+
+import {
+  foldClaudeMdIntoAgentsMd,
+  LEGACY_ENTRY_DOC,
+} from '../../../.agents/scripts/lib/bootstrap/agents-md-fold.js';
+
+export const foldClaudeMdIntoAgentsMdStep = {
+  version: '2.65.0',
+  description:
+    'fold the root CLAUDE.md into AGENTS.md and delete it — AGENTS.md is ' +
+    'now the entry doc (Story #5410)',
+  /**
+   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
+   * @param {typeof nodeFs} [fsImpl]
+   * @returns {boolean}
+   */
+  detect(ctx, fsImpl = ctx?.fs ?? nodeFs) {
+    const root = ctx?.projectRoot ?? process.cwd();
+    return fsImpl.existsSync(path.join(root, LEGACY_ENTRY_DOC));
+  },
+  /**
+   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
+   * @param {typeof nodeFs} [fsImpl]
+   * @returns {void}
+   */
+  apply(ctx, fsImpl = ctx?.fs ?? nodeFs) {
+    foldClaudeMdIntoAgentsMd(ctx?.projectRoot ?? process.cwd(), fsImpl);
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.63.0",
+  "version": "2.65.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",
@@ -102,6 +102,7 @@
     "@cucumber/gherkin": "^42.0.1",
     "c8": "^11.0.0",
     "chokidar": "^5.0.0",
+    "fast-check": "^4.10.2",
     "husky": "^9.1.7",
     "jscpd": "^4.2.5",
     "knip": "^6.17.1",

package/.agents/scripts/lib/audit-suite/lens-diff-floor.js

@@ -1,99 +0,0 @@
-/**
- * Close-scope lens diff-floor: a diff under the changed-line floor that
- * touches no sensitive path skips lens materialization. Fail-open — every
- * degraded input (unknown count, unreadable manifest, floor `0`) means "do
- * not skip". Sensitive classes come from the same selector as review depth,
- * so the two never disagree. Total; no I/O beyond the injected git spawn.
- */
-
-import { gitSpawn } from '../git-utils.js';
-import { readNumstatRows } from '../orchestration/diff-magnitude.js';
-import { selectSensitivePathClasses } from './selector.js';
-
-/** Measured: zero-yield closes clustered well under this size. */
-export const DEFAULT_LENS_DIFF_FLOOR = 40;
-
-/**
- * Whole-diff additions + deletions (no companion exemption: the question is
- * "is this diff small"). Shares the numstat parse with the light path's
- * backstop. `null` on any git failure; binary rows count 0.
- *
- * @param {{
- *   baseRef: string,
- *   headRef: string,
- *   cwd?: string,
- *   gitSpawnFn?: typeof gitSpawn,
- * }} args
- * @returns {number|null}
- */
-export function countChangedLines({
-  baseRef,
-  headRef,
-  cwd = process.cwd(),
-  gitSpawnFn = gitSpawn,
-} = {}) {
-  const rows = readNumstatRows({ baseRef, headRef, cwd, gitSpawnFn });
-  if (rows === null) return null;
-  return rows.reduce((total, row) => total + row.additions + row.deletions, 0);
-}
-
-/**
- * Skip only when the floor is enabled, the count is known and below it, and
- * no sensitive-path class matches; every other state names its reason.
- *
- * @param {{
- *   changedFiles?: string[]|null,
- *   changedLineCount?: number|null,
- *   floor?: number,
- *   injectedRules?: object,
- *   selectSensitivePathClassesFn?: typeof selectSensitivePathClasses,
- * }} [input]
- * @returns {{
- *   skip: boolean,
- *   reason: 'floor-disabled'|'line-count-unknown'|'at-or-above-floor'|'sensitive-classes-unknown'|'sensitive-path-hit'|'below-floor',
- *   floor: number,
- *   changedLineCount: number|null,
- *   sensitiveClasses: string[],
- * }}
- */
-export function evaluateLensDiffFloor(input = {}) {
-  const floorRaw = input.floor;
-  const floor =
-    typeof floorRaw === 'number' && Number.isInteger(floorRaw) && floorRaw >= 0
-      ? floorRaw
-      : DEFAULT_LENS_DIFF_FLOOR;
-  const count =
-    typeof input.changedLineCount === 'number' &&
-    Number.isFinite(input.changedLineCount) &&
-    input.changedLineCount >= 0
-      ? Math.floor(input.changedLineCount)
-      : null;
-  const verdict = (skip, reason, sensitiveClasses = []) => ({
-    skip,
-    reason,
-    floor,
-    changedLineCount: count,
-    sensitiveClasses,
-  });
-
-  if (floor <= 0) return verdict(false, 'floor-disabled');
-  if (count === null) return verdict(false, 'line-count-unknown');
-  if (count >= floor) return verdict(false, 'at-or-above-floor');
-
-  const select =
-    input.selectSensitivePathClassesFn ?? selectSensitivePathClasses;
-  let classes;
-  try {
-    classes = select({
-      changedFiles: Array.isArray(input.changedFiles) ? input.changedFiles : [],
-      injectedRules: input.injectedRules,
-    });
-  } catch {
-    return verdict(false, 'sensitive-classes-unknown');
-  }
-  const matched = Array.isArray(classes) ? classes : [];
-  if (matched.length > 0) {
-    return verdict(false, 'sensitive-path-hit', matched);
-  }
-  return verdict(true, 'below-floor');
-}

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

@@ -1,205 +0,0 @@
-/**
- * `runAuditSuite`: owns the audit envelope shape (`metadata`, `findings`,
- * `workflows`) and the per-audit fan-out; invoked via the barrel.
- */
-
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { getPaths, PROJECT_ROOT, resolveConfig } from '../config-resolver.js';
-import { ValidationError } from '../errors/index.js';
-import { aggregateSummary } from './findings.js';
-import { summarizeWorkflow } from './frontmatter.js';
-import { applySubstitutions, computeAllowedKeys } from './substitutions.js';
-import { defaultWriteArtifact, loadWorkflow } from './workflow-loader.js';
-
-async function loadRules(paths) {
-  const rulesPath = path.join(
-    PROJECT_ROOT,
-    paths.schemasRoot,
-    'audit-rules.json',
-  );
-  const rulesContent = await fs.readFile(rulesPath, 'utf8');
-  return JSON.parse(rulesContent);
-}
-
-function rejectUnknownKeys(allowedKeys, callerSubstitutions) {
-  const unknownKeys = Object.keys(callerSubstitutions).filter(
-    (k) => !allowedKeys.has(k),
-  );
-  if (unknownKeys.length === 0) return;
-  const allowedList = [...allowedKeys].sort().join(', ');
-  throw new ValidationError(
-    `Unknown substitution key(s): ${unknownKeys.join(', ')}. Allowed for this call: ${allowedList}.`,
-    { unknownKeys, allowedKeys: [...allowedKeys] },
-  );
-}
-
-function emptyEnvelope(auditWorkflows) {
-  return {
-    metadata: {
-      timestamp: new Date().toISOString(),
-      auditsRequested: auditWorkflows,
-      auditsRun: [],
-      summary: { critical: 0, high: 0, medium: 0, low: 0 },
-    },
-    findings: [],
-    workflows: [],
-  };
-}
-
-function notDefinedFinding(auditName) {
-  return {
-    error: true,
-    finding: {
-      audit: auditName,
-      severity: 'low',
-      message: `Requested audit workflow '${auditName}' is not defined in audit-rules.json.`,
-    },
-  };
-}
-
-function notFoundFinding(auditName) {
-  return {
-    error: true,
-    finding: {
-      audit: auditName,
-      severity: 'low',
-      message: `Audit workflow '${auditName}.md' not found in workflows directory.`,
-    },
-  };
-}
-
-async function processAudit({
-  auditName,
-  validAudits,
-  loader,
-  workflowsDir,
-  effectiveSubstitutions,
-}) {
-  if (!validAudits.includes(auditName)) {
-    return notDefinedFinding(auditName);
-  }
-
-  const workflow = await loader(auditName, workflowsDir);
-  if (!workflow) {
-    return notFoundFinding(auditName);
-  }
-
-  const substituted = applySubstitutions(
-    workflow.content,
-    effectiveSubstitutions,
-  );
-
-  return {
-    success: true,
-    auditName,
-    workflowPath: workflow.path ?? null,
-    workflowContent: substituted,
-    summary: summarizeWorkflow(workflow.content),
-    byteSize: Buffer.byteLength(substituted, 'utf8'),
-  };
-}
-
-async function reduceResults({
-  results,
-  envelope,
-  artifactPrefix,
-  effectiveArtifactsDir,
-  writeArtifact,
-}) {
-  for (const result of results) {
-    if (result.error) {
-      envelope.findings.push(result.finding);
-      continue;
-    }
-    if (!result.success) continue;
-
-    envelope.metadata.auditsRun.push(result.auditName);
-    let artifactPath = null;
-    if (artifactPrefix) {
-      const fileName = `audit-${artifactPrefix}-${result.auditName}.md`;
-      artifactPath = await writeArtifact(
-        effectiveArtifactsDir,
-        fileName,
-        result.workflowContent,
-      );
-    }
-    envelope.workflows.push({
-      audit: result.auditName,
-      path: result.workflowPath,
-      summary: result.summary,
-      byteSize: result.byteSize,
-      artifactPath,
-    });
-  }
-}
-
-/**
- * Resolve registered audit workflows into slim descriptors; with
- * `artifactPrefix`, full bodies are written to disk instead of travelling in
- * the envelope. Substitution keys beyond the built-ins must be declared as
- * `substitutionKeys` in audit-rules.json, else ValidationError.
- *
- * @param {object} opts
- * @param {string[]} opts.auditWorkflows
- * @param {Record<string,string>} [opts.substitutions]
- * @param {string} [opts.artifactPrefix] - writes `audit-<prefix>-<audit>.md`.
- * @param {string} [opts.artifactsDir] - defaults to `<auditOutputDir>`.
- * @param {Function} [opts.injectedLoadWorkflow]
- * @param {object} [opts.injectedRules]
- * @param {Function} [opts.injectedWriteArtifact]
- * @returns {Promise<object>} Aggregated audit results.
- */
-export async function runAuditSuite({
-  auditWorkflows,
-  substitutions,
-  artifactPrefix,
-  artifactsDir,
-  injectedLoadWorkflow,
-  injectedRules,
-  injectedWriteArtifact,
-}) {
-  const config = resolveConfig();
-  const paths = getPaths(config);
-  const callerSubstitutions = substitutions ?? {};
-  const rules = injectedRules ?? (await loadRules(paths));
-
-  const allowedKeys = computeAllowedKeys(rules, auditWorkflows);
-  rejectUnknownKeys(allowedKeys, callerSubstitutions);
-
-  const effectiveSubstitutions = {
-    auditOutputDir: paths.auditOutputDir,
-    ...callerSubstitutions,
-  };
-
-  const validAudits = Object.keys(rules.audits || {});
-  const envelope = emptyEnvelope(auditWorkflows);
-  const workflowsDir = path.join(PROJECT_ROOT, paths.workflowsRoot);
-  const effectiveArtifactsDir =
-    artifactsDir ?? path.join(PROJECT_ROOT, paths.auditOutputDir);
-  const writeArtifact = injectedWriteArtifact ?? defaultWriteArtifact;
-  const loader = injectedLoadWorkflow ?? loadWorkflow;
-
-  const results = await Promise.all(
-    auditWorkflows.map((auditName) =>
-      processAudit({
-        auditName,
-        validAudits,
-        loader,
-        workflowsDir,
-        effectiveSubstitutions,
-      }),
-    ),
-  );
-
-  await reduceResults({
-    results,
-    envelope,
-    artifactPrefix,
-    effectiveArtifactsDir,
-    writeArtifact,
-  });
-
-  envelope.metadata.summary = aggregateSummary(envelope.findings);
-  return envelope;
-}

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

@@ -1,96 +0,0 @@
-/**
- * `{{key}}` substitution for audit workflow bodies, plus the CLI glue and the
- * per-run allowed-key set.
- */
-
-import { ValidationError } from '../errors/index.js';
-
-export const BUILT_IN_SUBSTITUTION_KEYS = Object.freeze([
-  'auditOutputDir',
-  'ticketId',
-  'baseBranch',
-  // Newline-joined change set; when unsubstituted, lens templates read the
-  // literal as "no scope filter".
-  'changedFiles',
-]);
-
-function escapeRegExp(str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-/**
- * Unrecognised placeholders are left intact; keys are validated upstream.
- *
- * @param {string} content
- * @param {Record<string, string>} substitutions
- * @returns {string}
- */
-export function applySubstitutions(content, substitutions) {
-  let out = content;
-  for (const [key, value] of Object.entries(substitutions)) {
-    out = out.replace(
-      new RegExp(`\\{\\{${escapeRegExp(key)}\\}\\}`, 'g'),
-      value,
-    );
-  }
-  return out;
-}
-
-/**
- * Throws {@link ValidationError} on a missing `=` or empty key.
- *
- * @param {string[]} [pairs]
- * @returns {Record<string, string>}
- */
-export function parseSubstitutionPairs(pairs = []) {
-  const out = {};
-  for (const entry of pairs) {
-    const eq = entry.indexOf('=');
-    if (eq <= 0) {
-      throw new ValidationError(
-        `Invalid --substitution "${entry}"; expected key=value.`,
-        { entry },
-      );
-    }
-    const key = entry.slice(0, eq);
-    const value = entry.slice(eq + 1);
-    out[key] = value;
-  }
-  return out;
-}
-
-/**
- * Fill `ticketId`/`baseBranch` from flags in place, unless an explicit
- * `--substitution` already set them.
- *
- * @param {Record<string, unknown>} values
- * @param {Record<string, string|undefined>} substitutions
- */
-export function applyImplicitSubstitutions(values, substitutions) {
-  if (values.ticket && substitutions.ticketId === undefined) {
-    substitutions.ticketId = String(values.ticket);
-  }
-  if (values['base-branch'] && substitutions.baseBranch === undefined) {
-    substitutions.baseBranch = values['base-branch'];
-  }
-}
-
-/**
- * Built-ins plus each requested audit's declared keys; unregistered audits
- * are rejected elsewhere.
- *
- * @param {{ audits?: Record<string, { substitutionKeys?: string[] }> }} rules
- * @param {string[]} auditWorkflows
- * @returns {Set<string>}
- */
-export function computeAllowedKeys(rules, auditWorkflows) {
-  const allowed = new Set(BUILT_IN_SUBSTITUTION_KEYS);
-  for (const auditName of auditWorkflows) {
-    const entry = rules.audits?.[auditName];
-    if (!entry) continue;
-    for (const k of entry.substitutionKeys ?? []) {
-      allowed.add(k);
-    }
-  }
-  return allowed;
-}

package/.agents/scripts/lib/audit-suite/workflow-loader.js

@@ -1,37 +0,0 @@
-/**
- * Filesystem IO for audit workflows, kept out of the runner so tests can
- * inject stubs.
- */
-
-import fs from 'node:fs/promises';
-import path from 'node:path';
-
-/**
- * `null` when missing; the runner records a finding rather than failing.
- *
- * @param {string} auditName
- * @param {string} workflowsDir absolute path to the workflows root
- * @returns {Promise<{ path: string, content: string } | null>}
- */
-export async function loadWorkflow(auditName, workflowsDir) {
-  const workflowPath = path.join(workflowsDir, `${auditName}.md`);
-  try {
-    const content = await fs.readFile(workflowPath, 'utf8');
-    return { path: workflowPath, content };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * @param {string} artifactsDir
- * @param {string} fileName
- * @param {string} content
- * @returns {Promise<string>}
- */
-export async function defaultWriteArtifact(artifactsDir, fileName, content) {
-  await fs.mkdir(artifactsDir, { recursive: true });
-  const fullPath = path.join(artifactsDir, fileName);
-  await fs.writeFile(fullPath, content, 'utf8');
-  return fullPath;
-}