continuous-improvement 3.9.2 → 3.12.3

package/bin/companion-preference-status.mjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * /companion-preference status — read & aggregate hook telemetry.
+ *
+ * Reads ~/.claude/instincts/<project-hash>/companion-preference.jsonl
+ * (or an explicit path via --path), groups events by ci_skill within the
+ * configured window (default 7 days), and prints a summary report with
+ * per-skill totals, action breakdown, and companion_installed%.
+ *
+ * Usage:
+ *   node bin/companion-preference-status.mjs              # last 7 days, human
+ *   node bin/companion-preference-status.mjs --days 30    # 30-day window
+ *   node bin/companion-preference-status.mjs --all        # whole file, no window
+ *   node bin/companion-preference-status.mjs --json       # machine-readable JSON
+ *   node bin/companion-preference-status.mjs --path <p>   # override JSONL path
+ *
+ * Exit codes:
+ *   0 — report rendered (including the "no telemetry recorded yet" case)
+ *   1 — argument parse error or unexpected runtime failure
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { argv, exit, stdout } from "node:process";
+const ACTIONS = [
+    "observation",
+    "advisory",
+    "block",
+    "block-not-installed",
+];
+function parseArgs(args) {
+    const out = { days: 7, all: false, json: false, path: null };
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (a === "--days") {
+            const v = Number(args[++i]);
+            if (!Number.isFinite(v) || v <= 0) {
+                process.stderr.write(`--days requires a positive integer (got ${args[i]})\n`);
+                exit(1);
+            }
+            out.days = v;
+        }
+        else if (a === "--all") {
+            out.all = true;
+            out.days = null;
+        }
+        else if (a === "--json") {
+            out.json = true;
+        }
+        else if (a === "--path") {
+            out.path = args[++i] ?? null;
+            if (!out.path) {
+                process.stderr.write(`--path requires a value\n`);
+                exit(1);
+            }
+        }
+        else if (a === "--help" || a === "-h") {
+            printHelp();
+            exit(0);
+        }
+        else if (a !== undefined) {
+            process.stderr.write(`unknown argument: ${a}\n`);
+            exit(1);
+        }
+    }
+    return out;
+}
+function printHelp() {
+    stdout.write([
+        "Usage: companion-preference-status [options]",
+        "",
+        "Options:",
+        "  --days N       Only count events from the last N days (default 7)",
+        "  --all          Ignore the window; count every row in the file",
+        "  --json         Emit a machine-readable JSON report",
+        "  --path <file>  Override the default JSONL path (testing)",
+        "  -h, --help     Print this help",
+        "",
+    ].join("\n"));
+}
+function resolveProjectRoot() {
+    const fromEnv = process.env.CLAUDE_PROJECT_DIR;
+    if (fromEnv)
+        return fromEnv;
+    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 defaultJsonlPath() {
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? homedir();
+    const hash = createHash("sha256")
+        .update(resolveProjectRoot())
+        .digest("hex")
+        .slice(0, 12);
+    return join(home, ".claude", "instincts", hash, "companion-preference.jsonl");
+}
+function parseJsonl(raw) {
+    const rows = [];
+    let parseErrors = 0;
+    for (const line of raw.split(/\r?\n/)) {
+        if (line.trim().length === 0)
+            continue;
+        try {
+            rows.push(JSON.parse(line));
+        }
+        catch {
+            parseErrors += 1;
+        }
+    }
+    return { rows, parseErrors };
+}
+function aggregate(rows) {
+    const bySkill = {};
+    const byMode = {};
+    const installedYes = {};
+    for (const row of rows) {
+        const stats = (bySkill[row.ci_skill] ??= {
+            total: 0,
+            actions: {},
+            installed_pct: null,
+        });
+        stats.total += 1;
+        stats.actions[row.action] = (stats.actions[row.action] ?? 0) + 1;
+        if (row.companion_installed) {
+            installedYes[row.ci_skill] = (installedYes[row.ci_skill] ?? 0) + 1;
+        }
+        byMode[row.mode] = (byMode[row.mode] ?? 0) + 1;
+    }
+    for (const [skill, stats] of Object.entries(bySkill)) {
+        stats.installed_pct =
+            stats.total > 0
+                ? Math.round(((installedYes[skill] ?? 0) * 100) / stats.total)
+                : null;
+    }
+    return { bySkill, byMode };
+}
+function pad(s, width) {
+    return s.length >= width ? s : s + " ".repeat(width - s.length);
+}
+function rpad(n, width) {
+    const s = String(n);
+    return s.length >= width ? s : " ".repeat(width - s.length) + s;
+}
+function formatHuman(report) {
+    const lines = [];
+    const windowLabel = report.window_days === null ? "all-time" : `last ${report.window_days} days`;
+    lines.push(`Companion-preference telemetry — ${windowLabel}`);
+    lines.push(`File:   ${report.file}`);
+    if (report.since)
+        lines.push(`Window: ${report.since} to ${new Date().toISOString()}`);
+    lines.push("");
+    if (report.total_events === 0) {
+        lines.push("No events in window.");
+    }
+    else {
+        const skillWidth = Math.max(8, ...Object.keys(report.by_skill).map((k) => k.length));
+        const header = pad("ci_skill", skillWidth) +
+            "  " +
+            ["total", "observation", "advisory", "block", "block-not-installed", "installed%"]
+                .map((h) => rpad(h, h.length))
+                .join("  ");
+        lines.push(header);
+        for (const [skill, stats] of Object.entries(report.by_skill).sort((a, b) => b[1].total - a[1].total)) {
+            const cells = [
+                rpad(stats.total, "total".length),
+                rpad(stats.actions.observation ?? 0, "observation".length),
+                rpad(stats.actions.advisory ?? 0, "advisory".length),
+                rpad(stats.actions.block ?? 0, "block".length),
+                rpad(stats.actions["block-not-installed"] ?? 0, "block-not-installed".length),
+                rpad(stats.installed_pct === null ? "—" : `${stats.installed_pct}`, "installed%".length),
+            ].join("  ");
+            lines.push(pad(skill, skillWidth) + "  " + cells);
+        }
+    }
+    lines.push("");
+    const modeEntries = Object.entries(report.by_mode);
+    if (modeEntries.length > 0) {
+        lines.push(`Mode totals: ${modeEntries.map(([k, v]) => `${k} ${v}`).join(", ")}`);
+    }
+    lines.push(`Total events: ${report.total_events}`);
+    if (report.parse_errors > 0)
+        lines.push(`Parse errors (skipped): ${report.parse_errors}`);
+    return lines.join("\n") + "\n";
+}
+function main() {
+    const args = parseArgs(argv.slice(2));
+    const filePath = args.path ?? defaultJsonlPath();
+    if (!existsSync(filePath)) {
+        stdout.write(`Companion-preference telemetry: no telemetry recorded yet at ${filePath}\n`);
+        exit(0);
+    }
+    const raw = readFileSync(filePath, "utf8");
+    const { rows, parseErrors } = parseJsonl(raw);
+    const cutoff = args.all || args.days === null
+        ? null
+        : new Date(Date.now() - args.days * 24 * 3600 * 1000).toISOString();
+    const filtered = cutoff === null ? rows : rows.filter((r) => r.ts >= cutoff);
+    const { bySkill, byMode } = aggregate(filtered);
+    const report = {
+        file: filePath,
+        window_days: args.all ? null : args.days,
+        since: cutoff,
+        total_events: filtered.length,
+        parse_errors: parseErrors,
+        by_skill: bySkill,
+        by_mode: byMode,
+    };
+    if (args.json) {
+        stdout.write(JSON.stringify(report, null, 2) + "\n");
+    }
+    else {
+        stdout.write(formatHuman(report));
+    }
+    exit(0);
+}
+const invokedDirectly = argv[1]?.endsWith("companion-preference-status.mjs");
+if (invokedDirectly) {
+    main();
+}
+export { ACTIONS, aggregate, parseArgs, parseJsonl, };

package/bin/gateguard-clear.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * gateguard-clear — record GateGuard clearance for files from the Bash route.
+ *
+ * The GateGuard PreToolUse hook blocks the first Edit/Write per file and prints
+ * the session-state path in its block reason. After presenting the required
+ * facts, run this to clear the gate so the retry is allowed. Bash is not gated
+ * (unless the command is destructive), so this surface always works — including
+ * where the ci_gateguard_clear MCP tool is not connected.
+ *
+ * Usage:
+ *   node bin/gateguard-clear.mjs <file_path> [<file_path>...] [--state <path>]
+ *
+ * Default resolves the session dir canonically, the same way the hook does.
+ * --state <path> writes that exact gateguard-session.json — the path the block
+ * reason prints — bypassing resolution for any residual env mismatch.
+ */
+import { dirname, join } from "node:path";
+import { MAX_CLEARED_FILES, clearFiles, resolveSessionDir, } from "../lib/gateguard-state.mjs";
+function main() {
+    const argv = process.argv.slice(2);
+    const files = [];
+    let stateFile = "";
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--state") {
+            stateFile = argv[i + 1] ?? "";
+            i += 1;
+        }
+        else {
+            files.push(arg);
+        }
+    }
+    if (argv.includes("--state") && stateFile === "") {
+        process.stderr.write("--state requires a <gateguard-session.json> path argument\n");
+        process.exit(2);
+    }
+    if (files.length === 0) {
+        process.stderr.write("usage: gateguard-clear <file_path> [<file_path>...] [--state <gateguard-session.json>]\n");
+        process.exit(2);
+    }
+    // clearFiles writes <sessionDir>/gateguard-session.json. With --state the
+    // caller hands us the full state-file path the block reason printed, so the
+    // session dir is its parent.
+    const sessionDir = stateFile ? dirname(stateFile) : resolveSessionDir();
+    const { cleared, skippedForCap } = clearFiles(sessionDir, files);
+    process.stdout.write(`Cleared ${cleared.length}: ${cleared.length > 0 ? cleared.join(", ") : "(none — already cleared)"}\n`);
+    if (skippedForCap.length > 0) {
+        process.stdout.write(`Skipped — session cap of ${MAX_CLEARED_FILES} reached: ${skippedForCap.join(", ")}\n`);
+    }
+    process.stdout.write(`State: ${join(sessionDir, "gateguard-session.json")}\n`);
+}
+main();

