mandrel 1.93.0 → 2.0.0

package/.agents/schemas/lifecycle/ledger-record.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/ledger-record.schema.json",
   "title": "Lifecycle ledger record (emitted | completed | failed)",
-  "description": "Append-only NDJSON record shape for temp/epic-<id>/lifecycle.ndjson. Three discriminated kinds; consumers (LedgerWriter, the ledger-diff assertion helpers, TraceLogger) discriminate on `kind`.",
+  "description": "Append-only NDJSON record shape for temp/run-<id>/lifecycle.ndjson. Three discriminated kinds; consumers (LedgerWriter, the ledger-diff assertion helpers, TraceLogger) discriminate on `kind`.",
   "oneOf": [
     { "$ref": "#/$defs/emitted" },
     { "$ref": "#/$defs/completed" },

package/.agents/schemas/lifecycle/retro.end.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/retro.end.schema.json",
   "title": "retro.end",
-  "description": "Emitted at the end of the retro sub-phase. `posted` indicates whether the retro structured comment was upserted onto the Epic; `retroPath` is the local mirror path under temp/epic-<id>/ when written. Story #2252.",
+  "description": "Emitted at the end of the retro sub-phase. `posted` indicates whether the retro structured comment was upserted onto the Epic; `retroPath` is the local mirror path under temp/run-<id>/ when written. Story #2252.",
   "type": "object",
   "required": ["epicId", "posted"],
   "properties": {

package/.agents/schemas/risk-verdict.schema.json

@@ -47,20 +47,7 @@
       "type": "string",
       "minLength": 1,
       "description": "One-paragraph overall risk narrative for the audit trail (the rationale the retired regex classifier could never produce)."
-    },
-    "deliveryShape": {
-      "type": "string",
-      "enum": ["fan-out", "single"],
-      "description": "Planner-judged delivery shape for the Epic (Epic #4474 PR4, design §2 mode matrix). 'fan-out' persists a Story tree (the default when the field is absent — existing verdicts stay valid); 'single' is the spec-only single-delivery mode: no tickets are authored, the ticket validator + DAG are skipped, and plan-persist applies the delivery::single routing marker instead of a Story tree. The marker is inert until #4475 lands the deliver-side reader."
-    },
-    "deliveryShapeRationale": {
-      "type": "string",
-      "minLength": 1,
-      "description": "Concrete justification for the declared deliveryShape, grounded in the Delivery Slicing table (slice count / chain shape). Required whenever deliveryShape is present; surfaced as the routingReasons of the single-mode plan summary."
     }
   },
-  "dependentRequired": {
-    "deliveryShape": ["deliveryShapeRationale"]
-  },
   "additionalProperties": false
 }

package/.agents/scripts/acceptance-eval.js

@@ -32,9 +32,20 @@
  * — this CLI is the decision + signal boundary, mirroring how the existing
  * gates separate decision from ticket mutation.
  *
