@dev-loops/core 1.0.2-pre.0 → 1.0.2

package/src/loop/handoff-envelope.mjs

@@ -54,6 +54,16 @@ const STRATEGY_DEFAULT_STOP_RULES = Object.freeze({
   ],
 });
 
+const RECONCILIATION_ACCEPTANCE_TEMPLATE = deepFreeze({
+  criteria: [
+    { id: "reconcile", must: "Resolve the reported authoritative-state conflict before selecting or executing a strategy.", severity: "required" },
+  ],
+  evidence: ["commands-run", "validation-output"],
+  maxFinalizationTurns: 1,
+  needsAttentionAfterMs: DEFAULT_NEEDS_ATTENTION_MS,
+  activeNoticeAfterMs: DEFAULT_ACTIVE_NOTICE_MS,
+});
+
 // ---------------------------------------------------------------------------
 // Acceptance template table
 // ---------------------------------------------------------------------------
@@ -131,7 +141,7 @@ register(INTERNAL_DEV_LOOP_STRATEGY.LOCAL_IMPLEMENTATION, "default", {
   activeNoticeAfterMs: DEFAULT_ACTIVE_NOTICE_MS,
 });
 
-// local_implementation · spike run (SPIKE-RELAXED-GATE-PROFILE, #1628): a
+// local_implementation · spike run (SPIKE-RELAXED-GATE-PROFILE): a
 // spike-mode spin resolves the relaxed `spike` gate profile instead of the
 // default local-implementation gate. Kept as its own acceptance key so the
 // generic default can stay approach-agnostic.
@@ -305,7 +315,7 @@ function deriveRequiredReads(bundle, resolverOutput) {
 }
 
 // ---------------------------------------------------------------------------
-// specSource derivation (issue #1025 — lightweight PR-body-as-spec)
+// specSource derivation — lightweight PR-body-as-spec
 // ---------------------------------------------------------------------------
 
 /**
@@ -440,7 +450,7 @@ function deriveCwd(bundle, options = {}) {
 }
 
 /** Repo-relative root for loop-owned worktrees. The `dev-loops/` namespace */
-/** marks them so cleanup can only ever remove its own (issue #909). */
+/** marks them so cleanup can only ever remove its own. */
 export const WORKTREE_NAMESPACE = "tmp/worktrees/dev-loops";
 
 /**
@@ -470,7 +480,7 @@ function flattenSlugSegment(s) {
 }
 
 function buildWorktreeSlug(artifact, kind) {
-  // Canonical naming is namespaced + no branch suffix (issue #909) so the path
+  // Canonical naming is namespaced + no branch suffix so the path
   // is recomputable from the issue/PR number alone (cleanup can find it).
   if (kind === DEV_LOOP_TARGET_KIND.ISSUE && Number.isInteger(artifact.issue) && artifact.issue > 0) {
     return `issue-${artifact.issue}`;
@@ -511,7 +521,7 @@ function normalizeGateState(gateState) {
 
 
 /**
- * Normalize the structured retrospective findings (issue #1077, Reading B).
+ * Normalize the structured retrospective findings.
  *
  * The retrospective is advisory: it never blocks merge or any lifecycle
  * transition. Its findings travel in the handoff envelope (the conductor's
@@ -553,7 +563,7 @@ function resolveSubGate(strategy, gateState) {
   return "default";
 }
 
-/** True when the resolver output identifies a spike-mode run (#1628). */
+/** True when the resolver output identifies a spike-mode run. */
 function isSpikeRun(resolverOutput) {
   return Boolean(resolverOutput && resolverOutput.spikeIntakeState);
 }
@@ -584,8 +594,45 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
     throw new Error("handoff-envelope: resolverOutput is required and must be an object");
   }
 
