omniconductor 0.5.0 → 1.0.1

package/bin/doctor.js

@@ -0,0 +1,257 @@
+'use strict';
+
+/*
+ * omniconductor doctor — read-only health check for an installed project (ADR-041).
+ *
+ * Anchors on <target>/.conductor-manifest.json and NEVER writes anything.
+ * The bash adapters remain the single source of truth for install logic
+ * (ADR-002/023/025) — doctor only inspects their output.
+ *
+ * Check groups:
+ *   D1 manifest validity     — exists, parses, has version + emitted_files
+ *   D2 version drift         — manifest version vs the running package version
+ *   D3 file integrity        — every manifest-emitted file still exists
+ *   D4 stale legacy paths    — adapter's legacy paths present in the target
+ *   D5 hook validity         — emitted .json parse; emitted .sh executable + `bash -n`
+ *   D6 doc-link liveness     — relative markdown links in emitted docs resolve
+ *   D7 stale claims          — emitted files scanned against tools/stale-tokens.txt
+ *
+ * Severity: FAIL = broken install · WARN = degraded/attention · OK.
+ * Exit codes: 0 = all OK · 1 = warnings only · 2 = failures (or unusable target).
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+
+function readPkgVersion() {
+  try { return JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version || null; }
+  catch { return null; }
+}
+
+function loadAdapterMetadata(adapter) {
+  try { return JSON.parse(fs.readFileSync(path.join(ROOT, 'adapters', adapter, 'metadata.json'), 'utf8')); }
+  catch { return null; }
+}
+
+// tools/stale-tokens.txt: pattern \t reason \t hint \t allow_regex?  (# = comment)
+function loadStaleTokens() {
+  let raw;
+  try { raw = fs.readFileSync(path.join(ROOT, 'tools', 'stale-tokens.txt'), 'utf8'); }
+  catch { return []; }
+  const rules = [];
+  for (const line of raw.split('\n')) {
+    const l = line.replace(/\r$/, '');
+    if (!l || l.startsWith('#')) continue;
+    const [pattern, reason, hint, allow] = l.split('\t');
+    if (!pattern) continue;
+    rules.push({ pattern, reason: reason || '', hint: hint || '', allow: allow || null });
+  }
+  return rules;
+}
+
+function inferAdapter(manifest, targetAbs) {
+  if (manifest && typeof manifest.adapter === 'string') return manifest.adapter;
+  // Pre-0.8.0 claude manifests carry no adapter field — infer from footprint.
+  if (fs.existsSync(path.join(targetAbs, '.claude', 'rules'))) return 'claude';
+  return null;
+}
+
+function run(targetDir, opts) {
+  const json = !!(opts && opts.json);
+  const results = []; // {id, status: 'OK'|'WARN'|'FAIL', detail}
+  const add = (id, status, detail) => results.push({ id, status, detail });
+
+  const targetAbs = path.resolve(process.cwd(), targetDir || '.');
+  const finish = () => {
+    const counts = { OK: 0, WARN: 0, FAIL: 0 };
+    for (const r of results) counts[r.status]++;
+    if (json) {
+      process.stdout.write(JSON.stringify({
+        doctor: readPkgVersion(), target: targetAbs, checks: results, summary: counts,
+      }, null, 2) + '\n');
+    } else {
+      for (const r of results) {
+        const pad = r.status === 'OK' ? 'OK  ' : (r.status === 'WARN' ? 'WARN' : 'FAIL');
+        process.stdout.write(`${pad} [${r.id}] ${r.detail}\n`);
+      }
+      process.stdout.write(`\n${counts.FAIL ? 'FAIL' : counts.WARN ? 'WARN' : 'OK'} — ${counts.OK} ok, ${counts.WARN} warn, ${counts.FAIL} fail (${targetAbs})\n`);
+      if (counts.FAIL || counts.WARN) {
+        process.stdout.write(`Re-install (safe: backups + manifest): npx omniconductor init --target=<tool> ${targetDir || '.'}\n`);
+      }
+    }
+    return counts.FAIL ? 2 : (counts.WARN ? 1 : 0);
+  };
+
+  if (!fs.existsSync(targetAbs) || !fs.statSync(targetAbs).isDirectory()) {
+    add('D1', 'FAIL', `target directory does not exist: ${targetAbs}`);
+    return finish();
+  }
+
+  // ---- D1 manifest validity ------------------------------------------------
+  const manifestPath = path.join(targetAbs, '.conductor-manifest.json');
+  let manifest = null;
+  if (!fs.existsSync(manifestPath)) {
+    add('D1', 'FAIL', `no .conductor-manifest.json in ${targetAbs} — not a CONDUCTOR install (or installed pre-manifest / uninstalled)`);
+    return finish();
+  }
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (e) {
+    add('D1', 'FAIL', `.conductor-manifest.json does not parse: ${e.message}`);
+    return finish();
+  }
+  if (typeof manifest.version !== 'string' || !Array.isArray(manifest.emitted_files)) {
+    add('D1', 'FAIL', `.conductor-manifest.json missing 'version' or 'emitted_files'`);
+    return finish();
+  }
+  if (manifest.emitted_files.length === 0) {
+    add('D1', 'FAIL', `.conductor-manifest.json has an empty 'emitted_files' — a real install always tracks files (manifest damaged or hand-edited?)`);
+    return finish();
+  }
+  // Every tracked path must be a non-empty RELATIVE path that stays inside the
+  // target — a forged/merge-damaged manifest must not let doctor read (or later
+  // checks reason about) files outside the install root.
+  const badPaths = [];
+  for (const ef of manifest.emitted_files) {
+    const p = ef && ef.path;
+    if (typeof p !== 'string' || !p.trim() || path.isAbsolute(p)) { badPaths.push(String(p)); continue; }
+    const resolved = path.resolve(targetAbs, p);
+    if (resolved !== targetAbs && !resolved.startsWith(targetAbs + path.sep)) badPaths.push(p);
+  }
+  if (badPaths.length) {
+    add('D1', 'FAIL', `manifest contains ${badPaths.length} invalid/escaping path(s): ${badPaths.slice(0, 4).join(', ')}${badPaths.length > 4 ? ', …' : ''}`);
+    return finish();
+  }
+  add('D1', 'OK', `manifest valid — ${manifest.emitted_files.length} tracked files, recipes: ${(manifest.recipes_enabled || []).join(', ') || '(none)'}`);
+
+  const adapter = inferAdapter(manifest, targetAbs);
+  const meta = adapter ? loadAdapterMetadata(adapter) : null;
+
+  // ---- D2 version drift ------------------------------------------------------
+  const pkgVersion = readPkgVersion();
+  const installedVersion = String(manifest.version).replace(/^v/, '');
+  if (!pkgVersion) {
+    add('D2', 'WARN', 'cannot read the running package version');
+  } else if (installedVersion === 'unknown' || installedVersion === '') {
+    add('D2', 'WARN', `manifest has no usable version stamp ('${manifest.version}')`);
+  } else if (installedVersion !== pkgVersion) {
+    add('D2', 'WARN', `installed by v${installedVersion}, running CLI is v${pkgVersion} — re-run init to refresh (backups + manifest keep it safe)`);
+  } else {
+    add('D2', 'OK', `install version matches running CLI (v${pkgVersion})`);
+  }
+
+  // ---- D3 file integrity -----------------------------------------------------
+  const missing = [];
+  for (const ef of manifest.emitted_files) {
+    if (!ef || typeof ef.path !== 'string') continue;
+    if (!fs.existsSync(path.join(targetAbs, ef.path))) missing.push(ef.path);
+  }
+  if (missing.length) {
+    add('D3', 'FAIL', `${missing.length} manifest-tracked file(s) missing: ${missing.slice(0, 6).join(', ')}${missing.length > 6 ? ', …' : ''}`);
+  } else {
+    add('D3', 'OK', 'all manifest-tracked files exist');
+  }
+
+  // ---- D4 stale legacy paths ---------------------------------------------------
+  if (!adapter) {
+    add('D4', 'WARN', 'manifest has no adapter field and footprint is ambiguous — skipping legacy-path check');
+  } else if (!meta) {
+    add('D4', 'WARN', `no metadata for adapter '${adapter}' in this package — skipping legacy-path check`);
+  } else {
+    const emitted = new Set(manifest.emitted_files.map((e) => e && e.path).filter(Boolean));
+    const staleLegacy = (meta.legacy_paths || []).filter((lp) => {
+      if (fs.existsSync(path.join(targetAbs, lp)) === false) return false;
+      // Intentional legacy emissions are manifest-tracked (e.g. --legacy-cursorrules).
+      if (emitted.has(lp) || manifest.legacy_cursorrules === true && lp === '.cursorrules') return false;
+      return true;
+    });
+    if (staleLegacy.length) {
+      add('D4', 'WARN', `legacy path(s) present alongside the modern install: ${staleLegacy.join(', ')} — the tool may read both; consider removing after migrating content`);
+    } else {
+      add('D4', 'OK', `no stale legacy paths (adapter: ${adapter})`);
+    }
+  }
+
+  // ---- D5 hook validity ---------------------------------------------------------
+  let hookProblems = 0, hookChecked = 0;
+  let bashAvailable = true;
+  for (const ef of manifest.emitted_files) {
+    if (!ef || typeof ef.path !== 'string') continue;
+    const abs = path.join(targetAbs, ef.path);
+    if (!fs.existsSync(abs)) continue; // D3 already reported it
+    if (ef.path.endsWith('.json')) {
+      hookChecked++;
+      try { JSON.parse(fs.readFileSync(abs, 'utf8')); }
+      catch (e) { hookProblems++; add('D5', 'FAIL', `${ef.path} is not valid JSON: ${e.message}`); }
+    } else if (ef.path.endsWith('.sh')) {
+      hookChecked++;
+      try { fs.accessSync(abs, fs.constants.X_OK); }
+      catch { hookProblems++; add('D5', 'FAIL', `${ef.path} is not executable (chmod +x)`); }
+      if (bashAvailable) {
+        const r = spawnSync('bash', ['-n', abs], { stdio: 'pipe' });
+        if (r.error) { bashAvailable = false; add('D5', 'WARN', 'bash not available — skipping syntax checks'); }
+        else if (r.status !== 0) { hookProblems++; add('D5', 'FAIL', `${ef.path} has a bash syntax error`); }
+      }
+    }
+  }
+  if (hookProblems === 0) add('D5', 'OK', `hook/config surfaces sane (${hookChecked} .json/.sh file(s) checked)`);
+
+  // ---- D6 doc-link liveness -------------------------------------------------------
+  let deadLinks = 0, docsChecked = 0;
+  const linkRe = /\[[^\]]*\]\(([^)\s]+)\)/g;
+  for (const ef of manifest.emitted_files) {
+    if (!ef || typeof ef.path !== 'string' || !ef.path.endsWith('.md')) continue;
+    const abs = path.join(targetAbs, ef.path);
+    if (!fs.existsSync(abs)) continue;
+    docsChecked++;
+    const src = fs.readFileSync(abs, 'utf8');
+    let m;
+    while ((m = linkRe.exec(src)) !== null) {
+      const href = m[1];
+      if (/^(https?:|mailto:|#)/.test(href)) continue;
+      const dest = path.resolve(path.dirname(abs), href.split('#')[0]);
+      if (!fs.existsSync(dest)) {
+        deadLinks++;
+        if (deadLinks <= 5) add('D6', 'WARN', `${ef.path}: dead relative link → ${href}`);
+      }
+    }
+  }
+  if (deadLinks === 0) add('D6', 'OK', `relative links resolve in ${docsChecked} emitted doc(s)`);
+  else if (deadLinks > 5) add('D6', 'WARN', `…and ${deadLinks - 5} more dead link(s)`);
+
+  // ---- D7 stale claims ---------------------------------------------------------------
+  const rules = loadStaleTokens();
+  if (!rules.length) {
+    add('D7', 'WARN', 'tools/stale-tokens.txt not found in this package — skipping stale-claim scan');
+  } else {
+    let staleHits = 0;
+    for (const ef of manifest.emitted_files) {
+      if (!ef || typeof ef.path !== 'string') continue;
+      if (!/\.(md|sh|mdc|json|toml)$/.test(ef.path) && !/(^|\/)\.(windsurfrules|cursorrules)$/.test(ef.path)) continue;
+      const abs = path.join(targetAbs, ef.path);
+      if (!fs.existsSync(abs)) continue;
+      const lines = fs.readFileSync(abs, 'utf8').split('\n');
+      for (const rule of rules) {
+        let allowRe = null;
+        if (rule.allow) { try { allowRe = new RegExp(rule.allow); } catch { allowRe = null; } }
+        for (const line of lines) {
+          if (!line.includes(rule.pattern)) continue;
+          if (line.includes('stale-ok:')) continue;
+          if (allowRe && allowRe.test(line)) continue;
+          staleHits++;
+          if (staleHits <= 5) add('D7', 'WARN', `${ef.path}: stale claim '${rule.pattern}' (${rule.reason}) — re-install to refresh`);
+          break; // one report per rule per file
+        }
+      }
+    }
+    if (staleHits === 0) add('D7', 'OK', 'no known-stale claims in emitted files');
+    else if (staleHits > 5) add('D7', 'WARN', `…and ${staleHits - 5} more stale claim(s)`);
+  }
+
+  return finish();
+}
+
+module.exports = { run };

package/bin/omniconductor.js

@@ -7,13 +7,15 @@
  * Usage:
  *   omniconductor init --target=<tool> [target-dir] [--recipes=a,b] [--dry-run] [--no-prompt]
  *   omniconductor init --target=<tool> [target-dir] --uninstall [--force]
+ *   omniconductor doctor [target-dir] [--json]
  *   omniconductor list
  *   omniconductor --help | --version
  *
  * It does NOT reimplement any install logic. It locates this repo's
  * adapters/<tool>/transform.sh and runs it with `bash`, forwarding all flags
  * and inheriting stdio. The shell adapters remain the single source of truth
- * (ADR-018 / the bash adapters are the validated implementation).
+ * (ADR-002/023/025 — the bash adapters are the validated implementation).
+ * `doctor` (ADR-041) is read-only: it inspects an install, never changes it.
  */
 
 const path = require('path');
