continuous-improvement 3.1.0 → 3.8.0

package/bin/observe.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+// observe.mts — Mulahazah PreToolUse/PostToolUse observation hook.
+//
+// Reads a Claude Code hook JSON payload from stdin and appends one rich-schema
+// JSONL line to ~/.claude/instincts/<project-hash>/observations.jsonl. Drop-in
+// replacement for the bash observe.sh fallback path: no jq dependency, captures
+// `tool_input.command` for Bash and `Edit.file_path` for Edit/Write/Read so the
+// downstream analysis pass can detect user corrections, error→fix sequences,
+// and tool-argument bigrams the thin schema could not represent.
+//
+// Contract:
+//   - Always exits 0. Never blocks the Claude session.
+//   - Catches every error to stderr; never throws.
+//   - Empty stdin / malformed JSON / missing tool_name → no-op exit 0.
+//   - Hook budget: <500ms on Windows (per CONTRIBUTING.md).
+//
+// See docs/plans/2026-05-05-node-observer-rich-schema.md for the full design.
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { parseHookPayload, summariseInput, summariseOutput } from "../lib/observe-event.mjs";
+const ROTATION_LINE_THRESHOLD = 10_000;
+const ARCHIVE_RETENTION = 10;
+main();
+function main() {
+    try {
+        runObserver();
+    }
+    catch (error) {
+        // Never block the session. Failures land in stderr only.
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`[observe] ${message}\n`);
+    }
+    process.exit(0);
+}
+function runObserver() {
+    const raw = readStdin();
+    const payload = parseHookPayload(raw);
+    if (!payload)
+        return;
+    const projectRoot = resolveProjectRoot();
+    const projectHash = createHash("sha256").update(projectRoot).digest("hex").slice(0, 12);
+    const projectName = basename(projectRoot.replace(/\.git$/, ""));
+    const instinctsDir = join(getHomeDir(), ".claude", "instincts");
+    const projectDir = join(instinctsDir, projectHash);
+    const obsFile = join(projectDir, "observations.jsonl");
+    ensureDir(projectDir);
+    rotateIfNeeded(obsFile, projectDir);
+    const ts = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+    const event = payload.tool_response !== undefined ? "tool_complete" : "tool_start";
+    const row = {
+        ts,
+        event,
+        session: payload.session_id,
+        tool: payload.tool_name,
+        input_summary: summariseInput(payload.tool_name, payload.tool_input),
+        output_summary: summariseOutput(payload.tool_response),
+        project_id: projectHash,
+        project_name: projectName,
+    };
+    appendFileSync(obsFile, JSON.stringify(row) + "\n", "utf8");
+    writeProjectJsonIfNew(projectDir, projectHash, projectName, projectRoot, ts);
+}
+function readStdin() {
+    try {
+        return readFileSync(0, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function getHomeDir() {
+    // CLAUDE_PROJECT_DIR is the project root, not the home dir; HOME wins for
+    // home-dir resolution. Fall through to USERPROFILE on Windows then os.homedir.
+    return process.env.HOME || process.env.USERPROFILE || homedir();
+}
+function resolveProjectRoot() {
+    const fromEnv = process.env.CLAUDE_PROJECT_DIR;
+    // The bash version trusts CLAUDE_PROJECT_DIR unconditionally when set;
+    // preserve that semantic so test fixtures with synthetic /tmp/... paths
+    // and operator workflows that pre-set the env var both keep working.
+    if (fromEnv)
+        return fromEnv;
+    try {
+        // execFileSync (not execSync) — no shell, fixed argv array, no injection
+        // surface. Inputs are all hard-coded constants.
+        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 — fall through.
+    }
+    return "global";
+}
+function ensureDir(dir) {
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+}
+function rotateIfNeeded(obsFile, projectDir) {
+    if (!existsSync(obsFile))
+        return;
+    const lineCount = countLines(obsFile);
+    if (lineCount < ROTATION_LINE_THRESHOLD)
+        return;
+    const archiveTs = new Date().toISOString().replace(/[:.]/g, "-").replace(/Z$/, "");
+    renameSync(obsFile, join(projectDir, `observations.${archiveTs}.jsonl`));
+    pruneArchives(projectDir);
+}
+function countLines(file) {
+    const stat = statSync(file);
+    if (stat.size === 0)
+        return 0;
+    // For files capped at 10k lines, readFileSync is faster than streaming.
+    return readFileSync(file, "utf8").split("\n").length - 1;
+}
+function pruneArchives(projectDir) {
+    const archives = readdirSync(projectDir)
+        .filter((name) => /^observations\..+\.jsonl$/.test(name))
+        .sort()
+        .reverse()
+        .map((name) => join(projectDir, name));
+    for (const path of archives.slice(ARCHIVE_RETENTION)) {
+        try {
+            unlinkSync(path);
+        }
+        catch {
+            // Pruning failure is non-fatal; rotation already happened.
+        }
+    }
+}
+function writeProjectJsonIfNew(projectDir, projectHash, projectName, projectRoot, ts) {
+    const projectJson = join(projectDir, "project.json");
+    if (existsSync(projectJson))
+        return;
+    const body = {
+        id: projectHash,
+        name: projectName,
+        root: projectRoot,
+        created_at: ts,
+    };
+    writeFileSync(projectJson, JSON.stringify(body) + "\n", "utf8");
+}

package/bin/pre-commit-block-strays.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+#
+# pre-commit hook: block staging of paths that were already cleaned up
+# from the repo (and added to .gitignore) but could leak back in via
+# `git add -f` or accidental staging. Belt-and-suspenders alongside
+# .gitignore — .gitignore is silent if you bypass it; this hook is loud.
+#
+# Install:
+#   ln -s "$(pwd)/bin/pre-commit-block-strays.sh" .git/hooks/pre-commit
+#   # or, if you already have a pre-commit hook, source this from it.
+#
+# Exit codes:
+#   0 — no blocked paths in the staged diff
+#   1 — at least one blocked path is staged; commit is aborted
+
+set -u
+
+# Paths that have ever historically leaked into the repo and are now ignored.
+# Add an entry here when a new transient/output directory is removed.
+BLOCKED_PATTERNS=(
+  '^\.tmp-stop-e2e/'
+  '^nanobanana-output/'
+)
+
+staged_paths="$(git diff --cached --name-only --diff-filter=AM)"
+if [ -z "$staged_paths" ]; then
+  exit 0
+fi
+
+violations=""
+while IFS= read -r path; do
+  for pattern in "${BLOCKED_PATTERNS[@]}"; do
+    if printf '%s\n' "$path" | grep -qE "$pattern"; then
+      violations="${violations}  - $path  (matches /$pattern/)"$'\n'
+    fi
+  done
+done <<< "$staged_paths"
+
+if [ -n "$violations" ]; then
+  printf 'pre-commit: refusing to commit paths under historically-removed directories.\n\n'
+  printf '%s\n' "$violations"
+  printf 'These paths are .gitignore-blocked and have been removed from the repo;\n'
+  printf 'they should not re-enter via the staging area. If you really need to commit\n'
+  printf 'one of them, edit bin/pre-commit-block-strays.sh first to remove the pattern,\n'
+  printf 'document the reason, and commit that change as its own PR.\n'
+  exit 1
+fi
+
+exit 0

package/bin/refresh-third-party.mjs

@@ -0,0 +1,416 @@
+#!/usr/bin/env node
+/**
+ * Refresh vendored third-party snapshots.
+ *
+ * Reads pinned SHAs from third-party/MANIFEST.md and rerunns the documented
+ * selective copy for each snapshot, in code, so refreshes are reproducible
+ * across Windows / macOS / Linux without bash.
+ *
+ * The bash recipes in MANIFEST.md remain the authoritative human-readable
+ * spec; this driver mirrors them. If you change the selective surface for
+ * a snapshot, update MANIFEST.md and the SNAPSHOTS table below together.
+ *
+ * Usage:
+ *   node bin/refresh-third-party.mjs --list
+ *       List configured snapshots with their pinned SHAs.
+ *
+ *   node bin/refresh-third-party.mjs <name> --check
+ *       Shallow-clone upstream, compare HEAD to the pinned SHA. No file writes.
+ *
+ *   node bin/refresh-third-party.mjs <name>
+ *       Full refresh: shallow clone, verify HEAD matches the pinned SHA,
+ *       wipe the local path, recreate it, copy the selective surface
+ *       verbatim, strip every CLAUDE.md inside the snapshot, print a diff
+ *       stat. Aborts if the local snapshot path has uncommitted changes
+ *       unless --force is passed.
+ *
+ *   node bin/refresh-third-party.mjs --all
+ *   node bin/refresh-third-party.mjs --all --check
+ *       Same as above, applied to every configured snapshot in order.
+ *
+ *   node bin/refresh-third-party.mjs --help
+ *       Print this usage block.
+ *
+ * Exit codes:
+ *   0 — success (or --check found everything up-to-date)
+ *   1 — refresh failed, dirty working tree without --force, or --check found drift
+ *   2 — bad CLI usage / unknown snapshot name
+ */
+import { spawnSync } from "node:child_process";
+import { cp, mkdir, readFile, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { argv, cwd, exit, stderr, stdout } from "node:process";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(SCRIPT_DIR, "..");
+const MANIFEST_PATH = join(REPO_ROOT, "third-party", "MANIFEST.md");
+
+/**
+ * Per-snapshot config. Mirrors the bash recipe blocks in MANIFEST.md.
+ * `manifestHeading` is the literal `### <heading>` text used to locate the
+ * pinned SHA row in MANIFEST.md.
+ */
+const SNAPSHOTS = [
+  {
+    name: "oh-my-claudecode",
+    manifestHeading: "oh-my-claudecode",
+    upstream: "https://github.com/Yeachan-Heo/oh-my-claudecode.git",
+    localPath: "third-party/oh-my-claudecode",
+    selectiveDirs: [
+      "agents",
+      "skills",
+      "missions",
+      "templates",
+      "examples",
+      "hooks",
+      "docs",
+      ".claude-plugin",
+    ],
+    selectiveFiles: [
+      "LICENSE",
+      "README.md",
+      "AGENTS.md",
+      "CHANGELOG.md",
+      "SECURITY.md",
+    ],
+  },
+  {
+    name: "superpowers",
+    manifestHeading: "obra/superpowers",
+    upstream: "https://github.com/obra/superpowers.git",
+    localPath: "third-party/superpowers",
+    selectiveDirs: ["skills", "hooks", "docs", "assets", ".claude-plugin"],
+    selectiveFiles: [
+      "LICENSE",
+      "README.md",
+      "AGENTS.md",
+      "CODE_OF_CONDUCT.md",
+      "RELEASE-NOTES.md",
+    ],
+  },
+];
+
+const SHA_RE = /^[0-9a-f]{40}$/i;
+
+function log(msg) {
+  stdout.write(msg + "\n");
+}
+function err(msg) {
+  stderr.write(msg + "\n");
+}
+
+function usage() {
+  err(
+    [
+      "Usage:",
+      "  node bin/refresh-third-party.mjs --list",
+      "  node bin/refresh-third-party.mjs <name> --check",
+      "  node bin/refresh-third-party.mjs <name> [--force]",
+      "  node bin/refresh-third-party.mjs --all [--check] [--force]",
+      "  node bin/refresh-third-party.mjs --help",
+      "",
+      "Configured snapshots: " + SNAPSHOTS.map((s) => s.name).join(", "),
+    ].join("\n"),
+  );
+}
+
+/**
+ * Parse the pinned SHA for a snapshot from MANIFEST.md.
+ * Strategy: locate `### <heading>`, then the first table row in that
+ * section beginning with `| Pinned SHA |`.
+ */
+async function readPinnedSha(snapshot) {
+  const text = await readFile(MANIFEST_PATH, "utf8");
+  const lines = text.split(/\r?\n/);
+  const headingIdx = lines.findIndex(
+    (line) => line.trim() === `### ${snapshot.manifestHeading}`,
+  );
+  if (headingIdx === -1) {
+    throw new Error(
+      `MANIFEST.md missing heading "### ${snapshot.manifestHeading}"`,
+    );
+  }
+  for (let i = headingIdx + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith("### ")) break;
+    const m = line.match(/^\|\s*Pinned SHA\s*\|\s*`?([0-9a-fA-F]{7,40})`?\s*\|/);
+    if (m) {
+      const sha = m[1].toLowerCase();
+      if (!SHA_RE.test(sha)) {
+        throw new Error(
+          `MANIFEST.md "${snapshot.manifestHeading}": pinned SHA "${sha}" is not a 40-char hex`,
+        );
+      }
+      return sha;
+    }
+  }
+  throw new Error(
+    `MANIFEST.md "${snapshot.manifestHeading}": no "| Pinned SHA |" row found`,
+  );
+}
+
+function runGit(args, opts = {}) {
+  const result = spawnSync("git", args, {
+    encoding: "utf8",
+    ...opts,
+  });
+  if (result.error) {
+    throw new Error(`git ${args.join(" ")} failed: ${result.error.message}`);
+  }
+  return result;
+}
+
+function gitOk(args, opts = {}) {
+  const r = runGit(args, opts);
+  if (r.status !== 0) {
+    throw new Error(
+      `git ${args.join(" ")} exited ${r.status}: ${r.stderr || r.stdout}`,
+    );
+  }
+  return r.stdout.trim();
+}
+
+/**
+ * Shallow-clone upstream into a temp dir and return { dir, headSha }.
+ */
+async function shallowClone(upstream) {
+  const dir = join(
+    tmpdir(),
+    `ci-refresh-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+  );
+  gitOk(["clone", "--depth", "1", upstream, dir]);
+  const headSha = gitOk(["-C", dir, "rev-parse", "HEAD"]);
+  return { dir, headSha };
+}
+
+async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ask git whether the local snapshot path has uncommitted changes.
+ * Runs from REPO_ROOT so worktrees are handled correctly.
+ */
+function localPathDirty(relPath) {
+  const r = runGit(
+    ["status", "--porcelain", "--", relPath],
+    { cwd: REPO_ROOT },
+  );
+  if (r.status !== 0) {
+    throw new Error(
+      `git status failed for ${relPath}: ${r.stderr || r.stdout}`,
+    );
+  }
+  return r.stdout.trim().length > 0;
+}
+
+async function deleteClaudeMdRecursive(root) {
+  // Node-only equivalent of `find <root> -name CLAUDE.md -type f -delete`.
+  const { readdir } = await import("node:fs/promises");
+  const stack = [root];
+  let deleted = 0;
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const ent of entries) {
+      const full = join(dir, ent.name);
+      if (ent.isDirectory()) {
+        stack.push(full);
+      } else if (ent.isFile() && ent.name === "CLAUDE.md") {
+        await rm(full, { force: true });
+        deleted++;
+      }
+    }
+  }
+  return deleted;
+}
+
+async function checkOne(snapshot) {
+  const pinned = await readPinnedSha(snapshot);
+  const { dir, headSha } = await shallowClone(snapshot.upstream);
+  try {
+    const upToDate = headSha.toLowerCase() === pinned.toLowerCase();
+    log(`[${snapshot.name}]`);
+    log(`  upstream     : ${snapshot.upstream}`);
+    log(`  pinned SHA   : ${pinned}`);
+    log(`  upstream HEAD: ${headSha}`);
+    log(`  status       : ${upToDate ? "up-to-date" : "would-update"}`);
+    return upToDate;
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+async function refreshOne(snapshot, { force }) {
+  const pinned = await readPinnedSha(snapshot);
+  const localAbs = join(REPO_ROOT, snapshot.localPath);
+
+  if (!force && (await pathExists(localAbs))) {
+    if (localPathDirty(snapshot.localPath)) {
+      throw new Error(
+        `local snapshot path "${snapshot.localPath}" has uncommitted changes; ` +
+          `commit/stash first, or rerun with --force`,
+      );
+    }
+  }
+
+  const { dir, headSha } = await shallowClone(snapshot.upstream);
+  try {
+    if (headSha.toLowerCase() !== pinned.toLowerCase()) {
+      throw new Error(
+        `[${snapshot.name}] upstream HEAD ${headSha} != pinned ${pinned}; ` +
+          `bump the pinned SHA in third-party/MANIFEST.md first`,
+      );
+    }
+
+    // Wipe + recreate destination.
+    await rm(localAbs, { recursive: true, force: true });
+    await mkdir(localAbs, { recursive: true });
+
+    // Copy selective directories.
+    let copiedDirs = 0;
+    for (const d of snapshot.selectiveDirs) {
+      const src = join(dir, d);
+      if (!(await pathExists(src))) {
+        throw new Error(
+          `[${snapshot.name}] expected directory "${d}" missing in upstream`,
+        );
+      }
+      await cp(src, join(localAbs, d), { recursive: true });
+      copiedDirs++;
+    }
+    // Copy selective top-level files.
+    let copiedFiles = 0;
+    for (const f of snapshot.selectiveFiles) {
+      const src = join(dir, f);
+      if (!(await pathExists(src))) {
+        throw new Error(
+          `[${snapshot.name}] expected file "${f}" missing in upstream`,
+        );
+      }
+      await cp(src, join(localAbs, f));
+      copiedFiles++;
+    }
+
+    // Strip every CLAUDE.md (auto-loads as session context).
+    const stripped = await deleteClaudeMdRecursive(localAbs);
+
+    // Print git diff stat scoped to the snapshot path.
+    const diffStat = runGit(
+      ["diff", "--stat", "--", snapshot.localPath],
+      { cwd: REPO_ROOT },
+    );
+    log(`[${snapshot.name}]`);
+    log(`  upstream     : ${snapshot.upstream}`);
+    log(`  pinned SHA   : ${pinned}`);
+    log(`  upstream HEAD: ${headSha}`);
+    log(
+      `  status       : updated (${copiedDirs} dirs, ${copiedFiles} files, ${stripped} CLAUDE.md stripped)`,
+    );
+    if (diffStat.stdout.trim()) {
+      log("  diff --stat  :");
+      for (const line of diffStat.stdout.trimEnd().split(/\r?\n/)) {
+        log(`    ${line}`);
+      }
+    } else {
+      log("  diff --stat  : (no working-tree change)");
+    }
+    return true;
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+async function listAll() {
+  log("Configured third-party snapshots:");
+  for (const s of SNAPSHOTS) {
+    let pinned;
+    try {
+      pinned = await readPinnedSha(s);
+    } catch (e) {
+      pinned = `<error: ${e.message}>`;
+    }
+    log(`  - ${s.name}`);
+    log(`      upstream  : ${s.upstream}`);
+    log(`      localPath : ${s.localPath}`);
+    log(`      pinnedSHA : ${pinned}`);
+  }
+}
+
+function findSnapshot(name) {
+  return SNAPSHOTS.find((s) => s.name === name);
+}
+
+async function main() {
+  const args = argv.slice(2);
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    usage();
+    exit(args.length === 0 ? 2 : 0);
+  }
+
+  if (args.includes("--list")) {
+    await listAll();
+    exit(0);
+  }
+
+  const force = args.includes("--force");
+  const check = args.includes("--check");
+  const all = args.includes("--all");
+
+  const positional = args.filter((a) => !a.startsWith("--"));
+
+  let targets;
+  if (all) {
+    targets = SNAPSHOTS;
+  } else if (positional.length === 1) {
+    const snap = findSnapshot(positional[0]);
+    if (!snap) {
+      err(
+        `Unknown snapshot "${positional[0]}". Known: ${SNAPSHOTS.map((s) => s.name).join(", ")}`,
+      );
+      exit(2);
+    }
+    targets = [snap];
+  } else {
+    usage();
+    exit(2);
+  }
+
+  let allUpToDate = true;
+  let firstErr;
+  for (const snap of targets) {
+    try {
+      if (check) {
+        const ok = await checkOne(snap);
+        if (!ok) allUpToDate = false;
+      } else {
+        await refreshOne(snap, { force });
+      }
+    } catch (e) {
+      firstErr = firstErr || e;
+      err(`[${snap.name}] ERROR: ${e.message}`);
+      allUpToDate = false;
+    }
+  }
+
+  if (firstErr) exit(1);
+  if (check && !allUpToDate) exit(1);
+  exit(0);
+}
+
+main().catch((e) => {
+  err(`fatal: ${e.stack || e.message}`);
+  exit(1);
+});