-  const bundle = resolverOutput.bundle ?? resolverOutput;
-  const strategy = requireString(bundle.selectedStrategy, "resolverOutput.selectedStrategy");
+  const isWrapped = Object.hasOwn(resolverOutput, "bundle");
+  if (isWrapped && (!resolverOutput.bundle || typeof resolverOutput.bundle !== "object")) {
+    throw new Error("handoff-envelope: resolverOutput.bundle must be an object when present");
+  }
+  const bundle = isWrapped ? resolverOutput.bundle : resolverOutput;
+  const strategy = bundle.selectedStrategy === null
+    ? null
+    : requireString(bundle.selectedStrategy, "resolverOutput.selectedStrategy");
+  const routeKind = strategy === null
+    ? requireString(bundle.routeKind, "resolverOutput.routeKind")
+    : (trimmedOrNull(bundle.routeKind) ?? "route");
+  const selectedGate = trimmedOrNull(bundle.selectedGate);
+  const outerBundleKind = isWrapped ? trimmedOrNull(resolverOutput.bundleKind) : null;
+  const nestedBundleKind = trimmedOrNull(bundle.bundleKind);
+  if (outerBundleKind && nestedBundleKind && outerBundleKind !== nestedBundleKind) {
+    throw new Error(`handoff-envelope: outer bundleKind (${outerBundleKind}) and inner bundleKind (${nestedBundleKind}) must agree`);
+  }
+  const bundleKind = outerBundleKind ?? nestedBundleKind;
+  const isReconciliation = routeKind === "needs_reconcile"
+    && strategy === null
+    && selectedGate === "fail_closed_reconcile"
+    && bundleKind === "needs_reconcile";
+  if (isWrapped && isReconciliation && (
+    resolverOutput.bundleKind !== "needs_reconcile"
+    || bundle.bundleKind !== "needs_reconcile"
+    || resolverOutput.selectedStrategy !== "none"
+    || bundle.selectedStrategy !== null
+  )) {
+    throw new Error("handoff-envelope: wrapped needs_reconcile output requires exact outer and inner bundleKind needs_reconcile markers, outer selectedStrategy none, and inner selectedStrategy null");
+  }
+  if (bundleKind === "needs_reconcile" && !isReconciliation) {
+    throw new Error("handoff-envelope: outer/inner bundleKind needs_reconcile requires inner routeKind needs_reconcile, selectedGate fail_closed_reconcile, and selectedStrategy null");
+  }
+  if (routeKind === "needs_reconcile" && !isReconciliation) {
+    throw new Error("handoff-envelope: routeKind needs_reconcile requires outer bundleKind needs_reconcile, selectedGate fail_closed_reconcile, and selectedStrategy null");
+  }
+  if (strategy === null && !isReconciliation) {
+    throw new Error("handoff-envelope: a null resolverOutput.selectedStrategy is allowed only for the canonical needs_reconcile/fail_closed_reconcile tuple");
+  }
   const executionMode = requireString(bundle.executionMode, "resolverOutput.executionMode");
   const nextAction = requireString(bundle.nextAction, "resolverOutput.nextAction");
 
@@ -593,27 +640,33 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
   if (!repo) throw new Error("handoff-envelope: repo slug is required (owner/name)");
 
   const gs = normalizeGateState(gateState);
-  // SPIKE-RELAXED-GATE-PROFILE (#1628): a spike-mode spin (startup resolver
+  // SPIKE-RELAXED-GATE-PROFILE: a spike-mode spin (startup resolver
   // result carrying `spikeIntakeState`) resolves the relaxed `spike` gate
   // profile instead of the default local-implementation gate. The spike
   // marker lives at the TOP level of the resolver output (the bundle does not
   // carry it), so it is read off `resolverOutput` directly.
-  const subGate = (strategy === INTERNAL_DEV_LOOP_STRATEGY.LOCAL_IMPLEMENTATION && isSpikeRun(resolverOutput))
+  const subGate = isReconciliation
+    ? selectedGate
+    : (strategy === INTERNAL_DEV_LOOP_STRATEGY.LOCAL_IMPLEMENTATION && isSpikeRun(resolverOutput))
     ? "spike"
     : 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).
