continuous-improvement 3.12.3 → 3.16.0

package/bin/check-skill-count-prose.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * Skill Count Prose Check
+ *
+ * Sibling to `verify:skill-count`. That lint gates the literal phrase
+ * "N bundled skills" in the 5 generator-owned manifest surfaces. This lint
+ * gates the *human-facing* prose — the phrasings the marketing/docs copy
+ * actually uses, which no other invariant checks and which therefore rot
+ * silently every time a skill is added without a full prose cascade.
+ *
+ * Origin: PR #255 (`/roast`, the 26th skill) bumped the gated "N bundled
+ * skills" manifests but left README.md / docs/skills.md / docs/skill-use-cases.md
+ * / CONTRIBUTING.md / docs/using-this-plugin.md at "25 skills / 14 tier-2".
+ * verify:all stayed green because nothing checked those surfaces.
+ * `reports/daily-improvement.md` logs three prior rounds of the same drift.
+ *
+ * Single source of truth: the skill set on disk. The total and the
+ * core/featured/tier-1/tier-2/companion breakdown are *derived* from
+ * `skills/*.md` + the root `SKILL.md` frontmatter via the same primitives the
+ * tier lint uses (`discoverSkillSources`, `parseSkillFrontmatter`,
+ * `normalizeTier`). Nothing is hardcoded — add or retire a skill and this lint
+ * recomputes the expected numbers, then names every doc that disagrees.
+ *
+ * Checked surfaces (file → which derived claims it must contain):
+ *   - README.md                  breakdown, total-skills, next-ordinal
+ *   - docs/skills.md             breakdown, total-skills, total-catalog, next-ordinal
+ *   - docs/skill-use-cases.md    breakdown, total-skills
+ *   - CONTRIBUTING.md            total-skills
+ *   - docs/using-this-plugin.md  total-catalog
+ *
+ * Usage:
+ *   node bin/check-skill-count-prose.mjs              # Check the current repo
+ *   node bin/check-skill-count-prose.mjs <repo-root>  # Check a specific repo root
+ *
+ * Exit codes:
+ *   0 — every checked surface states the bundle-derived count
+ *   1 — at least one surface states a stale count, or a surface file is missing
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { argv, cwd, exit } from "node:process";
+import { normalizeTier, parseSkillFrontmatter } from "../lib/skill-tiers.mjs";
+import { discoverSkillSources } from "./check-skill-tiers.mjs";
+/** Derive the total + per-tier breakdown from `skills/` + root SKILL.md frontmatter. */
+export function deriveCounts(repoRoot) {
+    const sources = discoverSkillSources(repoRoot);
+    const tally = { core: 0, featured: 0, tier1: 0, tier2: 0, companion: 0, unknown: 0 };
+    for (const src of sources) {
+        const front = parseSkillFrontmatter(readFileSync(src.path, "utf8"));
+        switch (normalizeTier(front.tier)) {
+            case "core":
+                tally.core++;
+                break;
+            case "featured":
+                tally.featured++;
+                break;
+            case "1":
+                tally.tier1++;
+                break;
+            case "2":
+                tally.tier2++;
+                break;
+            case "companion":
+                tally.companion++;
+                break;
+            default:
+                tally.unknown++;
+                break;
+        }
+    }
+    const total = sources.length;
+    return { ...tally, total, next: total + 1 };
+}
+/** English ordinal: 1→1st, 2→2nd, 3→3rd, 11→11th, 21→21st, 27→27th. */
+export function ordinal(n) {
+    const mod100 = n % 100;
+    if (mod100 >= 11 && mod100 <= 13)
+        return `${n}th`;
+    switch (n % 10) {
+        case 1:
+            return `${n}st`;
+        case 2:
+            return `${n}nd`;
+        case 3:
+            return `${n}rd`;
+        default:
+            return `${n}th`;
+    }
+}
+/** The exact substring a surface must contain for the given check kind. */
+export function expectedFor(check, c) {
+    switch (check) {
+        case "breakdown":
+            return `${c.core} core + ${c.featured} featured + ${c.tier1} tier-1 + ${c.tier2} tier-2 + ${c.companion} always-bundled`;
+        case "total-skills":
+            return `${c.total} skills`;
+        case "total-catalog":
+            return `${c.total}-skill catalog`;
+        case "next-ordinal":
+            return `${ordinal(c.next)} skill`;
+    }
+}
+export const PROSE_SURFACES = [
+    { file: "README.md", checks: ["breakdown", "total-skills", "next-ordinal"] },
+    {
+        file: "docs/skills.md",
+        checks: ["breakdown", "total-skills", "total-catalog", "next-ordinal"],
+    },
+    { file: "docs/skill-use-cases.md", checks: ["breakdown", "total-skills"] },
+    { file: "CONTRIBUTING.md", checks: ["total-skills"] },
+    { file: "docs/using-this-plugin.md", checks: ["total-catalog"] },
+];
+/**
+ * Assert every surface contains every derived claim it owns. `counts` defaults
+ * to the value derived from `repoRoot`; pass it explicitly to test the
+ * surface-matching logic in isolation.
+ */
+export function checkProseSurfaces(repoRoot, counts, surfaces = PROSE_SURFACES) {
+    const c = counts ?? deriveCounts(repoRoot);
+    const failures = [];
+    for (const surface of surfaces) {
+        let content;
+        try {
+            content = readFileSync(join(repoRoot, surface.file), "utf8");
+        }
+        catch {
+            content = null;
+        }
+        for (const check of surface.checks) {
+            const expected = expectedFor(check, c);
+            if (content === null) {
+                failures.push({ file: surface.file, check, expected, reason: "target-missing" });
+                continue;
+            }
+            if (!content.includes(expected)) {
+                failures.push({ file: surface.file, check, expected, reason: "stale" });
+            }
+        }
+    }
+    return failures;
+}
+function main() {
+    const repoRoot = argv[2] ?? cwd();
+    const counts = deriveCounts(repoRoot);
+    const failures = checkProseSurfaces(repoRoot, counts);
+    if (failures.length === 0) {
+        console.log(`OK skill-count-prose: all ${PROSE_SURFACES.length} doc surface(s) state the derived count (total=${counts.total}: ${expectedFor("breakdown", counts)}).`);
+        exit(0);
+    }
+    console.error(`FAIL skill-count-prose: ${failures.length} doc prose claim(s) do not match the bundle-derived count of ${counts.total}.`);
+    console.error(`Source of truth: skills/ frontmatter → ${expectedFor("breakdown", counts)} = ${counts.total} skills; next skill is the ${ordinal(counts.next)}.`);
+    console.error("");
+    for (const f of failures) {
+        if (f.reason === "target-missing") {
+            console.error(`  ${f.file} — file not found (expected to contain "${f.expected}")`);
+        }
+        else {
+            console.error(`  ${f.file} — missing "${f.expected}" [${f.check}]`);
+        }
+    }
+    console.error("");
+    console.error("Fix: bump the prose in the named file(s) to the derived count. When a skill is genuinely added or retired, this lint enumerates every human-facing surface that needs the same change.");
+    exit(1);
+}
+const invokedDirectly = argv[1] !== undefined && import.meta.url.endsWith(argv[1].replace(/\\/g, "/"));
+if (invokedDirectly || argv[1]?.endsWith("check-skill-count-prose.mjs")) {
+    main();
+}

