continuous-improvement 3.20.0 → 3.20.4

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
 

package/plugins/continuous-improvement/skills/verification-loop/SKILL.md

@@ -23,10 +23,10 @@ Invoke this skill:
 
 Every project has its own actual invocation for build / typecheck / lint / test / security / deploy-receipt. Hardcoding `npm run build` and `npm run test` works when the project happens to use those exact scripts; for everything else (pnpm, yarn, cargo, go, mise, just, custom scripts, monorepos with workspace-scoped commands) it returns "deps not installed" or "config not found" misreads from the wrong invocation. Phase 0 runs first so Phases 1–6 never have to guess.
 
-**Run [`scripts/resolve-verify-ladder.mjs`](../scripts/resolve-verify-ladder.mjs)** at the repo root. It encodes the full four-step resolution priority and emits the fenced block below. Use `--json` for machine consumption.
+**Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-verify-ladder.mjs"`** (source: `scripts/resolve-verify-ladder.mjs`) at the repo root. It encodes the full four-step resolution priority and emits the fenced block below. Use `--json` for machine consumption.
 
 ```
-$ node scripts/resolve-verify-ladder.mjs
+$ node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-verify-ladder.mjs"
 verify-ladder (resolved):
   build:             npm run build  (sniff:package.json:scripts.build)
   typecheck:         npm run typecheck  (sniff:package.json:scripts.typecheck)
@@ -147,9 +147,9 @@ If either is `No`, the verification report goes back to the operator with the ex
 
 For repos whose `verify-ladder.json` declares a `deploy_receipt` field — or whose sniff path detects an auto-deploy target — the verify is not complete until the deployed SHA matches the merge SHA and a healthcheck returns 200. Hand off to the `deploy-receipt` skill (Law 4 deploy-seam companion landed in PR #83) and treat its `Receipt status: COMPLETE` as the gate.
 
-**Detection.** Run [`scripts/detect-deploy-target.sh`](../scripts/detect-deploy-target.sh) at the repo root. Output is one of `railway` / `cloudflare` / `vercel` / `netlify` / `fly` / `appengine` / `apprunner` / `gha-deploy` / `none`. Anything except `none` triggers handoff to `deploy-receipt`; `none` means Phase 8 is skipped (no deploy seam exists).
+**Detection.** Run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/detect-deploy-target.sh"` (source: `scripts/detect-deploy-target.sh`) at the repo root. Output is one of `railway` / `cloudflare` / `vercel` / `netlify` / `fly` / `appengine` / `apprunner` / `gha-deploy` / `none`. Anything except `none` triggers handoff to `deploy-receipt`; `none` means Phase 8 is skipped (no deploy seam exists).
 
-**SHA extraction.** For the detected provider, [`scripts/get-deployed-sha.sh <provider>`](../scripts/get-deployed-sha.sh) returns the currently-deployed SHA via the provider CLI; `--show-command <provider>` prints the pipeline shape without executing (useful for dry-runs and citation). `deploy-receipt` owns the receipt's other components (health endpoint, build artifact, on-incomplete modes) and Route B/C fallbacks.
+**SHA extraction.** For the detected provider, `bash "${CLAUDE_PLUGIN_ROOT}/scripts/get-deployed-sha.sh" <provider>` (source: `scripts/get-deployed-sha.sh`) returns the currently-deployed SHA via the provider CLI; `bash "${CLAUDE_PLUGIN_ROOT}/scripts/get-deployed-sha.sh" --show-command <provider>` prints the pipeline shape without executing (useful for dry-runs and citation). `deploy-receipt` owns the receipt's other components (health endpoint, build artifact, on-incomplete modes) and Route B/C fallbacks.
 
 INCOMPLETE receipts move to "Immediate operator action" in the close, never to "ready". Library-only / package-published repos skip this phase entirely (no deploy seam exists).
 
@@ -164,7 +164,7 @@ Phase 8 confirms the deploy seam. Phase 9 confirms the deployed surface matches
 
 **What the runner does:**
 
