continuous-improvement 3.9.2 → 3.12.3

package/.claude-plugin/marketplace.json

@@ -7,8 +7,8 @@
   "plugins": [
     {
       "name": "continuous-improvement",
-      "description": "Stops Claude Code from skipping research, claiming 'done' without verifying, and repeating yesterday's mistakes. The 7 Laws of AI Agent Discipline — 13 enforcement skills, gating hooks, and the Mulahazah auto-leveling instinct engine.",
-      "version": "3.9.2",
+      "description": "Makes Claude Code reason harder, recall past corrections, and learn from every session so its competence compounds run over run. The Mulahazah engine turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time — 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.12.3",
       "source": "./plugins/continuous-improvement",
       "author": {
         "name": "naimkatiman"
@@ -53,7 +53,7 @@
     },
     {
       "name": "oh-my-claudecode",
-      "description": "Multi-agent orchestration system for Claude Code — 39 skills + 19 agents covering audit, plan, build, verify, ship, release, retrospective, and ops. Includes ralph (autonomous PRD loop), release, ultrawork, ultraqa, team, trace, visual-verdict, debug, deep-dive, deep-interview, autopilot, autoresearch. Vendored snapshot at third-party/oh-my-claudecode/ pinned to upstream SHA aacde3e (v4.13.6). Heavy overlap with continuous-improvement /ralph and /superpowers — pick per task.",
+      "description": "Multi-agent orchestration system for Claude Code — 38 skills + 19 agents covering audit, plan, build, verify, ship, release, retrospective, and ops. Includes ralph (autonomous PRD loop), release, ultrawork, ultraqa, team, trace, visual-verdict, debug, deep-dive, deep-interview, autopilot, autoresearch. Vendored snapshot at third-party/oh-my-claudecode/ pinned to upstream SHA aacde3e (v4.13.6). Heavy overlap with continuous-improvement /ralph and /superpowers — pick per task.",
       "version": "4.13.6",
       "source": "./third-party/oh-my-claudecode",
       "author": {

package/CHANGELOG.md

@@ -6,6 +6,101 @@ All notable changes to this skill are documented here.
 
 ## [Unreleased]
 
+## [3.12.3] — 2026-06-08
+
+### Fixed
+
+- **Completed the OIDC trusted-publishing pipeline by restoring setup-node `registry-url`** — #211 had removed it to kill the dummy-token `.npmrc`, but that left npm with no registry anchor for the OIDC token exchange (`ENEEDAUTH` on 3.12.1/3.12.2). With `registry-url` back, Node 22 (#213), npm ≥ 11.5.1, and a configured trusted publisher, npm mints and uses the OIDC token. **3.12.3 is the first version actually published to npm** carrying the 3.12.0 changes (#198 positioning, #199 recall hook, #202 OIDC, #203 doc-drift, #204 tool-count); 3.12.0–3.12.2 were never published. (#215)
+
+## [3.12.2] — 2026-06-08
+
+### Fixed
+
+- **Release workflow now runs on Node 22 so OIDC trusted publishing actually authenticates** — npm trusted publishing requires npm ≥ 11.5.1 **and Node ≥ 22.14.0** ([docs.npmjs.com/trusted-publishers](https://docs.npmjs.com/trusted-publishers)). `release.yml` ran on Node 20, below the floor, so the OIDC token exchange never engaged: the `v3.12.0` publish fell back to setup-node's dummy `.npmrc` token (`E404`) and `v3.12.1` had no auth at all (`ENEEDAUTH`). Bumping `setup-node` to Node 22 (plus #211 dropping the token-bearing `.npmrc`) completes the OIDC pipeline. **3.12.2 is the first npm artifact to carry the 3.12.0 changes** (#198 positioning, #199 recall hook, #202 OIDC pipeline, #203 doc-drift, #204 tool-count invariant); `3.12.0` and `3.12.1` were never published to npm. (#211, #213)
+
+## [3.12.1] — 2026-06-08
+
+### Fixed
+
+- **npm release pipeline now authenticates via OIDC instead of a dummy token** — the `v3.12.0` tag publish failed with `E404` on the registry PUT: `actions/setup-node` with `registry-url` wrote an `.npmrc` carrying `_authToken=${NODE_AUTH_TOKEN}` set to its placeholder value, so npm used that dummy token for the publish instead of OIDC trusted publishing (provenance still signed, since the sigstore OIDC token is separate). Dropping `registry-url` from `release.yml` lets `npm publish --provenance` fall back to OIDC as intended. **3.12.1 is the first npm artifact to carry the 3.12.0 changes** (intelligence-amplifier positioning #198, recall-briefing hook #199, OIDC pipeline #202, doc-drift fixes #203, `verify:tool-count` invariant #204); the `3.12.0` version was never published to npm. (#211)
+
+## [3.12.0] — 2026-06-07
+
+### Added
+
+- **Proactive recall-briefing hook (opt-in episodic memory)** — `hooks/recall-briefing.mjs` runs on `UserPromptSubmit`, queries the BM25 observation index in-process, and surfaces the most relevant prior corrections as a briefing before the agent acts. First capability increment of the intelligence-amplifier reframe: a lesson learned once is recalled automatically on the next related prompt instead of being re-taught. Opt-in — disabled unless wired into the hook config.
+- **`verify:tool-count` content invariant (12th in `verify:all`)** — `bin/check-tool-count.mjs` pins MCP tool-count claims in docs and source to the generated `plugins/{expert,beginner}.json` `tools[].length`, so a count can't drift when a tool is added — the gap that let "12 tools" pass `verify:all` green in the 2026-06-07 audit. Pins four claims across `docs/skills.md`, `README.md`, `QUICKSTART.md`, and the `mcp-server` banner. Follow-up to #203 (PR #204).
+
+### Changed
+
+- **Positioning reframed from "seatbelt" to intelligence amplifier across every user-facing surface** — the 7 Laws of AI Agent Discipline keep their names but each is reframed from a restriction into a capability the agent gains. README h1 "A seatbelt for Claude Code" → "Claude Code that gets sharper every session"; landing page title/hero/CTA, `SHARED_PLUGIN_DESCRIPTION` (the source of truth that propagates to `package.json` + all generated manifests + `llms.txt`), SKILL.md, and CONTRIBUTING.md all reframed from "Stops Claude Code from…" loss-framing to capability-led copy. Honesty held: recall stays lexical/BM25, instincts decay, GateGuard still blocks (framed as forced grounding) — no over-claiming. Plan: `docs/plans/2026-06-07-intelligence-amplifier-reframe.md`.
+- **npm release now publishes via OIDC trusted publishing instead of `NPM_TOKEN`** — the account enforces 2FA-on-writes, which makes long-lived granular tokens hit EOTP in CI. `release.yml` upgrades npm to ≥ 11.5.1 and publishes with `npm publish --access public --provenance` (signed provenance from the OIDC claims); the `NPM_TOKEN` secret dependency is gone. See `docs/RELEASING.md` for the one-time trusted-publisher setup.
+
+### Fixed
+
+- **Doc/count drift surfaced by a post-merge audit** — corrected prose/count claims that drifted from the v3.11.0 implementation and that no `verify:all` invariant covers: MCP expert surface is 18 tools (not 12); the CONTRIBUTING release checklist now defers to `docs/RELEASING.md` instead of describing the retired manual publish flow; `agents/README.md` repointed off a non-existent reference doc; the oh-my-claudecode vendored snapshot count corrected to 38 skills; `harvest` observe-path corrected to `instincts/bin/observe.mjs`; and reports/update-card test counts synced to 793.
+
+## [3.11.0] — 2026-06-07
+
+### Added
+
+- **In-harness GateGuard clearance: `ci_gateguard_clear` + `bin/gateguard-clear.mjs`** — after presenting the facts, clear the gate with the `ci_gateguard_clear` MCP tool (available in beginner *and* expert mode, since the gate fires for every install) or the `gateguard-clear.mjs` CLI over the hook-allowed Bash route, instead of hand-writing the session-state JSON. Both take one or more file paths and record clearance through the shared canonical writer; the CLI accepts `--state <gateguard-session.json>` to target the exact file the block reason prints.
+
+### Changed
+
+- **Landing page rebuilt as a Blueprint spec-sheet on the `continuous-improvement.dev` domain** — `docs/landing/index.html` is now a warm-paper editorial spec-sheet (OKLCH palette, one safety-vermilion accent, Space Grotesk + JetBrains Mono, asymmetric hero, the 7 Laws rendered as numbered clauses, enforcement zig-zag), replacing the previous dark/purple/emoji page. The 7-Law copy is pulled verbatim from `commands/discipline.md`. A `docs/landing/CNAME` plus updated `homepage`, canonical URL, and README link point the GitHub Pages site at the `continuous-improvement.dev` custom domain.
+
+### Fixed
+
+- **GateGuard block reason now points at a clearance path that works on Claude Code** — the runtime hook told the agent to retry with `_gateguard_facts_presented: true`, but Claude Code's strict tool schema (`additionalProperties: false`) rejects that extra param with `InputValidationError` before the hook runs, leaving the first Edit/Write per file unclearable through the file tools. The block reason and the skill's "Honor system" note now lead with the portable route — record clearance in the session state file via a non-destructive Bash write — and keep the inline flag as a secondary path for harnesses that forward unknown tool params. No behavior change to the gate itself.
+- **GateGuard clearance now matches regardless of path form** — the hook and every clearance helper canonicalize the project root and per-file keys (lowercase drive letter, `\`→`/`, strip trailing slash), so a clearance recorded by one process (e.g. the MCP server, which resolves the root via git-toplevel `D:/…`) is seen by the hook (which resolves via `CLAUDE_PROJECT_DIR` `d:/…`). This removes the drive-case / separator mismatch that previously forced seeding every path variant across candidate session dirs by hand. `lib/gateguard-state.mjs` is now bundled into `plugins/continuous-improvement/` (the bundled hook and `mcp-server.mjs` both import it).
+
+---
+
+## [3.10.0] — 2026-06-03
+
+### Fixed
+
+- **Installer now persists cleanup-only hook filtering** — `src/bin/install.mts` now writes `settings.json` when it strips broken legacy observe/session hooks even if the clean installer hook was already present, so coexistence cases no longer leave stale legacy commands behind. Regression coverage now seeds a clean observe hook alongside a broken legacy one and verifies the broken entry disappears while the clean one remains once.
+- **Installer now clones hook entries per target bucket** — the observe/session hook entries are now constructed inside each loop iteration instead of reusing one object across `PreToolUse`/`PostToolUse` or `SessionStart`/`SessionEnd`, so a future mutation in one bucket can't silently leak into the paired bucket.
+- **GateGuard MultiEdit docs now match runtime behavior** — the skill docs no longer describe MultiEdit as `edits[0].file_path` V1; they now document the per-file gate that blocks mixed-clearance batches until every edited path is cleared or facts are presented, and the runtime keeps the 50-file cap intact even for multi-file batches while naming the full batch in the block reason.
+
+---
+
+## [3.9.2] — 2026-05-10
+
+Manifest-derivation patch. One fix plus the release cut.
+
+### Fixed
+
+- **Manifests track the package version automatically** (PR #122) — `VERSION` in `src/lib/plugin-metadata.mts` is now derived from `package.json` at build time instead of being a hand-maintained constant. `npm run build` regenerates `marketplace.json` and `plugin.json` with the correct version on every release without a separate manual edit. v3.9.2 was the first release cut with auto-derived manifests (PR #123).
+
+---
+
+## [3.9.1] — 2026-05-10
+
+First release through the tag-triggered `release.yml` pipeline. The `v3.9.0` tag was placed before PR #99 merged, so this release range also carries the feature and CI work that landed on top of the v3.8.0 dispatcher train — the substantive items are listed below; the `[3.9.0]` entry above describes only PRs #97–#99.
+
+### Added
+
+- **`release.yml` tag-triggered npm publish** (PR #119) — pushing a `v*` tag now builds, verifies, and publishes to npm, with the retarget policy and cut procedure documented in `docs/RELEASING.md`. PR #120 cut v3.9.1 as the first exercise of this pipeline.
+- **`gateguard` runtime PreToolUse hook** (PRs #106, #108) — `hooks/gateguard.mjs` ships as the runtime layer that physically blocks Edit/Write/MultiEdit and destructive Bash until fact-list investigation is presented. PR #107 added hotfix-PR mode, a synthetic-checks rung, and the insights CLAUDE.md template.
+- **Native review-agent trio** (PR #112) — `code-reviewer`, `security-auditor`, and `test-engineer` agents in `plugins/continuous-improvement/agents/`, routed by the orchestrator during verify and review phases.
+- **Three verification-ladder skills** (PR #117) — `state-reconciliation`, `recovery-classification`, and `worktree-safety` added as pre-dispatch invariants.
+- **`verify:doc-runtime-claims` lint** (commit `241e8fe`) — codifies the audit-twice rule: any user-facing runtime-hook claim must carry a `hooks/<file>.mjs` anchor within ±5 lines.
+- **Repo-root `.mcp.json`** (PR #113) — dogfoods `bin/mcp-server.mjs` from inside the repo.
+
+### Changed
+
+- **Installer path collapse + dispatcher rewrite** (commit `bc76bfe`) — installer paths collapsed, versions synced, installer surface expanded.
+- **`pm-skills` switched from vendored snapshot to out-of-band marketplace install** (PR #101) — product-management coverage now installs via `phuryn/pm-skills` per `docs/THIRD_PARTY.md` instead of being vendored under `third-party/`.
+- **CI `verify-generated` check widened** (PR #99) — `git diff` path widened to `.claude-plugin bin test lib plugins`.
+
+### Fixed
+
+- **MCP server emits NDJSON over stdio** (PR #114) — corrected the transport framing to the MCP spec (NDJSON, not LSP-style framing).
+- **`gateguard` doc wording reverted** (commit `5eca467`) — the "runtime gate is roadmap" wording was reverted once the hook actually shipped.
+
 ---
 
 ## [3.9.0] — 2026-05-07

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Naim Katiman
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Naim Katiman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/QUICKSTART.md

@@ -25,6 +25,8 @@ Without it, `/superpowers` still works — it falls back to inline behavior —
 
 ### Verify the install — two checks
 
+**Fastest path:** restart Claude Code, then run `/verify-install` — it walks all three checks (commands loaded, gateguard fires, observation capture recording) and prints a single ✓ wired / ✗ missing line. The manual checks below are the same probes done by hand, kept here so you can see what each one proves.
+
 **Check 1 — slash command loaded.** Quit and reopen Claude Code (slash commands only load on session start), then run:
 
 ```
@@ -97,14 +99,17 @@ This shows what the system has learned — instincts, confidence levels, and the
 
 ## How auto-leveling works
 
-You don't configure anything. The system promotes itself:
+You don't configure anything. The system promotes itself. The unit is
+**observations** — one per tool call, not one per session — so a single active
+session can produce dozens. The four levels below mirror the source-of-truth
+table in [SKILL.md](SKILL.md):
 
-| Your usage | What happens |
-|-----------|-------------|
-| First sessions | Hooks capture tool calls silently. No behavior change. |
-| After ~20 sessions | Agent analyzes patterns, creates instincts (silent — you see nothing) |
-| After ~50 sessions | Instincts cross 0.5 → agent starts suggesting: "Consider: [action]" |
-| After ~100 sessions | Instincts cross 0.7 → agent auto-applies learned behaviors |
+| Level | Trigger | What happens |
+|-------|---------|-------------|
+| CAPTURE | < 20 observations | Hooks capture tool calls silently. No behavior change. |
+| ANALYZE | 20+ observations | Agent analyzes patterns, creates instincts (silent — you see nothing) |
+| SUGGEST | Any instinct at 0.5–0.69 confidence | Agent suggests inline: "Consider: [action]" |
+| AUTO-APPLY | Any instinct at 0.7+ confidence | Agent auto-applies the learned behavior |
 
 Corrections drop instinct confidence. Unused instincts decay. The system self-corrects.
 
@@ -125,7 +130,7 @@ Corrections drop instinct confidence. Unused instincts decay. The system self-co
 
 ## Expert (npx) — only if you want MCP, hooks, or instinct packs
 
-The Beginner path above is enough for most users. Pick this only if you want the MCP tools (12 of them, including `ci_plan_init` / `ci_plan_status` for `task_plan.md`-style planning), the session hooks that feed Mulahazah, or the starter instinct packs.
+The Beginner path above is enough for most users. Pick this only if you want the MCP tools (18 of them, including `ci_plan_init` / `ci_plan_status` for `task_plan.md`-style planning), the session hooks that feed Mulahazah, or the starter instinct packs.
 
 Do not run both paths against the same `~/.claude/` — that produces duplicated state. Pick one and stick with it.
 

package/README.md

@@ -1,49 +1,94 @@
+<!-- README landing-page structure rationale: 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" />
 </p>
 
-<h1 align="center">The 7 Laws of AI Agent Discipline</h1>
+<h1 align="center">Claude Code that gets sharper every session</h1>
 
 <p align="center">
-  <b>Stop your Claude Code agent from skipping steps, guessing, and declaring "done" without verifying.</b>
+  <b>Reasons deeper. Recalls what it already solved. Verifies before "done". Keeps every lesson.</b>
+</p>
+
+<p align="center">
+  <i>The 7 Laws of AI Agent Discipline — runtime hooks, instinct memory, and skills that compound what it learns.</i>
 </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://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)
+  <b>New here?</b> → <a href="QUICKSTART.md">QUICKSTART.md</a> (2 minutes) · <a href="https://continuous-improvement.dev">continuous-improvement.dev</a>
 </p>
 
+> **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.
+
 ---
 
-## The problem this solves
+## What this does
+
+Claude Code is powerful but leaves intelligence on the table: it edits before reading, guesses instead of checking, stacks five concerns into one commit, and says "done" without running tests. Continuous Improvement adds three layers that make it sharper:
+
+1. **Before an edit** — [`gateguard`](skills/gateguard.md) ships as a `PreToolUse` hook (`hooks/gateguard.mjs`) that physically blocks `Edit` / `Write` / `MultiEdit` and destructive `Bash` until the agent presents a fact-list investigation.
+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 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
+
+Without Continuous Improvement, "fix the login redirect bug" looks like this:
+
+> Claude edits `Login.tsx`, `LoginForm.tsx`, `useAuth.ts`, `authRouter.ts`, `redirects.ts`, and `useNavigate.ts` — six files, no plan, no investigation. Says "done". The redirect still loops. You roll back six files.
+
+With Continuous Improvement, the same prompt is forced through the gate:
+
+> `gateguard` blocks the first `Edit` until Claude presents a fact list. Claude reads `useAuth.ts`, finds the existing `redirectAfterLogin` helper, traces *why* the redirect loops (a stale `from` query param), and edits one line in one file. `verification-loop` runs the tests. The reply names the file, the line, the cause.
+
+Same agent. Same model. Different intelligence.
+
+---
 
-You have used Claude Code (or any agentic coding tool) long enough to recognize the failure pattern.
+## Who this is for
 
-| You ask the agent to... | What actually happens |
-|---|---|
-| Add a feature | It edits five files, never runs the build, says "done" |
-| Fix a bug | It reinvents a helper that already exists in the repo |
-| Refactor a module | It bundles three unrelated changes into one commit |
-| Pick up where last session ended | It re-explores from zero — the prior session's lessons are gone |
-| Verify the change works | It claims "this should work" without running a single test |
+Use this if you:
 
-Every one of those failures is the agent skipping a step a disciplined engineer would not skip. The 7 Laws of AI Agent Discipline names each step, gives it a hook or a skill that enforces it, and feeds the captured patterns back into the agent so the same mistake gets harder to repeat next session.
+- 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
 
-## What you get
+Skip it if you:
 
-- **A 7-step discipline** the agent must follow every task — research → plan → execute one thing → verify → reflect → learn → iterate. Each Law has at least one skill or hook that enforces it.
-- **14 bundled skills + a runtime PreToolUse hook** that turn the Laws into enforced behavior — `gateguard` runs as a PreToolUse hook (`hooks/gateguard.mjs`) that physically blocks Edit/Write/destructive Bash until the agent presents fact-list investigation. `tdd-workflow` enforces RED → GREEN → REFACTOR, `verification-loop` runs build/types/tests/security before "done", `deploy-receipt` closes the merge-to-production gap (deployed SHA + healthcheck), `proceed-with-the-recommendation` walks any agent's recommendation list top-to-bottom with per-item verification. The runtime hook catches the "skipped investigation" failure mode at the tool-call layer; the skills run model-side once the gate clears. See [§ How enforcement works](#how-enforcement-works) for the two-layer model.
-- **Mulahazah, the auto-leveling instinct engine** — hooks capture every tool call; after ~20 observations the agent analyzes patterns and creates instincts with confidence scores. Suggestions appear at 0.5+, auto-apply at 0.7+, decay when ignored. Project-scoped, promote to global after 2+ projects. You configure nothing.
-- **A GitHub Action transcript linter** that catches skipped Laws in CI — writes without prior research, edits without verification, too many files at once.
-- **Two install paths** — Beginner is two slash commands inside Claude Code (no Node, no bash, ~90% of users). Expert adds the MCP server, observation hooks, instinct packs, and the linter.
+- 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 whole thing is MIT, free, and lives in this one repo. No service, no account, no telemetry leaves your machine.
+(The runtime gate is `hooks/gateguard.mjs`; full mechanics in [How enforcement works](#how-enforcement-works) below.)
+
+---
+
+## The problem this solves
+
+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 | 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) |
+| 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), [`para-memory-files`](skills/para-memory-files.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.
 
 ---
 
@@ -86,14 +131,14 @@ You should see Claude **blocked** by the bundled `gateguard` PreToolUse hook (`h
 
 The 7 Laws are enforced at **two layers**:
 
-- **Runtime layer (hooks).** `gateguard` ships as a PreToolUse hook (`hooks/gateguard.mjs`) that physically blocks Edit / Write / MultiEdit / destructive Bash on the first mutation per file until the agent presents the facts named in [skills/gateguard.md § Gate Types](skills/gateguard.md). Destructive Bash (`rm -rf`, `git push --force`, `--force-with-lease`, `DROP DATABASE`, Windows `Remove-Item -Recurse`, etc.) is gated on every call, not just first. Read-only and exploratory tools (Read, Grep, Glob, routine Bash like `git status`) bypass the gate. Per-session state at `~/.claude/instincts/<project-hash>/gateguard-session.json` caps cumulative clearances at 50 distinct files to bound stuck-loop damage.
+- **Runtime layer (hooks).** `gateguard` ships as a PreToolUse hook (`hooks/gateguard.mjs`) that physically blocks Edit / Write / MultiEdit / destructive Bash on the first mutation per file until the agent presents the facts named in [skills/gateguard.md § Gate Types](skills/gateguard.md). Destructive Bash (`rm -rf`, `git push --force`, `--force-with-lease`, `DROP DATABASE`, Windows `Remove-Item -Recurse`, etc.) is gated on every call, not just first. Read-only and exploratory tools (Read, Grep, Glob, routine Bash like `git status`) bypass the gate. Per-session state at `~/.claude/instincts/<project-hash>/gateguard-session.json` caps cumulative clearances at 50 distinct files to bound stuck-loop damage. A second runtime hook, `goal-drift-stop` (`hooks/goal-drift-stop.mjs`), fires on `Stop`: it scores each turn against the stated `## Goal` and, on a substantive wrap-up that has drifted off-goal, warns by default (or re-prompts under `CLAUDE_GOAL_DRIFT_GATE=block`) — so a drifted session can't quietly declare "done". Fail-open.
 - **Model layer (skills).** Once the runtime gate clears for a file, the rest of the discipline (`tdd-workflow`, `verification-loop`, `proceed-with-the-recommendation`, etc.) runs model-side — the agent reads each skill and applies it. `observe.sh` / `observe.mjs` records every tool call into the Mulahazah feed for instinct extraction; that surface is observational, not enforcement.
 
 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
 
-Pick this if you want the MCP tools (12 of them, including `ci_plan_init` / `ci_plan_status` for `task_plan.md`-style planning), the session hooks that feed Mulahazah, and starter packs.
+Pick this if you want the MCP tools (18 of them, including `ci_plan_init` / `ci_plan_status` for `task_plan.md`-style planning), the session hooks that feed Mulahazah, and starter packs.
 
 Preconditions: Node 18 / 20 / 22, plus bash on Windows (Git Bash or WSL — `hooks/observe.sh` is a bash script and silently no-ops without it). **`jq` is no longer required**: as of v3.6.0, `observe.sh` prefers the Node observer (`bin/observe.mjs`) which writes the rich event schema natively without external dependencies. The bash thin-schema path is kept as a two-phase shim, so legacy installs that have not re-run `npx continuous-improvement install` since v3.5.x will still degrade silently without `jq` (`winget install jqlang.jq` on Windows, `brew install jq` on macOS, `apt install jq` on Debian/Ubuntu) — re-running the installer is the cleaner fix and removes the dependency entirely. See [CHANGELOG.md](CHANGELOG.md) `[3.6.0]` for the migration details.
 
@@ -125,20 +170,22 @@ The framework has documented operator-level modes that change hook behavior with
 | Env var | Effect | How to set |
 |---|---|---|
 | `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). |
 
 ---
 
 ## The 7 Laws
 
-| # | Law | Without it, agents... |
+| # | Law | What it gives the agent |
 |---|-----|----------------------|
-| 1 | **Research Before Executing** | reinvent what already exists |
-| 2 | **Plan Is Sacred** | scope-creep and overbuild |
-| 3 | **One Thing at a Time** | stack untested changes |
-| 4 | **Verify Before Reporting** | lie about being "done" |
-| 5 | **Reflect After Sessions** | repeat the same failures |
-| 6 | **Iterate One Change** | debug 5 changes at once |
-| 7 | **Learn From Every Session** | lose knowledge when context ends |
+| 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 |
 
 ```
 Research -> Plan -> Execute (one thing) -> Verify -> Reflect -> Learn -> Iterate
@@ -148,19 +195,13 @@ Research -> Plan -> Execute (one thing) -> Verify -> Reflect -> Learn -> Iterate
   <img src="assets/diagram-7-laws-loop.jpg" alt="The 7 Laws of AI Agent Discipline — circular workflow loop" width="820" />
 </p>
 
-Full spec, reflection-block format, and anti-examples: [SKILL.md](SKILL.md).
+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).
 
 ---
 
-## Mulahazah: Auto-Leveling Learning
-
-Hooks capture every tool call. After ~20 observations, Claude analyzes patterns and creates **instincts** with confidence scores:
+## Mulahazah: auto-leveling learning
 
-- **< 0.5** silent (stored, not surfaced)
-- **0.5–0.69** suggested inline when relevant
-- **0.7+** auto-applied
-- User corrections drop confidence by 0.1; unused instincts decay
-- Project-scoped, promoted to global after seen across 2+ projects
+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" />
@@ -179,135 +220,27 @@ Hooks capture every tool call. After ~20 observations, Claude analyzes patterns
 /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
+/grill-me                         Interview-mode alignment (one question at a time)
+/grill-with-docs                  Grill-me with persistent outcomes — updates CONTEXT.md + ADRs inline
+/handoff                          End-of-session compaction into mktemp brief for the next agent
 /discipline                       Quick reference card of the 7 Laws
+/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 (expert)
-/harvest                          Extract reusable patterns from session friction
+/learn-eval                       Capture session patterns into new skills (needs observation history)
+/harvest                          Extract reusable patterns from session friction (needs observation history)
 /release-train                    Coordinate a multi-PR release sequence
 /swarm                            Fan-out coordination across parallel sub-agents
 ```
 
-All 13 ship in the marketplace bundle. The Beginner install gets all of them. 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 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).
 
 ---
 
-## Law Coverage
+## Skills
 
-Every bundled skill, command, and hook enforces at least one of the 7 Laws. The full Law-to-tool alignment matrix lives in [CONTRIBUTING.md → Law Coverage Matrix](CONTRIBUTING.md#law-coverage-matrix); each skill's `description:` also leads with `Enforces Law N (...)` so the tag shows up every time the skill is loaded. Operator-level mode toggles live in the **Operator modes** section above the 7 Laws, alongside install.
-
----
-
-## All 14 Skills
-
-The plugin ships **1 core + 1 featured + 5 tier-1 + 4 tier-2 + 3 always-bundled = 14 skills**. Source-of-truth lives in [`skills/`](skills/) (one `.md` per skill); the plugin bundle at [`plugins/continuous-improvement/skills/`](plugins/continuous-improvement/skills/) is regenerated by `npm run build`.
-
-<details>
-<summary>Show the full skill table (14 rows)</summary>
-
-| # | Skill | Tier | Law | What it does |
-|---|-------|------|-----|--------------|
-| 1 | [`continuous-improvement`](SKILL.md) | core | — | The 7 Laws spec itself (research → plan → execute → verify → reflect → learn → iterate) |
-| 2 | [`proceed-with-the-recommendation`](skills/proceed-with-the-recommendation.md) ⭐ | featured | all 7 | Walks any agent's recommendation list top-to-bottom, routes each item, verifies per item, halts on `needs-approval` |
-| 3 | [`gateguard`](skills/gateguard.md) | 1 | 1 | Runtime PreToolUse hook (`hooks/gateguard.mjs`) + skill: physically blocks Edit/Write/MultiEdit and every destructive Bash until fact-list investigation is presented. Read-only and routine Bash bypass. |
-| 4 | [`para-memory-files`](skills/para-memory-files.md) | 1 | 5 + 7 | Durable file-based memory using PARA (Projects/Areas/Resources/Archives) for cross-session context |
-| 5 | [`tdd-workflow`](skills/tdd-workflow.md) | 1 | 3 + 4 | RED → GREEN → REFACTOR enforcement with 80%+ coverage across unit/integration/E2E |
-| 6 | [`verification-loop`](skills/verification-loop.md) | 1 | 4 | Six-phase verification (build, types, lint, tests, security, diff) with PASS/FAIL report |
-| 7 | [`deploy-receipt`](skills/deploy-receipt.md) | 1 | 4 | Closes the merge-to-production gap on auto-deploy targets (Railway, Cloudflare Workers, Vercel, Netlify, Fly.io). "Done" requires the deployed SHA matching merged HEAD + a healthcheck returning 200 — runs after the vendored `finishing-a-development-branch`. |
-| 8 | [`safety-guard`](skills/safety-guard.md) | 2 | 3 | Three-mode runtime guard (careful/freeze/guard) that blocks destructive commands and locks edits to a directory |
-| 9 | [`strategic-compact`](skills/strategic-compact.md) | 2 | 5 | Suggests `/compact` at logical phase boundaries instead of arbitrary auto-compaction |
-| 10 | [`token-budget-advisor`](skills/token-budget-advisor.md) | 2 | 2 | Token estimator that offers 25/50/75/100% depth choices before answering |
-| 11 | [`wild-risa-balance`](skills/wild-risa-balance.md) | 2 | 2 | Pairs WILD (bold) generation with RISA (safe) execution; splits recommendation lists into pilots above a baseline |
-| 12 | [`ralph`](skills/ralph.md) | companion | 6 | Autonomous loop that executes a PRD story-by-story with quality checks between iterations |
-| 13 | [`superpowers`](skills/superpowers.md) | companion | activator | Law activator — routes tasks to the correct Law-aligned specialist so the right discipline fires automatically |
-| 14 | [`workspace-surface-audit`](skills/workspace-surface-audit.md) | companion | 1 | Audits the active repo, MCP servers, plugins, env, then recommends high-value skills/workflows |
-
-</details>
-
-The orchestrator skill `proceed-with-the-recommendation` also routes to optional companion skills from external plugins (e.g. `obra/superpowers`, `code-review`, `frontend-design`, `commit-commands`). Each routing target has an inline fallback in the orchestrator, so the plugin works on a clean install with nothing else present — install the dedicated companion only when you want a specialist over the fallback. Full target list with source-plugin and risk-if-absent: [`plugins/continuous-improvement/README.md` § Required vs Optional companions](plugins/continuous-improvement/README.md#required-vs-optional-companions).
-
-### Beginner gets — by default
-
-Tier 1 + featured + companion. Auto-installed when you run the plugin install commands above. No flags, no choices.
-
-### Expert gets — additionally
-
-Tier 2 (`safety-guard`, `strategic-compact`, `token-budget-advisor`, `wild-risa-balance`), the MCP server (12 tools incl. `ci_plan_init`/`ci_plan_status`), session-observation hooks for Mulahazah, and `/learn-eval` for capturing session patterns into new skills.
-
-### Drop-in single-file install
-
-Want one skill without the whole plugin? Copy the `.md` file straight into `~/.claude/skills/<name>/SKILL.md`:
-
-```bash
-SKILL=proceed-with-the-recommendation
-mkdir -p ~/.claude/skills/$SKILL
-curl -L https://raw.githubusercontent.com/naimkatiman/continuous-improvement/main/skills/$SKILL.md \
-  -o ~/.claude/skills/$SKILL/SKILL.md
-```
-
----
-
-## Evolution — adding a new skill
-
-Drop one `.md` file into [`skills/`](skills/), run `npm run build`, and the plugin bundle, manifests, and bundled-skills README regenerate from that source. Seven lints (`verify:all` + `verify:generated`) block the merge if anything drifts.
-
-### The 5-step recipe
-
-```bash
-# 1. Create the source file
-touch skills/<your-skill>.md
-```
-
-```yaml
-# 2. Frontmatter must declare name + tier + Law-tagged description
----
-name: <your-skill>
-tier: "1"                # core | featured | "1" | "2" | companion
-description: "Enforces Law N (<law name>) of the 7 Laws of AI Agent Discipline. <what it does>."
----
-```
-
-```bash
-# 3. Regenerate the bundle (also writes plugins/.../skills/<your-skill>/SKILL.md
-#    + the bundled-skills README, which is itself generator-output)
-npm run build
-
-# 4. Run all 6 verify lints — must all pass
-npm run verify:all
-
-# 5. Commit one concern at a time (per CLAUDE.md): the source skill alone first,
-#    then any wiring (hooks, commands, Law-coverage table updates) as separate commits
-git add skills/<your-skill>.md plugins/continuous-improvement/skills/<your-skill>/
-git commit -m "feat(skills): add <your-skill> for Law N enforcement"
-```
-
-### What the build does for you automatically
-
-- **Mirrors source → bundle** (`bin/generate-plugin-manifests.mjs`): copies `skills/<name>.md` to `plugins/continuous-improvement/skills/<name>/SKILL.md`
-- **Regenerates plugin manifests** with the new skill listed in tier order
-- **Re-renders** [`plugins/continuous-improvement/skills/README.md`](plugins/continuous-improvement/skills/README.md) (do not edit by hand — generator output)
-
-### What the lints enforce so you cannot ship a half-wired skill
-
-| Lint | Blocks |
-|------|--------|
-| `verify:skill-mirror` | source `skills/<name>.md` and `plugins/.../<name>/SKILL.md` are out of sync |
-| `verify:skill-tiers` | skill has missing or unrecognized `tier:` value |
-| `verify:skill-law-tag` | skill description does not start with `Enforces Law N` (or `Law activator`, or `all 7 Laws`) |
-| `verify:docs-substrings` | README/QUICKSTART references a removed/renamed skill |
-| `verify:everything-mirror` | non-skill files in `plugins/continuous-improvement/` drift from their root-level source |
-| `verify:routing-targets` | `proceed-with-the-recommendation` names a routing target that is neither bundled nor declared in `optional-companions.json` |
-| `verify:generated` | `npm run build` was not re-run after a source change |
-
-### When to fold a new external skill into the 7 Laws
-
-A new skill is a fit if it provably enforces (or is a routed activator for) at least one of the 7 Laws. The Law-tag lint will refuse it otherwise. If it sits outside the laws (a domain skill — e.g. SQL optimization), keep it as an external plugin. The 7 Laws plugin stays disciplined about scope; that is the point.
-
-### What is *not* automated (the honest limits)
-
-- The Law-coverage matrix above (`## Law Coverage`) is hand-maintained — add your new skill to the right Law row when you ship it.
-- The "All 14 Skills" count in the section header is a literal — bump it when N changes.
-- Promotion between tiers (e.g. `2` → `1` after it proves itself) is a manual edit to the frontmatter `tier:` field, by design — the maintainer should make that call deliberately.
+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).
 
 ---
 
@@ -322,9 +255,7 @@ Lint agent behavior in CI. Detects skipped laws.
     strict: true
 ```
 
-`@v3` is a floating major-version tag that retargets on every `v3.x.y` release. Pin to a specific tag (`@v3.7.0`) if you need byte-reproducible CI; use `@v3` to ride patch and minor bumps automatically. See [CONTRIBUTING.md § Release](CONTRIBUTING.md#release) for the retarget policy.
-
-Catches: writes without prior research (Law 1), too many edits without verification (Law 3), code changes without tests/builds (Law 4), too many files at once (Law 6). Run locally with `node bin/lint-transcript.mjs <file>`.
+Catches writes without prior research (Law 1), too many edits without verification (Law 3), code changes without tests/builds (Law 4), too many files at once (Law 6). Run locally with `node bin/lint-transcript.mjs <file>`. The `@v3` floating-tag retarget policy lives in [CONTRIBUTING.md § Release](CONTRIBUTING.md#release).
 
 ---
 
@@ -356,7 +287,7 @@ Every skill description leads with `Enforces Law N (...)` so the discipline tag
 
 Workflows from this repo, applied to real open-source contributions:
 
-### pm-skills (product-on-purpose, 189 stars, Apache 2.0)
+### 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.
 
@@ -368,9 +299,10 @@ Authored end-to-end with `/superpowers` and `/proceed-with-the-recommendation`:
 
 - [QUICKSTART.md](QUICKSTART.md) — 2-minute setup
 - [SKILL.md](SKILL.md) — full 7 Laws spec
+- [docs/skills.md](docs/skills.md) — full 25-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
+- [CONTRIBUTING.md](CONTRIBUTING.md) — architecture, repo internals, adding a new skill
 - [SECURITY.md](SECURITY.md)
 
 MIT.

package/SKILL.md

@@ -6,7 +6,7 @@ description: "Install structured self-improvement loops with instinct-based lear
 
 # continuous-improvement
 
-You follow the continuous-improvement framework. These 7 laws govern all your work.
+You follow the continuous-improvement framework. These 7 laws make every task sharper — each is a capability that compounds: research deeper, plan tighter, verify with evidence, reflect, and learn so the same lesson is never re-taught.
 
 ## Law 1: Research Before Executing