mandrel 2.15.0 → 2.17.0

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

@@ -26,6 +26,18 @@
  * 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`
@@ -43,6 +55,14 @@
  * @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
@@ -82,8 +102,11 @@
  *   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 {(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]
@@ -122,6 +145,45 @@ export function defaultContractError(check) {
   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.
@@ -149,9 +211,10 @@ export async function runAuditOrchestration(spec) {
 
   const { agent, phase } = ctx;
 
-  // Phase 1 — parallel per-dimension analysis (read-only agents).
-  const rawFindings = await phase(ORCHESTRATION_PHASES.ANALYZE, async () =>
-    Promise.all(
+  // 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),
@@ -161,11 +224,15 @@ export async function runAuditOrchestration(spec) {
       }),
     ),
   );
+  const { fulfilled: rawFindings, failures: analyzeFailures } =
+    partitionSettled(dimensions, analyzed, 'analyze');
 
   // 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(
+  // 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),
@@ -175,18 +242,38 @@ export async function runAuditOrchestration(spec) {
       }),
     ),
   );
+  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: report } = await phase(
+  const { output: synthesised } = await phase(
     ORCHESTRATION_PHASES.SYNTHESIZE,
     async () =>
       agent({
-        prompt: buildSynthesisPrompt(crossChecked),
+        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) {

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

@@ -0,0 +1,81 @@
+// .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/git-branch-lifecycle.js

@@ -134,16 +134,22 @@ export function classifyBranchSeed({ localHas, remoteHas }) {
  *
  * Caller-specific log lines and error text are passed in as the `messages`
  * data bag so behaviour stays byte-identical to the pre-extraction switches.
- * The git seams (`spawn`, `existsLocally`, `existsRemotely`) are injected so
- * each caller can bind its own cwd (and tests can mock them).
+ * The git seams (`spawn`, `existsLocally`, `existsRemotely`) are injectable so
+ * each caller can bind its own cwd (and tests can substitute stubs through the
+ * parameter rather than by module mocking). Per
+ * `.agents/rules/test-seams.md` rule 1 each seam **defaults to the real
+ * implementation** bound to `cwd`, so a caller that only knows its checkout
+ * passes `cwd` and nothing else; `single-story-init.js` keeps passing its own
+ * pre-bound seams and is unaffected.
  *
  * @param {object} opts
  * @param {string} opts.storyBranch
  * @param {string} opts.baseRef            Ref to branch from on `create`.
+ * @param {string} [opts.cwd]              Checkout the default seams bind to.
  * @param {boolean} [opts.swallowCreateRace=false]
- * @param {(args: string[]) => { status: number, stdout?: string, stderr?: string }} opts.spawn
- * @param {(branch: string) => boolean} opts.existsLocally
- * @param {(branch: string) => boolean} opts.existsRemotely
+ * @param {(args: string[]) => { status: number, stdout?: string, stderr?: string }} [opts.spawn]
+ * @param {(branch: string) => boolean} [opts.existsLocally]
+ * @param {(branch: string) => boolean} [opts.existsRemotely]
  * @param {(level: string, message: string) => void} [opts.progress]
  * @param {object} opts.messages
  * @param {(b: string) => string} opts.messages.reuse
@@ -158,10 +164,11 @@ export function classifyBranchSeed({ localHas, remoteHas }) {
 export function seedStoryBranchRef({
   storyBranch,
   baseRef,
+  cwd,
   swallowCreateRace = false,
-  spawn,
-  existsLocally,
-  existsRemotely,
+  spawn = (args) => gitSpawn(cwd, ...args),
+  existsLocally = (branch) => branchExistsLocally(branch, cwd),
+  existsRemotely = (branch) => branchExistsViaTrackingRef(branch, cwd),
   progress = () => {},
   messages,
 }) {

package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js

@@ -12,6 +12,7 @@
 import { readBaseFromGit } from '../../../baselines/git-base.js';
 import { getKindModule } from '../../../baselines/kernel.js';
 import { resolveScope } from '../../../baselines/scope.js';
+import { Logger } from '../../../Logger.js';
 import { DEFAULT_BASELINE_PATHS } from './parse-args.js';
 
 function baselineRelativePath(kind, gateBlock) {
@@ -67,6 +68,29 @@ export async function evaluateCompare({ kind, gateBlock, scope, cwd }) {
   return { baseRef: scope.ref, baseRead: true, basePayload, kindModule };
 }
 
+/**
+ * Is the base baseline comparable to the head baseline (Story #4775)?
+ *
+ * A kind can change its SCORING SEMANTICS — how it derives a row's metric —
+ * without moving `kernelVersion`. Across that boundary the same row can carry
+ * a different score for reasons that have nothing to do with the branch's
+ * changes, so a head-vs-base diff manufactures phantom regressions (and can
+ * hide real ones behind them).
+ *
+ * The head-side stamp is already a fail-closed gate: a stale HEAD baseline
+ * never reaches this point. What reaches here is the opposite and legitimate
+ * case — a branch that DOES carry a re-derived baseline, compared against a
+ * base that predates the change. The only honest verdict is "no comparison";
+ * floors still run, so a genuine ceiling breach is still caught, and once the
+ * refreshed baseline is the base the ratchet returns to full strength on the
+ * very next run without anything to remember to reset.
+ */
+function baseIsComparable(headBaseline, basePayload) {
+  const head = headBaseline?.scoringSemantics ?? null;
+  const base = basePayload?.scoringSemantics ?? null;
+  return head === base;
+}
+
 export function runCompareStage(headBaseline, cmp) {
   const empty = {
     regressions: [],
@@ -75,6 +99,17 @@ export function runCompareStage(headBaseline, cmp) {
     additions: [],
   };
   if (!cmp.baseRead || !cmp.basePayload || !cmp.kindModule) return empty;
+  if (!baseIsComparable(headBaseline, cmp.basePayload)) {
+    Logger.warn(
+      `[${cmp.kindModule.name}] ⚠ base baseline was scored under different ` +
+        `semantics (base=${cmp.basePayload.scoringSemantics ?? '<unstamped>'} ` +
+        `head=${headBaseline?.scoringSemantics ?? '<unstamped>'}); its rows are ` +
+        'not comparable, so the head-vs-base compare is skipped for this run. ' +
+        'Floors still enforced. The ratchet resumes once the re-derived ' +
+        'baseline is the base.',
+    );
+    return empty;
+  }
   try {
     const baseRows = Array.isArray(cmp.basePayload.rows)
       ? cmp.basePayload.rows

package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js

@@ -13,6 +13,7 @@ import {
 } from '../../../baselines/env-overrides.js';
 import { readRangeSubjectsTouchingFile } from '../../../baselines/git-base.js';
 import {
+  checkBaselineSemantics,
   checkKernelVersion,
   getKindModule,
 } from '../../../baselines/kernel.js';
@@ -247,6 +248,18 @@ export async function evaluateKind({
   const headLoad = loadHeadBaseline(kind, cwd, configPath);
   if (headLoad.schemaError) return { kind, schemaError: headLoad.schemaError };
   const baseline = headLoad.baseline;
+  // Story #4775 — scoring-semantics gate. A baseline whose rows were produced
+  // by superseded scoring semantics is structurally valid but semantically
+  // incomparable, so schema validation alone would wave it through. Fail
+  // closed on the `semantics` tag rather than compare across the boundary;
+  // the message names the exact re-baseline command.
+  const semanticsError = checkBaselineSemantics(kind, baseline);
+  if (semanticsError) {
+    return {
+      kind,
+      schemaError: { tag: 'semantics', message: semanticsError },
+    };
+  }
   const floorRollup = rollupExcludingIgnored({
     kind,
     baseline,