-Implementation: `scripts/run-synthetic.mjs` encodes the lexical walk, interpreter map, env injection, and exit-code aggregation below. The prose is documentation, not the contract — when the two disagree, the script wins.
+Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/run-synthetic.mjs"` (source: `scripts/run-synthetic.mjs`); it encodes the lexical walk, interpreter map, env injection, and exit-code aggregation below. The prose is documentation, not the contract — when the two disagree, the script wins.
 
 1. List every `*.synthetic.{sh,mjs,ts,py}` file in the resolved directory in lexical order.
 2. For each file, set the input env vars: `BASE_URL` (production base from project config), `BASELINE_URL` (staging baseline from project config), `EXPECTED_SHA` (the merge SHA Phase 8 reported COMPLETE), `DEPLOY_BRANCH` (the deploy branch name), `RECEIPT_TIMESTAMP` (ISO-8601 of the receipt).

package/plugins/continuous-improvement/skills/workspace-surface-audit/SKILL.md

@@ -74,7 +74,7 @@ Probe and record (no destructive commands; quote results inline):
 - **jq availability.** `command -v jq` (or `Get-Command jq`). When jq is missing, observation-pipeline hooks fall back to a thin schema and curl/JSON one-liners need a node/python rewrite.
 - **Case-sensitive filesystem.** Test by creating two paths differing only in case in a tempdir. NTFS (Windows) and APFS (macOS default) are case-insensitive; Linux ext4 and case-sensitive APFS are case-sensitive. Affects `CLAUDE.md` vs `claude.md` resolution and import paths.
 - **CWD baseline.** `pwd` (or `Get-Location`) recorded at session start. `tsc`, build scripts, and some test runners change CWD as a side effect; subsequent commands run from the wrong directory return "deps not installed" or "config not found" misreads.
-- **Parallel-actor expectation.** Document whether a second Claude / Codex / Maulana session may operate on the same working tree. If yes, the `gateguard` Parallel-Actor Gate uses [`scripts/git-state-snapshot.sh`](../scripts/git-state-snapshot.sh) to produce a single JSON envelope (`{head, upstream, dirty, root, branch}`) for the baseline and the divergence check. This skill records whether parallel-actor is expected; gateguard owns the runtime mechanics, so the audit doesn't restate the git-command triple.
+- **Parallel-actor expectation.** Document whether a second Claude / Codex / Maulana session may operate on the same working tree. If yes, the `gateguard` Parallel-Actor Gate runs `bash "${CLAUDE_PLUGIN_ROOT}/scripts/git-state-snapshot.sh"` (source: `scripts/git-state-snapshot.sh`) to produce a single JSON envelope (`{head, upstream, dirty, root, branch}`) for the baseline and the divergence check. This skill records whether parallel-actor is expected; gateguard owns the runtime mechanics, so the audit doesn't restate the git-command triple.
 
 Output the recorded grain as a single fenced block so it survives context compaction and any later phase can reference it without re-probing:
 

package/plugins/continuous-improvement/skills/worktree-safety/SKILL.md

@@ -32,7 +32,7 @@ The continuous-improvement repo runs on Windows + Git Bash with `autocrlf=true`
 
 Before any source-writing call, verify all five. Fail closed on any miss.
 
-1. **Root validity** — `git rev-parse --show-toplevel` resolves; the resolved path matches CWD after symlink-safe canonicalization. The `root` field of [`scripts/git-state-snapshot.sh`](../scripts/git-state-snapshot.sh) carries the canonicalized root, and its non-zero exit on `{"error":"not-a-git-repo"}` is itself the fail-closed signal — no second probe needed.
+1. **Root validity** — `git rev-parse --show-toplevel` resolves; the resolved path matches CWD after symlink-safe canonicalization. Run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/git-state-snapshot.sh"` (source: `scripts/git-state-snapshot.sh`); its `root` field carries the canonicalized root, and its non-zero exit on `{"error":"not-a-git-repo"}` is itself the fail-closed signal — no second probe needed.
 2. **`.git` presence** — `.git` exists (file pointer for worktrees, directory for primary checkout). A missing or unreadable `.git` is an immediate stop.
 3. **Worktree registration** — `git worktree list` includes the resolved root with no `prunable` flag. Prunable worktrees can be deleted by another process at any moment.
 4. **Branch alignment** — current branch matches the lease ledger; `HEAD` is not detached unless the unit explicitly asked for detached state. The snapshot script's `branch` field carries either the branch name or the literal `"detached"`, so detached-state is observable without a second probe.

package/plugins/expert.json