@@ -36,6 +38,7 @@ function usage() {
 
 Usage:
   omniconductor init --target=<tool> [target-dir] [options]   Install into target-dir (default: .)
+  omniconductor doctor [target-dir] [--json]                  Health-check an existing install (read-only)
   omniconductor list                                          List available tool adapters
   omniconductor --help | --version
 
@@ -43,6 +46,8 @@ Tools: ${TOOLS.join(', ')}
 
 Common options (forwarded to the adapter):
   --recipes=a,b,c     Opt-in recipes to install
+  --mode=<m>          Install preset: full (default) | minimal | strict |
+                      recipes-only | reflector-only (ADR-044)
   --dry-run           Preview only — write nothing
   --no-prompt         Skip interactive prompts (CI-safe)
   --uninstall         Revert a previous install (manifest-based)
@@ -52,6 +57,7 @@ Examples:
   omniconductor init --target=claude ./my-app --recipes=tdd,debugging
   omniconductor init --target=cursor ./my-app --dry-run
   omniconductor init --target=codex . --uninstall
+  omniconductor doctor ./my-app --json
 
 Run:  npx omniconductor init --target=<tool> <dir>`;
 }
@@ -85,8 +91,15 @@ function main(argv) {
     return 0;
   }
 
+  if (cmd === 'doctor') {
+    const rest = args.slice(1);
+    const jsonOut = rest.includes('--json');
+    const dir = rest.find((a) => !a.startsWith('-')) || '.';
+    return require('./doctor.js').run(dir, { json: jsonOut });
+  }
+
   if (cmd !== 'init') {
-    fail(`unknown command '${cmd}'. Expected 'init' or 'list'.`);
+    fail(`unknown command '${cmd}'. Expected 'init', 'doctor', or 'list'.`);
   }
 
   // Parse `init` args: extract --target, the positional target-dir, forward the rest.

package/core/anti-patterns/frequent-rule-file-edit.md

@@ -54,7 +54,7 @@ If the rule file is edited daily, every session starts with a fresh cache write
 ```bash
 # Edits per week to top-of-prefix files
 git log --since='1 week ago' --pretty=format:'%h %s' -- \
-  CLAUDE.md AGENT.md GEMINI.md .codex/codex.md \
+  CLAUDE.md AGENT.md AGENTS.md GEMINI.md \
   .claude/rules/*.md .cursor/rules/*.mdc 2>/dev/null | wc -l
 
 # Anything > 3 in a week is suspect

package/core/anti-patterns/single-monolithic-rule-file.md

@@ -52,7 +52,7 @@ Two corollaries:
 
 ```bash
 # Find oversized rule files
-wc -l CLAUDE.md AGENT.md GEMINI.md .codex/codex.md 2>/dev/null | \
+wc -l CLAUDE.md AGENT.md AGENTS.md GEMINI.md 2>/dev/null | \
   awk '$1 > 500 { print }'
 ```
 

package/core/hooks/README.md

@@ -15,6 +15,7 @@ CONDUCTOR's universal hook spec. Templates here are compiled into native shell s
 | `stop-cache-hit-baseline-check.sh.template` | Session stop event | Non-blocking diagnostic — reads the latest session JSONL, computes cache hit rate, reminds when below baseline (token-economy). Fail-open. Override env disables: `CONDUCTOR_SKIP_CACHE_CHECK=1`. | Claude `.claude/hooks/stop-cache-hit-baseline-check.sh` |
 | `stop-trajectory-log.sh.template` | Session stop event | Non-blocking — reads `transcript_path` + `session_id` from the Stop hook's **stdin** (exact provenance; no `~/.claude/projects` dir-scan) and **upserts** one pointer record per session (session id, transcript path, git HEAD, cwd) into `.conductor/trajectories/index.jsonl` for the Reflector (recipes/self-improvement.md). Same stdin approach as the non-Claude portable logger `core/reflector/trajectory-log.sh`. **Opt-in gated: no-ops unless `.conductor/reflect/` exists** (created only by the self-improvement recipe). Anchors to the project root; fail-open. Override: `CONDUCTOR_SKIP_TRAJLOG=1`. | Claude `.claude/hooks/stop-trajectory-log.sh` |
 | `stop-git-hygiene-guard.sh.template` | Session stop event | Non-blocking — detects git-hygiene collapse (extra worktrees, local-only commits not on any remote, abnormally many local branches) and injects a cleanup reminder per `recipes/git-hygiene.md` (G1/G2/G3/G7). **Opt-in gated: no-ops unless `.claude/rules/git-hygiene.md` exists** (created only by the git-hygiene recipe). Anchors to the project root; 15-min cool-down; fail-open, always exits 0. Overrides: `CONDUCTOR_SKIP_GIT_HYGIENE=1`, `CONDUCTOR_GIT_HYGIENE_BRANCH_MAX` (default 20). | Claude `.claude/hooks/stop-git-hygiene-guard.sh` |
+| `pretool-loop-guard.sh.template` | Before each tool call (PreToolUse, `*` matcher) | Non-blocking soft-warn (`permissionDecision: ask`) — tracks a per-session signature of each tool call and surfaces a reminder when the **same action repeats** ≥ `CONDUCTOR_LOOP_REPEAT_MAX` (default 5; oscillation/no-progress) or the session's **total tool calls** ≥ `CONDUCTOR_LOOP_BUDGET` (default 120; runaway), per `recipes/loop-engineering.md` (G2/G3/G6). **Opt-in gated: no-ops unless `.claude/rules/loop-engineering.md` exists.** Per-session cool-down (`CONDUCTOR_LOOP_COOLDOWN_SECONDS`, default 120); trace in `$TMPDIR`, not the repo; fail-open, always exits 0. Override: `CONDUCTOR_SKIP_LOOP_GUARD=1`. | Claude `.claude/hooks/pretool-loop-guard.sh` |
 
 The two `pretool-commit-*` templates are **soft `ask` warns**: they emit
 `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":...}}`,

package/core/hooks/pretool-loop-guard.sh.template

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+#
+# CONDUCTOR universal hook template
+# hook_id: pretool-loop-guard
+# trigger: pretool
+# action: Before each tool call, track a per-session signature of the call and
+#         soft-warn (non-blocking "ask") when the SAME action repeats too often
+#         (oscillation / no-progress loop) or the session's total tool calls
+#         exceed a budget (runaway loop). Enforces the loop-engineering recipe.
+# compile_targets: claude
+# fallback: rule-text-reminder
+#
+# Generated by adapters/<tool>/transform.sh.
+#
+# Enforces:
+#   - recipes/loop-engineering.md (bound the loop: iteration budget G2, no-progress
+#     halt G3, oscillation/infinite-loop guard G6)
+#
+# Behavior (fail-open, non-blocking):
+#   1. No-op unless the loop-engineering recipe is installed (self-gate on
+#      .claude/rules/loop-engineering.md).
+#   2. Per session, keep a trace of tool-call signatures in a private tmp file.
+#      A "signature" = tool_name + hash(tool_input): identical calls collide.
+#   3. Warn (permissionDecision:ask + reason) when the CURRENT signature has
+#      occurred >= REPEAT_MAX times (same action repeated — likely looping without
+#      progress), OR the session's total tool calls >= BUDGET (runaway). A per-
+#      session cool-down keeps it from firing on every subsequent call.
+#   4. ALWAYS exit 0. Any error, missing input, or missing python3 → allow silently.
+#      "ask" surfaces the reason and routes to the permission flow — it does NOT
+#      hard-block and does NOT auto-approve (same contract as the other pretool
+#      soft-warns).
+#
+# Overrides (runtime env, not compile-time placeholders):
+#   CONDUCTOR_SKIP_LOOP_GUARD=1        disable entirely
+#   CONDUCTOR_LOOP_REPEAT_MAX          same-action repeat threshold (default 5)
+#   CONDUCTOR_LOOP_BUDGET              total tool-calls-per-session threshold (default 120)
+#   CONDUCTOR_LOOP_COOLDOWN_SECONDS    min seconds between warns per session (default 120)
+
+set -u
+
+# Honor opt-out before any work.
+[ "${CONDUCTOR_SKIP_LOOP_GUARD:-}" = "1" ] && exit 0
+
+# Anchor to the project root (emitted hook lives at <project>/.claude/hooks/).
+_self_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)" || exit 0
+_proj_root="$(cd "$_self_dir/../.." 2>/dev/null && pwd)" || exit 0
+cd "$_proj_root" 2>/dev/null || exit 0
+
+# Self-gate: only act when the loop-engineering recipe is installed.
+[ -f ".claude/rules/loop-engineering.md" ] || exit 0
+
+# Robust JSON handling needs python3; without it, degrade to silent allow.
+command -v /usr/bin/python3 >/dev/null 2>&1 || exit 0
+
+# Read the PreToolUse payload from stdin (no piped stdin → nothing to do).
+export PAYLOAD_RAW="$(/bin/cat 2>/dev/null || true)"
+[ -n "${PAYLOAD_RAW:-}" ] || exit 0
+
+# All logic lives in python for safe parsing / hashing / file IO. It prints EITHER
+# the ask-JSON (when a threshold is crossed and not cooling down) or nothing. Any
+# exception prints nothing → the shell falls through to `exit 0` (allow).
+REPEAT_MAX="${CONDUCTOR_LOOP_REPEAT_MAX:-5}" \
+BUDGET="${CONDUCTOR_LOOP_BUDGET:-120}" \
+COOLDOWN="${CONDUCTOR_LOOP_COOLDOWN_SECONDS:-120}" \
+/usr/bin/python3 -c '
+import json, os, sys, hashlib, re, time, tempfile
+
+def out_nothing():
+    sys.exit(0)
+
+try:
+    raw = os.environ.get("PAYLOAD_RAW", "") or ""
+    d = json.loads(raw)
+    if not isinstance(d, dict):
+        out_nothing()
+
+    tool = d.get("tool_name", "") or ""
+    if not tool:
+        out_nothing()  # no identifiable action → nothing to track
+
+    tool_input = d.get("tool_input", {})
+    session = d.get("session_id", "") or d.get("sessionId", "") or "nosession"
+
+    # Sanitize identifiers used in file paths (defense against path injection).
+    session = re.sub(r"[^A-Za-z0-9_-]", "", str(session))[:64] or "nosession"
+    user = re.sub(r"[^A-Za-z0-9_-]", "", os.environ.get("USER", "") or "unknown")[:32] or "unknown"
+
+    # Thresholds (env-tunable, with safe fallbacks on garbage input).
+    def envint(name, default):
+        try:
+            v = int(os.environ.get(name, "") or default)
+            return v if v > 0 else default
+        except Exception:
+            return default
+    repeat_max = envint("REPEAT_MAX", 5)
+    budget = envint("BUDGET", 120)
+    cooldown = envint("COOLDOWN", 120)
+
+    # Signature = tool + stable hash of its input. Identical calls collide;
+    # a canonical (sorted-key) dump makes key order irrelevant.
+    try:
+        payload = json.dumps(tool_input, sort_keys=True, ensure_ascii=True, default=str)
+    except Exception:
+        payload = repr(tool_input)
+    sig = tool + ":" + hashlib.sha1(payload.encode("utf-8", "replace")).hexdigest()[:16]
+
+    tmp = tempfile.gettempdir()
+    base = os.path.join(tmp, "conductor-loop-%s-%s" % (user, session))
+    trace_path = base + ".trace"
+    cooldown_path = base + ".cooldown"
+
+    # Append this signature, then read the (bounded) trace back.
+    try:
+        with open(trace_path, "a", encoding="utf-8") as f:
+            f.write(sig + "\n")
+    except Exception:
+        out_nothing()  # cannot persist → cannot reason about the loop; allow.
+
+    try:
+        with open(trace_path, "r", encoding="utf-8") as f:
+            lines = f.read().splitlines()
+    except Exception:
+        out_nothing()
+
+    # Bound work: only the last N entries matter for a runaway/oscillation view.
+    if len(lines) > 5000:
+        lines = lines[-5000:]
+
+    total = len(lines)
+    same = sum(1 for x in lines if x == sig)
+
+    hit_repeat = same >= repeat_max
+    hit_budget = total >= budget
+    if not (hit_repeat or hit_budget):
+        out_nothing()
+
+    # Cool-down: at most one warn per `cooldown` seconds per session.
+    now = int(time.time())
+    try:
+        with open(cooldown_path, "r", encoding="utf-8") as f:
+            last = int((f.read().strip() or "0"))
+    except Exception:
+        last = 0
+    if now - last < cooldown:
+        out_nothing()
+    try:
+        with open(cooldown_path, "w", encoding="utf-8") as f:
+            f.write(str(now))
+    except Exception:
+        pass  # cool-down is best-effort; still warn this once.
+
+    if hit_repeat:
+        reason = ("[loop-guard] The same action (%s) has run %d times this session — "
+                  "you may be looping without progress (recipe G3/G6). Before repeating: "
+                  "confirm each iteration changes state, verify with an EXTERNAL check "
+                  "(tests/rules/tool output — not self-judgment), and if stuck after a few "
+                  "tries, stop and ask rather than loop (G4). " % (tool, same))
+    else:
+        reason = ("[loop-guard] %d tool calls this session — approaching a runaway loop "
+                  "(recipe G2 iteration budget). Confirm you are converging on an explicit "
+                  "done-criterion, not spinning. " % total)
+    reason += "(Silence: CONDUCTOR_SKIP_LOOP_GUARD=1; tune CONDUCTOR_LOOP_REPEAT_MAX / CONDUCTOR_LOOP_BUDGET.)"
+
+    print(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "ask",
+            "permissionDecisionReason": reason,
+        }
+    }))
+except SystemExit:
+    raise
+except Exception:
+    # Absolutely never fail a tool call because of this guard.
+    pass
+'
+exit 0

package/core/recipes/README.md

@@ -2,7 +2,7 @@
 
 Per ADR-013, CONDUCTOR ships project-specific recipes as OPT-IN. They are not loaded by default. Adopters select the recipes that match their project and the adapter wires them into the appropriate native location.
 
-## The 12 recipes
+## The 13 recipes
 
 | File | When to install |
 |---|---|
@@ -18,6 +18,7 @@ Per ADR-013, CONDUCTOR ships project-specific recipes as OPT-IN. They are not lo
 | `design-system.md` | Project maintains a design-token system (color/spacing/typography tokens). Ships 1 recipe-scoped hookify rule (raw-hex-instead-of-token) — see ADR-028 |
 | `self-improvement.md` | Project wants a periodic, human-approved Reflector that distils session lessons into memory/rules. Propose-only; nothing auto-applies. Drives the `reflector` role — see ADR-030 |
 | `git-hygiene.md` | Any git project — esp. repos worked by multiple sessions/agents or with protected branches. Shared-repo discipline (no orphan worktrees, push-don't-hoard, merge=delete-branch, backup≠applied). Ships a Claude-only Stop-hook reminder (`stop-git-hygiene-guard`); other tools use the rule text — see ADR-037 |
+| `loop-engineering.md` | Any agentic loop (generate→verify→fix→re-verify, test-fix, multi-step). Bounded, externally-verified loops: explicit done-criterion, iteration+token budget, require-progress, escalate-on-stall, verify-externally-not-self-judgment, oscillation guard. Ships a Claude-only PreToolUse reminder (`pretool-loop-guard`); other tools use the rule text — see ADR-038 |
 
 ## Selection patterns
 
@@ -28,8 +29,9 @@ Per ADR-013, CONDUCTOR ships project-specific recipes as OPT-IN. They are not lo
 | Multi-locale SaaS | `i18n` + `coding-conventions` + `tdd` + `debugging` |
 | Relational-DB-backed SaaS (migrations + dev/prod) | `database-discipline` + `coding-conventions` + `tdd` + `debugging` |
 | Token-driven design system (theming / dark-mode) | `design-system` + `coding-conventions` + `tdd` + `debugging` |
-| Full-stack SaaS with web + mobile + i18n | All 12 |
+| Full-stack SaaS with web + mobile + i18n | All 13 |
 | Any git repo, esp. shared / multi-session | add `git-hygiene` to any of the above |
+| Agentic / iterative loops (fix-verify, test-fix) | add `loop-engineering` to any of the above |
 | Greenfield experiment | None — universal-rules + roles only is enough |
 
 ## How adapters consume these files
@@ -42,7 +44,7 @@ Adapter `transform.sh` accepts a `--recipes=<comma-separated-list>` flag (or per
 | Cursor | `.cursor/rules/<recipe>.mdc` |
 | Copilot | `.github/instructions/<recipe>.instructions.md` |
 | Gemini | Section in `GEMINI.md` |
-| Codex | Section in `.codex/codex.md` |
-| Windsurf | `.windsurf/rules/<recipe>.md` |
+| Codex | Section in `AGENTS.md` |
+| Windsurf | `.devin/rules/<recipe>.md` (legacy `.windsurf/rules/` still read) |
 
 Recipes are layered on TOP of universal-rules. They never override; they extend.

package/core/recipes/loop-engineering.md

@@ -0,0 +1,73 @@
+---
+recipe_id: loop-engineering
+recipe_name: "Loop Engineering (bounded, externally-verified agent loops)"
+applies_when: "any agentic coding work that iterates — generate→verify→fix→re-verify, test-fix loops, multi-step tasks"
+severity: STRONG (when installed)
+linked_rules:
+  - quality-gates
+  - meta-discipline
+  - workflow
+---
+
+# Recipe — Loop Engineering
+
+> Opt-in recipe. Install for any project where the agent works in a **loop** — "do → check → fix → re-check until done." It codifies how to run that loop so it **terminates correctly, stays bounded, and never declares success without an external check.** Install if you want agent loops that are reliable instead of ones that thrash, run away, or report "done" on unverified work.
+
+## Why this exists
+
+An agent that loops "until it's right" fails in a few well-documented ways. The evidence (peer-reviewed + Anthropic primary sources) is blunt:
+
+- **Self-correction without an external signal is unreliable and can make things WORSE.** Models asked to fix their own work with no external feedback often flip correct answers to wrong ones (*LLMs Cannot Self-Correct Reasoning Yet*, Huang et al., DeepMind, ICLR'24). The real gains come from loops grounded in **tests/tools** (Reflexion, CRITIC), not self-judgment.
+- **"The model says it's done" is not evidence.** LLM self-assessment is systematically over-confident, and LLM-as-judge carries position/verbosity/self-preference bias (*Judging LLM-as-a-Judge*, Zheng et al., NeurIPS'23). Declaring victory without running the check ("early victory") is the most common fidelity failure.
+- **Unbounded loops run away.** Infinite / oscillation (edit↔revert) loops are a documented structural failure — in one study **95.6% ended in cost exhaustion / model-DoS** (*When Agents Do Not Stop*, 2026). More iterations help only up to a point, then *saturate and hurt*; long trajectories degrade (context rot, error compounding).
+
+So a good loop is **bounded, progress-checked, and terminated by an external verifier** — not by the model's opinion. Prose gets forgotten, so on the Claude adapter this recipe is backed by a `pretool-loop-guard` hook.
+
+## The loop shape (well-supported)
+
+```
+Plan → (act → verify) loop → replan on failure → escalate on repeated stall
+```
+
+- **Plan first**, then act (ReAct: interleave reason+act+observe beats act-only).
+- On a failed check, **reflect and replan** using the failure (Reflexion) — not a blind retry.
+- Reserve expensive search/branching (Tree-of-Thoughts) for genuinely exploratory tasks; the default loop stays simple (Anthropic: "the simplest solution possible; add complexity only when it demonstrably improves outcomes").
+
+## The 6 obligations
+
+### G1 — Terminate on an explicit, verified done-criterion
+Before looping, state what "done" IS (a passing test, a matching value, a satisfied spec item). The loop ends when that criterion is **verified true** — never on a vibe or a word-count of effort.
+
+### G2 — Bound the loop (iteration + token budget)
+Set a ceiling before you start: a max number of iterations AND a token/time budget. When the ceiling is hit, **stop and report** (with what's done and what's left) — do not silently keep going. Anthropic ships this as `max_turns` / `max_budget_usd` ("a good default for production agents").
+
+### G3 — Require progress each iteration
+Every pass must change state toward the goal. If an iteration produces no new information or the same result, that is a **no-progress signal** — stop and rethink rather than repeat. (More iterations past the point of progress saturate, then degrade quality.)
+
+### G4 — Escalate on stall, don't loop forever
+After a small number of failed/no-progress iterations (default ~3–5), **hand back to the human** with the state and the blocker, instead of looping. Ties to `meta-discipline.md` AMB — when stuck or the next step is non-trivially reversible, ASK.
+
+### G5 — Verify externally, never by self-judgment (the core rule)
+A loop's exit signal MUST be an **external / ground-truth check** — run the test, execute the code, lint against the rule, diff the value — **not** the model asserting "looks correct." Verify hierarchy (Anthropic, strongest first):
+
+1. **Rules / tests / tool output** — deterministic, best (e.g. run the test suite; lint TS instead of eyeballing).
+2. **Visual / rendered feedback** — screenshots, output diffs.
+3. **LLM-as-judge** — weakest, last resort, and never the sole gate.
+
+This is `quality-gates.md` Q4 (verify-after-changes) applied inside the loop. "Declared done without running the check" = the early-victory anti-pattern; it is a rule violation here.
+
+### G6 — Guard against oscillation / infinite loops
+Detect and break repetition: the same action repeated, or an edit↔revert cycle, means the loop is spinning. Track what you've already tried; if you're repeating, **change approach or escalate (G4)** — never keep re-issuing the same failing action.
+
+## Conductor Integration
+
+- **Claude** — a PreToolUse hook `pretool-loop-guard` (from `core/hooks/`) tracks a per-session signature of each tool call and fires a **non-blocking soft-warn** (`permissionDecision: ask`) when the **same action repeats too often** (G3/G6 — likely looping without progress) or the **session's total tool calls exceed a budget** (G2 — runaway). It self-gates on this recipe being installed, is fail-open (never blocks a tool call on error), and honors `CONDUCTOR_SKIP_LOOP_GUARD=1`, `CONDUCTOR_LOOP_REPEAT_MAX` (default 5), `CONDUCTOR_LOOP_BUDGET` (default 120), `CONDUCTOR_LOOP_COOLDOWN_SECONDS` (default 120).
+- **Cursor / Copilot / Gemini / Codex / Windsurf** — the hook is Claude-only (per `docs/DESIGN-DECISIONS.md` ADR-034/ADR-038). On these tools this recipe's rule text is the enforcement: follow G1–G6 by discipline (the loop shape + external-verify rule are tool-agnostic).
+
+## Cross-References
+
+- `quality-gates.md` §4 (verify-after-changes) — G5's external-verify rule is Q4 applied inside the loop.
+- `meta-discipline.md` §3 (AMB) — G4's escalate-on-stall / ASK-when-stuck gate.
+- `meta-discipline.md` §5.9 (output brevity) + §5.7 — G2's token budget shares the token-economy ceiling.
+- `tdd.md` / `debugging.md` recipes — concrete instances of a G1–G6 loop (Red-Green; reproduce→root-cause→fix→regression).
+- `self-improvement.md` recipe — the session-level Reflector loop is itself a G1–G6 instance (propose → human-verify → apply).

package/core/universal-rules/README.md

@@ -52,11 +52,11 @@ Adapters do not strip these callouts. The honest acknowledgment of degraded enfo
 | Adapter | Output |
 |---|---|
 | Claude | One file per bundle under `.claude/rules/` with `paths:` frontmatter. Universal bundles also referenced from `CLAUDE.md`. |
-| Cursor | One `.mdc` per bundle under `.cursor/rules/` with `globs:` frontmatter. Bundles summarized in `.cursorrules`. |
-| Copilot | One `.instructions.md` per bundle under `.github/instructions/` with `applyTo:` frontmatter. |
+| Cursor | One `.mdc` per bundle under `.cursor/rules/` (`alwaysApply: true`; recipes get `globs:`). Optional legacy `.cursorrules` bundle via `--legacy-cursorrules`. |
+| Copilot | All bundles merged into `.github/copilot-instructions.md` (default) or one `.instructions.md` per bundle under `.github/instructions/` with `--per-rule`. |
 | Gemini | All bundles concatenated into `GEMINI.md`, sectioned. |
-| Codex | All bundles concatenated into `.codex/codex.md`. |
-| Windsurf | One file per bundle under `.windsurf/rules/`. |
+| Codex | All bundles concatenated into `AGENTS.md` (project root). |
+| Windsurf | One file per bundle under `.devin/rules/` (legacy `.windsurf/rules/` still read). |
 
 See `adapters/<tool>/transform-spec.md` for the exact transformation per adapter.