dev-loops 0.4.0 → 0.6.0

package/scripts/loop/detect-pr-gate-coordination-state.mjs

@@ -17,6 +17,7 @@ import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { buildSnapshotFromPrFacts, interpretLoopState, summarizeLoopInterpretation } from "@dev-loops/core/loop/copilot-loop-state";
 import { evaluatePrGateCoordination, PR_CHECKPOINT, PR_CHECKPOINT_ACTION } from "@dev-loops/core/loop/pr-gate-coordination";
 import { shouldGuardCopilotReviewRequest } from "@dev-loops/core/loop/pr-gate-coordination";
+import { UI_E2E_CHECK_NAMES } from "@dev-loops/core/loop/ui-e2e-scoping";
 import { fetchGithubReviewThreadsPayload } from "../github/capture-review-threads.mjs";
 import { detectCheckpointEvidence } from "../github/detect-checkpoint-evidence.mjs";
 import { parseArgs } from "node:util";
@@ -163,7 +164,7 @@ async function fetchRequestedReviewers({ repo, pr }, { env = process.env, ghComm
 async function fetchPrFacts({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
   const result = await runChild(
     ghCommand,
-    ["pr", "view", String(pr), "--repo", repo, "--json", "number,state,isDraft,headRefOid,mergeStateStatus,body,title,closingIssuesReferences,reviews,statusCheckRollup"],
+    ["pr", "view", String(pr), "--repo", repo, "--json", "number,state,isDraft,headRefOid,mergeable,mergeStateStatus,body,title,closingIssuesReferences,reviews,statusCheckRollup,files"],
     env,
   );
   if (result.code !== 0) {
@@ -172,6 +173,58 @@ async function fetchPrFacts({ repo, pr }, { env = process.env, ghCommand = "gh"
   }
   return parseJsonText(result.stdout, { label: "gh pr view" });
 }
+
+// GitHub computes `mergeable` asynchronously, so a freshly-pushed head briefly
+// reads `UNKNOWN`. After the initial fetch, re-poll up to `maxPolls` more times
+// while the value stays UNKNOWN (so at most 1 + maxPolls total fetches) before
+// deciding; never treat a transient UNKNOWN as a pass — the caller fails closed
+// to recheck if it never settles. (issue #980)
+export async function fetchPrFactsWithSettledMergeable(
+  options,
+  {
+    env = process.env,
+    ghCommand = "gh",
+    maxPolls = 3,
+    pollDelayMs = 1500,
+    sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+    fetch = fetchPrFacts,
+  } = {},
+) {
+  let prData = await fetch(options, { env, ghCommand });
+  let polls = 0;
+  while (String(prData?.mergeable || "").toUpperCase() === "UNKNOWN" && polls < maxPolls) {
+    polls += 1;
+    await sleep(pollDelayMs);
+    prData = await fetch(options, { env, ghCommand });
+  }
+  return prData;
+}
+// Changed-file paths from `gh pr view --json files` (issue #976). Feeds the
+// path-triggered UI e2e scoping precondition in the evaluator.
+export function extractChangedFiles(prData) {
+  const files = Array.isArray(prData?.files) ? prData.files : [];
+  return files
+    .map((entry) => (typeof entry?.path === "string" ? entry.path : null))
+    .filter((p) => typeof p === "string" && p.length > 0);
+}
+
+// Whether the shared UI e2e suite passed for this head, read deterministically
+// from the statusCheckRollup: every UI e2e check that is present must be
+// SUCCESS. Returns null when no UI e2e check is present in the rollup (unknown
+// → the evaluator fails closed), false if any present UI e2e check is not a
+// success, true if all present ones succeeded.
+export function deriveUiE2ePassed(prData, checkNames = UI_E2E_CHECK_NAMES) {
+  const rollup = Array.isArray(prData?.statusCheckRollup) ? prData.statusCheckRollup : [];
+  const wanted = new Set(checkNames);
+  const present = rollup.filter((entry) => wanted.has(entry?.name) || wanted.has(entry?.context));
+  if (present.length === 0) return null;
+  return present.every((entry) => {
+    const conclusion = String(entry?.conclusion ?? "").toUpperCase();
+    const state = String(entry?.state ?? "").toUpperCase();
+    return conclusion === "SUCCESS" || state === "SUCCESS";
+  });
+}
+
 export function resolveLinkedIssueFromPr(prData) {
   if (!prData || typeof prData !== "object") return null;
   const closing = Array.isArray(prData.closingIssuesReferences) ? prData.closingIssuesReferences : [];
@@ -290,7 +343,7 @@ async function loadRetrospectiveCheckpoint(repoRoot) {
   }
 }
 export async function loadPrGateCoordinationContext(options, runtime = {}) {
-  const prData = await fetchPrFacts(options, runtime);
+  const prData = await fetchPrFactsWithSettledMergeable(options, runtime);
   const currentHeadSha = typeof prData?.headRefOid === "string" && prData.headRefOid.trim().length > 0
     ? prData.headRefOid.trim()
     : null;
@@ -349,6 +402,9 @@ export async function loadPrGateCoordinationContext(options, runtime = {}) {
   const mergeStateStatus = typeof prData?.mergeStateStatus === "string" && prData.mergeStateStatus.trim().length > 0
     ? prData.mergeStateStatus.trim().toUpperCase()
     : null;
+  const mergeable = typeof prData?.mergeable === "string" && prData.mergeable.trim().length > 0
+    ? prData.mergeable.trim().toUpperCase()
+    : null;
   const isDraft = Boolean(prData?.isDraft);
   const isClosed = String(prData?.state || "").toUpperCase() === "CLOSED";
   const isMerged = String(prData?.state || "").toUpperCase() === "MERGED";
@@ -361,6 +417,7 @@ export async function loadPrGateCoordinationContext(options, runtime = {}) {
     pr: options.pr,
     currentHeadSha,
     mergeStateStatus,
+    mergeable,
     conflictFiles,
     prData,
     snapshot,
@@ -396,6 +453,7 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
   const draftGateConfig = resolveGateConfig(config, "draft");
   const maxCopilotRounds = resolveRefinementConfig(config, "maxCopilotRounds");
   const requireRetrospectiveGate = resolveWorkflowConfig(config, "requireRetrospectiveGate");
+  const requireRetrospectiveInternalTooling = resolveWorkflowConfig(config, "requireRetrospectiveInternalTooling");
   const retrospectiveCheckpoint = await loadRetrospectiveCheckpoint(repoRoot);
   const result = evaluatePrGateCoordination({
     repo: context.repo,
@@ -406,7 +464,11 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
     prMerged: String(context.prData?.state || "").toUpperCase() === "MERGED",
     prTitle: context.prData?.title,
     mergeStateStatus: context.mergeStateStatus,
+    mergeable: context.mergeable,
     conflictFiles: context.conflictFiles,
+    // UI e2e auto-scoping (#976): path-triggered + fail-closed precondition.
+    changedFiles: extractChangedFiles(context.prData),
+    uiE2ePassed: deriveUiE2ePassed(context.prData),
     lifecycleState: context.interpretation.state,
     loopDisposition: context.disposition.loopDisposition,
     ciStatus: context.snapshot?.ciStatus ?? null,
@@ -415,6 +477,7 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
     sameHeadCleanConverged: context.interpretation.sameHeadCleanConverged,
     draftGateRequireCi: draftGateConfig.requireCi,
     requireRetrospectiveGate,
+    requireRetrospectiveInternalTooling,
     retrospectiveCheckpoint,
     draftGate: context.gateEvidence.draftGate,
     draftGateMarker: context.gateEvidence.draftGateMarker,

package/scripts/loop/docs-grill-contract.mjs

@@ -0,0 +1,70 @@
+// Bounded docs-grill disposition classifier behind `dev-loop`. Sibling of
+// scripts/loop/slides-story-review-contract.mjs: this one codifies the keep/fix
+// rule for the autonomous docs-grill step (claims vs the actual contracts,
+// code-vs-doc drift, stale references, contract-surface accuracy). Pure module,
+// no I/O. See docs/docs-grill-step.md.
+
+// What each finding asserts is wrong. `drift` covers any divergence between a
+// claim/reference and the contract surface it points at; `stale_reference`
+// covers a link/path/command that no longer resolves; `cosmetic` covers
+// wording-only nits with no behavioral or reference impact.
+export const DOCS_GRILL_FINDING_KINDS = Object.freeze([
+  'drift',
+  'stale_reference',
+  'cosmetic',
+]);
+
+// The bounded disposition the step assigns to each finding.
+export const DOCS_GRILL_DISPOSITIONS = Object.freeze([
+  'record_finding', // real drift between code/behavior and a contract claim — record it
+  'fix_in_place', // doc-only drift the loop can correct on this branch
+  'route_followup', // doc-only drift too large for this branch — route a follow-up
+  'ignore_cosmetic', // wording nit that does not justify a block or a fix here
+]);
+
+/**
+ * Classify one docs-grill finding into its keep/fix disposition.
+ *
+ * The keep/fix rule (docs/docs-grill-step.md):
+ *   - real drift between code/behavior and a contract claim   -> record_finding
+ *   - doc-only drift the loop can correct here                -> fix_in_place
+ *   - doc-only drift too large for this branch                -> route_followup
+ *   - cosmetic wording nit                                    -> ignore_cosmetic
+ *
+ * A coerced/invalid finding returns a structured invalid result rather than
+ * throwing (the module's contract is a structured result, never an exception).
+ *
+ * @param {object} finding
+ * @param {string} finding.kind - one of DOCS_GRILL_FINDING_KINDS
+ * @param {boolean} [finding.docOnly] - true when only docs (no code/behavior) diverge
+ * @param {boolean} [finding.fixableHere] - true when a doc-only fix is small enough for this branch
+ * @returns {{ ok: boolean, disposition?: string, status: string, reason: string, invalid?: string[] }}
+ */
+export function classifyDocsGrillFinding(finding = {}) {
+  if (!finding || typeof finding !== 'object') finding = {};
+  if (!DOCS_GRILL_FINDING_KINDS.includes(finding.kind)) {
+    return {
+      ok: false,
+      status: 'invalid_finding',
+      reason: 'unknown_finding_kind',
+      invalid: ['kind'],
+    };
+  }
+
+  if (finding.kind === 'cosmetic') {
+    return { ok: true, disposition: 'ignore_cosmetic', status: 'classified', reason: 'cosmetic_nit' };
+  }
+
+  // drift | stale_reference against live code/behavior is always recorded; the
+  // reason reflects the kind so downstream filtering stays accurate.
+  if (finding.docOnly !== true) {
+    const reason = finding.kind === 'stale_reference' ? 'stale_reference' : 'real_drift';
+    return { ok: true, disposition: 'record_finding', status: 'classified', reason };
+  }
+
+  // Doc-only drift: fix it here when small, otherwise route a follow-up.
+  if (finding.fixableHere === true) {
+    return { ok: true, disposition: 'fix_in_place', status: 'classified', reason: 'doc_only_fixable_here' };
+  }
+  return { ok: true, disposition: 'route_followup', status: 'classified', reason: 'doc_only_too_large' };
+}

package/scripts/loop/info.mjs

@@ -100,13 +100,32 @@ function formatCiDisplay(ciStatus, ciConclusion) {
   return `CI ${ciStatus}`;
 }
 
+function formatMergeableDisplay(mergeable, mergeStateStatus) {
+  const m = typeof mergeable === "string" ? mergeable.toUpperCase() : null;
+  const s = typeof mergeStateStatus === "string" ? mergeStateStatus.toUpperCase() : null;
+  if (m === "CONFLICTING" || s === "DIRTY" || s === "CONFLICTING") {
+    return `❌ CONFLICTING${s ? ` (${s})` : ""} — resolve before any gate`;
+  }
+  if (s === "BEHIND") {
+    return "⚠️ BEHIND — update branch from base before any gate";
+  }
+  if (m === "UNKNOWN") {
+    return "⏳ UNKNOWN — GitHub still computing; recheck before proceeding";
+  }
+  if (m === "MERGEABLE") {
+    return `✅ MERGEABLE${s ? ` (${s})` : ""}`;
+  }
+  return s || m || "unknown";
+}
+
 function formatPrSummary(prData, handoffResult) {
   const lines = [];
   lines.push(`PR #${prData.number}: ${prData.title}`);
   lines.push(`  Branch: ${formatBranchDisplay(prData.headRefName, prData.baseRefName)}`);
   lines.push(`  State: ${prData.state}${prData.isDraft ? " (draft)" : ""}`);
   lines.push(`  Author: ${prData.author?.login || "unknown"}`);
-  
+  lines.push(`  Mergeable: ${formatMergeableDisplay(prData.mergeable, prData.mergeStateStatus)}`);
+
   if (handoffResult?.snapshot) {
     const s = handoffResult.snapshot;
     if (s.ciStatus !== undefined) {
@@ -189,7 +208,7 @@ function formatIssueSummary(issueData, startupBundle, linkedPrData) {
 }
 
 function buildPrInfo(prNumber, repo, cwd) {
-  const prData = ghJson(["pr", "view", String(prNumber), "--repo", repo, "--json", "number,title,body,state,isDraft,headRefName,baseRefName,author,mergedAt,url,reviewRequests"], cwd);
+  const prData = ghJson(["pr", "view", String(prNumber), "--repo", repo, "--json", "number,title,body,state,isDraft,headRefName,baseRefName,author,mergedAt,mergeable,mergeStateStatus,url,reviewRequests"], cwd);
   
   let handoffResult = null;
   try {

package/scripts/loop/pr-runner-coordination.mjs

@@ -5,6 +5,7 @@ import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helper
 import { parsePrNumber, requireTokenValue } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { resolveRunId as resolveEnvRunId } from "@dev-loops/core/loop/run-context";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 import {
   assertRunnerOwnership,
   claimRunnerOwnership,
@@ -23,6 +24,7 @@ If --run-id is omitted for claim/assert/release/takeover, DEVLOOPS_RUN_ID is use
 Output:
   stdout: { "ok": true, ... }
   stderr: { "ok": false, "error": "...", ... }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success / clean stop-compatible result
   1  Argument error or coordination conflict`.trim();
@@ -36,6 +38,8 @@ function parseCliArgs(argv) {
     pr: undefined,
     runId: undefined,
     requireExisting: false,
+    jq: undefined,
+    silent: false,
   };
   const command = args.shift();
   if (command === undefined || command === "--help" || command === "-h") {
@@ -51,6 +55,7 @@ function parseCliArgs(argv) {
       pr: { type: "string" },
       "run-id": { type: "string" },
       "require-existing": { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -83,6 +88,14 @@ function parseCliArgs(argv) {
       options.requireExisting = true;
       continue;
     }
+    if (token.name === "jq") {
+      options.jq = requireTokenValue(token, parseError);
+      continue;
+    }
+    if (token.name === "silent") {
+      options.silent = true;
+      continue;
+    }
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   const validCommands = new Set(["status", "claim", "takeover", "assert", "release"]);
@@ -146,11 +159,14 @@ async function main() {
     }
     const result = await runPrRunnerCoordination(options, { env: process.env });
     if (!result.ok) {
-      console.error(JSON.stringify(result));
-      process.exitCode = 1;
-      return;
+      // Preserve the established stderr-on-failure contract when not filtering.
+      if (options.jq === undefined && !options.silent) {
+        console.error(JSON.stringify(result));
+        process.exitCode = 1;
+        return;
+      }
     }
-    console.log(JSON.stringify(result));
+    process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent });
   } catch (error) {
     const payload = formatCliError(error, { usage: USAGE });
     console.error(JSON.stringify(payload));

package/scripts/loop/resolve-dev-loop-startup.mjs

@@ -23,18 +23,37 @@ import { detectRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { isCopilotLogin } from "@dev-loops/core/github/copilot-helpers";
 import { loadDevLoopConfig, resolveWorkflowConfig } from "@dev-loops/core/config";
 import { createPiAdapter } from "@dev-loops/core/harness";
+import { validatePlanFile } from "../refine/validate-plan-file.mjs";
+import {
+  validateSpikeExplorationSections,
+  SPIKE_FILE_EXIT_MARKER_SECTION,
+} from "../refine/validate-spike-file.mjs";
+import { extractSection } from "../refine/_refine-helpers.mjs";
+import {
+  evaluatePlanFileIntakeState,
+  PLAN_FILE_REFINEMENT_SECTIONS,
+} from "@dev-loops/core/loop/plan-file-intake-contract";
+import { evaluateSpikeIntakeState } from "@dev-loops/core/loop/spike-intake-contract";
 import { parseArgs } from "node:util";
 const USAGE = `Usage:
   resolve-dev-loop-startup.mjs --issue <number>
   resolve-dev-loop-startup.mjs --pr <number>
   resolve-dev-loop-startup.mjs --input <path>
+  resolve-dev-loop-startup.mjs --plan-file <path>
+  resolve-dev-loop-startup.mjs --spike <path>
 Resolve the authoritative public dev-loop startup/resume bundle.
 Auto-resolves state from GitHub API, git remote, and settings when
 --issue or --pr is used. Use --input for non-standard states.
+Use --plan-file to start local planning from a phase-doc-format plan
+(read-only: no tracker mutation, no issue/PR number).
+Use --spike to start a time-boxed exploratory loop from a local spike
+artifact (read-only: no tracker mutation, no issue/PR number).
 Required (exactly one):
   --issue <n>    Target an issue by number (auto-resolves all state)
   --pr <n>       Target a PR by number (auto-resolves all state)
   --input <path>  Path to a JSON file with canonical-state payload
+  --plan-file <path>  Path to a phase-doc-format plan to start locally
+  --spike <path>  Path to a spike artifact to start a spike loop locally
 Exit codes:
   0  Success
   1  Argument error, runtime failure, or async-start contract rejection`.trim();
@@ -102,6 +121,8 @@ export function parseResolveDevLoopStartupCliArgs(argv) {
     inputPath: undefined,
     issue: undefined,
     pr: undefined,
+    planFile: undefined,
+    spike: undefined,
   };
   const { tokens } = parseArgs({
     args: [...argv],
@@ -110,6 +131,8 @@ export function parseResolveDevLoopStartupCliArgs(argv) {
       input: { type: "string" },
       issue: { type: "string" },
       pr: { type: "string" },
+      "plan-file": { type: "string" },
+      spike: { type: "string" },
     },
     allowPositionals: true,
     strict: false,
@@ -138,14 +161,22 @@ export function parseResolveDevLoopStartupCliArgs(argv) {
       options.pr = parsePositiveInteger(requireTokenValue(token, parseError), "--pr", parseError);
       continue;
     }
+    if (token.name === "plan-file") {
+      options.planFile = requireTokenValue(token, parseError);
+      continue;
+    }
+    if (token.name === "spike") {
+      options.spike = requireTokenValue(token, parseError);
+      continue;
+    }
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
-  const modeCount = [options.inputPath, options.issue, options.pr].filter(v => v !== undefined).length;
+  const modeCount = [options.inputPath, options.issue, options.pr, options.planFile, options.spike].filter(v => v !== undefined).length;
   if (modeCount > 1) {
-    throw parseError("--issue, --pr, and --input are mutually exclusive; provide exactly one");
+    throw parseError("--issue, --pr, --input, --plan-file, and --spike are mutually exclusive; provide exactly one");
   }
   if (modeCount === 0) {
-    throw parseError("--input <path>, --issue <n>, or --pr <n> is required");
+    throw parseError("--input <path>, --issue <n>, --pr <n>, --plan-file <path>, or --spike <path> is required");
   }
   return options;
 }
@@ -368,6 +399,118 @@ export function buildAutoResolvedInput({ issue, pr, cwd, targetPreference, input
     },
   };
 }
+/**
+ * Read + validate a `--plan-file` path and build a local_phase startup input.
+ *
+ * Read-only: no tracker mutation, no GitHub calls, no issue/PR number. A
+ * missing/unreadable file, or one failing the base-section validator, throws so
+ * the CLI fails closed (exit 1, no readiness bundle). The plan-file path is
+ * carried as the target `phase` and is exempt from the worktree-isolation guard
+ * because there is no issue to key a worktree on before promotion.
+ *
+ * @returns {object} startup input with a `planFileIntakeState` field threaded onto output
+ */
+export function buildPlanFileInput({ planFilePath }) {
+  const resolvedPath = path.resolve(planFilePath);
+  let markdownText;
+  try {
+    markdownText = readFileSync(resolvedPath, "utf8");
+  } catch (err) {
+    throw new Error(`Plan file is missing or unreadable: ${resolvedPath} (${err instanceof Error ? err.message : String(err)})`);
+  }
+  const validation = validatePlanFile(markdownText);
+  if (!validation.ok) {
+    const codes = validation.errors.map(e => e.code).join(", ");
+    throw new Error(`Plan file failed validation (${resolvedPath}): ${codes}`);
+  }
+  // Refined-vs-needs-refinement: refinement adds Acceptance criteria + Definition
+  // of done on top of the base authoring sections. Detect each via extractSection
+  // (non-null trimmed body == present and non-empty), then classify with the pure
+  // intake evaluator.
+  const [acHeading, dodHeading] = PLAN_FILE_REFINEMENT_SECTIONS;
+  const hasAcceptanceCriteria = extractSection(markdownText, acHeading) ? true : false;
+  const hasDefinitionOfDone = extractSection(markdownText, dodHeading) ? true : false;
+  const { state: planFileIntakeState } = evaluatePlanFileIntakeState({
+    baseSectionsValid: true,
+    hasAcceptanceCriteria,
+    hasDefinitionOfDone,
+  });
+  return {
+    intent: "start_issue_locally",
+    mode: "bounded_handoff",
+    targetPreference: "prefer_local",
+    artifactState: "not_applicable",
+    issueLinkageResolution: "not_applicable",
+    issueReadiness: "not_applicable",
+    issueAssignmentState: "not_applicable",
+    loopState: "implementation_pending",
+    planFileIntakeState,
+    planFileExempt: true,
+    currentState: {
+      target: { kind: "local_phase", issue: null, pr: null, linkedPr: null, branch: null, phase: resolvedPath },
+      ownership: "local",
+      nextActor: "local",
+      status: "active",
+      authorization: "authorized",
+    },
+  };
+}
+/**
+ * Read + validate a `--spike` path and build a local_phase startup input for a
+ * time-boxed exploratory loop.
+ *
+ * Read-only: no tracker mutation, no GitHub calls, no issue/PR number — a spike
+ * is startable from a local question with no GitHub issue and no production-gate
+ * ceremony at entry. A missing/unreadable file, or one missing the exploration
+ * scaffold (Question/Approach/Findings), throws so the CLI fails closed (exit 1,
+ * no readiness bundle). The Recommendation section is filled in during the spike;
+ * its presence flips the intake state to spike_ready_for_exit (the seam phase 2's
+ * discard/graduate exits consume). The spike path is carried as the target
+ * `phase` and is exempt from the worktree-isolation guard because there is no
+ * issue to key a worktree on.
+ *
+ * @returns {object} startup input with a `spikeIntakeState` field threaded onto output
+ */
+export function buildSpikeInput({ spikeFilePath }) {
+  const resolvedPath = path.resolve(spikeFilePath);
+  let markdownText;
+  try {
+    markdownText = readFileSync(resolvedPath, "utf8");
+  } catch (err) {
+    throw new Error(`Spike file is missing or unreadable: ${resolvedPath} (${err instanceof Error ? err.message : String(err)})`);
+  }
+  // Entry gate: the exploration scaffold must be present and non-empty. A
+  // malformed spike artifact fails closed before any intake classification.
+  const validation = validateSpikeExplorationSections(markdownText);
+  if (!validation.ok) {
+    const codes = validation.errors.map(e => e.code).join(", ");
+    throw new Error(`Spike file failed validation (${resolvedPath}): ${codes}`);
+  }
+  const hasRecommendation = extractSection(markdownText, SPIKE_FILE_EXIT_MARKER_SECTION) ? true : false;
+  const { state: spikeIntakeState } = evaluateSpikeIntakeState({
+    baseSectionsValid: true,
+    hasRecommendation,
+  });
+  return {
+    intent: "start_issue_locally",
+    mode: "bounded_handoff",
+    targetPreference: "prefer_local",
+    artifactState: "not_applicable",
+    issueLinkageResolution: "not_applicable",
+    issueReadiness: "not_applicable",
+    issueAssignmentState: "not_applicable",
+    loopState: "implementation_pending",
+    spikeIntakeState,
+    planFileExempt: true,
+    currentState: {
+      target: { kind: "local_phase", issue: null, pr: null, linkedPr: null, branch: null, phase: resolvedPath },
+      ownership: "local",
+      nextActor: "local",
+      status: "active",
+      authorization: "authorized",
+    },
+  };
+}
 export function summarizeCanonicalState(bundle) {
   return {
     target: bundle.canonicalState?.target ?? null,
@@ -390,6 +533,16 @@ export function summarizeCanonicalState(bundle) {
 export function buildResolveDevLoopStartupResult(input, { adapter = createPiAdapter(), env, cwd, asyncStartMode = "required" } = {}) {
   const effectiveEnv = env ?? adapter.getEnv();
   const effectiveCwd = cwd ?? adapter.getCwd();
+  // Normalize a non-object input (e.g. `--input null`, which parses to a legal
+  // JSON null) to {} so the destructure below cannot throw before routing can
+  // fail closed with a structured reconcile bundle.
+  if (input === null || typeof input !== "object") input = {};
+  // Plan-file intake carries two resolver-only fields that the pure routing
+  // evaluator does not model. Strip them before evaluation and re-apply them to
+  // the result; `planFileExempt` waives the worktree-isolation guard because a
+  // pre-promotion plan has no issue to key a worktree on.
+  const { planFileExempt = false, planFileIntakeState = null, spikeIntakeState = null, ...routingInput } = input;
+  input = routingInput;
   try {
     const checkpointText = readFileSync(
       path.join(effectiveCwd, ".pi", "dev-loop-retrospective-checkpoint.json"),
@@ -440,6 +593,7 @@ export function buildResolveDevLoopStartupResult(input, { adapter = createPiAdap
   const DEVLOOPS_WORKTREE_BYPASS_VAR = "DEVLOOPS_WORKTREE_BYPASS";
   if (
     strategyKey === "local_implementation" &&
+    !planFileExempt &&
     (effectiveEnv[DEVLOOPS_WORKTREE_BYPASS_VAR] ?? "").trim() !== "1"
   ) {
     try {
@@ -496,6 +650,8 @@ export function buildResolveDevLoopStartupResult(input, { adapter = createPiAdap
     requiredReads: STRATEGY_REQUIRED_READS[strategyKey],
     nextAction: bundle.nextAction,
     canonicalStateSummary: summarizeCanonicalState(bundle),
+    ...(planFileIntakeState !== null ? { planFileIntakeState } : {}),
+    ...(spikeIntakeState !== null ? { spikeIntakeState } : {}),
     bundle,
   };
 }
@@ -521,9 +677,24 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
     ? normalizeConfigInputSource(devLoopConfig?.inputSource?.default)
     : "tracker";
   let input;
-  if (options.inputPath !== undefined) {
+  if (options.spike !== undefined) {
+    input = buildSpikeInput({ spikeFilePath: options.spike });
+  } else if (options.planFile !== undefined) {
+    input = buildPlanFileInput({ planFilePath: options.planFile });
+  } else if (options.inputPath !== undefined) {
     const text = await readFile(path.resolve(options.inputPath), "utf8");
-    input = parseJsonText(text);
+    const parsed = parseJsonText(text);
+    // `--input` is untrusted external JSON. Strip the resolver-only intake fields
+    // so it cannot inject them — `planFileExempt` would otherwise waive the
+    // worktree-isolation guard for a normal local_implementation, and the intake
+    // state is owned by the internal plan-file path (buildPlanFileInput), not the
+    // caller.
+    if (parsed && typeof parsed === "object") {
+      delete parsed.planFileExempt;
+      delete parsed.planFileIntakeState;
+      delete parsed.spikeIntakeState;
+    }
+    input = parsed;
   } else if (options.issue !== undefined) {
     input = buildAutoResolvedInput({
       issue: options.issue,