@dev-loops/core 0.3.0 → 0.5.0

package/src/loop/pr-gate-coordination.mjs

@@ -119,6 +119,19 @@ function normalizeMergeStateStatus(value) {
   return value.trim().toUpperCase();
 }
 
+function normalizeMergeable(value) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    return null;
+  }
+
+  const upper = value.trim().toUpperCase();
+  if (upper === "MERGEABLE" || upper === "CONFLICTING" || upper === "UNKNOWN") {
+    return upper;
+  }
+
+  return null;
+}
+
 function normalizeConflictFiles(value) {
   if (!Array.isArray(value)) {
     return [];
@@ -142,14 +155,18 @@ function hasBlockedMergeStatus(mergeStateStatus) {
   return mergeStateStatus !== null && BLOCKED_MERGE_STATE_STATUSES.has(mergeStateStatus);
 }
 
-function formatBlockedMergeReason(mergeStateStatus, conflictFiles) {
+function formatBlockedMergeReason(mergeStateStatus, conflictFiles, mergeable = null) {
   if (mergeStateStatus === "BEHIND") {
     let reason = "Branch must be updated from base before entering any gate.";
     reason += ` GitHub mergeStateStatus: ${mergeStateStatus}.`;
     return reason;
   }
 
-  let reason = "The current branch conflicts with the base branch, so resolve the conflict locally on the PR branch, rerun validation, rerun gate detection, and only then resume the normal gate path.";
+  let reason = "The current branch conflicts with the base branch, so resolve the conflict locally on the PR branch (run `node scripts/loop/resolve-pr-conflicts.mjs --push` for the safe additive-CHANGELOG case), rerun validation, rerun gate detection, and only then resume the normal gate path.";
+
+  if (mergeable === "CONFLICTING") {
+    reason += " GitHub mergeable: CONFLICTING.";
+  }
 
   if (mergeStateStatus !== null) {
     reason += ` GitHub mergeStateStatus: ${mergeStateStatus}.`;
@@ -218,7 +235,23 @@ function buildRoundExhaustionGateEvidenceNote({ copilotReviewRoundCount, maxCopi
   return `Copilot review rounds exhausted (${copilotReviewRoundCount}/${maxCopilotRounds}); current head has zero unresolved threads and green or credibly green CI, so pre_approval_gate fallback is allowed without another Copilot re-request.`;
 }
 
-function evaluateRetrospectiveMergeApproval(checkpoint) {
+/**
+ * Render the (user-authored) rawCallViolations array into a bounded, single-line
+ * fragment for the gate failure reason. Collapses whitespace/newlines per entry,
+ * caps per-entry length, and caps the number of entries shown so a large or
+ * garbled checkpoint cannot bloat or break gate output. Still fails closed —
+ * this only formats the reason; the violation count above does the gating.
+ */
+function summarizeRawCallViolations(violations, { maxEntries = 10, maxEntryLen = 200 } = {}) {
+  const shown = violations.slice(0, maxEntries).map((v) => {
+    const flat = String(v).replace(/\s+/g, " ").trim();
+    return flat.length > maxEntryLen ? `${flat.slice(0, maxEntryLen)}…` : flat;
+  });
+  const more = violations.length - shown.length;
+  return more > 0 ? `${shown.join("; ")}; …(+${more} more)` : shown.join("; ");
+}
+
+function evaluateRetrospectiveMergeApproval(checkpoint, { developerMode = false } = {}) {
   if (!checkpoint || typeof checkpoint !== "object") {
     return { approved: false, reason: "No retrospective checkpoint was found." };
   }
@@ -278,6 +311,37 @@ function evaluateRetrospectiveMergeApproval(checkpoint) {
     return { approved: false, reason: "Retrospective is missing explicit `mergeRecommendation`." };
   }
 
+  // internalToolingOnly: the loop's own execution must have used internal dev-loops
+  // tooling only — no agent-level raw `gh`/`python`/`python3`/`node -e` (issue #982).
+  // This is a DEVELOPER-MODE retro step: it enforces the dev-loops maintainers'
+  // own dogfooding discipline and is opt-in via `workflow.requireRetrospectiveInternalTooling`
+  // (default OFF). CONSUMERS of the extension are never blocked by it — they may
+  // legitimately use raw gh/python/node -e in their own workflow — so when the flag
+  // is OFF these fields are neither required nor enforced (a complete checkpoint
+  // without them passes exactly as it did before #982). When ON it fails closed:
+  // a complete checkpoint must explicitly attest a clean tooling record, and an OLD
+  // checkpoint missing `internalToolingOnly` fails (not a silent pass). Re-record the
+  // retrospective with the new fields to clear it.
+  if (developerMode) {
+    const internalToolingOnly = br !== null ? br.internalToolingOnly : checkpoint.internalToolingOnly;
+    if (internalToolingOnly !== true) {
+      return {
+        approved: false,
+        reason: "Retrospective does not attest internal-tooling-only execution (`internalToolingOnly: true` is required in developer mode; agent-level raw gh/python/node -e is a violation). — re-record the retrospective with internalToolingOnly + rawCallViolations.",
+      };
+    }
+    const rawCallViolations = br !== null ? br.rawCallViolations : checkpoint.rawCallViolations;
+    if (!Array.isArray(rawCallViolations)) {
+      return { approved: false, reason: "Retrospective is missing `rawCallViolations` (array; empty when clean). — re-record the retrospective with internalToolingOnly + rawCallViolations." };
+    }
+    if (rawCallViolations.length > 0) {
+      return {
+        approved: false,
+        reason: `Retrospective records ${rawCallViolations.length} raw-call violation(s) (agent-level gh/python/node -e): ${summarizeRawCallViolations(rawCallViolations)}.`,
+      };
+    }
+  }
+
   return { approved: true, reason: null };
 }
 
@@ -610,6 +674,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
     ? "internal_only"
     : (typeof input.reviewMode === "string" ? input.reviewMode.trim().toLowerCase() : null);
   const mergeStateStatus = normalizeMergeStateStatus(input.mergeStateStatus);
+  const mergeable = normalizeMergeable(input.mergeable);
   const conflictFiles = normalizeConflictFiles(input.conflictFiles);
   const ciStatus = normalizeCiStatus(input.ciStatus);
   const draftGateRequireCi = input.draftGateRequireCi !== false;
@@ -617,6 +682,9 @@ function evaluatePrGateCoordinationCore(input = {}) {
   const maxCopilotRounds = normalizePositiveInteger(input.maxCopilotRounds);
   const roundCapReached = maxCopilotRounds !== null && copilotReviewRoundCount >= maxCopilotRounds;
   const requireRetrospectiveGate = input.requireRetrospectiveGate === true;
+  // Developer-mode flag (#982): only the dev-loops repo dogfooding itself enforces the
+  // internal-tooling-only retro discipline. Default OFF so consumer state changes pass.
+  const requireRetrospectiveInternalTooling = input.requireRetrospectiveInternalTooling === true;
   const retrospectiveCheckpoint = input.retrospectiveCheckpoint;
   const prTitle = typeof input.prTitle === "string" ? input.prTitle : "";
   const refinementArtifact = input.refinementArtifact && typeof input.refinementArtifact === "object"
@@ -694,7 +762,44 @@ function evaluatePrGateCoordinationCore(input = {}) {
     });
   }
 
-  if (hasBlockedMergeStatus(mergeStateStatus) || conflictFiles.length > 0) {
+  // Mergeability is a required precondition at every gate (issue #980). GitHub
+  // computes `mergeable` asynchronously, so an unsettled UNKNOWN must fail closed
+  // to a recheck — never a pass. The detect layer already re-polls a bounded
+  // number of times; if it still reads UNKNOWN here, hold gate progression and
+  // recheck rather than guess.
+  if (mergeable === "UNKNOWN") {
+    pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.WAIT_FOR_CI]);
+    pushUnique(forbiddenActions, [
+      PR_CHECKPOINT_ACTION.RUN_DRAFT_GATE,
+      PR_CHECKPOINT_ACTION.RECONCILE_DRAFT_GATE,
+      PR_CHECKPOINT_ACTION.MARK_READY_FOR_REVIEW,
+      PR_CHECKPOINT_ACTION.REQUEST_COPILOT_REVIEW,
+      PR_CHECKPOINT_ACTION.RUN_PRE_APPROVAL_GATE,
+      PR_CHECKPOINT_ACTION.AWAIT_FINAL_HUMAN_APPROVAL,
+      PR_CHECKPOINT_ACTION.DECLARE_MERGE_READY,
+    ]);
+    return buildResult({
+      repo: input.repo ?? null,
+      pr: Number.isInteger(input.pr) ? input.pr : null,
+      currentHeadSha,
+      lifecycleState: effectiveLifecycleState,
+      loopDisposition: DISPOSITION.PENDING,
+      gateBoundary: PR_CHECKPOINT.CONFLICT_RESOLUTION,
+      draftGateAlreadySatisfied,
+      draftGate,
+      preApprovalGate,
+      allowedNextActions,
+      forbiddenActions,
+      nextAction: PR_CHECKPOINT_ACTION.WAIT_FOR_CI,
+      reason: "GitHub has not yet computed mergeability (mergeable=UNKNOWN), so gate progression is held: recheck before proceeding rather than treating an unsettled merge state as clean.",
+      mergeStateStatus,
+      conflictFiles,
+      refinementArtifact,
+      copilotReviewRoundCount,
+    });
+  }
+
+  if (hasBlockedMergeStatus(mergeStateStatus) || mergeable === "CONFLICTING" || conflictFiles.length > 0) {
     pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.RESOLVE_MERGE_CONFLICTS]);
     pushUnique(forbiddenActions, [
       PR_CHECKPOINT_ACTION.RUN_DRAFT_GATE,
@@ -723,7 +828,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
       allowedNextActions,
       forbiddenActions,
       nextAction: PR_CHECKPOINT_ACTION.RESOLVE_MERGE_CONFLICTS,
-      reason: formatBlockedMergeReason(mergeStateStatus, conflictFiles),
+      reason: formatBlockedMergeReason(mergeStateStatus, conflictFiles, mergeable),
       mergeStateStatus,
       conflictFiles,
         refinementArtifact,
@@ -911,7 +1016,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
           });
         }
         if (requireRetrospectiveGate) {
-          const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint);
+          const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint, { developerMode: requireRetrospectiveInternalTooling });
           if (!retrospectiveGate.approved) {
             return buildRetrospectiveGatePendingResult({
               input,
@@ -1183,7 +1288,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         });
       }
       if (requireRetrospectiveGate) {
-        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint);
+        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint, { developerMode: requireRetrospectiveInternalTooling });
         if (!retrospectiveGate.approved) {
           return buildRetrospectiveGatePendingResult({
             input,
@@ -1349,7 +1454,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         });
       }
       if (requireRetrospectiveGate) {
-        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint);
+        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint, { developerMode: requireRetrospectiveInternalTooling });
         if (!retrospectiveGate.approved) {
           return buildRetrospectiveGatePendingResult({
             input,
@@ -1509,7 +1614,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         });
       }
       if (requireRetrospectiveGate) {
-        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint);
+        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint, { developerMode: requireRetrospectiveInternalTooling });
         if (!retrospectiveGate.approved) {
           return buildRetrospectiveGatePendingResult({
             input,

package/src/loop/queue-board-ordering.mjs

@@ -25,7 +25,11 @@ export async function resolveNextUpOrder(
   const listItems = dependencies.listQueueItems ?? listQueueItemsMain;
   try {
     const result = await listItems(
-      { repo, project: projectNumber, column: "Next Up" },
+      // list-queue-items validates `project` as a string ref (CLI contract);
+      // resolveProjectNumber yields a number, so stringify it. Passing the raw
+      // number trips parseProjectRef's `typeof raw !== "string"` guard, which
+      // surfaces as a misleading "--project is required" (#901).
+      { repo, project: String(projectNumber), column: "Next Up" },
       { env, runChild: dependencies.runChild },
     );
     const order = (result?.items ?? [])

package/src/loop/queue-driver.mjs

@@ -57,6 +57,28 @@ export async function runQueue(repoRoot, repo, options = {}) {
   const opts = { ...DEFAULT_QUEUE_DRIVER_OPTIONS, ...options };
   const queue = await readQueue(repoRoot);
 
+  // Data-integrity guard (#913): this driver is a deterministic ADAPTER over the
+  // board, not the orchestration harness. Completion (`done` / move to Done) may
+  // only ever REFLECT a real terminal signal supplied by an orchestrator via
+  // `runEntry` (e.g. a merged PR). With no `runEntry` wired in the current
+  // harness there is nothing that can produce a verifiable terminal state, so
+  // the run MUST be a no-op: leave every entry and board column untouched and
+  // report the reason. Previously the missing-orchestrator path fell back to a
+  // fabricated `{ ok: true, pr: null }` per entry, which silently marked an
+  // entire Next Up `done` and moved it to Done without any work happening.
+  if (typeof opts.runEntry !== "function") {
+    return {
+      ok: true,
+      noop: true,
+      reason: "no-orchestrator",
+      message:
+        "queue run is a deterministic adapter with no orchestrator wired (no runEntry); " +
+        "leaving board columns unchanged. Items move to Done only on a real terminal signal.",
+      results: [],
+      queue,
+    };
+  }
+
   // Config-driven loop-state → board-column mapping (#793, AC1/AC3). Loaded
   // once per run; resolves logical columns to configured display names, with
   // the AC1 defaults when no `queue.statusColumns`/`queue.stateColumnMap` is set.
@@ -135,9 +157,9 @@ export async function runQueue(repoRoot, repo, options = {}) {
     await syncColumn(entry.target, columnFor("implementation"));
 
     try {
-      const entryResult = opts.runEntry
-        ? await opts.runEntry(entry, repo, opts)
-        : { ok: true, pr: null };
+      // runEntry is guaranteed a function here (guarded at function entry):
+      // the adapter never fabricates a terminal result for an undispatched item.
+      const entryResult = await opts.runEntry(entry, repo, opts);
 
       if (entryResult.ok) {
         if (entryResult.pr) {

package/src/loop/run-context.mjs

@@ -1,15 +1,11 @@
 /**
  * Neutral run-id / async-context contract.
  *
- * The dev-loop async path historically keyed off Pi's `PI_SUBAGENT_RUN_ID` env var to
+ * The dev-loop async path keys off the harness-neutral `DEVLOOPS_RUN_ID` env var to
  * identify an inspectable per-subagent run (runner ownership, async-start enforcement,
- * human-comment gating). This module generalizes that into a harness-neutral
- * `DEVLOOPS_RUN_ID`, keeping `PI_SUBAGENT_RUN_ID` as a backward-compatible alias, and
- * provides a mint-and-propagate path for harnesses (e.g. Claude Code) that inject no
- * native per-subagent run id.
- *
- * Marker precedence is neutral-first: a present `DEVLOOPS_RUN_ID` wins; otherwise the Pi
- * alias is honored. Existing Pi runs that set only `PI_SUBAGENT_RUN_ID` behave identically.
+ * human-comment gating), and provides a mint-and-propagate path for harnesses (e.g. Claude
+ * Code) that inject no native per-subagent run id. The harness sets `DEVLOOPS_RUN_ID` when
+ * dispatching an async subagent.
  *
  * This module is pure except for the explicit file/IO helpers (writeRunContext/readRunContext),
  * which take an injectable `fs` and `root` for testability.
@@ -21,16 +17,13 @@ import path from "node:path";
 
 /**
  * Env var names that carry the async-context run id, in resolution precedence order.
- * Neutral `DEVLOOPS_RUN_ID` first; Pi `PI_SUBAGENT_RUN_ID` retained as a compatibility alias.
+ * The neutral `DEVLOOPS_RUN_ID` is the sole marker.
  */
-export const RUN_ID_MARKERS = Object.freeze(["DEVLOOPS_RUN_ID", "PI_SUBAGENT_RUN_ID"]);
+export const RUN_ID_MARKERS = Object.freeze(["DEVLOOPS_RUN_ID"]);
 
 /** Neutral env var name used when minting/propagating a run id. */
 export const NEUTRAL_RUN_ID_VAR = "DEVLOOPS_RUN_ID";
 
-/** Pi-compatibility alias env var name. */
-export const PI_RUN_ID_ALIAS_VAR = "PI_SUBAGENT_RUN_ID";
-
 /** State-file name (under `.pi/`, consistent with existing dev-loop checkpoint files). */
 export const RUN_CONTEXT_FILENAME = "dev-loop-run-context.json";
 
@@ -56,7 +49,7 @@ export function isClaudeHarness(env = process.env) {
 }
 
 /**
- * Resolve the active run id from the environment, neutral marker first.
+ * Resolve the active run id from the environment.
  *
  * @param {Record<string, string|undefined>} [env]
  * @returns {string|null} The trimmed run id, or null when none is set.
@@ -154,8 +147,8 @@ export function readRunContext({ root, fs = fsDefault }) {
  * Resolve the active run id, or mint one and persist a run-context state file.
  *
  * This is the "mint at startup and propagate" primitive a Claude dev-loop agent (or a
- * headless entry) calls before dispatching child work. When the env already carries a run
- * id (Pi alias or neutral), it is reused and no new id is minted.
+ * headless entry) calls before dispatching child work. When the env already carries a
+ * `DEVLOOPS_RUN_ID`, it is reused and no new id is minted.
  *
  * @param {object} [params]
  * @param {Record<string, string|undefined>} [params.env]

package/src/loop/spike-exit-contract.mjs

@@ -0,0 +1,138 @@
+/**
+ * Spike-mode exit (P2 of the spike-mode track #965).
+ *
+ * Phase 1 (#964) shipped the spike intake state machine
+ * (`evaluateSpikeIntakeState` → SPIKE_INTAKE_STATE). A spike becomes exitable
+ * only once it carries a Recommendation (`spike_ready_for_exit`). This module is
+ * the exit decision: from that ready state, the operator picks a disposition —
+ *   - DISCARD  — the recommendation is "don't pursue"; drop the spike with ZERO
+ *                tracker artifacts (the findings doc is the whole record).
+ *   - GRADUATE — promote the exploration into a #947-consumable plan file
+ *                (Status/Objective/In scope/Explicit non-goals) built from the
+ *                spike's Question/Approach/Findings/Recommendation, which then
+ *                enters the existing local-first plan→PR promotion path (#952).
+ *
+ * Pure: no fs/network/gh, no `scripts/` import (mirrors spike-intake-contract
+ * and plan-file-promote-contract). The CLI (`scripts/refine/exit-spike.mjs`)
+ * owns all I/O. Fail-closed on an unknown disposition or a non-ready state so
+ * the CLI makes zero mutation on those paths.
+ */
+
+import { SPIKE_INTAKE_STATE } from "./spike-intake-contract.mjs";
+
+/** Dispositions the operator can choose at a ready spike's exit. */
+export const SPIKE_EXIT_DISPOSITION = Object.freeze({
+  /** Drop the spike with no tracker artifact (recommendation: don't pursue). */
+  DISCARD: "discard",
+  /** Promote into a plan file consumable by the #947 local-first flow. */
+  GRADUATE: "graduate",
+});
+
+/** Actions the exit decision can return (1:1 with the eligible dispositions). */
+export const SPIKE_EXIT_ACTION = Object.freeze({
+  DISCARD: "discard",
+  GRADUATE: "graduate",
+});
+
+const DISPOSITION_TO_ACTION = Object.freeze({
+  [SPIKE_EXIT_DISPOSITION.DISCARD]: SPIKE_EXIT_ACTION.DISCARD,
+  [SPIKE_EXIT_DISPOSITION.GRADUATE]: SPIKE_EXIT_ACTION.GRADUATE,
+});
+
+/**
+ * Pure exit-eligibility decision.
+ *
+ * Eligible ONLY from `spike_ready_for_exit` (a Recommendation has been reached).
+ * Any other state — in-progress or ambiguous — fails closed with
+ * `not_ready_for_exit` and no action; the CLI must make zero tracker mutation.
+ * An unrecognized disposition fails closed with `unknown_disposition`.
+ *
+ * @param {object} facts
+ * @param {string} facts.spikeIntakeState  one of SPIKE_INTAKE_STATE values (from evaluateSpikeIntakeState)
+ * @param {string} facts.disposition  one of SPIKE_EXIT_DISPOSITION values
+ * @returns {{ ok: boolean, action?: string, reason?: string, spikeIntakeState?: string | null }}
+ */
+export function evaluateSpikeExit({ spikeIntakeState, disposition } = {}) {
+  // The ready gate: an exit decision is only meaningful once a recommendation
+  // exists. Fail closed otherwise — never guess an exit for an in-progress or
+  // malformed spike.
+  if (spikeIntakeState !== SPIKE_INTAKE_STATE.SPIKE_READY_FOR_EXIT) {
+    return { ok: false, reason: "not_ready_for_exit", spikeIntakeState: spikeIntakeState ?? null };
+  }
+
+  // Own-property check: a bare index lookup would also match inherited
+  // Object.prototype keys (`toString`, `__proto__`, `constructor`), letting an
+  // unknown disposition resolve to a truthy value and bypass the fail-closed
+  // contract. Require a string that is an own key of the map.
+  if (typeof disposition !== "string" || !Object.hasOwn(DISPOSITION_TO_ACTION, disposition)) {
+    return { ok: false, reason: "unknown_disposition", spikeIntakeState };
+  }
+  const action = DISPOSITION_TO_ACTION[disposition];
+
+  return { ok: true, action, spikeIntakeState };
+}
+
+/**
+ * Build a #947-consumable plan-file body from a ready spike's sections.
+ *
+ * The emitted body carries the four base authoring sections the plan-file
+ * format requires (Status / Objective / In scope / Explicit non-goals — see
+ * scripts/refine/validate-plan-file.mjs), so it passes `validatePlanFile` and
+ * enters the existing local-first plan→PR promotion path (#952) unchanged.
+ *
+ * The spike sections map onto the plan as: the Question + Approach become the
+ * Objective's context, the Recommendation becomes the In-scope work, the
+ * Findings record the evidence, and a fixed non-goal keeps the plan from
+ * re-opening the (now-concluded) exploration. Status starts as Draft.
+ *
+ * Idempotent and pure: same input → identical output, no side effects. Fails
+ * closed (throws) on an empty required section so a graduate exit cannot emit a
+ * plan that the validator would reject.
+ *
+ * @param {object} sections
+ * @param {string} sections.question
+ * @param {string} sections.approach
+ * @param {string} sections.findings
+ * @param {string} sections.recommendation
+ * @returns {string} markdown plan-file body
+ */
+export function buildGraduatedPlanBody({ question, approach, findings, recommendation } = {}) {
+  const q = String(question ?? "").trim();
+  const a = String(approach ?? "").trim();
+  const f = String(findings ?? "").trim();
+  const r = String(recommendation ?? "").trim();
+  if (q.length === 0) throw new Error("buildGraduatedPlanBody requires a non-empty question");
+  if (a.length === 0) throw new Error("buildGraduatedPlanBody requires a non-empty approach");
+  if (f.length === 0) throw new Error("buildGraduatedPlanBody requires non-empty findings");
+  if (r.length === 0) throw new Error("buildGraduatedPlanBody requires a non-empty recommendation");
+
+  return [
+    "# Graduated spike plan",
+    "",
+    "## Status",
+    "",
+    "Draft (graduated from a spike). Needs refinement before promotion.",
+    "",
+    "## Objective",
+    "",
+    `Act on the spike's recommendation. The spike asked: ${q}`,
+    "",
+    "Approach explored:",
+    "",
+    a,
+    "",
+    "## In scope",
+    "",
+    r,
+    "",
+    "Supporting findings from the spike:",
+    "",
+    f,
+    "",
+    "## Explicit non-goals",
+    "",
+    "- Re-running the spike's exploration; that question is concluded.",
+    "- Work beyond the recommendation above.",
+    "",
+  ].join("\n");
+}

package/src/loop/spike-intake-contract.mjs

@@ -0,0 +1,52 @@
+/**
+ * Spike-mode intake state machine.
+ *
+ * A `--spike` startup hands the dev-loop a time-boxed, exploratory artifact that
+ * lives outside the tracker — startable from a local question with no GitHub
+ * issue. A spike is NOT a plan-needing-refinement, so its states are distinct
+ * from PLAN_FILE_INTAKE_STATE: it classifies how far the exploration has
+ * progressed toward an exit decision, not how far a plan has progressed toward
+ * promotion.
+ *
+ * This evaluator mirrors `evaluatePlanFileIntakeState`: a frozen enum plus a
+ * pure, deterministic function with no GitHub or filesystem side effects — the
+ * caller supplies the section-presence facts it has already read.
+ *
+ * The two non-ambiguous states are the seam phase 2 (#965) consumes for its
+ * discard/graduate exits:
+ *   - SPIKE_IN_PROGRESS    — exploration ongoing (no recommendation yet); a
+ *                            discard exit can drop it with no artifact.
+ *   - SPIKE_READY_FOR_EXIT — a recommendation has been reached; phase 2 routes
+ *                            this to graduate (promote into a plan/PR) or
+ *                            discard (recommendation is "don't pursue").
+ */
+
+export const SPIKE_INTAKE_STATE = Object.freeze({
+  /** Valid spike artifact; the Recommendation is not yet reached. */
+  SPIKE_IN_PROGRESS: "spike_in_progress",
+  /** Valid spike artifact carrying a Recommendation; an exit decision can be made. */
+  SPIKE_READY_FOR_EXIT: "spike_ready_for_exit",
+  /** Inputs are malformed or unusable; fail closed. */
+  AMBIGUOUS_FAIL_CLOSED: "ambiguous_fail_closed",
+});
+
+/**
+ * Pure intake-state classifier.
+ *
+ * @param {object} facts
+ * @param {boolean} facts.baseSectionsValid  whether the spike's exploration scaffold (Question/Approach/Findings) is present and non-empty. Recommendation is NOT part of this fact — it is the separate exit-marker carried by `hasRecommendation`, so that a scaffold-valid spike without a Recommendation classifies as in-progress rather than failing closed.
+ * @param {boolean} facts.hasRecommendation  whether a non-empty Recommendation section is present (the exit-marker that flips in-progress → ready-for-exit)
+ * @returns {{ state: string }} one of SPIKE_INTAKE_STATE values
+ */
+export function evaluateSpikeIntakeState({ baseSectionsValid, hasRecommendation } = {}) {
+  // A malformed spike artifact (missing/empty base sections) is unusable intake
+  // input; fail closed instead of guessing an exit.
+  if (baseSectionsValid !== true) {
+    return { state: SPIKE_INTAKE_STATE.AMBIGUOUS_FAIL_CLOSED };
+  }
+  return {
+    state: hasRecommendation === true
+      ? SPIKE_INTAKE_STATE.SPIKE_READY_FOR_EXIT
+      : SPIKE_INTAKE_STATE.SPIKE_IN_PROGRESS,
+  };
+}

package/src/loop/worktree-guard.mjs

@@ -121,32 +121,22 @@ export function isListedWorktree(cwd, worktreePaths) {
  * Neutral environment variable name checked by `detectSubagentAvailability`.
  *
  * Set `DEVLOOPS_SUBAGENT_AVAILABLE=1` when the runtime supports subagent dispatch.
- * This is consistent with the `PI_WORKTREE_BYPASS` pattern and other repo-local
+ * This is consistent with the `DEVLOOPS_WORKTREE_BYPASS` pattern and other repo-local
  * runtime configuration gates already present in the repo.
  */
 export const DEVLOOPS_SUBAGENT_AVAILABLE_VAR = "DEVLOOPS_SUBAGENT_AVAILABLE";
 
-/**
- * Pi-compatibility alias for {@link DEVLOOPS_SUBAGENT_AVAILABLE_VAR}; honored when the
- * neutral var is unset so existing Pi runtimes keep working unchanged.
- */
-export const PI_SUBAGENT_AVAILABLE_VAR = "PI_SUBAGENT_AVAILABLE";
-
-/** Availability env var names, neutral-first. */
-export const SUBAGENT_AVAILABLE_VARS = Object.freeze([
-  DEVLOOPS_SUBAGENT_AVAILABLE_VAR,
-  PI_SUBAGENT_AVAILABLE_VAR,
-]);
+/** Availability env var names. */
+export const SUBAGENT_AVAILABLE_VARS = Object.freeze([DEVLOOPS_SUBAGENT_AVAILABLE_VAR]);
 
 /**
  * Detect whether subagent dispatch is available in the current runtime.
  *
  * This is an env-var-based heuristic, consistent with other bypass/availability
  * patterns in the repo. It is intentionally simple — the gate's subagent check
- * is advisory (fails-open) and never hard-blocks on subagent absence. Precedence is
- * neutral-first: the first var that is *set* (non-blank) is authoritative — so an explicit
- * `DEVLOOPS_SUBAGENT_AVAILABLE=0` is respected even when `PI_SUBAGENT_AVAILABLE=1`. The Pi
- * alias is only consulted when the neutral var is unset/blank.
+ * is advisory (fails-open) and never hard-blocks on subagent absence. The var that is
+ * *set* (non-blank) is authoritative — so an explicit `DEVLOOPS_SUBAGENT_AVAILABLE=0` is
+ * respected as a hard "not available".
  *
  * @param {{ env?: Record<string, string | undefined> }} [options]
  * @returns {boolean}