mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/dynamic-workflow/audit-orchestrator.js

@@ -1,284 +0,0 @@
-// .agents/scripts/lib/dynamic-workflow/audit-orchestrator.js
-/**
- * Reusable audit-lens orchestration engine (Epic #3597, Story #3609).
- *
- * Every audit lens that runs as a Claude Code **dynamic workflow**
- * (https://code.claude.com/docs/en/workflows) shares the same three-phase
- * fan-out:
- *
- *   1. **analyze** — one read-only sub-agent per analysis dimension, run in
- *      parallel, each producing raw findings for its dimension only.
- *   2. **adversarial cross-check** — an independent read-only reviewer
- *      re-verifies each dimension's findings, dropping false positives.
- *   3. **synthesize** — a single agent assembles the cross-checked findings
- *      into the lens's report contract and writes the artifact.
- *
- * Before this engine existed, each lens (starting with `audit-clean-code`)
- * inlined a private copy of this loop. `runAuditOrchestration` extracts it
- * once so a lens workflow only has to declare *what* is lens-specific —
- * its dimension list, its prompt builders, its read-only tool allowlist, and
- * its report-contract self-check — and delegate the fan-out plumbing here.
- *
- * ## Read-only guarantee
- *
- * Analysis and cross-check agents receive only the caller-supplied
- * `readOnlyTools` allowlist (read/search tools — no write/edit/shell). The
- * single write in the run is the report artifact, performed by the synthesis
- * agent, which is granted the read-only allowlist plus `Write`.
- *
- * ## Partial-failure posture
- *
- * The per-dimension fan-out is settled, not all-or-nothing (Story #4783). One
- * rejected dimension used to discard every sibling's completed work; the
- * engine now partitions the settled results, flows the fulfilled dimensions on
- * to the next phase, and records the rejected ones as an explicit
- * degraded-coverage note in the report's Executive Summary. This mirrors the
- * posture `close-validation/runner.js` already takes with per-gate errors:
- * capture the failure into the result rather than rejecting the whole run.
- * Only a *total* loss — every dimension rejected — throws, because there is
- * then nothing to synthesise.
- *
- * ## Report-contract self-check
- *
- * After synthesis the engine calls the caller-supplied `assertReportContract`
- * on the synthesis output and throws when the report is non-conformant, so a
- * lens can never silently emit a malformed report. The thrown message is
- * derived from the caller's `formatContractError` (when supplied) so each lens
- * can phrase the failure in its own terms.
- *
- * This module is dependency-free and lens-agnostic: it imports nothing from
- * any specific lens. It is exercised in isolation by
- * `tests/dynamic-workflow-audit-orchestrator.test.js` with a stub `agent` /
- * `phase` so the fan-out wiring is unit-testable without a live Claude Code
- * runtime.
- *
- * @module dynamic-workflow/audit-orchestrator
- */
-
-import { withDegradedCoverageNote } from './degraded-coverage.js';
-
-/**
- * A dimension that did not complete, as recorded by the settled fan-out.
- *
- * @typedef {import('./degraded-coverage.js').DimensionFailure} DimensionFailure
- */
-
-/**
- * The live dynamic-workflow runtime context the host passes to a saved
- * `.claude/workflows/*.workflow.js` entry point. Re-exported as a typedef so
- * every lens workflow references one canonical shape rather than re-declaring
- * it (and drifting from) the runtime contract.
- *
- * `agent` spawns a sub-agent and resolves to its result envelope (the textual
- * output is on `.output`). `phase` groups one or more agent calls under a
- * named phase surfaced in the `/workflows` view; it resolves to **whatever its
- * callback resolves to**, so it is generic over the callback's return type.
- *
- * @typedef {object} AgentResult
- * @property {string} output - The sub-agent's textual output.
- *
- * @typedef {object} WorkflowContext
- * @property {(opts: { prompt: string, allowedTools?: string[], model?: string }) => Promise<AgentResult>} agent
- *   Spawn a sub-agent with the given prompt and (optional) tool allowlist /
- *   model. Resolves to the agent's result envelope.
- * @property {<T>(name: string, fn: () => Promise<T>) => Promise<T>} phase
- *   Group agent calls into a named phase (per-phase agent count, token total,
- *   and elapsed time surface in `/workflows`). Resolves to the callback's
- *   own resolved value.
- * @property {object} inputs - Caller-supplied workflow inputs.
- */
-
-/**
- * @template TReport
- * @typedef {object} AuditOrchestrationSpec
- * @property {WorkflowContext} ctx
- *   The live dynamic-workflow runtime context (`agent` + `phase`).
- * @property {readonly string[]} dimensions
- *   The independent analysis dimensions to fan out, one sub-agent each.
- * @property {readonly string[]} readOnlyTools
- *   The read-only tool allowlist granted to analysis and cross-check agents.
- *   The synthesis agent additionally receives `Write`.
- * @property {(dimension: string) => string} buildDimensionPrompt
- *   Compose the analysis prompt for one dimension (lens-specific).
- * @property {(dimension: string, findings: string) => string} buildCrossCheckPrompt
- *   Compose the adversarial cross-check prompt for one dimension's findings.
- * @property {(crossCheckedBlocks: string[], degraded: DimensionFailure[]) => string} buildSynthesisPrompt
- *   Compose the synthesis prompt that assembles the report and writes it. The
- *   second argument lists the dimensions that did not complete (empty on a
- *   full-coverage run); lenses may ignore it — the engine annotates the report
- *   with the degraded-coverage note either way.
- * @property {(report: string) => { conformant: boolean, missingSections: string[], hasTitle: boolean }} assertReportContract
- *   Self-check the synthesised report against the lens's report contract.
- * @property {(check: { conformant: boolean, missingSections: string[], hasTitle: boolean }) => string} [formatContractError]
- *   Optional: phrase the non-conformance error in the lens's own terms.
- *   Defaults to a generic message naming the missing title / sections.
- * @property {(report: string) => TReport} [buildResult]
- *   Optional: derive the engine's return value from the synthesised report.
- *   Defaults to returning `{ report }`.
- */
-
-/**
- * The default phase names, exported so lenses and tests reference the exact
- * strings rather than hard-coding them.
- */
-export const ORCHESTRATION_PHASES = Object.freeze({
-  ANALYZE: 'analyze-dimensions',
-  CROSS_CHECK: 'adversarial-cross-check',
-  SYNTHESIZE: 'synthesize-report',
-});
-
-/** The single mutating tool the synthesis agent is granted. */
-export const SYNTHESIS_WRITE_TOOL = 'Write';
-
-/**
- * Default phrasing for a report-contract self-check failure. Lenses can
- * override via `spec.formatContractError`.
- *
- * @param {{ conformant: boolean, missingSections: string[], hasTitle: boolean }} check
- * @returns {string}
- */
-export function defaultContractError(check) {
-  const titlePart = check.hasTitle ? '' : 'title; ';
-  const sections = Array.isArray(check.missingSections)
-    ? check.missingSections.join(', ')
-    : '';
-  return `report failed contract check: missing ${titlePart}sections=[${sections}]`;
-}
-
-/**
- * Reduce a rejection reason to a single-line message.
- *
- * @param {unknown} reason
- * @returns {string}
- */
-function describeRejection(reason) {
-  if (reason instanceof Error) return reason.message;
-  return String(reason ?? 'unknown error');
-}
-
-/**
- * Partition settled fan-out results into the values that completed and the
- * dimensions that did not. `dimensions[i]` names the dimension behind
- * `settled[i]`, so a rejection is always attributable.
- *
- * @template T
- * @param {readonly string[]} dimensions
- * @param {readonly PromiseSettledResult<T>[]} settled
- * @param {string} phaseName Phase recorded on each failure.
- * @returns {{ fulfilled: T[], failures: DimensionFailure[] }}
- */
-function partitionSettled(dimensions, settled, phaseName) {
-  const fulfilled = [];
-  const failures = [];
-  settled.forEach((result, index) => {
-    if (result.status === 'fulfilled') {
-      fulfilled.push(result.value);
-      return;
-    }
-    failures.push({
-      dimension: dimensions[index],
-      phase: phaseName,
-      reason: describeRejection(result.reason),
-    });
-  });
-  return { fulfilled, failures };
-}
-
-/**
- * Run the shared three-phase audit-lens orchestration: parallel per-dimension
- * analysis → adversarial cross-check → synthesis + report-contract self-check.
- *
- * The caller supplies everything lens-specific (dimensions, prompt builders,
- * tool allowlist, contract assertion); this engine owns the fan-out plumbing
- * and the read-only / single-write tool discipline.
- *
- * @template TReport
- * @param {AuditOrchestrationSpec<TReport>} spec
- * @returns {Promise<TReport>}
- */
-export async function runAuditOrchestration(spec) {
-  const {
-    ctx,
-    dimensions,
-    readOnlyTools,
-    buildDimensionPrompt,
-    buildCrossCheckPrompt,
-    buildSynthesisPrompt,
-    assertReportContract,
-    formatContractError = defaultContractError,
-    buildResult = (report) => /** @type {TReport} */ ({ report }),
-  } = spec;
-
-  const { agent, phase } = ctx;
-
-  // Phase 1 — parallel per-dimension analysis (read-only agents). Settled, not
-  // all-or-nothing: one dimension's rejection must not discard its siblings.
-  const analyzed = await phase(ORCHESTRATION_PHASES.ANALYZE, async () =>
-    Promise.allSettled(
-      dimensions.map(async (dimension) => {
-        const { output } = await agent({
-          prompt: buildDimensionPrompt(dimension),
-          allowedTools: [...readOnlyTools],
-        });
-        return { dimension, findings: output };
-      }),
-    ),
-  );
-  const { fulfilled: rawFindings, failures: analyzeFailures } =
-    partitionSettled(dimensions, analyzed, 'analyze');
-
-  // Phase 2 — adversarial cross-check: an independent agent re-verifies each
-  // surviving dimension's findings and filters false positives before
-  // inclusion. Settled for the same reason as phase 1.
-  const checkedDimensions = rawFindings.map((entry) => entry.dimension);
-  const checked = await phase(ORCHESTRATION_PHASES.CROSS_CHECK, async () =>
-    Promise.allSettled(
-      rawFindings.map(async ({ dimension, findings }) => {
-        const { output } = await agent({
-          prompt: buildCrossCheckPrompt(dimension, findings),
-          allowedTools: [...readOnlyTools],
-        });
-        return output;
-      }),
-    ),
-  );
-  const { fulfilled: crossChecked, failures: crossCheckFailures } =
-    partitionSettled(checkedDimensions, checked, 'cross-check');
-
-  const degraded = [...analyzeFailures, ...crossCheckFailures];
-  if (dimensions.length > 0 && crossChecked.length === 0) {
-    // Nothing survived — there is no partial report to salvage.
-    throw new Error(
-      `every audit dimension failed: ${degraded
-        .map((f) => `${f.dimension} (${f.phase}: ${f.reason})`)
-        .join('; ')}`,
-    );
-  }
-
-  // Phase 3 — synthesis: assemble the report contract and write the artifact.
-  const { output: synthesised } = await phase(
-    ORCHESTRATION_PHASES.SYNTHESIZE,
-    async () =>
-      agent({
-        prompt: buildSynthesisPrompt(crossChecked, degraded),
-        // Synthesis is the one stage permitted to write the report artifact.
-        allowedTools: [...readOnlyTools, SYNTHESIS_WRITE_TOOL],
-      }),
-  );
-
-  // The coverage gap is annotated by the engine, never left to the synthesis
-  // agent's discretion.
-  const report = withDegradedCoverageNote(
-    synthesised,
-    degraded,
-    dimensions.length,
-  );
-
-  // Self-verify report-contract conformance before returning.
-  const check = assertReportContract(report);
-  if (!check.conformant) {
-    throw new Error(formatContractError(check));
-  }
-
-  return buildResult(report);
-}