+  // valid options.retrospectiveFindings fallback.
   const retrospectiveFindings = normalizeRetrospectiveFindings(gateState?.retrospectiveFindings)
     ?? normalizeRetrospectiveFindings(options.retrospectiveFindings);
 
   const target = deriveTarget(bundle, repo);
   const requiredReads = deriveRequiredReads(bundle, resolverOutput);
-  const stopRules = deriveStopRules(settings, strategy);
+  const stopRules = isReconciliation
+    ? ["reconcile", ...(resolveHumanMergeOnly(settings) ? ["merge"] : [])]
+    : deriveStopRules(settings, strategy);
   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
+  const template = isReconciliation
+    ? RECONCILIATION_ACCEPTANCE_TEMPLATE
+    : lookupAcceptanceTemplate(strategy, subGate);
+  // Lightweight PR-body-as-spec: 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);
@@ -623,7 +676,7 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
     ? { ...options.overrides }
     : undefined;
 
-  // Sanctioned operation → wrapper command map (issue #1081). Core is
+  // Sanctioned operation → wrapper command map. 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 —
@@ -632,7 +685,7 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
     ? options.sanctionedCommands
     : undefined;
 
-  // Surface the *effective* async-start posture alongside the *configured* one (#834). The
+  // Surface the *effective* async-start posture alongside the *configured* one. The
   // configured `asyncStartMode` is echoed verbatim from settings (back-compat), but the contract
   // is relaxed at validation time under the Claude harness (resolveEffectiveAsyncStartMode →
   // "allowed" when CLAUDECODE=1). Without surfacing the effective value, a `required` envelope
@@ -650,6 +703,8 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
     maxCopilotRounds: settings?.refinement?.maxCopilotRounds ?? 5,
     executionMode,
 
+    ...(isReconciliation ? { routeKind, selectedStrategy: null } : {}),
+
     nextAction,
     requiredReads,
 
@@ -660,7 +715,7 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
     requireDraftFirst: settings?.workflow?.requireDraftFirst ?? false,
 
     cwd: derivedCwd,
-    worktreeRequired: true,
+    worktreeRequired: !isReconciliation,
 
     acceptance: {
       criteria: acceptanceCriteria,
@@ -686,21 +741,21 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
     envelope.sanctionedCommands = sanctionedCommands;
   }
 
-  // Advisory retrospective findings (issue #1077, Reading B). Optional structured
+  // Advisory retrospective findings. 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
+  // Canonical spec source. 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;
   }
 
-  // #1462: the ONLY per-round-varying block, kept LAST. Every field here changes
+  // The ONLY per-round-varying block, kept LAST. Every field here changes
   // between builds/rounds (the timestamp, the head SHA, CI status, thread/round
   // counts); isolating them as the envelope's tail keeps everything above a
   // byte-stable prefix that a fresh reviewer spawn can cache-READ instead of
@@ -832,6 +887,58 @@ export function validateHandoffEnvelope(envelope) {
     });
   }
 
