dev-loops 0.1.0

package/scripts/github/verify-fresh-review-context.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { buildParseError, isDirectCliRun, formatCliError } from "../_core-helpers.mjs";
+const USAGE = `Usage: verify-fresh-review-context.mjs [--help] [--scope <name>]
+Verify that the current subagent session has fresh context.
+Options:
+  --scope <name>  Unique reviewer scope (e.g. "draft-gate-coverage").
+                  Must be non-empty, containing only alphanumeric
+                  characters and hyphens. When provided, the sentinel
+                  is scoped so parallel reviewers in the same working
+                  directory do not trigger false contamination.
+Output (stdout, JSON):
+  { "ok": true, "fresh": true, "sentinelCreated": true }
+  { "ok": true, "fresh": false, "sentinelCreated": false, "reason": "..." }
+  On error (stderr, JSON):
+  { "ok": false, "error": "...", "usage": "..." }
+Exit codes:
+  0  Clean (first run)
+  1  Contaminated (prior session detected)
+  2  Usage or internal error`.trim();
+const VALID_SCOPE_RE = /^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/;
+const parseError = buildParseError(USAGE);
+function resolveScope(argv) {
+  const idx = argv.indexOf("--scope");
+  if (idx === -1) return null;
+  const val = argv[idx + 1];
+  if (val === undefined || val === "" || (val.length > 0 && val[0] === "-")) {
+    return ""; // provided but missing/empty/flag-like
+  }
+  return val;
+}
+function resolveValidatedScope(argv) {
+  const raw = resolveScope(argv);
+  if (raw === null) return null;
+  if (raw === "" || !VALID_SCOPE_RE.test(raw)) {
+    process.stderr.write(`${formatCliError(
+      parseError(`Invalid --scope value "${raw}": must be non-empty and contain only alphanumeric characters and hyphens.`)
+    )}\n`);
+    return undefined; // signals invalid
+  }
+  return raw;
+}
+function sentinelRelative(scope) {
+  const suffix = scope ? `-${scope}` : "";
+  return path.join("tmp", `checkpoint-context-sentinel${suffix}.json`);
+}
+function legacySentinelRelative(scope) {
+  const suffix = scope ? `-${scope}` : "";
+  return path.join("tmp", `gate-review-context-sentinel${suffix}.json`);
+}
+async function checkSentinelExists(scope, cwd = process.cwd()) {
+  const sentinelPath = path.resolve(cwd, sentinelRelative(scope));
+  try { await stat(sentinelPath); return { exists: true, path: sentinelPath, legacy: false }; } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+  const legacyPath = path.resolve(cwd, legacySentinelRelative(scope));
+  try { await stat(legacyPath); return { exists: true, path: legacyPath, legacy: true }; } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+  return { exists: false, path: sentinelPath, legacy: false };
+}
+async function main(argv = process.argv.slice(2)) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  const scope = resolveValidatedScope(argv);
+  if (scope === undefined) return 2;
+  const sentinelPath = path.resolve(process.cwd(), sentinelRelative(scope));
+  try {
+    await mkdir(path.dirname(sentinelPath), { recursive: true });
+  } catch (err) {
+    process.stderr.write(`${formatCliError(err)}\n`);
+    return 2;
+  }
+  const existing = await checkSentinelExists(scope);
+  if (existing.exists) {
+    process.stdout.write(JSON.stringify({
+      ok: true,
+      fresh: false,
+      sentinelCreated: false,
+      reason: `Checkpoint context sentinel already exists${existing.legacy ? " (legacy name)" : ""} — inherited session context detected. Restart the subagent with fresh context (subagent({context:\"fresh\"})).`,
+    }) + "\n");
+    return 1;
+  }
+  const sentinel = {
+    createdAt: new Date().toISOString(),
+    pid: process.pid,
+    ...(scope ? { scope } : {}),
+  };
+  try {
+    await writeFile(sentinelPath, JSON.stringify(sentinel, null, 2) + "\n", {
+      encoding: "utf8",
+      flag: "wx",
+    });
+  } catch (err) {
+    if (err.code === "EEXIST") {
+      process.stdout.write(JSON.stringify({
+        ok: true,
+        fresh: false,
+        sentinelCreated: false,
+        reason: "Checkpoint context sentinel already exists (detected on atomic create) — inherited session context detected. Restart the subagent with fresh context (subagent({context:\"fresh\"})).",
+      }) + "\n");
+      return 1;
+    }
+    process.stderr.write(`${formatCliError(err)}\n`);
+    return 2;
+  }
+  process.stdout.write(JSON.stringify({
+    ok: true,
+    fresh: true,
+    sentinelCreated: true,
+  }) + "\n");
+  return 0;
+}
+if (isDirectCliRun(import.meta.url)) {
+  try {
+    const exitCode = await main();
+    process.exitCode = exitCode;
+  } catch (err) {
+    process.stderr.write(`${formatCliError(err)}\n`);
+    process.exitCode = 2;
+  }
+}

