continuous-improvement 3.16.0 → 3.18.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 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",
+      "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 27 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.18.0",
       "source": "./plugins/continuous-improvement",
       "author": {
         "name": "naimkatiman"

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this skill are documented here.
 
 ---
 
+## [3.17.0] — 2026-06-28
+
+### Added
+
+- **`/intent-driven-development`**: turn an ambiguous or high-impact change into verifiable acceptance criteria before you build. Converts a fuzzy request into observable `AC-NNN` criteria with named verification methods and a `[revised]` protocol that forbids silently dropping a criterion mid-build, so "done" is falsifiable and the agreed plan is held sacred (Law 2). Tier 2 (expert install). Brings the bundle to 27 skills. (#258)
+
 ## [3.16.0] — 2026-06-27
 
 ### Added

package/README.md

@@ -1,4 +1,4 @@
-<!-- README landing-page structure rationale: docs/plans/2026-05-14-readme-landing-rewrite.md -->
+<!-- README landing-page structure rationale: docs/plans/2026-06-28-readme-progressive-disclosure.md (supersedes docs/plans/2026-05-14-readme-landing-rewrite.md) -->
 
 <p align="center">
   <img src="assets/combined.gif" alt="Before vs After — The 7 Laws of AI Agent Discipline" width="700" />
@@ -15,17 +15,30 @@
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/continuous-improvement"><img src="https://img.shields.io/npm/v/continuous-improvement" alt="npm"></a>
+  <a href="https://www.npmjs.com/package/continuous-improvement"><img src="https://img.shields.io/npm/v/continuous-improvement" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/continuous-improvement"><img src="https://img.shields.io/npm/dm/continuous-improvement" alt="npm downloads"></a>
   <a href="https://docs.anthropic.com/en/docs/claude-code"><img src="https://img.shields.io/badge/Claude%20Code-skill-blueviolet" alt="Claude Code"></a>
   <a href="https://github.com/marketplace/actions/ai-agent-discipline-linter"><img src="https://img.shields.io/badge/GitHub%20Action-marketplace-blue" alt="GitHub Action"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license"></a>
-  <a href="test/"><img src="https://img.shields.io/badge/tests-passing-brightgreen" alt="tests"></a>
 </p>
 
 <p align="center">
   <b>New here?</b> → <a href="QUICKSTART.md">QUICKSTART.md</a> (2 minutes) · <a href="https://continuous-improvement.dev">continuous-improvement.dev</a>
 </p>
 
+## Quick start
+
+Inside Claude Code — two commands, no Node, no bash:
+
+```bash
+/plugin marketplace add naimkatiman/continuous-improvement
+/plugin install continuous-improvement@continuous-improvement
+```
+
+**If you don't know which to pick, use Beginner.** That is the install above — enough for ~90% of users. Want the MCP server, observation hooks, and instinct packs too? See [Expert install](#install) below.
+
+Verify it is live: run `/discipline` in Claude Code and you should see the 7 Laws card. (Commands load on session start — if it is not recognized, restart Claude Code once.)
+
 > **What this is *not*:** a prompt template, a `CLAUDE.md`, or a vibes-based reminder. It is a runtime hook (`hooks/gateguard.mjs`) plus a bundled skill set that makes the agent ground every change in real facts — it physically blocks `Edit` / `Write` / destructive `Bash` until the investigation is done, so edits land on understanding instead of guesses.
 
 ---
@@ -38,11 +51,13 @@ Claude Code is powerful but leaves intelligence on the table: it edits before re
 2. **During work** — bundled skills enforce planning, one-thing-at-a-time execution, TDD ([`tdd-workflow`](skills/tdd-workflow.md)), and a six-phase verification ladder ([`verification-loop`](skills/verification-loop.md)) before "done".
 3. **After work** — `/seven-laws` reflection plus the Mulahazah instinct engine capture lessons, and the opt-in [`recall-briefing`](hooks/recall-briefing.mjs) hook resurfaces the most relevant past fix on the next related prompt, so the same mistake does not repeat next session.
 
-Beginner install is two slash commands inside Claude Code (no Node, no bash). Expert install adds MCP tools, observation hooks, instinct packs, and a GitHub Action transcript linter for CI.
-
 ---
 
-## Before and after
+## See it in action
+
+<p align="center">
+  <img src="assets/gateguard-demo.png" alt="gateguard blocks an unresearched Edit until the investigation is on the table" width="820" />
+</p>
 
 Without Continuous Improvement, "fix the login redirect bug" looks like this:
 
@@ -56,59 +71,38 @@ Same agent. Same model. Different intelligence.
 
 ---
 
-## Who this is for
-
-Use this if you:
-
-- ship from real repositories with real consequences
-- have been bitten by an agent that edits before understanding
-- want tests, builds, or healthchecks to pass before "done"
-- want lessons from yesterday to survive into today
-
-Skip it if you:
-
-- only do one-off prompts (no edits, no commits)
-- do not use Claude Code
-- dislike *any* friction before agent edits
-- want a prompt template, not a runtime gate
-
-(The runtime gate is `hooks/gateguard.mjs`; full mechanics in [How enforcement works](#how-enforcement-works) below.)
-
----
+## The 7 Laws
 
-## The problem this solves
+| # | Law | What it gives the agent |
+|---|-----|----------------------|
+| 1 | **Research Before Executing** | builds on what already exists instead of reinventing it |
+| 2 | **Plan Is Sacred** | lands effort on the goal with success defined up front |
+| 3 | **One Thing at a Time** | ships each change on a known-good base |
+| 4 | **Verify Before Reporting** | backs every "done" with evidence you can trust |
+| 5 | **Reflect After Sessions** | turns each session into a captured lesson |
+| 6 | **Iterate One Change** | keeps debugging isolated and the signal clean |
+| 7 | **Learn From Every Session** | compounds knowledge so next week's agent is sharper |
 
-You have used Claude Code (or any agentic coding tool) long enough to recognize the failure pattern. Matt Pocock's [Skills For Real Engineers](https://github.com/mattpocock/skills) names four root failure modes that account for nearly every "the agent didn't help" complaint; the 7 Laws of AI Agent Discipline catch those four at the tool-call boundary plus a fifth that only shows up across sessions.
+```
+Research -> Plan -> Execute (one thing) -> Verify -> Reflect -> Learn -> Iterate
+```
 
-| # | 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, 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) |
-| 5 | **Forgotten lessons** | Next session starts from zero — prior corrections, decisions, instincts are lost; the same mistake repeats next week | Law 5 (Reflect), Law 7 (Learn) | [`handoff`](skills/handoff.md), Mulahazah instinct engine |
+<p align="center">
+  <img src="assets/diagram-7-laws-loop.jpg" alt="The 7 Laws of AI Agent Discipline — circular workflow loop" width="820" />
+</p>
 
-Three of those alignment + reflection skills (`grill-me`, `grill-with-docs`, `handoff`) are MIT-licensed ports from mattpocock/skills; the rest are continuous-improvement-native. Every failure mode has at least one runtime hook or model-side skill that catches it before it lands in the diff.
+Full spec, reflection-block format, and anti-examples: [SKILL.md](SKILL.md). Full Law-to-tool alignment matrix: [CONTRIBUTING.md § Law Coverage Matrix](CONTRIBUTING.md#law-coverage-matrix).
 
 ---
 
 ## Install
 
-**If you don't know which to pick, use Beginner.** It is enough for ~90% of users and adds no Node or bash dependency.
+**Beginner (recommended)** is the two-command [Quick start](#quick-start) above — the 7 Laws skill, the hooks that enforce it, and the slash commands. Nothing else to install.
 
-### Beginner — inside Claude Code, two commands (plus one optional companion)
+<details>
+<summary><b>Optional companion — the <code>/superpowers</code> dispatcher (recommended)</b></summary>
 
-You get the 7 Laws skill, the hooks that enforce it, and the slash commands. Nothing else to install.
-
-```bash
-# Inside Claude Code (no shell needed)
-/plugin marketplace add naimkatiman/continuous-improvement
-/plugin install continuous-improvement@continuous-improvement
-```
-
-The doubled name is correct: it reads as `<plugin>@<marketplace>`.
-
-**Optional companion (recommended).** The `/superpowers` dispatcher routes per-task to specialist skills (`writing-plans`, `test-driven-development`, `using-git-worktrees`, `dispatching-parallel-agents`, `finishing-a-development-branch`, etc.) shipped by Obra's `superpowers` plugin, which is vendored into this same marketplace as a pinned-SHA snapshot. Install it with one extra line:
+The `/superpowers` dispatcher routes per-task to specialist skills (`writing-plans`, `test-driven-development`, `using-git-worktrees`, `dispatching-parallel-agents`, `finishing-a-development-branch`, etc.) shipped by Obra's `superpowers` plugin, which is vendored into this same marketplace as a pinned-SHA snapshot. Install it with one extra line:
 
 ```bash
 /plugin install superpowers@continuous-improvement
@@ -116,9 +110,6 @@ The doubled name is correct: it reads as `<plugin>@<marketplace>`.
 
 Without the companion the dispatcher still works — every routing target has a concrete inline fallback — but specialist quality is fallback-quality, not dedicated-skill-quality.
 
-Verify: run `/discipline` in Claude Code — you should see the 7 Laws card.
-If the command is not recognized, restart your Claude Code session first; the marketplace did pick the plugin up but commands load on session start.
-
 **Second-stage verify (proves the runtime gate is firing — i.e. `hooks/gateguard.mjs` is invoked — not just docs claiming it).** Ask Claude to write a throwaway file with no research first:
 
 ```
@@ -127,7 +118,10 @@ Edit a new file scratch.txt and put the word "hello" in it. Don't research anyth
 
 You should see Claude **blocked** by the bundled `gateguard` PreToolUse hook (`hooks/gateguard.mjs`) with a fact-list reason. That block is the proof the hook is wired and enforcing. If Claude writes the file with no pause, the hook did not load — see Troubleshooting below. (To also verify observation hooks, run `/dashboard` and confirm a non-zero `Total` under `Observations`.)
 
-### How enforcement works
+</details>
+
+<details>
+<summary><b>How enforcement works (two layers: runtime hooks + model-side skills)</b></summary>
 
 The 7 Laws are enforced at **two layers**:
 
@@ -136,7 +130,10 @@ The 7 Laws are enforced at **two layers**:
 
 V1 honest limitations: the runtime gate is honor-system once the agent flips `_gateguard_facts_presented: true` (the hook can't verify the investigation actually happened); the state file is deletable and parallel hook invocations can race. Documented in `src/hooks/gateguard.mts` and `src/lib/gateguard-state.mts` headers.
 
-### Expert — adds MCP server, observation hooks, and instinct packs
+</details>
+
+<details>
+<summary><b>Expert install — MCP server, observation hooks, and instinct packs</b></summary>
 
 Pick this if you want the MCP tools (19 of them, including `ci_plan_init` / `ci_plan_status` for `task_plan.md`-style planning), the session hooks that feed Mulahazah, and starter packs.
 
@@ -151,7 +148,10 @@ 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. 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
+</details>
+
+<details>
+<summary><b>Troubleshooting install</b></summary>
 
 Three failures account for nearly every install support thread. Try them in order:
 
@@ -163,7 +163,10 @@ Three failures account for nearly every install support thread. Try them in orde
 
 If none of those apply, paste the output of `npx continuous-improvement install` into a GitHub issue — that surface logs every step.
 
-### Operator modes
+</details>
+
+<details>
+<summary><b>Operator modes (env vars that change hook behavior)</b></summary>
 
 The framework has documented operator-level modes that change hook behavior without rebuilding the plugin. These are first-class — set them once in your shell rc and they persist across sessions.
 
@@ -174,7 +177,10 @@ The framework has documented operator-level modes that change hook behavior with
 | `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
+</details>
+
+<details>
+<summary><b>Works with other agents (Gemini, Codex, Cursor, Windsurf, Zed, Aider, Copilot)</b></summary>
 
 Claude Code gets the full install (hooks, MCP server, instinct learning). Every other agent platform can still run the 7 Laws as a rules file — one flag writes the skill text into the file that platform reads, at your project root:
 
@@ -194,43 +200,75 @@ npx continuous-improvement install --target gemini,codex
 
 Shared files (`GEMINI.md`, `AGENTS.md`, `.rules`, `CONVENTIONS.md`, `copilot-instructions.md`) are merged through a managed marker block — your existing content is preserved and reinstalls are idempotent. Targets can be combined freely (`--target claude,gemini,codex` runs the full Claude Code install plus the rules files).
 
+</details>
+
 ---
 
-## The 7 Laws
+## Who this is for
 
-| # | Law | What it gives the agent |
-|---|-----|----------------------|
-| 1 | **Research Before Executing** | builds on what already exists instead of reinventing it |
-| 2 | **Plan Is Sacred** | lands effort on the goal with success defined up front |
-| 3 | **One Thing at a Time** | ships each change on a known-good base |
-| 4 | **Verify Before Reporting** | backs every "done" with evidence you can trust |
-| 5 | **Reflect After Sessions** | turns each session into a captured lesson |
-| 6 | **Iterate One Change** | keeps debugging isolated and the signal clean |
-| 7 | **Learn From Every Session** | compounds knowledge so next week's agent is sharper |
+<details>
+<summary><b>Use it if you ship from real repos — skip it if you only do one-off prompts</b></summary>
 
-```
-Research -> Plan -> Execute (one thing) -> Verify -> Reflect -> Learn -> Iterate
-```
+Use this if you:
 
-<p align="center">
-  <img src="assets/diagram-7-laws-loop.jpg" alt="The 7 Laws of AI Agent Discipline — circular workflow loop" width="820" />
-</p>
+- ship from real repositories with real consequences
+- have been bitten by an agent that edits before understanding
+- want tests, builds, or healthchecks to pass before "done"
+- want lessons from yesterday to survive into today
 
-Full spec, reflection-block format, and anti-examples: [SKILL.md](SKILL.md). Full Law-to-tool alignment matrix: [CONTRIBUTING.md § Law Coverage Matrix](CONTRIBUTING.md#law-coverage-matrix).
+Skip it if you:
+
+- only do one-off prompts (no edits, no commits)
+- do not use Claude Code
+- dislike *any* friction before agent edits
+- want a prompt template, not a runtime gate
+
+(The runtime gate is `hooks/gateguard.mjs`; full mechanics in [How enforcement works](#install) above.)
+
+</details>
+
+---
+
+## The problem this solves
+
+<details>
+<summary><b>Five failure modes every agentic-coding user hits — and which Law catches each</b></summary>
+
+You have used Claude Code (or any agentic coding tool) long enough to recognize the failure pattern. Matt Pocock's [Skills For Real Engineers](https://github.com/mattpocock/skills) names four root failure modes that account for nearly every "the agent didn't help" complaint; the 7 Laws of AI Agent Discipline catch those four at the tool-call boundary plus a fifth that only shows up across sessions.
+
+| # | 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, 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) |
+| 5 | **Forgotten lessons** | Next session starts from zero — prior corrections, decisions, instincts are lost; the same mistake repeats next week | Law 5 (Reflect), Law 7 (Learn) | [`handoff`](skills/handoff.md), Mulahazah instinct engine |
+
+Three of those alignment + reflection skills (`grill-me`, `grill-with-docs`, `handoff`) are MIT-licensed ports from mattpocock/skills; the rest are continuous-improvement-native. Every failure mode has at least one runtime hook or model-side skill that catches it before it lands in the diff.
+
+</details>
 
 ---
 
 ## Mulahazah: auto-leveling learning
 
+<details>
+<summary><b>How instincts form, level up, and decay — you configure nothing</b></summary>
+
 Hooks capture every tool call. After ~20 observations Claude analyzes patterns and creates **instincts** with confidence scores: silent below 0.5, suggested at 0.5–0.69, auto-applied at 0.7+. Corrections drop confidence by 0.1; unused instincts decay. Project-scoped; promoted to global after seen across 2+ projects. You configure nothing.
 
 <p align="center">
   <img src="assets/diagram-mulahazah-learning.jpg" alt="Mulahazah pipeline" width="820" />
 </p>
 
+</details>
+
 ---
 
-## Slash Commands
+## Slash commands
+
+<details>
+<summary><b>All 28 commands (Beginner gets every one)</b></summary>
 
 `/seven-laws` is the canonical reflect-and-learn command. `/continuous-improvement` is kept as an alias for backward compatibility — both run the same workflow.
 
@@ -240,28 +278,40 @@ Hooks capture every tool call. After ~20 observations Claude analyzes patterns a
 /proceed-with-the-recommendation  Walk any agent's recommendation list top-to-bottom
 /superpowers                      Law activator — route the task to the right specialist
 /workspace-surface-audit          Audit repo + MCP + env, recommend high-value skills
-/planning-with-files              Create task_plan.md, findings.md, progress.md
+/roast                            5-persona adversarial council — GO / RESHAPE / KILL on an idea
 /grill-me                         Interview-mode alignment (one question at a time)
 /grill-with-docs                  Grill-me with persistent outcomes — updates CONTEXT.md + ADRs inline
+/intent-driven-development        Scope an ambiguous change into verifiable acceptance criteria
+/planning-with-files              Create task_plan.md, findings.md, progress.md
+/goal-check                       Score recent activity against the task_plan.md goal (drift detector)
+/reconcile                        Establish git ground truth before any mutation; verify a push landed
+/audit                            Audit recent commits for real defects, confirm each before fixing
+/ship                             Single-defect fast path — reconcile, TDD fix, verify, one PR
+/production-readiness-review      Parallel readiness gate — severity-ranked punch-list (reports only)
 /handoff                          End-of-session compaction into mktemp brief for the next agent
+/recall                           BM25 search over past observations — "have I hit this before?"
 /discipline                       Quick reference card of the 7 Laws
+/model-forward                    Restate the model-forward stance — go with the model, not against it
 /verify-install                   One-shot post-install check — commands, gateguard, observe
 /dashboard                        Visual instinct health dashboard
 /companion-preference             Inspect companion-preference hook telemetry
 /ralph                            Autonomous PRD story-by-story loop
 /learn-eval                       Capture session patterns into new skills (needs observation history)
 /harvest                          Extract reusable patterns from session friction (needs observation history)
+/distill                          Distill repeated successful sequences into draft instincts (needs observation history)
 /release-train                    Coordinate a multi-PR release sequence
 /swarm                            Fan-out coordination across parallel sub-agents
 ```
 
-All 18 ship in the marketplace bundle. The Beginner install gets all of them — with one caveat: `/learn-eval` and `/harvest` only produce useful output once Mulahazah has accumulated observation history (~20 observations), so running them on day 1 returns an empty result, not a broken command. `/swarm` and `/release-train` are orchestration commands aimed at larger multi-agent or multi-PR work. In Expert (`npx`) mode, the installer mirrors the full set into `~/.claude/commands/` and additionally exposes the planning workflow through the MCP tools `ci_plan_init` (initialize `task_plan.md`, `findings.md`, `progress.md` in the project root) and `ci_plan_status` (summarize their current contents).
+All 28 ship in the marketplace bundle. The Beginner install gets all of them — with one caveat: `/learn-eval`, `/harvest`, and `/distill` only produce useful output once Mulahazah has accumulated observation history (~20 observations), so running them on day 1 returns an empty result, not a broken command. `/swarm` and `/release-train` are orchestration commands aimed at larger multi-agent or multi-PR work. In Expert (`npx`) mode, the installer mirrors the full set into `~/.claude/commands/` and additionally exposes the planning workflow through the MCP tools `ci_plan_init` (initialize `task_plan.md`, `findings.md`, `progress.md` in the project root) and `ci_plan_status` (summarize their current contents).
+
+</details>
 
 ---
 
 ## Skills
 
-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).
+The plugin ships **27 skills** — 1 core + 1 featured + 6 tier-1 + 16 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 28th skill: [CONTRIBUTING.md § Evolution — adding a new skill](CONTRIBUTING.md#evolution--adding-a-new-skill).
 
 ---
 
@@ -280,17 +330,48 @@ Catches writes without prior research (Law 1), too many edits without verificati
 
 ---
 
-## Uninstall
+## Portfolio spine
+
+Two standalone commands turn a multi-repo portfolio into scored, auditable evidence. Both are offline: they read local files only, no network.
+
+**`ci-audit-actions`** — static GitHub Actions security scan. Flags missing/over-broad `permissions:`, unpinned actions, missing job timeouts, missing concurrency, untrusted event text interpolated into `run:`, and dangerous triggers combined with secrets. Writes a markdown report; `--strict` exits 1 on high-severity findings.
 
 ```bash
-npx continuous-improvement install --uninstall
+npx -p continuous-improvement ci-audit-actions --repo . --out reports/actions-security.md --strict
 ```
 
-Removes skill, hooks, commands, MCP server. Learned instincts in `~/.claude/instincts/` are preserved — delete manually for a clean slate.
+**`ci-portfolio-health`** — scores every repo in a `portfolio/repos.json` registry 0-100 from local proof signals (CI presence, release receipts, experiment records, commit freshness, high-severity audit findings) and writes a worst-first table with a named next action per repo.
+
+```bash
+npx -p continuous-improvement ci-portfolio-health --config portfolio/repos.json --out reports/portfolio-health.md
+```
+
+Proof-format templates ship in [templates/](templates/): `release_receipt_template.md`, `experiment_template.md`, `actions_security_checklist.md`, and `portfolio_event.schema.json`.
 
 ---
 
-## The Brand Stack
+## More
+
+- [QUICKSTART.md](QUICKSTART.md) — 2-minute setup
+- [SKILL.md](SKILL.md) — full 7 Laws spec
+- [docs/skills.md](docs/skills.md) — full 27-skill catalog
+- [examples/](examples/) — bug fix, feature build, refactor walkthroughs
+- [templates/insights-claude-md.md](templates/insights-claude-md.md) — paste-in CLAUDE.md blocks for verification discipline, environment notes, think-before-acting, and git/deploy workflow (sourced from the 28-day usage report)
+- [CONTRIBUTING.md](CONTRIBUTING.md) — architecture, repo internals, adding a new skill
+- [SECURITY.md](SECURITY.md)
+
+<details>
+<summary><b>Uninstall · the brand stack · in the wild</b></summary>
+
+### Uninstall
+
+```bash
+npx continuous-improvement install --uninstall
+```
+
+Removes skill, hooks, commands, MCP server. Learned instincts in `~/.claude/instincts/` are preserved — delete manually for a clean slate.
+
+### The brand stack
 
 One product, three names. Use the one that fits the audience:
 
@@ -302,28 +383,12 @@ One product, three names. Use the one that fits the audience:
 
 Every skill description leads with `Enforces Law N (...)` so the discipline tag shows up the moment the skill is loaded; the lint `verify:skill-law-tag` blocks any skill that drops the tag.
 
----
-
-## In the wild
+### In the wild
 
 Workflows from this repo, applied to real open-source contributions:
 
-### pm-skills (product-on-purpose, Apache 2.0)
-
-[F-07 discover-market-sizing](https://github.com/product-on-purpose/pm-skills/pull/141) - new domain skill in the Discover phase covering TAM/SAM/SOM market sizing for the [pm-skills](https://github.com/product-on-purpose/pm-skills) library.
-
-Authored end-to-end with `/superpowers` and `/proceed-with-the-recommendation`: surface audit before any code, brainstorm gate with WILD/RISA framing, branch isolation off the upstream fork, single-skill PR scope per the upstream maintainer's curated-contributions model, count cascade across 23 docs files, and 9 local validators green before push (`lint-skills-frontmatter`, `validate-agents-md`, `validate-commands`, `check-count-consistency`, `check-nav-completeness`, `check-generated-content-untouched`, `check-generated-freshness`, `validate-meeting-skills-family`, `validate-plugin-install`).
+**pm-skills (product-on-purpose, Apache 2.0)** — [F-07 discover-market-sizing](https://github.com/product-on-purpose/pm-skills/pull/141), a new domain skill in the Discover phase covering TAM/SAM/SOM market sizing for the [pm-skills](https://github.com/product-on-purpose/pm-skills) library. Authored end-to-end with `/superpowers` and `/proceed-with-the-recommendation`: surface audit before any code, brainstorm gate with WILD/RISA framing, branch isolation off the upstream fork, single-skill PR scope per the upstream maintainer's curated-contributions model, count cascade across 23 docs files, and 9 local validators green before push.
 
----
-
-## More
-
-- [QUICKSTART.md](QUICKSTART.md) — 2-minute setup
-- [SKILL.md](SKILL.md) — full 7 Laws spec
-- [docs/skills.md](docs/skills.md) — full 26-skill catalog
-- [examples/](examples/) — bug fix, feature build, refactor walkthroughs
-- [templates/insights-claude-md.md](templates/insights-claude-md.md) — paste-in CLAUDE.md blocks for verification discipline, environment notes, think-before-acting, and git/deploy workflow (sourced from the 28-day usage report)
-- [CONTRIBUTING.md](CONTRIBUTING.md) — architecture, repo internals, adding a new skill
-- [SECURITY.md](SECURITY.md)
+</details>
 
 MIT.