package/.agents/scripts/lib/dynamic-workflow/clean-code-report-contract.js

@@ -1,80 +0,0 @@
-// .agents/scripts/lib/dynamic-workflow/clean-code-report-contract.js
-import { assertSectionsContract } from './report-contract-core.js';
-
-/**
- * The `audit-clean-code` report contract (Story #3278).
- *
- * This is the **single source of truth** for the report shape that BOTH the
- * sequential lens (`.agents/workflows/audit-clean-code.md` Step 3) and the
- * orchestrated dynamic-workflow path
- * (`.claude/workflows/audit-clean-code.workflow.js`) MUST emit to
- * `{{auditOutputDir}}/audit-clean-code-results.md`. Keeping it here lets the
- * contract-tier test assert report conformance against one definition rather
- * than re-deriving headings from prose in two places.
- *
- * This module documents the **existing** report shape; it does not introduce
- * a new one. Changing the report contract is a separate, deliberate decision —
- * not a side effect of the dual-path orchestration work.
- *
- * @module dynamic-workflow/clean-code-report-contract
- */
-
-/** The artifact filename the lens writes under `auditOutputDir`. */
-export const REPORT_ARTIFACT_BASENAME = 'audit-clean-code-results.md';
-
-/**
- * The required top-level (`##`) section headings, in document order, that the
- * lens markdown's Step 3 template defines. A conformant report MUST contain
- * each of these headings; the orchestrated path assembles its sub-agent
- * findings into exactly this skeleton.
- */
-export const REQUIRED_SECTIONS = Object.freeze([
-  'Executive Summary',
-  'Detailed Findings',
-  'Dead Code Inventory',
-  'Technical Debt Backlog',
-]);
-
-/** The H1 title the report opens with. */
-export const REPORT_TITLE = 'Clean Code Audit Report';
-
-/**
- * The required field labels inside each `### <finding>` block under
- * `## Detailed Findings`. Mirrors the strict per-finding structure in the
- * lens template.
- */
-export const FINDING_FIELDS = Object.freeze([
-  'Dimension',
-  'Impact',
-  'Current State',
-  'Recommendation & Rationale',
-  'Agent Prompt',
-]);
-
-/**
- * The Dead Code Inventory table column headers, in order.
- */
-export const DEAD_CODE_COLUMNS = Object.freeze([
-  'File',
-  'Symbol / Block',
-  'Type',
-  'Estimated LOC',
-]);
-
-/**
- * Assert that a rendered markdown report conforms to the contract: it has the
- * H1 title and every required `##` section heading. Returns a structured
- * result rather than throwing, so callers (tests, the orchestrated path's
- * self-check) can report precisely which sections are missing.
- *
- * Pure function — string analysis only.
- *
- * @param {string} markdown - The rendered report body.
- * @returns {{ conformant: boolean, missingSections: string[], hasTitle: boolean }}
- */
-export function assertReportContract(markdown) {
-  return assertSectionsContract(markdown, {
-    title: REPORT_TITLE,
-    requiredSections: REQUIRED_SECTIONS,
-  });
-}

