dev-loops 0.1.0

package/scripts/loop/outer-loop.mjs

@@ -0,0 +1,419 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { buildParseError, formatCliError, parseJsonText } from "../_core-helpers.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import {
+  buildCheckpointFilePath,
+  buildDefaultCheckpointDir,
+} from "./_checkpoint-paths.mjs";
+import { readExistingCheckpoint } from "./_checkpoint-io.mjs";
+import { loadCopilotEvidence, loadReviewerEvidence } from "./_loop-evidence.mjs";
+import {
+  ENTRYPOINT,
+  evaluateConductorRouting,
+  LOOP_FAMILY,
+  ROUTING_OUTCOME,
+  SOURCE_MODE,
+} from "@dev-loops/core/loop/conductor-routing";
+import {
+  ASYNC_START_STATUS,
+  buildAsyncStartRejection,
+  validateAsyncStartContext,
+} from "@dev-loops/core/loop/async-start-contract";
+import { loadDevLoopConfig, resolveConductorModel, resolveAutonomyStopAt, resolveWorkflowConfig } from "@dev-loops/core/config";
+const USAGE = `Usage: outer-loop.mjs --repo <owner/name> --pr <number>
+Thin outer-loop wrapper for the Copilot PR remediation loop.
+Detects current PR state from both the Copilot inner loop and the reviewer
+inner loop, decides the outer-loop action, and persists a minimal checkpoint.
+Required:
+  --repo <owner/name>                   Repository slug (e.g. owner/repo)
+  --pr <number>                         Pull request number
+  --checkpoint-dir <dir>                Directory for checkpoint artifact
+                                        (default: tmp/copilot-loop/<owner>/<repo>/pr-<n>/)
+  --copilot-input <path>                Path to a pre-built copilot snapshot JSON
+                                        (skips live copilot detection; for testing)
+  --reviewer-input <path>               Path to a pre-built reviewer snapshot JSON
+                                        (skips live reviewer detection; for testing)
+Output (stdout, JSON):
+  { "ok": true, "outerAction": "...", "copilotState": "...",
+    "reviewerState": "...", "reviewerScope": { "mode": "...",
+      "reviewerLogin": "..."|null }, "reason"?: "...",
+    "conductorRouting": { "routingOutcome": "...", "outerAction": "...",
+      "stopReason": null|"...", "handoffEnvelope": { ... } },
+    "checkpoint": { "pr": N, "repo": "...", "outerAction": "...",
+      "copilotState": "...", "reviewerState": "...",
+      "reviewerScope": "...", "reviewerLogin": "..."|null,
+      "reason": null|"...", "timestamp": "...", "waitCycles": N,
+      "headSha": "..."|null },
+    "conductorModel": "..."|null }
+Outer actions:
+  continue_wait          Durable outer-loop wait state; re-run after bounded wait
+  reenter_copilot_loop   Copilot inner loop needs action
+  reenter_reviewer_loop  Reviewer inner loop needs action
+  stop                   Terminal, blocked, or reconcile-needed; do not proceed
+  done                   PR is merged or closed; loop complete
+Stop reasons:
+  pr_not_ready                         PR does not exist
+  copilot_blocked                      Copilot loop is blocked
+  reviewer_blocked                     Reviewer loop is blocked
+  review_unavailable                   Copilot review is unavailable
+  unsafe_local_branch_mismatch_requires_reconcile
+                                       Next step needs PR-local work but local
+                                       branch does not match PR head branch
+  unsafe_local_head_mismatch_requires_reconcile
+                                       Next step needs PR-local work but local
+                                       HEAD does not match PR head commit
+  unknown_state                        Unrecognized combined state
+Async-start contract:
+  This loop must run within a visible Pi-managed async context when
+  workflow.asyncStartMode is set to required (default). It fails closed unless
+  PI_SUBAGENT_RUN_ID is set, to prevent hidden detached-process fallback
+  (nohup, disowned shell jobs, etc.). Snapshot/test input mode
+  (both --copilot-input and --reviewer-input) is exempt. Any relaxed
+  async-start posture is maintainer-controlled repository policy, not an
+  agent-tunable runtime path.
+Error output (stderr, JSON):
+  Argument/usage errors:
+    { "ok": false, "error": "...", "usage": "..." }
+  gh/git/runtime failures:
+    { "ok": false, "error": "..." }
+  Async-start contract rejection:
+    { "ok": false, "error": "...", "asyncStartContract": "rejected" }
+Exit codes:
+  0  Success
+  1  Argument error, gh/git failure, or indeterminate state`.trim();
+const parseError = buildParseError(USAGE);
+export function parseOuterLoopCliArgs(argv) {
+  const args = [...argv];
+  const options = {
+    help: false,
+    repo: undefined,
+    pr: undefined,
+    checkpointDir: undefined,
+    copilotInputPath: undefined,
+    reviewerInputPath: undefined,
+  };
+  while (args.length > 0) {
+    const token = args.shift();
+    if (token === "--help" || token === "-h") {
+      options.help = true;
+      return options;
+    }
+    if (token === "--repo") {
+      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+      continue;
+    }
+    if (token === "--pr") {
+      options.pr = parsePrNumber(requireOptionValue(args, "--pr", parseError), parseError);
+      continue;
+    }
+    if (token === "--checkpoint-dir") {
+      options.checkpointDir = requireOptionValue(args, "--checkpoint-dir", parseError);
+      continue;
+    }
+    if (token === "--copilot-input") {
+      options.copilotInputPath = requireOptionValue(args, "--copilot-input", parseError);
+      continue;
+    }
+    if (token === "--reviewer-input") {
+      options.reviewerInputPath = requireOptionValue(args, "--reviewer-input", parseError);
+      continue;
+    }
+    throw parseError(`Unknown argument: ${token}`);
+  }
+  if (!options.help) {
+    if (options.repo === undefined || options.pr === undefined) {
+      throw parseError("outer-loop requires both --repo <owner/name> and --pr <number>");
+    }
+    try {
+      parseRepoSlug(options.repo);
+    } catch (error) {
+      throw parseError(error instanceof Error ? error.message : String(error));
+    }
+  }
+  return options;
+}
+async function checkGitStatus({ env = process.env, gitCommand = "git" } = {}) {
+  const [statusResult, headRefResult, headShaResult] = await Promise.all([
+    runChild(gitCommand, ["status", "--porcelain"], env),
+    runChild(gitCommand, ["rev-parse", "--abbrev-ref", "HEAD"], env),
+    runChild(gitCommand, ["rev-parse", "HEAD"], env),
+  ]);
+  const isDirty = statusResult.code === 0
+    ? statusResult.stdout.trim().length > 0
+    : false;
+  const headRef = headRefResult.code === 0
+    ? headRefResult.stdout.trim()
+    : "";
+  const isDetached = headRef === "HEAD";
+  const branchName = !isDetached && headRef.length > 0 ? headRef : null;
+  const headSha = headShaResult.code === 0
+    ? headShaResult.stdout.trim() || null
+    : null;
+  return { isDirty, isDetached, branchName, headSha };
+}
+async function fetchPrHeadIdentity({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
+  const result = await runChild(
+    ghCommand,
+    ["pr", "view", String(pr), "--repo", repo, "--json", "headRefName,headRefOid"],
+    env,
+  );
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || result.stdout.trim() || `exit code ${result.code}`;
+    throw new Error(`Failed to read PR head identity: ${detail}`);
+  }
+  const payload = parseJsonText(result.stdout);
+  const branchName = typeof payload.headRefName === "string" && payload.headRefName.trim().length > 0
+    ? payload.headRefName.trim()
+    : null;
+  const headSha = typeof payload.headRefOid === "string" && payload.headRefOid.trim().length > 0
+    ? payload.headRefOid.trim()
+    : null;
+  return { branchName, headSha };
+}
+function requiresPrLocalIdentityGate(outerAction) {
+  return outerAction === "reenter_copilot_loop" || outerAction === "reenter_reviewer_loop";
+}
+function evaluatePrLocalIdentity({
+  localBranch,
+  localHeadSha,
+  prBranch,
+  prHeadSha,
+}) {
+  const branchMatches = typeof prBranch === "string" && prBranch.length > 0
+    ? localBranch === prBranch
+    : null;
+  const headMatches = typeof prHeadSha === "string" && prHeadSha.length > 0
+    ? localHeadSha === prHeadSha
+    : null;
+  const mismatchReason = branchMatches === false
+    ? "unsafe_local_branch_mismatch_requires_reconcile"
+    : (headMatches === false ? "unsafe_local_head_mismatch_requires_reconcile" : null);
+  return {
+    localBranch,
+    localHeadSha,
+    prBranch,
+    prHeadSha,
+    branchMatches,
+    headMatches,
+    mismatchReason,
+  };
+}
+function buildPrLocalIdentityStopRouting({
+  repo,
+  pr,
+  branchIdentity,
+}) {
+  const targetIdentity = { repo, pr };
+  const reason = branchIdentity.mismatchReason === "unsafe_local_branch_mismatch_requires_reconcile"
+    ? `Local branch '${branchIdentity.localBranch ?? "(unknown)"}' does not match PR head branch '${branchIdentity.prBranch ?? "(unknown)"}'; reconcile local branch/worktree before PR-local follow-up.`
+    : `Local HEAD '${branchIdentity.localHeadSha ?? "(unknown)"}' does not match PR head '${branchIdentity.prHeadSha ?? "(unknown)"}'; reconcile local branch/worktree before PR-local follow-up.`;
+  return {
+    routingOutcome: ROUTING_OUTCOME.STOP_NEEDS_HUMAN,
+    outerAction: "stop",
+    stopReason: branchIdentity.mismatchReason,
+    handoffEnvelope: {
+      targetIdentity,
+      loopFamily: LOOP_FAMILY.NONE,
+      entrypoint: ENTRYPOINT.NONE,
+      reason,
+      requiredArgs: { repo, pr },
+      requiresLocalIsolation: false,
+      confidence: SOURCE_MODE.LOCAL,
+    },
+  };
+}
+function enrichHandoffWithPrHeadIdentity(routing, { branchName, headSha }) {
+  if (!routing || typeof routing !== "object" || !routing.handoffEnvelope || typeof routing.handoffEnvelope !== "object") {
+    return routing;
+  }
+  const requiredArgs = {
+    ...(routing.handoffEnvelope.requiredArgs && typeof routing.handoffEnvelope.requiredArgs === "object"
+      ? routing.handoffEnvelope.requiredArgs
+      : {}),
+    ...(typeof branchName === "string" && branchName.length > 0 ? { headRefName: branchName } : {}),
+    ...(typeof headSha === "string" && headSha.length > 0 ? { headRefOid: headSha } : {}),
+  };
+  return {
+    ...routing,
+    handoffEnvelope: {
+      ...routing.handoffEnvelope,
+      requiredArgs,
+    },
+  };
+}
+async function writeCheckpoint(checkpointDir, checkpoint) {
+  await mkdir(checkpointDir, { recursive: true });
+  const filePath = buildCheckpointFilePath(checkpointDir);
+  await writeFile(filePath, `${JSON.stringify(checkpoint, null, 2)}\n`, "utf8");
+}
+function shouldCarryForwardWaitCycles(previousCheckpoint, { repo, pr, headSha, outerAction }) {
+  return previousCheckpoint !== null
+    && previousCheckpoint.outerAction === "continue_wait"
+    && outerAction === "continue_wait"
+    && previousCheckpoint.repo === repo
+    && previousCheckpoint.pr === pr
+    && typeof previousCheckpoint.headSha === "string"
+    && previousCheckpoint.headSha.length > 0
+    && typeof headSha === "string"
+    && headSha.length > 0
+    && previousCheckpoint.headSha === headSha;
+}
+export function decideOuterAction({ copilotState, reviewerState, gitStatus }) {
+  const routing = evaluateConductorRouting({
+    target: { repo: "routing/sentinel", pr: 1 },
+    copilotState,
+    reviewerState,
+    requiresLocalIsolation: gitStatus.isDirty || gitStatus.isDetached,
+  });
+  return {
+    outerAction: routing.outerAction,
+    ...(routing.stopReason !== null ? { reason: routing.stopReason } : {}),
+  };
+}
+export async function runOuterLoop(options, { env = process.env, ghCommand = "gh", gitCommand = "git" } = {}) {
+  const { repo, pr, copilotInputPath, reviewerInputPath } = options;
+  const normalizedRepo = repo.trim().toLowerCase();
+  const checkpointDir = options.checkpointDir ?? buildDefaultCheckpointDir(normalizedRepo, pr);
+  const isSnapshotMode = copilotInputPath !== undefined && reviewerInputPath !== undefined;
+  let devLoopConfig = null;
+  if (!isSnapshotMode) {
+    const loaded = await loadDevLoopConfig();
+    if (loaded.errors.length === 0) {
+      devLoopConfig = loaded.config;
+    }
+  }
+  const asyncStartMode = devLoopConfig === null
+    ? "required"
+    : resolveWorkflowConfig(devLoopConfig, "asyncStartMode");
+  const asyncStartValidation = validateAsyncStartContext({ env, isSnapshotMode, asyncStartMode });
+  if (asyncStartValidation.status === ASYNC_START_STATUS.REJECTED) {
+    return buildAsyncStartRejection(asyncStartValidation);
+  }
+  const { snapshot: copilotSnapshot, interpretation: copilotInterpretation } = await loadCopilotEvidence(
+    { repo: normalizedRepo, pr, copilotInputPath },
+    { env, ghCommand },
+  );
+  const { snapshot: reviewerSnapshot, interpretation: reviewerInterpretation } = await loadReviewerEvidence(
+    { repo: normalizedRepo, pr, reviewerInputPath },
+    { env, ghCommand },
+  );
+  const currentHeadSha = typeof reviewerSnapshot?.prHeadSha === "string" && reviewerSnapshot.prHeadSha.length > 0
+    ? reviewerSnapshot.prHeadSha
+    : null;
+  const gitStatus = await checkGitStatus({ env, gitCommand });
+  const sourceMode = (copilotInputPath !== undefined && reviewerInputPath !== undefined)
+    ? "snapshot"
+    : "local";
+  let conductorRouting = evaluateConductorRouting({
+    target: { repo: normalizedRepo, pr },
+    copilotState: copilotInterpretation.state,
+    reviewerState: reviewerInterpretation.state,
+    sourceMode,
+    requiresLocalIsolation: gitStatus.isDirty || gitStatus.isDetached,
+  });
+  let outerAction = conductorRouting.outerAction;
+  let outerReason = conductorRouting.stopReason;
+  let branchIdentity = null;
+  if (outerReason === null && sourceMode === "local" && requiresPrLocalIdentityGate(outerAction)) {
+    const prHeadIdentity = await fetchPrHeadIdentity({ repo: normalizedRepo, pr }, { env, ghCommand });
+    conductorRouting = enrichHandoffWithPrHeadIdentity(conductorRouting, prHeadIdentity);
+    branchIdentity = evaluatePrLocalIdentity({
+      localBranch: gitStatus.branchName,
+      localHeadSha: gitStatus.headSha,
+      prBranch: prHeadIdentity.branchName,
+      prHeadSha: prHeadIdentity.headSha ?? currentHeadSha,
+    });
+    const isolationManagedHandoff = conductorRouting.handoffEnvelope?.requiresLocalIsolation === true;
+    if (branchIdentity.mismatchReason !== null && !isolationManagedHandoff) {
+      outerAction = "stop";
+      outerReason = branchIdentity.mismatchReason;
+      conductorRouting = buildPrLocalIdentityStopRouting({
+        repo: normalizedRepo,
+        pr,
+        branchIdentity,
+      });
+    }
+  }
+  const { checkpoint: prevCheckpoint } = await readExistingCheckpoint(normalizedRepo, pr, {
+    checkpointDir: options.checkpointDir,
+  });
+  const prevWaitCycles = typeof prevCheckpoint?.waitCycles === "number" ? prevCheckpoint.waitCycles : 0;
+  const waitCycles = shouldCarryForwardWaitCycles(prevCheckpoint, {
+    repo: normalizedRepo,
+    pr,
+    headSha: currentHeadSha,
+    outerAction,
+  })
+    ? prevWaitCycles + 1
+    : (outerAction === "continue_wait" ? 1 : 0);
+  const checkpoint = {
+    pr,
+    repo: normalizedRepo,
+    outerAction,
+    copilotState: copilotInterpretation.state,
+    reviewerState: reviewerInterpretation.state,
+    reviewerScope: reviewerSnapshot.reviewerScope,
+    reviewerLogin: reviewerSnapshot.reviewerLogin,
+    reason: outerReason ?? null,
+    timestamp: new Date().toISOString(),
+    waitCycles,
+    headSha: currentHeadSha,
+  };
+  await writeCheckpoint(checkpointDir, checkpoint);
+  let conductorModel = null;
+  let autonomyStopAt = null;
+  if (devLoopConfig !== null) {
+    conductorModel = resolveConductorModel(devLoopConfig);
+    autonomyStopAt = resolveAutonomyStopAt(devLoopConfig);
+  }
+  return {
+    ok: true,
+    outerAction,
+    copilotState: copilotInterpretation.state,
+    reviewerState: reviewerInterpretation.state,
+    reviewerScope: {
+      mode: reviewerSnapshot.reviewerScope,
+      reviewerLogin: reviewerSnapshot.reviewerLogin,
+    },
+    ...(outerReason !== null && outerReason !== undefined ? { reason: outerReason } : {}),
+    ...(branchIdentity !== null ? { branchIdentity } : {}),
+    conductorRouting,
+    checkpoint,
+    conductorModel,
+    autonomyStopAt,
+  };
+}
+export async function runCli(
+  argv = process.argv.slice(2),
+  {
+    stdout = process.stdout,
+    stderr = process.stderr,
+    env = process.env,
+    ghCommand = "gh",
+    gitCommand = "git",
+  } = {},
+) {
+  const options = parseOuterLoopCliArgs(argv);
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return;
+  }
+  const result = await runOuterLoop(options, { env, ghCommand, gitCommand });
+  if (result.ok === false) {
+    stderr.write(`${JSON.stringify(result)}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  stdout.write(`${JSON.stringify(result)}\n`);
+}
+const isDirectRun = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isDirectRun) {
+  runCli().catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  });
+}

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

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { parsePrNumber, requireOptionValue } from "../_cli-primitives.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import {
+  assertRunnerOwnership,
+  claimRunnerOwnership,
+  loadRunnerCoordinationState,
+  releaseRunnerOwnership,
+} from "./_pr-runner-coordination.mjs";
+const USAGE = `Usage:
+  pr-runner-coordination.mjs status --repo <owner/name> --pr <number>
+  pr-runner-coordination.mjs claim --repo <owner/name> --pr <number> [--run-id <id>]
+  pr-runner-coordination.mjs takeover --repo <owner/name> --pr <number> [--run-id <id>]
+  pr-runner-coordination.mjs assert --repo <owner/name> --pr <number> [--run-id <id>] [--require-existing]
+  pr-runner-coordination.mjs release --repo <owner/name> --pr <number> [--run-id <id>]
+Durable one-runner-per-PR coordination helper.
+If --run-id is omitted for claim/assert/release/takeover, PI_SUBAGENT_RUN_ID is used.
+Output:
+  stdout: { "ok": true, ... }
+  stderr: { "ok": false, "error": "...", ... }
+Exit codes:
+  0  Success / clean stop-compatible result
+  1  Argument error or coordination conflict`.trim();
+const parseError = buildParseError(USAGE);
+function parseCliArgs(argv) {
+  const args = [...argv];
+  const options = {
+    help: false,
+    command: null,
+    repo: undefined,
+    pr: undefined,
+    runId: undefined,
+    requireExisting: false,
+  };
+  const command = args.shift();
+  if (command === undefined || command === "--help" || command === "-h") {
+    options.help = true;
+    return options;
+  }
+  options.command = command;
+  while (args.length > 0) {
+    const token = args.shift();
+    if (token === "--help" || token === "-h") {
+      options.help = true;
+      return options;
+    }
+    if (token === "--repo") {
+      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+      continue;
+    }
+    if (token === "--pr") {
+      options.pr = parsePrNumber(requireOptionValue(args, "--pr", parseError), parseError);
+      continue;
+    }
+    if (token === "--run-id") {
+      options.runId = requireOptionValue(args, "--run-id", parseError).trim();
+      continue;
+    }
+    if (token === "--require-existing") {
+      options.requireExisting = true;
+      continue;
+    }
+    throw parseError(`Unknown argument: ${token}`);
+  }
+  const validCommands = new Set(["status", "claim", "takeover", "assert", "release"]);
+  if (!validCommands.has(options.command)) {
+    throw parseError(`Unknown subcommand: ${options.command}`);
+  }
+  if (options.repo === undefined || options.pr === undefined) {
+    throw parseError("pr-runner-coordination requires both --repo <owner/name> and --pr <number>");
+  }
+  try {
+    parseRepoSlug(options.repo);
+  } catch (error) {
+    throw parseError(error instanceof Error ? error.message : String(error));
+  }
+  return options;
+}
+function resolveRunId(explicitRunId, env) {
+  return typeof explicitRunId === "string" && explicitRunId.trim().length > 0
+    ? explicitRunId.trim()
+    : (typeof env?.PI_SUBAGENT_RUN_ID === "string" && env.PI_SUBAGENT_RUN_ID.trim().length > 0
+      ? env.PI_SUBAGENT_RUN_ID.trim()
+      : null);
+}
+export async function runPrRunnerCoordination(options, { env = process.env, cwd = process.cwd() } = {}) {
+  if (options.command === "status") {
+    const { filePath, state } = await loadRunnerCoordinationState({ repo: options.repo, pr: options.pr, cwd });
+    return {
+      ok: true,
+      command: "status",
+      repo: options.repo.trim().toLowerCase(),
+      pr: options.pr,
+      filePath,
+      state,
+    };
+  }
+  const runId = resolveRunId(options.runId, env);
+  if (options.command === "claim") {
+    return claimRunnerOwnership({ repo: options.repo, pr: options.pr, runId, mode: "claim", cwd });
+  }
+  if (options.command === "takeover") {
+    return claimRunnerOwnership({ repo: options.repo, pr: options.pr, runId, mode: "takeover", cwd });
+  }
+  if (options.command === "assert") {
+    return assertRunnerOwnership({
+      repo: options.repo,
+      pr: options.pr,
+      runId,
+      requireExisting: options.requireExisting,
+      cwd,
+    });
+  }
+  if (options.command === "release") {
+    return releaseRunnerOwnership({ repo: options.repo, pr: options.pr, runId, cwd });
+  }
+  throw new Error(`Unhandled runner coordination command: ${options.command}`);
+}
+async function main() {
+  try {
+    const options = parseCliArgs(process.argv.slice(2));
+    if (options.help) {
+      console.log(USAGE);
+      return;
+    }
+    const result = await runPrRunnerCoordination(options, { env: process.env });
+    if (!result.ok) {
+      console.error(JSON.stringify(result));
+      process.exitCode = 1;
+      return;
+    }
+    console.log(JSON.stringify(result));
+  } catch (error) {
+    const payload = formatCliError(error, { usage: USAGE });
+    console.error(JSON.stringify(payload));
+    process.exitCode = 1;
+  }
+}
+if (isDirectCliRun(import.meta.url)) {
+  await main();
+}

package/scripts/loop/pre-commit-branch-guard.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { requireOptionValue, runCommand } from "../_cli-primitives.mjs";
+import {
+  isUnderWorktreePath, parseMainWorktreePath, isMainCheckout,
+} from "@dev-loops/core/loop/worktree-guard";
+
+const USAGE = `Usage:
+  pre-commit-branch-guard.mjs --expected-branch <name> [--require-worktree] [--block-main-checkout]
+
+Verify the current git branch identity and/or worktree isolation before local commit steps.`;
+
+const parseError = buildParseError(USAGE);
+
+export function parseBranchGuardCliArgs(argv) {
+  const args = [...argv];
+  const options = { help: false, expectedBranch: undefined, requireWorktree: false, blockMainCheckout: false };
+  while (args.length > 0) {
+    const token = args.shift();
+    if (token === "--help" || token === "-h") { options.help = true; return options; }
+    if (token === "--expected-branch") { options.expectedBranch = requireOptionValue(args, "--expected-branch", parseError, { flagPattern: /^-/u }); continue; }
+    if (token === "--require-worktree") { options.requireWorktree = true; continue; }
+    if (token === "--block-main-checkout") { options.blockMainCheckout = true; continue; }
+    throw parseError(`Unknown argument: ${token}`);
+  }
+  if (options.expectedBranch === undefined) { throw parseError("--expected-branch <name> is required"); }
+  return options;
+}
+
+export async function runCli(argv = process.argv.slice(2), { stdout = process.stdout, stderr = process.stderr, cwd = process.cwd(), env = process.env, gitCommand = "git" } = {}) {
+  const options = parseBranchGuardCliArgs(argv);
+  if (options.help) { stdout.write(`${USAGE}\n`); return { ok: true, help: true }; }
+
+  const { stdout: branchOutput } = await runCommand(gitCommand, ["branch", "--show-current"], { cwd, env });
+  const currentBranch = branchOutput.trim();
+  if (currentBranch !== options.expectedBranch) {
+    const payload = { ok: false, error: "branch_mismatch", current: currentBranch, expected: options.expectedBranch };
+    stderr.write(`${JSON.stringify(payload)}\n`);
+    return payload;
+  }
+
+  let worktreeOk = null, mainCheckoutBlocked = null;
+  if (options.requireWorktree || options.blockMainCheckout) {
+    let mainWorktreePath = null;
+    if (options.blockMainCheckout) {
+      try { const { stdout: wtOutput } = await runCommand(gitCommand, ["worktree", "list"], { cwd, env }); mainWorktreePath = parseMainWorktreePath(wtOutput); } catch {}
+    }
+    if (options.requireWorktree) {
+      worktreeOk = isUnderWorktreePath(cwd);
+      if (!worktreeOk) { stderr.write(JSON.stringify({ ok: false, error: "not_in_worktree", cwd, requiredPrefix: "tmp/worktrees/" }) + "\n"); return { ok: false, error: "not_in_worktree" }; }
+    }
+    if (options.blockMainCheckout) {
+      const isMain = isMainCheckout(cwd, mainWorktreePath);
+      mainCheckoutBlocked = !(isMain && !isUnderWorktreePath(cwd));
+      if (!mainCheckoutBlocked) { stderr.write(JSON.stringify({ ok: false, error: "main_checkout_blocked", cwd, mainWorktree: mainWorktreePath }) + "\n"); return { ok: false, error: "main_checkout_blocked" }; }
+    }
+    if (!options.requireWorktree) worktreeOk = null;
+    if (!options.blockMainCheckout) mainCheckoutBlocked = null;
+  }
+
+  const payload = { ok: true, branch: currentBranch, matched: true, worktreeOk, mainCheckoutBlocked };
+  stdout.write(`${JSON.stringify(payload)}\n`);
+  return payload;
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().then((result) => { if (result?.ok === false) { process.exitCode = 1; } }).catch((error) => { process.stderr.write(`${formatCliError(error)}\n`); process.exitCode = 1; });
+}