@@ -1,6 +1,6 @@
 {
   "name": "continuous-improvement",
-  "version": "3.20.0",
+  "version": "3.20.4",
   "mode": "expert",
   "description": "Expert mode: tune confidence, manage instincts, and persist plans on disk. Adds safety, token-budget, and strategic-compact skills plus the /learn-eval command so long sessions stay sharp and learnings survive context resets.",
   "tools": [

package/scripts/README.md

@@ -0,0 +1,33 @@
+# `scripts/` — deterministic primitives skills cite
+
+This directory holds small, hand-authored scripts that skills (and hooks) cite instead of restating fixed operations inline. The motivation is the skills audit's "deterministic vs non-deterministic" axis: when a step inside a skill is the same operation every time (a fixed git command, a regex parse, a path lookup), it does not belong in the LLM-driven part of the skill — it belongs here, where the script runs the same way every invocation, costs no tokens, and stays in one place so multiple skills can share it.
+
+## Conventions
+
+- **Hand-authored, no `.mts` source.** Files in `scripts/` are not part of the `tsc` build pipeline (see [`CLAUDE.md`](../CLAUDE.md) → "Build pipeline"). The pipeline owns `bin/`, `lib/`, `test/`. `scripts/` is the bare-metal home for shell scripts and one-off Node utilities skills cite directly.
+- **One concern per script.** Each script does one thing and prints either machine-readable output (JSON envelope, single value) or a stable fenced block. Skills consume the output; they do not re-derive it.
+- **Cross-platform shape.** Bash scripts run via Git Bash on Windows, native bash on macOS/Linux. Tests for bash scripts skip when bash is not on PATH (see `src/test/hook.test.mts` for the established skip pattern).
+- **Cite from skills.** When a skill needs a primitive, the skill body cites the script path (`scripts/<name>.<ext>`) and quotes the expected output shape once. The skill does not restate the script's inner mechanics.
+
+## Inventory
+
+| Script | Purpose | Cited by |
+|---|---|---|
+| `git-state-snapshot.sh` | JSON envelope `{head, upstream, dirty, root, branch}` for the current git working tree | `skills/gateguard.md` (Parallel-Actor Gate), `skills/worktree-safety.md` (Root + branch), `skills/workspace-surface-audit.md` (Environment Grain — parallel-actor row), `skills/reconcile.md` (Detect a Concurrent Writer) |
+| `detect-deploy-target.sh` | Detect the auto-deploy provider for the repo at the current working directory (or first arg). Prints one of `railway`/`cloudflare`/`vercel`/`netlify`/`fly`/`appengine`/`apprunner`/`gha-deploy`/`none`. Always exits 0. | `skills/verification-loop.md` (Phase 8 deploy-receipt handoff), `skills/deploy-receipt.md` (When to Activate gate) |
+| `get-deployed-sha.sh` | Per-provider deployed-SHA extraction. Default mode runs the CLI; `--show-command <provider>` prints the pipeline shape without executing (useful for citation, dry-run, tests). | `skills/verification-loop.md` (Phase 8), `skills/deploy-receipt.md` (Route A — provider CLI extraction) |
+| `resolve-verify-ladder.mjs` | Resolve the per-project verification ladder for Phase 0 of `verification-loop`. Encodes the four-step priority — manifest > package.json sniff > per-language toolchain > ask-operator. Default mode prints the fenced block the skill displays; `--json` mode emits a JSON object for machine consumption. | `skills/verification-loop.md` (Phase 0) |
+| `scan-past-mistakes.mjs` | Scan the three Past-Mistake Acknowledgment Gate surfaces — `~/.claude/instincts/<hash>/observations.jsonl` (last N failure/correction rows), `~/.claude/projects/<hash>/memory/feedback_*.md`, and `<root>/CLAUDE.md` "## Past Mistakes" table. Active-in-scope judgment is the LLM's job; the script provides quotes + citations only. | `skills/proceed-with-the-recommendation.md` (Phase 0 Rule 1) |
+| `route-recommendation.mjs` + `route-recommendation.routes.json` | Match a recommendation item to its preferred-skill chain + inline fallback from the Phase 3 routing table (29 rows). Data file is the programmatic source of truth; the skill's table is documentation that mirrors it. Default mode prints a match block; `--json` for machine consumption; `--list` enumerates all rows. | `skills/proceed-with-the-recommendation.md` (Phase 3 routing table) |
+| `run-synthetic.mjs` | Phase 9 runner: invoke every `*.synthetic.{sh,mjs,ts,py}` in `synthetic-checks/`, inject `BASE_URL`/`BASELINE_URL`/`EXPECTED_SHA`/`DEPLOY_BRANCH`/`RECEIPT_TIMESTAMP` (unset vars pass through as `""`), capture stdout/stderr/exit per check, aggregate. Default mode prints the report block; `--json` for machine consumption; `--fail-fast` halts on first drift or timeout; `--timeout <sec>` per-check wall-clock cap; `--show-command` dry-run. Exit 0 all-pass, 1 drift, 2 config error, 3 usage. | `skills/verification-loop.md` (Phase 9 — production-vs-baseline diff) |
+
+When a new script lands here, add a row to this table in the same PR and cite the script from at least one skill — otherwise the script is dead code on arrival.
+
+## Relationship to other locations
+
+- `bin/` — generated CLI entrypoints (`.mjs` from `src/bin/*.mts`). Do not hand-edit; see [`CLAUDE.md`](../CLAUDE.md) → "Build pipeline".
+- `lib/` — generated library code (`.mjs` from `src/lib/*.mts`). Same rule.
+- `hooks/` — generated PreToolUse / PostToolUse / Stop hooks (`.mjs` from `src/hooks/*.mts`). Wired in `plugins/continuous-improvement/hooks/hooks.json`.
+- `scripts/` — this directory. Hand-authored primitives skills cite.
+
+When deciding where a new piece of code belongs: if it implements a runtime hook the harness will call, it goes in `src/hooks/`. If it's a verification or CLI entrypoint the plugin or `npm run` invokes, it goes in `src/bin/`. If it's reusable logic shared between those, it goes in `src/lib/`. If it's a small primitive a skill body cites by path (and the operator or harness runs ad hoc), it goes here.

package/scripts/detect-deploy-target.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# scripts/detect-deploy-target.sh
+#
+# Detect the auto-deploy provider for the repo rooted at the current working
+# directory (or the first argument, if supplied). Composability primitive used
+# by skills and hooks that need to know "does this repo auto-deploy, and if so
+# from where?" without each restating the file-marker table.
+#
+# Output: one of
+#   railway | cloudflare | vercel | netlify | fly | appengine | apprunner |
+#   gha-deploy | none
+#
+# Resolution priority (first match wins):
+#   1. railway.toml | railway.json                              → railway
+#   2. wrangler.toml | wrangler.jsonc                           → cloudflare
+#   3. vercel.json | .vercel/                                   → vercel
+#   4. netlify.toml                                             → netlify
+#   5. fly.toml                                                 → fly
+#   6. app.yaml                                                 → appengine
+#   7. apprunner.yaml                                           → apprunner
+#   8. .github/workflows/*.{yml,yaml} containing "deploy:" job  → gha-deploy
+#   9. nothing matched                                          → none
+#
+# Always exits 0. `none` is a valid result, not an error condition.
+#
+# Cited by:
+#   - skills/verification-loop.md Phase 8 (deploy-receipt handoff trigger)
+#   - skills/deploy-receipt.md "When to Activate" gate
+
+set -u
+
+ROOT="${1:-$PWD}"
+
+emit() {
+  printf '%s\n' "$1"
+  exit 0
+}
+
+# Order is the contract — earlier rows shadow later ones when multiple
+# markers exist in the same repo.
+[ -f "$ROOT/railway.toml" ]    && emit railway
+[ -f "$ROOT/railway.json" ]    && emit railway
+[ -f "$ROOT/wrangler.toml" ]   && emit cloudflare
+[ -f "$ROOT/wrangler.jsonc" ]  && emit cloudflare
+[ -f "$ROOT/vercel.json" ]     && emit vercel
+[ -d "$ROOT/.vercel" ]         && emit vercel
+[ -f "$ROOT/netlify.toml" ]    && emit netlify
+[ -f "$ROOT/fly.toml" ]        && emit fly
+[ -f "$ROOT/app.yaml" ]        && emit appengine
+[ -f "$ROOT/apprunner.yaml" ]  && emit apprunner
+
+# GitHub Actions deploy workflow: scan .github/workflows/*.{yml,yaml} for a
+# job whose key is literally `deploy:`. Cheap and conservative — false
+# positives (a non-deploy job named "deploy") are unlikely; false negatives
+# (a deploy job named something else) require the repo to declare the
+# provider via one of the file markers above instead.
+if [ -d "$ROOT/.github/workflows" ]; then
+  if grep -lE '^[[:space:]]*deploy:[[:space:]]*$' \
+        "$ROOT/.github/workflows/"*.yml \
+        "$ROOT/.github/workflows/"*.yaml 2>/dev/null \
+      | head -n 1 | grep -q .; then
+    emit gha-deploy
+  fi
+fi
+
+emit none

package/scripts/get-deployed-sha.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# scripts/get-deployed-sha.sh
+#
+# Print the currently-deployed commit SHA for an auto-deploy provider, or
+# print the CLI command shape (with `--show-command`) without executing it.
+# Composability primitive that owns the per-provider CLI knowledge so skills
+# can cite one path instead of restating the 5-provider extraction table.
+#
+# Usage:
+#   bash scripts/get-deployed-sha.sh <provider>
+#   bash scripts/get-deployed-sha.sh --show-command <provider>
+#
+# Providers: railway | cloudflare | vercel | netlify | fly
+#
+# Default mode: runs the provider CLI, pipes through jq, prints the SHA on
+# stdout. Requires the CLI to be installed and authenticated; exits 3 with a
+# clear error if the CLI is missing.
+#
+# --show-command mode: prints the command pipeline that would run, without
+# executing it. Useful for skill citations, dry-runs, and tests that should
+# not require live CLI auth.
+#
+# Exit codes:
+#   0 — SHA printed (default mode) or command printed (--show-command mode)
+#   2 — missing or unknown provider (usage error)
+#   3 — required CLI not installed (default mode only)
+#   non-zero — CLI failure (passed through)
+#
+# Cited by:
+#   - skills/verification-loop.md Phase 8 (deploy-receipt handoff trigger)
+#   - skills/deploy-receipt.md Route A (provider CLI extraction)
+
+set -u
+
+SHOW_COMMAND=false
+PROVIDER=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --show-command)
+      SHOW_COMMAND=true
+      shift
+      ;;
+    -h|--help)
+      sed -n '2,/^$/p' "$0" >&2
+      exit 0
+      ;;
+    *)
+      if [ -z "$PROVIDER" ]; then
+        PROVIDER="$1"
+      else
+        printf 'usage: get-deployed-sha.sh [--show-command] <provider>\n' >&2
+        exit 2
+      fi
+      shift
+      ;;
+  esac
+done
+
+if [ -z "$PROVIDER" ]; then
+  printf 'usage: get-deployed-sha.sh [--show-command] <provider>\n' >&2
+  exit 2
+fi
+
+# Single source of truth for the per-provider command pipeline. Each value is
+# the literal pipeline that would run; the jq filter extracts the SHA.
+case "$PROVIDER" in
+  railway)
+    CMD='railway status --json | jq -r .deployments[0].meta.commitHash'
+    CLI=railway
+    ;;
+  cloudflare)
+    CMD='wrangler deployments list --json | jq -r .[0].metadata.deployment_trigger.metadata.commit_hash'
+    CLI=wrangler
+    ;;
+  vercel)
+    CMD='vercel inspect "$(vercel ls --json | jq -r .[0].url)" --json | jq -r .gitSource.sha'
+    CLI=vercel
+    ;;
+  netlify)
+    CMD='netlify api listSiteDeploys --data="{\"site_id\":\"$NETLIFY_SITE_ID\"}" | jq -r .[0].commit_ref'
+    CLI=netlify
+    ;;
+  fly)
+    CMD='fly releases --json | jq -r .[0].commit_sha'
+    CLI=fly
+    ;;
+  *)
+    printf 'unknown or unsupported provider: %s\n' "$PROVIDER" >&2
+    printf 'supported: railway | cloudflare | vercel | netlify | fly\n' >&2
+    exit 2
+    ;;
+esac
+
+if [ "$SHOW_COMMAND" = "true" ]; then
+  printf '%s\n' "$CMD"
+  exit 0
+fi
+
+if ! command -v "$CLI" >/dev/null 2>&1; then
+  printf 'required CLI "%s" not installed for provider "%s"\n' "$CLI" "$PROVIDER" >&2
+  exit 3
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'required CLI "jq" not installed\n' >&2
+  exit 3
+fi
+
+# Execute the pipeline. eval is intentional — the per-provider CMD contains
+# pipes and command substitution that need shell interpretation. CMDs are
+# sourced from the literal table above, not user input.
+eval "$CMD"