package/scripts/github/write-gate-findings-log.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parsePrNumber, requireOptionValue } from "../_cli-primitives.mjs";
+import { formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+const USAGE = `Usage: write-gate-findings-log.mjs --repo <owner/name> --pr <number> --gate <draft_gate|pre_approval_gate> --head-sha <sha> --verdict <clean|findings_present|blocked> --findings <json> [--tmp-root <path>]
+Write a durable <gate>-<headSha>.json log under deterministic tmp/ paths.
+Required:
+  --repo <owner/name>
+  --pr <number>
+  --gate <draft_gate|pre_approval_gate>
+  --head-sha <sha>
+  --verdict <clean|findings_present|blocked>
+  --findings <json>              JSON array of finding objects with severity, disposition, angle, and summary
+Optional:
+  --tmp-root <path>              Root tmp directory (default: tmp/)
+`.trim();
+function parseError(message) {
+  return Object.assign(new Error(message), { usage: USAGE });
+}
+function normalizeGate(value) {
+  const gates = new Set(["draft_gate", "pre_approval_gate"]);
+  const normalized = String(value).trim().toLowerCase();
+  return gates.has(normalized) ? normalized : null;
+}
+function normalizeVerdict(value) {
+  const verdicts = new Set(["clean", "findings_present", "blocked"]);
+  const normalized = String(value).trim().toLowerCase();
+  return verdicts.has(normalized) ? normalized : null;
+}
+function normalizeHeadSha(value) {
+  const normalized = String(value).trim().toLowerCase();
+  return /^[0-9a-f]{7,64}$/i.test(normalized) ? normalized : null;
+}
+const VALID_SEVERITIES = new Set(["must-fix", "worth-fixing-now", "defer"]);
+const VALID_DISPOSITIONS = new Set(["accepted-for-fix", "deferred", "disputed", "operator_acknowledged"]);
+function parseFindingsJson(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw parseError("--findings must be valid JSON");
+  }
+  if (!Array.isArray(parsed)) {
+    throw parseError("--findings must be a JSON array");
+  }
+  return parsed.map((f, i) => {
+    if (!f || typeof f !== "object") {
+      throw parseError(`--findings[${i}] must be an object`);
+    }
+    if (!f.severity || !VALID_SEVERITIES.has(f.severity)) {
+      throw parseError(`--findings[${i}].severity must be one of: must-fix, worth-fixing-now, defer`);
+    }
+    if (!f.angle || typeof f.angle !== "string" || f.angle.trim().length === 0) {
+      throw parseError(`--findings[${i}].angle is required`);
+    }
+    if (!f.summary || typeof f.summary !== "string" || f.summary.trim().length === 0) {
+      throw parseError(`--findings[${i}].summary is required`);
+    }
+    const entry = {
+      severity: f.severity,
+      angle: f.angle.trim(),
+      summary: f.summary.trim(),
+    };
+    if ("disposition" in f) {
+      if (typeof f.disposition !== "string" || f.disposition.trim().length === 0) {
+        throw parseError(`--findings[${i}].disposition must be a non-empty string`);
+      }
+      const disp = f.disposition.trim();
+      if (!VALID_DISPOSITIONS.has(disp)) {
+        throw parseError(`--findings[${i}].disposition must be one of: accepted-for-fix, deferred, disputed, operator_acknowledged`);
+      }
+      entry.disposition = disp;
+    }
+    if (Array.isArray(f.files)) {
+      entry.files = f.files.filter(x => typeof x === "string" && x.trim().length > 0);
+    }
+    if ("resolvedIn" in f) {
+      if (typeof f.resolvedIn !== "string" || f.resolvedIn.trim().length === 0) {
+        throw parseError(`--findings[${i}].resolvedIn must be a non-empty string`);
+      }
+      const sha = f.resolvedIn.trim();
+      if (!/^[0-9a-f]{7,64}$/i.test(sha)) {
+        throw parseError(`--findings[${i}].resolvedIn must be a 7-64 char hex SHA`);
+      }
+      entry.resolvedIn = sha;
+    }
+    return entry;
+  });
+}
+export function parseWriteGateFindingsLogCliArgs(argv) {
+  const args = [...argv];
+  const options = {
+    repo: undefined,
+    pr: undefined,
+    gate: undefined,
+    headSha: undefined,
+    verdict: undefined,
+    findings: undefined,
+    tmpRoot: "tmp",
+  };
+  while (args.length > 0) {
+    const token = args.shift();
+    if (token === "--help" || token === "-h") {
+      return { help: true };
+    }
+    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 === "--gate") {
+      const gate = normalizeGate(requireOptionValue(args, "--gate", parseError));
+      if (!gate) throw parseError("--gate must be draft_gate or pre_approval_gate");
+      options.gate = gate;
+      continue;
+    }
+    if (token === "--head-sha") {
+      const sha = normalizeHeadSha(requireOptionValue(args, "--head-sha", parseError));
+      if (!sha) throw parseError("--head-sha must be a 7-64 character hex SHA");
+      options.headSha = sha;
+      continue;
+    }
+    if (token === "--verdict") {
+      const verdict = normalizeVerdict(requireOptionValue(args, "--verdict", parseError));
+      if (!verdict) throw parseError("--verdict must be clean, findings_present, or blocked");
+      options.verdict = verdict;
+      continue;
+    }
+    if (token === "--findings") {
+      options.findings = requireOptionValue(args, "--findings", parseError);
+      continue;
+    }
+    if (token === "--tmp-root") {
+      options.tmpRoot = requireOptionValue(args, "--tmp-root", parseError).trim();
+      continue;
+    }
+    throw parseError(`Unknown argument: ${token}`);
+  }
+  const missing = ["repo", "pr", "gate", "headSha", "verdict", "findings"]
+    .filter(k => options[k] === undefined);
+  if (missing.length > 0) {
+    throw parseError(`Missing required arguments: ${missing.join(", ")}`);
+  }
+  return options;
+}
+function buildLogPath({ repo, pr, gate, headSha, tmpRoot }) {
+  const parts = repo.split("/");
+  if (parts.length !== 2 || parts.some(p => p.length === 0)) {
+    throw new Error(`--repo must be in owner/name format, got: ${JSON.stringify(repo)}`);
+  }
+  for (const p of parts) {
+    if (p === "." || p === ".." || /[\s\\]/.test(p)) {
+      throw new Error(`--repo segment ${JSON.stringify(p)} contains unsafe characters (dots, whitespace, or backslashes)`);
+    }
+  }
+  const repoSlug = parts.join("-");
+  return path.join(tmpRoot, "gate-findings", repoSlug, `pr-${pr}`, `${gate}-${headSha}.json`);
+}
+export async function writeGateFindingsLog(options, { repoRoot = process.cwd() } = {}) {
+  const findings = parseFindingsJson(options.findings);
+  const logPath = buildLogPath({
+    repo: options.repo,
+    pr: options.pr,
+    gate: options.gate,
+    headSha: options.headSha,
+    tmpRoot: options.tmpRoot || "tmp",
+  });
+  const fullPath = path.resolve(repoRoot, logPath);
+  const log = {
+    repo: options.repo,
+    pr: options.pr,
+    gate: options.gate,
+    headSha: options.headSha,
+    verdict: options.verdict,
+    loggedAt: new Date().toISOString(),
+    findings,
+  };
+  await mkdir(path.dirname(fullPath), { recursive: true });
+  await writeFile(fullPath, JSON.stringify(log, null, 2) + "\n", "utf8");
+  return { ok: true, path: logPath, log };
+}
+async function main() {
+  let options;
+  try {
+    options = parseWriteGateFindingsLogCliArgs(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`${formatCliError(error, { usage: USAGE })}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (options.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return;
+  }
+  try {
+    const result = await writeGateFindingsLog(options);
+    process.stdout.write(JSON.stringify(result) + "\n");
+  } catch (error) {
+    process.stderr.write(JSON.stringify({
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    }) + "\n");
+    process.exitCode = 1;
+  }
+}
+if (isDirectCliRun(import.meta.url)) {
+  await main();
+}

package/scripts/loop/_checkpoint-io.mjs

@@ -0,0 +1,55 @@
+import { readFile } from "node:fs/promises";
+import { parseJsonText } from "../_core-helpers.mjs";
+import {
+  buildCheckpointFilePath,
+  buildDefaultCheckpointDir,
+  buildLegacyDefaultCheckpointDir,
+} from "./_checkpoint-paths.mjs";
+export async function readExistingCheckpoint(repo, pr, { checkpointDir, failSilently = false } = {}) {
+  const normalizedRepo = typeof repo === "string" ? repo.trim().toLowerCase() : repo;
+  if (checkpointDir !== undefined) {
+    const filePath = buildCheckpointFilePath(checkpointDir);
+    try {
+      const text = await readFile(filePath, "utf8");
+      return { checkpoint: parseJsonText(text), filePath };
+    } catch (error) {
+      if (error && error.code === "ENOENT") {
+        return { checkpoint: null, filePath: null };
+      }
+      if (failSilently) {
+        return { checkpoint: null, filePath: null };
+      }
+      throw new Error(`Failed to read checkpoint '${filePath}': ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  const preferredDir = buildDefaultCheckpointDir(normalizedRepo, pr);
+  const preferredPath = buildCheckpointFilePath(preferredDir);
+  try {
+    const text = await readFile(preferredPath, "utf8");
+    return { checkpoint: parseJsonText(text), filePath: preferredPath };
+  } catch (error) {
+    if (error && error.code !== "ENOENT") {
+      if (failSilently) {
+        return { checkpoint: null, filePath: null };
+      }
+      throw new Error(`Failed to read checkpoint '${preferredPath}': ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  const legacyPath = buildCheckpointFilePath(buildLegacyDefaultCheckpointDir(pr));
+  try {
+    const text = await readFile(legacyPath, "utf8");
+    const checkpoint = parseJsonText(text);
+    if (checkpoint?.repo === normalizedRepo && checkpoint?.pr === pr) {
+      return { checkpoint, filePath: legacyPath };
+    }
+    return { checkpoint: null, filePath: null };
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return { checkpoint: null, filePath: null };
+    }
+    if (failSilently) {
+      return { checkpoint: null, filePath: null };
+    }
+    throw new Error(`Failed to read checkpoint '${legacyPath}': ${error instanceof Error ? error.message : String(error)}`);
+  }
+}

package/scripts/loop/_checkpoint-paths.mjs

@@ -0,0 +1,28 @@
+import path from "node:path";
+function splitRepo(repo) {
+  if (typeof repo !== "string") {
+    throw new Error("repo must be a string");
+  }
+  const normalized = repo.trim().toLowerCase();
+  const parts = normalized.split("/");
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    throw new Error(`repo must be owner/name, received ${repo}`);
+  }
+  return { owner: parts[0], name: parts[1], normalized };
+}
+export function buildDefaultCheckpointDir(repo, pr) {
+  const { owner, name } = splitRepo(repo);
+  return path.join("tmp", "copilot-loop", owner, name, `pr-${pr}`);
+}
+export function buildLegacyDefaultCheckpointDir(pr) {
+  return path.join("tmp", "copilot-loop", `pr-${pr}`);
+}
+export function buildCheckpointFilePath(checkpointDir) {
+  return path.join(checkpointDir, "outer-loop-state.json");
+}
+export function buildDefaultCheckpointFilePath(repo, pr) {
+  return buildCheckpointFilePath(buildDefaultCheckpointDir(repo, pr));
+}
+export function buildLegacyDefaultCheckpointFilePath(pr) {
+  return buildCheckpointFilePath(buildLegacyDefaultCheckpointDir(pr));
+}

package/scripts/loop/_handoff-contract.mjs

@@ -0,0 +1,230 @@
+import { PR_CHECKPOINT } from "@dev-loops/core/loop/pr-gate-coordination";
+const HANDOFF_OWNERSHIP = Object.freeze({
+  SUBAGENT: "subagent",
+  PARENT: "parent",
+  HUMAN: "human",
+  TERMINAL: "terminal",
+});
+const HANDOFF_STOP_BOUNDARY = Object.freeze({
+  SUBAGENT_EXIT: "subagent_exit",
+  WATCH_BOUNDARY: "watch_boundary",
+  APPROVAL_BOUNDARY: "approval_boundary",
+  MERGE_BOUNDARY: "merge_boundary",
+  CONFLICT_BOUNDARY: "conflict_boundary",
+  TERMINAL: "terminal_boundary",
+});
+const HANDOFF_RESUME_POLICY = Object.freeze({
+  RESUME_AFTER_SUBAGENT_EXIT: "resume_after_subagent_exit",
+  RESUME_AFTER_STATE_REFRESH: "resume_after_state_refresh",
+  RESUME_AFTER_HUMAN_APPROVAL: "resume_after_human_approval",
+  RESUME_AFTER_MERGE_AUTHORIZATION: "resume_after_merge_authorization",
+  MANUAL_ATTENTION: "manual_attention",
+  NONE: "none",
+});
+const GATE_BOUNDARY_STOP_VALUES = new Set(Object.values(PR_CHECKPOINT));
+const SUBAGENT_ACTIONS = new Set([
+  "fix_threads",
+  "draft_gate",
+  "request_review",
+  "rerequest_review",
+  "run_pre_approval",
+]);
+function normalizeContractValue(value) {
+  return typeof value === "string" ? value.trim().toLowerCase() : null;
+}
+function buildContract({ ownership, stopBoundary, resumePolicy }) {
+  return {
+    ownership,
+    stopBoundary,
+    resumePolicy,
+  };
+}
+export function buildHandoffContractForConductorAction({ action, gateBoundary, requiresApproval = false } = {}) {
+  const normalizedAction = normalizeContractValue(action);
+  if (SUBAGENT_ACTIONS.has(normalizedAction)) {
+    if (requiresApproval) {
+      return buildContract({
+        ownership: HANDOFF_OWNERSHIP.HUMAN,
+        stopBoundary: HANDOFF_STOP_BOUNDARY.APPROVAL_BOUNDARY,
+        resumePolicy: HANDOFF_RESUME_POLICY.RESUME_AFTER_HUMAN_APPROVAL,
+      });
+    }
+    return buildContract({
+      ownership: HANDOFF_OWNERSHIP.SUBAGENT,
+      stopBoundary: HANDOFF_STOP_BOUNDARY.SUBAGENT_EXIT,
+      resumePolicy: HANDOFF_RESUME_POLICY.RESUME_AFTER_SUBAGENT_EXIT,
+    });
+  }
+  switch (normalizedAction) {
+    case "watch":
+      return buildContract({
+        ownership: HANDOFF_OWNERSHIP.PARENT,
+        stopBoundary: HANDOFF_STOP_BOUNDARY.WATCH_BOUNDARY,
+        resumePolicy: HANDOFF_RESUME_POLICY.RESUME_AFTER_STATE_REFRESH,
+      });
+    case "merge":
+      return buildContract({
+        ownership: requiresApproval ? HANDOFF_OWNERSHIP.HUMAN : HANDOFF_OWNERSHIP.PARENT,
+        stopBoundary: HANDOFF_STOP_BOUNDARY.MERGE_BOUNDARY,
+        resumePolicy: requiresApproval
+          ? HANDOFF_RESUME_POLICY.RESUME_AFTER_MERGE_AUTHORIZATION
+          : HANDOFF_RESUME_POLICY.NONE,
+      });
+    case "await_approval":
+      return buildContract({
+        ownership: HANDOFF_OWNERSHIP.HUMAN,
+        stopBoundary: HANDOFF_STOP_BOUNDARY.APPROVAL_BOUNDARY,
+        resumePolicy: HANDOFF_RESUME_POLICY.RESUME_AFTER_HUMAN_APPROVAL,
+      });
+    case "resolve_conflicts":
+    case "blocked":
+    case "error":
+      return buildContract({
+        ownership: HANDOFF_OWNERSHIP.HUMAN,
+        stopBoundary: HANDOFF_STOP_BOUNDARY.CONFLICT_BOUNDARY,
+        resumePolicy: HANDOFF_RESUME_POLICY.MANUAL_ATTENTION,
+      });
+    case "done":
+      return buildContract({
+        ownership: HANDOFF_OWNERSHIP.TERMINAL,
+        stopBoundary: HANDOFF_STOP_BOUNDARY.TERMINAL,
+        resumePolicy: HANDOFF_RESUME_POLICY.NONE,
+      });
+    default:
+      return buildContract({
+        ownership: HANDOFF_OWNERSHIP.HUMAN,
+        stopBoundary: HANDOFF_STOP_BOUNDARY.CONFLICT_BOUNDARY,
+        resumePolicy: HANDOFF_RESUME_POLICY.MANUAL_ATTENTION,
+      });
+  }
+}
+export function buildHandoffContractForResumeAction(resumeAction) {
+  const normalizedAction = normalizeContractValue(resumeAction);
+  switch (normalizedAction) {
+    case "needs_feedback_fix":
+      return buildContract({
+        ownership: HANDOFF_OWNERSHIP.SUBAGENT,
+        stopBoundary: HANDOFF_STOP_BOUNDARY.SUBAGENT_EXIT,
+        resumePolicy: HANDOFF_RESUME_POLICY.RESUME_AFTER_SUBAGENT_EXIT,
+      });
+    case "needs_reply_resolve":
+      return buildContract({
+        ownership: HANDOFF_OWNERSHIP.SUBAGENT,
+        stopBoundary: HANDOFF_STOP_BOUNDARY.SUBAGENT_EXIT,
+        resumePolicy: HANDOFF_RESUME_POLICY.RESUME_AFTER_SUBAGENT_EXIT,
+      });
+    case "needs_rerequest_or_watch":
+      return buildContract({
+        ownership: HANDOFF_OWNERSHIP.PARENT,
+        stopBoundary: HANDOFF_STOP_BOUNDARY.WATCH_BOUNDARY,
+        resumePolicy: HANDOFF_RESUME_POLICY.RESUME_AFTER_STATE_REFRESH,
+      });
+    case "await_final_approval":
+      return buildContract({
+        ownership: HANDOFF_OWNERSHIP.HUMAN,
+        stopBoundary: HANDOFF_STOP_BOUNDARY.APPROVAL_BOUNDARY,
+        resumePolicy: HANDOFF_RESUME_POLICY.RESUME_AFTER_HUMAN_APPROVAL,
+      });
+    case "await_merge_authorization":
+      return buildContract({
+        ownership: HANDOFF_OWNERSHIP.HUMAN,
+        stopBoundary: HANDOFF_STOP_BOUNDARY.MERGE_BOUNDARY,
+        resumePolicy: HANDOFF_RESUME_POLICY.RESUME_AFTER_MERGE_AUTHORIZATION,
+      });
+    case "await_ready_for_review_authorization":
+      return buildContract({
+        ownership: HANDOFF_OWNERSHIP.HUMAN,
+        stopBoundary: HANDOFF_STOP_BOUNDARY.APPROVAL_BOUNDARY,
+        resumePolicy: HANDOFF_RESUME_POLICY.RESUME_AFTER_HUMAN_APPROVAL,
+      });
+    case "done_or_merged":
+      return buildContract({
+        ownership: HANDOFF_OWNERSHIP.TERMINAL,
+        stopBoundary: HANDOFF_STOP_BOUNDARY.TERMINAL,
+        resumePolicy: HANDOFF_RESUME_POLICY.NONE,
+      });
+    case "needs_manual_attention":
+    default:
+      return buildContract({
+        ownership: HANDOFF_OWNERSHIP.HUMAN,
+        stopBoundary: HANDOFF_STOP_BOUNDARY.CONFLICT_BOUNDARY,
+        resumePolicy: HANDOFF_RESUME_POLICY.MANUAL_ATTENTION,
+      });
+  }
+}
+function parseContractLine(text, label) {
+  const pattern = new RegExp(String.raw`(?:^|\n)\s*[-*]?\s*${label}:\s*(.+)$`, "imu");
+  const match = text.match(pattern);
+  return match?.[1]?.trim() ?? null;
+}
+export function parseRecordedHandoffContract(text) {
+  if (typeof text !== "string" || text.length === 0) {
+    return { contract: null, reason: null };
+  }
+  const ownership = normalizeContractValue(parseContractLine(text, "Handoff ownership"));
+  const stopBoundary = normalizeContractValue(parseContractLine(text, "Stop boundary"));
+  const resumePolicy = normalizeContractValue(parseContractLine(text, "Resume policy"));
+  const foundCount = [ownership, stopBoundary, resumePolicy].filter((value) => value !== null).length;
+  if (foundCount === 0) {
+    return { contract: null, reason: null };
+  }
+  if (foundCount !== 3) {
+    return {
+      contract: null,
+      reason: "incomplete_handoff_contract",
+      details: {
+        ownership,
+        stopBoundary,
+        resumePolicy,
+      },
+    };
+  }
+  const validOwnership = Object.values(HANDOFF_OWNERSHIP).includes(ownership);
+  const validStopBoundary = Object.values(HANDOFF_STOP_BOUNDARY).includes(stopBoundary)
+    || GATE_BOUNDARY_STOP_VALUES.has(stopBoundary);
+  const validResumePolicy = Object.values(HANDOFF_RESUME_POLICY).includes(resumePolicy);
+  if (!validOwnership || !validStopBoundary || !validResumePolicy) {
+    return {
+      contract: null,
+      reason: "invalid_handoff_contract",
+      details: {
+        ownership,
+        stopBoundary,
+        resumePolicy,
+      },
+    };
+  }
+  return {
+    contract: buildContract({
+      ownership,
+      stopBoundary,
+      resumePolicy,
+    }),
+    reason: null,
+  };
+}
+export function compareHandoffContracts(recorded, expected) {
+  if (!recorded || !expected) {
+    return null;
+  }
+  const mismatches = [];
+  for (const key of ["ownership", "stopBoundary", "resumePolicy"]) {
+    if (recorded[key] !== expected[key]) {
+      mismatches.push(key);
+    }
+  }
+  if (mismatches.length === 0) {
+    return null;
+  }
+  return {
+    mismatches,
+    recorded,
+    expected,
+  };
+}
+export {
+  HANDOFF_OWNERSHIP,
+  HANDOFF_STOP_BOUNDARY,
+  HANDOFF_RESUME_POLICY,
+  SUBAGENT_ACTIONS
+};