@dev-loops/core 0.6.0 → 0.7.2

package/src/loop/gate-fanin.mjs

@@ -24,6 +24,143 @@
 const VALID_SEVERITIES = new Set(["must-fix", "worth-fixing-now", "defer"]);
 const VALID_VERDICTS = new Set(["clean", "findings_present"]);
 
+/**
+ * Canonical fail-closed signal for when a child/agent cannot perform real
+ * parallel fan-out (e.g. the harness does not honor the subagent tool at child
+ * depth). The flow MUST fail closed with this message and route the gate review
+ * to the conductor rather than silently degrading to a single-agent inline
+ * review (which requireFanoutProvenance is designed to reject). Documented as a
+ * contract in docs/gate-review-sub-loop-contract.md.
+ */
+export const FANOUT_UNAVAILABLE_MESSAGE = "fan-out unavailable — route to conductor";
+
+/**
+ * Build a fail-closed Error carrying the route-to-conductor contract signal.
+ * Callers throw this (or check `.routeToConductor === true`) when real fan-out
+ * cannot be performed. `detail` is appended for diagnostics but the stable,
+ * matchable prefix is always {@link FANOUT_UNAVAILABLE_MESSAGE}.
+ *
+ * @param {string} [detail] — optional diagnostic suffix (e.g. why fan-out failed)
+ * @returns {Error & { routeToConductor: true, code: "FANOUT_UNAVAILABLE" }}
+ */
+export function fanoutUnavailableError(detail) {
+  const suffix = typeof detail === "string" && detail.trim().length > 0 ? ` (${detail.trim()})` : "";
+  const error = new Error(`${FANOUT_UNAVAILABLE_MESSAGE}${suffix}`);
+  return Object.assign(error, { routeToConductor: /** @type {const} */ (true), code: /** @type {const} */ ("FANOUT_UNAVAILABLE") });
+}
+
+/**
+ * Count DISTINCT reviewer identities actually recorded in a `perAngle` array.
+ * An entry contributes an identity via `reviewer` (preferred) or `dispatchId`;
+ * entries carrying neither are not countable reviewers (a bare `{angle}` proves
+ * nothing about who reviewed it). Pure.
+ *
+ * @param {unknown} perAngle
+ * @returns {number}
+ */
+export function countDistinctReviewers(perAngle) {
+  if (!Array.isArray(perAngle)) return 0;
+  const ids = new Set();
+  for (const e of perAngle) {
+    if (!e || typeof e !== "object" || Array.isArray(e)) continue;
+    const id = typeof e.reviewer === "string" && e.reviewer.trim().length > 0
+      ? e.reviewer.trim()
+      : typeof e.dispatchId === "string" && e.dispatchId.trim().length > 0
+        ? e.dispatchId.trim()
+        : null;
+    if (id) ids.add(id);
+  }
+  return ids.size;
+}
+
+/**
+ * Validate INTERNAL CONSISTENCY of a fan-out provenance object. Returns an error
+ * string when the provenance is malformed or self-inconsistent, or null when it
+ * is well-formed and consistent. Shared by the write path (write-gate-findings-log)
+ * and the enforcement read path (buildPreMergeGateCheck) so both agree.
+ *
+ * Consistency rule (documented in docs/gate-review-sub-loop-contract.md):
+ *   - `distinctReviewers` must be a non-negative integer.
+ *   - `perAngle` must be an array, and non-empty when `distinctReviewers > 0`.
+ *   - `distinctReviewers` must be <= the count of DISTINCT reviewer identities
+ *     actually recorded in `perAngle` — you cannot claim more reviewers than you
+ *     recorded dispatch entries for.
+ *
+ * HONEST CAVEAT: this makes recorded provenance internally consistent and raises
+ * the bar, but the provenance is self-reported (written by the same agent whose
+ * independence it claims), so it remains forgeable by a determined single agent.
+ * Un-forgeable recording is the Pi-harness bridge (subagent tool at child depth).
+ *
+ * @param {unknown} prov
+ * @returns {string|null}
+ */
+export function provenanceConsistencyError(prov) {
+  if (!prov || typeof prov !== "object" || Array.isArray(prov)) {
+    return "provenance must be an object";
+  }
+  const p = /** @type {Record<string, unknown>} */ (prov);
+  if (!Number.isInteger(p.distinctReviewers) || /** @type {number} */ (p.distinctReviewers) < 0) {
+    return "provenance.distinctReviewers must be a non-negative integer";
+  }
+  if (!Array.isArray(p.perAngle)) {
+    return "provenance.perAngle must be an array";
+  }
+  const claimed = /** @type {number} */ (p.distinctReviewers);
+  if (claimed > 0 && p.perAngle.length === 0) {
+    return "provenance.perAngle must be non-empty when distinctReviewers > 0";
+  }
+  const recorded = countDistinctReviewers(p.perAngle);
+  if (claimed > recorded) {
+    return `provenance.distinctReviewers (${claimed}) exceeds distinct recorded reviewer identities (${recorded})`;
+  }
+  return null;
+}
+
+/**
+ * Base angle name for a delta-suffixed re-review entry (`<angle>-delta-at-...`,
+ * e.g. `pr-checklist-matrix-delta-at-current-head`): a re-review scoped to only
+ * the current head's delta still counts toward its base angle for both
+ * mandatory-angle coverage and pool-membership checks.
+ *
+ * @param {string} angle
+ * @returns {string}
+ */
+function baseAngleName(angle) {
+  return angle.replace(/-delta-at-.+$/, "");
+}
+
+/**
+ * Validate a recorded fan-out angle list against a gate's configured angle
+ * contract: every mandatory angle must be represented, and — when a pool is
+ * supplied — every recorded angle must be a member of it (delta-suffixed
+ * angles count toward their {@link baseAngleName}). Pure; shared by the write
+ * path (write-gate-findings-log's `provenance.perAngle`, upsert-checkpoint-verdict's
+ * `--findings-json` per-angle results) and the merge-evidence read path
+ * (detect-checkpoint-evidence re-validating the ledger's `provenance.perAngle`)
+ * so all three enforce identically.
+ *
+ * @param {unknown} recordedAngles — array of `{ angle: string, ... }` entries (provenance.perAngle or normalized per-angle findings)
+ * @param {object} [gateAngleContract]
+ * @param {string[]} [gateAngleContract.mandatoryAngles] — angles that must always be represented
+ * @param {string[]|null} [gateAngleContract.pool] — configured angle pool; null/omitted skips the foreign-angle check
+ * @returns {{ missingMandatory: string[], foreignAngles: string[] }}
+ */
+export function checkFanoutAngleCoverage(recordedAngles, { mandatoryAngles = [], pool = null } = {}) {
+  const recorded = Array.isArray(recordedAngles)
+    ? recordedAngles
+      .map((e) => (e && typeof e === "object" && typeof e.angle === "string" ? e.angle.trim() : ""))
+      .filter((a) => a.length > 0)
+    : [];
+  const recordedBases = new Set(recorded.map(baseAngleName));
+  const missingMandatory = mandatoryAngles.filter((a) => !recordedBases.has(a));
+  let foreignAngles = [];
+  if (Array.isArray(pool) && pool.length > 0) {
+    const poolSet = new Set(pool);
+    foreignAngles = [...new Set(recorded.filter((a) => !poolSet.has(baseAngleName(a))))];
+  }
+  return { missingMandatory, foreignAngles };
+}
+
 /**
  * Default cap on parallel fan-out reviewers when a caller does not supply one.
  * Mirrors the config default (gates.maxFanoutReviewers).

package/src/loop/handoff-envelope.mjs

@@ -269,6 +269,55 @@ function deriveRequiredReads(bundle, resolverOutput) {
   return Array.isArray(reads) ? [...reads] : [];
 }
 
+// ---------------------------------------------------------------------------
+// specSource derivation (issue #1025 — lightweight PR-body-as-spec)
+// ---------------------------------------------------------------------------
+
+/**
+ * The LOCAL-FIRST spec-source subset the envelope distinguishes: phase_doc vs
+ * pr_body. This is NOT the full `canonicalSpecSource` value space — the same
+ * field name also carries "tracker_issue" in the tracker-backed mode
+ * (scripts/github/resolve-tracker-local-spec.mjs), which the envelope does not
+ * model (deriveSpecSource coerces it to null).
+ */
+export const CANONICAL_SPEC_SOURCE = Object.freeze({
+  PHASE_DOC: "phase_doc",
+  PR_BODY: "pr_body",
+});
+
+/**
+ * Derive the canonical spec source. Prefer the resolver-output-level field,
+ * fall back to bundle-level (mirrors deriveRequiredReads). Returns null when
+ * absent so the default (phase-doc) path carries no specSource field and stays
+ * byte-identical. Any value outside the local-first subset {phase_doc, pr_body}
+ * — e.g. the tracker-backed "tracker_issue" carried by the same field name — is
+ * coerced to null so the envelope can never set a specSource that
+ * validateHandoffEnvelope would then reject.
+ */
+function deriveSpecSource(bundle, resolverOutput) {
+  const raw = normalizeStringOrNull(resolverOutput?.canonicalSpecSource)
+    ?? normalizeStringOrNull(bundle?.canonicalSpecSource);
+  return raw === CANONICAL_SPEC_SOURCE.PHASE_DOC || raw === CANONICAL_SPEC_SOURCE.PR_BODY ? raw : null;
+}
+
+/**
+ * Apply the spec-source variant to acceptance criteria. Under the lightweight
+ * PR-body-as-spec path the phase-doc criterion text is retargeted to the PR
+ * description; the default (null/phase_doc) path returns the criteria verbatim
+ * so the phase-doc template text stays identical.
+ */
+function applySpecSourceVariant(criteria, specSource) {
+  // ponytail: free-text substring retarget is a no-op for any strategy whose
+  // criteria lack the phase-doc phrase — fine while lightweight only composes
+  // with local_implementation; make it a structured criterion-id lookup if
+  // lightweight is ever extended to another strategy.
+  if (specSource !== CANONICAL_SPEC_SOURCE.PR_BODY) return [...criteria];
+  return criteria.map((c) => ({
+    ...c,
+    must: c.must.replace("from the active phase doc", "from the PR description"),
+  }));
+}
+
 // ---------------------------------------------------------------------------
 // Gate config derivation
 // ---------------------------------------------------------------------------
