dev-loops 0.1.0

package/cli/index.mjs

@@ -0,0 +1,424 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { realpathSync, constants as fsConstants } from "node:fs";
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  describeReadiness,
+  executeDevLoopsCommand,
+  renderCheckLines,
+  summarizeChecks,
+  DEV_LOOP_CHECK_IDS,
+} from "../lib/dev-loops-core.mjs";
+import { isUsageError, buildCorrectedArgs } from "@dev-loops/core/cli/retry-wrapper";
+import { createPiAdapter } from "@dev-loops/core/harness";
+
+const REPO_ROOT = fileURLToPath(new URL("..", import.meta.url));
+
+const SUBCOMMAND_ROUTES = {
+  gate: {
+    "upsert-verdict":     "scripts/github/upsert-checkpoint-verdict.mjs",
+    "detect-evidence":    "scripts/github/detect-checkpoint-evidence.mjs",
+    "write-findings-log": "scripts/github/write-gate-findings-log.mjs",
+    "request-copilot":    "scripts/github/request-copilot-review.mjs",
+    "probe-copilot":      "scripts/github/probe-copilot-review.mjs",
+    "capture-threads":    "scripts/github/capture-review-threads.mjs",
+    "reply-resolve":      "scripts/github/reply-resolve-review-threads.mjs",
+  },
+  loop: {
+    startup:        "scripts/loop/resolve-dev-loop-startup.mjs",
+    "build-envelope": "scripts/loop/build-handoff-envelope.mjs",
+    outer:          "scripts/loop/outer-loop.mjs",
+    "watch-cycle":  "scripts/loop/run-watch-cycle.mjs",
+    handoff:        "scripts/loop/copilot-pr-handoff.mjs",
+    "watch-initial": "scripts/loop/watch-initial-copilot-pr.mjs",
+    "loop-state":           "scripts/loop/detect-copilot-loop-state.mjs",
+    "reviewer-state":       "scripts/loop/detect-reviewer-loop-state.mjs",
+    "gate-coordination":    "scripts/loop/detect-pr-gate-coordination-state.mjs",
+    "linked-issue-pr":      "scripts/github/detect-linked-issue-pr.mjs",
+    "info":                  "scripts/loop/info.mjs",
+    "issue-refinement":     "scripts/loop/detect-issue-refinement-artifact.mjs",
+    "debt-remediate":       "scripts/loop/debt-remediate.mjs",
+  },
+  pr: {
+    "create-draft":     "scripts/github/create-draft-pr.mjs",
+    "ready-for-review": "scripts/github/ready-for-review.mjs",
+    "reconcile-draft":  "scripts/github/reconcile-draft-gate.mjs",
+  },
+  project: {
+    list:    "scripts/projects/list-queue-items.mjs",
+    add:     "scripts/projects/add-queue-item.mjs",
+    move:    "scripts/projects/move-queue-item.mjs",
+    reorder: "scripts/projects/reorder-queue-item.mjs",
+    ensure:  "scripts/projects/ensure-queue-board.mjs",
+  },
+  queue: {
+    run:            "scripts/loop/run-queue.mjs",
+  },
+  inspect: {
+    run:    "scripts/loop/inspect-run.mjs",
+    viewer: "scripts/loop/inspect-run-viewer.mjs",
+  },
+  refine: {
+    verify: "scripts/refine/verify.mjs",
+  },
+};
+
+const TOP_LEVEL_COMMANDS = new Set(["help", "status", "doctor", "gates", "hide"]);
+
+const HELP_CATEGORY_LABELS = {
+  gate: "Gate verdicts, evidence, and review operations",
+  loop: "Loop lifecycle",
+  pr: "PR helpers",
+  project: "GitHub Projects queue helpers",
+  inspect: "Inspection (Pi extension only)",
+  refine: "Epic tree refinement verification",
+};
+
+const TOP_LEVEL_HELP_CATEGORY_ORDER = ["gate", "loop", "pr", "project", "inspect", "refine"];
+
+const SUBCOMMAND_DESCRIPTIONS = {
+  gate: {
+    "upsert-verdict": "Post/update gate review comment",
+    "detect-evidence": "Check merge preconditions",
+    "write-findings-log": "Write disposition ledger",
+    "request-copilot": "Request Copilot review",
+    "probe-copilot": "Poll for Copilot review activity",
+    "capture-threads": "Capture review threads",
+    "reply-resolve": "Reply and resolve review threads",
+  },
+  loop: {
+    startup: "Resolve dev-loop startup bundle",
+    "build-envelope": "Build handoff envelope from startup output",
+    outer: "Run outer-loop detection",
+    "watch-cycle": "Run Copilot wait cycle",
+    handoff: "Copilot PR handoff",
+    "watch-initial": "Watch initial Copilot PR",
+    "loop-state": "Detect Copilot loop state",
+    "reviewer-state": "Detect reviewer loop state",
+    "gate-coordination": "Detect PR gate coordination state",
+    "linked-issue-pr": "Detect linked issue ↔ PR",
+    "issue-refinement": "Detect issue refinement artifact",
+    info: "Show read-only issue/PR state summary",
+    "debt-remediate": "File debt remediation issues",
+  },
+  pr: {
+    "create-draft": "Create draft PR",
+    "ready-for-review": "Mark PR ready for review",
+    "reconcile-draft": "Reconcile non-draft PR",
+  },
+  project: {
+    list: "List queue board items",
+    add: "Add issue/PR to queue board",
+    move: "Move queue item between Status columns",
+    reorder: "Reorder queue board items",
+    ensure: "Create/repair queue board bootstrap surface",
+  },
+  queue: {
+    run: "Run queue driver",
+  },
+  inspect: {
+    run: "Inspect run state",
+    viewer: "Start inspection viewer",
+  },
+  refine: {
+    verify: "Verify epic tree refinement integrity",
+  },
+};
+
+const CLI_SETUP_GUIDANCE = {
+  "gh-installed": "Install GitHub CLI to enable remote GitHub/Copilot workflows.",
+  "gh-auth": "Run `gh auth login` so remote GitHub/Copilot workflows can use your GitHub session.",
+  "subagent-command": "Install or enable subagent support so the `subagent` command is available.",
+  "git-repo": "Run the command from a git repository checkout before using repo-scoped workflows.",
+};
+
+function spawnResult(command, args, options = {}) {
+  try {
+    const result = spawnSync(command, args, { encoding: "utf8", ...options });
+    return { ok: result.status === 0, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+  } catch {
+    return { ok: false, stdout: "", stderr: "" };
+  }
+}
+
+function executableCandidates(command, platform, pathExt) {
+  if (platform !== "win32") return [command];
+  if (path.extname(command)) return [command];
+  const extensions = [...new Set(pathExt.split(";").map((e) => e.trim()).filter(Boolean))];
+  return extensions.map((ext) => `${command}${ext}`);
+}
+
+async function commandExists(
+  command,
+  { searchPath = process.env.PATH ?? "", platform = process.platform, pathExt = process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD" } = {},
+) {
+  if (/[\\/]/.test(command)) return false;
+  const accessMode = platform === "win32" ? fsConstants.F_OK : fsConstants.X_OK;
+  for (const entry of searchPath.split(path.delimiter)) {
+    if (!entry) continue;
+    for (const candidateName of executableCandidates(command, platform, pathExt)) {
+      try { await access(path.join(entry, candidateName), accessMode); return true; } catch { /* continue */ }
+    }
+  }
+  return false;
+}
+
+function buildSubcommandLines(category, { includeHeader = false } = {}) {
+  const routes = SUBCOMMAND_ROUTES[category];
+  if (!routes) return [];
+  const descriptions = SUBCOMMAND_DESCRIPTIONS[category] ?? {};
+  const lines = Object.keys(routes).map((subcommand) => {
+    const description = descriptions[subcommand];
+    return description ? `    ${subcommand.padEnd(16)} ${description}` : `    ${subcommand}`;
+  });
+  if (!includeHeader) return lines;
+  const label = HELP_CATEGORY_LABELS[category] ?? `${category} helpers`;
+  return [`- dev-loops ${category} <sub> [...]    ${label}`, ...lines];
+}
+
+function buildCategoryHelp(category) {
+  const routes = SUBCOMMAND_ROUTES[category];
+  if (!routes) return [`Unknown category: ${category}`];
+  return [
+    `dev-loops ${category} <subcommand> [...]`,
+    "",
+    "Available subcommands:",
+    ...buildSubcommandLines(category),
+  ];
+}
+
+function buildCliHelpLines() {
+  return [
+    "dev-loops help",
+    "",
+    "Workflow entry:",
+    "- /skill:dev-loop (in Pi) or `subagent dev-loop` — single public entrypoint; routing handles the rest",
+    "",
+    "Commands:",
+    "- dev-loops help                   Show this help",
+    "- dev-loops status                 Show readiness snapshot",
+    "- dev-loops doctor                 Show full diagnostic checks",
+    "- dev-loops gates                  Print gate state",
+    "",
+    "Subcommands:",
+    ...TOP_LEVEL_HELP_CATEGORY_ORDER.flatMap((category) => buildSubcommandLines(category, { includeHeader: true })),
+    "",
+    "Use `dev-loops <category> <subcommand> --help` for per-subcommand usage.",
+    "",
+    "`/dev-loops hide` remains an extension-only Pi command.",
+    "Use `pi install git:github.com/mfittko/dev-loops` to install skills and agents, or",
+    "`pi update git:github.com/mfittko/dev-loops` to refresh the package.",
+  ];
+}
+
+function buildCliUsageLines(action) {
+  switch (action) {
+    case "help": case "status": case "doctor": case "gates":
+      return ["Usage:", `- dev-loops ${action}`];
+    case "hide":
+      return ["Usage:", "- dev-loops hide", "`hide` is only supported without extra arguments, and only inside the Pi extension."];
+    default:
+      throw new Error(`Unknown CLI usage action: ${action}`);
+  }
+}
+
+function orderedCliSetupSteps(checks) {
+  const byId = new Map(checks.map((c) => [c.id, c]));
+  const steps = [...new Set(DEV_LOOP_CHECK_IDS.filter((id) => byId.get(id)?.ok === false).map((id) => CLI_SETUP_GUIDANCE[id]))];
+  if (steps.length > 0) return steps.map((step, i) => `${i + 1}. ${step}`);
+  return [
+    "1. Use `/skill:dev-loop` (in Pi) or `subagent dev-loop` to start or continue a dev loop — the single public entry.",
+    "2. Run `dev-loops status` whenever you want a concise readiness snapshot.",
+    "3. Use `pi install git:github.com/mfittko/dev-loops` to install the package, or `pi update git:github.com/mfittko/dev-loops` to refresh it.",
+  ];
+}
+
+function writeLines(stream, lines) { stream.write(`${lines.join("\n")}\n`); }
+
+export function createCliRuntime({
+  adapter = createPiAdapter(),
+  cwd, searchPath,
+  platform, pathExt,
+} = {}) {
+  const effectiveCwd = cwd ?? adapter.getCwd();
+  const effectiveSearchPath = searchPath ?? adapter.getEnv().PATH ?? "";
+  const effectivePlatform = platform ?? process.platform;
+  const effectivePathExt = pathExt ?? adapter.getEnv().PATHEXT ?? ".COM;.EXE;.BAT;.CMD";
+  return {
+    surface: "cli",
+    cwd: effectiveCwd,
+    async commandExists(command) { return commandExists(command, { searchPath: effectiveSearchPath, platform: effectivePlatform, pathExt: effectivePathExt }); },
+    async ghAuthOk() { return spawnResult("gh", ["auth", "status"], { cwd: effectiveCwd }).ok; },
+    async insideGitRepo() { return spawnResult("git", ["rev-parse", "--is-inside-work-tree"], { cwd: effectiveCwd }).ok; },
+    async getSubagentAvailability() {
+      const ok = await commandExists("subagent", { searchPath: effectiveSearchPath, platform: effectivePlatform, pathExt: effectivePathExt });
+      return { ok, availableDetail: "`subagent` command is available.", unavailableDetail: "Install or enable subagent support so `subagent` is available." };
+    },
+  };
+}
+
+// ── Subcommand routing dispatch ────────────────────────────────────
+
+function resolveSubcommandRoute(args) {
+  if (args.length === 0) return null;
+  const category = args[0];
+  const routes = SUBCOMMAND_ROUTES[category];
+  if (!routes) return null;
+
+  if (args.length < 2) {
+    const subs = Object.keys(routes).join(", ");
+    return { error: `Missing subcommand for '${category}'. Available: ${subs}` };
+  }
+
+  const subcommand = args[1];
+  const scriptPath = routes[subcommand];
+  if (!scriptPath) {
+    const subs = Object.keys(routes).join(", ");
+    return { error: `Unknown subcommand '${subcommand}' for '${category}'. Available: ${subs}` };
+  }
+
+  return {
+    scriptPath: path.resolve(REPO_ROOT, scriptPath),
+    forwardedArgs: args.slice(2),
+  };
+}
+
+function parseTopLevelCommand(argv) {
+  const args = [...argv];
+  if (args.length === 0) return { kind: "help" };
+
+  const [cmd, sub] = args;
+
+  // Bare --help / -h
+  if (cmd === "--help" || cmd === "-h") return { kind: "help" };
+
+  // Top-level commands
+  if (TOP_LEVEL_COMMANDS.has(cmd)) {
+    if (args.some((a) => a === "--help" || a === "-h")) return { kind: "help" };
+    if (args.length > 1) return { kind: "malformed", message: `\`${cmd}\` does not accept additional arguments.`, usageAction: cmd };
+    return { kind: "action", action: cmd };
+  }
+
+  // Subcommand routing
+  const routes = SUBCOMMAND_ROUTES[cmd];
+  if (routes) {
+    // If second arg is --help/-h or missing, show category help
+    if (!sub || sub === "--help" || sub === "-h") {
+      return { kind: "category_help", category: cmd };
+    }
+    // Check if any remaining arg is --help — delegate to script
+    if (args.slice(1).some((a) => a === "--help" || a === "-h")) {
+      const scriptPath = routes[sub];
+      if (!scriptPath) return { kind: "category_help", category: cmd };
+      return { kind: "subcommand_help", scriptPath: path.resolve(REPO_ROOT, scriptPath) };
+    }
+    const route = resolveSubcommandRoute(args);
+    if (route) return { kind: "subcommand", ...route };
+    return { kind: "category_help", category: cmd };
+  }
+
+  // Unknown
+  return { kind: "malformed", message: `Unrecognized command: ${cmd}.` };
+}
+
+export async function runCli({
+  argv = process.argv.slice(2),
+  stdout = process.stdout,
+  stderr = process.stderr,
+  runtime,
+  cwd = process.cwd(),
+} = {}) {
+  const fromTop = parseTopLevelCommand(argv);
+
+  switch (fromTop.kind) {
+    case "help": {
+      writeLines(stdout, buildCliHelpLines());
+      return 0;
+    }
+    case "category_help": {
+      writeLines(stdout, buildCategoryHelp(fromTop.category));
+      return 0;
+    }
+    case "subcommand_help": {
+      const result = spawnSync("node", [fromTop.scriptPath, "--help"], {
+        cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
+      });
+      if (result.stdout) stdout.write(result.stdout);
+      if (result.stderr) stderr.write(result.stderr);
+      return result.status ?? (result.signal ? 1 : result.error ? 1 : 0);
+    }
+    case "action": {
+      const activeRuntime = runtime ?? createCliRuntime({ adapter: createPiAdapter({ cwd }), cwd });
+      const result = await executeDevLoopsCommand({ input: argv, surface: "cli", runtime: activeRuntime, stdout });
+      switch (result.kind) {
+        case "help": { writeLines(stdout, buildCliHelpLines()); return 0; }
+        case "checks": {
+          const summary = summarizeChecks(result.checks);
+          const readiness = describeReadiness(result.checks);
+          const lines = [
+            `dev-loops ${result.action}: ${summary.ok}/${summary.total} checks passed`,
+            `Local loop readiness: ${readiness.localReady ? "ready" : "needs setup"}`,
+            `Remote GitHub/Copilot readiness: ${readiness.remoteReady ? "ready" : "needs setup"}`,
+          ];
+          if (result.action === "status") { lines.push("Suggested next steps:", ...orderedCliSetupSteps(result.checks)); }
+          else { lines.push(...renderCheckLines(result.checks)); }
+          writeLines(stdout, lines);
+          return 0;
+        }
+        case "unsupported": { writeLines(stderr, [result.message]); return 1; }
+        case "gates": { return 0; }
+        case "malformed": {
+          const lines = [result.message, ...buildCliHelpLines()];
+          if (result.usageAction) lines.splice(1, 0, ...buildCliUsageLines(result.usageAction));
+          writeLines(stderr, lines);
+          return 1;
+        }
+        default: throw new Error(`Unhandled CLI result: ${result.kind}`);
+      }
+    }
+    case "subcommand": {
+      if (fromTop.error) { writeLines(stderr, [fromTop.error]); return 1; }
+      const scriptArgs = fromTop.forwardedArgs || [];
+      const result = spawnSync("node", [fromTop.scriptPath, ...scriptArgs], {
+        cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
+      });
+      // Retry on usage/flag errors: parse usage for valid flags, retry once (#483)
+      if (result.status !== 0 && isUsageError(result.stderr)) {
+        const correctedArgs = buildCorrectedArgs(scriptArgs, result.stderr);
+        if (correctedArgs && correctedArgs.length > 0) {
+          const retryResult = spawnSync("node", [fromTop.scriptPath, ...correctedArgs], {
+            cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
+          });
+          if (retryResult.stdout) stdout.write(retryResult.stdout);
+          if (retryResult.stderr) stderr.write(retryResult.stderr);
+          return retryResult.status ?? (retryResult.signal ? 1 : retryResult.error ? 1 : 0);
+        }
+      }
+      if (result.stdout) stdout.write(result.stdout);
+      if (result.stderr) stderr.write(result.stderr);
+      return result.status ?? (result.signal ? 1 : result.error ? 1 : 0);
+    }
+    case "malformed": {
+      const lines = [fromTop.message, ...buildCliHelpLines()];
+      if (fromTop.usageAction) lines.splice(1, 0, ...buildCliUsageLines(fromTop.usageAction));
+      writeLines(stderr, lines);
+      return 1;
+    }
+    default:
+      throw new Error(`Unhandled parse result: ${fromTop.kind}`);
+  }
+}
+
+const invokedAsScript = (() => {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(path.resolve(process.argv[1]));
+  } catch { return false; }
+})();
+
+if (invokedAsScript) {
+  process.exitCode = await runCli();
+}

package/extension/README.md

@@ -0,0 +1,233 @@
+# Extension scaffold
+
+`dev-loops` ships a lightweight package extension for readiness UX plus one bounded local UI lifecycle seam.
+
+Installing the package exposes two thin wrappers over one shared deterministic core:
+- the Pi extension command family rooted at `/dev-loops`
+- the shell CLI entrypoint `dev-loops`
+- a bounded post-merge helper that queues one `pi update git:github.com/mfittko/dev-loops` after a successful in-session `gh pr merge ...` or `git merge ...` inside this repo and flushes it on `agent_end`
+
+Installing the package with `pi install git:github.com/mfittko/dev-loops` exposes the packaged skills through `package.json` `pi.skills`, and the extension syncs packaged agent files (`agents/*.agent.md`) into `~/.agents/` on `session_start`.
+
+## Command surface
+
+- `/dev-loops`
+  - defaults to help output for the available subcommands
+- `/dev-loops status`
+  - concise readiness summary plus lightweight next steps
+- `/dev-loops doctor`
+  - full diagnostic report with explicit pass/fail detail
+- `/dev-loops hide`
+  - removes the readiness widget cleanly
+- `/dev-loops inspect open [--repo <owner/name>]`
+  - start or reuse the managed local inspect-run viewer and best-effort open it in the browser
+- `/dev-loops inspect resume [--repo <owner/name>]`
+  - reattach only to a confirmed live managed inspect-run viewer; fails closed when nothing live is managed
+- `/dev-loops inspect status [--repo <owner/name>]`
+  - report one bounded local lifecycle state plus the current URL when known
+- `/dev-loops inspect stop [--repo <owner/name>]`
+  - stop only the recorded managed inspect-run viewer process
+- `/dev-loops inspect restart [--repo <owner/name>]`
+  - explicitly restart the recorded managed inspect-run viewer; never kill an unknown listener
+- `dev-loops`
+  - defaults to help output for the available subcommands
+- `dev-loops help`
+  - prints shell help for the shared command family
+- `dev-loops status`
+  - prints the concise readiness summary in shell-friendly output
+- `dev-loops doctor`
+  - prints the full diagnostic report in shell-friendly output
+- `dev-loops gates`
+  - prints active review angles with their prompts from config
+- `/dev-loops gates`
+  - same as above, but inside the Pi extension
+- `dev-loops hide`
+  - is intentionally unsupported and exits non-zero with a shell-friendly stderr message because `hide` is session-local Pi UI behavior
+
+## Inspect local UI lifecycle ownership
+
+This slice is intentionally narrow.
+
+Extension-owned behavior:
+- operator-facing lifecycle UX under `/dev-loops inspect ...`
+- repo-local managed-instance record at `.pi/ui-servers/inspect-run-viewer.json`
+- safe URL discovery, liveness checks, resume/reattach, stop, and explicit restart handling
+- best-effort browser open
+- fail-closed handling for stale ownership and unknown listeners
+
+Viewer-script-owned behavior:
+- HTTP server implementation
+- viewer HTML/JS rendering
+- inbox and query-state behavior
+- snapshot loading through the existing adapter
+- read-only route behavior and localhost safety rules
+
+Lifecycle states reported by the extension-managed seam are intentionally bounded to:
+- `running`
+- `stopped`
+- `stale_record`
+- `conflict_unmanaged_listener`
+
+Guard rails for this seam:
+- loopback-first local-only posture
+- no remote/public hosting
+- no generic local app platform
+- no background watcher/supervisor behavior
+- no inspect-run viewer redesign
+
+## Current readiness checks
+
+The extension currently reports on:
+- `gh` installed
+- `gh` authenticated
+- `subagent` command available
+- inside a git repository
+
+Readiness and help messaging should lead with `dev-loop` as the single public workflow entrypoint. Internal compatibility seams may still exist for runtime/routing purposes, but the readiness surface should not present them as separate user-facing checks or workflow choices.
+
+The messaging distinguishes between local loop readiness and remote GitHub/Copilot readiness. Missing `gh` or `gh auth` blocks remote-loop readiness, but does not imply that local phase-based work is completely unavailable.
+
+## Package install contract for this phase
+
+- `pi install git:github.com/mfittko/dev-loops` is the distribution mechanism for the extension, skills, scripts, packaged agents, and required installed runtime contract docs
+- `pi install -l git:github.com/mfittko/dev-loops` is the project-local replacement for the old `install repo` flow
+- `pi update git:github.com/mfittko/dev-loops` refreshes an installed package
+- source-tree canonical contract docs live under `skills/docs/`; installer/package output must ship this shared docs bundle with the installed skills subtree: [Public Dev Loop Contract](../skills/docs/public-dev-loop-contract.md) and [Retrospective Checkpoint Contract](../skills/docs/retrospective-checkpoint-contract.md)
+- installed skill/runtime guidance must read those bundled shared docs (from installed `skills/<skill>/`, resolve via `../docs/`) instead of assuming a source checkout is present; a missing bundled contract doc is a packaging/installer bug
+- packaged agents are refreshed into `~/.agents/` on each `session_start`
+- `/dev-loops install ...` and `/dev-loops update ...` are removed; use `pi install` / `pi update` directly instead
+
+## Configuration
+
+The dev-loop workflow is driven by a YAML config at `.pi/dev-loop/defaults.yaml` (shipped with the package) and an optional consumer settings file at `.devloops` at repo root (the loader also accepts `.devloops.yaml`, `.devloops.yml`, and `.devloops.json`; legacy `.pi/dev-loop/settings.*` and `overrides.*` still load as fallbacks with a deprecation warning).
+
+### How consumers customize config
+
+Create `.devloops` at your project root. It merges on top of the shipped defaults. Accepted formats: `.devloops` (bare, YAML-format), `.devloops.yaml`, `.devloops.yml`, or `.devloops.json`. Legacy `.pi/dev-loop/settings.*` and `overrides.*` still load as fallbacks with a deprecation warning. You can override any section, including workflow policy defaults:
+
+```yaml
+# Example: add a custom review angle with a dedicated persona agent
+gates:
+  preApproval:
+    angles:
+      - dry
+      - kiss
+      - yagni
+      - security    # your custom angle
+
+personas:
+  security:
+    persona: security-reviewer
+    prompt: >-
+      Audit for auth bypasses, secret leaks, insecure defaults,
+      unsafe command execution, and data exposure risks.
+    defaultModel: null
+
+  # Override an existing angle's prompt
+  dry:
+    persona: review
+    prompt: >-
+      Flag duplication. In this repo, also check for duplicated
+      contract language across docs/ and skills/.
+    defaultModel: null
+
+# Override gate requirements
+refinement:
+  fanOut: 5      # run 5 parallel review variants instead of 3
+
+autonomy:
+  stopAt:
+    - draft-pr
+    - merge        # stop for confirmation at both gates
+
+workflow:
+  requireRetrospective: true
+  requireRetrospectiveGate: true
+  requireDraftFirst: true
+  devModeDefault: true
+```
+
+### Available review angles
+
+The shipped defaults activate these angles. Additional angles are available as opt-in — add them to your `gates.draft.angles` or `gates.preApproval.angles` and they'll use the prompts defined in the personas registry. Opt-in prompts are generic and can be overridden in consumer repos through `personas.<angle>.prompt` without depending on this repository's audit examples.
+
+| Default (active) | Opt-in (add to gates) |
+|---|---|
+| `dry` — duplication | `ocp` — Open/Closed (extension over modification) |
+| `kiss` — over-engineering | `lsp` — Liskov Substitution (subtype contracts) |
+| `yagni` — speculative features | `isp` — Interface Segregation (fat interfaces) |
+| `srp` — Single Responsibility | `dip` — Dependency Inversion (abstractions) |
+| `soc` — Separation of Concerns | `docs` — documentation links, command references, stale docs |
+| `deep` — structural quality / deslop audit | |
+| `scope` — scope compliance (draft gate) | `link-check` — Markdown links, anchors, doc paths |
+| `coverage` — test coverage (draft gate) | `config-drift` — config/schema/docs/runtime disagreement |
+| `correctness` — acceptance criteria (draft gate) | `gate-evidence` — missing/stale gate-review PR evidence |
+| `ci-guard` — CI/workflow reproducibility (draft gate) | `no-op` — ineffective tool or command usage |
+| `contract-surface` — schema/runtime/docs plus CLI help/stdout/stderr drift (draft gate) | `input-validation` — CLI/API args, repo slugs, IDs, sentinels |
+| | `packaging-runtime` — installers, bundles, copied assets, runtime imports |
+| | `state-concurrency` — state files, locks, polling/process cleanup |
+| | `renderer-security` — HTML/attribute/URL escaping and user content |
+| | `determinism` — ordering, tie-breakers, strict stubs, env/time independence |
+
+### Workflow defaults
+
+The optional `workflow` family carries repo-level workflow posture without hardcoding it into prose-only guidance. Shipped defaults stay permissive:
+
+```yaml
+workflow:
+  requireRetrospective: false
+  requireRetrospectiveGate: false
+  requireDraftFirst: false
+  devModeDefault: false
+```
+
+- `requireRetrospective` — when enabled by repo settings, the next qualifying GitHub-first async start/resume must honor the retrospective checkpoint gate
+- `requireRetrospectiveGate` — when enabled by repo settings, merge readiness after `pre_approval_gate` requires a completed retrospective checkpoint that explicitly approves merge. The retrospective must include: `state: "complete"`, `mergeApproved: true`, `followedWorkingAgreement` (boolean), `gateQuality` (string), `unexpectedFindings` (string), and `mergeRecommendation` (string). A `SKIPPED` retrospective does not satisfy the merge gate when this flag is enabled.
+- `requireDraftFirst` — marks draft-first PR creation as required workflow policy for repos that opt in
+- `devModeDefault` — declares that local implementation should default to formal dev mode; this is config-only for now and establishes source-of-truth config plus docs for future runtime consumers
+
+### Config precedence
+
+1. Built-in defaults (`packages/core/src/config/config.mjs` `BUILT_IN_DEFAULTS`)
+2. Shipped defaults (`.pi/dev-loop/defaults.yaml` — committed in source repo)
+3. Consumer settings (`.devloops` at repo root — preferred; `.devloops.yaml`/`.devloops.yml`/`.devloops.json` also load; legacy `.pi/dev-loop/settings.*` and `overrides.*` still load as fallbacks with deprecation warning)
+
+### Adding custom review angles
+
+1. Add the angle name to `gates.draft.angles` or `gates.preApproval.angles`
+2. Add a `personas.<angle>` entry with a `persona` agent name and a `prompt` instruction
+3. Create the corresponding `Agent file` (`agents/<persona>.agent.md`) if using a new persona
+4. Optionally set a per-angle model override via `models.roles.<angle>`
+
+### Config format
+
+YAML is preferred (`.yaml` or `.yml`). JSON (`.json`) is supported as a fallback for backward compatibility. When both exist, YAML takes priority.
+
+Config is validated at runtime by Zod schemas (`packages/core/src/config/config.mjs`).
+
+## Runtime / build / test contract
+
+Current Phase 3+ contract:
+- Node runtime floor: `>=20` (from `package.json`)
+- Pi host expectations are documented from current peer dependencies rather than a tested pinned Pi version range
+- the extension is source-loaded from `./extension/index.ts` through `package.json` `pi.extensions`
+- the package exposes `skills` through `package.json` `pi.skills` for install-based global skill loading
+- the shell CLI is exposed through `package.json` `bin.dev-loops`
+- the extension syncs packaged agent files (`agents/*.agent.md`) into `~/.agents/` on `session_start` so user-level agents are available outside this repo
+- package install/update happens through `pi install` / `pi update`
+- this phase does not yet claim a specific supported `gh` version; it only checks `gh` presence and authentication state
+- this phase does not require a separate compiled build or `dist/` pipeline
+
+Root verification and test commands are intentionally explicit:
+- `npm run verify` is the canonical root verification path (`npm test` + `npm run test:dev-loop`)
+- `npm test` runs the current root test suite (`test:assets`, `test:extension`, `test:scripts`, and `test:core`)
+- `npm run test:extension`
+- `npm run test:extension` currently expands to one `node --import tsx --test ...` invocation in `package.json`; prefer the script entrypoint over copying the file list into downstream docs or runbooks
+- `npm run test:scripts`
+- `npm run test:assets`
+- `npm run test:dev-loop`
+- `npm run test:playwright:viewer` remains an explicit viewer/browser smoke, not part of the default root verify path
+
+## Design rule
+
+Both wrappers should stay thin. Shared workflow mechanics should live in deterministic `packages/core/` modules and `scripts/`, not in extension-only or CLI-only command logic. Runtime command support that bridges both surfaces belongs in `lib/dev-loops-core.mjs`. See [Library vs Packages Core Boundary](../docs/lib-vs-packages-core-boundary.md) for the full ownership rule.