package/.agents/scripts/lib/dynamic-workflow/degraded-coverage.js

@@ -1,81 +0,0 @@
-// .agents/scripts/lib/dynamic-workflow/degraded-coverage.js
-/**
- * Degraded-coverage annotation for audit-lens reports (Story #4783).
- *
- * An audit lens fans out one sub-agent per analysis dimension. When one of
- * those dimensions rejects — a sub-agent that ran out of context, a
- * measurement command that failed, a transient runtime error — the run used to
- * discard every sibling dimension's completed work along with it.
- *
- * The engine now partitions instead: the fulfilled dimensions flow on to
- * synthesis, and the rejected ones are recorded here as an explicit note in
- * the report's Executive Summary. A lens that covers four of five dimensions
- * *and says which one is missing* is strictly more useful than one that yields
- * nothing — but only if the gap is visible. An unannotated partial report is
- * worse than no report, because it reads as complete coverage.
- *
- * The annotation is applied by the engine, not requested of the synthesis
- * agent: a coverage disclaimer that depends on an LLM remembering to write it
- * is not a disclaimer.
- *
- * @module dynamic-workflow/degraded-coverage
- */
-
-/**
- * A dimension that did not complete.
- *
- * @typedef {object} DimensionFailure
- * @property {string} dimension The analysis dimension that failed.
- * @property {string} phase     The phase it failed in (`analyze` / `cross-check`).
- * @property {string} reason    The rejection's message.
- */
-
-/** Matches the Executive Summary heading at any heading level. */
-const EXECUTIVE_SUMMARY_HEADING = /^#{1,6}\s+Executive Summary\b/i;
-
-/**
- * Render the degraded-coverage note. Names every failed dimension, the phase
- * it failed in, and the reason, so a reader can tell coverage loss apart from
- * an absence of findings.
- *
- * @param {readonly DimensionFailure[]} failures
- * @param {number} totalDimensions Dimensions the run set out to cover.
- * @returns {string} A markdown blockquote.
- */
-function formatDegradedCoverageNote(failures, totalDimensions) {
-  const detail = failures
-    .map((f) => `**${f.dimension}** (${f.phase}: ${f.reason})`)
-    .join('; ');
-  const noun = failures.length === 1 ? 'dimension' : 'dimensions';
-  return [
-    `> ⚠️ **Degraded coverage** — ${failures.length} of ${totalDimensions} analysis ${noun} did not complete`,
-    `> and ${failures.length === 1 ? 'is' : 'are'} unrepresented in this report: ${detail}.`,
-    '> Findings for the remaining dimensions are complete; the gap above is not evidence of their absence.',
-  ].join('\n');
-}
-
-/**
- * Annotate a synthesised report with the degraded-coverage note, inserted
- * directly beneath the `## Executive Summary` heading (every lens report
- * contract requires that section). A report without the heading is prefixed
- * instead, so the note can never be silently dropped.
- *
- * Returns the report unchanged when nothing failed — a full-coverage run must
- * not carry a coverage caveat.
- *
- * @param {string} report
- * @param {readonly DimensionFailure[]} failures
- * @param {number} totalDimensions
- * @returns {string}
- */
-export function withDegradedCoverageNote(report, failures, totalDimensions) {
-  if (!Array.isArray(failures) || failures.length === 0) return report;
-  const note = formatDegradedCoverageNote(failures, totalDimensions);
-  const lines = String(report).split('\n');
-  const headingIndex = lines.findIndex((line) =>
-    EXECUTIVE_SUMMARY_HEADING.test(line.trim()),
-  );
-  if (headingIndex === -1) return `${note}\n\n${report}`;
-  lines.splice(headingIndex + 1, 0, '', note);
-  return lines.join('\n');
-}