+  // ----- terminal reconciliation tuple -----
+  // routeKind/selectedStrategy are omitted for ordinary routed envelopes to
+  // preserve the v1 shape. If either is present, both must identify the one
+  // supported no-strategy terminal envelope exactly; serialized/tampered
+  // envelopes receive the same fail-closed enforcement as the builder.
+  const hasRouteKind = Object.hasOwn(envelope, "routeKind");
+  const hasSelectedStrategy = Object.hasOwn(envelope, "selectedStrategy");
+  if (hasRouteKind || hasSelectedStrategy || envelope.currentGate === "fail_closed_reconcile") {
+    const reconciliationStopRulesAreCanonical = Array.isArray(envelope.stopRules)
+      && envelope.stopRules[0] === "reconcile"
+      && (envelope.stopRules.length === 1
+        || (envelope.stopRules.length === 2 && envelope.stopRules[1] === "merge"));
+    // Routing invariants only: acceptance prose remains the resolver's
+    // business, while nextAction must begin with one of the known fail-closed
+    // directives rather than arbitrary non-empty text.
+    const reconciliationCriterion = envelope.acceptance?.criteria;
+    const reconciliationAcceptanceIsCanonical = Array.isArray(reconciliationCriterion)
+      && reconciliationCriterion.some((criterion) => criterion?.id === "reconcile" && criterion?.severity === "required");
+    const normalizedNextAction = typeof envelope.nextAction === "string" ? envelope.nextAction.trim() : "";
+    const reconciliationNextActionIsActionable = [
+      "Reconcile ",
+      "Stop and reconcile ",
+      "Complete or explicitly skip ",
+      "Local implementation requires worktree isolation",
+    ].some((directive) => normalizedNextAction.startsWith(directive));
+    if (
+      envelope.routeKind !== "needs_reconcile"
+      || envelope.selectedStrategy !== null
+      || envelope.currentGate !== "fail_closed_reconcile"
+      || envelope.worktreeRequired !== false
+      || !reconciliationStopRulesAreCanonical
+      || !reconciliationAcceptanceIsCanonical
+      || !reconciliationNextActionIsActionable
+    ) {
+      errors.push({
+        field: "routeKind/selectedStrategy/currentGate/worktreeRequired/stopRules/acceptance.criteria",
+        reason: "terminal reconciliation must use the exact needs_reconcile / null / fail_closed_reconcile tuple, require no worktree, instruct reconciliation, stop at reconcile (plus optional merge), and carry a required reconcile acceptance criterion",
+        got: {
+          routeKind: envelope.routeKind,
+          selectedStrategy: envelope.selectedStrategy,
+          currentGate: envelope.currentGate,
+          worktreeRequired: envelope.worktreeRequired,
+          stopRules: envelope.stopRules,
+          nextAction: envelope.nextAction,
+          acceptanceCriteria: envelope.acceptance?.criteria,
+          acceptanceEvidence: envelope.acceptance?.evidence,
+          maxFinalizationTurns: envelope.acceptance?.maxFinalizationTurns,
+        },
+      });
+    }
+  }
+
   // ----- requiredReads -----
   if (!Array.isArray(envelope.requiredReads)) {
     errors.push({ field: "requiredReads", reason: "must be an array", got: envelope.requiredReads });
@@ -931,7 +1038,7 @@ export function validateHandoffEnvelope(envelope) {
     });
   }
 
-  // ----- asyncStartEffective (required field; the harness-resolved posture, #834) -----
+  // ----- asyncStartEffective (required field; the harness-resolved posture) -----
   if (envelope.asyncStartEffective === undefined || envelope.asyncStartEffective === null) {
     errors.push({
       field: "asyncStartEffective",
@@ -946,7 +1053,7 @@ export function validateHandoffEnvelope(envelope) {
     });
   }
 
-  // ----- retrospectiveFindings (optional, advisory — issue #1077) -----
+  // ----- retrospectiveFindings (optional, advisory) -----
   if (envelope.retrospectiveFindings !== undefined && envelope.retrospectiveFindings !== null) {
     const rf = envelope.retrospectiveFindings;
     if (typeof rf !== "object" || Array.isArray(rf)) {
@@ -968,7 +1075,7 @@ export function validateHandoffEnvelope(envelope) {
     }
   }
 
-  // ----- specSource (optional — issue #1025, lightweight PR-body-as-spec) -----
+  // ----- specSource (optional — 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)) {
@@ -980,8 +1087,8 @@ export function validateHandoffEnvelope(envelope) {
     }
   }
 
-  // ----- gateState.derivedAt (informational, warn on missing) — #1462 moved the
-  // volatile timestamp into the gateState tail so the rest stays byte-stable -----
+  // ----- gateState.derivedAt (informational, warn on missing) — the
+  // volatile timestamp lives in the gateState tail so the rest stays byte-stable -----
   if (typeof envelope.gateState?.derivedAt !== "string" || !envelope.gateState.derivedAt.trim()) {
     warnings.push({ field: "gateState.derivedAt", reason: "should be an ISO 8601 timestamp" });
   }