@dev-loops/core 1.0.0-rc.6 → 1.0.0

package/src/loop/gate-fanin.mjs

@@ -34,6 +34,7 @@
  */
 
 import { scheduleParallelWaves } from "./queue-parallel.mjs";
+import { trimmedOrNull } from "./normalize.mjs";
 
 /**
  * Schedule fan-out dispatch units into bounded-concurrency waves (issue #1601).
@@ -106,30 +107,46 @@ export function backoffMaxConcurrent(maxConcurrent) {
  *
  * @param {{ name: string, angles: string[] }[]} dispatchGroups — `resolveFanoutGroups` output (fresh angles + re-verifications)
  * @param {number|null} [availableReviewers] — harness remaining reviewer budget; null/non-finite = unknown/unexposed
- * @param {{ completedAngles?: Iterable<string> }} [options] — `completedAngles`: angle names that
- *   already have a clean per-angle findings artifact stamped for THIS head. A dispatch unit (group)
- *   whose angles are ALL complete is excluded from the required count and from `pendingGroups`, so a
- *   later session resumes the fan-out instead of restarting it (issue #1507 AC3): it re-runs the
- *   preflight and dispatches only the groups not already complete at this head.
- * @returns {{ ok: boolean, dispatch: boolean, requiredReviewers: number, availableReviewers: number|null, shortfall: number|null, reason: string, verdict: null, executionMode: null, pendingGroups: { name: string, angles: string[] }[], skippedGroups: { name: string, angles: string[] }[], completedAngles: string[] }}
+ * @param {{ completedAngles?: Iterable<string>, carriedAngles?: Iterable<string> }} [options] — `completedAngles`:
+ *   angle names that already have a clean per-angle findings artifact stamped for THIS head.
+ *   `carriedAngles`: angle names the fail-closed carry-forward seam (resolve-angle-carry-forward.mjs)
+ *   has proven carried from a prior clean head, so no reviewer re-runs them this round either — that
+ *   carry-forward resolution runs AFTER this preflight, so a head-bump re-gate must feed its result
+ *   back in to avoid over-counting. A dispatch unit (group) whose angles are ALL complete-or-carried
+ *   is excluded from the required count and from `pendingGroups`, so a later session resumes the
+ *   fan-out instead of restarting it: it re-runs the preflight and dispatches only the groups not
+ *   already resolved at this head. Membership is matched trim+lowercase (mirrors
+ *   consolidate-fanin.mjs's own carried-key normalization) so a config/plan case difference in an
+ *   angle name still excludes the right group instead of silently spending a reviewer on it.
+ * @returns {{ ok: boolean, dispatch: boolean, requiredReviewers: number, availableReviewers: number|null, shortfall: number|null, reason: string, verdict: null, executionMode: null, pendingGroups: { name: string, angles: string[] }[], skippedGroups: { name: string, angles: string[] }[], completedAngles: string[], carriedAngles: string[] }}
  */