package/.agents/scripts/lib/dynamic-workflow/documentation-report-contract.js

@@ -1,87 +0,0 @@
-// .agents/scripts/lib/dynamic-workflow/documentation-report-contract.js
-import { assertSectionsContract } from './report-contract-core.js';
-
-/**
- * The `audit-documentation` report contract (Story #4024).
- *
- * This is the **single source of truth** for the report shape that BOTH the
- * sequential lens (`.agents/workflows/audit-documentation.md` Step 3) and the
- * orchestrated dynamic-workflow path
- * (`.claude/workflows/audit-documentation.workflow.js`) MUST emit to
- * `{{auditOutputDir}}/audit-documentation-results.md`. Keeping it here lets
- * the contract-tier test assert report conformance against one definition
- * rather than re-deriving headings from prose in two places.
- *
- * @module dynamic-workflow/documentation-report-contract
- */
-
-/** The artifact filename the lens writes under `auditOutputDir`. */
-export const REPORT_ARTIFACT_BASENAME = 'audit-documentation-results.md';
-
-/**
- * The required top-level (`##`) section headings, in document order, that the
- * lens markdown's Step 3 template defines. A conformant report MUST contain
- * each of these headings; the orchestrated path assembles its verified
- * findings into exactly this skeleton.
- */
-export const REQUIRED_SECTIONS = Object.freeze([
-  'Executive Summary',
-  'Target Set Coverage',
-  'Detailed Findings',
-]);
-
-/** The H1 title the report opens with. */
-export const REPORT_TITLE = 'Documentation Audit Report';
-
-/**
- * The required field labels inside each `### <finding>` block under
- * `## Detailed Findings`. Mirrors the strict per-finding structure in the
- * lens template.
- */
-export const FINDING_FIELDS = Object.freeze([
-  'Category',
-  'Impact',
-  'Current State',
-  'Recommendation & Rationale',
-  'Agent Prompt',
-]);
-
-/**
- * The finding categories the per-finding `Category` field draws from. These
- * mirror the lens's Step 3 template enumeration: deterministic-gate findings
- * (Generator Drift, Link Integrity) plus semantic-verification findings
- * (Broken Instruction, Stale Description, Missing Coverage).
- */
-export const FINDING_CATEGORIES = Object.freeze([
-  'Broken Instruction',
-  'Stale Description',
-  'Missing Coverage',
-  'Generator Drift',
-  'Link Integrity',
-]);
-
-/**
- * The impact buckets the Executive Summary and per-finding `Impact` field draw
- * from. The lens speaks in High/Medium/Low; this list is the canonical
- * taxonomy the downstream `audit-to-stories` consumer maps onto Story
- * priority.
- */
-export const IMPACT_LEVELS = Object.freeze(['High', 'Medium', 'Low']);
-
-/**
- * Assert that a rendered markdown report conforms to the contract: it has the
- * H1 title and every required `##` section heading. Returns a structured
- * result rather than throwing, so callers (tests, the orchestrated path's
- * self-check) can report precisely which sections are missing.
- *
- * Pure function — string analysis only.
- *
- * @param {string} markdown - The rendered report body.
- * @returns {{ conformant: boolean, missingSections: string[], hasTitle: boolean }}
- */
-export function assertReportContract(markdown) {
-  return assertSectionsContract(markdown, {
-    title: REPORT_TITLE,
-    requiredSections: REQUIRED_SECTIONS,
-  });
-}

