continuous-improvement 3.17.0 → 3.19.0

package/bin/portfolio-health.mjs

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+/**
+ * portfolio-health — v0 portfolio repo scorer from LOCAL static signals.
+ *
+ * Portfolio-spine train (docs/plans/2026-07-04-portfolio-spine.md).
+ *
+ * Reads the machine-readable registry at portfolio/repos.json and scores each
+ * repo 0-100 from local, offline signals only (no network):
+ *
+ *   - CI configured (`.github/workflows` with at least one yml/yaml)
+ *   - Release receipts (`.releases/*.md` or `docs/releases/*.md`, templates excluded)
+ *   - Experiment records (`.experiments/*.md` or `docs/experiments/*.md`, templates excluded)
+ *   - Commit freshness (`git log -1 --format=%ct` via child_process, guarded)
+ *   - High-severity findings from auditWorkflows (imported pure function)
+ *
+ * Repos without a local checkout score "n/a (no local checkout)" — never a crash.
+ * The weighted rubric lives in the named WEIGHT_* constants below and is
+ * mirrored in the generated report's appendix.
+ *
+ * Usage:
+ *   node bin/portfolio-health.mjs [--config <path>] [--out <file>]
+ *     --config <path>  registry path (default "portfolio/repos.json")
+ *     --out <file>     markdown report path (default "reports/portfolio-health.md")
+ *     --help           print usage
+ *
+ * Exit codes: 0 report written; 1 config/registry error (missing or malformed
+ * --config file reports a one-line `portfolio-health: ...` error, no stack).
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { argv, exit } from "node:process";
+import { auditWorkflows } from "./audit-actions.mjs";
+// Scoring rubric (documented in the report appendix; weights sum to 100).
+export const WEIGHT_CI = 25;
+export const WEIGHT_RECEIPTS = 20;
+export const WEIGHT_EXPERIMENTS = 15;
+export const WEIGHT_FRESHNESS = 20;
+export const WEIGHT_SECURITY = 20;
+export const HIGH_FINDING_PENALTY = 5; // security points lost per high finding
+export const RECEIPT_FULL_CREDIT = 3; // receipts needed for full receipt credit
+export const EXPERIMENT_FULL_CREDIT = 2; // experiment records needed for full credit
+export const FRESH_DAYS = 7; // full freshness credit at or under this
+export const STALE_DAYS = 30; // half credit at or under this; zero beyond
+const TEMPLATE_NAME = /template/i;
+const RECEIPT_DIRS = [".releases", join("docs", "releases")];
+const EXPERIMENT_DIRS = [".experiments", join("docs", "experiments")];
+function countProofFiles(localPath, dirs) {
+    let count = 0;
+    for (const dir of dirs) {
+        const full = join(localPath, dir);
+        if (!existsSync(full))
+            continue;
+        for (const entry of readdirSync(full)) {
+            if (entry.endsWith(".md") && !TEMPLATE_NAME.test(entry))
+                count++;
+        }
+    }
+    return count;
+}
+function readWorkflowFiles(localPath) {
+    const dir = join(localPath, ".github", "workflows");
+    if (!existsSync(dir))
+        return [];
+    const files = [];
+    for (const entry of readdirSync(dir).sort()) {
+        if (!entry.endsWith(".yml") && !entry.endsWith(".yaml"))
+            continue;
+        try {
+            files.push({ path: `.github/workflows/${entry}`, content: readFileSync(join(dir, entry), "utf8") });
+        }
+        catch {
+            // Unreadable workflow file: skip rather than crash the whole report.
+        }
+    }
+    return files;
+}
+/** Last-commit age in whole days via `git log -1 --format=%ct`. Any failure → null. */
+function daysSinceLastCommit(localPath, nowMs) {
+    try {
+        const out = execFileSync("git", ["-C", localPath, "log", "-1", "--format=%ct"], {
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 10000,
+        })
+            .toString()
+            .trim();
+        const epochSeconds = Number.parseInt(out, 10);
+        if (!Number.isFinite(epochSeconds) || epochSeconds <= 0)
+            return null;
+        return Math.max(0, Math.floor((nowMs - epochSeconds * 1000) / 86400000));
+    }
+    catch {
+        return null;
+    }
+}
+/** Gather all local static signals for one checked-out repo. */
+export function collectSignals(localPath, opts = {}) {
+    const workflows = readWorkflowFiles(localPath);
+    const findings = auditWorkflows(workflows);
+    return {
+        hasCI: workflows.length > 0,
+        receiptCount: countProofFiles(localPath, RECEIPT_DIRS),
+        experimentCount: countProofFiles(localPath, EXPERIMENT_DIRS),
+        daysSinceLastCommit: daysSinceLastCommit(localPath, opts.nowMs ?? Date.now()),
+        highFindings: findings.filter((f) => f.severity === "high").length,
+    };
+}
+function freshnessPoints(days) {
+    if (days === null)
+        return 0;
+    if (days <= FRESH_DAYS)
+        return WEIGHT_FRESHNESS;
+    if (days <= STALE_DAYS)
+        return WEIGHT_FRESHNESS / 2;
+    return 0;
+}
+/**
+ * Weighted 0-100 score plus the largest-gap risk and its next action.
+ * Security credit requires CI: with no workflows there is nothing audited,
+ * so a repo cannot earn security points by having no CI at all.
+ */
+export function scoreRepo(s) {
+    const ci = s.hasCI ? WEIGHT_CI : 0;
+    const receipts = Math.round((WEIGHT_RECEIPTS * Math.min(s.receiptCount, RECEIPT_FULL_CREDIT)) / RECEIPT_FULL_CREDIT);
+    const experiments = Math.round((WEIGHT_EXPERIMENTS * Math.min(s.experimentCount, EXPERIMENT_FULL_CREDIT)) / EXPERIMENT_FULL_CREDIT);
+    const freshness = freshnessPoints(s.daysSinceLastCommit);
+    const security = s.hasCI ? Math.max(0, WEIGHT_SECURITY - HIGH_FINDING_PENALTY * s.highFindings) : 0;
+    const score = ci + receipts + experiments + freshness + security;
+    // Largest points gap wins; ties resolve in this fixed order (worst first).
+    const gaps = [
+        {
+            lost: WEIGHT_SECURITY - security,
+            risk: s.hasCI
+                ? `${s.highFindings} high-severity Actions finding(s)`
+                : "No CI, so no security signal exists",
+            action: s.hasCI
+                ? "Run ci-audit-actions --strict and fix the high findings"
+                : "Add CI first, then run ci-audit-actions",
+        },
+        {
+            lost: WEIGHT_CI - ci,
+            risk: "No CI configured (.github/workflows is empty or missing)",
+            action: "Add a CI workflow that runs the test suite on push",
+        },
+        {
+            lost: WEIGHT_FRESHNESS - freshness,
+            risk: s.daysSinceLastCommit === null
+                ? "Last-commit date unknown (git unavailable or no history)"
+                : `No commits in ${s.daysSinceLastCommit} day(s)`,
+            action: "Land one small maintenance commit or archive the repo deliberately",
+        },
+        {
+            lost: WEIGHT_RECEIPTS - receipts,
+            risk: `Only ${s.receiptCount} release receipt(s) on record`,
+            action: "Write a .releases/ receipt for the next ship (template in continuous-improvement)",
+        },
+        {
+            lost: WEIGHT_EXPERIMENTS - experiments,
+            risk: `Only ${s.experimentCount} experiment record(s) on record`,
+            action: "Record the next hypothesis in .experiments/ before building",
+        },
+    ];
+    gaps.sort((a, b) => b.lost - a.lost);
+    const top = gaps[0];
+    if (top.lost === 0) {
+        return { score, topRisk: "none", nextAction: "Keep the receipts flowing" };
+    }
+    return { score, topRisk: top.risk, nextAction: top.action };
+}
+/** Registry loader with explicit validation — fail fast on malformed config. */
+export function loadConfig(configPath) {
+    const raw = readFileSync(configPath, "utf8");
+    const data = JSON.parse(raw);
+    if (!Array.isArray(data)) {
+        throw new Error(`portfolio registry ${configPath} must be a JSON array of repo entries`);
+    }
+    const entries = [];
+    for (let i = 0; i < data.length; i++) {
+        const e = data[i];
+        const missing = [];
+        if (typeof e.repo !== "string" || e.repo === "")
+            missing.push("repo");
+        if (typeof e.lane !== "string" || e.lane === "")
+            missing.push("lane");
+        if (typeof e.localPath !== "string" || e.localPath === "")
+            missing.push("localPath");
+        if (typeof e.active !== "boolean")
+            missing.push("active");
+        if (missing.length > 0) {
+            throw new Error(`portfolio registry entry ${i} has missing/invalid field(s): ${missing.join(", ")}`);
+        }
+        entries.push({ repo: e.repo, lane: e.lane, localPath: e.localPath, active: e.active });
+    }
+    return entries;
+}
+/**
+ * One row per entry. Missing local checkouts degrade to an "n/a" row.
+ * Deterministic ordering: scored rows worst-first (score asc, then repo),
+ * then n/a rows alphabetically.
+ */
+export function buildRows(entries, opts = {}) {
+    const rows = entries.map((entry) => {
+        if (!existsSync(entry.localPath)) {
+            return {
+                repo: entry.repo,
+                lane: entry.lane,
+                score: null,
+                scoreLabel: "n/a (no local checkout)",
+                topRisk: "No local checkout on this host",
+                nextAction: `Clone to ${entry.localPath} or set active:false in the registry`,
+            };
+        }
+        const signals = collectSignals(entry.localPath, opts);
+        const { score, topRisk, nextAction } = scoreRepo(signals);
+        return { repo: entry.repo, lane: entry.lane, score, scoreLabel: String(score), topRisk, nextAction };
+    });
+    return rows.sort((a, b) => {
+        if (a.score === null && b.score === null)
+            return a.repo.localeCompare(b.repo);
+        if (a.score === null)
+            return 1;
+        if (b.score === null)
+            return -1;
+        return a.score - b.score || a.repo.localeCompare(b.repo);
+    });
+}
+/** Markdown report: scored table (worst first) + how-scores-are-computed appendix. */
+export function renderReport(rows, generatedAt) {
+    const out = [];
+    out.push("# Portfolio health report");
+    out.push("");
+    out.push(`Generated at: ${generatedAt}`);
+    out.push("");
+    out.push(`Scored ${rows.filter((r) => r.score !== null).length} repo(s) from local signals; ${rows.filter((r) => r.score === null).length} without a local checkout. Worst score first.`);
+    out.push("");
+    out.push("| Repo | Score | Top Risk | Next Action |");
+    out.push("|---|---|---|---|");
+    for (const r of rows) {
+        out.push(`| ${r.repo} | ${r.scoreLabel} | ${r.topRisk} | ${r.nextAction} |`);
+    }
+    out.push("");
+    out.push("## How scores are computed");
+    out.push("");
+    out.push("v0 scores use LOCAL static signals only — no network calls. Weights (sum 100):");
+    out.push("");
+    out.push("| Signal | Weight | Full credit |");
+    out.push("|---|---|---|");
+    out.push(`| CI configured (.github/workflows with >=1 yml/yaml) | ${WEIGHT_CI} | present |`);
+    out.push(`| Release receipts (.releases/ or docs/releases/, templates excluded) | ${WEIGHT_RECEIPTS} | ${RECEIPT_FULL_CREDIT}+ receipts |`);
+    out.push(`| Experiment records (.experiments/ or docs/experiments/, templates excluded) | ${WEIGHT_EXPERIMENTS} | ${EXPERIMENT_FULL_CREDIT}+ records |`);
+    out.push(`| Commit freshness (git log -1 --format=%ct, guarded) | ${WEIGHT_FRESHNESS} | <=${FRESH_DAYS} days; half <=${STALE_DAYS} days |`);
+    out.push(`| Actions security (high findings from audit-actions) | ${WEIGHT_SECURITY} | 0 high findings; -${HIGH_FINDING_PENALTY}/finding; requires CI |`);
+    out.push("");
+    out.push("Repos without a local checkout are reported as n/a rather than guessed at.");
+    out.push("");
+    return out.join("\n");
+}
+const USAGE = `Usage: node bin/portfolio-health.mjs [--config <path>] [--out <file>]
+
+  --config <path>  registry path (default "portfolio/repos.json")
+  --out <file>     markdown report path (default "reports/portfolio-health.md")
+  --help           print this usage
+
+Exit codes: 0 report written; 1 config/registry error.
+`;
+function main() {
+    const args = argv.slice(2);
+    if (args.includes("--help")) {
+        console.log(USAGE);
+        return 0;
+    }
+    const configIdx = args.indexOf("--config");
+    const outIdx = args.indexOf("--out");
+    const configPath = configIdx >= 0 ? (args[configIdx + 1] ?? "portfolio/repos.json") : "portfolio/repos.json";
+    const outPath = outIdx >= 0 ? (args[outIdx + 1] ?? "reports/portfolio-health.md") : "reports/portfolio-health.md";
+    // Explicit error handling at the CLI boundary: a missing or malformed
+    // --config file is the most common operator mistake and must produce a
+    // one-line error, not a raw stack trace (loadConfig throws deliberately).
+    try {
+        const entries = loadConfig(configPath).filter((e) => e.active);
+        const rows = buildRows(entries);
+        const report = renderReport(rows, new Date().toISOString());
+        mkdirSync(dirname(outPath), { recursive: true });
+        writeFileSync(outPath, report);
+        const scored = rows.filter((r) => r.score !== null);
+        console.log(`portfolio-health: ${entries.length} active repo(s), ${scored.length} scored, ${rows.length - scored.length} without local checkout.`);
+        console.log(`Report written to ${outPath}`);
+        return 0;
+    }
+    catch (err) {
+        console.error(`portfolio-health: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}
+const invokedDirectly = argv[1]?.endsWith("portfolio-health.mjs");
+if (invokedDirectly) {
+    exit(main());
+}

package/commands/reconcile.md

@@ -1,22 +1,22 @@
 ---
 name: reconcile
-description: Establish git ground truth (branch, status, stashes, worktrees, ahead/behind) before any mutation, halt on protected or destructive operations, and verify a push actually landed. Enforces Law 1 (Research Before Executing).
+description: Establish git ground truth (branch, status, stashes, worktrees, ahead/behind) before any mutation, halt on protected or destructive operations, then carry the known-good state through a single-concern commit, a push, an open PR, and — after the PR merges — a fast-forward of the default branch. Enforces Law 1 (Research Before Executing).
 ---
 
-# /reconcile — Ground-Truth Git State Before You Touch It
+# /reconcile — Ground Truth, Then Commit, Push, and Open the PR
 
-Read the repo's real state before acting on it: a branch that shifted, a push that did not land, or another session mid-merge will burn a whole session if you assume instead of check.
+Read the repo's real state before acting on it: a branch that shifted, a push that did not land, or another session mid-merge will burn a whole session if you assume instead of check. Once the state is known, `/reconcile` carries the work through to an open PR and back to an up-to-date default branch.
 
 ## What it does
 
-Snapshots the full git state in one pass, detects a concurrent writer, classifies the upstream relationship, then acts only on the known state — stopping at every operation that is hard to reverse. Backed by the `reconcile` skill.
+Snapshots the full git state in one pass, detects a concurrent writer, classifies the upstream relationship, then acts only on the known state — stopping at every operation that is hard to reverse. When work is ready, it stages by filename, commits one concern, pushes a feature branch, verifies the push landed, and opens a PR. After a human merges, it fast-forwards the default branch and checks it out. Backed by the `reconcile` skill.
 
 ## Establish ground truth
 
 ```
 git branch --show-current
 git status --porcelain=v1                     # but trust git diff --stat for real drift (autocrlf)
-git rev-list --left-right --count @{u}...HEAD  # behind / ahead
+git rev-list --left-right --count '@{u}...HEAD'  # behind / ahead (quote the ref — bare @{u} trips the Bash parser)
 git stash list
 git worktree list
 ls .git/MERGE_HEAD .git/rebase-merge .git/rebase-apply 2>/dev/null  # in-progress op = another actor; do not race
@@ -31,7 +31,22 @@ behind    -> git pull --ff-only
 diverged  -> rebase/merge deliberately; never blind --force
 ```
 
-STOP for authorization before: pushing to a protected branch (this repo = feature branch + PR, never direct push to main), `--force` / `--force-with-lease`, `reset --hard`, `clean -fd`, or removing a dirty worktree. Never stage with `git add -A` on a Windows autocrlf tree (it commits phantom line-ending-only changes) — stage by explicit filename.
+STOP for authorization before: pushing to a protected branch (this repo = feature branch + PR, never direct push to main), merging the PR you opened, `--force` / `--force-with-lease`, `reset --hard`, `clean -fd`, force-deleting a branch (`branch -D`), or removing a dirty worktree. Never stage with `git add -A` on a Windows autocrlf tree (it commits phantom line-ending-only changes) — stage by explicit filename.
+
+## Commit and open the PR (self-contained)
+
+Reimplements the commit → push → PR tail inline, so it works with no companion plugin installed:
+
+```
+git switch main && git pull --ff-only origin main   # branch from a fresh base
+git switch -c <type>/<slug>                          # only if not already on a feature branch
+git add path/one path/two                            # stage by name, one concern
+git commit -m "feat(scope): <observable outcome>"    # single-line -m; never a multi-line here-doc on Windows
+git push -u origin <type>/<slug>
+gh pr create --fill --base main                      # open one PR, then STOP — the merge is a human decision
+```
+
+`/reconcile` never merges the PR, never uses `--admin` / `--force` / `--no-verify`, never auto-merges on green CI, and never deploys.
 
 ## Verify the push landed
 
@@ -39,9 +54,21 @@ STOP for authorization before: pushing to a protected branch (this repo = featur
 git ls-remote origin refs/heads/<branch>   # remote tip must equal local HEAD, else it did not land
 ```
 
+## Sync the default branch after the PR merges
+
+"Latest work on main" is true only once the PR merges, and on a protected branch that merge is a human action. After it lands:
+
+```
+git switch main                        # or master
+git pull --ff-only origin main         # fast-forward only; if it will not ff, main diverged — re-survey, do not force
+git rev-parse HEAD                     # confirm this equals the squash-merge SHA
+git branch -d <type>/<slug>            # delete the merged feature branch (safe -d, never -D)
+```
+
 ## Pairs with
 
 - **`reconcile`** skill — the discipline this command runs.
 - **`gateguard`** / **`safety-guard`** — runtime + destructive-op guardrails.
 - **`recall`** — recall whether the same git op failed here before.
-- **`audit`** — the loop that often produces the fix `reconcile` then ships.
+- **`audit`** — the loop that often produces the fix `/reconcile` then ships.
+- **`/ship`** — the TDD-gated single-defect variant; `commit-commands:commit-push-pr` is the external-plugin equivalent of the commit → PR tail.

package/hooks/gateguard.mjs

@@ -35,7 +35,7 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { MAX_CLEARED_FILES, canonicalizeFileKey, isCapReached, isFileCleared, loadState, markFileCleared, resolveSessionDir, saveState, } from "../lib/gateguard-state.mjs";
+import { MAX_CLEARED_FILES, canonicalizeFileKey, canonicalizeProjectRoot, isCapReached, isFileCleared, loadState, markFileCleared, resolveProjectRoot, resolveSessionDir, saveState, } from "../lib/gateguard-state.mjs";
 const TOOL_ROUTE = {
     Read: "allow",
     Grep: "allow",
@@ -69,8 +69,20 @@ const DESTRUCTIVE_PATTERNS = [
     "Remove-Item -Recurse",
     "Remove-Item -Force",
 ];
+// Flags whose VALUE is human prose (a commit message, a PR body) or a filename —
+// never a command to execute. Their contents must not trip the destructive scan:
+// `git commit -m "drop the stale format helper"` and `gh pr create --body "…"`
+// were stranding finished work on their own wording. `-c` is deliberately
+// EXCLUDED — `bash -c "rm -rf /"` carries a real command and must still gate.
+const MESSAGE_FLAG_RE = /(^|\s)(-m|--message|-F|--file|--body|--body-file|--title|--notes|-C|--reuse-message)(=|\s+)('[^']*'|"[^"]*"|\S+)/g;
+// Blank the value of every message/body flag so only executable command syntax
+// remains for the destructive-pattern scan. The flag itself is preserved so a
+// flag like `-F` never accidentally merges with its neighbours.
+function stripMessageArgs(command) {
+    return command.replace(MESSAGE_FLAG_RE, (_match, lead, flag) => `${lead}${flag} `);
+}
 function isDestructiveBash(command) {
-    const lower = command.toLowerCase();
+    const lower = stripMessageArgs(command).toLowerCase();
     return DESTRUCTIVE_PATTERNS.some((p) => lower.includes(p.toLowerCase()));
 }
 function classifyTool(toolName, toolInput) {
@@ -95,6 +107,60 @@ function extractFilePaths(toolInput) {
         return [toolInput.command];
     return [];
 }
+// --- Path exclusions -------------------------------------------------------
+// Opt-in: skip the fact-forcing gate for low-risk paths a user edits
+// constantly (an LLM-maintained prose wiki, a generated scratch dir). Set the
+// CI_GATEGUARD_EXCLUDE env var to a comma-separated list of path substrings;
+// each is matched case-insensitively against the forward-slash-normalized file
+// path. Unset/empty (the default) changes nothing — every mutating file call is
+// gated exactly as before. A call whose targets mix excluded and non-excluded
+// paths still gates the non-excluded ones.
+const EXCLUDE_FRAGMENTS = String(process.env.CI_GATEGUARD_EXCLUDE ?? "")
+    .split(",")
+    .map((fragment) => fragment.trim().replace(/\\/g, "/").toLowerCase())
+    .filter((fragment) => fragment !== "");
+function isExcludedPath(filePath) {
+    if (EXCLUDE_FRAGMENTS.length === 0 || typeof filePath !== "string" || filePath === "") {
+        return false;
+    }
+    const normalized = filePath.replace(/\\/g, "/").toLowerCase();
+    return EXCLUDE_FRAGMENTS.some((fragment) => normalized.includes(fragment));
+}
+// --- Target lock (opt-in) --------------------------------------------------
+// A fact-list can't catch a wrong-repo / wrong-worktree write — you can present
+// perfect facts about the wrong file. CI_GATEGUARD_TARGET_LOCK=block denies a
+// mutating call whose ABSOLUTE target canonicalizes outside the session project
+// root. Default (unset) checks nothing, so existing sessions — including
+// legitimate out-of-root edits to ~/.claude or /tmp — are unaffected. This is
+// the warn-first rollout: ship non-enforcing, flip to block per session.
+const TARGET_LOCK_ON = String(process.env.CI_GATEGUARD_TARGET_LOCK ?? "").toLowerCase() === "block";
+// Relative paths resolve under cwd (= the project root) and always pass; only an
+// absolute path into a different tree can be out-of-root. Drive-letter (d:/,
+// D:\), POSIX-absolute (/x), and UNC (\\host) forms all count as absolute.
+function isAbsolutePathString(p) {
+    return /^[A-Za-z]:[\\/]/.test(p) || p.startsWith("/") || p.startsWith("\\\\");
+}
+function isTargetOutsideRoot(filePath, projectRoot) {
+    if (!isAbsolutePathString(filePath))
+        return false;
+    const root = canonicalizeProjectRoot(projectRoot);
+    if (root === "global" || root === "")
+        return false; // no known root — do not guess
+    const target = canonicalizeFileKey(filePath);
+    return target !== root && !target.startsWith(`${root}/`);
+}
+function buildTargetLockReason(strayPath, projectRoot) {
+    return [
+        `Target is outside the session project root — refusing a possible wrong-repo / wrong-worktree write.`,
+        "",
+        `  Target: ${strayPath.replace(/\\/g, "/")}`,
+        `  Session root: ${canonicalizeProjectRoot(projectRoot)}`,
+        "",
+        "If this is intentional, confirm you are in the right worktree (cwd / CLAUDE_PROJECT_DIR),",
+        "or unset CI_GATEGUARD_TARGET_LOCK for this session. Target lock is opt-in; it fires only",
+        "when CI_GATEGUARD_TARGET_LOCK=block.",
+    ].join("\n");
+}
 // The call site only reads this inside the block branch, where at least one
 // path is uncleared; an all-cleared batch returns "" and is never consumed.
 function firstUnclearedFilePath(toolInput, state) {
@@ -144,6 +210,47 @@ function buildMutatingFileReason(toolName, filePaths, stateFilePath) {
         "  `_gateguard_facts_presented: true`; Claude Code's strict schema rejects that, so use A or B.)",
     ].join("\n");
 }
+function findUnquotedBraceRef(command) {
+    let quote = null;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (ch === "@" && command[i + 1] === "{") {
+            // 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;
+            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 fixed = `${command.slice(0, wordStart)}'${word}'${command.slice(wordEnd)}`;
+            return { ref, fixed };
+        }
+    }
+    return null;
+}
+function buildBraceRefReason(hit) {
+    return [
+        `Unquoted git ref ${hit.ref} — Claude Code's Bash parser trips on the braces and blocks this`,
+        "post-hoc, costing a retry. Quote the ref and run the SAME command:",
+        "",
+        `  ${hit.fixed}`,
+        "",
+        "Single quotes stop the shell from touching the braces; git reads the ref as-is.",
+    ].join("\n");
+}
 function buildDestructiveBashReason(command) {
     return [
         `Destructive command requested: ${command}`,
@@ -199,6 +306,16 @@ function main() {
     const toolName = typeof payload.tool_name === "string" ? payload.tool_name : "";
     const toolInput = payload.tool_input ?? {};
     const gate = classifyTool(toolName, toolInput);
+    // Unquoted @{…} refs trip the built-in Bash parser — catch them first, for
+    // both routine and destructive commands, so the quoted fix surfaces before the
+    // opaque post-hoc block (and before the destructive rollback demand).
+    if (toolName === "Bash" && typeof toolInput.command === "string") {
+        const braceHit = findUnquotedBraceRef(toolInput.command);
+        if (braceHit) {
+            emitDeny(buildBraceRefReason(braceHit));
+            return;
+        }
+    }
     if (gate === "allow") {
         emitAllow();
         return;
@@ -215,7 +332,24 @@ function main() {
     const sessionDir = resolveSessionDir(sessionId);
     const stateFilePath = join(sessionDir, "gateguard-session.json");
     const state = loadState(sessionDir);
-    const filePaths = extractFilePaths(toolInput);
+    const allTargetPaths = extractFilePaths(toolInput);
+    const filePaths = allTargetPaths.filter((path) => !isExcludedPath(path));
+    if (allTargetPaths.length > 0 && filePaths.length === 0) {
+        emitAllow(); // every target is under a CI_GATEGUARD_EXCLUDE path; skip the gate
+        return;
+    }
+    // Target lock runs before the fact gate and independent of clearance: a
+    // wrong-repo write is wrong even with perfect facts. Excluded paths were
+    // already filtered out above, so an explicitly-excluded scratch dir outside
+    // the root is never target-locked.
+    if (TARGET_LOCK_ON) {
+        const projectRoot = resolveProjectRoot();
+        const stray = filePaths.find((path) => isTargetOutsideRoot(path, projectRoot));
+        if (stray) {
+            emitDeny(buildTargetLockReason(stray, projectRoot));
+            return;
+        }
+    }
     const filePath = firstUnclearedFilePath(toolInput, state);
     const factsFlagged = toolInput._gateguard_facts_presented === true;
     const alreadyCleared = filePaths.length > 0 && filePaths.every((path) => isFileCleared(state, path));

package/hooks/typecheck-stop.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * typecheck-stop.mts — Stop hook that runs the project typecheck on changed TS
+ * files and, when opted in, returns a block decision so the failure re-enters
+ * model context and the agent fixes it before ending the turn — in all modes,
+ * including headless `-p` runs where Stop still fires (RISA 4 / G4).
+ *
+ * Ports the proven detection logic of ~/.claude/scripts/typecheck-changed.sh
+ * (skip non-TS repos, skip TS repos with no changed TS file, prefer the npm
+ * `typecheck` script) and adds the block mechanism of goal-drift-stop.mts.
+ *
+ * Mode via CLAUDE_TYPECHECK_GATE: "off" (default) | "warn" | "block".
+ *   off   : no-op (the global script's advisory systemMessage stays the default
+ *           layer; this hook is the opt-in enforcement layer — zero regression).
+ *   warn  : one-line stderr notice; never blocks.
+ *   block : {"decision":"block","reason":...} to re-prompt the model.
+ *
+ * Fail-open by construction: any error, missing root, non-TS repo, no changed
+ * TS file, no runnable typecheck, or a run that times out exits 0 (allow). No
+ * network. The wiring gives this hook a longer timeout than the 5s hooks
+ * because `tsc` is slower; on the internal timeout it fails open.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { decideTypecheckAction, formatTypecheckReason, hasChangedTsFile, parseChangedFiles, pickTypecheckKind, resolveTypecheckMode, } from "../lib/typecheck-gate.mjs";
+const SPAWN_TIMEOUT_MS = 25_000;
+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();
+        return root || null;
+    }
+    catch {
+        return null;
+    }
+}
+function collectChangedFiles(root) {
+    const run = (args) => {
+        try {
+            return execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+        }
+        catch {
+            return "";
+        }
+    };
+    const unstaged = run(["diff", "--name-only", "--diff-filter=ACMR"]);
+    const staged = run(["diff", "--cached", "--name-only", "--diff-filter=ACMR"]);
+    return [...parseChangedFiles(unstaged), ...parseChangedFiles(staged)];
+}
+function hasNpmTypecheckScript(root) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        return typeof pkg.scripts?.typecheck === "string";
+    }
+    catch {
+        return false;
+    }
+}
+function localTscPath(root) {
+    // node_modules/typescript/bin/tsc is a Node script — invoking it via `node`
+    // is cross-platform, unlike node_modules/.bin/tsc (a shell script / .cmd).
+    const path = join(root, "node_modules", "typescript", "bin", "tsc");
+    return existsSync(path) ? path : null;
+}
+function runTypecheck(root) {
+    const tscPath = localTscPath(root);
+    const kind = pickTypecheckKind(hasNpmTypecheckScript(root), tscPath !== null);
+    if (!kind)
+        return { ran: false, rc: 0, output: "" };
+    const result = kind === "npm"
+        ? spawnSync("npm", ["run", "--silent", "typecheck"], {
+            cwd: root,
+            encoding: "utf8",
+            shell: true,
+            timeout: SPAWN_TIMEOUT_MS,
+        })
+        : spawnSync(process.execPath, [tscPath, "--noEmit"], {
+            cwd: root,
+            encoding: "utf8",
+            timeout: SPAWN_TIMEOUT_MS,
+        });
+    // A timeout or spawn failure leaves error set / status null — inconclusive, so
+    // fail open (do not block on a check that never produced a verdict).
+    if (result.error || typeof result.status !== "number")
+        return { ran: false, rc: 0, output: "" };
+    return { ran: true, rc: result.status, output: `${result.stdout ?? ""}${result.stderr ?? ""}` };
+}
+function main() {
+    const mode = resolveTypecheckMode(process.env.CLAUDE_TYPECHECK_GATE);
+    if (mode === "off")
+        return;
+    const root = resolveProjectRoot();
+    if (!root || !existsSync(join(root, "tsconfig.json")))
+        return; // not a TS project
+    if (!hasChangedTsFile(collectChangedFiles(root)))
+        return; // nothing TS changed — near-zero cost
+    const { ran, rc, output } = runTypecheck(root);
+    const action = decideTypecheckAction({ mode, ranTypecheck: ran, rc });
+    if (action === "block") {
+        process.stdout.write(`${JSON.stringify({ decision: "block", reason: formatTypecheckReason(output) })}\n`);
+    }
+    else if (action === "warn") {
+        process.stderr.write(`[continuous-improvement] typecheck: ${formatTypecheckReason(output)}\n`);
+    }
+}
+try {
+    main();
+}
+catch {
+    // fail open — never trap a turn on a hook bug
+}