@@ -412,6 +461,37 @@ function normalizeGateState(gateState) {
   };
 }
 
+
+/**
+ * Normalize the structured retrospective findings (issue #1077, Reading B).
+ *
+ * The retrospective is advisory: it never blocks merge or any lifecycle
+ * transition. Its findings travel in the handoff envelope (the conductor's
+ * decision input) and in an advisory PR comment — never on disk as a gate.
+ *
+ * The source is the `check-retro-tooling.mjs` JSON output shape:
+ *   { ok, internalToolingOnly, rawCallViolations, allowedWriteOps }
+ *
+ * Returns a normalized object carrying the substantive fields, or null when no
+ * findings were supplied (the field is optional — present only when the loop
+ * subagent ran the retrospective tooling).
+ */
+function normalizeRetrospectiveFindings(findings) {
+  if (findings === null || findings === undefined) return null;
+  if (typeof findings !== "object" || Array.isArray(findings)) return null;
+
+  const toStrArray = (v) => Array.isArray(v)
+    ? v.map((x) => (typeof x === "string" ? x : String(x)).trim()).filter((x) => x.length > 0)
+    : [];
+
+  const internalToolingOnly = findings.internalToolingOnly === true;
+  return {
+    internalToolingOnly,
+    rawCallViolations: toStrArray(findings.rawCallViolations),
+    allowedWriteOps: toStrArray(findings.allowedWriteOps),
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Sub-gate resolution
 // ---------------------------------------------------------------------------
@@ -461,6 +541,11 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
 
   const gs = normalizeGateState(gateState);
   const subGate = resolveSubGate(strategy, gs);
+  // Normalize each source independently, then fall back on the normalized result
+  // (not the raw value): a present-but-invalid gateState value must NOT shadow a
+  // valid options.retrospectiveFindings fallback (issue #1077 review finding).
+  const retrospectiveFindings = normalizeRetrospectiveFindings(gateState?.retrospectiveFindings)
+    ?? normalizeRetrospectiveFindings(options.retrospectiveFindings);
 
   const target = deriveTarget(bundle, repo);
   const requiredReads = deriveRequiredReads(bundle, resolverOutput);
@@ -468,11 +553,25 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
   const gateConfig = deriveGateConfig(settings, subGate);
   const derivedCwd = deriveCwd(bundle, { repoRoot: options.repoRoot, worktreeCwd: options.worktreeCwd });
   const template = lookupAcceptanceTemplate(strategy, subGate);
+  // Lightweight PR-body-as-spec (issue #1025): retarget the phase-doc criterion
+  // text to the PR description. Null/phase_doc leaves the criteria untouched, so
+  // the non-lightweight path stays byte-identical.
+  const specSource = deriveSpecSource(bundle, resolverOutput);
+  const acceptanceCriteria = applySpecSourceVariant(template.criteria, specSource);
 
   const overrides = options.overrides && typeof options.overrides === "object" && Object.keys(options.overrides).length > 0
     ? { ...options.overrides }
     : undefined;
 
+  // Sanctioned operation → wrapper command map (issue #1081). Core is
+  // consumer-agnostic: it carries whatever map the consumer supplies (the
+  // `loop build-envelope` CLI injects this repo's scripts/... paths) so every
+  // spawned subagent receives it by DEFAULT. Core defines the SHAPE only —
+  // it never hardcodes repo-specific paths. A non-object is ignored.
+  const sanctionedCommands = options.sanctionedCommands && typeof options.sanctionedCommands === "object" && !Array.isArray(options.sanctionedCommands)
+    ? options.sanctionedCommands
+    : undefined;
+
   // Surface the *effective* async-start posture alongside the *configured* one (#834). The
   // configured `asyncStartMode` is echoed verbatim from settings (back-compat), but the contract
   // is relaxed at validation time under the Claude harness (resolveEffectiveAsyncStartMode →
@@ -509,7 +608,7 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
     worktreeRequired: true,
 
     acceptance: {
-      criteria: [...template.criteria],
+      criteria: acceptanceCriteria,
       evidence: [...template.evidence],
       maxFinalizationTurns: template.maxFinalizationTurns,
     },
@@ -528,11 +627,22 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
     envelope.overrides = overrides;
   }
 
-  // Optional refinement contract (AC/DoD matrix) from the refiner.
-  // Set via options.refinementContract, bundle.refinementContract, or resolverOutput.refinementContract.
-  const refinementContract = options.refinementContract ?? bundle.refinementContract ?? resolverOutput.refinementContract ?? null;
-  if (refinementContract != null) {
-    envelope.refinementContract = refinementContract;
+  if (sanctionedCommands) {
+    envelope.sanctionedCommands = sanctionedCommands;
+  }
+
+  // Advisory retrospective findings (issue #1077, Reading B). Optional structured
+  // field carrying the check-retro-tooling.mjs JSON output to the conductor. Never a
+  // gate — the conductor surfaces these as an advisory PR comment, not a block.
+  if (retrospectiveFindings) {
+    envelope.retrospectiveFindings = retrospectiveFindings;
+  }
+
+  // Canonical spec source (issue #1025). Optional: only set when the resolver
+  // marks a lightweight PR-body-as-spec session, so the default (phase-doc) path
+  // carries no specSource field and its envelope stays byte-identical.
+  if (specSource) {
+    envelope.specSource = specSource;
   }
 
   return deepFreeze(envelope);
@@ -767,79 +877,40 @@ export function validateHandoffEnvelope(envelope) {
     });
   }
 
