continuous-improvement 3.23.0 → 3.25.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 29 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.23.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 28 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.25.0",
       "source": "./plugins/continuous-improvement",
       "author": {
         "name": "naimkatiman"

package/CHANGELOG.md

@@ -4,6 +4,43 @@ All notable changes to this skill are documented here.
 
 ---
 
+## [3.25.0] — 2026-09-07
+
+### Added
+
+- **Tagged releases now deploy continuous-improvement.dev** — after npm publish, `release.yml` deploys `docs/landing` to the Cloudflare Pages project and re-reads the live domain so a missed deploy fails the release instead of turning `landing-drift.yml` red the next morning. Gated on `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID`: without them the step warns and skips, so a fork still gets a complete publish. Last in the job, so a Cloudflare outage cannot block npm. (#307)
+- **`verify:test-count`** — every surface that states the suite size must agree, and CI tees `npm test` then asserts the claimed count against the real run. The filesystem cannot derive the number (generated cases in loops), so the docs stay the source of truth and the live run is the check. (#306)
+- **`verify:invariant-count`** — derives the invariant list from the `verify:all` script and fails if `CLAUDE.md`, `AGENTS.md`, or `docs/RELEASING.md` claim a different count or a different ordered name list. (#312)
+
+### Changed
+
+- **oh-my-claudecode snapshot 4.13.6 → 5.3.0** — `ultrawork` is gone upstream; the autonomous-run row now routes to `ultragoal`. The never-existent `oh-my-claudecode:retrospective` target is dropped rather than substituted. (#308, #309)
+- **obra/superpowers snapshot 5.1.0 → 6.3.0**. (#304)
+- **`verify:routing-targets` checks the vendored snapshot**, not just the declaration in `optional-companions.json`. A declared `oh-my-claudecode:` / `superpowers:` / `agent-skills:` / `ruflo-swarm:` target must exist at `third-party/<snapshot>/skills/<name>/`. (#311)
+
+### Fixed
+
+- **`refresh-third-party.mjs` keeps `OUR_NOTES.md` and `.fork-only-skills.txt`** across the wipe, and reports how many of ours were preserved. (#310)
+- **Refresh aborts before the wipe** if upstream removed a skill our flat source still routes to, naming the skills and files. Bypass is `--allow-stale-refs`, not `--force`. (#313)
+- **Brainstorming dispatcher wording** now describes the three-path router, not just the architectural path. (#305)
+
+## [3.24.0] — 2026-09-06
+
+### Added
+
+- **`config-guard`: the files that wire the guardrails are no longer unguarded** — a new PreToolUse hook (`hooks/config-guard.mjs`, matcher `Bash|Edit|MultiEdit|Write|NotebookEdit`) watches `.claude/settings.json`, `.claude/settings.local.json`, `.mcp.json`, `hooks.json`, `.claude/hooks/`, `.claude/plugins/`, `.claude-plugin/`, and the `claude plugin` / `mcp` / `config` CLI forms that edit them. Until now an agent could switch off every gate this plugin ships in a single `Edit` and nothing stood in the way. `CI_CONFIG_GUARD=warn` is the default and only prints one stderr line; `block` denies with the reason and the bypass; `off` disables it. Reads never trigger it, `CI_CONFIG_GUARD_ALLOW=true` clears one call, and it fails open on malformed input. Ported from karanb192/claude-code-hooks (MIT); the code and pattern list are ours. (#302)
+
+### Changed
+
+- **Destructive Bash is caught by structure, not spelling** — the guard was a 19-entry substring list, so `rm -r -f dist` walked past a rule written as `rm -rf`. A new pure classifier (`lib/destructive-bash.mjs`) splits the command at unquoted separators, tokenizes each segment (skipping `sudo`, `env` and `VAR=` prefixes) and applies structured rules for recursive-force `rm`, forced `git clean`, discarding `git checkout` / `git restore`, `find -delete`, a `+refspec` push and `git stash drop`, falling back to the original substring list. Every deny now ends with `Matched rule: <id>`, so the agent and the operator can see which rule fired. (#301)
+- **`CI_GATEGUARD_EXCLUDE` says when it skips the gate** — an exclusion used to be silent, so an operator whose config excluded a path saw no block and no explanation. The hook now prints one stderr line naming the matched fragment, and a catch-all fragment such as `/` or `.` is reported as the file gate being off for every path. The decision itself is unchanged, and destructive Bash is still never excluded. (#300)
+- **`safety-guard` retired; the six context-engineering rules applied across the bundle** — the skill's runtime edge never existed, so it is removed rather than left as prose that implies enforcement. The bundle is now 28 skills. (#293)
+- **The site and the README state only what the code does** — continuous-improvement.dev rebuilt around one question, "did I check, or did I hope": the two `/plugin` commands as the install, the literal deny JSON captured from the hook instead of mocked spec boxes, every enforcement card labelled with its real default, and a "what it cannot do" block naming the honor-system clearance, the ungated Bash writes and the fact that a Beginner install alone does not learn. New `docs/philosophy.md` carries the sourcing. Unsourced numbers ("~90% of users", "nearly every install support thread") are gone. (#299, #296)
+
+### Fixed
+
+- **One instinct hash for `C:/` and `c:/`** — a Windows drive letter differing only in case produced two project hashes, so observations split across two instinct directories and `/harvest` read half the history. Harvest sandbox false positives dropped in the same pass. (#297)
+
 ## [3.23.0] — 2026-08-15
 
 ### Added

package/QUICKSTART.md

@@ -2,7 +2,7 @@
 
 Zero to working in under 2 minutes.
 
-This is the **Beginner** path. It mirrors README.md and is enough for ~90% of users — no Node, no bash, no shell. If you want the MCP server, observation hooks, and instinct packs, see the **Expert (npx)** section at the bottom.
+This is the **Beginner** path. It mirrors README.md and is enough for most users — no npm install, no bash, no shell (the hooks run with the `node` on your PATH, 18+; without it the gate is silently absent). If you want the MCP server, observation hooks, and instinct packs, see the **Expert (npx)** section at the bottom.
 
 ---
 
@@ -33,7 +33,7 @@ Without it, `/superpowers` still works — it falls back to inline behavior —
 /discipline
 ```
 
-You should see the 7 Laws quick-reference card. If the command is not recognized after a restart, see Troubleshooting in [README.md](README.md#troubleshooting-install).
+You should see the 7 Laws quick-reference card. If the command is not recognized after a restart, see Troubleshooting in [README.md](README.md#install).
 
 **Check 2 — runtime gate is firing** (the `hooks/gateguard.mjs` script must invoke). Ask Claude to write a throwaway file with no research first:
 
@@ -41,7 +41,7 @@ You should see the 7 Laws quick-reference card. If the command is not recognized
 Edit a new file scratch.txt and put the word "hello" in it. Don't research anything first.
 ```
 
-You should see Claude **blocked** by the bundled `gateguard` PreToolUse hook (`hooks/gateguard.mjs`) with a fact-list reason: list importers, list public functions affected, show data-file schemas, quote the user instruction. That block is the proof the hook is wired and firing. If Claude writes the file with no pause, the hook did not load — see [README.md → Troubleshooting](README.md#troubleshooting-install).
+You should see Claude **blocked** by the bundled `gateguard` PreToolUse hook (`hooks/gateguard.mjs`) with a fact-list reason: list importers, list public functions affected, show data-file schemas, quote the user instruction. That block is the proof the hook is wired and firing. If Claude writes the file with no pause, the hook did not load — see [README.md → Troubleshooting](README.md#install).
 
 If you also want to confirm observation hooks: run `/dashboard` and look for a non-zero `Total` under `Observations` — that proves `observe.sh` / `observe.mjs` is recording tool calls.
 
@@ -60,21 +60,14 @@ If you ever see Claude skip a Law that the runtime hook doesn't enforce, name it
 
 ## Step 2: Use it
 
-Give your agent a task and prefix it:
+Give the agent a real task. You do **not** have to prefix every prompt — the `gateguard` PreToolUse hook (`hooks/gateguard.mjs`) fires on `Edit` / `Write` / destructive `Bash` either way.
 
-```
-Use the continuous-improvement framework to [your task here].
-```
+If you want the model-side loop named out loud:
 
-Examples:
 ```
 Use the continuous-improvement framework to add pagination to the users API endpoint.
-Use the continuous-improvement framework to debug why the login form breaks on mobile.
-Use the continuous-improvement framework to refactor the payment module to use the new SDK.
 ```
 
-Your agent will research, plan, execute one thing at a time, verify, and reflect.
-
 For long tasks that need persistent notes on disk, run:
 
 ```
@@ -85,24 +78,26 @@ That creates `task_plan.md`, `findings.md`, and `progress.md` in the project roo
 
 ---
 
-## Step 3: Check learning
+## Step 3: Close the loop (this is the learning trigger)
 
-After completing non-trivial work, run the canonical reflection command:
+Hooks capture tool calls silently. Instincts do **not** form until you ask. After a real task, run:
 
 ```
 /seven-laws
 ```
 
-This shows what the system has learned — instincts, confidence levels, and the current auto-level. `/continuous-improvement` is kept as an alias for backward compatibility and runs the same workflow.
+That is reflect + analyze + status. Skip it and observations pile up while nothing compounds. `/continuous-improvement` is an alias for the same workflow.
+
+When a bug feels familiar: `/recall <the error>`. One defect, one PR: `/ship`.
 
 ---
 
 ## How auto-leveling works
 
-You don't configure anything. The system promotes itself. The unit is
+On-demand by default (not every session start — that costs tokens). 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):
+table in [SKILL.md](SKILL.md). They apply when you run `/seven-laws` / `analyze`, a weekly schedule, or always-on:
 
 | Level | Trigger | What happens |
 |-------|---------|-------------|
@@ -124,7 +119,7 @@ Corrections drop instinct confidence. Unused instincts decay. The system self-co
 → Reply: *"What verification command did you run? Show me the output."*
 
 **No instincts showing up yet?**
-→ Normal. The system needs 20+ observations before it creates instincts. Keep working.
+→ Run `/seven-laws` after a real session. Then check `/dashboard`. Zero `Total` under Observations means capture is not wired (Expert install / plugin hooks). A high Total and zero instincts means you have not closed the loop yet. 20+ observations is the floor before analysis creates instincts.
 
 ---
 
@@ -139,7 +134,7 @@ npx continuous-improvement install --mode expert
 npx continuous-improvement install --pack react   # optional: react | python | go | meta
 ```
 
-Precondition: Node 18 / 20 / 22. Runtime hooks execute Node directly, so Git Bash and `jq` are not required. Re-run the installer once after upgrading to migrate legacy Bash hook rows. See [README.md § Expert](README.md#expert--adds-mcp-server-observation-hooks-and-instinct-packs) for the troubleshooting matrix.
+Precondition: Node 18 / 20 / 22. Runtime hooks execute Node directly, so Git Bash and `jq` are not required. Re-run the installer once after upgrading to migrate legacy Bash hook rows. See [README.md § Install](README.md#install) for the troubleshooting matrix.
 
 Verify with `/dashboard` — you should see instinct health and observation count.
 
@@ -147,7 +142,11 @@ Verify with `/dashboard` — you should see instinct health and observation coun
 
 ## That's it
 
-The skill is most valuable when:
+Smarter models do not retire this. They still skip your existing helper, claim "done" without the test output, and forget last week's correction. The runtime gate (`hooks/gateguard.mjs`) and this-repo memory do not merge into the model.
+
+You benefit in three rungs: (1) install and work — the gate fires; (2) `/seven-laws` after a real session — observations become instincts; (3) Expert + optional `CLAUDE_RECALL_BRIEFING=1` — memory fires without asking.
+
+Most valuable when:
 - You're under pressure and tempted to skip steps
 - A task has failed 2+ times
 - You want your agent to stop repeating the same mistakes

package/README.md

@@ -1,4 +1,4 @@
-<!-- README landing-page structure rationale: docs/plans/2026-06-28-readme-progressive-disclosure.md (supersedes docs/plans/2026-05-14-readme-landing-rewrite.md) -->
+<!-- README landing-page structure rationale: docs/plans/2026-08-22-readme-still-useful.md (adds model-forward + benefit rungs; prior: docs/plans/2026-06-28-readme-progressive-disclosure.md, 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" />
@@ -23,19 +23,19 @@
 </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>
+  <b>New here?</b> → <a href="QUICKSTART.md">QUICKSTART.md</a> (2 minutes) · <a href="https://continuous-improvement.dev">continuous-improvement.dev</a> · Latest: <a href="CHANGELOG.md">v3.23.0</a> (2026-08-15)
 </p>
 
 ## Quick start
 
-Inside Claude Code — two commands, no Node, no bash:
+Inside Claude Code — two commands, no npm install, no bash (the hooks run with the `node` on your PATH, 18+):
 
 ```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.
+**If you don't know which to pick, use Beginner.** That is the install above — enough for most 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.)
 
@@ -53,12 +53,54 @@ Claude Code is powerful but leaves intelligence on the table: it edits before re
 
 ---
 
+## As models get better
+
+Yes. This is still worth installing. Smarter models write more plausible code, faster. They still skip the helper that already exists in *your* repo, say "done" without the test output, and forget last Tuesday's correction. Those are harness problems, not IQ problems.
+
+| Merges into the model over time | Does not merge — this is the product |
+|---|---|
+| Planning etiquette, "remember to verify" reminders, routing flavor | The runtime gate (`hooks/gateguard.mjs`) that physically blocks an unresearched `Edit` |
+| Generic coding taste | *This repo's* past fixes, refusals, and instincts |
+| Sounding sure | Proof: the command you ran, the SHA that deployed, the test that failed then passed |
+
+The standing stance is [`model-forward`](skills/model-forward.md): go with the model, retire scaffolding when the native harness covers it, keep the two invariants — goal-driven execution, and research / verify / learn guardrails. Skills are disposable. The gate and the memory are not.
+
+---
+
+## How you actually benefit
+
+Three rungs. Most people stop at 1, never run `/seven-laws`, and conclude "it didn't learn." Capture is silent. Instincts form when you close the loop.
+
+| Rung | What you do | What you get | When |
+|---|---|---|---|
+| **1. Same session** | Beginner install (Quick start above). Give the agent a real task. Do not prefix every prompt — `hooks/gateguard.mjs` fires on `Edit` / `Write` / destructive `Bash`. | Reckless edits get blocked. Fake "done" has nowhere to hide once [`verification-loop`](skills/verification-loop.md) / [`tdd-workflow`](skills/tdd-workflow.md) run. | First hour. No memory required. |
+| **2. Close the loop** | After a non-trivial session: `/seven-laws`. When a bug feels familiar: `/recall <the error>`. One defect, one PR: `/ship`. Long task: `/planning-with-files` (writes `task_plan.md`). | Observations become instincts. Yesterday's correction survives into today. | After the first real task, then at session end. |
+| **3. Memory that fires without asking** | Expert install (`npx`, below). Optional: `CLAUDE_RECALL_BRIEFING=1`. After ~20 observations: `/harvest` and `/distill`. | Starter instincts, MCP tools (`ci_plan_init` / `ci_recall` / distill), a briefing of the last relevant fix on the next related prompt. | When you want compounding, not just a seatbelt. |
+
+`/learn-eval`, `/harvest`, and `/distill` return empty on day 1 if observation history is missing. That is not a broken command — it is rung 3 without rung 2. Check `/dashboard`: a zero `Total` under Observations means capture is not wired; a high Total and zero instincts means you have not run `/seven-laws` yet.
+
+---
+
 ## 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>
 
+The image is rendered from [`demo/gateguard-demo.html`](demo/gateguard-demo.html), faithful to what the hook prints. The literal output of `hooks/gateguard.mjs` on a `Write` payload with no research on the table (v3.23.0, paths shortened):
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Before creating src/lib/retry-helper.mts, present these facts:\n\n  1. List ALL files that import/require this file (use Grep)\n  2. List the public functions/classes affected by this change\n  3. If this file reads/writes data files, show field names, structure, and date format\n  4. Quote the user's current instruction verbatim\n\nThen clear the gate and retry the same call. ..."
+  }
+}
+```
+
+One denied call, a printed reason, a retry. Reproduce it yourself: `printf '{"tool_name":"Write","tool_input":{"file_path":"x.mts"}}' | node hooks/gateguard.mjs`.
+
 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.
@@ -93,6 +135,10 @@ Research -> Plan -> Execute (one thing) -> Verify -> Reflect -> Learn -> Iterate
 
 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).
 
+**Why these seven.** Every red flag in the table is a wish standing in for a check: "this should work" hopes the test passes, "I'll remember" hopes memory survives the session. The Laws are one old sentence turned into checks an agent can run on itself: the wise one takes account of himself and works for what comes after; the weak one follows his impulse and merely wishes (Jami` at-Tirmidhi 2459). You do not need the theology to use the test: before you say done, did you check, or did you hope? Sourcing, both gradings, and the mapping to each Law: [docs/philosophy.md](docs/philosophy.md).
+
+**What a gate can and cannot do.** `hooks/gateguard.mjs` can force the *form* of research; it cannot force honesty. It stays honor-system once the agent says the facts are on the table, which is why the account is settled by outcomes instead of by the agent's word: a correction cuts an instinct's confidence, a drifted session cannot quietly say done, and "verified" means the command output is in the reply.
+
 ---
 
 ## Install
@@ -153,7 +199,7 @@ Update later with `/plugin marketplace update continuous-improvement` or by re-r
 <details>
 <summary><b>Troubleshooting install</b></summary>
 
-Three failures account for nearly every install support thread. Try them in order:
+Three failures account for most install problems. Try them in order:
 
 | Symptom | Real cause | Fix |
 |---|---|---|
@@ -177,6 +223,9 @@ The framework has documented operator-level modes that change hook behavior with
 | `CLAUDE_TYPECHECK_GATE` | `hooks/typecheck-stop.mjs` (a `Stop` hook) runs the project typecheck (the `typecheck` npm script, else a local `tsc --noEmit`) on changed TS files at turn end and feeds a failure back to the model. `off` (default) is a no-op — the global advisory `typecheck-changed.sh` stays the default layer; `warn` prints a one-line stderr notice; `block` re-prompts with the tsc output so a headless/autonomous `-p` loop fixes its own type errors before ending the turn. Skips non-TS repos and turns where no TS file changed; fails open on any error or timeout. | bash/zsh: `export CLAUDE_TYPECHECK_GATE=block` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CLAUDE_TYPECHECK_GATE='block'` (session) or `[Environment]::SetEnvironmentVariable('CLAUDE_TYPECHECK_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). |
+| `CI_GATEGUARD_EXCLUDE` | Comma-separated path fragments that `hooks/gateguard.mjs` skips for Edit / Write / MultiEdit (case-insensitive substring match on the forward-slash path). Meant for a prose wiki or a generated scratch dir. The hook prints one stderr line naming the fragment whenever an exclusion fires, and a catch-all fragment such as `/` or `.` matches every path and is reported as the file gate being off. Destructive Bash is never excluded. Unset (default) changes nothing. | bash/zsh: `export CI_GATEGUARD_EXCLUDE=docs/wiki,scratch/`. PowerShell: `$env:CI_GATEGUARD_EXCLUDE='docs/wiki,scratch/'` (session). |
+| `CI_GATEGUARD_TARGET_LOCK=block` | `hooks/gateguard.mjs` refuses any Edit / Write / MultiEdit whose absolute target canonicalizes outside the session project root, before the fact gate and independent of clearance, so a wrong-repo or wrong-worktree write is denied even with perfect facts. Off by default. | bash/zsh: `export CI_GATEGUARD_TARGET_LOCK=block`. PowerShell: `$env:CI_GATEGUARD_TARGET_LOCK='block'` (session). |
+| `CI_CONFIG_GUARD` | `hooks/config-guard.mjs` (a PreToolUse hook on Bash / Edit / Write / MultiEdit / NotebookEdit) watches the files that wire the guardrails: `.claude/settings*.json`, `.mcp.json`, `hooks.json`, `.claude/hooks/`, `.claude/plugins/`, `.claude-plugin/`, and the `claude plugin\|mcp\|config` CLI forms that edit them. `warn` (default) prints one stderr line and never blocks; `block` denies the call with the reason and the bypass; `off` disables it. Reads never trigger it. One-call bypass: `CI_CONFIG_GUARD_ALLOW=true`. Fails open. | bash/zsh: `export CI_CONFIG_GUARD=block` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CI_CONFIG_GUARD='block'` (session) or `[Environment]::SetEnvironmentVariable('CI_CONFIG_GUARD','block','User')` (persistent). |
 | `CLAUDE_QUERY_COST_NUDGE=on` | `hooks/query-cost-nudge.mjs` (a `Stop` hook) guards against surprise DB bills: when the working tree has changed DB/query files (`.sql`, `.prisma`, `migrations/`, `/db/`, `schema.*`, `drizzle`) at turn end, it injects a once-per-session `additionalContext` reminder to run a D1-aware cost audit — dispatch the `database-reviewer` agent or check EXPLAIN QUERY PLAN, index coverage, N+1, and D1 `rows_read` billing before finishing. `on` enables it; default (unset) is off. Opt-in amplifier, never a gate; dedupes per session and fails open. | bash/zsh: `export CLAUDE_QUERY_COST_NUDGE=on` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CLAUDE_QUERY_COST_NUDGE='on'` (session) or `[Environment]::SetEnvironmentVariable('CLAUDE_QUERY_COST_NUDGE','on','User')` (persistent). |
 
 </details>
@@ -208,26 +257,26 @@ Shared files (`GEMINI.md`, `AGENTS.md`, `.rules`, `CONVENTIONS.md`, `copilot-ins
 
 ## Who this is for
 
-<details>
-<summary><b>Use it if you ship from real repos — skip it if you only do one-off prompts</b></summary>
-
 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
+- want the work to outlive the session: lessons from yesterday survive into today, and today's fix survives into the next engineer's week
 
 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
+- want a prompt template, not a runtime gate (`hooks/gateguard.mjs`)
 
-(The runtime gate is `hooks/gateguard.mjs`; full mechanics in [How enforcement works](#install) above.)
+Claude Code gets the full install (hooks, MCP, instincts). Other agents can still load the 7 Laws as a rules file — see [Works with other agents](#install).
 
-</details>
+---
+
+## What leaves your machine
+
+Nothing. Observations (`observations.jsonl`) and instincts live under `~/.claude/instincts/` and are never uploaded. The npx installer makes one throttled, fail-open read of the public npm registry to print a newer-version notice; `CLAUDE_CI_UPDATE_CHECK=off` silences it. No telemetry. Raw observation rows can contain command heads and file paths, so review them before you share an export — see [SECURITY.md](SECURITY.md).
 
 ---
 
@@ -243,7 +292,7 @@ You have used Claude Code (or any agentic coding tool) long enough to recognize
 | 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) |
+| 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), [`gateguard`](skills/gateguard.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.
@@ -257,7 +306,7 @@ Three of those alignment + reflection skills (`grill-me`, `grill-with-docs`, `ha
 <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.
+Hooks capture every tool call silently. When you run `/seven-laws` (or `/harvest`, `/distill`) 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+. What runs in code today: `ci_reinforce` adds 0.15 on an accepted suggestion and cuts 0.1 on a correction, and `/harvest` weights recurring friction by recency. The confirm, decay, and cross-project promotion rules in [SKILL.md](SKILL.md) are instructions the model applies during analysis, not a background process. Nothing forms until you close the loop.
 
 <p align="center">
   <img src="assets/diagram-mulahazah-learning.jpg" alt="Mulahazah pipeline" width="820" />
@@ -314,7 +363,7 @@ All 29 legacy commands ship in the marketplace bundle. The marketplace Beginner
 
 ## Skills
 
-The plugin ships **29 skills** — 1 core + 1 featured + 7 tier-1 + 17 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. The tier-1 `ship` skill is the single source for the `/ship` workflow and the npm installer makes it global across Claude Code projects. Full catalog with per-skill descriptions, Law tagging, and drop-in single-file install: [docs/skills.md](docs/skills.md). Adding a 30th skill: [CONTRIBUTING.md § Evolution — adding a new skill](CONTRIBUTING.md#evolution--adding-a-new-skill).
+The plugin ships **28 skills** — 1 core + 1 featured + 7 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. The tier-1 `ship` skill is the single source for the `/ship` workflow and the npm installer makes it global across Claude Code projects. Full catalog with per-skill descriptions, Law tagging, and drop-in single-file install: [docs/skills.md](docs/skills.md). Adding a 29th skill: [CONTRIBUTING.md § Evolution — adding a new skill](CONTRIBUTING.md#evolution--adding-a-new-skill).
 
 ---
 
@@ -357,11 +406,15 @@ Proof-format templates ship in [templates/](templates/): `release_receipt_templa
 
 - [QUICKSTART.md](QUICKSTART.md) — 2-minute setup
 - [SKILL.md](SKILL.md) — full 7 Laws spec
-- [docs/skills.md](docs/skills.md) — full 29-skill catalog
+- [skills/model-forward.md](skills/model-forward.md) — what stays valuable as models improve
+- [docs/skills.md](docs/skills.md) — full 28-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
+- [docs/philosophy.md](docs/philosophy.md) — the one sentence the product is built on, with sources and the mapping to each Law
+- [CHANGELOG.md](CHANGELOG.md) — what changed in each release
 - [SECURITY.md](SECURITY.md)
+- Found a bug? [Open an issue](https://github.com/naimkatiman/continuous-improvement/issues) with the one-line output of `/verify-install`
 
 <details>
 <summary><b>Uninstall · the brand stack · in the wild</b></summary>
@@ -381,7 +434,7 @@ One product, three names. Use the one that fits the audience:
 | Layer | Name | When you say it |
 |-------|------|-----------------|
 | **Brand** | The 7 Laws of AI Agent Discipline | Tweets, talks, docs, "what is this" |
-| **Engine** | Mulahazah | The auto-leveling instinct system inside it |
+| **Engine** | Mulahazah | Arabic for observation. The engine watches every tool call; the confidence ledger keeps the account (suggest at 0.5, apply at 0.7, corrections cut). Taking account of yourself is *muhasabah*, the reason the engine exists: [docs/philosophy.md](docs/philosophy.md) |
 | **Package** | `continuous-improvement` | `npm install`, `/plugin install`, `settings.json` |
 
 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.

package/SKILL.md

@@ -42,6 +42,8 @@ Before executing, state:
 - Build passes
 - You can explain what changed in one sentence
 
+"Done" is an audit, not a hope: settle the actual result against the Verification you stipulated in Law 2.
+
 ## Law 5: Reflect After Every Session
 
 After non-trivial tasks:
@@ -59,6 +61,8 @@ After non-trivial tasks:
 
 The "Rule to add" field feeds Law 7 — it becomes an instinct with 0.6 starting confidence.
 
+This block is the ledger: what worked and what failed are the session's gains and losses; the rule to add is what you carry into the session you will not be in.
+
 The "Iteration — Next best recommendations" field feeds Law 6. List the **top 3 ranked** core-development moves based on the current code state — what to build, fix, refactor, or investigate next so the feature/system advances. Item #1 is the strongest recommendation; #2 and #3 are alternative directions the user can pick from. NOT git plumbing (commit, push, PR), NOT pure CI ceremony (run tests, type-check), NOT deploy steps. Those belong in the end-of-run summary, not here.
 
 Format per item: `<verb> <object at path:line> (<why, one clause grounded in current context>)`.

package/bin/check-invariant-count.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * Invariant Count Check
+ *
+ * `CLAUDE.md` and `AGENTS.md` tell an agent, as a hard instruction, to run
+ * `npm run verify:all` and state how many invariants that is plus the full
+ * ordered list. `docs/RELEASING.md` states the count in its release checklist.
+ * All three are hand-maintained prose, and all three drifted: on 2026-09-06
+ * CLAUDE.md and RELEASING.md said 16 against an actual 17, and AGENTS.md — the
+ * file Codex reads as its contract — said **12** and listed an incomplete set,
+ * having missed skill-count-prose, command-count, landing-version and
+ * reconcile-parity entirely.
+ *
+ * That is worse than a stale number. An agent told "12 invariants" that sees 17
+ * OK lines has no way to know whether it ran too much or the doc is wrong, and
+ * an agent reading the list as authoritative will not notice an invariant it was
+ * never told about.
+ *
+ * Source of truth: the `verify:all` script in package.json. Everything before
+ * the first non-`verify:` step is a content invariant; the rest (today just
+ * `typecheck`) is the trailing tail the docs name after the colon. Derived, not
+ * hardcoded, so adding an invariant to the chain is the only edit needed to make
+ * this check demand the docs follow.
+ *
+ * Two claim shapes are recognised:
+ *   long  — "(17 content invariants + typecheck: a, b, …, typecheck)"  count + ordered names
+ *   short — "(17 invariants + typecheck)"                              count only
+ *
+ * Fail-closed: a scanned file with no claim at all is a violation, not a pass.
+ *
+ * Usage:
+ *   node bin/check-invariant-count.mjs              # Check the current repo
+ *   node bin/check-invariant-count.mjs <repo-root>  # Check a specific repo root
+ *
+ * Exit codes:
+ *   0 — every claim matches the verify:all chain
+ *   1 — a count is stale, a name list is wrong or out of order, or a file states none
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { argv, cwd, exit } from "node:process";
+/** Files that carry a verify:all claim. Explicit, so dropping one is deliberate. */
+export const CLAIM_FILES = ["CLAUDE.md", "AGENTS.md", join("docs", "RELEASING.md")];
+const LONG_RE = /\((\d+) content invariants \+ typecheck:\s*([^)]+)\)/g;
+const SHORT_RE = /\((\d+) invariants \+ typecheck\)/g;
+/** Split the verify:all chain into `verify:*` invariants and the trailing steps. */
+export function parseVerifyAllChain(chainScript) {
+    const steps = [...chainScript.matchAll(/npm run ([A-Za-z0-9:_-]+)/g)].map((m) => m[1]);
+    const invariants = [];
+    const trailing = [];
+    for (const step of steps) {
+        if (step.startsWith("verify:"))
+            invariants.push(step.slice("verify:".length));
+        else
+            trailing.push(step);
+    }
+    return { invariants, trailing };
+}
+export function parseClaims(content) {
+    const claims = [];
+    for (const m of content.matchAll(LONG_RE)) {
+        claims.push({
+            count: Number(m[1]),
+            names: m[2].split(",").map((s) => s.trim()).filter(Boolean),
+        });
+    }
+    for (const m of content.matchAll(SHORT_RE)) {
+        claims.push({ count: Number(m[1]), names: null });
+    }
+    return claims;
+}
+export function findViolations(chain, claimsByFile) {
+    const violations = [];
+    const expectedCount = chain.invariants.length;
+    const expectedNames = [...chain.invariants, ...chain.trailing];
+    for (const [file, claims] of Object.entries(claimsByFile)) {
+        if (claims.length === 0) {
+            violations.push(`${file}: states no "verify:all" invariant-count claim. Expected "(${expectedCount} invariants + typecheck)" or the long form with the full list.`);
+            continue;
+        }
+        for (const claim of claims) {
+            if (claim.count !== expectedCount) {
+                violations.push(`${file}: claims ${claim.count} invariants but verify:all runs ${expectedCount}.`);
+            }
+            if (claim.names === null)
+                continue;
+            if (claim.names.length !== expectedNames.length) {
+                const missing = expectedNames.filter((n) => !claim.names.includes(n));
+                const extra = claim.names.filter((n) => !expectedNames.includes(n));
+                violations.push(`${file}: the listed steps do not match verify:all.` +
+                    (missing.length ? ` Missing: ${missing.join(", ")}.` : "") +
+                    (extra.length ? ` Not in the chain: ${extra.join(", ")}.` : ""));
+            }
+            else if (claim.names.some((n, i) => n !== expectedNames[i])) {
+                violations.push(`${file}: the listed steps are out of order. Expected the chain order: ${expectedNames.join(", ")}.`);
+            }
+        }
+    }
+    return violations;
+}
+export function checkInvariantCount(repoRoot) {
+    const pkgRaw = readFileSync(join(repoRoot, "package.json"), "utf8");
+    const pkg = JSON.parse(pkgRaw);
+    const chainScript = pkg.scripts?.["verify:all"];
+    if (typeof chainScript !== "string" || chainScript.length === 0) {
+        return {
+            chain: { invariants: [], trailing: [] },
+            violations: [`package.json has no "verify:all" script, so no claim can be checked.`],
+        };
+    }
+    const chain = parseVerifyAllChain(chainScript);
+    const claimsByFile = {};
+    for (const rel of CLAIM_FILES) {
+        let content;
+        try {
+            content = readFileSync(join(repoRoot, rel), "utf8");
+        }
+        catch {
+            claimsByFile[rel] = [];
+            continue;
+        }
+        claimsByFile[rel] = parseClaims(content);
+    }
+    return { chain, violations: findViolations(chain, claimsByFile) };
+}
+function main() {
+    const repoRoot = argv[2] ?? cwd();
+    const { chain, violations } = checkInvariantCount(repoRoot);
+    if (violations.length === 0) {
+        console.log(`OK invariant-count: all ${CLAIM_FILES.length} doc surface(s) state ${chain.invariants.length} invariants + ${chain.trailing.join(", ")}, matching the verify:all chain.`);
+        exit(0);
+    }
+    console.error(`FAIL invariant-count: ${violations.length} stale claim(s) about verify:all.\n`);
+    for (const v of violations)
+        console.error(`  ${v}`);
+    console.error(`\nFix: verify:all currently runs ${chain.invariants.length} invariants — ` +
+        `${[...chain.invariants, ...chain.trailing].join(", ")}. ` +
+        `Update the claim in each file above to match. The chain in package.json is the source of truth.`);
+    exit(1);
+}
+const invokedDirectly = argv[1] !== undefined && import.meta.url.endsWith(argv[1].replace(/\\/g, "/"));
+if (invokedDirectly || argv[1]?.endsWith("check-invariant-count.mjs")) {
+    main();
+}