@dev-loops/core 0.1.0

package/src/loop/queue-state.mjs

@@ -0,0 +1,230 @@
+/**
+ * Queue state machine — durable .pi/dev-loop-queue.json read/write/transition.
+ *
+ * Entry lifecycle:
+ *   queued → running → waiting_review → gates_passing → merging → done
+ *   any state → blocked | failed
+ */
+
+import { readFile, writeFile, rename, mkdir } from "node:fs/promises";
+import path from "node:path";
+
+// ── Schema constants ────────────────────────────────────────────────
+
+export const QUEUE_VERSION = 1;
+
+export const ENTRY_STATUS = Object.freeze([
+  "queued",
+  "running",
+  "waiting_review",
+  "gates_passing",
+  "merging",
+  "done",
+  "blocked",
+  "failed",
+]);
+
+export const VALID_TRANSITIONS = Object.freeze({
+  queued:           ["running", "blocked"],
+  running:           ["waiting_review", "blocked", "failed", "done"],
+  waiting_review:    ["running", "gates_passing", "blocked", "failed", "done"],
+  gates_passing:     ["merging", "blocked", "failed", "done"],
+  merging:           ["done", "failed", "blocked"],
+  done:              [],
+  blocked:           ["queued", "running", "failed"],
+  failed:            ["queued"],
+});
+
+export const RECOVERABLE_FAILURES = new Set([
+  "acceptance_report_parse_failure",
+  "round_cap_reached",
+  "timeout",
+]);
+
+// ── Default queue shape ─────────────────────────────────────────────
+
+function emptyQueue() {
+  return { version: QUEUE_VERSION, entries: [] };
+}
+
+// ── File I/O ─────────────────────────────────────────────────────────
+
+export function queueFilePath(repoRoot) {
+  return path.join(repoRoot, ".pi", "dev-loop-queue.json");
+}
+
+export async function readQueue(repoRoot) {
+  const fp = queueFilePath(repoRoot);
+  try {
+    const raw = await readFile(fp, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.entries)) {
+      return emptyQueue();
+    }
+    return { version: parsed.version ?? QUEUE_VERSION, entries: parsed.entries };
+  } catch {
+    return emptyQueue();
+  }
+}
+
+export async function writeQueue(repoRoot, queue) {
+  const fp = queueFilePath(repoRoot);
+  await mkdir(path.dirname(fp), { recursive: true });
+  // Atomic write: write to temp file then rename
+  const tmp = fp + ".tmp." + Date.now();
+  await writeFile(tmp, JSON.stringify(queue, null, 2) + "\n", "utf8");
+  await rename(tmp, fp);
+}
+
+// ── Entry helpers ────────────────────────────────────────────────────
+
+export function createEntry(target, kind, dependsOn = []) {
+  return {
+    target,
+    kind,           // "issue" | "pr"
+    status: "queued",
+    dependsOn: Array.isArray(dependsOn) ? dependsOn : [],
+    pr: null,
+    runId: null,
+    retrospectiveWritten: false,
+    failureReason: null,
+    failureKind: null,
+    retryCount: 0,
+  };
+}
+
+export function snapshotEntry(entry) {
+  return { ...entry };
+}
+
+export function findEntry(queue, target) {
+  return queue.entries.find((e) => e.target === target);
+}
+
+export function findEntryIndex(queue, target) {
+  return queue.entries.findIndex((e) => e.target === target);
+}
+
+// ── State machine ────────────────────────────────────────────────────
+
+export function isValidTransition(from, to) {
+  const allowed = VALID_TRANSITIONS[from];
+  if (!allowed) return false;
+  return allowed.includes(to);
+}
+
+export function transitionEntry(entry, to, metadata = {}) {
+  if (!isValidTransition(entry.status, to)) {
+    throw new Error(
+      `Invalid transition: ${entry.status} → ${to} for entry ${entry.target}`
+    );
+  }
+  entry.status = to;
+  if (metadata.pr != null) entry.pr = metadata.pr;
+  if (metadata.runId != null) entry.runId = metadata.runId;
+  if (metadata.retrospectiveWritten != null) entry.retrospectiveWritten = metadata.retrospectiveWritten;
+  if (metadata.failureReason != null) entry.failureReason = metadata.failureReason;
+  if (metadata.failureKind != null) entry.failureKind = metadata.failureKind;
+  return entry;
+}
+
+// ── Dependency resolution ────────────────────────────────────────────
+
+export function entryDependenciesSatisfied(queue, entry) {
+  if (!entry.dependsOn || entry.dependsOn.length === 0) return true;
+  return entry.dependsOn.every((depTarget) => {
+    const dep = findEntry(queue, depTarget);
+    return dep && dep.status === "done";
+  });
+}
+
+// ── Queue ordering ───────────────────────────────────────────────────
+
+export function topologicalOrder(entries) {
+  const visited = new Set();
+  const result = [];
+
+  function visit(entry, path = new Set()) {
+    if (visited.has(entry.target)) return;
+    if (path.has(entry.target)) {
+      throw new Error(`Circular dependency detected involving ${entry.target}`);
+    }
+    path.add(entry.target);
+    for (const depTarget of entry.dependsOn || []) {
+      const dep = entries.find((e) => e.target === depTarget);
+      if (dep) visit(dep, new Set(path));
+    }
+    path.delete(entry.target);
+    visited.add(entry.target);
+    result.push(entry);
+  }
+
+  for (const entry of entries) {
+    visit(entry);
+  }
+
+  return result;
+}
+
+function applyOrderHint(ordered, orderHint) {
+  if (orderHint.length === 0) return ordered;
+  const hinted = new Set(orderHint);
+  const hintIndex = new Map(orderHint.map((target, i) => [target, i]));
+  const inHint = [];
+  const rest = [];
+  for (const entry of ordered) {
+    if (hinted.has(entry.target)) {
+      inHint.push(entry);
+    } else {
+      rest.push(entry);
+    }
+  }
+  inHint.sort((a, b) => hintIndex.get(a.target) - hintIndex.get(b.target));
+  return [...inHint, ...rest];
+}
+
+export function nextReadyEntry(queue, maxRetries = 1, orderHint = []) {
+  const ordered = topologicalOrder(queue.entries);
+  const sorted = applyOrderHint(ordered, orderHint);
+  for (const entry of sorted) {
+    if (entry.status === "queued" && entryDependenciesSatisfied(queue, entry)) {
+      return entry;
+    }
+    if (
+      entry.status === "failed" &&
+      RECOVERABLE_FAILURES.has(entry.failureKind) &&
+      (entry.retryCount ?? 0) < maxRetries
+    ) {
+      return entry;
+    }
+  }
+  return null;
+}
+
+export function allDone(queue) {
+  return queue.entries.every((e) => e.status === "done" || e.status === "blocked");
+}
+
+export function pendingEntries(queue) {
+  return queue.entries.filter(
+    (e) => e.status !== "done" && e.status !== "blocked"
+  );
+}
+
+// ── Bug injection ────────────────────────────────────────────────────
+
+export function appendBugIssue(queue, issueNumber, dependsOn = null) {
+  const entry = createEntry(issueNumber, "issue", dependsOn ? [dependsOn] : []);
+  entry.status = "queued";
+  queue.entries.push(entry);
+  return entry;
+}
+
+// ── Serialization helpers ────────────────────────────────────────────
+
+export function serializeQueue(queue) {
+  return {
+    version: queue.version,
+    entries: queue.entries.map((e) => ({ ...e })),
+  };
+}