package/bin/generate-plugin-manifests.mjs

@@ -35,7 +35,7 @@ async function writeBundledSkills() {
     const sourceSkillsDir = join(REPO_ROOT, "skills");
     const targetSkillsDir = join(PLUGIN_BUNDLE_DIR, "skills");
     const companionSkills = (await readdir(sourceSkillsDir))
-        .filter((file) => /^[a-z][a-z0-9-]*\.md$/.test(file))
+        .filter((file) => file.endsWith(".md") && file !== "README.md")
         .sort();
     await mkdir(targetSkillsDir, { recursive: true });
     await copyFileTo(join(REPO_ROOT, "SKILL.md"), join(targetSkillsDir, PACKAGE_NAME, "SKILL.md"));
@@ -145,9 +145,16 @@ async function writePluginBundle() {
         copyFileTo(join(REPO_ROOT, "bin", "mcp-server.mjs"), join(PLUGIN_BUNDLE_DIR, "bin", "mcp-server.mjs")),
         copyFileTo(join(REPO_ROOT, "bin", "observe.mjs"), join(PLUGIN_BUNDLE_DIR, "bin", "observe.mjs")),
         copyFileTo(join(REPO_ROOT, "bin", "backfill.mjs"), join(PLUGIN_BUNDLE_DIR, "bin", "backfill.mjs")),
+        copyFileTo(join(REPO_ROOT, "bin", "gateguard-clear.mjs"), join(PLUGIN_BUNDLE_DIR, "bin", "gateguard-clear.mjs")),
+        copyFileTo(join(REPO_ROOT, "lib", "gateguard-state.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "gateguard-state.mjs")),
         copyFileTo(join(REPO_ROOT, "lib", "plugin-metadata.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "plugin-metadata.mjs")),
         copyFileTo(join(REPO_ROOT, "lib", "resolve-home-dir.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "resolve-home-dir.mjs")),
         copyFileTo(join(REPO_ROOT, "lib", "observe-event.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "observe-event.mjs")),
+        copyFileTo(join(REPO_ROOT, "lib", "goal-state.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "goal-state.mjs")),
+        copyFileTo(join(REPO_ROOT, "lib", "goal-drift-gate.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "goal-drift-gate.mjs")),
+        copyFileTo(join(REPO_ROOT, "lib", "recall-index.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "recall-index.mjs")),
+        copyFileTo(join(REPO_ROOT, "lib", "recall-briefing.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "recall-briefing.mjs")),
+        copyFileTo(join(REPO_ROOT, "lib", "skill-distill.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "skill-distill.mjs")),
         copyFileTo(join(REPO_ROOT, "LICENSE"), join(PLUGIN_BUNDLE_DIR, "LICENSE")),
         writePluginBundleReadme(),
     ]);

package/bin/harvest-friction.mjs

@@ -248,7 +248,7 @@ function main() {
         console.log("  the Node observer is not on PATH — never tool_complete with output_summary,");
         console.log("  which is what the classifier needs.");
         console.log("  Install jq (winget install jqlang.jq | brew install jq | apt install jq)");
-        console.log("  OR ensure hooks/bin/observe.mjs is reachable from the hook script.");
+        console.log("  OR ensure instincts/bin/observe.mjs is reachable from the hook script.");
     }
     else if (result.thinSchemaRows > 0 && result.classifiedRows === 0) {
         console.log("");

package/bin/hook-stats.mjs

@@ -46,27 +46,27 @@ import { platform } from "node:os";
 import { join } from "node:path";
 import { argv, cwd, exit, stderr, stdout } from "node:process";
 import { resolveHomeDir } from "../lib/resolve-home-dir.mjs";
-const USAGE = `Usage: node bin/hook-stats.mjs [options]
-
-Reads JSONL telemetry from <HOME>/.claude/hook-telemetry/*.jsonl and
-prints per-hook aggregate counts over a recent time window.
-
-Options:
-  --hours=<n>            Time window in hours (default: 24)
-  --hash=<hash>          Only read this single <hash>.jsonl file
-                         (default: sha256 of the current working directory,
-                         normalized to forward slashes and lowercased on
-                         Windows, then first 12 hex chars)
-  --telemetry-dir=<path> Override telemetry dir
-                         (default: <HOME>/.claude/hook-telemetry)
-  --help                 Show this help and exit 0
-
-Output:
-  One line per hook: "<hook> last <hours>h: pass=<n> block=<n>
-  skip-short=<n> total=<n> avg-duration=<X>ms".
-  If there are no records in the window: "no records in last <hours>h".
-
-The reader is parse-tolerant: malformed JSONL lines are skipped silently.
+const USAGE = `Usage: node bin/hook-stats.mjs [options]
+
+Reads JSONL telemetry from <HOME>/.claude/hook-telemetry/*.jsonl and
+prints per-hook aggregate counts over a recent time window.
+
+Options:
+  --hours=<n>            Time window in hours (default: 24)
+  --hash=<hash>          Only read this single <hash>.jsonl file
+                         (default: sha256 of the current working directory,
+                         normalized to forward slashes and lowercased on
+                         Windows, then first 12 hex chars)
+  --telemetry-dir=<path> Override telemetry dir
+                         (default: <HOME>/.claude/hook-telemetry)
+  --help                 Show this help and exit 0
+
+Output:
+  One line per hook: "<hook> last <hours>h: pass=<n> block=<n>
+  skip-short=<n> total=<n> avg-duration=<X>ms".
+  If there are no records in the window: "no records in last <hours>h".
+
+The reader is parse-tolerant: malformed JSONL lines are skipped silently.
 `;
 function parseArgs(rawArgs) {
     const opts = {