continuous-improvement 3.15.0 → 3.16.0

package/.claude-plugin/marketplace.json

@@ -7,8 +7,8 @@
   "plugins": [
     {
       "name": "continuous-improvement",
-      "description": "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 25 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
-      "version": "3.15.0",
+      "description": "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 26 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
+      "version": "3.16.0",
       "source": "./plugins/continuous-improvement",
       "author": {
         "name": "naimkatiman"

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this skill are documented here.
 
 ---
 
+## [3.16.0] — 2026-06-27
+
+### Added
+
+- **`/roast` — a 5-persona adversarial idea council that pressure-tests a plan before any code is written** — routes a proposed idea or plan through five distinct critic personas (each attacking a different failure axis) and reconciles their objections into a go / revise / kill verdict. Catches misalignment at Law 1 (Research) before it lands in the diff. Brings the bundle to 26 skills. (#255, #256)
+- **npm-install users get nudged when a newer version is published** — the installer compares the running version against the registry `latest` and surfaces an upgrade hint instead of silently running stale. (#252)
+- **Hook nudge to distill a verified Workflow run into a reusable instinct** — a completed multi-agent Workflow's verified trajectory no longer evaporates with the session; the agent is prompted to capture it as a draft instinct. (#251)
+- **`lint-transcript` GitHub Action IO + fleet docs** — the transcript linter ships defined Action inputs/outputs for CI wiring, with fleet-usage documentation. (#250)
+- **Skill use-case decision guide** — a when-to-reach-for-each-skill map so the right skill is picked without scanning all of them. (#254)
+
+### Changed
+
+- **`skill-count` prose is now gated against the actual bundle** — the verify suite fails if any doc claims a skill count that disagrees with the shipped skill set; synced all prose to 26 after `/roast`. (#256)
+
 ## [3.15.0] — 2026-06-21
 
 ### Added

package/README.md

@@ -82,7 +82,7 @@ You have used Claude Code (or any agentic coding tool) long enough to recognize
 
 | # | Failure mode | What you see | Which Law fires | What enforces it |
 |---|---|---|---|---|
-| 1 | **Misalignment** | The agent doesn't do what you want — invents requirements, reinvents helpers that already exist | Law 1 (Research) | [`grill-me`](skills/grill-me.md), [`grill-with-docs`](skills/grill-with-docs.md), [`gateguard`](skills/gateguard.md), [`workspace-surface-audit`](skills/workspace-surface-audit.md) |
+| 1 | **Misalignment** | The agent doesn't do what you want — invents requirements, reinvents helpers that already exist, or builds the wrong thing before anyone challenged the idea | Law 1 (Research) | [`roast`](skills/roast.md), [`grill-me`](skills/grill-me.md), [`grill-with-docs`](skills/grill-with-docs.md), [`gateguard`](skills/gateguard.md), [`workspace-surface-audit`](skills/workspace-surface-audit.md) |
 | 2 | **No shared language** | The agent uses 20 words where 1 would do; jargon decoded fresh every session; variable names drift from domain terms | Law 2 (Plan), Law 7 (Learn) | [`grill-with-docs`](skills/grill-with-docs.md) (writes & maintains `CONTEXT.md`), [`token-budget-advisor`](skills/token-budget-advisor.md), [`strategic-compact`](skills/strategic-compact.md) |
 | 3 | **No feedback loop** | The code doesn't work — agent claims "done" without running build, tests, or healthcheck | Law 4 (Verify) | [`tdd-workflow`](skills/tdd-workflow.md), [`verification-loop`](skills/verification-loop.md), [`deploy-receipt`](skills/deploy-receipt.md) |
 | 4 | **Design rot** | Ball-of-mud accelerates — agent bundles three concerns into one PR, stacks untested changes, ignores prior architectural decisions | Law 2 (Plan), Law 3 (One Thing) | [`superpowers:writing-plans`](https://github.com/obra/superpowers/blob/main/skills/writing-plans/SKILL.md), [`safety-guard`](skills/safety-guard.md), [`worktree-safety`](skills/worktree-safety.md), [`wild-risa-balance`](skills/wild-risa-balance.md) |
@@ -149,7 +149,7 @@ npx continuous-improvement install --pack react   # optional: react | python | g
 ```
 
 Verify: run `/dashboard` in Claude Code — you should see instinct health and observation count.
-Update later with `/plugin marketplace update continuous-improvement` or by re-running the npx command.
+Update later with `/plugin marketplace update continuous-improvement` or by re-running the npx command. When you run the npx installer, it makes one throttled, fail-open read of the public npm registry and prints a one-line notice if a newer version is published (no telemetry — nothing about you is sent). Silence it with `CLAUDE_CI_UPDATE_CHECK=off`.
 
 ### Troubleshooting install
 
@@ -172,6 +172,7 @@ The framework has documented operator-level modes that change hook behavior with
 | `CLAUDE_THREE_SECTION_CLOSE_DISABLED=1` | `three-section-close.mjs` short-circuits before any enforcement or telemetry. Use when end-of-turn reflection should run as internal thinking rather than visible "What has been done / What is next / Recommendation" sections. Public default unchanged — the rule still fires for everyone else. | bash/zsh: `export CLAUDE_THREE_SECTION_CLOSE_DISABLED=1` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CLAUDE_THREE_SECTION_CLOSE_DISABLED=1` (session) or `[Environment]::SetEnvironmentVariable('CLAUDE_THREE_SECTION_CLOSE_DISABLED','1','User')` (persistent). |
 | `CLAUDE_GOAL_DRIFT_GATE` | `goal-drift-stop.mjs` (a `Stop` hook) scores each turn's activity against the `## Goal` in `task_plan.md` and acts on drift. `warn` (default) prints a one-line stderr notice and never blocks; `block` re-prompts a substantive wrap-up that has drifted off-goal so the goal gates the close; `off` disables it. Reads the same observation feed as Mulahazah; fails open on any error. | bash/zsh: `export CLAUDE_GOAL_DRIFT_GATE=block` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CLAUDE_GOAL_DRIFT_GATE='block'` (session) or `[Environment]::SetEnvironmentVariable('CLAUDE_GOAL_DRIFT_GATE','block','User')` (persistent). |
 | `CLAUDE_RECALL_BRIEFING=1` | `hooks/recall-briefing.mjs` (a UserPromptSubmit hook) makes episodic memory proactive: on the first substantive prompt of a session it searches this project's past observations (BM25) and injects a one-time `<system-reminder>` with the most relevant prior activity, so the agent reuses a past fix instead of re-deriving it. Opt-in and default off; it is an amplifier, never a gate — it cannot block a prompt and fails open. The `ci_recall` MCP tool stays available for explicit, deeper searches. | bash/zsh: `export CLAUDE_RECALL_BRIEFING=1` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CLAUDE_RECALL_BRIEFING=1` (session) or `[Environment]::SetEnvironmentVariable('CLAUDE_RECALL_BRIEFING','1','User')` (persistent). |
+| `CLAUDE_WORKFLOW_DISTILL_NUDGE=on` | `hooks/workflow-distill.mjs` (a `Stop` hook) closes the orchestration-to-memory loop: when a native Workflow run's output then passed a verify in the same session, it prints a one-line stderr nudge to run the `ci_distill_from_workflow` MCP tool, so an expensive multi-agent run leaves a durable Mulahazah draft instinct instead of evaporating. `on` enables it; default (unset or any other value) is off. Opt-in amplifier, never a gate — it cannot block the Stop, dedupes per run, and fails open. | bash/zsh: `export CLAUDE_WORKFLOW_DISTILL_NUDGE=on` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CLAUDE_WORKFLOW_DISTILL_NUDGE='on'` (session) or `[Environment]::SetEnvironmentVariable('CLAUDE_WORKFLOW_DISTILL_NUDGE','on','User')` (persistent). |
 
 ### Works with other agents
 
@@ -260,7 +261,7 @@ All 18 ship in the marketplace bundle. The Beginner install gets all of them —
 
 ## Skills
 
-The plugin ships **25 skills** — 1 core + 1 featured + 6 tier-1 + 14 tier-2 + 3 always-bundled. Beginner install gets tier-1, featured, and the always-bundled companion; Expert adds tier-2, the MCP server, and observation hooks. Full catalog with per-skill descriptions, Law tagging, and drop-in single-file install: [docs/skills.md](docs/skills.md). Adding a 26th skill: [CONTRIBUTING.md § Evolution — adding a new skill](CONTRIBUTING.md#evolution--adding-a-new-skill).
+The plugin ships **26 skills** — 1 core + 1 featured + 6 tier-1 + 15 tier-2 + 3 always-bundled. Beginner install gets tier-1, featured, and the always-bundled companion; Expert adds tier-2, the MCP server, and observation hooks. Full catalog with per-skill descriptions, Law tagging, and drop-in single-file install: [docs/skills.md](docs/skills.md). Adding a 27th skill: [CONTRIBUTING.md § Evolution — adding a new skill](CONTRIBUTING.md#evolution--adding-a-new-skill).
 
 ---
 

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/install.mjs

@@ -15,8 +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");
@@ -694,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

@@ -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) {

package/commands/roast.md

@@ -0,0 +1,34 @@
+---
+name: roast
+description: "Convene a 5-persona adversarial council (Contrarian, Expansionist, Logician, Researcher, Buyer) to pressure-test an idea, then deliver one GO / RESHAPE / KILL verdict plus the cheapest 48-hour test to de-risk it. Enforces Law 1 (Research Before Executing)."
+argument-hint: "[the idea to roast]"
+---
+
+# /roast
+
+Pressure-test an idea before you build it. Convene a council of five independent persona agents who attack the idea from every angle, then act as the Judge and return one decisive verdict — so Law 1 (Research Before Executing) is satisfied on the *idea* itself, not just the plan.
+
+## Trigger phrases
+
+- `/roast`
+- `/roast <the idea>`
+- "roast this idea"
+- "convene the council"
+- "pressure-test this" / "stress-test this idea"
+- "validate this business idea"
+- "give me a brutal second opinion before I build this"
+
+## What happens
+
+1. **Brief.** Read the idea from the argument (if given) and ask up to 3-4 clarifying questions in one batch — the idea, the buyer + money model, your edge, your constraints. Skip the questions if the user says "just run it."
+2. **Council (parallel).** Spin up all five personas in parallel, each pasted the same brief: Contrarian (assume it fails), Expansionist (the 10x case), Logician (first-principles, no web), Researcher (web evidence + competitors), Buyer (role-play the target customer). Each returns a stance, 3-5 sharp points, the one thing you must hear, and a 1-10 score.
+3. **Verdict.** Act as the Judge: resolve the council's tension, fold in the economics lens, and return one `GO / RESHAPE / KILL` call with the biggest risk, biggest upside, money read, and — most importantly — the cheapest 48-hour test to validate the riskiest assumption before building anything.
+
+## Skill file
+
+Full behavior is defined in [`skills/roast.md`](../skills/roast.md).
+
+## Pairs with
+
+- `/grill-me` — roast validates the idea; grill-me then hardens the plan.
+- `/proceed-with-the-recommendation` — walk the verdict's next steps under the 7 Laws.

package/hooks/workflow-distill.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// workflow-distill.mts — Stop hook (opt-in, default off) that nudges the operator
+// to persist a verified native Workflow run as a Mulahazah draft instinct via the
+// ci_distill_from_workflow MCP tool. This is the one integration a per-turn
+// orchestration primitive cannot do for itself: make the lesson of an expensive
+// multi-agent run survive the run instead of evaporating when the turn ends — the
+// fast-follow deferred in docs/plans/2026-06-08-workflow-instinct-bridge.md.
+//
+// Mode via CLAUDE_WORKFLOW_DISTILL_NUDGE: "on" | "off" (default).
+//   - off (default): no-op. Operators who do not use native Workflows are never
+//     nagged.
+//   - on: if the session's observation feed shows a verified Workflow run that
+//     has not already been nudged, print ONE stderr line suggesting
+//     ci_distill_from_workflow. It is an amplifier, never a gate — it cannot
+//     block the Stop and writes nothing to stdout.
+//
+// Project-hash resolution is byte-identical to bin/observe.mts and
+// hooks/goal-drift-stop.mts so this hook reads the SAME observations.jsonl the
+// observer writes. The "is this run verified" decision is the pure, already-tested
+// workflowRunFromObservations (src/lib/skill-distill.mts), which fails closed:
+// no Workflow row, unparseable meta, or no following verify-exit-0 => null => no
+// nudge. Per-run dedup state lives in
+// ~/.claude/instincts/<project-hash>/workflow-distill-state.json keyed by run
+// name + verify command, so a run is nudged at most once. Fail-open by
+// construction: any error exits 0 and never blocks. No network. 5s hook budget.
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveHomeDir } from "../lib/resolve-home-dir.mjs";
+import { workflowRunFromObservations } from "../lib/skill-distill.mjs";
+function safeJsonParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function resolveMode() {
+    return (process.env.CLAUDE_WORKFLOW_DISTILL_NUDGE ?? "off").trim().toLowerCase() === "on" ? "on" : "off";
+}
+// Mirrors bin/observe.mts:resolveProjectRoot — the same basis the observer uses
+// to bucket observations.jsonl, so the hash here resolves to the same file.
+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 a git repo
+    }
+    return "global";
+}
+function projectHash(root) {
+    return createHash("sha256").update(root).digest("hex").slice(0, 12);
+}
+function readObservations(instinctsProjectDir) {
+    const file = join(instinctsProjectDir, "observations.jsonl");
+    try {
+        if (!existsSync(file))
+            return [];
+        const lines = readFileSync(file, "utf8")
+            .split("\n")
+            .filter((line) => line.trim().length > 0);
+        const out = [];
+        // A workflow row plus its following verify both sit near the tail; a bounded
+        // window keeps the 5s budget safe on a long-lived feed.
+        for (const line of lines.slice(-5000)) {
+            const row = safeJsonParse(line);
+            if (!row)
+                continue;
+            out.push({
+                ts: typeof row.ts === "string" ? row.ts : "",
+                session: typeof row.session === "string" ? row.session : "",
+                session_id: typeof row.session_id === "string" ? row.session_id : "",
+                tool: typeof row.tool === "string" ? row.tool : "",
+                input_summary: typeof row.input_summary === "string" ? row.input_summary : "",
+                output_summary: typeof row.output_summary === "string" ? row.output_summary : "",
+            });
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+function readNudgedKeys(instinctsProjectDir) {
+    const file = join(instinctsProjectDir, "workflow-distill-state.json");
+    try {
+        if (!existsSync(file))
+            return new Set();
+        const parsed = safeJsonParse(readFileSync(file, "utf8"));
+        const arr = parsed && Array.isArray(parsed.nudged) ? parsed.nudged : [];
+        return new Set(arr.filter((x) => typeof x === "string"));
+    }
+    catch {
+        return new Set();
+    }
+}
+function persistNudged(instinctsProjectDir, keys) {
+    try {
+        mkdirSync(instinctsProjectDir, { recursive: true });
+        writeFileSync(join(instinctsProjectDir, "workflow-distill-state.json"), JSON.stringify({ ts: new Date().toISOString(), nudged: [...keys] }) + "\n", "utf8");
+    }
+    catch {
+        // dedup persistence is best-effort; never throw
+    }
+}
+function main() {
+    if (resolveMode() === "off")
+        return;
+    const home = resolveHomeDir();
+    if (!home)
+        return;
+    const projectRoot = resolveProjectRoot();
+    const instinctsProjectDir = join(home, ".claude", "instincts", projectHash(projectRoot));
+    const observations = readObservations(instinctsProjectDir);
+    if (observations.length === 0)
+        return;
+    const run = workflowRunFromObservations(observations);
+    if (!run)
+        return; // fail closed: no verified run, nothing to nudge
+    const runKey = `${run.name}::${run.verifyCommand}`;
+    const nudged = readNudgedKeys(instinctsProjectDir);
+    if (nudged.has(runKey))
+        return; // already nudged this run — stay quiet
+    process.stderr.write(`[continuous-improvement] workflow-distill: verified workflow run "${run.name}" detected — ` +
+        "run the ci_distill_from_workflow MCP tool to persist it as a Mulahazah draft instinct.\n");
+    nudged.add(runKey);
+    persistNudged(instinctsProjectDir, nudged);
+}
+try {
+    main();
+}
+catch {
+    // fail open — never block the session due to a hook bug
+}

package/lib/plugin-metadata.mjs

@@ -26,7 +26,7 @@ const KEYWORDS = [
     "transcript-linter",
 ];
 const CLAUDE_PLUGIN_CATEGORY = "productivity";
-const SHARED_PLUGIN_DESCRIPTION = "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 25 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.";
+const SHARED_PLUGIN_DESCRIPTION = "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 26 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.";
 // Four vendored upstream companions registered alongside the CI plugin.
 // Each entry points at a pinned-SHA snapshot under third-party/<name>/.
 // See third-party/MANIFEST.md for refresh recipes and per-snapshot
@@ -492,6 +492,11 @@ export function getPluginHooksConfig() {
         command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/goal-drift-stop.mjs\"",
         timeout: 5,
     };
+    const workflowDistillCommand = {
+        type: "command",
+        command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/workflow-distill.mjs\"",
+        timeout: 5,
+    };
     const routePromptCommand = {
         type: "command",
         command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/route-prompt.mjs\"",
@@ -503,7 +508,7 @@ export function getPluginHooksConfig() {
         timeout: 5,
     };
     return {
-        description: "Gateguard fact-forcing PreToolUse, companion-preference enforcement, observation, session lifecycle, 3-section-close discipline, goal-drift Stop gate, and UserPromptSubmit lazy-routing plus opt-in proactive recall-briefing hooks for continuous-improvement.",
+        description: "Gateguard fact-forcing PreToolUse, companion-preference enforcement, observation, session lifecycle, 3-section-close discipline, goal-drift Stop gate, opt-in workflow-distill Stop nudge, and UserPromptSubmit lazy-routing plus opt-in proactive recall-briefing hooks for continuous-improvement.",
         hooks: {
             // gateguard runs FIRST on PreToolUse so its block decision short-circuits
             // before companion-preference sees the call. companion-preference runs
@@ -527,7 +532,7 @@ export function getPluginHooksConfig() {
             UserPromptSubmit: [{ hooks: [routePromptCommand, recallBriefingCommand] }],
             SessionStart: [{ hooks: [sessionCommand] }],
             SessionEnd: [{ hooks: [sessionCommand] }],
-            Stop: [{ hooks: [threeSectionCloseCommand, goalDriftStopCommand] }],
+            Stop: [{ hooks: [threeSectionCloseCommand, goalDriftStopCommand, workflowDistillCommand] }],
         },
     };
 }