continuous-improvement 3.19.0 → 3.20.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "continuous-improvement",
-  "version": "3.19.0",
+  "version": "3.20.4",
   "description": "Claude Code that gets sharper every session: the persistent-memory and runtime-discipline layer built on the 7 Laws of AI Agent Discipline. It grounds every edit in real facts before it lands and, through the Mulahazah engine, turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Shipped as 27 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts. Beginner: one /plugin install command. Expert: adds MCP tools and session hooks.",
   "keywords": [
     "claude-code",
@@ -56,10 +56,11 @@
     "verify:routing-targets": "node bin/check-routing-targets.mjs",
     "verify:doc-runtime-claims": "node bin/check-doc-runtime-claims.mjs",
     "verify:test-imports-only": "node bin/check-test-imports-only.mjs",
-    "verify:scripts-citation-drift": "node bin/check-scripts-citation-drift.mjs",
+    "verify:landing-version": "node bin/check-landing-version.mjs",
+    "verify:scripts-citation-drift": "node bin/check-scripts-citation-drift.mjs && node bin/check-scripts-citation-drift.mjs plugins/continuous-improvement",
     "verify:third-party-shape": "node bin/check-third-party-shape.mjs",
     "verify:tool-count": "node bin/check-tool-count.mjs",
-    "verify:all": "npm run verify:skill-mirror && npm run verify:skill-tiers && npm run verify:skill-law-tag && npm run verify:skill-count && npm run verify:skill-count-prose && npm run verify:command-count && npm run verify:docs-substrings && npm run verify:everything-mirror && npm run verify:routing-targets && npm run verify:doc-runtime-claims && npm run verify:test-imports-only && npm run verify:scripts-citation-drift && npm run verify:third-party-shape && npm run verify:tool-count && npm run typecheck"
+    "verify:all": "npm run verify:skill-mirror && npm run verify:skill-tiers && npm run verify:skill-law-tag && npm run verify:skill-count && npm run verify:skill-count-prose && npm run verify:command-count && npm run verify:docs-substrings && npm run verify:everything-mirror && npm run verify:routing-targets && npm run verify:doc-runtime-claims && npm run verify:test-imports-only && npm run verify:landing-version && npm run verify:scripts-citation-drift && npm run verify:third-party-shape && npm run verify:tool-count && npm run typecheck"
   },
   "files": [
     ".claude-plugin/",
@@ -74,6 +75,7 @@
     "hooks/",
     "commands/",
     "skills/",
+    "scripts/",
     "templates/",
     "plugins/",
     "instinct-packs/"

package/plugins/beginner.json

@@ -1,6 +1,6 @@
 {
   "name": "continuous-improvement",
-  "version": "3.19.0",
+  "version": "3.20.4",
   "mode": "beginner",
   "description": "Beginner mode: see what your agent learned, list its instincts, and request a session reflection. Bundles three grounding skills (gateguard, tdd-workflow, verification-loop) so research, memory, tests, and verification happen by default — every edit starts from facts, not guesses.",
   "tools": [

package/plugins/continuous-improvement/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "continuous-improvement",
       "description": "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 27 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
-      "version": "3.19.0",
+      "version": "3.20.4",
       "source": "./",
       "author": {
         "name": "naimkatiman"

package/plugins/continuous-improvement/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "continuous-improvement",
-  "version": "3.19.0",
+  "version": "3.20.4",
   "description": "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 27 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
   "author": {
     "name": "naimkatiman",

package/plugins/continuous-improvement/README.md

@@ -10,6 +10,7 @@ Included surfaces:
 - `commands/`
 - `agents/` — `code-reviewer`, `security-auditor`, `test-engineer` personas (auto-discovered Claude Code subagents; pattern from addy/agent-skills)
 - `hooks/`
+- `scripts/`
 - `bin/mcp-server.mjs`
 - `bin/observe.mjs`
 - `bin/backfill.mjs`

package/plugins/continuous-improvement/commands/verify-install.md

@@ -41,7 +41,7 @@ The observation hook appends one row per tool call to
 
 - If it exists and has at least one row — capture is recording. Record `observe: ✓`.
 - If it is missing or empty — record `observe: ✗ (observation hook not recording —
-  on Windows confirm Git Bash / WSL is installed, then re-run the installer)`.
+  on Windows confirm Git Bash is installed before WSL Bash on PATH, then re-run the installer)`.
 
 ## Report
 

package/plugins/continuous-improvement/hooks/gateguard.mjs

@@ -210,6 +210,16 @@ function buildMutatingFileReason(toolName, filePaths, stateFilePath) {
         "  `_gateguard_facts_presented: true`; Claude Code's strict schema rejects that, so use A or B.)",
     ].join("\n");
 }
+function isGitBraceSelector(value) {
+    const selector = value.trim();
+    if (/^(?:u|upstream|push|-?\d+)$/i.test(selector))
+        return true;
+    if (/^(?:now|today|yesterday|tomorrow|noon|midnight|tea)$/i.test(selector))
+        return true;
+    if (/^\d{4}-\d{1,2}-\d{1,2}(?:[ T].*)?$/.test(selector))
+        return true;
+    return !selector.startsWith("#") && /(?:^|[.\s])ago$/i.test(selector);
+}
 function findUnquotedBraceRef(command) {
     let quote = null;
     for (let i = 0; i < command.length; i++) {
@@ -224,17 +234,26 @@ function findUnquotedBraceRef(command) {
             continue;
         }
         if (ch === "@" && command[i + 1] === "{") {
+            const braceEnd = command.indexOf("}", i + 2);
+            if (braceEnd === -1)
+                continue;
+            const selector = command.slice(i + 2, braceEnd);
+            // Deny only recognized Git selector grammar. PowerShell hashtables can
+            // contain comments, quoted braces, or arbitrary key expressions.
+            if (!isGitBraceSelector(selector)) {
+                i = braceEnd;
+                continue;
+            }
             // Expand to the whitespace-delimited word that carries this @{ ref, then
             // single-quote that whole word in the suggested fix.
             let wordStart = i;
             while (wordStart > 0 && !/\s/.test(command[wordStart - 1]))
                 wordStart--;
-            let wordEnd = i;
+            let wordEnd = braceEnd + 1;
             while (wordEnd < command.length && !/\s/.test(command[wordEnd]))
                 wordEnd++;
             const word = command.slice(wordStart, wordEnd);
-            const braceEnd = command.indexOf("}", i);
-            const ref = braceEnd === -1 ? command.slice(i, wordEnd) : command.slice(i, braceEnd + 1);
+            const ref = command.slice(i, braceEnd + 1);
             const fixed = `${command.slice(0, wordStart)}'${word}'${command.slice(wordEnd)}`;
             return { ref, fixed };
         }

package/plugins/continuous-improvement/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Gateguard fact-forcing PreToolUse, companion-preference enforcement, observation, session lifecycle, 3-section-close discipline, goal-drift Stop gate, opt-in workflow-distill Stop nudge, opt-in typecheck Stop gate, and UserPromptSubmit lazy-routing plus opt-in proactive recall-briefing hooks for continuous-improvement.",
+  "description": "Gateguard fact-forcing PreToolUse, companion-preference enforcement, observation, session lifecycle, 3-section-close discipline, goal-drift Stop gate, opt-in workflow-distill Stop nudge, opt-in typecheck Stop gate, opt-in query-cost Stop nudge, and UserPromptSubmit lazy-routing plus opt-in proactive recall-briefing hooks for continuous-improvement.",
   "hooks": {
     "PreToolUse": [
       {
@@ -98,6 +98,11 @@
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/typecheck-stop.mjs\"",
             "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/query-cost-nudge.mjs\"",
+            "timeout": 5
           }
         ]
       }

package/plugins/continuous-improvement/hooks/query-cost-nudge.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * query-cost-nudge.mts — Stop hook that nudges a D1-aware query-cost audit when
+ * the working tree has changed DB/query files at turn end (RISA 5 / G5).
+ *
+ * The `database-reviewer` agent already carries the cost checklist, but nothing
+ * dispatched it on DB edits, so cost regressions (the surprise-D1-bill class)
+ * shipped unaudited. This injects a once-per-session reminder via Stop
+ * `additionalContext` — a Stop hook (not PostToolUse) because only PreToolUse /
+ * UserPromptSubmit / Stop / SubagentStop support additionalContext; PostToolUse
+ * could only emit a user-facing systemMessage that never reaches the model.
+ *
+ * Opt-in via CLAUDE_QUERY_COST_NUDGE=on (default off). Once-per-session dedup
+ * keyed on the Stop stdin session_id (falls back to a per-day key) — without it,
+ * additionalContext "keeps the turn going" and would re-fire every turn while
+ * the DB files stay dirty. Never blocks; fail-open on any error.
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { buildQueryCostReminder, changedQueryPaths, parseChangedFiles, resolveQueryCostNudge, } from "../lib/query-cost-gate.mjs";
+function readStdin() {
+    try {
+        return readFileSync(0, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function resolveHome() {
+    return process.env.HOME || process.env.USERPROFILE || homedir();
+}
+function resolveProjectRoot() {
+    const fromEnv = process.env.CLAUDE_PROJECT_DIR;
+    if (fromEnv && fromEnv.trim())
+        return fromEnv.trim();
+    try {
+        const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (root)
+            return root;
+    }
+    catch {
+        // not in a git repo
+    }
+    return "global";
+}
+function collectChangedFiles(root) {
+    const run = (args) => {
+        try {
+            return execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+        }
+        catch {
+            return "";
+        }
+    };
+    return [
+        ...parseChangedFiles(run(["diff", "--name-only", "--diff-filter=ACMR"])),
+        ...parseChangedFiles(run(["diff", "--cached", "--name-only", "--diff-filter=ACMR"])),
+        ...parseChangedFiles(run(["ls-files", "--others", "--exclude-standard"])),
+    ];
+}
+// Marker key: the sanitized session_id when present (the normal case), else a
+// per-day key so a missing id self-heals daily instead of blocking forever.
+function markerKey(sessionId) {
+    const sanitized = (sessionId ?? "").replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64);
+    return sanitized || `day-${new Date().toISOString().slice(0, 10)}`;
+}
+function markerPath(home, projectRoot, sessionId) {
+    const hash = createHash("sha256").update(projectRoot).digest("hex").slice(0, 12);
+    return join(home, ".claude", "instincts", hash, "query-cost-nudge", `${markerKey(sessionId)}.nudged`);
+}
+function main() {
+    if (resolveQueryCostNudge(process.env.CLAUDE_QUERY_COST_NUDGE) === "off")
+        return;
+    let sessionId;
+    try {
+        const payload = JSON.parse(readStdin());
+        if (typeof payload.session_id === "string")
+            sessionId = payload.session_id;
+    }
+    catch {
+        // stdin optional — proceed without a session id (per-day dedup)
+    }
+    const root = resolveProjectRoot();
+    if (root === "global")
+        return; // no repo → nothing to diff
+    const changed = changedQueryPaths(collectChangedFiles(root));
+    if (changed.length === 0)
+        return;
+    const marker = markerPath(resolveHome(), root, sessionId);
+    try {
+        if (existsSync(marker))
+            return; // already nudged this session
+        mkdirSync(dirname(marker), { recursive: true });
+        writeFileSync(marker, `${new Date().toISOString()}\n`);
+    }
+    catch {
+        // if the marker can't be written, nudge anyway (no dedup) rather than stay silent
+    }
+    process.stdout.write(`${JSON.stringify({
+        hookSpecificOutput: { hookEventName: "Stop", additionalContext: buildQueryCostReminder(changed) },
+    })}\n`);
+}
+try {
+    main();
+}
+catch {
+    // fail open — never trap a turn on a hook bug
+}

package/plugins/continuous-improvement/hooks/typecheck-stop.mjs

@@ -51,7 +51,8 @@ function collectChangedFiles(root) {
     };
     const unstaged = run(["diff", "--name-only", "--diff-filter=ACMR"]);
     const staged = run(["diff", "--cached", "--name-only", "--diff-filter=ACMR"]);
-    return [...parseChangedFiles(unstaged), ...parseChangedFiles(staged)];
+    const untracked = run(["ls-files", "--others", "--exclude-standard"]);
+    return [...parseChangedFiles(unstaged), ...parseChangedFiles(staged), ...parseChangedFiles(untracked)];
 }
 function hasNpmTypecheckScript(root) {
     try {

package/plugins/continuous-improvement/lib/plugin-metadata.mjs

@@ -505,6 +505,11 @@ export function getPluginHooksConfig() {
         // internal timeout it fails open (allow) rather than blocking.
         timeout: 30,
     };
+    const queryCostNudgeCommand = {
+        type: "command",
+        command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/query-cost-nudge.mjs\"",
+        timeout: 5,
+    };
     const routePromptCommand = {
         type: "command",
         command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/route-prompt.mjs\"",
@@ -516,7 +521,7 @@ export function getPluginHooksConfig() {
         timeout: 5,
     };
     return {
-        description: "Gateguard fact-forcing PreToolUse, companion-preference enforcement, observation, session lifecycle, 3-section-close discipline, goal-drift Stop gate, opt-in workflow-distill Stop nudge, opt-in typecheck Stop gate, and UserPromptSubmit lazy-routing plus opt-in proactive recall-briefing hooks for continuous-improvement.",
+        description: "Gateguard fact-forcing PreToolUse, companion-preference enforcement, observation, session lifecycle, 3-section-close discipline, goal-drift Stop gate, opt-in workflow-distill Stop nudge, opt-in typecheck Stop gate, opt-in query-cost Stop nudge, and UserPromptSubmit lazy-routing plus opt-in proactive recall-briefing hooks for continuous-improvement.",
         hooks: {
             // gateguard runs FIRST on PreToolUse so its block decision short-circuits
             // before companion-preference sees the call. companion-preference runs
@@ -540,7 +545,7 @@ export function getPluginHooksConfig() {
             UserPromptSubmit: [{ hooks: [routePromptCommand, recallBriefingCommand] }],
             SessionStart: [{ hooks: [sessionCommand] }],
             SessionEnd: [{ hooks: [sessionCommand] }],
-            Stop: [{ hooks: [threeSectionCloseCommand, goalDriftStopCommand, workflowDistillCommand, typecheckStopCommand] }],
+            Stop: [{ hooks: [threeSectionCloseCommand, goalDriftStopCommand, workflowDistillCommand, typecheckStopCommand, queryCostNudgeCommand] }],
         },
     };
 }

package/plugins/continuous-improvement/lib/query-cost-gate.mjs

@@ -0,0 +1,53 @@
+/**
+ * Pure helpers for the query-cost nudge Stop hook (RISA 5 / G5).
+ *
+ * The hook (src/hooks/query-cost-nudge.mts) does the I/O — git, the per-session
+ * dedup marker, emitting the reminder. Everything here is pure and unit-tested.
+ *
+ * Opt-in via CLAUDE_QUERY_COST_NUDGE=on (default off). When on and the working
+ * tree has changed DB/query files at turn end, the hook injects a once-per-session
+ * reminder (via Stop `additionalContext`) to run a D1-aware cost audit before
+ * finishing — the surprise-D1-bill class the insights flagged. Never blocks.
+ */
+export function resolveQueryCostNudge(raw) {
+    return (raw ?? "").trim().toLowerCase() === "on" ? "on" : "off";
+}
+// DB / query source paths. Case-insensitive; the caller passes forward-slash
+// paths straight from `git diff --name-only` (git always uses forward slashes).
+const QUERY_PATH_RES = [
+    /\.sql$/i,
+    /\.prisma$/i,
+    /(^|\/)migrations?\//i,
+    /(^|\/)db\//i,
+    /(^|\/)schema\.(ts|js|mjs|cjs|cts|mts|prisma|sql)$/i,
+    /drizzle/i,
+];
+export function isQueryPath(filePath) {
+    const path = (filePath ?? "").replace(/\\/g, "/").trim();
+    if (path === "")
+        return false;
+    return QUERY_PATH_RES.some((re) => re.test(path));
+}
+export function parseChangedFiles(gitOutput) {
+    return (gitOutput ?? "")
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+export function changedQueryPaths(files) {
+    return files.filter((file) => isQueryPath(file));
+}
+export function buildQueryCostReminder(paths) {
+    const list = paths.slice(0, 8).map((path) => path.replace(/\\/g, "/")).join(", ");
+    return [
+        "<system-reminder>",
+        `Query-cost check: you changed DB/query file(s) this session (${list}).`,
+        "Before finishing, audit cost — dispatch the database-reviewer agent, or check directly:",
+        "  - EXPLAIN QUERY PLAN each new/changed query; no full table SCAN on a hot path.",
+        "  - Every WHERE / JOIN / ORDER BY column is index-covered; no N+1 loops.",
+        "  - D1: rows_read is billed per row SCANNED (not returned) — add covering indexes and cache hot reads (KV) instead of re-querying.",
+        "  - No unbounded query — add LIMIT / pagination.",
+        "One-time per-session reminder (CLAUDE_QUERY_COST_NUDGE).",
+        "</system-reminder>",
+    ].join("\n");
+}

package/plugins/continuous-improvement/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/plugins/continuous-improvement/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/plugins/continuous-improvement/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"

package/plugins/continuous-improvement/scripts/git-state-snapshot.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# scripts/git-state-snapshot.sh
+#
+# Emit a single-line JSON envelope describing the current git working-tree
+# state. Composability primitive used by skills that need to baseline or check
+# git state without each restating the same 3-command triple.
+#
+# Fields:
+#   - head:     short SHA returned by `git rev-parse --short HEAD`
+#   - upstream: short SHA of `@{u}` if the branch tracks an upstream, else "none"
+#   - dirty:    integer count of lines from `git status --porcelain` (0 == clean)
+#   - root:     absolute path from `git rev-parse --show-toplevel`
+#   - branch:   `git symbolic-ref --short HEAD`, else "detached"
+#
+# Outside a git repository the script prints `{"error":"not-a-git-repo"}` and
+# exits 1. All other failures are treated as a non-git-repo condition rather
+# than emitting a partial envelope.
+#
+# Cited by:
+#   - skills/gateguard.md            (Parallel-Actor Gate baseline + divergence)
+#   - skills/worktree-safety.md      (Root + branch alignment)
+#   - skills/workspace-surface-audit.md (Environment Grain — parallel-actor row)
+
+set -u
+
+head=$(git rev-parse --short HEAD 2>/dev/null) || {
+  printf '{"error":"not-a-git-repo"}\n'
+  exit 1
+}
+
+if upstream=$(git rev-parse --short '@{u}' 2>/dev/null); then
+  upstream_field=$(printf '"%s"' "$upstream")
+else
+  upstream_field='"none"'
+fi
+
+dirty=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+
+root=$(git rev-parse --show-toplevel 2>/dev/null || printf 'unknown')
+
+if branch=$(git symbolic-ref --short HEAD 2>/dev/null); then
+  branch_field=$(printf '"%s"' "$branch")
+else
+  branch_field='"detached"'
+fi
+
+printf '{"head":"%s","upstream":%s,"dirty":%s,"root":"%s","branch":%s}\n' \
+  "$head" "$upstream_field" "$dirty" "$root" "$branch_field"