+ * Two invocation shapes (Epic #4475, M4-B):
+ *   - Per-Story (fan-out): the diff is one Story's; round scoping is per
+ *     Story off the Story's `signals.ndjson`.
+ *   - Per-AC-cluster (single delivery): `--epic <id> --cluster <clusterId>`
+ *     with NO `--story`. The verdict scores one AC cluster of the Epic's
+ *     `## Acceptance Table` against the cumulative `main..epic/<id>` diff;
+ *     round scoping is per cluster off the Epic's `signals.ndjson`. This is
+ *     the acceptance-dilution guard — `ceil(totalACs / clusterCeiling)`
+ *     independent maker-blind critic passes, one per cluster.
+ *
  * CLI:
- *   --story <id>            Story ID (required).
- *   --epic <id>            Parent Epic ID (omit for standalone Stories).
+ *   --story <id>           Story ID (required unless --cluster is given).
+ *   --epic <id>            Parent Epic ID (required with --cluster).
+ *   --cluster <id>         AC-cluster id for the single-delivery critic.
  *   --verdict <path>       Path to the round's verdict JSON (required).
  *   --no-signal            Suppress the signal emit (tests).
  *
@@ -57,7 +68,10 @@ import addFormats from 'ajv-formats';
 import { runAsCli } from './lib/cli-utils.js';
 import { getAcceptanceEval, resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
-import { appendSignal } from './lib/observability/signals-writer.js';
+import {
+  appendEpicSignal,
+  appendSignal,
+} from './lib/observability/signals-writer.js';
 import {
   buildAcceptanceEvalSignal,
   decideAcceptanceEval,
@@ -126,6 +140,7 @@ function parseCliArgs(argv) {
     options: {
       story: { type: 'string' },
       epic: { type: 'string' },
+      cluster: { type: 'string' },
       verdict: { type: 'string' },
       'no-signal': { type: 'boolean', default: false },
     },
@@ -136,6 +151,10 @@ function parseCliArgs(argv) {
   return {
     storyId: Number.isInteger(storyId) && storyId > 0 ? storyId : null,
     epicId: Number.isInteger(epicRaw) && epicRaw > 0 ? epicRaw : null,
+    clusterId:
+      typeof values.cluster === 'string' && values.cluster.length > 0
+        ? values.cluster
+        : null,
     verdictPath: values.verdict ?? null,
     emitSignal: values['no-signal'] !== true,
   };
@@ -163,18 +182,23 @@ function parseCliArgs(argv) {
  * @returns {Promise<{ envelope: object, exitCode: number }>}
  */
 export async function runAcceptanceEval(
-  { storyId, epicId, verdict, config, emitSignal, round },
+  { storyId, epicId, clusterId = null, verdict, config, emitSignal, round },
   deps = {},
 ) {
   const {
     appendSignalFn = appendSignal,
+    appendEpicSignalFn = appendEpicSignal,
     deriveRoundFn = deriveAcceptanceEvalRound,
   } = deps;
+  const clusterMode =
+    typeof clusterId === 'string' &&
+    clusterId.length > 0 &&
+    Number.isInteger(epicId);
   const { maxRounds } = getAcceptanceEval(config);
   const resolvedRound =
     Number.isInteger(round) && round >= 1
       ? round
-      : deriveRoundFn({ epicId: epicId ?? null, storyId, config });
+      : deriveRoundFn({ epicId: epicId ?? null, storyId, clusterId, config });
   const outcome = decideAcceptanceEval({
     verdict,
     maxRounds,
@@ -184,16 +208,21 @@ export async function runAcceptanceEval(
   let signalEmitted = false;
   if (emitSignal) {
     const signal = {
-      ...buildAcceptanceEvalSignal({ storyId, epicId, outcome }),
+      ...buildAcceptanceEvalSignal({ storyId, epicId, outcome, clusterId }),
       ts: new Date().toISOString(),
     };
     try {
-      signalEmitted = await appendSignalFn({
-        epicId,
-        storyId,
-        signal,
-        config,
-      });
+      // Cluster mode (single delivery) writes to the epic-level signals
+      // stream so per-cluster round counts survive resume; the per-Story
+      // path writes to the Story stream (unchanged).
+      signalEmitted = clusterMode
+        ? await appendEpicSignalFn({ epicId, signal, config })
+        : await appendSignalFn({
+            epicId,
+            storyId,
+            signal,
+            config,
+          });
     } catch (err) {
       // Observability is best-effort — a failed signal write must never
       // take down the gate. The decision still stands.
@@ -206,8 +235,9 @@ export async function runAcceptanceEval(
   }
 
   const envelope = {
-    storyId,
+    storyId: storyId ?? null,
     epicId: epicId ?? null,
+    ...(clusterMode ? { clusterId } : {}),
     decision: outcome.decision,
     round: outcome.round,
     cap: outcome.cap,
@@ -231,11 +261,19 @@ export async function runAcceptanceEval(
 }
 
 export async function main(argv = process.argv.slice(2)) {
-  const { storyId, epicId, verdictPath, emitSignal } = parseCliArgs(argv);
+  const { storyId, epicId, clusterId, verdictPath, emitSignal } =
+    parseCliArgs(argv);
 
-  if (!storyId) {
+  // Epic #4475 (M4-B): two invocation shapes.
+  //   - Per-Story (fan-out): --story <id> [--epic <id>].
+  //   - Per-AC-cluster (single delivery): --epic <id> --cluster <id> (no
+  //     --story); the verdict scores one AC cluster of the Epic's Acceptance
+  //     Table against the cumulative main..epic/<id> diff.
+  const clusterMode = Boolean(clusterId) && Number.isInteger(epicId);
+  if (!storyId && !clusterMode) {
     throw new Error(
-      'Usage: node acceptance-eval.js --story <id> [--epic <id>] --verdict <path> [--no-signal]',
+      'Usage: node acceptance-eval.js --story <id> [--epic <id>] --verdict <path> [--no-signal]\n' +
+        '   or: node acceptance-eval.js --epic <id> --cluster <clusterId> --verdict <path> [--no-signal]',
     );
   }
   if (!verdictPath) {
@@ -267,8 +305,13 @@ export async function main(argv = process.argv.slice(2)) {
   const verdict = validateVerdict(parsed);
 
   // A verdict whose embedded storyId disagrees with the CLI flag is a
-  // wiring error worth failing on, not a silent mismatch.
-  if (Number.isInteger(verdict.storyId) && verdict.storyId !== storyId) {
+  // wiring error worth failing on, not a silent mismatch. Skipped in cluster
+  // mode (no --story; the verdict scores an AC cluster, not a Story).
+  if (
+    !clusterMode &&
+    Number.isInteger(verdict.storyId) &&
+    verdict.storyId !== storyId
+  ) {
     throw new Error(
       `acceptance-eval: verdict storyId (${verdict.storyId}) does not match --story ${storyId}.`,
     );
@@ -278,6 +321,7 @@ export async function main(argv = process.argv.slice(2)) {
   const { envelope, exitCode } = await runAcceptanceEval({
     storyId,
     epicId,
+    clusterId,
     verdict,
     config,
     emitSignal,

package/.agents/scripts/agents-bootstrap-github.js

@@ -237,7 +237,7 @@ async function ensureProjectFields(provider, project, log) {
  *
  * Accepts the canonical resolved config (output of `resolveConfig()` —
  * `config.github` holds the GitHub provider block). Epic #2880 removed the
- * legacy shim parameters; see `.agents/rules/git-conventions.md#contract-cutovers-—-no-shim-layer`.
+ * legacy shim parameters; see `.agents/rules/git-conventions-reference.md#contract-cutovers-—-no-shim-layer`.
  *
  * Consent-first install (Story #3526, Feature #3515, Epic #3438): every
  * mutation this function performs — labels, Projects V2, branch protection,

package/.agents/scripts/analyze-execution.js

@@ -27,7 +27,7 @@
  * NDJSON for a Story, no children for an Epic) so the close pipelines
  * never block on observability output. Hard failures (bad CLI args,
  * provider error, schema-violating payload) exit non-zero — the call
- * sites in post-merge-pipeline / `/deliver` Phase 5 treat that
+ * sites in `single-story-close.js` / `helpers/deliver-story.md` treat that
  * as a non-fatal warning.
  *
  * This file is a thin CLI: it wires the I/O readers from

package/.agents/scripts/audit-to-stories.js

@@ -12,8 +12,8 @@
  *     Emits a single `audit-to-stories-plan.json` envelope to --out (or
  *     stdout when --json is set).
  *
- *   --emit-epic-seed --plan <plan.json> --out <path>
- *     Read the plan envelope from disk, render the `/plan --idea`
+ *   --emit-plan-seed --plan <plan.json> --out <path>
+ *     Read the plan envelope from disk, render the `/plan --seed`
  *     seed markdown, persist to --out.
  *
  *   --emit-stories --plan <plan.json>
@@ -37,7 +37,7 @@ import { classifyGroupsAgainstGitHub } from './lib/audit-to-stories/dedupe-again
 import { withFingerprints } from './lib/audit-to-stories/finding-adapter.js';
 import { groupFindings } from './lib/audit-to-stories/group-findings.js';
 import { parseAuditReports } from './lib/audit-to-stories/parse-audit-md.js';
-import { buildEpicSeedMarkdown } from './lib/audit-to-stories/seed-epic-from-findings.js';
+import { buildPlanSeedMarkdown } from './lib/audit-to-stories/seed-from-findings.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { Logger } from './lib/Logger.js';
 import { parse as parseStoryBody } from './lib/story-body/story-body.js';
@@ -291,7 +291,7 @@ async function main() {
     args: process.argv.slice(2),
     options: {
       scan: { type: 'boolean' },
-      'emit-epic-seed': { type: 'boolean' },
+      'emit-plan-seed': { type: 'boolean' },
       'emit-stories': { type: 'boolean' },
       glob: { type: 'string' },
       severity: { type: 'string' },
@@ -315,9 +315,9 @@ async function main() {
     return;
   }
 
-  if (values['emit-epic-seed']) {
+  if (values['emit-plan-seed']) {
     const plan = loadPlan(values.plan);
-    const md = buildEpicSeedMarkdown({
+    const md = buildPlanSeedMarkdown({
       groups: plan.groups ?? [],
       findings: plan.findings ?? [],
       sourceReports: plan.sourceReports ?? [],
@@ -346,7 +346,7 @@ async function main() {
   }
 
   throw new Error(
-    'Usage: node audit-to-stories.js (--scan | --emit-epic-seed | --emit-stories) [options]',
+    'Usage: node audit-to-stories.js (--scan | --emit-plan-seed | --emit-stories) [options]',
   );
 }
 

package/.agents/scripts/boot-sweep.js

@@ -72,7 +72,7 @@ Options:
  * returns the sweep envelope so no caller can be blocked by a failure.
  *
  * DI-friendly: `injectedConfig` / `injectedProvider` let a caller (e.g.
- * `epic-deliver-prepare.js`) reuse an already-resolved config + provider,
+ * `single-story-init.js`) reuse an already-resolved config + provider,
  * and `injectedSweep` swaps the engine for unit tests.
  *
  * @param {{

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

@@ -12,7 +12,13 @@
  *                       session and every subagent spawn (instructions.md § 4).
  *   - `mandatoryRead` — the resolved `project.docsContextFiles` set.
  *
- * A tier that resolves **empty** is skipped silently (the `docsContextFiles`
+ * It additionally enforces a **per-file** ceiling on the role-scoped agent-boot
+ * tier (`.agents/agents/*.md`, #4478): no single boot context may exceed
+ * `agentBoot.ceilingBytes` (default 8192). This is a per-agent cap, not a sum
+ * ratchet — each role def is a standalone system prompt a converted spawn boots
+ * on, and adding another role def is legitimate.
+ *
+ * A read-tier that resolves **empty** is skipped silently (the `docsContextFiles`
  * half skips when unconfigured / its files are absent), so a repo with no
  * `CLAUDE.md` and no context docs is a clean no-op.
  *
@@ -60,6 +66,31 @@ export const GATED_TIERS = ['alwaysLoaded', 'mandatoryRead'];
  */
 export const DEFAULT_TOLERANCE_BYTES = 2048;
 
+/**
+ * Per-file ceiling (bytes) for the role-scoped agent-boot tier (#4478). Unlike
+ * the read-tiers (gated by a total-byte ratchet), each `.agents/agents/*.md`
+ * boot context is a **standalone** system prompt a converted spawn boots on, so
+ * the meaningful budget is per-agent, not the sum: no single role def may
+ * exceed this ceiling. Adding another role def is legitimate — a per-file gate
+ * (rather than a sum ratchet) does not false-positive on that.
+ * @type {number}
+ */
+export const AGENT_BOOT_CEILING_BYTES = 8192;
+
+/**
+ * Return the agent-boot files that exceed the per-file ceiling.
+ *
+ * @param {{ tiers: Record<string, Array<{ path: string, bytes: number }>> }} tierMap
+ * @param {number} ceiling
+ * @returns {Array<{ path: string, bytes: number, ceiling: number }>}
+ */
+export function agentBootOverflow(tierMap, ceiling = AGENT_BOOT_CEILING_BYTES) {
+  const files = tierMap?.tiers?.agentBoot ?? [];
+  return files
+    .filter((f) => Number.isFinite(f?.bytes) && f.bytes > ceiling)
+    .map((f) => ({ path: f.path, bytes: f.bytes, ceiling }));
+}
+
 /**
  * Parse argv for `--baseline <path>`, `--root <path>`, `--update`, `--json`.
  * Exported so unit tests can pin the parser.
@@ -127,11 +158,19 @@ export function buildBaseline(tierMap, toleranceBytes) {
     const files = tierMap.tiers[name] ?? [];
     tiers[name] = { totalBytes: tierTotalBytes(files), files };
   }
+  // The agent-boot tier is recorded top-level (not under `tiers`) because it is
+  // gated by a per-file ceiling, not the total-byte ratchet the `tiers` entries
+  // use — keeping it out of `tiers` keeps the ratchet diff loop unambiguous.
+  const agentBootFiles = tierMap.tiers.agentBoot ?? [];
   return {
     $schema: 'https://mandrel.dev/baselines/context-budget.schema.json',
     generatedAt: new Date().toISOString(),
     toleranceBytes,
     tiers,
+    agentBoot: {
+      ceilingBytes: AGENT_BOOT_CEILING_BYTES,
+      files: agentBootFiles,
+    },
   };
 }
 
@@ -278,7 +317,11 @@ export async function runCli({
   }
 
   const diff = diffBudget(tierMap, baseline);
-  const exitCode = diff.grown.length > 0 ? 1 : 0;
+  const ceiling = Number.isFinite(baseline?.agentBoot?.ceilingBytes)
+    ? baseline.agentBoot.ceilingBytes
+    : AGENT_BOOT_CEILING_BYTES;
+  const bootOverflow = agentBootOverflow(tierMap, ceiling);
+  const exitCode = diff.grown.length > 0 || bootOverflow.length > 0 ? 1 : 0;
 
   if (json) {
     const envelope = {
@@ -293,17 +336,31 @@ export async function runCli({
       grown: diff.grown,
       shrunk: diff.shrunk,
       skipped: diff.skipped,
+      agentBootCeilingBytes: ceiling,
+      agentBootOverflow: bootOverflow,
       exitCode,
     };
     stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
   } else {
     stdout.write(`\n--- context-budget preview ---\n`);
     stdout.write(`${renderDiff(diff)}\n`);
-    if (exitCode === 1) {
-      stderr.write(
-        `[context-budget] ❌ a documentation tier grew beyond tolerance — refresh the budget consciously with \`node .agents/scripts/check-context-budget.js --update\` once the growth is intentional\n`,
+    for (const o of bootOverflow) {
+      stdout.write(
+        `+ agentBoot: ${o.path} is ${o.bytes} bytes, over the ${o.ceiling}-byte per-agent ceiling\n`,
       );
     }
+    if (exitCode === 1) {
+      if (bootOverflow.length > 0) {
+        stderr.write(
+          `[context-budget] ❌ a role-agent boot context exceeds the ${ceiling}-byte per-agent ceiling — trim the role def (the ceiling is a hard cap, not a starve target)\n`,
+        );
+      }
+      if (diff.grown.length > 0) {
+        stderr.write(
+          `[context-budget] ❌ a documentation tier grew beyond tolerance — refresh the budget consciously with \`node .agents/scripts/check-context-budget.js --update\` once the growth is intentional\n`,
+        );
+      }
+    }
   }
 
   return exitCode;

package/.agents/scripts/check-lifecycle-lint.js

@@ -80,17 +80,14 @@ const SCRIPTS_DIR = path.join(REPO_ROOT, '.agents', 'scripts');
  * auto-merge call could re-enter the codebase.
  */
 const MERGE_LOCKOUT_ALLOWED_SUFFIXES = Object.freeze([
-  // Story #2256 / #2336 — the predicate-gated AutomergeArmer listener is
-  // now the SOLE production code path authorized to call `gh pr merge`.
-  // The legacy `.agents/scripts/epic-deliver-automerge.js` exemption was
-  // removed in Story #2336 / Task #2340 once the CLI was reduced to a
-  // pure `epic.automerge.start` emit shim.
+  // v2 Story close path — the sole production code path authorized to
+  // call `gh pr merge` after the Epic AutomergeArmer listener was removed.
   path.join(
     'lib',
     'orchestration',
-    'lifecycle',
-    'listeners',
-    'automerge-armer.js',
+    'single-story-close',
+    'phases',
+    'auto-merge.js',
   ),
 ]);
 
@@ -339,7 +336,7 @@ export function findMergeLockoutViolations(
           violations.push({
             file,
             line: i + 1,
-            hint: `String literal containing '${FORBIDDEN}' is forbidden outside automerge-armer.js (Story #2253 review High-1). Auto-merge enablement must flow through the AutomergeArmer listener so blocker/review predicates gate the call.`,
+            hint: `String literal containing '${FORBIDDEN}' is forbidden outside single-story-close/phases/auto-merge.js. Auto-merge enablement must flow through the Story close path.`,
           });
           break; // one violation per line is enough
         }

package/.agents/scripts/check-prepush-recovery.js

@@ -3,7 +3,7 @@
  * check-prepush-recovery.js — gate decision for the pre-push coverage step.
  *
  * Story #3162. The pre-push hook normally runs `coverage-capture.js` +
- * `crap:check` on every push. During a `story-close.js` recovery (operator
+ * `crap:check` on every push. During a pre-v2 `story-close.js` recovery (operator
  * pushing `epic/<id>` to unblock a run after a merge-orchestrator failure),
  * a pre-existing coverage regression on `epic/<id>` — unrelated to the
  * Story under recovery — hard-blocks the push and forces a `--no-verify`

package/.agents/scripts/cleanup-repo-test-temp.js

@@ -20,7 +20,12 @@
 import { existsSync, readdirSync, rmSync } from 'node:fs';
 import path from 'node:path';
 import { runAsCli } from './lib/cli-utils.js';
-import { isReservedTestEpicTempDirName } from './lib/test-reserved-epic-temp-ids.js';
+
+const RESERVED_TEST_EPIC_TEMP_DIR = /^epic-999\d{3}$/;
+
+function isReservedTestEpicTempDirName(name) {
+  return RESERVED_TEST_EPIC_TEMP_DIR.test(name);
+}
 
 /**
  * @param {object} [opts]

package/.agents/scripts/diagnose-friction.js

@@ -81,12 +81,6 @@ const FRICTION_RULES = [
     remediation:
       ' - Syntax/parsing error. Check recently modified files for missing brackets, quotes, or invalid structures.',
   },
-  {
-    markers: ['Astro', 'astro'],
-    category: 'Missing Skill',
-    remediation:
-      ' - Framework error: Refer to `.agents/skills/stack/frontend/astro/SKILL.md` for Astro rules.',
-  },
 ];
 
 const FRICTION_DEFAULT = {

package/.agents/scripts/lib/Logger.js

@@ -18,7 +18,6 @@
  *   - `silent`   → only `fatal` emits.
  *   - `info`     → default. Emits `info` and above; suppresses `debug`.
  *   - `verbose`  → emits everything (including `debug`).
- *   - `debug`    → alias for `verbose` (backward compatible).
  */
 /**
  * Recognized log levels, lowest-noise first. Anything outside this set
@@ -26,9 +25,7 @@
  *
  * @type {ReadonlySet<string>}
  */
-const VALID_LEVELS = Object.freeze(
-  new Set(['silent', 'info', 'verbose', 'debug']),
-);
+const VALID_LEVELS = Object.freeze(new Set(['silent', 'info', 'verbose']));
 
 /**
  * Process-wide level override. `null` means "no explicit override — read
@@ -50,7 +47,7 @@ let levelOverride = null;
  * the level branches react in-process, without a child process per level
  * (Story #3329).
  *
- * @returns {'silent'|'info'|'verbose'|'debug'}
+ * @returns {'silent'|'info'|'verbose'}
  */
 export function resolveLevel() {
   const raw = (
@@ -63,12 +60,12 @@ export function resolveLevel() {
 
 /**
  * Pin the process-wide log level, bypassing `AGENT_LOG_LEVEL`. Pass a
- * recognized level (`silent` / `info` / `verbose` / `debug`) to force it,
+ * recognized level (`silent` / `info` / `verbose`) to force it,
  * or `null` to clear the pin and restore env-driven resolution. An
  * unrecognized non-null value throws so callers cannot silently pin a
  * level that resolves to `info`.
  *
- * @param {('silent'|'info'|'verbose'|'debug')|null} level
+ * @param {('silent'|'info'|'verbose')|null} level
  * @returns {void}
  */
 export function setLevel(level) {
@@ -78,15 +75,14 @@ export function setLevel(level) {
   }
   if (typeof level !== 'string' || !VALID_LEVELS.has(level.toLowerCase())) {
     throw new RangeError(
-      `setLevel: level must be one of silent|info|verbose|debug or null (got ${level})`,
+      `setLevel: level must be one of silent|info|verbose or null (got ${level})`,
     );
   }
   levelOverride = level.toLowerCase();
 }
 
 function debugEnabled() {
-  const level = resolveLevel();
-  return level === 'verbose' || level === 'debug';
+  return resolveLevel() === 'verbose';
 }
 
 function infoEnabled() {

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

@@ -189,8 +189,8 @@ export async function runAuditSuite({
   injectedRules,
   injectedWriteArtifact,
 }) {
-  const { agentSettings } = resolveConfig();
-  const paths = getPaths({ agentSettings });
+  const config = resolveConfig();
+  const paths = getPaths(config);
   const callerSubstitutions = substitutions ?? {};
   const rules = injectedRules ?? (await loadRules(paths));
 

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

@@ -109,10 +109,10 @@ export const LENS_TIERS = Object.freeze(['local', 'cumulative', 'global']);
  * @throws {Error} When the manifest cannot be read or parsed.
  */
 function readAuditRulesSync() {
-  const { agentSettings } = resolveConfig();
+  const config = resolveConfig();
   const rulesPath = path.join(
     PROJECT_ROOT,
-    getPaths({ agentSettings }).schemasRoot,
+    getPaths(config).schemasRoot,
     'audit-rules.json',
   );
   try {
@@ -160,7 +160,7 @@ export function resolveLensTier(lens) {
  * every path) matches every change set here, so its concern is verified at
  * BOTH innermost tiers — the
  * write-time checklist threading and this Story-scope lens pass — and excluded
- * from Epic close (a local lens is dropped by {@link selectEpicCloseLenses}).
+ * from the retired Epic-close roster (local lenses stay Story-scope only).
  * A local lens with an empty `filePatterns` list matches nothing here, so a
  * diff matching no local lens's patterns yields an empty roster and adds no
  * lens work.
@@ -300,12 +300,12 @@ export async function selectAudits({
   gitTimeoutMsOverride,
   gateModeOpts,
 }) {
-  const { agentSettings } = resolveConfig();
+  const config = resolveConfig();
   const timeoutMs = gitTimeoutMsOverride ?? DEFAULT_GIT_TIMEOUT_MS;
 
   const rulesPath = path.join(
     PROJECT_ROOT,
-    getPaths({ agentSettings }).schemasRoot,
+    getPaths(config).schemasRoot,
     'audit-rules.json',
   );
   let rulesData;

package/.agents/scripts/lib/audit-to-stories/{seed-epic-from-findings.js → seed-from-findings.js}

@@ -1,17 +1,17 @@
 /**
- * lib/audit-to-stories/seed-epic-from-findings.js
+ * lib/audit-to-stories/seed-from-findings.js
  *
- * Build the `--idea`-shaped seed markdown that `/plan` Phase 1
- * consumes when the operator picks the Single-Epic grouping mode.
+ * Build the `/plan --seed`-shaped one-pager markdown that the audit-to-
+ * stories Single-plan grouping path emits for `/plan` to consume.
  *
- * The seed renders the canonical one-pager sections so the idea-refinement
- * skill can sharpen it without having to invent context:
+ * The seed renders the canonical one-pager sections so the authoring
+ * pass can sharpen it without having to invent context:
  *   - Problem Statement (aggregated severity profile)
  *   - Recommended Direction (rollup of recommendations by dimension)
  *   - Key Assumptions (carries the source-report links forward)
  *   - MVP Scope (the proposed Stories, one bullet per group)
- *   - Key Files (explicit file paths so /plan Phase 7 decompose
- *     has concrete anchors)
+ *   - Key Files (explicit file paths so `/plan` authoring has concrete
+ *     anchors)
  *   - Not Doing (out-of-scope items by convention)
  *
  * Pure: returns a string. The caller decides where to persist it.
@@ -112,14 +112,14 @@ function formatKeyAssumptions(sourceReports) {
  * @param {string[]} params.sourceReports — list of source report paths.
  * @returns {string}
  */
-export function buildEpicSeedMarkdown({ groups, findings, sourceReports }) {
+export function buildPlanSeedMarkdown({ groups, findings, sourceReports }) {
   if (
     !Array.isArray(groups) ||
     !Array.isArray(findings) ||
     !Array.isArray(sourceReports)
   ) {
     throw new Error(
-      'buildEpicSeedMarkdown: groups, findings, sourceReports must all be arrays',
+      'buildPlanSeedMarkdown: groups, findings, sourceReports must all be arrays',
     );
   }
   const problem = formatProblemStatement(findings);