continuous-improvement 3.1.0 → 3.8.0

package/bin/check-third-party-shape.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * Third-Party Snapshot Shape Invariant
+ *
+ * Verifies that every `third-party/<name>/` snapshot directory conforms to the
+ * vendor playbook documented in `third-party/README.md`. For each snapshot
+ * directory the check asserts:
+ *
+ *   1. `OUR_NOTES.md` exists and is non-empty
+ *   2. `LICENSE` exists
+ *   3. `third-party/MANIFEST.md` has at least one `### <heading>` block whose
+ *      `Local path` row points at this snapshot directory
+ *   4. The matching MANIFEST entry has a `Pinned SHA` row containing a
+ *      40-char lowercase hex string wrapped in backticks
+ *
+ * The mapping between snapshot directory and MANIFEST heading is NOT identity
+ * (e.g. dir `superpowers` <-> heading `obra/superpowers`). The check looks up
+ * by `Local path`, not by name.
+ *
+ * Usage:
+ *   node bin/check-third-party-shape.mjs              # check the current repo
+ *   node bin/check-third-party-shape.mjs <repo-root>  # check a specific repo root
+ *
+ * Exit codes:
+ *   0 - every snapshot is shape-compliant
+ *   1 - at least one drift found
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { argv, cwd, exit } from "node:process";
+const THIRD_PARTY_DIR = "third-party";
+const MANIFEST_FILENAME = "MANIFEST.md";
+const OUR_NOTES_FILENAME = "OUR_NOTES.md";
+const LICENSE_FILENAME = "LICENSE";
+const SHA_RE = /^[0-9a-f]{40}$/;
+export function discoverSnapshots(repoRoot) {
+    const dir = join(repoRoot, THIRD_PARTY_DIR);
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const snapshots = [];
+    for (const name of entries) {
+        const full = join(dir, name);
+        let entryStat;
+        try {
+            entryStat = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (!entryStat.isDirectory())
+            continue;
+        snapshots.push({
+            name,
+            hasOurNotes: hasNonEmptyFile(join(full, OUR_NOTES_FILENAME)),
+            hasLicense: fileExists(join(full, LICENSE_FILENAME)),
+        });
+    }
+    return snapshots;
+}
+function fileExists(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function hasNonEmptyFile(path) {
+    try {
+        const s = statSync(path);
+        return s.isFile() && s.size > 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function parseManifestEntries(manifestText) {
+    const lines = manifestText.split(/\r?\n/);
+    const entries = [];
+    let current = null;
+    const flush = () => {
+        if (current && current.localPath !== null)
+            entries.push(current);
+        current = null;
+    };
+    for (const line of lines) {
+        const headingMatch = line.match(/^###\s+(.+?)\s*$/);
+        if (headingMatch) {
+            flush();
+            current = { heading: headingMatch[1], pinnedSha: null, localPath: null };
+            continue;
+        }
+        if (line.match(/^##\s+/) || line.match(/^#\s+/)) {
+            flush();
+            continue;
+        }
+        if (!current)
+            continue;
+        const shaRow = line.match(/^\|\s*Pinned SHA\s*\|\s*`?([0-9a-fA-F]+)`?\s*\|/);
+        if (shaRow) {
+            current.pinnedSha = shaRow[1].toLowerCase();
+            continue;
+        }
+        const pathRow = line.match(/^\|\s*Local path\s*\|\s*`?([^`|]+?)`?\s*\|/);
+        if (pathRow) {
+            current.localPath = pathRow[1].trim();
+            continue;
+        }
+    }
+    flush();
+    return entries;
+}
+function normalizeLocalPath(p) {
+    let out = p.replace(/\\/g, "/").replace(/\/+$/, "");
+    if (out.startsWith("./"))
+        out = out.slice(2);
+    return out;
+}
+export function checkThirdPartyShape(repoRoot) {
+    const snapshots = discoverSnapshots(repoRoot);
+    const manifestPath = join(repoRoot, THIRD_PARTY_DIR, MANIFEST_FILENAME);
+    let manifestText = "";
+    try {
+        manifestText = readFileSync(manifestPath, "utf8");
+    }
+    catch {
+        /* no manifest at all - every snapshot will fail no-manifest-entry */
+    }
+    const entries = parseManifestEntries(manifestText);
+    const entryByLocalPath = new Map();
+    for (const e of entries) {
+        if (e.localPath)
+            entryByLocalPath.set(normalizeLocalPath(e.localPath), e);
+    }
+    const drifts = [];
+    for (const snap of snapshots) {
+        if (!snap.hasOurNotes) {
+            drifts.push({
+                kind: "missing-our-notes",
+                snapshot: snap.name,
+                detail: `expected non-empty ${OUR_NOTES_FILENAME} at ${THIRD_PARTY_DIR}/${snap.name}/`,
+            });
+        }
+        if (!snap.hasLicense) {
+            drifts.push({
+                kind: "missing-license",
+                snapshot: snap.name,
+                detail: `expected ${LICENSE_FILENAME} at ${THIRD_PARTY_DIR}/${snap.name}/`,
+            });
+        }
+        const expectedPath = `${THIRD_PARTY_DIR}/${snap.name}`;
+        const entry = entryByLocalPath.get(expectedPath);
+        if (!entry) {
+            drifts.push({
+                kind: "no-manifest-entry",
+                snapshot: snap.name,
+                detail: `no MANIFEST.md ### block has Local path \`${expectedPath}/\``,
+            });
+            continue;
+        }
+        if (!entry.pinnedSha || !SHA_RE.test(entry.pinnedSha)) {
+            drifts.push({
+                kind: "invalid-sha",
+                snapshot: snap.name,
+                detail: `MANIFEST entry "${entry.heading}" has Pinned SHA "${entry.pinnedSha ?? "(none)"}" - expected 40-char lowercase hex`,
+            });
+        }
+    }
+    return {
+        drifts,
+        snapshotCount: snapshots.length,
+        manifestEntryCount: entries.length,
+    };
+}
+function main() {
+    const repoRoot = argv[2] ?? cwd();
+    const { drifts, snapshotCount, manifestEntryCount } = checkThirdPartyShape(repoRoot);
+    if (drifts.length === 0) {
+        console.log(`OK third-party-shape: all ${snapshotCount} snapshot(s) compliant ` +
+            `(${manifestEntryCount} MANIFEST entr${manifestEntryCount === 1 ? "y" : "ies"} with Local path).`);
+        exit(0);
+    }
+    console.error(`FAIL third-party-shape: ${drifts.length} drift(s) across ${snapshotCount} snapshot(s).\n`);
+    for (const d of drifts) {
+        console.error(`  - [${d.kind}] ${d.snapshot}`);
+        if (d.detail)
+            console.error(`      ${d.detail}`);
+    }
+    console.error(`\nFix: see third-party/README.md "Layout" + third-party/MANIFEST.md ` +
+        `existing entries for the playbook shape (OUR_NOTES.md, LICENSE, ` +
+        `### <heading> block with Pinned SHA + Local path rows).`);
+    exit(1);
+}
+const invokedDirectly = argv[1] !== undefined && import.meta.url.endsWith(argv[1].replace(/\\/g, "/"));
+if (invokedDirectly || argv[1]?.endsWith("check-third-party-shape.mjs")) {
+    main();
+}

package/bin/generate-plugin-manifests.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+import { copyFile, mkdir, readdir, readFile, rm, writeFile, } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PACKAGE_NAME, PLUGIN_MODES, getPluginHooksConfig, getClaudePluginManifest, getClaudePluginMarketplaceManifest, getClaudeRepoMarketplaceManifest, getPluginManifest, } from "../lib/plugin-metadata.mjs";
+import { normalizeTier, parseSkillFrontmatter, renderBundledSkillsReadme, } from "../lib/skill-tiers.mjs";
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const PLUGINS_DIR = join(REPO_ROOT, "plugins");
+const PLUGIN_BUNDLE_DIR = join(PLUGINS_DIR, PACKAGE_NAME);
+const CLAUDE_REPO_MARKETPLACE_PATH = join(REPO_ROOT, ".claude-plugin", "marketplace.json");
+async function writeJson(filePath, data) {
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`);
+}
+async function copyFileTo(sourcePath, targetPath) {
+    await mkdir(dirname(targetPath), { recursive: true });
+    await copyFile(sourcePath, targetPath);
+}
+async function copyDirectory(sourceDir, targetDir) {
+    await mkdir(targetDir, { recursive: true });
+    const entries = await readdir(sourceDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const sourcePath = join(sourceDir, entry.name);
+        const targetPath = join(targetDir, entry.name);
+        if (entry.isDirectory()) {
+            await copyDirectory(sourcePath, targetPath);
+            continue;
+        }
+        if (entry.isFile()) {
+            await copyFile(sourcePath, targetPath);
+        }
+    }
+}
+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))
+        .sort();
+    await mkdir(targetSkillsDir, { recursive: true });
+    await copyFileTo(join(REPO_ROOT, "SKILL.md"), join(targetSkillsDir, PACKAGE_NAME, "SKILL.md"));
+    // Build the SkillMeta list as we copy each source skill into the bundle.
+    // The core continuous-improvement skill is treated as tier "core" — it's
+    // the 7 Laws spec itself, not a companion — so it leads the bundled README
+    // in its own section, separate from the featured companion.
+    const coreSkillContent = await readFile(join(REPO_ROOT, "SKILL.md"), "utf8");
+    const coreFrontmatter = parseSkillFrontmatter(coreSkillContent);
+    const skillsForReadme = [
+        {
+            name: PACKAGE_NAME,
+            tier: "core",
+            description: coreFrontmatter.description,
+        },
+    ];
+    for (const file of companionSkills) {
+        const skillName = basename(file, ".md");
+        const skillDir = join(targetSkillsDir, skillName);
+        await mkdir(skillDir, { recursive: true });
+        await copyFile(join(sourceSkillsDir, file), join(skillDir, "SKILL.md"));
+        const sourcePath = join(sourceSkillsDir, file);
+        const content = await readFile(sourcePath, "utf8");
+        const front = parseSkillFrontmatter(content);
+        skillsForReadme.push({
+            name: front.name ?? skillName,
+            tier: normalizeTier(front.tier),
+            description: front.description,
+        });
+    }
+    await writeFile(join(targetSkillsDir, "README.md"), renderBundledSkillsReadme(skillsForReadme));
+}
+async function writePluginBundleReadme() {
+    const readme = [
+        "# Continuous Improvement Plugin Bundle (Claude Code)",
+        "",
+        "This directory is generated by `npm run build`.",
+        "Do not edit files here manually; edit the source files in the repo root and rebuild.",
+        "",
+        "Included surfaces:",
+        "- `.claude-plugin/plugin.json`",
+        "- `.claude-plugin/marketplace.json`",
+        "- `skills/`",
+        "- `commands/`",
+        "- `hooks/`",
+        "- `bin/mcp-server.mjs`",
+        "- `bin/observe.mjs`",
+        "- `bin/backfill.mjs`",
+        "- `lib/plugin-metadata.mjs`",
+        "- `lib/observe-event.mjs`",
+        "- `instinct-packs/`",
+        "- `templates/planning-with-files/`",
+        "",
+        "## Required vs Optional companions",
+        "",
+        "The `proceed-with-the-recommendation` skill (bundled here) routes each",
+        "recommendation it walks to a specialist skill. Some specialists ship in",
+        "this bundle; the rest live in external plugins. Every external routing",
+        "target has a concretely-worded inline fallback in the orchestrator skill,",
+        "so the plugin works on a clean install with no other plugins present —",
+        "the trade-off is fallback quality vs dedicated-skill quality.",
+        "",
+        "**Bundled with this plugin (no extra install needed):**",
+        "",
+        "- `continuous-improvement` — core 7 Laws skill",
+        "- `proceed-with-the-recommendation` — the orchestrator itself",
+        "- `ralph` — autonomous PRD-scale loop",
+        "- `tdd-workflow` — RED/GREEN/REFACTOR + 80% coverage gate",
+        "- `workspace-surface-audit` — environment + capability audit",
+        "- Tier-1/Tier-2 enforcement skills (`gateguard`, `verification-loop`,",
+        "  `para-memory-files`, `safety-guard`, `token-budget-advisor`,",
+        "  `strategic-compact`, `wild-risa-balance`)",
+        "",
+        "**Optional companions the orchestrator routes to (install separately if",
+        "you want the dedicated skill instead of the inline fallback):**",
+        "",
+        "| Source plugin | Routing targets | Notes |",
+        "|---|---|---|",
+        "| `obra/superpowers` | `superpowers:brainstorming`, `:writing-plans`, `:systematic-debugging`, `:test-driven-development`, `:requesting-code-review`, `:verification-before-completion`, `:dispatching-parallel-agents`, `:finishing-a-development-branch`, `simplify`, `schedule`, `loop`, `update-config` | Largest external surface; covers planning, debugging, parallel dispatch, branch-finish |",
+        "| Claude Code host (Anthropic built-in) | `security-review` | Ships with the host CLI itself, not a separate plugin install |",
+        "| `code-review` plugin | `code-review` | Diff walk + severity tagging |",
+        "| `documentation-lookup` agent / `context7` MCP | `documentation-lookup` | Library docs lookup with citations |",
+        "| `frontend-design` plugin | `frontend-design:frontend-design` | Distinctive UI generation |",
+        "| `commit-commands` plugin | `commit-commands:commit`, `:commit-push-pr` | Conventional-commit + push-PR helpers |",
+        "",
+        "Full per-target audit (license status, bundled flag, inline fallback,",
+        "risk-if-absent) lives in `docs/audits/2026-05-06-routing-target-gap.md`.",
+        "Per-target inline fallbacks are spelled out in the orchestrator skill at",
+        "`skills/proceed-with-the-recommendation/SKILL.md` § \"Routing Table",
+        "(with Inline Fallbacks)\".",
+        "",
+    ].join("\n");
+    await writeFile(join(PLUGIN_BUNDLE_DIR, "README.md"), readme);
+}
+async function writePluginBundle() {
+    await rm(PLUGIN_BUNDLE_DIR, { recursive: true, force: true });
+    await mkdir(PLUGIN_BUNDLE_DIR, { recursive: true });
+    await Promise.all([
+        writeJson(join(PLUGIN_BUNDLE_DIR, ".claude-plugin", "plugin.json"), getClaudePluginManifest()),
+        writeJson(join(PLUGIN_BUNDLE_DIR, ".claude-plugin", "marketplace.json"), getClaudePluginMarketplaceManifest()),
+        copyDirectory(join(REPO_ROOT, "commands"), join(PLUGIN_BUNDLE_DIR, "commands")),
+        copyDirectory(join(REPO_ROOT, "hooks"), join(PLUGIN_BUNDLE_DIR, "hooks")),
+        copyDirectory(join(REPO_ROOT, "instinct-packs"), join(PLUGIN_BUNDLE_DIR, "instinct-packs")),
+        copyDirectory(join(REPO_ROOT, "templates", "planning-with-files"), join(PLUGIN_BUNDLE_DIR, "templates", "planning-with-files")),
+        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, "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, "LICENSE"), join(PLUGIN_BUNDLE_DIR, "LICENSE")),
+        writePluginBundleReadme(),
+    ]);
+    await writeJson(join(PLUGIN_BUNDLE_DIR, "hooks", "hooks.json"), getPluginHooksConfig());
+    await writeBundledSkills();
+    // PM plugins are no longer surfaced in the repo-level marketplace as the project
+    // refocuses on the 7 Laws of AI Agent Discipline. Source plugin directories under
+    // plugins/pm-* remain on disk pending follow-up removal. The discoverPm... helper
+    // is preserved so downstream consumers (and the function-level test) still work.
+    const pmEntries = [];
+    await writeJson(CLAUDE_REPO_MARKETPLACE_PATH, getClaudeRepoMarketplaceManifest(pmEntries));
+}
+await mkdir(PLUGINS_DIR, { recursive: true });
+for (const mode of PLUGIN_MODES) {
+    const outputPath = join(PLUGINS_DIR, `${mode}.json`);
+    await writeFile(outputPath, `${JSON.stringify(getPluginManifest(mode), null, 2)}\n`);
+    console.log(`Generated ${outputPath}`);
+}
+await writePluginBundle();
+console.log(`Generated ${join(PLUGIN_BUNDLE_DIR, ".claude-plugin", "plugin.json")}`);
+console.log(`Generated ${CLAUDE_REPO_MARKETPLACE_PATH}`);

package/bin/harvest-friction.mjs

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+/**
+ * Friction Harvest — turn observation rows into typed instincts.
+ *
+ * PR D of the second-release train (item 8 from the 28-day usage report).
+ *
+ * Reads `~/.claude/instincts/<project-hash>/observations.jsonl` produced by
+ * the Mulahazah hook (see `hooks/observe.sh` and `src/lib/observe-event.mts`),
+ * classifies failure rows into typed instincts, aggregates by deduplication
+ * key, scores confidence with a recency-weighted decay, and appends new
+ * instincts to `<project-hash>/instincts.jsonl`. Idempotent: re-running on
+ * the same observations does not duplicate previously-written instincts.
+ *
+ * Schema awareness:
+ *   - Rich-schema rows (input_summary + output_summary present) are the
+ *     contract surface. The classifier reads output_summary to detect
+ *     command-not-found, permission-denied, file-not-read, etc.
+ *   - Thin-schema rows (no input/output fields — emitted by the bash
+ *     fallback when jq is missing AND the Node observer is not on PATH)
+ *     return null from classifyObservation. The CLI reports the gap
+ *     explicitly rather than misclassifying.
+ *
+ * Slash-command wrapper (commands/harvest.md), Law-7 SKILL.md prose, and
+ * a scheduled trigger are explicitly out of scope for this PR. The trim
+ * is documented in docs/plans/2026-05-07-second-release-train.md.
+ *
+ * Usage:
+ *   node bin/harvest-friction.mjs                # current project
+ *   node bin/harvest-friction.mjs <project-hash> # specific project
+ *   node bin/harvest-friction.mjs --list         # show classifications without writing
+ */
+import { createHash } from "node:crypto";
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { argv, cwd, exit } from "node:process";
+const SUMMARY_TRUNCATE = 120;
+const DEDUP_KEY_INPUT_TRUNCATE = 120;
+/**
+ * Stable deduplication key. Truncates summary at 120 chars before hashing so
+ * minor output variance (timestamps, retry counts, paths) past the boundary
+ * does not split the same friction event into multiple instincts.
+ */
+export function computeDedupKey(c) {
+    const truncated = c.summary.length > DEDUP_KEY_INPUT_TRUNCATE
+        ? c.summary.slice(0, DEDUP_KEY_INPUT_TRUNCATE)
+        : c.summary;
+    return createHash("sha1").update(`${c.type}|${c.tool}|${truncated}`).digest("hex");
+}
+/**
+ * Classify a single observation row. Returns null when:
+ *   - The row is not a tool_complete event (no failure signal yet)
+ *   - The row lacks output_summary (thin-schema row — gap, not classifiable)
+ *   - The output does not match any known friction pattern (success row)
+ *
+ * Heuristics are deliberately specific to keep false-positive rate low.
+ * Each branch matches a documented failure mode the operator hit on this
+ * host in the last 28 days.
+ */
+export function classifyObservation(row) {
+    if (row.event !== "tool_complete")
+        return null;
+    const out = row.output_summary;
+    if (out === undefined || out === "")
+        return null;
+    const tool = row.tool;
+    const summary = out.length > SUMMARY_TRUNCATE ? out.slice(0, SUMMARY_TRUNCATE) : out;
+    // env_issue — missing tooling, wrong shell flavor, missing env var.
+    // Match before permission_block because "command not found" is a stronger signal
+    // than the generic "Permission denied" tail of the output.
+    if (/command not found/i.test(out) ||
+        /not recognized as (?:an internal|the name)/i.test(out) ||
+        /is not recognized as a cmdlet/i.test(out)) {
+        return build("env_issue", tool, summary, row.ts);
+    }
+    // permission_block — harness, sandbox, or OS denied the action.
+    if (/permission denied/i.test(out) ||
+        /harness[- ]blocked/i.test(out) ||
+        /sandbox/i.test(out) ||
+        /operation not permitted/i.test(out)) {
+        return build("permission_block", tool, summary, row.ts);
+    }
+    // wrong_approach — agent acted on stale state. The "file changed since last
+    // read" signal is the canonical case (parallel actor or skipped Read).
+    if (/file changed since last read/i.test(out) ||
+        /modified by (?:another session|the user)/i.test(out)) {
+        return build("wrong_approach", tool, summary, row.ts);
+    }
+    // buggy_code — agent's own input was malformed for the tool contract.
+    // Includes Edit-without-Read, ambiguous old_string, file-too-large, etc.
+    if (/file has not been read/i.test(out) ||
+        /old_string is not unique/i.test(out) ||
+        /string_to_replace not found/i.test(out) ||
+        /file too large/i.test(out)) {
+        return build("buggy_code", tool, summary, row.ts);
+    }
+    return null;
+}
+function build(type, tool, summary, evidence_ts) {
+    return {
+        type,
+        tool,
+        summary,
+        evidence_ts,
+        dedup_key: computeDedupKey({ type, tool, summary }),
+    };
+}
+/**
+ * Aggregate classifications by dedup_key into Instincts with frequency and
+ * recency-weighted confidence.
+ *
+ * Confidence model (deliberately simple for the first cut; tune in a follow-up
+ * once the operator has confirmed the classifier output is plausible):
+ *   confidence = min(1.0, log10(occurrence_count + 1) * recency_factor)
+ *   recency_factor = 0.5 + 0.5 * exp(-days_since_last_seen / 14)
+ *
+ * A single occurrence today: confidence ≈ log10(2) * 1.0 ≈ 0.30.
+ * Ten occurrences today:     confidence ≈ log10(11) * 1.0 ≈ 1.04 → clamp 1.0.
+ * One occurrence 30 days ago: confidence ≈ log10(2) * (0.5 + 0.5 * 0.118) ≈ 0.17.
+ */
+export function aggregateInstincts(classified) {
+    if (classified.length === 0)
+        return [];
+    const groups = new Map();
+    for (const c of classified) {
+        const list = groups.get(c.dedup_key) ?? [];
+        list.push(c);
+        groups.set(c.dedup_key, list);
+    }
+    const now = Date.now();
+    const instincts = [];
+    for (const [, group] of groups) {
+        const sorted = [...group].sort((a, b) => a.evidence_ts.localeCompare(b.evidence_ts));
+        const first = sorted[0];
+        const last = sorted[sorted.length - 1];
+        const occurrence_count = group.length;
+        const lastSeenMs = Date.parse(last.evidence_ts);
+        const daysSince = isFinite(lastSeenMs) ? (now - lastSeenMs) / 86400000 : 0;
+        const recency_factor = 0.5 + 0.5 * Math.exp(-Math.max(0, daysSince) / 14);
+        const raw = Math.log10(occurrence_count + 1) * recency_factor;
+        const confidence = Math.max(0, Math.min(1, raw));
+        instincts.push({
+            type: first.type,
+            tool: first.tool,
+            summary: first.summary,
+            evidence_ts: last.evidence_ts,
+            dedup_key: first.dedup_key,
+            confidence,
+            occurrence_count,
+            first_seen: first.evidence_ts,
+            last_seen: last.evidence_ts,
+        });
+    }
+    return instincts.sort((a, b) => b.confidence - a.confidence);
+}
+/**
+ * Read existing instincts.jsonl and return the set of dedup keys already
+ * recorded. Missing file is treated as empty (idempotent first run).
+ * Malformed lines are skipped silently — a partially-written instincts.jsonl
+ * should not block the next harvest.
+ */
+export function loadExistingDedupKeys(instinctsJsonlPath) {
+    if (!existsSync(instinctsJsonlPath))
+        return new Set();
+    const keys = new Set();
+    const content = readFileSync(instinctsJsonlPath, "utf8");
+    for (const line of content.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        try {
+            const obj = JSON.parse(line);
+            if (typeof obj.dedup_key === "string")
+                keys.add(obj.dedup_key);
+        }
+        catch {
+            // Skip malformed line.
+        }
+    }
+    return keys;
+}
+export function harvest(observationsPath, instinctsPath) {
+    if (!existsSync(observationsPath)) {
+        return { totalRows: 0, toolCompleteRows: 0, classifiedRows: 0, thinSchemaRows: 0, newInstincts: [], skippedExisting: 0 };
+    }
+    const content = readFileSync(observationsPath, "utf8");
+    const lines = content.split("\n").filter((l) => l.trim() !== "");
+    const classified = [];
+    let toolCompleteRows = 0;
+    let thinSchemaRows = 0;
+    for (const line of lines) {
+        let row;
+        try {
+            row = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (row.event === "tool_complete") {
+            toolCompleteRows++;
+            if (row.output_summary === undefined || row.output_summary === "") {
+                thinSchemaRows++;
+                continue;
+            }
+        }
+        const c = classifyObservation(row);
+        if (c)
+            classified.push(c);
+    }
+    const allInstincts = aggregateInstincts(classified);
+    const existing = loadExistingDedupKeys(instinctsPath);
+    const newInstincts = allInstincts.filter((i) => !existing.has(i.dedup_key));
+    return {
+        totalRows: lines.length,
+        toolCompleteRows,
+        classifiedRows: classified.length,
+        thinSchemaRows,
+        newInstincts,
+        skippedExisting: allInstincts.length - newInstincts.length,
+    };
+}
+function defaultProjectHash() {
+    // Mirror the bash hook's hashing rule: sha256(project_root) → first 12 hex chars.
+    // Keeps the CLI compatible with whatever directory the bash hook was already
+    // populating, without re-implementing project-root detection here.
+    const root = cwd();
+    return createHash("sha256").update(root).digest("hex").slice(0, 12);
+}
+function main() {
+    const args = argv.slice(2);
+    const listOnly = args.includes("--list");
+    const positional = args.filter((a) => !a.startsWith("--"));
+    const projectHash = positional[0] ?? defaultProjectHash();
+    const projectDir = join(homedir(), ".claude", "instincts", projectHash);
+    const observationsPath = join(projectDir, "observations.jsonl");
+    const instinctsPath = join(projectDir, "instincts.jsonl");
+    const result = harvest(observationsPath, instinctsPath);
+    console.log(`harvest-friction project=${projectHash}`);
+    console.log(`  observations rows:    ${result.totalRows}`);
+    console.log(`  tool_complete rows:   ${result.toolCompleteRows}`);
+    console.log(`  classified failures:  ${result.classifiedRows}`);
+    console.log(`  thin-schema rows:     ${result.thinSchemaRows}`);
+    console.log(`  new instincts:        ${result.newInstincts.length}`);
+    console.log(`  skipped (existing):   ${result.skippedExisting}`);
+    if (result.totalRows > 0 && result.toolCompleteRows === 0) {
+        console.log("");
+        console.log("WARNING: observations contain only tool_start events.");
+        console.log("  The bash fallback in hooks/observe.sh emits tool_start when jq is missing AND");
+        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.");
+    }
+    else if (result.thinSchemaRows > 0 && result.classifiedRows === 0) {
+        console.log("");
+        console.log("WARNING: tool_complete rows found but lack output_summary fields.");
+        console.log("  The classifier needs the rich-schema output_summary to detect failures.");
+        console.log("  Confirm the Node observer (src/bin/observe.mts) is the active hook.");
+    }
+    if (result.newInstincts.length === 0) {
+        return;
+    }
+    console.log("");
+    console.log("New instincts:");
+    for (const i of result.newInstincts) {
+        const conf = i.confidence.toFixed(2);
+        console.log(`  [${conf}] ${i.type} on ${i.tool} (×${i.occurrence_count}): ${i.summary}`);
+    }
+    if (listOnly)
+        return;
+    for (const i of result.newInstincts) {
+        appendFileSync(instinctsPath, JSON.stringify(i) + "\n");
+    }
+    console.log(`\nAppended ${result.newInstincts.length} instinct(s) to ${instinctsPath}`);
+}
+const invokedDirectly = argv[1]?.endsWith("harvest-friction.mjs");
+if (invokedDirectly) {
+    main();
+    exit(0);
+}