continuous-improvement 3.19.0 → 3.20.4

package/plugins/continuous-improvement/scripts/run-synthetic.mjs

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+/**
+ * Phase 9 Synthetic-Checks Runner
+ *
+ * Executes every *.synthetic.{sh,mjs,ts,py} file in --dir (default
+ * synthetic-checks/) in lexical order. Injects the documented env vars
+ * (BASE_URL, BASELINE_URL, EXPECTED_SHA, DEPLOY_BRANCH, RECEIPT_TIMESTAMP),
+ * captures stdout + stderr + exit per check, aggregates.
+ *
+ * Pure aggregator: required-env enforcement lives in the synthetic checks
+ * themselves (a check exits 2 when its own input contract is unmet, per
+ * synthetic-checks/README.md). The runner forwards env, propagates exit
+ * categories, and prints the operator-facing report.
+ *
+ * Contract: synthetic-checks/README.md
+ * Skill: skills/verification-loop.md (Phase 9 — production-vs-baseline diff)
+ *
+ * Exit codes:
+ *   0 — every recognized check exited 0, OR directory empty/absent
+ *   1 — at least one check exited non-zero (drift) or hit the wall-clock cap
+ *   2 — at least one check exited 2 (config error) AND zero drift
+ *   3 — runner-level usage error (bad flag, --timeout not a positive int)
+ *
+ * Flags:
+ *   --dir <path>       synthetic-checks/  Directory to walk
+ *   --timeout <sec>    60                 Per-check wall-clock cap
+ *   --fail-fast        off                Halt on first drift or timeout
+ *                                         (config_error does not halt — gate
+ *                                         did not run is not the same as drift)
+ *   --json             off                Emit machine-readable summary
+ *   --show-command     off                Print interpreter map, do not execute
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { argv, env, exit, stderr, stdout } from "node:process";
+import { parseArgs } from "node:util";
+
+const INTERPRETER_MAP = {
+  ".sh": "bash",
+  ".mjs": "node",
+  ".ts": "tsx",
+  ".py": "python",
+};
+
+const FORWARDED_ENV = [
+  "BASE_URL",
+  "BASELINE_URL",
+  "EXPECTED_SHA",
+  "DEPLOY_BRANCH",
+  "RECEIPT_TIMESTAMP",
+];
+
+const SYNTHETIC_FILE_RE = /\.synthetic\.[A-Za-z0-9]+$/;
+
+function parseFlags() {
+  try {
+    const { values } = parseArgs({
+      args: argv.slice(2),
+      options: {
+        dir: { type: "string", default: "synthetic-checks/" },
+        timeout: { type: "string", default: "60" },
+        "fail-fast": { type: "boolean", default: false },
+        json: { type: "boolean", default: false },
+        "show-command": { type: "boolean", default: false },
+      },
+      strict: true,
+    });
+    return values;
+  } catch (err) {
+    stderr.write(`usage error: ${err.message}\n`);
+    stderr.write("Run with no arguments to see defaults; --dir/--timeout/--fail-fast/--json/--show-command are the supported flags.\n");
+    exit(3);
+  }
+}
+
+function showCommand(dir) {
+  stdout.write(`Phase 9 runner — interpreter map (dry run for ${dir}):\n`);
+  for (const [ext, bin] of Object.entries(INTERPRETER_MAP)) {
+    stdout.write(`  ${ext} -> ${bin}\n`);
+  }
+  stdout.write("\nForwarded env vars (runner -> child):\n");
+  for (const name of FORWARDED_ENV) {
+    const present = env[name] !== undefined ? "set" : "unset";
+    stdout.write(`  ${name} (${present})\n`);
+  }
+  stdout.write("\nNo checks were executed. Re-run without --show-command to invoke.\n");
+}
+
+function listChecks(dir) {
+  if (!existsSync(dir)) return null;
+  try {
+    if (!statSync(dir).isDirectory()) return null;
+  } catch {
+    return null;
+  }
+  return readdirSync(dir)
+    .filter((name) => SYNTHETIC_FILE_RE.test(name))
+    .sort();
+}
+
+function runOne(filePath, timeoutMs) {
+  const ext = extname(filePath);
+  const interpreter = INTERPRETER_MAP[ext];
+  if (!interpreter) {
+    return {
+      status: "skipped — unknown extension",
+      exitCode: null,
+      stdout: "",
+      stderr: `unknown extension: ${ext}`,
+      durationMs: 0,
+    };
+  }
+  const childEnv = { PATH: env.PATH ?? "" };
+  for (const name of FORWARDED_ENV) {
+    childEnv[name] = env[name] ?? "";
+  }
+  const start = Date.now();
+  const result = spawnSync(interpreter, [filePath], {
+    env: childEnv,
+    encoding: "utf8",
+    timeout: timeoutMs,
+    killSignal: "SIGKILL",
+  });
+  const durationMs = Date.now() - start;
+
+  if (result.error && result.error.code === "ENOENT") {
+    return {
+      status: "skipped — interpreter not on PATH",
+      exitCode: null,
+      stdout: "",
+      stderr: `interpreter '${interpreter}' not on PATH`,
+      durationMs,
+    };
+  }
+
+  // Cross-platform timeout detection: POSIX returns a signal name; Windows
+  // sets result.error.code to "ETIMEDOUT" with result.signal sometimes null.
+  const timedOut =
+    result.signal === "SIGKILL" ||
+    result.signal === "SIGTERM" ||
+    result.error?.code === "ETIMEDOUT";
+  if (timedOut) {
+    return {
+      status: "timeout",
+      exitCode: 124,
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? "",
+      durationMs,
+    };
+  }
+
+  const exitCode = result.status ?? -1;
+  let status;
+  if (exitCode === 0) status = "pass";
+  else if (exitCode === 2) status = "config_error";
+  else status = "fail";
+
+  return {
+    status,
+    exitCode,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    durationMs,
+  };
+}
+
+function main() {
+  const args = parseFlags();
+  const dir = args.dir;
+
+  if (args["show-command"]) {
+    showCommand(dir);
+    exit(0);
+  }
+
+  const timeoutSec = Number.parseInt(args.timeout, 10);
+  if (Number.isNaN(timeoutSec) || timeoutSec <= 0) {
+    stderr.write(`usage error: --timeout must be a positive integer (got "${args.timeout}")\n`);
+    exit(3);
+  }
+  const timeoutMs = timeoutSec * 1000;
+
+  const files = listChecks(dir);
+
+  if (files === null) {
+    const note = `skipped — directory not found: ${dir}`;
+    if (args.json) {
+      stdout.write(JSON.stringify({
+        dir,
+        checks: [],
+        summary: { pass: 0, fail: 0, configError: 0, skipped: 0, total: 0 },
+        note,
+      }, null, 2) + "\n");
+    } else {
+      stdout.write(`Phase 9 runner: ${note}\n`);
+    }
+    exit(0);
+  }
+
+  if (files.length === 0) {
+    const note = `skipped — 0 check(s) in ${dir}`;
+    if (args.json) {
+      stdout.write(JSON.stringify({
+        dir,
+        checks: [],
+        summary: { pass: 0, fail: 0, configError: 0, skipped: 0, total: 0 },
+        note,
+      }, null, 2) + "\n");
+    } else {
+      stdout.write(`Phase 9 runner: ${note}\n`);
+    }
+    exit(0);
+  }
+
+  const results = [];
+  let halt = false;
+  for (const name of files) {
+    const ext = extname(name);
+    if (!INTERPRETER_MAP[ext]) {
+      results.push({
+        file: name,
+        status: "skipped — unknown extension",
+        exitCode: null,
+        stdout: "",
+        stderr: `unknown extension: ${ext}`,
+        durationMs: 0,
+      });
+      continue;
+    }
+
+    if (halt) {
+      results.push({
+        file: name,
+        status: "skipped — fail_fast",
+        exitCode: null,
+        stdout: "",
+        stderr: "",
+        durationMs: 0,
+      });
+      continue;
+    }
+
+    const r = runOne(join(dir, name), timeoutMs);
+    results.push({ file: name, ...r });
+
+    if (args["fail-fast"] && (r.status === "fail" || r.status === "timeout")) {
+      halt = true;
+    }
+  }
+
+  let pass = 0, fail = 0, configError = 0, skipped = 0;
+  for (const r of results) {
+    if (r.status === "pass") pass += 1;
+    else if (r.status === "fail" || r.status === "timeout") fail += 1;
+    else if (r.status === "config_error") configError += 1;
+    else if (typeof r.status === "string" && r.status.startsWith("skipped")) skipped += 1;
+  }
+  const summary = { pass, fail, configError, skipped, total: results.length };
+
+  let exitCode;
+  if (fail > 0) exitCode = 1;
+  else if (configError > 0) exitCode = 2;
+  else exitCode = 0;
+
+  if (args.json) {
+    stdout.write(JSON.stringify({ dir, checks: results, summary }, null, 2) + "\n");
+  } else {
+    stdout.write(`Phase 9 runner: ${results.length} check(s) in ${dir}\n`);
+    for (const r of results) {
+      const label = r.status === "pass"
+        ? "PASS"
+        : r.status === "fail"
+          ? "FAIL"
+          : r.status === "config_error"
+            ? "CONFIG"
+            : r.status === "timeout"
+              ? "TIMEOUT"
+              : (typeof r.status === "string" && r.status.startsWith("skipped"))
+                ? "SKIP"
+                : "UNKNOWN";
+      stdout.write(`  ${label.padEnd(8)} ${r.file}\n`);
+      if (r.status === "fail" || r.status === "timeout" || r.status === "config_error") {
+        if (r.stdout) stdout.write(r.stdout.split("\n").map((l) => "    " + l).join("\n") + "\n");
+        if (r.stderr) stderr.write(r.stderr.split("\n").map((l) => "    " + l).join("\n") + "\n");
+      }
+      if (typeof r.status === "string" && r.status.startsWith("skipped")) {
+        stderr.write(`    ${r.status}${r.stderr ? `: ${r.stderr}` : ""}\n`);
+      }
+    }
+    stdout.write(`\nSummary: ${pass} pass, ${fail} fail, ${configError} config-error, ${skipped} skipped (${results.length} total)\n`);
+  }
+
+  exit(exitCode);
+}
+
+main();

package/plugins/continuous-improvement/scripts/scan-past-mistakes.mjs

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+// scripts/scan-past-mistakes.mjs
+//
+// Scan the three past-mistake surfaces named in Phase 0 P-MAG of
+// `proceed-with-the-recommendation` and surface their content as a
+// machine-readable list, so the skill's most-skipped phase becomes
+// mechanically detectable: if the scan never runs, no output is emitted.
+//
+// Surfaces (all three are scanned every invocation):
+//   1. observations.jsonl  — JSONL lines whose type (or legacy event field)
+//      is "failure" or "correction". Last N (default 10) returned.
+//   2. memory feedback     — every feedback_*.md file in the project's
+//      auto-memory directory whose frontmatter declares `type: feedback`.
+//   3. CLAUDE.md           — rows extracted from a "## Past Mistakes" table
+//      in the project's CLAUDE.md (markdown table, first column = date).
+//
+// Defaults derive each path from the project root (positional arg; default
+// cwd). All three can be overridden explicitly via flags for testing or
+// non-default layouts.
+//
+// Usage:
+//   node scripts/scan-past-mistakes.mjs                       # cwd default
+//   node scripts/scan-past-mistakes.mjs <repo-root>           # explicit root
+//   node scripts/scan-past-mistakes.mjs --json                # JSON output
+//   node scripts/scan-past-mistakes.mjs \
+//     --observations <path> --memory-dir <dir> --claude-md <path>
+//   node scripts/scan-past-mistakes.mjs --max-observations 25
+//
+// Active-in-scope assessment is the LLM's job, not the script's. The script
+// surfaces raw entries with citations; the skill body annotates each line
+// with "Active in current scope: yes|no" based on the current task.
+//
+// Cited by:
+//   - skills/proceed-with-the-recommendation.md Phase 0 Rule 1
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { argv, cwd, exit, stdout } from "node:process";
+
+function parseArgs() {
+  const args = argv.slice(2);
+  const out = {
+    json: false,
+    root: cwd(),
+    observations: null,
+    memoryDir: null,
+    claudeMd: null,
+    maxObservations: 10,
+  };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--json") {
+      out.json = true;
+    } else if (a === "--observations") {
+      out.observations = args[++i];
+    } else if (a === "--memory-dir") {
+      out.memoryDir = args[++i];
+    } else if (a === "--claude-md") {
+      out.claudeMd = args[++i];
+    } else if (a === "--max-observations") {
+      out.maxObservations = parseInt(args[++i], 10) || 10;
+    } else if (a === "-h" || a === "--help") {
+      stdout.write(
+        "usage: scan-past-mistakes.mjs [--json] [<repo-root>]\n" +
+          "       [--observations <path>] [--memory-dir <dir>] [--claude-md <path>]\n" +
+          "       [--max-observations <n>]\n",
+      );
+      exit(0);
+    } else {
+      out.root = a;
+    }
+  }
+  return out;
+}
+
+// Map a project root to the auto-memory subdirectory name. Lowercases the
+// Windows drive letter and replaces path separators with dashes, matching
+// the convention used by `~/.claude/projects/<hash>/memory/` and
+// `~/.claude/instincts/<hash>/`. On POSIX paths the leading slash becomes
+// a leading dash, which is fine — the host has the same path on both
+// surfaces and the resolved file existence is what's checked, not the
+// hash format itself.
+function projectHash(root) {
+  let p = root;
+  p = p.replace(/^([A-Za-z]):/, (_m, d) => d.toLowerCase() + ":");
+  p = p.replace(/:[\\/]/, "--");
+  p = p.replace(/[\\/]/g, "-");
+  return p;
+}
+
+function defaultObservationsPath(root) {
+  return join(homedir(), ".claude", "instincts", projectHash(root), "observations.jsonl");
+}
+
+function defaultMemoryDir(root) {
+  return join(homedir(), ".claude", "projects", projectHash(root), "memory");
+}
+
+function defaultClaudeMdPath(root) {
+  return join(root, "CLAUDE.md");
+}
+
+function scanObservations(path, maxN) {
+  if (!path || !existsSync(path)) return [];
+  const raw = readFileSync(path, "utf8");
+  const lines = raw.split(/\r?\n/);
+  const matches = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    // Support both the current `type` field and the legacy `event` field
+    // (per feedback_observer_field_name_bug — pre-2026-05-06T00:38Z rows).
+    const t = obj.type ?? obj.event;
+    if (t !== "failure" && t !== "correction") continue;
+    const summary =
+      obj.summary ??
+      obj.output_summary ??
+      (typeof obj.tool_response === "string"
+        ? obj.tool_response
+        : JSON.stringify(obj).slice(0, 240));
+    matches.push({
+      line: i + 1,
+      ts: obj.ts ?? obj.timestamp ?? null,
+      type: t,
+      summary,
+    });
+  }
+  // Last N (chronologically — JSONL is append-only).
+  return matches.slice(-maxN);
+}
+
+function parseFrontmatter(content) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+  if (!m) return null;
+  const fm = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/.exec(line);
+    if (!kv) continue;
+    let value = kv[2].trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    fm[kv[1]] = value;
+  }
+  return fm;
+}
+
+function scanFeedbackMemories(dir) {
+  if (!dir || !existsSync(dir)) return [];
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const file of entries) {
+    if (!file.startsWith("feedback_") || !file.endsWith(".md")) continue;
+    let content;
+    try {
+      content = readFileSync(join(dir, file), "utf8");
+    } catch {
+      continue;
+    }
+    const fm = parseFrontmatter(content);
+    if (!fm) continue;
+    // Only surface entries explicitly typed as feedback.
+    if (fm.type && fm.type !== "feedback") continue;
+    out.push({
+      file,
+      name: fm.name ?? null,
+      description: fm.description ?? null,
+    });
+  }
+  out.sort((a, b) => a.file.localeCompare(b.file));
+  return out;
+}
+
+function scanClaudeMdPastMistakes(path) {
+  if (!path || !existsSync(path)) return [];
+  const content = readFileSync(path, "utf8");
+  const headingIdx = content.search(/^##\s+Past Mistakes\s*$/m);
+  if (headingIdx === -1) return [];
+
+  // Slice from the heading to the start of the next ## heading (or EOF).
+  const fromHeading = content.slice(headingIdx);
+  const nextSectionRel = fromHeading.slice(2).search(/^##\s/m);
+  const section = nextSectionRel === -1 ? fromHeading : fromHeading.slice(0, nextSectionRel + 2);
+
+  const out = [];
+  for (const rawLine of section.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    // Skip blank, heading, and the markdown table divider.
+    if (!line || line.startsWith("#")) continue;
+    if (/^\|[\s|:-]+\|$/.test(line)) continue;
+    if (!line.startsWith("|") || !line.endsWith("|")) continue;
+
+    // Parse pipe-delimited cells; strip leading/trailing pipe.
+    const inner = line.slice(1, -1);
+    const cells = inner.split("|").map((c) => c.trim());
+    if (cells.length < 2) continue;
+
+    // Header detection: literal "Date" first cell.
+    if (cells[0].toLowerCase() === "date") continue;
+    if (/^[-: ]+$/.test(cells[0])) continue;
+
+    out.push({
+      date: cells[0],
+      mistake: cells[1] ?? "",
+      lesson: cells[2] ?? null,
+    });
+  }
+  return out;
+}
+
+function pretty(scan) {
+  const total = scan.observations.length + scan.feedback.length + scan.claude_md.length;
+  if (total === 0) return "No prior mistakes recorded — proceed.\n";
+
+  const out = [`Past mistakes scanned: ${total} found across 3 surfaces.`, ""];
+
+  if (scan.observations.length > 0) {
+    out.push(`== observations.jsonl (${scan.observations.length}) ==`);
+    for (const o of scan.observations) {
+      const ts = o.ts ? `${o.ts} ` : "";
+      out.push(`  [line ${o.line}] ${ts}${o.type}: ${o.summary}`);
+    }
+    out.push("");
+  }
+
+  if (scan.feedback.length > 0) {
+    out.push(`== feedback memories (${scan.feedback.length}) ==`);
+    for (const f of scan.feedback) {
+      out.push(`  [${f.file}] ${f.name ?? ""}`);
+      if (f.description) out.push(`    — ${f.description}`);
+    }
+    out.push("");
+  }
+
+  if (scan.claude_md.length > 0) {
+    out.push(`== CLAUDE.md Past Mistakes (${scan.claude_md.length}) ==`);
+    for (const e of scan.claude_md) {
+      out.push(`  [${e.date}] ${e.mistake}`);
+      if (e.lesson) out.push(`    Lesson: ${e.lesson}`);
+    }
+  }
+
+  return out.join("\n") + "\n";
+}
+
+function main() {
+  const args = parseArgs();
+  const obsPath = args.observations ?? defaultObservationsPath(args.root);
+  const memDir = args.memoryDir ?? defaultMemoryDir(args.root);
+  const claudeMd = args.claudeMd ?? defaultClaudeMdPath(args.root);
+
+  const scan = {
+    observations: scanObservations(obsPath, args.maxObservations),
+    feedback: scanFeedbackMemories(memDir),
+    claude_md: scanClaudeMdPastMistakes(claudeMd),
+    sources: {
+      observations: obsPath,
+      memory_dir: memDir,
+      claude_md: claudeMd,
+    },
+  };
+
+  if (args.json) {
+    stdout.write(JSON.stringify(scan, null, 2) + "\n");
+  } else {
+    stdout.write(pretty(scan));
+  }
+}
+
+main();

package/plugins/continuous-improvement/skills/deploy-receipt/SKILL.md

@@ -21,7 +21,7 @@ This skill defines the receipt that closes that gap, without modifying the vendo
 Activate when ALL of the following are true:
 
 1. A merge into the deploy branch (typically `main` or `master`) has just landed
-2. [`scripts/detect-deploy-target.sh`](../scripts/detect-deploy-target.sh) returns a value other than `none` at the repo root. The script encodes the full file-marker table — `railway.toml` / `railway.json` → `railway`, `wrangler.toml` / `wrangler.jsonc` → `cloudflare`, `vercel.json` / `.vercel/` → `vercel`, `netlify.toml` → `netlify`, `fly.toml` → `fly`, `app.yaml` → `appengine`, `apprunner.yaml` → `apprunner`, `.github/workflows/*.yml` with a `deploy:` job → `gha-deploy`. First match wins, in that order. The script is the source of truth; the file list above is documentation
+2. `bash "${CLAUDE_PLUGIN_ROOT}/scripts/detect-deploy-target.sh"` (source: `scripts/detect-deploy-target.sh`) returns a value other than `none` at the repo root. The script encodes the full file-marker table — `railway.toml` / `railway.json` → `railway`, `wrangler.toml` / `wrangler.jsonc` → `cloudflare`, `vercel.json` / `.vercel/` → `vercel`, `netlify.toml` → `netlify`, `fly.toml` → `fly`, `app.yaml` → `appengine`, `apprunner.yaml` → `apprunner`, `.github/workflows/*.yml` with a `deploy:` job → `gha-deploy`. First match wins, in that order. The script is the source of truth; the file list above is documentation
 3. `finishing-a-development-branch` has reported "merged" — not "PR opened", not "review pending"
 
 Do NOT activate when:
@@ -45,7 +45,7 @@ The skill is provider-aware but never hardcodes a specific API key or token shap
 
 ### Route A — Provider CLI (preferred when authenticated)
 
-The CLI is the highest-fidelity source. Run [`scripts/get-deployed-sha.sh <provider>`](../scripts/get-deployed-sha.sh) — the script owns the per-provider pipeline (CLI + jq filter) and prints just the SHA on stdout. Inspect the pipeline shape without executing via `bash scripts/get-deployed-sha.sh --show-command <provider>`.
+The CLI is the highest-fidelity source. Run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/get-deployed-sha.sh" <provider>` (source: `scripts/get-deployed-sha.sh`) — the script owns the per-provider pipeline (CLI + jq filter) and prints just the SHA on stdout. Inspect the pipeline shape without executing via `bash "${CLAUDE_PLUGIN_ROOT}/scripts/get-deployed-sha.sh" --show-command <provider>`.
 
 Provider-to-pipeline map (cited from the script, not redefined here):
 

package/plugins/continuous-improvement/skills/gateguard/SKILL.md

@@ -97,7 +97,7 @@ A second Claude/Codex/Maulana session can be running on the same host and the sa
 
 **On the first Edit / Write / mutating Bash of a session:**
 
-Run [`scripts/git-state-snapshot.sh`](../scripts/git-state-snapshot.sh) and quote its JSON envelope verbatim. Example output:
+Run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/git-state-snapshot.sh"` (source: `scripts/git-state-snapshot.sh`) and quote its JSON envelope verbatim. Example output:
 
 ```
 {"head":"966ce51","upstream":"966ce51","dirty":0,"root":"/path/to/repo","branch":"main"}
@@ -115,7 +115,7 @@ If `upstream` is `"none"` or `branch` is `"detached"`, say so explicitly. Do not
 
 **On every subsequent Edit / Write / mutating Bash, before allowing the action:**
 
-Re-run [`scripts/git-state-snapshot.sh`](../scripts/git-state-snapshot.sh) and diff against the baseline:
+Re-run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/git-state-snapshot.sh"` (source: `scripts/git-state-snapshot.sh`) and diff against the baseline:
 
 1. `head` — has it advanced past your baseline without your commits?
 2. `upstream` — did upstream move while you worked?

package/plugins/continuous-improvement/skills/proceed-with-the-recommendation/SKILL.md

@@ -135,7 +135,7 @@ Before research begins, the skill must read its own track record. The instinct s
 
 ### Rule 1 — Acknowledge before context (right context from the beginning)
 
-Run [`scripts/scan-past-mistakes.mjs`](../scripts/scan-past-mistakes.mjs) at the project root. Scan three surfaces in one pass and surface every entry with a citation:
+Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/scan-past-mistakes.mjs"` (source: `scripts/scan-past-mistakes.mjs`) at the project root. Scan three surfaces in one pass and surface every entry with a citation:
 
 - `~/.claude/instincts/<project-hash>/observations.jsonl` — last N (default 10) entries with `type: failure` or `correction` (legacy `event` field also matched for pre-2026-05-06 rows)
 - `~/.claude/projects/<project-hash>/memory/feedback_*.md` — every file whose frontmatter declares `type: feedback`; the canonical home of the operator's named corrections (e.g. `feedback_past_mistake_gate.md`, `feedback_no_git_add_all_on_windows.md`)
@@ -202,7 +202,7 @@ For each item in the ORIGINAL order:
 
 ### Routing Table (with Inline Fallbacks)
 
-Run [`scripts/route-recommendation.mjs "<item>"`](../scripts/route-recommendation.mjs) to match a single recommendation item to its preferred chain + inline fallback. Default mode prints the matched row; `--json` for programmatic consumption; `--list` enumerates every row. The programmatic source of truth is [`scripts/route-recommendation.routes.json`](../scripts/route-recommendation.routes.json) — the table below is the human-readable documentation that mirrors it. If they drift, the routes.json file wins.
+Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/route-recommendation.mjs" "<item>"` (source: `scripts/route-recommendation.mjs`) to match a single recommendation item to its preferred chain + inline fallback. Default mode prints the matched row; `--json` for programmatic consumption; `--list` enumerates every row. The programmatic source of truth is `scripts/route-recommendation.routes.json` — the table below is the human-readable documentation that mirrors it. If they drift, the routes.json file wins.
 
 Rows whose **Preferred skill** is not bundled with the `continuous-improvement` plugin carry a `(Reference behavior — does not require <skill>.)` marker on the fallback cell. The marker makes the soft-dependency contract visible at point of use: the inline fallback is fully self-contained and runs without that skill installed. Rows whose preferred skill ships with the plugin (`ralph`, `tdd-workflow`, `continuous-improvement`) carry no marker — the dedicated skill is always available.
 

package/plugins/continuous-improvement/skills/reconcile/SKILL.md

@@ -40,7 +40,7 @@ When another session/loop may be active, do not assume the tree is yours:
 - An in-progress `MERGE_HEAD` / `rebase-merge` you did not start means another actor is mid-operation. Do not "help" by editing conflicted files — wait, or hand off.
 - Re-read the current branch immediately before any mutation; if it shifted since your snapshot, re-survey from the top.
 - If `.git/index` keeps changing while you are idle, a writer is active. Pause and surface it rather than racing.
-- If `gateguard` is installed, its Parallel-Actor Gate already captured this baseline on the session's first mutation (via `scripts/git-state-snapshot.sh`) and divergence-checks every later mutation — `reconcile` complements that gate, it does not replace it. Without gateguard, run the snapshot above yourself.
+- If `gateguard` is installed, its Parallel-Actor Gate already captured this baseline on the session's first mutation by running `bash "${CLAUDE_PLUGIN_ROOT}/scripts/git-state-snapshot.sh"` (source: `scripts/git-state-snapshot.sh`) and divergence-checks every later mutation — `reconcile` complements that gate, it does not replace it. Without gateguard, run the snapshot above yourself.
 
 ## Classify, Then Act