# CLAUDE.md — continuous-improvement

Project-local rules for AI coding agents. Global rules live in `~/.claude/CLAUDE.md`. This file only adds what is *specific to this repo*.

## Repository

- npm package `continuous-improvement` (Claude Code plugin + GitHub Action transcript linter)
- Marketplace at `.claude-plugin/marketplace.json` ships 5 plugins: 1 native + 4 vendored companions (Obra superpowers, addy/agent-skills, ruflo-swarm, oh-my-claudecode). pm-skills is out-of-band per [docs/THIRD_PARTY.md](docs/THIRD_PARTY.md).
- Source layout: `skills/`, `commands/`, `hooks/`, `agents/`, `bin/`, `lib/`, `templates/`, `instinct-packs/`, `synthetic-checks/`, `third-party/`, `plugins/continuous-improvement/`.

## Think Before Acting

- For any non-trivial request, produce a short plan before editing files. Under the 7 Laws this is Law 2.
- When the user references prior work (`PR #X`, `last session's fix`), verify it exists with `gh pr view X` or `git log` before acting on the assumption.
- Use TDD for new features: failing test → code → verify. The native [tdd-workflow](skills/tdd-workflow.md) skill enforces RED-GREEN-REFACTOR strictly — pre-test code is deleted.

## Verification Discipline

- After any code change, run `npm run verify:all` (17 content invariants + typecheck: skill-mirror, skill-tiers, skill-law-tag, skill-count, skill-count-prose, command-count, test-count, docs-substrings, everything-mirror, routing-targets, doc-runtime-claims, test-imports-only, landing-version, scripts-citation-drift, third-party-shape, tool-count, reconcile-parity, typecheck). Anything below that is incomplete.
- For doc-only or template-only changes, `npm run typecheck` is the floor.
- Run all commands from repo root. Verify CWD with `pwd` if a previous step may have changed it.
- Never claim "verified" or "done" without the passing output. Silence is not a pass.

## Build pipeline (CRITICAL)

- `.mts` files under `src/` are the source. `.mjs` files in `bin/`, `lib/`, `test/` are **generated by `tsc`**.
- Direct edits to `.mjs` files are **wiped on next `npm run build`** and fail CI's `git diff --exit-code -- bin test lib plugins` invariant. PR #66 was rejected for exactly this; PRs #73/#74 shipped the fix.
- After editing `.mts`: `npm run build` regenerates the `.mjs`. Commit both.

## Environment Notes (Windows + Git Bash + PowerShell)

- Shell is Git Bash on Windows. `jq` is not installed — use Node, PowerShell, or vendored helpers for JSON parsing.
- `autocrlf=true` produces 40+ phantom modifications on `git status` after a clean checkout. **Never** stage with `git add .` or `git add -A`. Stage by explicit filename. Use `git diff --stat` (not `git status`) to see real content drift.
- CLAUDE.md is case-sensitive on the filesystem when checked into Git. Always uppercase.

## Git & Release Workflow

- **Never push directly to `main`.** Every change — including doc-only, lockfile-only, release commits — goes through a feature branch + PR. The PR flow is mandatory and the harness has historically caught direct-push attempts.
- After merge, fast-forward `main`: `git switch main && git pull --ff-only origin main`. Squash-merge is the default (`gh pr merge <N> --squash --delete-branch`).
- `git push --force-with-lease` and `git reset --hard origin/X` are gated. If a rebase diverges, supersede via a new branch + new PR — do not force-recover.
- Release trains are vulnerable to **auto-merge ordering hazards**: GitHub orders by CI-completion time, not PR number. A release PR can land before its dependency lockfile/refactor PR and leave a stale base. When chaining release PRs, gate the release on the lockfile PR completing first.

## third-party vendoring contract

- The 5 vendored companions (`third-party/superpowers/`, `third-party/addy-agent-skills/`, `third-party/ruflo-swarm/`, `third-party/oh-my-claudecode/`, `third-party/mattpocock-skills/`) are **pinned-SHA snapshots**.
- Each snapshot must carry `MANIFEST.md` (SHA + version), `OUR_NOTES.md` (drift radar + integration scope), `CLAUDE.md` (read-only guard).
- To refresh a snapshot: `node bin/refresh-third-party.mjs <name>` from a worktree off `origin/main`.
- Never edit files inside `third-party/<name>/` directly — those are verbatim upstream copies. Cross-cutting integration code lives outside the snapshot.

## Single source of truth

- Exactly one `CLAUDE.md` at repo root (this file). Do not create `claude.md` (lowercase) — Windows treats them as the same file but Git treats them as distinct.
- Plugin manifests at `.claude-plugin/marketplace.json` and `plugins/continuous-improvement/.claude-plugin/plugin.json` are **generated** by `bin/generate-plugin-manifests.mjs`. Source is `package.json` + `marketplace.json` plus discovery walk.

## Past Mistakes → [docs/past-mistakes.md](docs/past-mistakes.md)

Ask `recall` first — it searches the observation log across all sessions and finds matching past failures without anyone having curated them. The doc is the curated subset: each mistake paired with the invariant that now enforces it. Newest entry 2026-08-07 (`safety-guard` claimed enforcement it never shipped).

## Deferred → [docs/deferred.md](docs/deferred.md)

⚠️ Logged, not dropped. Open items: `token-budget-advisor` / `strategic-compact` / `handoff` / `superpowers` retirement decisions, and the `skill-distill` empty-verify-output data-model call.

## Companion skills (enforce these rules at the tool boundary)

| Rule | Enforcing skill |
|---|---|
| Think Before Acting | [gateguard](skills/gateguard.md) — blocks Edit/Write/Bash before grounding; `CI_GATEGUARD_TARGET_LOCK=block` also refuses writes outside the project root |
| Verification Discipline | [verification-loop](skills/verification-loop.md) — per-project ladder via `templates/verify-ladder.example.json`; `hooks/typecheck-stop.mjs` — opt-in Stop-boundary typecheck gate (off by default; `CLAUDE_TYPECHECK_GATE=block` re-prompts the model with tsc failures) |
| Build pipeline | `bin/check-everything-mirror.mjs` + `verify:generated` script |
| 7 Laws routing | [proceed-with-the-recommendation](skills/proceed-with-the-recommendation.md) — walks recommendation lists under all 7 Laws |
| Recommendation shape | [wild-risa-balance](skills/wild-risa-balance.md) — 5+2 floor + R-I-S-A filter |
| Goal-Driven Execution | [goal-monitor](skills/goal-monitor.md) + `hooks/goal-drift-stop.mjs` — Stop-boundary drift gate (warn by default; `CLAUDE_GOAL_DRIFT_GATE=block` enforces) |

CLAUDE.md text tells humans the rule. Skills make the agent obey it. Keep both layers.