package/src/loop/retrospective-checkpoint.mjs

@@ -0,0 +1,178 @@
+/**
+ * Post-run behavioral retrospective checkpoint contract.
+ *
+ * Defines the enforcement seam for the required post-run behavioral retrospective
+ * after qualifying async dev-loop completions in this repository.
+ *
+ * This module is intentionally pure and side-effect free. Callers are responsible
+ * for reading/writing the durable checkpoint artifact and passing the resolved
+ * checkpoint state to the enforcement gate.
+ *
+ * Relationship to formal dev mode:
+ * - Formal local dev mode is scoped to local implementation/self-improvement work.
+ * - The required post-run behavioral retrospective applies to qualifying async
+ *   GitHub-first dev-loop completions, independent of whether that run was in
+ *   formal local dev mode.
+ * - These are related but distinct requirements.
+ */
+
+/**
+ * Stable state constants for the post-run behavioral retrospective checkpoint.
+ *
+ * These represent the state that a caller derives from the durable checkpoint
+ * artifact on disk, then passes to the enforcement gate.
+ *
+ * Mapping from durable artifact to checkpoint state:
+ * - No artifact file → NONE (no qualifying completion has occurred)
+ * - Artifact file with state "required" → MISSING (completion detected, retrospective pending)
+ * - Artifact file with state "complete" → COMPLETE (retrospective recorded)
+ * - Artifact file with state "skipped" → SKIPPED (explicitly skipped with reason)
+ */
+export const RETROSPECTIVE_CHECKPOINT_STATE = Object.freeze({
+  /** No qualifying async dev-loop completion has occurred; no retrospective is required. */
+  NONE: "none",
+  /** The required retrospective has been completed and recorded. */
+  COMPLETE: "complete",
+  /** The required retrospective was explicitly skipped with a stated reason. */
+  SKIPPED: "skipped",
+  /** A qualifying async dev-loop completion was detected but no retrospective checkpoint exists. */
+  MISSING: "missing",
+});
+
+/**
+ * The set of internal dev-loop strategy gate names that represent qualifying
+ * GitHub-first async completions in this repository.
+ *
+ * A post-run behavioral retrospective is required before the next dev-loop
+ * start/resume when the previous run used one of these gates.
+ *
+ * Qualifying gates:
+ * - copilot_pr_followup: Copilot-owned PR follow-up (primary routed GitHub-first path)
+ * - issue_intake: Copilot-first issue intake (GitHub-first issue assignment path)
+ */
+export const RETROSPECTIVE_QUALIFYING_GATES = Object.freeze([
+  "copilot_pr_followup",
+  "issue_intake",
+]);
+
+/**
+ * Normalizes an external retrospective checkpoint-state input to one of the
+ * stable RETROSPECTIVE_CHECKPOINT_STATE values. Returns null when the value is
+ * absent or unrecognized.
+ *
+ * @param {unknown} value
+ * @returns {"none"|"complete"|"skipped"|"missing"|null}
+ */
+export function normalizeRetrospectiveCheckpointState(value) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+
+  const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+  return Object.values(RETROSPECTIVE_CHECKPOINT_STATE).includes(normalized) ? normalized : null;
+}
+
+/**
+ * Returns true if a routing result represents a qualifying GitHub-first async
+ * dev-loop completion that requires a post-run behavioral retrospective before
+ * the next start/resume.
+ *
+ * A qualifying completion is one that:
+ * - has a `selectedGate` in RETROSPECTIVE_QUALIFYING_GATES
+ * - with `routeKind === "route"` (inspect/status-only results do not qualify)
+ */
+export function isQualifyingAsyncCompletion(routingResult) {
+  if (!routingResult || typeof routingResult !== "object") return false;
+  const { routeKind, selectedGate } = routingResult;
+  if (routeKind !== "route") {
+    return false;
+  }
+  if (typeof selectedGate !== "string") return false;
+  return RETROSPECTIVE_QUALIFYING_GATES.includes(selectedGate);
+}
+
+/**
+ * Enforcement gate for the required post-run behavioral retrospective.
+ *
+ * Evaluates whether a proposed dev-loop routing result should proceed or be
+ * blocked due to a missing retrospective checkpoint from the previous qualifying
+ * async completion.
+ *
+ * Pass-through cases (proposed routing is returned unchanged):
+ * - checkpoint state is NONE (no qualifying completion has happened; no requirement exists)
+ * - checkpoint state is COMPLETE (retrospective was recorded; requirement satisfied)
+ * - checkpoint state is SKIPPED (explicitly skipped with reason; requirement satisfied)
+ * - proposed routing is already a stop or needs_reconcile result
+ * - proposed routing is an inspect-only result
+ *
+ * Fail-closed case:
+ * - checkpoint state is MISSING: returns a needs_reconcile result that blocks start/resume
+ * - unrecognized checkpoint state: returns a needs_reconcile result
+ *
+ * @param {object} input
+ * @param {string} input.checkpointState - One of the RETROSPECTIVE_CHECKPOINT_STATE values
+ * @param {object} input.proposedRouting - The routing result from evaluatePublicDevLoopRouting
+ * @returns {object} The original or replacement routing result
+ */
+export function evaluateRetrospectiveGate({ checkpointState, proposedRouting } = {}) {
+  if (!proposedRouting || typeof proposedRouting !== "object") {
+    return {
+      publicEntrypoint: "dev-loop",
+      routeKind: "needs_reconcile",
+      selectedGate: "fail_closed_reconcile",
+      selectedStrategy: null,
+      executionMode: "bounded_handoff",
+      waitSemantics: "default",
+      canonicalState: null,
+      issueAssignmentSeam: "not_applicable",
+      nextAction: "Reconcile the retrospective checkpoint state before routing.",
+      reason: "Missing or invalid proposed routing result for retrospective gate evaluation.",
+    };
+  }
+
+  // Already a terminal/inspect result — pass through regardless of checkpoint state.
+  if (
+    proposedRouting.routeKind === "stop" ||
+    proposedRouting.routeKind === "needs_reconcile" ||
+    proposedRouting.routeKind === "inspect"
+  ) {
+    return proposedRouting;
+  }
+
+  // No qualifying completion, or retrospective satisfied — pass through.
+  if (
+    checkpointState === RETROSPECTIVE_CHECKPOINT_STATE.NONE ||
+    checkpointState === RETROSPECTIVE_CHECKPOINT_STATE.COMPLETE ||
+    checkpointState === RETROSPECTIVE_CHECKPOINT_STATE.SKIPPED
+  ) {
+    return proposedRouting;
+  }
+
+  // Missing retrospective checkpoint — fail closed.
+  if (checkpointState === RETROSPECTIVE_CHECKPOINT_STATE.MISSING) {
+    return {
+      ...proposedRouting,
+      routeKind: "needs_reconcile",
+      selectedGate: "fail_closed_reconcile",
+      selectedStrategy: null,
+      waitSemantics: proposedRouting.waitSemantics ?? "default",
+      issueAssignmentSeam: proposedRouting.issueAssignmentSeam ?? "not_applicable",
+      nextAction:
+        "Complete or explicitly skip the required post-run behavioral retrospective before starting or resuming the next dev-loop run.",
+      reason:
+        "The previous qualifying async dev-loop completion is missing its required behavioral retrospective checkpoint.",
+    };
+  }
+
+  // Unrecognized checkpoint state — fail closed.
+  return {
+    ...proposedRouting,
+    routeKind: "needs_reconcile",
+    selectedGate: "fail_closed_reconcile",
+    selectedStrategy: null,
+    waitSemantics: proposedRouting.waitSemantics ?? "default",
+    issueAssignmentSeam: proposedRouting.issueAssignmentSeam ?? "not_applicable",
+    nextAction: "Reconcile the retrospective checkpoint state before routing.",
+    reason: `Unrecognized retrospective checkpoint state: "${String(checkpointState)}".`,
+  };
+}