package/.agents/scripts/lib/dynamic-workflow/performance-report-contract.js

@@ -1,74 +0,0 @@
-// .agents/scripts/lib/dynamic-workflow/performance-report-contract.js
-import { assertSectionsContract } from './report-contract-core.js';
-
-/**
- * The `audit-performance` report contract (Epic #3597, Story #3611).
- *
- * This is the **single source of truth** for the report shape that BOTH the
- * sequential lens (`.agents/workflows/audit-performance.md` Step 3) and the
- * orchestrated dynamic-workflow path
- * (`.claude/workflows/audit-performance.workflow.js`) MUST emit to
- * `{{auditOutputDir}}/audit-performance-results.md`. Keeping it here lets the
- * contract-tier test assert report conformance against one definition rather
- * than re-deriving headings from prose in two places.
- *
- * The report shape is declared by the lens markdown's Step 4 template. Story
- * #4631 added the mandatory per-finding **Evidence** field (a repro command
- * plus a `measured`/`estimated` tag) so measurement-first evidence is part of
- * the contract both paths must emit, not just prose in the lens.
- *
- * @module dynamic-workflow/performance-report-contract
- */
-
-/** The artifact filename the lens writes under `auditOutputDir`. */
-export const REPORT_ARTIFACT_BASENAME = 'audit-performance-results.md';
-
-/**
- * The required top-level (`##`) section headings, in document order, that the
- * lens markdown's Step 3 template defines. A conformant report MUST contain
- * each of these headings; the orchestrated path assembles its cross-checked
- * sub-agent findings into exactly this skeleton.
- *
- * The `Low-Hanging Fruit` section is the performance lens's distinguishing
- * section — the quick-win backlog the synthesis stage must always emit.
- */
-export const REQUIRED_SECTIONS = Object.freeze([
-  'Executive Summary',
-  'Detailed Findings',
-  'Low-Hanging Fruit',
-]);
-
-/** The H1 title the report opens with. */
-export const REPORT_TITLE = 'Performance Audit Report';
-
-/**
- * The required field labels inside each `### <finding>` block under
- * `## Detailed Findings`. Mirrors the strict per-finding structure in the
- * lens template.
- */
-export const FINDING_FIELDS = Object.freeze([
-  'Dimension',
-  'Impact',
-  'Evidence',
-  'Current State',
-  'Recommendation & Rationale',
-  'Agent Prompt',
-]);
-
-/**
- * Assert that a rendered markdown report conforms to the contract: it has the
- * H1 title and every required `##` section heading. Returns a structured
- * result rather than throwing, so callers (tests, the orchestrated path's
- * self-check) can report precisely which sections are missing.
- *
- * Pure function — string analysis only.
- *
- * @param {string} markdown - The rendered report body.
- * @returns {{ conformant: boolean, missingSections: string[], hasTitle: boolean }}
- */
-export function assertReportContract(markdown) {
-  return assertSectionsContract(markdown, {
-    title: REPORT_TITLE,
-    requiredSections: REQUIRED_SECTIONS,
-  });
-}