package/bin/check-skill-count.mjs

@@ -24,6 +24,11 @@
  *   - plugins/continuous-improvement/.claude-plugin/plugin.json
  *   - package.json
  *   - llms.txt
+ *   - .cloudplugin/marketplace.json   (hand-maintained, not generator-owned)
+ *
+ * Stat-block files (count lives in a split HTML stat, not the phrase):
+ *   - docs/landing/index.html — `<span class="v">N</span><span class="k">Bundled skills</span>`
+ *     (PR #229 found this surface stale at 25 while every phrase file said 26)
  *
  * Usage:
  *   node bin/check-skill-count.mjs              # Check the current repo
@@ -42,7 +47,9 @@ const CHECKED_FILES = [
     "plugins/continuous-improvement/.claude-plugin/plugin.json",
     "package.json",
     "llms.txt",
+    ".cloudplugin/marketplace.json",
 ];
+const STAT_CHECKED_FILES = ["docs/landing/index.html"];
 export function countSkills(repoRoot) {
     const skillsDir = join(repoRoot, BUNDLE_SKILLS_DIR);
     const entries = readdirSync(skillsDir);
@@ -75,6 +82,24 @@ function checkFile(repoRoot, relPath, expected) {
         found: staleMatch ? staleMatch[0] : undefined,
     };
 }
+function checkStatFile(repoRoot, relPath, expected) {
+    let content;
+    try {
+        content = readFileSync(join(repoRoot, relPath), "utf8");
+    }
+    catch {
+        return { file: relPath, reason: "missing" };
+    }
+    const expectedPattern = new RegExp(`class="v">${expected}</span><span class="k">Bundled skills`);
+    if (expectedPattern.test(content))
+        return null;
+    const staleMatch = content.match(/class="v">(\d+)<\/span><span class="k">Bundled skills/);
+    return {
+        file: relPath,
+        reason: staleMatch ? "stale" : "missing",
+        found: staleMatch ? `${staleMatch[1]} Bundled skills (stat block)` : undefined,
+    };
+}
 function main() {
     const repoRoot = argv[2] ?? cwd();
     const expected = countSkills(repoRoot);
@@ -84,8 +109,14 @@ function main() {
         if (v)
             violations.push(v);
     }
+    for (const file of STAT_CHECKED_FILES) {
+        const v = checkStatFile(repoRoot, file, expected);
+        if (v)
+            violations.push(v);
+    }
+    const totalChecked = CHECKED_FILES.length + STAT_CHECKED_FILES.length;
     if (violations.length === 0) {
-        console.log(`OK skill-count: all ${CHECKED_FILES.length} description string(s) state "${expected} bundled skills" (matches skills/ source-of-truth).`);
+        console.log(`OK skill-count: all ${totalChecked} description string(s) state "${expected} bundled skills" (matches skills/ source-of-truth).`);
         exit(0);
     }
     console.error(`FAIL skill-count: ${violations.length} description string(s) do not state the actual bundled-skill count of ${expected}.`);

package/bin/check-test-imports-only.mjs

@@ -12,7 +12,7 @@
  *   - reach-through into `hooks/`, `scripts/`, `src/`, or deeper paths under
  *     `bin/` or `lib/`
  *
- * Baseline: all 50 `src/test/*.test.mts` files pass today.
+ * Baseline: all 56 `src/test/*.test.mts` files pass today.
  *
  * Usage:
  *   node bin/check-test-imports-only.mjs              # Check the current repo

package/bin/generate-plugin-manifests.mjs

@@ -107,7 +107,7 @@ async function writePluginBundleReadme() {
         "- `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`,",
+        "  `safety-guard`, `token-budget-advisor`,",
         "  `strategic-compact`, `wild-risa-balance`)",
         "",
         "**Optional companions the orchestrator routes to (install separately if",
@@ -152,6 +152,7 @@ async function writePluginBundle() {
         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", "hook-pack-gate.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "hook-pack-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")),

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 = {

package/bin/install.mjs

@@ -6,6 +6,7 @@
  *   npx continuous-improvement install                # beginner mode (default)
  *   npx continuous-improvement install --mode expert  # + MCP server + session hooks
  *   npx continuous-improvement install --pack react   # load starter instinct pack
+ *   npx continuous-improvement install --target gemini,codex  # skill into other agents' rules files
  *   npx continuous-improvement install --uninstall    # remove everything
  */
 import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
@@ -14,7 +15,9 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
-import { getToolNames } from "../lib/plugin-metadata.mjs";
+import { PACKAGE_NAME, VERSION, getToolNames } from "../lib/plugin-metadata.mjs";
+import { TARGET_IDS, planTargetWrites, resolveTargets } from "../lib/install-targets.mjs";
+import { evaluateUpdateCheck, fetchLatestNpmVersion, isThrottled, pendingNotice, } from "../lib/version-check.mjs";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const SKILL_SOURCE = join(__dirname, "..", "SKILL.md");
@@ -493,6 +496,17 @@ Options for 'install':
                       beginner  — hooks + skill + commands (default)
                       expert    — beginner + MCP server + session hooks
   --pack <name>     Load a starter instinct pack (react, python, go, meta)
+  --target <names>  Comma-separated platform list (default: claude):
+                      claude    — full install: hooks + skill + commands
+                      gemini    — GEMINI.md (Gemini CLI)
+                      codex     — AGENTS.md (Codex CLI / agents.md standard)
+                      cursor    — .cursor/rules/continuous-improvement.mdc
+                      windsurf  — .windsurf/rules/continuous-improvement.md
+                      zed       — .rules
+                      aider     — CONVENTIONS.md + .aider.conf.yml
+                      copilot   — .github/copilot-instructions.md
+                    Non-claude targets write the 7-Laws skill text into the
+                    current project; hooks/MCP/instincts stay Claude Code-only.
   --help            Show this help
 
 Options for 'backfill':
@@ -503,6 +517,7 @@ Examples:
   npx continuous-improvement install                # beginner (default)
   npx continuous-improvement install --mode expert  # full power
   npx continuous-improvement install --pack react   # load React instincts
+  npx continuous-improvement install --target gemini,codex  # other agents' rules files
   npx continuous-improvement backfill --dry-run     # report thin/rich row counts
   npx continuous-improvement backfill               # tag rows in place
   npx continuous-improvement install --uninstall    # remove everything
@@ -510,7 +525,12 @@ Examples:
 }
 function getProjectHashSync() {
     try {
-        const root = execSync("git rev-parse --show-toplevel 2>/dev/null", { encoding: "utf8" }).trim();
+        // No shell redirect — `2>/dev/null` breaks under cmd.exe (tries to open a
+        // file literally named /dev/null); ignore stderr via stdio instead.
+        const root = execSync("git rev-parse --show-toplevel", {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
         const hash = createHash("sha256").update(root).digest("hex").slice(0, 12);
         return { root, hash };
     }
@@ -547,6 +567,60 @@ if (args.includes("--uninstall")) {
     uninstallAll();
     process.exit(0);
 }
+// --target <names>: comma-separated platform list, default claude-only.
+// Non-claude targets receive the skill text in their platform's rules file
+// (project-level); the full hook/MCP/instinct install stays Claude Code-only.
+const targetFlagIndex = rawArgs.indexOf("--target");
+let requestedTargets = ["claude"];
+if (targetFlagIndex !== -1) {
+    const targetCsv = rawArgs[targetFlagIndex + 1];
+    if (!targetCsv || targetCsv.startsWith("--")) {
+        console.error(`--target requires a value. Valid targets: ${TARGET_IDS.join(", ")}`);
+        process.exit(1);
+    }
+    const resolved = resolveTargets(targetCsv);
+    if (resolved.unknown.length > 0) {
+        console.error(`Unknown --target name(s): ${resolved.unknown.join(", ")}. Valid targets: ${TARGET_IDS.join(", ")}`);
+        process.exit(1);
+    }
+    if (resolved.targets.length === 0) {
+        console.error(`--target requires at least one name. Valid targets: ${TARGET_IDS.join(", ")}`);
+        process.exit(1);
+    }
+    requestedTargets = resolved.targets;
+}
+function installNonClaudeTargets(targetIds) {
+    const skillMd = readFileSync(SKILL_SOURCE, "utf8");
+    const project = getProjectHashSync();
+    const projectRoot = project.root === "global" ? process.cwd() : project.root;
+    const readExisting = (relPath) => {
+        const absPath = join(projectRoot, relPath);
+        return existsSync(absPath) ? readFileSync(absPath, "utf8") : null;
+    };
+    const notes = new Set();
+    for (const targetId of targetIds) {
+        const plan = planTargetWrites(targetId, skillMd, readExisting);
+        for (const write of plan.writes) {
+            const absPath = join(projectRoot, write.relPath);
+            mkdirSync(dirname(absPath), { recursive: true });
+            writeFileSync(absPath, write.content);
+            console.log(`  ✓ ${targetId} → ${write.relPath}`);
+        }
+        for (const note of plan.notes)
+            notes.add(note);
+    }
+    for (const note of notes)
+        console.log(`  ℹ ${note}`);
+}
+const nonClaudeTargets = requestedTargets.filter((targetId) => targetId !== "claude");
+if (nonClaudeTargets.length > 0) {
+    console.log("\ncontinuous-improvement multi-platform install\n");
+    installNonClaudeTargets(nonClaudeTargets);
+    if (!requestedTargets.includes("claude")) {
+        console.log("\nDone. Claude Code install skipped (not in --target list).");
+        process.exit(0);
+    }
+}
 console.log(`
 continuous-improvement (mode: ${INSTALL_MODE})
 Research → Plan → Execute → Verify → Reflect → Learn → Iterate
@@ -621,3 +695,47 @@ Next steps:
 ${INSTALL_MODE === "expert" ? `\nMCP tools available (${getToolNames("expert").length}): ${getToolNames("expert").join(", ")}` : ""}
 Available instinct packs: npx continuous-improvement install --pack react|python|go|meta
 `);
+// Update-available nudge for the npm/CLI install path (the marketplace path is
+// covered by Claude Code's native plugin auto-update). Reads the public npm
+// registry only — no telemetry. Throttled, default-on, off via
+// CLAUDE_CI_UPDATE_CHECK=off. Fully fail-open: it can never change the
+// installer's outcome. See docs/plans/2026-06-25-version-check-nudge.md.
+async function maybeNotifyUpdate() {
+    if ((process.env.CLAUDE_CI_UPDATE_CHECK ?? "on").trim().toLowerCase() === "off")
+        return;
+    const cacheFile = join(getHomeDir(), ".claude", "instincts", "global", "update-check.json");
+    const now = Date.now();
+    let cache = null;
+    try {
+        if (existsSync(cacheFile))
+            cache = JSON.parse(readFileSync(cacheFile, "utf8"));
+    }
+    catch {
+        cache = null;
+    }
+    if (isThrottled(cache, now)) {
+        const notice = pendingNotice(cache, VERSION);
+        if (notice)
+            console.log(`\n${notice}`);
+        return;
+    }
+    const remote = await fetchLatestNpmVersion(PACKAGE_NAME);
+    const decision = evaluateUpdateCheck({ local: VERSION, remote, now });
+    if (decision.notice)
+        console.log(`\n${decision.notice}`);
+    if (decision.nextCache) {
+        try {
+            mkdirSync(dirname(cacheFile), { recursive: true });
+            writeFileSync(cacheFile, JSON.stringify(decision.nextCache) + "\n", "utf8");
+        }
+        catch {
+            // cache persistence is best-effort; never throw
+        }
+    }
+}
+try {
+    await maybeNotifyUpdate();
+}
+catch {
+    // a version check must never change the installer's outcome
+}

package/bin/lint-transcript.mjs

@@ -160,6 +160,12 @@ function formatReport(result) {
     return lines.join("\n");
 }
 const args = process.argv.slice(2);
+function actionInput(name) {
+    return (process.env[`INPUT_${name.toUpperCase()}`] ?? "").trim();
+}
+function actionInputBoolean(name) {
+    return /^(1|true|yes)$/i.test(actionInput(name));
+}
 if (args.includes("--help") || args.includes("-h")) {
     console.log(`
 Agent Transcript Linter — The 7 Laws of AI Agent Discipline
@@ -176,7 +182,7 @@ Options:
 `);
     process.exit(0);
 }
-const isStrict = args.includes("--strict");
+const isStrict = args.includes("--strict") || actionInputBoolean("strict");
 const isJson = args.includes("--json");
 const isStdin = args.includes("--stdin");
 async function main() {
@@ -190,7 +196,9 @@ async function main() {
         }
     }
     else {
-        const filePath = args.find((arg) => !arg.startsWith("--"));
+        const filePath = args.find((arg) => !arg.startsWith("--"))
+            || actionInput("transcript-path")
+            || actionInput("observations-path");
         if (!filePath) {
             console.error("Error: provide a file path or use --stdin");
             process.exit(1);
@@ -213,16 +221,20 @@ async function main() {
         process.exit(0);
     }
     const result = analyzeTranscript(events, parseFailures);
+    const report = formatReport(result);
     if (isJson) {
         console.log(JSON.stringify(result, null, 2));
     }
     else {
-        console.log(formatReport(result));
+        console.log(report);
     }
     if (process.env.GITHUB_OUTPUT) {
         const outputLines = [
             `violations=${result.violations.length}`,
             `score=${result.score}`,
+            `report<<CI_REPORT_EOF`,
+            report,
+            "CI_REPORT_EOF",
         ];
         const { appendFileSync } = await import("node:fs");
         for (const line of outputLines) {

package/bin/mcp-server.mjs

@@ -13,15 +13,15 @@
 import { execSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
 import { PACKAGE_NAME, VERSION, getToolDefinitions, isPluginMode, } from "../lib/plugin-metadata.mjs";
 import { formatDriftReport, parseGoalFromPlan, scoreObservations, } from "../lib/goal-state.mjs";
 import { buildIndex, formatRecallHits, parseSince, query as queryRecall, } from "../lib/recall-index.mjs";
-import { draftFromCandidate, extractTrajectories, findCandidates, formatCandidates, serializeDraft, } from "../lib/skill-distill.mjs";
-import { MAX_CLEARED_FILES, clearFiles, resolveSessionDir, } from "../lib/gateguard-state.mjs";
+import { draftFromCandidate, draftFromWorkflowRun, extractTrajectories, findCandidates, formatCandidates, serializeDraft, workflowRunFromObservations, } from "../lib/skill-distill.mjs";
+import { MAX_CLEARED_FILES, canonicalizeFileKey, clearFiles, resolveInstinctsRoot, resolveSessionDir, } from "../lib/gateguard-state.mjs";
 function getHomeDir() {
     return process.env.HOME || process.env.USERPROFILE || homedir();
 }
@@ -219,6 +219,7 @@ function readDistillObservations(projectHash) {
         tool: getString(observation.tool),
         input_summary: getString(observation.input_summary),
         output_summary: getString(observation.output_summary),
+        event: getString(observation.event),
     }));
 }
 function detectLevel(projectHash) {
@@ -508,10 +509,11 @@ function handleTool(name, params) {
         }
         case "ci_gateguard_clear": {
             // Beginner-available on purpose: the GateGuard hook fires for every
-            // install, so the clearance action must too. Resolves the session dir via
-            // gateguard-state (canonical), the same way the hook does, so the marker
-            // lands where the hook looks regardless of how each process spelled the
-            // project root.
+            // install, so the clearance action must too. The hook's block reason now
+            // prints state_path (the session-scoped state file); honoring it writes
+            // the marker exactly where the hook looks. Without it the MCP server can't
+            // know the caller's session, so it falls back to the canonical session dir
+            // — correct only on the legacy unscoped path.
             const rawList = Array.isArray(params.file_paths) ? params.file_paths : [];
             const listPaths = rawList.filter((value) => typeof value === "string" && value.length > 0);
             const single = getString(params.file_path).trim();
@@ -519,7 +521,24 @@ function handleTool(name, params) {
             if (paths.length === 0) {
                 return error("file_paths is required — pass the file path(s) named in the GateGuard block reason, e.g. { file_paths: [\"src/x.ts\"] }.");
             }
-            const sessionDir = resolveSessionDir();
+            // state_path is a model-controlled argument, so it could be a traversal
+            // string (`../../etc/...`). dirname leaves `..` segments for the OS to
+            // resolve at write time, so without a bound this is an arbitrary-write
+            // primitive. Resolve + canonicalize, then require containment within the
+            // instincts root (the only tree the hook ever prints a state_path inside).
+            const rawStatePath = getString(params.state_path).trim();
+            let sessionDir;
+            if (rawStatePath) {
+                const resolvedKey = canonicalizeFileKey(resolve(rawStatePath));
+                const rootKey = canonicalizeFileKey(resolveInstinctsRoot());
+                if (resolvedKey !== rootKey && !resolvedKey.startsWith(`${rootKey}/`)) {
+                    return error("state_path must resolve inside ~/.claude/instincts/. Pass it verbatim from the GateGuard block reason.");
+                }
+                sessionDir = dirname(resolve(rawStatePath));
+            }
+            else {
+                sessionDir = resolveSessionDir();
+            }
             const { cleared, skippedForCap } = clearFiles(sessionDir, paths);
             const lines = [
                 "## GateGuard clearance",
@@ -837,6 +856,45 @@ function handleTool(name, params) {
                 "```",
             ].join("\n"));
         }
+        case "ci_distill_from_workflow": {
+            if (MODE !== "expert") {
+                return error("ci_distill_from_workflow requires expert mode");
+            }
+            const run = workflowRunFromObservations(readDistillObservations(project.hash));
+            if (!run) {
+                return text("No completed-and-verified Workflow run found in this project's observations. " +
+                    "A run qualifies when a `Workflow` tool call is followed by a passing verify/test/build in the same feed. " +
+                    "Run a workflow, verify its output, then try `ci_distill_from_workflow` again.");
+            }
+            const draftInstinct = draftFromWorkflowRun(run);
+            if (!isSafeDraftId(draftInstinct.id)) {
+                return error(`Internal error: generated draft id "${draftInstinct.id}" failed the safety check.`);
+            }
+            const draft = serializeDraft(draftInstinct);
+            const draftsDir = join(INSTINCTS_DIR, project.hash, "drafts");
+            const draftPath = join(draftsDir, `${draftInstinct.id}.yaml`);
+            try {
+                mkdirSync(draftsDir, { recursive: true });
+                writeFileSync(draftPath, draft);
+            }
+            catch (err) {
+                return error(`Failed to write draft to ${draftPath}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            return text([
+                "## Draft written from a verified workflow run",
+                "",
+                `**Workflow:** ${run.name}`,
+                `**Path:** ${draftPath}`,
+                "",
+                "Edit the body to capture the real recipe (preconditions, concrete steps, gotchas), then promote with:",
+                "",
+                `  ci_distill_promote id=${draftInstinct.id}`,
+                "",
+                "```yaml",
+                draft.trimEnd(),
+                "```",
+            ].join("\n"));
+        }
         case "ci_distill_promote": {
             if (MODE !== "expert") {
                 return error("ci_distill_promote requires expert mode");