-  // ----- refinementContract (optional) -----
-  if (envelope.refinementContract !== undefined && envelope.refinementContract !== null) {
-    if (typeof envelope.refinementContract !== "object" || Array.isArray(envelope.refinementContract)) {
+  // ----- retrospectiveFindings (optional, advisory — issue #1077) -----
+  if (envelope.retrospectiveFindings !== undefined && envelope.retrospectiveFindings !== null) {
+    const rf = envelope.retrospectiveFindings;
+    if (typeof rf !== "object" || Array.isArray(rf)) {
       errors.push({
-        field: "refinementContract",
-        reason: "if present, must be a non-array object with schema, items, generatedAt, and isComplete",
-        got: envelope.refinementContract,
+        field: "retrospectiveFindings",
+        reason: "if present, must be a non-array object { internalToolingOnly, rawCallViolations, allowedWriteOps }",
+        got: rf,
       });
     } else {
-      if (envelope.refinementContract.schema !== "ac-dod-matrix/v1") {
-        warnings.push({
-          field: "refinementContract.schema",
-          reason: "expected 'ac-dod-matrix/v1'",
-          got: envelope.refinementContract.schema,
-        });
-      }
-      if (!Array.isArray(envelope.refinementContract.items) || envelope.refinementContract.items.length === 0) {
-        errors.push({
-          field: "refinementContract.items",
-          reason: "must be a non-empty array of AC/DoD matrix items",
-          got: envelope.refinementContract.items,
-        });
-      } else {
-        const bad = [];
-        for (let i = 0; i < envelope.refinementContract.items.length; i++) {
-          const item = envelope.refinementContract.items[i];
-          if (
-            !item || typeof item !== "object" ||
-            typeof item.item !== "string" || !item.item.trim() ||
-            !["AC", "DoD", "Non-goal"].includes(item.type) ||
-            !["Met", "Partial", "Unmet", "Unverified"].includes(item.status) ||
-            typeof item.evidence !== "string" ||
-            typeof item.notes !== "string"
-          ) {
-            bad.push(i);
-          }
-        }
-        if (bad.length > 0) {
-          errors.push({
-            field: "refinementContract.items",
-            reason: `entries at indices [${bad.join(",")}] must have valid item, type, status, evidence, and notes fields`,
-            got: envelope.refinementContract.items,
-          });
-        }
+      if (typeof rf.internalToolingOnly !== "boolean") {
+        errors.push({ field: "retrospectiveFindings.internalToolingOnly", reason: "must be a boolean", got: rf.internalToolingOnly });
       }
-      if (typeof envelope.refinementContract.generatedAt !== "string" || isNaN(Date.parse(envelope.refinementContract.generatedAt))) {
-        errors.push({
-          field: "refinementContract.generatedAt",
-          reason: "must be a valid ISO 8601 timestamp",
-          got: envelope.refinementContract.generatedAt,
-        });
+      if (!Array.isArray(rf.rawCallViolations) || rf.rawCallViolations.some((v) => typeof v !== "string")) {
+        errors.push({ field: "retrospectiveFindings.rawCallViolations", reason: "must be an array of strings", got: rf.rawCallViolations });
       }
-      if (typeof envelope.refinementContract.isComplete !== "boolean") {
-        errors.push({
-          field: "refinementContract.isComplete",
-          reason: "must be a boolean",
-          got: envelope.refinementContract.isComplete,
-        });
-      } else if (envelope.refinementContract.items && Array.isArray(envelope.refinementContract.items)) {
-        const allMet = envelope.refinementContract.items.every(
-          (item) => item && typeof item === "object" && item.status === "Met"
-        );
-        if (envelope.refinementContract.isComplete !== allMet) {
-          errors.push({
-            field: "refinementContract.isComplete",
-            reason: "must match items status (true iff every item has status 'Met')",
-            got: { isComplete: envelope.refinementContract.isComplete, allItemsMet: allMet },
-          });
-        }
+      if (!Array.isArray(rf.allowedWriteOps) || rf.allowedWriteOps.some((v) => typeof v !== "string")) {
+        errors.push({ field: "retrospectiveFindings.allowedWriteOps", reason: "must be an array of strings", got: rf.allowedWriteOps });
       }
     }
   }
 
+  // ----- specSource (optional — issue #1025, lightweight PR-body-as-spec) -----
+  if (envelope.specSource !== undefined && envelope.specSource !== null) {
+    const validSources = [CANONICAL_SPEC_SOURCE.PHASE_DOC, CANONICAL_SPEC_SOURCE.PR_BODY];
+    if (typeof envelope.specSource !== "string" || !validSources.includes(envelope.specSource)) {
+      errors.push({
+        field: "specSource",
+        reason: `if present, must be one of ${validSources.join(", ")}`,
+        got: envelope.specSource,
+      });
+    }
+  }
+
   // ----- derivedAt (informational, warn on missing) -----
   if (typeof envelope.derivedAt !== "string" || !envelope.derivedAt.trim()) {
     warnings.push({ field: "derivedAt", reason: "should be an ISO 8601 timestamp" });
@@ -863,6 +934,7 @@ export {
   deriveCwd,
   deriveRequiredReads,
   normalizeGateState,
+  normalizeRetrospectiveFindings,
   resolveSubGate,
   lookupAcceptanceTemplate,
   buildWorktreeSlug,