-export function reviewerBudgetPreflight(dispatchGroups, availableReviewers, { completedAngles } = {}) {
+export function reviewerBudgetPreflight(dispatchGroups, availableReviewers, { completedAngles, carriedAngles } = {}) {
   const groups = Array.isArray(dispatchGroups) ? dispatchGroups : [];
-  const completedSet = new Set(
-    Array.isArray(completedAngles)
-      ? completedAngles
-      : completedAngles == null
-        ? []
-        : [...completedAngles],
-  );
-  // #1507 AC3: resume instead of restart. One reviewer per dispatch unit (a
-  // group of N angles is one reviewer's scoped dispatch — see resolveFanoutGroups /
-  // countFreshDispatchUnits), but a group already COMPLETE at this head — every
-  // one of its angles has a clean artifact stamped for this head — needs no
-  // reviewer and is excluded from the required count and the pending plan. The
-  // conductor dispatches only `pendingGroups`.
+  const toSet = (iterable) =>
+    new Set(Array.isArray(iterable) ? iterable : iterable == null ? [] : [...iterable]);
+  const completedSet = toSet(completedAngles);
+  const carriedSet = toSet(carriedAngles);
+  // Same-head resume + head-bump carry-forward: one reviewer per dispatch unit
+  // (a group of N angles is one reviewer's scoped dispatch — see
+  // resolveFanoutGroups / countFreshDispatchUnits), but a group already
+  // RESOLVED for this round — every one of its angles either has a clean
+  // artifact stamped for this head OR is proven carried forward from a prior
+  // clean head — needs no reviewer and is excluded from the required count
+  // and the pending plan. The conductor dispatches only `pendingGroups`.
+  // Membership is matched trim+lowercase (`normalizeAngleKey`) — the same
+  // normalization consolidate-fanin.mjs applies to its own carried keys — so a
+  // config/plan case difference in an angle name still excludes the group
+  // instead of leaving it (and its exempted sibling) silently disagreeing.
+  const normalizeAngleKey = (a) => String(a).trim().toLowerCase();
+  const completedKeys = new Set([...completedSet].map(normalizeAngleKey));
+  const carriedKeys = new Set([...carriedSet].map(normalizeAngleKey));
   const groupIsComplete = (g) =>
-    Array.isArray(g?.angles) && g.angles.length > 0 && g.angles.every((a) => completedSet.has(a));
+    Array.isArray(g?.angles) &&
+    g.angles.length > 0 &&
+    g.angles.every((a) => {
+      const key = normalizeAngleKey(a);
+      return completedKeys.has(key) || carriedKeys.has(key);
+    });
   const pendingGroups = groups.filter((g) => !groupIsComplete(g));
   const skippedGroups = groups.filter((g) => groupIsComplete(g));
   // One reviewer per dispatch unit: a group of N angles is one reviewer's
@@ -138,7 +155,7 @@ export function reviewerBudgetPreflight(dispatchGroups, availableReviewers, { co
   const requiredReviewers = pendingGroups.length;
   const verdict = null;
   const executionMode = null;
-  const resume = { pendingGroups, skippedGroups, completedAngles: [...completedSet] };
+  const resume = { pendingGroups, skippedGroups, completedAngles: [...completedSet], carriedAngles: [...carriedSet] };
   if (typeof availableReviewers !== "number" || !Number.isFinite(availableReviewers)) {
     return { ok: true, dispatch: true, requiredReviewers, availableReviewers: null, shortfall: null, reason: "budget_unknown", verdict, executionMode, ...resume };
   }
@@ -175,13 +192,33 @@ export function reviewerBudgetPreflight(dispatchGroups, availableReviewers, { co
 // finding via the fix loop, a question via never being auto-deferred) — it
 // outranks "medium"/"low", which both eventually defer. "nit" trails last:
 // it defers immediately, with no fixer cycle at all.
-export const SEVERITY_ORDER = ["high", "question", "medium", "low", "nit"];
+export const SEVERITY_ORDER = Object.freeze(["high", "question", "medium", "low", "nit"]);
+
+// The non-defect subset of SEVERITY_ORDER: a "question" is answered (never
+// fixed or deferred like a defect — see deriveDisposition), and a "nit"
+// always defers regardless of any gate's blockCleanOnFindingSeverities
+// config (see isDefaultDeferrableSeverity) — neither belongs in a
+// defect-only blocking vocabulary. Exported as the single source for that
+// partition so a consumer (e.g. config.mjs's BLOCKING_SEVERITY_SPELLINGS
+// vocabulary contract test) derives "defect severities" as
+// SEVERITY_ORDER minus this set, rather than re-hand-listing "question"/"nit".
+// Object.freeze on a Set only locks its OWN properties, not the add/delete
+// methods that mutate its internal collection — freezing is still applied
+// here for consistency with SEVERITY_ORDER and this file's other frozen
+// exports (GATE_CONFIG_KEY, LEGACY_SEVERITY_ALIASES, etc.), and it does stop
+// a caller from attaching a stray own property to the Set object itself.
+export const NON_DEFECT_SEVERITIES = Object.freeze(new Set(["question", "nit"]));
 
 // Marker gate name → gates.<key> config key. Owned here so every caller of
 // resolveFanoutGroups maps the same way; passing the marker name verbatim
 // resolves no groups and silently downgrades pairing enforcement.
 export const GATE_CONFIG_KEY = Object.freeze({ draft_gate: "draft", pre_approval_gate: "preApproval" });
-export const VALID_SEVERITIES = new Set(SEVERITY_ORDER);
+// Object.freeze on a Set only locks its OWN properties, not the add/delete
+// methods that mutate its internal collection — freezing is still applied
+// here for consistency with SEVERITY_ORDER and this file's other frozen
+// exports (GATE_CONFIG_KEY, LEGACY_SEVERITY_ALIASES, etc.), and it does stop
+// a caller from attaching a stray own property to the Set object itself.
+export const VALID_SEVERITIES = Object.freeze(new Set(SEVERITY_ORDER));
 
 // Pre-rename spellings. Old ledgers, markers, and configs still carry them;
 // every read boundary normalizes through this map. Every SANCTIONED producer
@@ -241,6 +278,47 @@ export function severityRank(severity) {
   return idx === -1 ? SEVERITY_ORDER.length : idx;
 }
 
+/**
+ * A zero-initialized severity→count map, one key per SEVERITY_ORDER entry, in
+ * SEVERITY_ORDER's order. The shared starting point every severity tally in
+ * this codebase (consolidateFanin's own `bySeverity`, consolidate-fanin.mjs's
+ * `buildAngleMarker`, reconcile-draft-gate.mjs's no-findings placeholder) used
+ * to hand-roll separately via `Object.fromEntries(SEVERITY_ORDER.map((s) =>
+ * [s, 0]))` — one copy here means a severity added to SEVERITY_ORDER is
+ * zero-initialized everywhere at once.
+ * @returns {Record<string, number>}
+ */
+export function zeroSeverityCounts() {
+  return Object.fromEntries(SEVERITY_ORDER.map((s) => [s, 0]));
+}
+
+/**
+ * Tally `findings` by (normalized) severity into a {@link zeroSeverityCounts}
+ * map. Each finding's severity is normalized through `normalizeSeverity`
+ * before counting, so a legacy spelling still lands on its canonical key. A
+ * finding whose normalized severity is not a recognized SEVERITY_ORDER member
+ * is silently excluded from the tally rather than inflating an unknown key —
+ * every routed call site here counts already-validated findings in practice
+ * (consolidateFanin validates every result's severity before this runs;
+ * buildAngleMarker tallies consolidateFanin's own output), so this guard is a
+ * defensive floor against future drift, not an escape hatch for accepting
+ * unvalidated severities. `findings` and its entries are NOT nullish-tolerant:
+ * a nullish `findings` argument throws (not iterable), and a nullish
+ * individual entry throws reading `.severity` — no routed caller passes
+ * either shape, so a caller that does gets a loud failure instead of a
+ * silently wrong all-zero tally.
+ * @param {Iterable<{severity: unknown}>} findings
+ * @returns {Record<string, number>}
+ */
+export function tallySeverities(findings) {
+  const counts = zeroSeverityCounts();
+  for (const f of findings) {
+    const severity = /** @type {string} */ (normalizeSeverity(f.severity));
+    if (Object.hasOwn(counts, severity)) counts[severity] += 1;
+  }
+  return counts;
+}
+
 /**
  * Merge a severity→count map's legacy-spelled keys into their canonical keys
  * (summing counts) so both the CLI parser and direct programmatic callers of
@@ -457,7 +535,7 @@ function* freshEntries(perAngle) {
     if (typeof entry.carriedFromHead === "string" && entry.carriedFromHead.trim().length > 0) continue;
     const angle = typeof entry.angle === "string" ? entry.angle.trim() : "";
     if (!angle) continue;
-    const group = typeof entry.group === "string" && entry.group.trim().length > 0 ? entry.group.trim() : null;
+    const group = trimmedOrNull(entry.group);
     yield { entry, angle, group };
   }
 }
@@ -665,6 +743,63 @@ export function checkFanoutAngleCoverage(recordedAngles, { mandatoryAngles = [],
  */
 export const FANIN_SYNTHETIC_ANGLES = Object.freeze(["pr-checklist-matrix"]);
 
+/**
+ * Validate a round's RESOLVED angle set — the full angle list the round
+ * targeted, independent of any single gate's configured MANDATORY subset —
+ * against the evidence actually recorded for it: every resolved angle must
+ * have either a per-angle artifact in `recordedAngles` (matched by
+ * {@link baseAngleName} plus a case-insensitive compare — same base+lowercase
+ * rule consolidate-fanin.mjs applies to its own angle keys) or be
+ * named in `carriedAngles` (angle names a caller has already PROVEN carried
+ * forward from a prior clean head — never a bare, unverified name; the
+ * consolidate-fanin CLI's own `--carried-angles` is only ever populated after
+ * its `--carry-forward-plan` proof check, so passing it straight through here
+ * keeps that same guarantee).
+ *
+ * This closes a gap {@link checkFanoutAngleCoverage} leaves open: that check
+ * only protects a CALLER-SUPPLIED mandatory subset, so a wrong carry-forward
+ * declaration naming only NON-mandatory angles under-dispatches with no
+ * mechanical refusal — visible only in the ledger's own carried-angle
+ * provenance (see the Gate Review Sub-Loop Contract's Phase 3 backstop
+ * paragraph). This function protects every resolved angle, not just the
+ * mandatory ones. Pure.
+ *
+ * @param {unknown} resolvedAngles — the round's full resolved angle-name list
+ * @param {object} [evidence]
+ * @param {unknown} [evidence.recordedAngles] — array of `{ angle: string, ... }` entries (per-angle artifacts this round consolidated)
+ * @param {Iterable<string>} [evidence.carriedAngles] — angle names already proven carried forward
+ * @returns {{ missingAngles: string[] }}
+ */
+export function checkResolvedAngleEvidence(resolvedAngles, { recordedAngles, carriedAngles } = {}) {
+  const resolved = Array.isArray(resolvedAngles)
+    ? [...new Set(
+        resolvedAngles
+          .map((a) => (typeof a === "string" ? a.trim() : ""))
+          .filter((a) => a.length > 0),
+      )]
+    : [];
+  const recorded = Array.isArray(recordedAngles)
+    ? recordedAngles
+      .map((e) => (e && typeof e === "object" && typeof e.angle === "string" ? e.angle.trim() : ""))
+      .filter((a) => a.length > 0)
+    : [];
+  // Matched base+lowercase, same as checkFanoutAngleCoverage's callers
+  // (consolidate-fanin's realAngleKeys/exemptCarriedKeys) and
+  // reviewerBudgetPreflight's normalizeAngleKey: per-angle artifacts are
+  // independently authored, so a case difference between a resolved angle
+  // name and its recorded/carried evidence must not read as missing.
+  const normalizeAngleBase = (a) => baseAngleName(a).toLowerCase();
+  const recordedBases = new Set(recorded.map(normalizeAngleBase));
+  const carriedBases = new Set(
+    [...(carriedAngles ?? [])].map((a) => normalizeAngleBase(String(a).trim())),
+  );
+  const missingAngles = resolved.filter((a) => {
+    const base = normalizeAngleBase(a);
+    return !recordedBases.has(base) && !carriedBases.has(base);
+  });
+  return { missingAngles };
+}
+
 /**
  * Default cap on parallel fan-out reviewers when a caller does not supply one.
  * Mirrors the config default (gates.maxFanoutReviewers).
@@ -770,7 +905,6 @@ export function consolidateFanin({ angleResults, blockCleanOnFindingSeverities }
     if (err) malformed.push({ index, reason: err });
   });
 
-  const bySeverity = Object.fromEntries(SEVERITY_ORDER.map((s) => [s, 0]));
   /** @type {Array<{severity: string, angle: string, summary: string, file?: string, line?: number, recommendation?: string, disposition: string}>} */
   const findings = [];
   let blockingCount = 0;
@@ -782,7 +916,6 @@ export function consolidateFanin({ angleResults, blockCleanOnFindingSeverities }
         const severity = /** @type {string} */ (normalizeSeverity(f.severity));
         const isBlocking = blocking.has(severity);
         if (isBlocking) blockingCount += 1;
-        bySeverity[severity] += 1;
         const entry = {
           severity,
           angle,
@@ -810,6 +943,9 @@ export function consolidateFanin({ angleResults, blockCleanOnFindingSeverities }
     verdict = "clean";
   }
 
+  // `findings` already carries each entry's normalized severity, so tallying
+  // it directly (rather than incrementing a running map inside the loop
+  // above) reproduces the same counts via the one shared tally rule.
   return {
     verdict,
     findings,
@@ -817,7 +953,7 @@ export function consolidateFanin({ angleResults, blockCleanOnFindingSeverities }
       angles: results.length,
       findings: findings.length,
       blocking: blockingCount,
-      bySeverity,
+      bySeverity: tallySeverities(findings),
     },
     malformed,
   };
@@ -938,7 +1074,10 @@ export function validateJudgeVerdict(verdict) {
  *
  * Pure. Fails closed (throws) when a disposition references an out-of-range
  * index — a judge verdict that names a finding that is not in the ledger is a
- * mismatch, never a silent enrichment.
+ * mismatch, never a silent enrichment — and when the dispositions do not
+ * cover every finding: an undisposed finding must never be silently dropped
+ * from the fixer's act list. An empty findings array with an empty
+ * dispositions array is vacuously covered and returns without error.
  *
  * @param {Array<object>} findings — the flat consolidated findings array
  * @param {object} judgeVerdict — the validated judge verdict artifact
@@ -953,6 +1092,13 @@ export function applyJudgeDispositions(findings, judgeVerdict) {
       throw new Error(`judge disposition index ${d.index} is out of range (findings has ${enriched.length} entries)`);
     }
     const target = enriched[d.index];
+    // Reset judge-owned fields before the re-merge: a pre-enriched finding
+    // (already-enriched from a prior round, re-disposed by THIS verdict)
+    // must not let stale judgeCriterion/followUpDraft survive a
+    // defer -> act/reject re-disposition — the merged copy carries only
+    // what the current disposition provides, never prior-round residue.
+    delete target.judgeCriterion;
+    delete target.followUpDraft;
     target.judgeDisposition = d.disposition;
     target.judgeRationale = d.rationale;
     if (typeof d.criterion === "string" && d.criterion.trim().length > 0) {
@@ -962,6 +1108,21 @@ export function applyJudgeDispositions(findings, judgeVerdict) {
       target.followUpDraft = d.followUpDraft;
     }
   }
+  // Coverage is judged against THIS verdict's disposed-index set, not field
+  // presence on the merged copy — an already-enriched ledger (a finding that
+  // already carries judgeDisposition from a prior round) must not let a
+  // verdict that disposes nothing pass silently. validateJudgeVerdict already
+  // rejects duplicate indexes, so the Set is exact.
+  const disposed = new Set(validated.dispositions.map((d) => d.index));
+  const uncovered = enriched.reduce((positions, _f, i) => {
+    if (!disposed.has(i)) positions.push(i);
+    return positions;
+  }, /** @type {number[]} */ ([]));
+  if (uncovered.length > 0) {
+    throw new Error(
+      `judge verdict does not dispose ${uncovered.length} finding(s) (indexes: ${uncovered.join(", ")}) — fail closed; an undisposed finding must never be silently dropped from the fixer act list`
+    );
+  }
   return { findings: enriched, scopeDrift: validated.scopeDrift };
 }
 

package/src/loop/handoff-envelope.mjs

@@ -20,6 +20,7 @@ import {
 } from "./public-dev-loop-routing-contract.mjs";
 import { normalizeRepoSlug } from "../github/repo-slug.mjs";
 import { COPILOT_REVIEW_WAIT_TIMEOUT_MS } from "./policy-constants.mjs";
+import { trimmedOrNull } from "./normalize.mjs";
 import { resolveEffectiveAsyncStartMode } from "./async-start-contract.mjs";
 import { resolveGateAngleContract, resolveGateAngles, resolveGateConfig, resolveHumanMergeOnly } from "../config/config.mjs";
 
@@ -222,16 +223,8 @@ function normalizePositiveInt(v) {
   return v;
 }
 
-function normalizeString(v) {
-  return typeof v === "string" && v.trim().length > 0 ? v.trim() : null;
-}
-
-function normalizeStringOrNull(v) {
-  return v === null || v === undefined ? null : normalizeString(v);
-}
-
 function requireString(v, label) {
-  const s = normalizeString(v);
+  const s = trimmedOrNull(v);
   if (s === null) throw new Error(`handoff-envelope: ${label} is required and must be a non-empty string`);
   return s;
 }
@@ -264,12 +257,12 @@ function deriveTarget(bundle, repo) {
     target.pr = pr;
     if (Number.isInteger(artifact.issue) && artifact.issue > 0) target.issue = artifact.issue;
   } else if (kind === DEV_LOOP_TARGET_KIND.LOCAL_BRANCH) {
-    const branch = normalizeString(artifact.branch);
+    const branch = trimmedOrNull(artifact.branch);
     if (!branch) throw new Error("handoff-envelope: local_branch target must include a non-empty branch name");
     target.branch = branch;
     if (Number.isInteger(artifact.issue) && artifact.issue > 0) target.issue = artifact.issue;
   } else if (kind === DEV_LOOP_TARGET_KIND.LOCAL_PHASE) {
-    const phase = normalizeString(artifact.phase);
+    const phase = trimmedOrNull(artifact.phase);
     const validIssue = Number.isInteger(artifact.issue) && artifact.issue > 0;
     if (!phase && !validIssue) {
       throw new Error("handoff-envelope: local_phase target must include a non-empty phase or a valid positive issue number");
@@ -340,8 +333,8 @@ export const CANONICAL_SPEC_SOURCE = Object.freeze({
  * validateHandoffEnvelope would then reject.
  */
 function deriveSpecSource(bundle, resolverOutput) {
-  const raw = normalizeStringOrNull(resolverOutput?.canonicalSpecSource)
-    ?? normalizeStringOrNull(bundle?.canonicalSpecSource);
+  const raw = trimmedOrNull(resolverOutput?.canonicalSpecSource)
+    ?? trimmedOrNull(bundle?.canonicalSpecSource);
   return raw === CANONICAL_SPEC_SOURCE.PHASE_DOC || raw === CANONICAL_SPEC_SOURCE.PR_BODY ? raw : null;
 }
 
@@ -459,7 +452,7 @@ export const WORKTREE_NAMESPACE = "tmp/worktrees/dev-loops";
  * @returns {string} Absolute path `<repoRoot>/tmp/worktrees/dev-loops/<kind>-<number>`
  */
 export function resolveWorktreePath({ repoRoot, kind, number } = {}) {
-  const root = normalizeString(repoRoot);
+  const root = trimmedOrNull(repoRoot);
   if (!root) throw new Error("resolveWorktreePath: repoRoot is required and must be a non-empty string");
   const k = typeof kind === "string" ? kind.trim().toLowerCase() : "";
   if (k !== DEV_LOOP_TARGET_KIND.ISSUE && k !== DEV_LOOP_TARGET_KIND.PR) {
@@ -486,11 +479,11 @@ function buildWorktreeSlug(artifact, kind) {
     return `pr-${artifact.pr}`;
   }
   if (kind === DEV_LOOP_TARGET_KIND.LOCAL_BRANCH) {
-    const branch = normalizeString(artifact.branch);
+    const branch = trimmedOrNull(artifact.branch);
     return branch ? flattenSlugSegment(branch) : null;
   }
   if (kind === DEV_LOOP_TARGET_KIND.LOCAL_PHASE) {
-    const phase = normalizeString(artifact.phase);
+    const phase = trimmedOrNull(artifact.phase);
     const issue = Number.isInteger(artifact.issue) && artifact.issue > 0 ? artifact.issue : null;
     if (phase && issue) return `phase-${issue}-${flattenSlugSegment(phase)}`;
     if (phase) return `phase-${flattenSlugSegment(phase)}`;
@@ -508,11 +501,11 @@ function normalizeGateState(gateState) {
   const gs = gateState ?? {};
 
   return {
-    currentHeadSha: normalizeStringOrNull(gs.currentHeadSha) ?? null,
-    ciStatus: normalizeStringOrNull(gs.ciStatus) ?? null,
+    currentHeadSha: trimmedOrNull(gs.currentHeadSha) ?? null,
+    ciStatus: trimmedOrNull(gs.ciStatus) ?? null,
     unresolvedThreadCount: normalizePositiveInt(gs.unresolvedThreadCount) ?? 0,
     copilotRoundCount: normalizePositiveInt(gs.copilotRoundCount) ?? 0,
-    currentSubGate: normalizeString(gs.currentSubGate) ?? undefined,
+    currentSubGate: trimmedOrNull(gs.currentSubGate) ?? undefined,
   };
 }