mandrel 1.57.0

package/.agents/scripts/lib/duplicate-search.js

@@ -0,0 +1,189 @@
+/**
+ * duplicate-search.js — Cross-Epic Duplicate Detection
+ *
+ * Used by `/epic-plan` Phase 2 (s-plan-ideation) to surface open Epics
+ * whose scope overlaps with a sharpened one-pager before a new Epic is
+ * created. Returns ranked candidates with an overlap score and URL so
+ * the host LLM can pause for HITL confirmation.
+ *
+ * Design notes:
+ *  - The provider abstraction (`ITicketingProvider#getEpics`) is the
+ *    only I/O surface; the scoring routine is pure and trivially
+ *    testable in isolation.
+ *  - Scoring is intentionally simple (token Jaccard over title +
+ *    structured one-pager sections). It is a triage signal, not a
+ *    semantic-search replacement.
+ *  - Provider errors propagate verbatim — the caller is responsible
+ *    for translating them into a friction comment or operator-visible
+ *    failure.
+ */
+
+const STOPWORDS = new Set([
+  'a',
+  'an',
+  'and',
+  'are',
+  'as',
+  'at',
+  'be',
+  'but',
+  'by',
+  'for',
+  'from',
+  'has',
+  'have',
+  'how',
+  'if',
+  'in',
+  'into',
+  'is',
+  'it',
+  'its',
+  'me',
+  'might',
+  'not',
+  'of',
+  'on',
+  'or',
+  'our',
+  'should',
+  'so',
+  'than',
+  'that',
+  'the',
+  'their',
+  'them',
+  'then',
+  'there',
+  'these',
+  'they',
+  'this',
+  'those',
+  'to',
+  'we',
+  'what',
+  'when',
+  'which',
+  'who',
+  'why',
+  'will',
+  'with',
+  'would',
+  'you',
+  'your',
+]);
+
+const DEFAULT_MIN_SCORE = 0.15;
+const DEFAULT_MAX_RESULTS = 5;
+
+/**
+ * Tokenize freeform text into a deduplicated set of meaningful words.
+ *
+ * @param {string} text
+ * @returns {Set<string>}
+ */
+export function tokenize(text) {
+  if (!text || typeof text !== 'string') return new Set();
+  const tokens = text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .split(/\s+/)
+    .filter((t) => t.length >= 3 && !STOPWORDS.has(t));
+  return new Set(tokens);
+}
+
+/**
+ * Compute the Jaccard overlap between two token sets.
+ *
+ * @param {Set<string>} a
+ * @param {Set<string>} b
+ * @returns {number} 0..1
+ */
+export function overlapScore(a, b) {
+  if (!a || !b || a.size === 0 || b.size === 0) return 0;
+  let intersection = 0;
+  for (const tok of a) if (b.has(tok)) intersection += 1;
+  const union = a.size + b.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+/**
+ * Build the Epic URL for an issue id. The candidate exposes the URL so
+ * the HITL pause can render clickable links without a second round-trip.
+ *
+ * @param {number|string} id
+ * @param {{ owner?: string, repo?: string }} [opts]
+ * @returns {string}
+ */
+function buildEpicUrl(id, opts = {}) {
+  const owner = opts.owner || process.env.GITHUB_OWNER;
+  const repo = opts.repo || process.env.GITHUB_REPO;
+  if (owner && repo) {
+    return `https://github.com/${owner}/${repo}/issues/${id}`;
+  }
+  return `#${id}`;
+}
+
+/**
+ * Find open Epics whose title + body overlap with the supplied
+ * one-pager above a configurable threshold.
+ *
+ * @param {{
+ *   onePager: string,
+ *   provider: import('./ITicketingProvider.js').ITicketingProvider,
+ *   minScore?: number,
+ *   maxResults?: number,
+ *   owner?: string,
+ *   repo?: string,
+ * }} args
+ * @returns {Promise<Array<{ id: number, title: string, score: number, url: string }>>}
+ */
+export async function findSimilarOpenEpics({
+  onePager,
+  provider,
+  minScore = DEFAULT_MIN_SCORE,
+  maxResults = DEFAULT_MAX_RESULTS,
+  owner,
+  repo,
+}) {
+  if (!onePager || typeof onePager !== 'string') {
+    throw new Error(
+      'findSimilarOpenEpics: onePager must be a non-empty string',
+    );
+  }
+  if (!provider || typeof provider.getEpics !== 'function') {
+    throw new Error('findSimilarOpenEpics: provider must implement getEpics()');
+  }
+
+  const seedTokens = tokenize(onePager);
+  if (seedTokens.size === 0) return [];
+
+  // Provider errors propagate verbatim — caller decides how to surface.
+  const epics = await provider.getEpics({ state: 'open' });
+  if (!Array.isArray(epics) || epics.length === 0) return [];
+
+  const ranked = [];
+  for (const epic of epics) {
+    const corpus = `${epic.title || ''}\n${epic.body || ''}`;
+    const candidateTokens = tokenize(corpus);
+    const score = overlapScore(seedTokens, candidateTokens);
+    if (score >= minScore) {
+      ranked.push({
+        id: epic.id,
+        title: epic.title,
+        score: Number(score.toFixed(4)),
+        url: buildEpicUrl(epic.id, { owner, repo }),
+      });
+    }
+  }
+
+  ranked.sort((a, b) => b.score - a.score);
+  return ranked.slice(0, maxResults);
+}
+
+export const __test = {
+  STOPWORDS,
+  DEFAULT_MIN_SCORE,
+  DEFAULT_MAX_RESULTS,
+  buildEpicUrl,
+};

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

@@ -0,0 +1,70 @@
+// .agents/scripts/lib/dynamic-workflow/architecture-report-contract.js
+import { assertSectionsContract } from './report-contract-core.js';
+
+/**
+ * The `audit-architecture` report contract (Epic #3597, Story #3612).
+ *
+ * This is the **single source of truth** for the report shape that BOTH the
+ * sequential lens (`.agents/workflows/audit-architecture.md` Step 3) and the
+ * orchestrated dynamic-workflow path
+ * (`.claude/workflows/audit-architecture.workflow.js`) MUST emit to
+ * `{{auditOutputDir}}/audit-architecture-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.
+ *
+ * Changing the report contract is explicitly **out of scope** for this Story —
+ * the orchestrated path emits the lens's existing report contract unchanged.
+ * This module documents the existing shape, it does not introduce a new one.
+ *
+ * @module dynamic-workflow/architecture-report-contract
+ */
+
+/** The artifact filename the lens writes under `auditOutputDir`. */
+export const REPORT_ARTIFACT_BASENAME = 'audit-architecture-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',
+  'Triage Summary',
+  'Architecture Guardrail Coverage',
+  'Detailed Findings',
+]);
+
+/** The H1 title the report opens with. */
+export const REPORT_TITLE = 'Architecture & Clean Code Review';
+
+/**
+ * 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',
+  'Dimension',
+  '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,
+  });
+}

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

@@ -0,0 +1,197 @@
+// .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`.
+ *
+ * ## 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
+ */
+
+/**
+ * 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[]) => string} buildSynthesisPrompt
+ *   Compose the synthesis prompt that assembles the report and writes it.
+ * @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}]`;
+}
+
+/**
+ * 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).
+  const rawFindings = await phase(ORCHESTRATION_PHASES.ANALYZE, async () =>
+    Promise.all(
+      dimensions.map(async (dimension) => {
+        const { output } = await agent({
+          prompt: buildDimensionPrompt(dimension),
+          allowedTools: [...readOnlyTools],
+        });
+        return { dimension, findings: output };
+      }),
+    ),
+  );
+
+  // Phase 2 — adversarial cross-check: an independent agent re-verifies each
+  // dimension's findings and filters false positives before inclusion.
+  const crossChecked = await phase(ORCHESTRATION_PHASES.CROSS_CHECK, async () =>
+    Promise.all(
+      rawFindings.map(async ({ dimension, findings }) => {
+        const { output } = await agent({
+          prompt: buildCrossCheckPrompt(dimension, findings),
+          allowedTools: [...readOnlyTools],
+        });
+        return output;
+      }),
+    ),
+  );
+
+  // Phase 3 — synthesis: assemble the report contract and write the artifact.
+  const { output: report } = await phase(
+    ORCHESTRATION_PHASES.SYNTHESIZE,
+    async () =>
+      agent({
+        prompt: buildSynthesisPrompt(crossChecked),
+        // Synthesis is the one stage permitted to write the report artifact.
+        allowedTools: [...readOnlyTools, SYNTHESIS_WRITE_TOOL],
+      }),
+  );
+
+  // Self-verify report-contract conformance before returning.
+  const check = assertReportContract(report);
+  if (!check.conformant) {
+    throw new Error(formatContractError(check));
+  }
+
+  return buildResult(report);
+}