From 7a87112aa45df42ff01b0d2e89382da016baae1b Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Wed, 16 Sep 2026 15:42:24 +0100
Subject: [PATCH 01/24] docs(cw-plugin): add design + research artifacts

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .gitattributes                                |   1 +
 .../plans/cw-plugin/cw-plugin-design-draft.md | 535 ++++++++++++++++++
 .../cw-plugin-research-bestpractices.md       |  15 +
 .../cw-plugin/cw-plugin-research-codebase.md  | 131 +++++
 .../cw-plugin/cw-plugin-research-docs.md      | 101 ++++
 docs/plans/cw-plugin/cw-plugin-tasks.md       | 141 +++++
 6 files changed, 924 insertions(+)
 create mode 100644 .gitattributes
 create mode 100644 docs/plans/cw-plugin/cw-plugin-design-draft.md
 create mode 100644 docs/plans/cw-plugin/cw-plugin-research-bestpractices.md
 create mode 100644 docs/plans/cw-plugin/cw-plugin-research-codebase.md
 create mode 100644 docs/plans/cw-plugin/cw-plugin-research-docs.md
 create mode 100644 docs/plans/cw-plugin/cw-plugin-tasks.md

diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..5a88ee3
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1 @@
+docs/plans/** linguist-generated=true
diff --git a/docs/plans/cw-plugin/cw-plugin-design-draft.md b/docs/plans/cw-plugin/cw-plugin-design-draft.md
new file mode 100644
index 0000000..3b6b201
--- /dev/null
+++ b/docs/plans/cw-plugin/cw-plugin-design-draft.md
@@ -0,0 +1,535 @@
+# cw-plugin — /design artifact set (single-file form while in plan mode)
+
+Slug `cw-plugin`. Plan mode allows exactly one writable file, so the five artifacts live here as
+sections. At Step 6 the `/design` session itself splits them, by section, into five named
+files under `<repo>/docs/plans/cw-plugin/`: `cw-plugin-research-codebase.md` (§R1),
+`cw-plugin-research-docs.md` (§R2), `cw-plugin-research-bestpractices.md` (§R3),
+`cw-plugin-design-draft.md` (§D) and `cw-plugin-tasks.md` (§T); `/build` commits them. The
+live `/design` skill's routing rule would keep workflow designs about this repo local; the
+maintainer's instruction of 2026-09-16 overrides it for this set (these files carry no
+personal information), and the session executing Step 6 follows the instruction, not the
+rule. P0 verifies the five files are present before `/build`.
+
+Lineage: plan B of the 2026-09-16 split of a private predecessor design (rev 8.1). Plan A
+(the maintainer's private profiles design) follows and links the published plugin. Scrub rule for every section: no absolute home paths (write `~/...`), no employer or
+client names, no organisation ids, no private folder layouts or private design slugs; the repo
+owner is "the maintainer", adopters are "the user"; the maintainer's name appears in this set
+only through a check that derives it from `LICENSE` at run time.
+
+---
+
+## §D Design draft — cw-plugin rev 2
+
+### D0 Revision log and review status
+Risk: high (rewrites the workflow this repo's own build and ship depend on).
+Rev 1 (2026-09-16) derived from the private predecessor design rev 8.1 (§D2.1–D2.4, D2.7,
+D2.10; tasks T1–T6, T12) with the 2026-09-16 decisions applied (prefix `cw`; auto-updates on,
+so no symlink mitigation; five-line CLAUDE.md with two imports; stack preferences move to
+project CLAUDE.md files; Chrome not enabled by default; no subagent caps) and the non-blocking
+findings of the PR #2 review folded (the `git clean` grant, the README reinstall claim, the
+undocumented `.gitattributes` line, the unused `docs/research` allowlist, the NotebookEdit
+refusal — all vanish with the rewrite). Research deltas folded before review: plugin agents
+ignore `mcpServers`, `hooks` and `permissionMode` (§R2.7); no `if` on the safety hooks (§R3
+row 6); profile-check never exits 2 (§R2.5); `disallowed-tools` on `/cw:build` replaces the
+delegate guard (§R2.6, §R3 row 7); marketplace name distinct from the plugin name (§R3 row 4);
+`claude plugin validate` in CI (§R3 row 5).
+Rev 2 (2026-09-16) after review round 1 (direction PASS with advisories; design-reviewer
+NO_VERDICT once, re-nudged; completeness NEEDS_WORK). Verified and folded: the scrub check
+would have matched the committed artifacts (the name is now derived from `LICENSE` at check
+time); P0 lacked the artifact write and forbade it with a clean-tree check (Step 6 of `/design`
+writes the set; the check tolerates it); `disallowed-tools` is scoped to the invoking turn
+(stated; follow-ups re-invoke the skill; binding verified at P0); the live `/build` has no
+`continue` branch (resume and fix-ups restated); the live `/ship` gate needs a project
+CLAUDE.md test line (CLAUDE.md becomes this repo's project file); jq absence would brick
+sessions (hooks fail open with a warning); no main-push opt-out (`CW_ALLOW_MAIN_PUSH=1`);
+implementer loses `acceptEdits` (documented requirement); rules delivery on the marketplace
+path (documented); migration for installer users (README); `settings-keys.txt` moves to T6;
+`scan --report`; fixture contract; haiku pin check; per-skill `allowed-tools`; `-w` greps;
+root-anchored probes; a zero-count cluster leaves the dedupe list (16 phrases); kill switch;
+profile-check edge cases; description cap; post-merge install check; pattern-file sanity;
+allowlist for the build session; the allowlist narrowed to `docs/plans/cw-plugin/`; the cut
+line. Deviations from rev 8.1, each a judgment call: the transcript-secret scanner leaves for
+plan A (replaced by the generic `run.sh scan`, which also works outside git trees); the stale
+private mirror is deleted at P0 and the `docs/plans` allowlist narrowed instead of ignored by
+name; the template CLAUDE.md becomes a project CLAUDE.md; the release task is numbered T7.
+Accepted risks (logged): `cw:google-workspace` stays in 1.0.0 (requested; a hold for 1.1 is the
+maintainer's call at the checkpoint); `profile-check.sh` stays in the plugin (requested; its
+user-visible channel is verified at P0); the CI `validate` step costs one minute per push; CI
+is red between the T1 and T2 commits.
+Round 2 (higher evidence bar; direction PASS with two advisories, design-reviewer NEEDS_WORK
+on two verified majors, completeness NEEDS_WORK on one critical and three majors, all
+verified and folded; a third round is not run, per the anti-ratchet rule): folded — Step 6
+of `/design` (this session) writes the five named files under the maintainer's override of
+the skill's carve-out and P0 counts them; each dedupe cluster has one named home (D2.2 table)
+and the stack-preference cluster leaves the prompts; the jq-absent case runs with a scratch
+bin that lacks jq; the project CLAUDE.md carries the commit conventions; the shell-wide main-push opt-out dropped (the kill switch
+serves that case; a variable would silently follow the maintainer across profiles); the
+allowlist admits `docs/plans/*.md` so future single-file designs in this repo are tracked,
+`/cw:design` names the fix when a destination is ignored, the project CLAUDE.md states the
+convention, and `run.sh all` scans tracked files whenever the private pattern file is set;
+`run.sh scan` uses `git grep --untracked` so new files are scanned before their commit, and
+index-dependent clauses are marked "(after the commit)"; the build skill's allowed-tools
+check uses a portable pattern; no agent keeps a `skills:` preload; the G-load fixture is
+copied into the scratch repo as `docs/plans/two-task.md`; plan A's slug left the header; P0
+confirms the stale mirror is untracked, pre-approves the remaining verification commands,
+and its probe also checks that a subagent can still write while `disallowed-tools` is active;
+private paths left P0 (the pattern file is `<pattern file>`); loops in verifications became
+single commands; the README no longer mentions the legacy `.gitattributes` marker. Review
+status: converged after two rounds with every verified critical folded; the unverified
+items (whether `claude plugin list` runs non-interactively under a scratch config dir — the
+2026-09-15 probe says yes —, `plugin details` output shape, `memory: project` in plugin
+agents) are checked at T1 and G-load.
+P0 probe answers (2026-09-16, print mode with `--plugin-dir`, edits pre-approved): (1) the
+SessionStart hook's `systemMessage` arrived in the session stream as a `system/hook_response`
+event; (2) `disallowed-tools: Write, Edit` on an inline skill bound — the orchestrator's Write
+was denied at call time; (3) it also propagated — a subagent spawned in that turn had no Write
+tool at all ("Write is disabled for this session, in subagents as well as here"). Consequence
+applied: `/cw:build` carries no `disallowed-tools`; its delegation boundary is the one-sentence
+rule plus the review gate (D2.5, D5).
+
+### D1 Context
+The maintainer's Claude Code coding workflow (five skills, five agents, five hooks, rules, a
+manifest installer with merge scripts and bats suites) was written for Opus 4.8 and now runs
+under Fable 5.1, for which Anthropic recommends fewer, plainer instructions (§R3 row 1). The
+same files exist in two divergent copies (the live profile and this repo, whose latest port is
+PR #2). The maintainer needs one copy of the workflow shared by several Claude Code profiles
+(config dirs), never per-profile copies, and wants the repo published in a state anyone can
+adopt. Outcome of this plan: the repo IS a Claude Code plugin named `cw` — one checkout, loaded
+in place by every profile through a `skills/cw` symlink, or installed from the repo's own
+marketplace by adopters — with lean prompts, two safety hooks plus a profile check, one test
+runner, CI, and no personal information anywhere. Profile setup (settings parity, MCP policy,
+logins, symlinks) is plan A and out of scope here.
+
+### D2 Approach
+
+D2.1 The repo is the plugin `cw`. Add `.claude-plugin/plugin.json` (`name: cw`, `version:
+1.0.0`, description, `author.name` = the maintainer's public GitHub display name, `repository`
+= the public repo URL, `license: MIT`, keywords) and `.claude-plugin/marketplace.json`
+(marketplace `claude-code-setup` — distinct from the plugin name, §R3 row 4 — with one plugin
+entry `cw`, `source: "./"`), keep `skills/`, `agents/`, `hooks/`, `rules/`. Published identity,
+deliberate and confirmed at the checkpoint: the maintainer's display name in `LICENSE` and
+`plugin.json`, the GitHub handle in repository URLs; nowhere else. Three load paths, all
+documented in the README: (a) in place — `ln -s <checkout> <config dir>/skills/cw` →
+`cw@skills-dir`, SKILL.md edits live, agents and hooks after `/reload-plugins`; the
+maintainer's path and the live-edit path, the least robust one (§R3 row 8), with the
+real-directory fallback beside it (move the checkout under `skills/cw`, symlink back for
+editing); (b) marketplace — `claude plugin marketplace add <owner>/claude-code-setup && claude
+plugin install cw@claude-code-setup` (a copy in the plugin cache, updated with `claude plugin
+update`; the reliable path for adopters); (c) trial — `claude --plugin-dir <checkout>`.
+Commands `/cw:design`, `/cw:build`, `/cw:ship`, `/cw:compound`, `/cw:search`,
+`/cw:google-workspace` (none collides with a built-in command, §R2.6); agents
+`cw:implementer`, `cw:reviewer`, `cw:researcher`, `cw:design-reviewer`,
+`cw:direction-reviewer`; hooks self-register through `hooks/hooks.json`. Model invocation:
+design, search and google-workspace keep trigger phrases in `description` (or `when_to_use`)
+and may be invoked by Claude; build, ship and compound keep `disable-model-invocation: true`.
+The custom Explore agent is retired (a plugin cannot override the built-in; every Explore
+call passes `model: haiku`). The installer, merge scripts, manifest, bats suites, `/setup`
+skill and the CLAUDE.md template are retired; `CLAUDE.md` becomes this repo's own project
+file (≤20 lines: what the repo is, `Tests: bash tests/run.sh all`, the commit conventions an
+outside contributor needs — Conventional Commits and the `Co-Authored-By: Claude
+<noreply@anthropic.com>` trailer, which the live `/build` and `/ship` read from the project
+CLAUDE.md —, and the design-document rule of this repo: single-file designs `docs/plans/<slug>.md` are tracked;
+a folder-style set needs its own `!docs/plans/<slug>/` allowlist lines before `/cw:build`) —
+the project CLAUDE.md of a plugin repo is read when working in the repo, not by the plugin's
+users.
+Rules: `rules/workflow.md` (≤40 lines) and `rules/orchestration.md` (≤60 lines) are imported
+by each profile's CLAUDE.md by absolute path — the README shows the five-line CLAUDE.md (one
+identity line, a `Profile: <name>` line, the two `@` lines), says stack preferences belong in
+project CLAUDE.md files, and states the import path per install mode (the checkout for (a);
+for (b) the install path that `claude plugin details cw@claude-code-setup` prints, which
+changes on update — or a separate clone kept for the rules; for (c) the checkout). A checkout
+linked in place is the running workflow: edits on a branch are live at once (the intended
+local proof); the checkout normally sits on `main`. Unsourced judgment: the two-rule-file
+split.
+
+D2.2 Lean-cut (§R3 row 1). Base copies: agents and the skills design, build, ship, compound,
+search from the REPO at `main` after PR #2, carrying the live-ahead items of §R1.3 (the
+`continue` hint and behaviour, the template allowlist, the anti-ratchet section);
+`rules/orchestration.md` from LIVE; the two protect hooks from LIVE plus the repo's jq check
+and minus the machine-specific exemption and the personal comment. Delete: emphatic capitals,
+model-workaround lines, worker self-verification nudges, duplicated rules, sentinel
+choreography and guard references, the plans-dir promotion machinery, the `.gitattributes`
+write, the `git clean` grant, the maintainer's first name (prompts address "the user"; the
+check derives the name from `LICENSE`). Keep: rationale, scope boundaries, project facts, the
+JSON verdict contracts, the review-loop structure (reviewers report every finding; severity
+filtering is the orchestrator's separate pass), the `model: haiku` pin on Explore calls.
+Reviewer prompts may stay checklist-shaped. Fifteen rule clusters, each surviving in exactly
+one prompt home (phrases in `tests/dedupe-phrases.txt`), with the home assigned here — an
+operational rule lives in the skill that executes it, a policy every commit or session
+inherits lives in `rules/`, and the hooks enforce the hard ones regardless of imports:
+| Cluster | Home |
+|---|---|
+| never push main | ship (`rules/workflow.md` says "feature branches only" instead) |
+| one atomic commit per task | build |
+| co-author trailer (`Co-Authored-By`) | `rules/workflow.md` (build refers to "the trailer the workflow rules define") |
+| PR only after the gate | ship |
+| NO_VERDICT handling | `rules/orchestration.md` |
+| ground truth over testimony | `rules/orchestration.md` |
+| fresh-context counter-model reviewer | `rules/orchestration.md` |
+| same-turn spawn | `rules/orchestration.md` |
+| root-anchored check-ignore | design |
+| search-source detection | search |
+| three-angle methodology | search |
+| two checkpoints | `rules/workflow.md` |
+| explicit model per Agent call | `rules/orchestration.md` |
+| context7 before APIs | `rules/workflow.md` |
+| `/compound` never commits | compound |
+Two former clusters leave the prompts entirely and are enforced by the categorical grep of
+D6.4: sentinel choreography, and "functions under 50 lines" (a stack preference, which the
+2026-09-16 decision moves to project CLAUDE.md files). Mechanical gates: every agent and rules file and the
+skills search, compound, google-workspace ≤150 lines; the two orchestration skills design and
+build ≤200 (they carry procedures and the verdict contracts; an implementer that cannot fit a
+kept item reports the conflict rather than dropping it); `WORKFLOW.md` ≤200; each skill's
+`description` plus `when_to_use` ≤1,536 characters (§R2.6); `tests/run.sh dedupe` finds each
+phrase at most once across `skills/`, `agents/`, `rules/`; bytes of `skills/**/SKILL.md` +
+`agents/*.md` + `rules/*.md` reported against the baseline 73,738 (the old set: five skills,
+six agents, one rules file; the new set has six, five and two — a coarse gauge, reported not
+gated) with a target of ≤60% and a hard fail only above 100%. Rollback: revert the lean-cut
+commits (one per file group).
+
+D2.3 Model and effort matrix (aliases only; unsupported effort clamps silently):
+| Role | model | effort | maxTurns |
+|---|---|---|---|
+| Session orchestrator (`/cw:design` frontmatter) | inherits | `effort: xhigh` on design only | — |
+| Explore (built-in, called with `model: haiku`) | `haiku` | none | — |
+| cw:researcher | `sonnet` | `medium` | 30 |
+| cw:implementer | `sonnet`; a task may set `opus` | `high` | 50 |
+| cw:reviewer | `opus`; `risk: trivial` tasks may set `sonnet` | `high` | 20 |
+| cw:design-reviewer | `opus` | `high` | 25 |
+| cw:direction-reviewer | `opus` | `xhigh` | 15 |
+| compound worker (inside `/cw:compound`) | `sonnet` | `medium` | — |
+`tools:` allowlists (the researcher's names the exa and context7 tools it may use; MCP
+access comes from the session), no `disallowedTools`, and none of `permissionMode`,
+`mcpServers`, `hooks` (ignored in plugin agents, §R2.7); the three reviewers keep
+`memory: project` (not listed among the ignored fields, not documented as honoured either —
+checked at G-load); `cw:reviewer` adopts the JSON verdict schema `/cw:build` expects; no
+agent carries a `skills:` preload (the researcher and the design-reviewer invoke `cw:search`
+through the Skill tool when they need it; a preload by bare name is not known to resolve to a
+plugin skill). Consequence of the dropped `permissionMode`:
+`cw:implementer` cannot self-grant `acceptEdits`, so `/cw:build` expects a session in auto
+mode or `--permission-mode acceptEdits` (README requirement; the maintainer runs auto mode).
+No subagent caps.
+
+D2.4 Hooks (all in `hooks/hooks.json`, commands `bash "${CLAUDE_PLUGIN_ROOT}/hooks/<script>"`,
+timeouts 10 s, no `if` field anywhere — `if` fails open on chained or unparseable commands,
+§R3 row 6). Every script starts with the jq check: when `jq` is missing it prints `cw: jq not
+found, hook skipped` to stderr and exits 0 (fail open with a visible warning rather than
+blocking every tool call; jq is a stated requirement in the README).
+- PreToolUse, matcher `Bash` → `protect-branches.sh` (LIVE base, exemption removed): splits
+  `tool_input.command` on `&&`, `||`, `;`, `|` and newlines, tokenises each segment (env
+  assignments and git global options skipped), and blocks with exit 2 any segment that is a
+  `git push` to a main/master destination (explicit refspec, or the current branch when no
+  refspec is given) or that carries `--force`/`-f`; everything else exits 0. No opt-out
+  switch (a shell-wide variable would silently follow the maintainer across profiles): a repo
+  that pushes to main by convention uses the kill switch below or removes the entry from
+  `hooks/hooks.json` in its fork; documented in the README.
+- PreToolUse, matcher `Write|Edit|MultiEdit|NotebookEdit` → `protect-secrets.sh` (LIVE base
+  incl. the template allowlist, which applies only after the directory checks — a
+  `.env.example` under `secrets/`, `.ssh/` or `.aws/` stays blocked; reads `file_path //
+  filePath // notebook_path`; empty path → allow).
+- SessionStart, matcher `startup|resume|clear|fork` → `profile-check.sh`, which always exits 0
+  (exit 2 would block session initialisation, §R2.5) and always prints the JSON context line:
+  reads `$HOME/.claude-profiles` (private, `<folder prefix>|<config dir>` per line, `#`
+  comments and malformed lines skipped, `~` expanded; an absent file means no profile
+  notices, not no output); longest-prefix match of the hook's `cwd`; collects notices —
+  `wrong profile: <cwd> maps to <dir>` when the mapped config dir differs from
+  `${CLAUDE_CONFIG_DIR:-$HOME/.claude}` (both realpath'd), `missing import: <path>` for each
+  `@` line of the active config dir's CLAUDE.md (lines starting with `@`; targets `~`-expanded,
+  absolute as is, relative resolved against the config dir) whose target is missing; prints
+  JSON `{"systemMessage": "<notices joined by '; '>", "hookSpecificOutput": {"hookEventName":
+  "SessionStart", "additionalContext": "<the same text>"}}` when there are notices, otherwise
+  `additionalContext` = `profile <basename of the config dir> · plugin cw` and no
+  `systemMessage`. Claude sees the context either way; the P0 probe showed the `systemMessage` delivered to
+  the session's system stream as a hook response (G-load records how the TUI renders it).
+Two events, three commands. Kill switch, documented: `claude plugin disable cw@skills-dir`
+(or `cw@claude-code-setup`) turns every hook off at once. Deleted: orchestrator-delegate-guard,
+design-scope-guard, syntax-check (and every settings registration of them, which is plan A's
+side; adopters of the old installer unregister theirs per the README migration section,
+since a plugin hook and a settings hook both fire, §R2.5). No compact-time re-injection
+(user-scope CLAUDE.md reloads after compaction); if plan A finds otherwise, one extra
+SessionStart entry with matcher `compact` echoes the two import lines.
+
+D2.5 Design documents and the skills. `/cw:design` runs Steps 0–5 in plan mode writing the
+single plan file (wherever plan mode puts it: `docs/plans/` when `plansDirectory: docs/plans`
+is set, else the default plans dir); on approval Step 6 moves it to `$ROOT/docs/plans/<slug>.md`
+(`git mv` when tracked, `mv` otherwise), and when `git -C "$ROOT" check-ignore` says the
+destination is ignored prints the fix by name (`the design file is ignored by .gitignore;
+un-ignore docs/plans/<slug>.md before /cw:build`) instead of a bare warning; in a non-repo
+folder it leaves the file where it is and says so. No sentinel, no
+promotion, no mirror. Its Explore calls keep `model: haiku`. `/cw:build <slug> [continue
+[<task-id>]]` reads the `## Tasks` section of `docs/plans/<slug>.md`, falls back to
+`docs/plans/<slug>/<slug>-tasks.md` with `<slug>-design-draft.md` beside it (the layout this
+build uses), commits the design file(s) as `docs(<slug>): design` through git when untracked
+or modified (no `.gitattributes` write), hands each implementer only its task block, keeps the
+ground-truth gate, counter-model review, NO_VERDICT retry and three iterations, and states
+the delegation boundary in one sentence (the orchestrator edits no file; every change is an
+implementer's) backed by the review gate — no guard hook and no tool restriction: the P0
+probe showed that `disallowed-tools` on a skill also strips the tools from the subagents it
+spawns, so it cannot be used on `/cw:build` (D0). The checkpoint text tells the user to resume
+with `/cw:build <slug> continue [<task-id>]`; `continue` skips tasks whose `commit:` subject
+already appears in `git log main..HEAD`.
+`allowed-tools` per skill (a pre-approval list, not a restriction), without write tools on build: design `Read, Glob, Grep, Agent,
+Write, Edit, Bash(git:*), Bash(mv:*), Bash(mkdir:*)`; build `Read, Glob, Grep, Agent,
+Bash(git:*), Bash(bash:*), Bash(jq:*), Bash(shellcheck:*), Bash(claude plugin:*)` (plus the
+language test runners it inherits from the old skill — the grants cover the verification
+re-runs the orchestrator performs); ship `Read, Glob, Grep, Edit, Write, Bash(git:*), Bash(gh:*), Bash(bash:*),
+Bash(npm:*), Bash(python:*), Bash(pytest:*), Bash(xcodebuild:*), Bash(make:*)`; compound
+`Read, Glob, Grep, Edit, Write, Bash(git:*), Agent`; search and google-workspace none. `/cw:ship`
+verifies the series, detects the quality gate with today's precedence plus one convention
+(`tests/run.sh` present → `bash tests/run.sh all`), pushes, opens the PR, offers
+`/cw:compound`; `/cw:compound` proposes process-rule edits and never commits. `/cw:search`
+keeps source detection and the three-angle method; `--deep` points to the bundled
+`/deep-research` (needs dynamic workflows, §R2.11). `/cw:google-workspace` is the live rule as
+a skill, the four personal lines removed. Deliberate deviation from the multi-file convention
+(§R3 row 9).
+
+D2.6 Tests and CI. `tests/run.sh`, one subcommand per invocation, `BASELINE_BYTES=73738` as a
+constant at the top:
+- `hooks`: fifteen scratch cases fed on stdin under a scratch `HOME` and `CLAUDE_CONFIG_DIR`:
+  push to main blocked (exit 2), feature push allowed (0), force push blocked (2), chained
+  `cd x && git push origin main` blocked (2), `.env` write blocked (2), `.env.example`
+  allowed (0), `secrets/.env.example` blocked (2), a `notebook_path` matching `*secret*`
+  blocked (2), jq absent (a scratch `bin` holding links to every utility the hooks use except
+  jq, run with `PATH=<scratch bin>`) → exit 0 and the warning on stderr,
+  profile right → exit 0 and `additionalContext` starting with `profile `, wrong → exit 0 and
+  `systemMessage` containing `wrong profile`, unmapped → exit 0 and no `systemMessage`,
+  missing absolute import → exit 0 and `missing import` in both fields, relative import that
+  exists → no notice, commented and malformed `.claude-profiles` lines ignored (assertions
+  with `jq -e`).
+- `size [<baseline-bytes>] [--only <dir,dir>]`: prints bytes and the percentage against the
+  baseline (default the constant), fails above 100%; per-file caps (≤150 lines; ≤200 for
+  `skills/design/SKILL.md` and `skills/build/SKILL.md`) apply to `skills/`, `agents/`,
+  `rules/` — restricted to the `--only` directories when given —,
+  `WORKFLOW.md` ≤200 and the skill `description`+`when_to_use` ≤1,536 characters are checked
+  only in full mode.
+- `dedupe [--only <dir>]`: each line of `tests/dedupe-phrases.txt` (15 case-insensitive fixed
+  strings) occurs at most once across `skills/`, `agents/`, `rules/`.
+- `scan [<pattern-file>] [--history [<range>]] [--report] [-p <path>] [-- <pathspec>...]`:
+  the pattern file defaults to `$CW_SCAN_PATTERNS` (private, outside the repo; P0 exports it);
+  inside a git tree `git grep --untracked -niEf` over tracked and untracked, non-ignored files
+  (pathspecs pass through; new files are scanned before their commit); `-p <path>`
+  scans any directory with `grep -rIniEf` (plan A's residue checks); `--history` counts hits
+  in `git log -p <range>` (default `--all`); any hit exits 1 unless `--report`, which prints
+  the hits and exits 0.
+- `all`: `hooks`, `size` (full mode), `dedupe`, the settings-keys check (`comm -23 <(jq -r
+  'keys[]' settings.example.json | sort) <(sort tests/settings-keys.txt)` empty), and `scan`
+  over the tree when `$CW_SCAN_PATTERNS` is set (skipped with a notice otherwise, so CI and
+  adopters run without it) — every `/cw:ship` in this repo therefore scans the tracked
+  files, design documents included, before pushing.
+`tests/settings-keys.txt` (written with the example settings in T6): the top-level keys of
+the settings reference (§R2.13). `tests/fixtures/two-task-plan.md` in the single-file format:
+two independent tasks, `risk: trivial`, `model: sonnet`, task 1 creates `a.txt` (verification
+`test -f a.txt`, commit `feat: add a`), task 2 creates `b.txt` (`test -f b.txt`, `feat: add
+b`). CI: job `ubuntu` (jq, shellcheck; `shellcheck -x hooks/*.sh tests/run.sh` at the default
+severity — the new scripts are clean, so the old `--severity=error` floor goes; `jq empty` on
+the three manifests; `bash tests/run.sh all`; the categorical greps of D6.4; `npm install -g
+@anthropic-ai/claude-code && claude plugin validate .`, unauthenticated, §R3 row 5) and job
+`macos` (`bash tests/run.sh hooks` on the system bash 3.2). CI runs on push and pull request,
+so the red window between the T1 and T2 commits (the old bats and manifest still reference
+the deleted guards) is never exercised; accepted. `claude plugin validate .` also runs
+locally at T1 and T7.
+
+D2.7 Docs and example settings. README (rewritten): what the plugin is; requirements
+(Claude Code ≥ 2.1.269, git, jq — the hooks warn and stand down without it — and a session in
+auto mode or `acceptEdits` for `/cw:build`); the three install paths with the fragility note
+and the real-directory fallback; the command table; the five-line CLAUDE.md and the rules
+import path per install mode; extra profiles (`CLAUDE_CONFIG_DIR`, the `~/.claude-profiles`
+format, one shell alias per extra profile such as `alias claude-acme='CLAUDE_CONFIG_DIR=$HOME/.claude-acme
+claude'` as the launch path that survives GUI launchers, `plansDirectory: docs/plans`);
+`settings.example.json` as a starting point; what to adapt (models and effort in the agents,
+the rules text, the deny list, the identity line); the kill switch, which is also the answer
+for repos that push to main by convention;
+migrating from the old installer (delete the user-scope copies of the five skills, six agents
+and five hooks; remove their `hooks` entries from `settings.json`); `/cw:search --deep`
+needing dynamic workflows; update and uninstall; running the tests; a changelog. (The
+`.gitattributes` file the live `/build` leaves behind is legacy residue, mentioned nowhere in
+the README.) The real owner replaces the `<you>`
+placeholder in the marketplace command (adopters who fork adapt it). `WORKFLOW.md` (≤200
+lines): the pipeline narrative and roles. `CLAUDE.md`: the project file of D2.1.
+`settings.example.json`: `model: fable`, `effortLevel: high`, `plansDirectory: docs/plans`,
+`permissions.defaultMode: auto`, generic deny rules (`.env`, `.env.*`, `**/.envrc`,
+`~/.ssh/**`, `~/.aws/**`, `~/.config/gcloud/**`), `ask: Bash(gh pr create *)`, a short generic
+allow list, `autoMode.allow: ["$defaults"]`, `enabledPlugins` for the three official LSP
+plugins, no `hooks` key, no `_comment_*` keys.
+
+D2.8 Publish. The repo is the plugin, so every commit must be publishable. T7 is a
+verification-only gate (`commit: none`): it fetches `refs/pull/*/head`, runs `run.sh scan`
+over the tree and `--history main..HEAD` (zero hits required) and `--history --all --report`
+(older hits listed, history not rewritten), `claude plugin validate .`, shellcheck, `run.sh
+all` and the temp-config-dir inventory check; the version and the changelog entry land with
+T1 and T6. The live `/ship` opens the PR (the `ask` rule prompts;
+its Step 1 flags the staged `hooks/protect-secrets.sh` as a `*secret*` match — expected,
+waved through; the design is tagged `risk: high`, so it offers the 3-lens panel); CI green;
+the maintainer merges on GitHub; never push main. After the merge, from a temp config dir:
+`claude plugin marketplace add <owner>/claude-code-setup && claude plugin install
+cw@claude-code-setup && claude plugin list` proves the published plugin installs. Evals
+(`claude plugin eval`) are a follow-up.
+
+D2.9 Out of scope, provided for plan A. The symlink is the maintainer's load path. Plan A
+links `skills/cw` in each profile (its launch alias re-creates the link when auto-update has
+removed it, §R2.9), writes the five-line CLAUDE.md and `~/.claude-profiles`, copies
+`settings.example.json` into the profile template, validates profile settings with
+`tests/settings-keys.txt`, and uses `run.sh scan -p <dir>` with its private pattern file for
+residue checks outside git trees. Nothing in this repo names a profile other than the generic
+`~/.claude-acme` example.
+
+D2.10 Baseline, build driver and sessions. `/design` Step 6 writes this artifact set to
+`docs/plans/cw-plugin/` (untracked until `/build` commits it). P0 (the maintainer, plain
+shell): (1) merge PR #2 on GitHub, `git switch main && git pull`; (2) remove the stale private
+mirror directory under `docs/plans/` (the only entry there besides `cw-plugin`; its canonical
+archive lives in the private profile), `git checkout .gitignore`, `rm -f src.txt`; (3) create
+the private pattern file (extended regexes, one per line: the home path, employer and client
+names, organisation ids, private profile-dir names — NOT the public display name or handle),
+export `CW_SCAN_PATTERNS=<its path>` in the shell that launches Claude Code, and prove the
+file bites (it must match a local file known to carry private strings, and must not match
+`LICENSE`); (4) pre-approve the verification commands for the
+build session in the repo-local, ignored `.claude/settings.local.json`; (5) a two-minute probe
+with `claude --plugin-dir` on a scratch plugin (answers recorded in D0); (6) `claude --version` ≥ 2.1.269, `jq`, `shellcheck`. Then
+`/build cw-plugin` (the LIVE `/build` of the personal profile) creates `feat/cw-plugin` from
+`main`, commits the artifact set (plus the `.gitattributes` line it insists on — accepted),
+runs T1→T7 sequentially, stops at its checkpoint; G-load follows; then `/ship`. Interruption:
+re-run `/build cw-plugin`, telling the orchestrator to reuse `feat/cw-plugin` and skip tasks
+whose `commit:` subject already appears in `git log main..HEAD` (the live skill has no
+`continue` branch). Fix-ups after G-load: fresh `fix(<scope>):` commits, one per file group.
+Cut line: if T5 exhausts its three review iterations, ship 1.0.0 from T1, T2, T6 and T7 with
+the prompts unchanged and land the lean cut as 1.1.0 on a second PR; plan A links either.
+Every session launches from the repo root.
+
+### D3 Files
+Create: `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `hooks/hooks.json`,
+`hooks/profile-check.sh`, `rules/workflow.md`, `skills/google-workspace/SKILL.md`,
+`tests/run.sh`, `tests/dedupe-phrases.txt`, `tests/settings-keys.txt`,
+`tests/fixtures/two-task-plan.md`.
+Modify: `.gitignore` (allow `.claude-plugin/`; narrow `docs/` to `docs/plans/*.md` and
+`docs/plans/cw-plugin/`; drop the `scripts/`, `docs/research/` and `.claude/` allowlist
+lines), the five agents, the five
+skills, `hooks/protect-branches.sh`, `hooks/protect-secrets.sh`, `rules/orchestration.md`,
+`README.md`, `WORKFLOW.md`, `CLAUDE.md` (template → project file), `settings.example.json`,
+`.github/workflows/ci.yml`.
+Delete: `agents/Explore.md`, `hooks/orchestrator-delegate-guard.sh`, `hooks/design-scope-guard.sh`,
+`hooks/syntax-check.sh`, `scripts/` (six files), `tests/*.bats` (six), `tests/test_helper.bash`,
+`tests/manual-setup-checklist.md`, `.claude/skills/setup/SKILL.md`. Local only: `src.txt`
+(untracked, removed at P0).
+Written by the live `/build`, not by a task: `docs/plans/cw-plugin/*` (this set) and
+`.gitattributes`.
+
+### D4 Dependencies
+Claude Code ≥ 2.1.269 (installed 2.1.273); `jq`; `shellcheck` (local and CI); `git`; GitHub
+Actions `ubuntu-latest` and `macos-latest`; node and npm on the ubuntu runner only (to
+install the CLI for `claude plugin validate`). No runtime dependency on node.
+
+### D5 Risks and mitigations
+- Skills-dir plugin not discovered, or skills registered bare → T1 and T7 assert
+  `cw@skills-dir` and the inventory under a temp `CLAUDE_CONFIG_DIR`; G-load runs the real
+  session both with `--plugin-dir` and from a symlinked temp config dir; fallback documented
+  in the README (a real directory under `skills/cw` with a symlink back for editing).
+- `if:` fails open on chained or unparseable commands (§R3 row 6) → no `if`; the push guard
+  splits the command on shell separators and checks every segment; `run.sh hooks` has a
+  chained-command case. Cost: the hook runs on every Bash call (jq, milliseconds).
+- A SessionStart exit 2 blocks session initialisation (§R2.5) → profile-check always exits 0
+  and reports through `systemMessage` and `additionalContext`; the P0 probe showed
+  `systemMessage` delivered as a hook response; Claude relays the context line as well.
+- Missing jq → the hooks warn and exit 0 instead of blocking every tool call; README
+  requirement; `run.sh hooks` covers the case. Accepted: no protection without jq.
+- A future design in this repo lands in an ignored path → the allowlist admits
+  `docs/plans/*.md`; `/cw:design` names the fix when a destination is ignored; the project
+  CLAUDE.md states the convention; `run.sh all` scans tracked files for private strings
+  whenever the maintainer's pattern file is set.
+- A bad hook would block every Bash or write call in every linked profile → kill switch
+  `claude plugin disable cw@skills-dir`; hooks are tested by `run.sh hooks` and G-load before
+  merge; revert per commit.
+- The orchestrator edits files itself during `/cw:build` (Fable 5 has overridden delegation
+  rules under cost pressure, §R3 row 7) → the prose boundary plus the review gate, an
+  accepted risk: the P0 probe showed `disallowed-tools` propagating to subagents, which rules
+  it out, and the maintainer decided against guard hooks and sentinels.
+- Plugin agents ignore `mcpServers`, `hooks`, `permissionMode` (§R2.7) → none used; the
+  researcher's MCP tools come from the session's servers and are named in `tools:`; the
+  implementer needs auto mode or `acceptEdits` at session level (README requirement).
+- A file-write tool name missing from the matcher → `Write|Edit|MultiEdit|NotebookEdit`
+  (unknown names are harmless in a regex matcher); `run.sh hooks` feeds both `file_path` and
+  `notebook_path` shapes.
+- Lean-cut regressions → per-file cap and dedupe only; bytes reported; round trip at G-load;
+  revert per commit; the cut line of D2.10.
+- The public repo leaks private strings through the artifacts themselves → the scrub rule of
+  the header; `run.sh scan` runs over tracked files including `docs/`; the P0 sanity check
+  proves the pattern file bites; reviewers check.
+- Older refs (pull refs) already carry private strings → reported, not rewritten (they are
+  already public).
+- Rules cannot travel with a marketplace install (plugins expose no rules component, §R2.10)
+  → README states the import path per install mode; the symlink path is the maintainer's.
+- Adopters of the old installer get double-firing guards → README migration section.
+- The live `/build` drives this build with the delegate and design-scope guards active →
+  implementers are subagents (not guarded); the orchestrator's only write is the
+  `.gitattributes` line, which the guard allows; the live secrets hook blocks Write/Edit on
+  `hooks/protect-secrets.sh`, so T1 writes it with Bash (stated in T1's scope).
+- The live `/build` pre-approves only git and language runners → P0 step 4 allowlists the
+  verification commands in the repo-local settings; otherwise auto mode prompts.
+- The live `/ship` would run pytest on `tests/` → the project CLAUDE.md states `Tests: bash
+  tests/run.sh all` (precedence 2); its Step 1 `*secret*` match on the secrets hook is
+  expected.
+- CI is red between the T1 and T2 commits → accepted; CI runs only at push time.
+- `claude plugin validate` in CI needs the npm package → one minute per push; accepted.
+- Size target of 60% missed → reported; hard fail only above 100%.
+- The checkout becomes the live workflow once plan A links it → branch discipline; the
+  checkout sits on `main`; a half-saved edit is fixed by `git checkout` (accepted).
+
+### D6 Success criteria
+1. `claude plugin validate .` exits 0; `jq empty .claude-plugin/plugin.json
+   .claude-plugin/marketplace.json hooks/hooks.json`; `jq -e '.name=="cw" and
+   .version=="1.0.0"' .claude-plugin/plugin.json`; `jq -e '.name=="claude-code-setup" and
+   .plugins[0].name=="cw" and .plugins[0].source=="./"' .claude-plugin/marketplace.json`.
+2. Loading: `CFG=$(mktemp -d); mkdir -p "$CFG/skills"; ln -s "$PWD" "$CFG/skills/cw"; env
+   CLAUDE_CONFIG_DIR="$CFG" claude plugin list | grep -q 'cw@skills-dir'`; `env
+   CLAUDE_CONFIG_DIR="$CFG" claude plugin details cw@skills-dir` lists 6 skills, 5 agents and
+   the hooks (2 events, 3 commands).
+3. Gates: `bash tests/run.sh all` exits 0 (15 hook cases; the size ratio printed, target
+   ≤60%; per-file caps; dedupe; settings keys); `shellcheck -x hooks/*.sh tests/run.sh` clean
+   at the default severity; `wc -l < WORKFLOW.md` ≤ 200.
+4. Categorical (tracked files): `! git grep -qniE 'opus needs|do not trust|be decisive|read
+   all files fresh|claude-design-active|claude-orchestrator-active' -- skills agents rules`;
+   `! git grep -qwE 'NEVER|ALWAYS|MUST|CRITICAL' -- skills agents rules`; `! git grep -qniE
+   'under 50 lines' -- skills agents rules`; `! git grep -qnE
+   '^(disallowedTools|permissionMode|mcpServers|hooks):' -- agents`; every agent has `model:`,
+   `tools:`, `effort:`, `maxTurns:`; `! git grep -qniE '~/.claude/plans|gitattributes|linguist|git
+   clean' -- skills`; `grep -q haiku skills/design/SKILL.md`; `N=$(sed -n 's/^Copyright (c)
+   [0-9]* //p' LICENSE | cut -d' ' -f1); ! git grep -qi "$N" -- skills agents rules hooks
+   tests WORKFLOW.md CLAUDE.md docs` (the maintainer's name appears only in `LICENSE`,
+   `.claude-plugin/plugin.json` and README URLs); `bash tests/run.sh scan` exits 0 (tree,
+   `$CW_SCAN_PATTERNS`).
+5. Frontmatter: `grep -l 'disable-model-invocation: true' skills/*/SKILL.md | wc -l` = 3
+   (build, ship, compound); `grep -q '^effort: xhigh' skills/design/SKILL.md`; `! grep -q
+   '^disallowed-tools:' skills/build/SKILL.md`; `ls skills | tr '\n' ' '` = `build compound
+   design google-workspace search ship `; `ls agents | wc -l` = 5.
+6. Round trip (G-load, human). (a) From a scratch git repo under `/tmp` launched with
+   `claude --plugin-dir <checkout>` in the logged-in profile: `/cw:design` and the other five
+   `/cw:` skills are listed and the five `cw:` agents appear in `/agents`; `git push origin
+   main` and `cd . && git push origin main` are blocked, a `.env` write is blocked; a dry
+   `/cw:design` ends with `docs/plans/<slug>.md`; with the fixture copied into the scratch
+   repo as `docs/plans/two-task.md`, a dry `/cw:build two-task` yields exactly two commits
+   with the trailer, both authored through implementer subagents (the transcript shows one Agent call per task and no orchestrator Write or Edit). (b) From a temp config dir
+   holding only `skills/cw -> <checkout>` (one-time login there), started in a folder mapped to
+   another config dir by a scratch `~/.claude-profiles`: the six skills are listed and the
+   `wrong profile` notice appears (record the channel).
+7. Publish: `bash tests/run.sh scan --history main..HEAD` = 0 hits; `git fetch origin
+   '+refs/pull/*/head:refs/remotes/origin/pr/*'` then `bash tests/run.sh scan --history --all
+   --report` hits listed in the exit report; PR opened by `/ship`; CI green (both jobs);
+   merged on GitHub; from a temp config dir `claude plugin marketplace add
+   <owner>/claude-code-setup && claude plugin install cw@claude-code-setup && claude plugin
+   list | grep -q 'cw@claude-code-setup'`.
+8. Docs: README contains `skills/cw`, `marketplace add`, `--plugin-dir`, `.claude-profiles`,
+   `plansDirectory`, `jq`, `plugin disable`, `acceptEdits`, a migration section and a
+   five-line CLAUDE.md example; `! grep -q '<you>' README.md`; `! grep -qE
+   'install.sh|merge-settings|/setup' README.md WORKFLOW.md`; `grep -q 'tests/run.sh all'
+   CLAUDE.md && grep -q 'Co-Authored-By' CLAUDE.md && test $(wc -l < CLAUDE.md) -le 20`; `jq -e '.model=="fable" and
+   .plansDirectory=="docs/plans" and (has("hooks")|not) and ([keys[]|select(startswith("_"))]|length)==0'
+   settings.example.json`; `comm -23 <(jq -r 'keys[]' settings.example.json | sort) <(sort
+   tests/settings-keys.txt)` empty.
+
+### D7 Implementation plan
+P0 → `/build cw-plugin` (live build, cwd = repo root): T1 manifest, hooks.json, hooks → T2
+run.sh, phrases, CI, retire installer and bats → T3 rules → T4 agents → T5 skills, fixture →
+T6 README (with the changelog), WORKFLOW, project CLAUDE.md, example settings, settings keys
+→ T7 release gate (verification only) → `/build` checkpoint → G-load (human, both round trips; fix-ups as fresh `fix(<scope>):`
+commits) → `/ship` (gate from the project CLAUDE.md; the `*secret*` match waved through) → CI
+→ merge on GitHub → post-merge marketplace install check → `git switch main && git pull` →
+plan A. Cut line per D2.10.
diff --git a/docs/plans/cw-plugin/cw-plugin-research-bestpractices.md b/docs/plans/cw-plugin/cw-plugin-research-bestpractices.md
new file mode 100644
index 0000000..2974376
--- /dev/null
+++ b/docs/plans/cw-plugin/cw-plugin-research-bestpractices.md
@@ -0,0 +1,15 @@
+## §R3 Research: best practices and contrarian (researcher sonnet 2026-09-16, three angles; the rev 8.1 rows on the `cw` prefix, `@import` rules and model routing carry over unchanged)
+
+| # | Choice | Best practice | Contrarian | Verdict |
+|---|---|---|---|---|
+| 1 | Lean cut for Claude 5 | Anthropic removed >80% of Claude Code's system prompt for Opus 5 and Fable 5 "with no measurable loss"; the tax is duplication and contradiction, not length; verification and self-check nudges go ("Opus 5 verifies its own work without being told"); CLAUDE.md under ~200 lines; always-rules in CLAUDE.md, on-demand procedures in skills. https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models · https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5 | Over-deletion of project gotchas that look like boilerplate; behaviour moved into judgment shifts when the model changes; a separate reviewer process is NOT what the "cut self-verification" guidance targets | Apply; keep gotchas, scope boundaries, verdict schemas; per-file cap + dedupe; round trip before publish |
+| 2 | Reviewer severity | "If your review prompt says 'only report high-severity issues' … the model may follow that instruction literally and report less; ask it to report everything and filter in a separate pass" (Opus 5 guide) | — | Reviewers report everything; the orchestrator filters |
+| 3 | Plugin layout and versioning | Anthropic's own plugins: `plugin.json` alone inside `.claude-plugin/`, components at the root, flat semver (`1.0.0`), no CHANGELOG files, `hooks.json` with `${CLAUDE_PLUGIN_ROOT}` and 10 s timeouts, agents mostly set `model` only. https://github.com/anthropics/claude-code/tree/main/plugins | None of the official plugins ship tests or CI (a gap, not evidence) | Follow the layout; keep `effort` and `maxTurns` (documented, cheap) |
+| 4 | Self-hosted marketplace | Documented; community template Nagell/claude-marketplace-template; dual install paths documented side by side in obra/superpowers-marketplace | Plugin name equal to the marketplace name crashes installs on Linux (EXDEV, #24389); flat namespace (#45266); a second marketplace with the same name silently overwrites (#44042) | Marketplace `claude-code-setup`, plugin `cw` |
+| 5 | Hook tests in plain bash; `validate` in CI | Anthropic's plugin-dev skill tests hooks with `echo '{…}' \| bash hook.sh; echo $?` (no bats); ScottHysom/claude-plugins CI installs the CLI and runs `claude plugin validate` unauthenticated on every push | No precedent for a `run.sh <subcommand>` dispatcher (bespoke; unsourced judgment) | Plain-bash runner; `validate` step in CI |
+| 6 | `if:` on safety hooks | The official security-guidance plugin uses `if: Bash(git push:*)` | The doc calls `if` best-effort and points to the permission system for hard guarantees; #46056 reported chained commands skipped in earlier versions and #63066 a permissive parser fallback | No `if` on the two safety hooks; the script splits the command on shell separators and checks every segment |
+| 7 | Deleting the delegate guard | Claude 5 guidance: scope boundaries suffice, remove nudges | Fable 5 overrode a persisted delegation rule repeatedly under cost pressure (#89114); a subagent ignored "surgical edits only" (#63356); Anthropic backs delegation prose with deterministic caps | The P0 probe showed `disallowed-tools` also strips the tools from subagents, so `/cw:build` keeps a prose boundary plus the review gate (accepted risk); no hook, no sentinel |
+| 8 | Symlinked skills-dir loading | Documented in-place loading | Recurring issues: auto-update removes symlinks (#50052), the installer skips symlinks (#57339), `/skills` misses them (#14836), Desktop skips them (#37435), duplicate listing (#23819) | The maintainer's path (plan A links it; the alias re-links); the README documents the real-directory fallback and the marketplace path for adopters; the plugin works from any of the three |
+| 9 | Single design file | `plansDirectory` puts plans beside code | Spec-driven workflows (cc-sdd, Spec-Kit derivatives) split spec/plan/tasks files; no Anthropic source prescribes either | Keep the single file (judgment call, unsourced); `/cw:build` reads both layouts |
+| 10 | `disable-model-invocation` on build, ship, compound | Documented, current | None found | Keep |
+| 11 | README shape | Official plugin READMEs: overview, commands, workflow, agents, requirements, troubleshooting; marketplace templates add install paths and versioning | No comparator for a "personal workflow turned template" | Add requirements, "what to adapt", the three install paths, migration from the installer, uninstall, the fragility note |
diff --git a/docs/plans/cw-plugin/cw-plugin-research-codebase.md b/docs/plans/cw-plugin/cw-plugin-research-codebase.md
new file mode 100644
index 0000000..b738824
--- /dev/null
+++ b/docs/plans/cw-plugin/cw-plugin-research-codebase.md
@@ -0,0 +1,131 @@
+## §R1 Research: codebase (Explore haiku + orchestrator git inspection, 2026-09-16)
+
+### R1.1 Baseline tree
+Repo `claude-code-setup`, commit 53b6bb9 = head of PR #2 (`feat/project-local-docs`, 19 commits
+over `main` e87cac6, no divergence, so the merge result equals this tree). Line counts (`wc -l`):
+- `skills/`: design 285, build 272, ship 153, search 129, compound 59.
+- `agents/`: direction-reviewer 78, design-reviewer 69, researcher 59, reviewer 47, implementer 43,
+  Explore 34.
+- `rules/orchestration.md` 47. No `rules/workflow.md`, no `rules/google-workspace.md`.
+- `hooks/`: orchestrator-delegate-guard 128, design-scope-guard 127, protect-branches 97,
+  syntax-check 38, protect-secrets 26. No `hooks.json`, no profile check.
+- `scripts/`: check.sh 298, merge-settings.sh 269, install.sh 241, lib.sh 174, merge-claude-md.sh
+  160, manifest.txt 17 (manifest-driven installer for user-scope copies).
+- `tests/`: merge-settings.bats 356, install.bats 331, hooks.bats 329, check.bats 326,
+  merge-claude-md.bats 195, e2e.bats 128, test_helper.bash 50, manual-setup-checklist.md 51.
+  `hooks.bats` covers ONLY the delegate guard and the design-scope guard; protect-branches.sh
+  and protect-secrets.sh have no behaviour tests today.
+- `.github/workflows/ci.yml` 65: job `lint-and-test` (ubuntu: `shellcheck -x --severity=error
+  scripts/*.sh hooks/*.sh` — the severity floor tolerates five pre-existing findings in the
+  two protect hooks —, `bats tests/*.bats`, manifest diff) and job `bats-macos` (system bash
+  3.2).
+- `README.md` 372 (14 sections; install by `git clone https://github.com/<you>/...` with a
+  `<you>` placeholder for the owner), `WORKFLOW.md` 298, `CLAUDE.md` 48 (a template for the
+  adopter's user-scope CLAUDE.md with fenced `workflow-rules v1` markers, merged by the
+  installer — not a project file for this repo), `settings.example.json` 90 (registers the
+  five hook scripts by `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks/...`; its top-level keys
+  include two `_comment_*` entries), `.claude/skills/setup/SKILL.md` 184 (`/setup`
+  orchestrating the scripts), `LICENSE` (MIT, the maintainer's name as copyright holder),
+  `src.txt` (an untracked, ignored placeholder — not part of the tree). No `.gitattributes`.
+- Bytes of `skills/*/SKILL.md` + `agents/*.md` + `rules/*.md` at 53b6bb9: **73,738** (the
+  lean-cut baseline).
+- `.gitignore` is default-deny (`*`) with an allowlist: `.gitignore`, `.gitattributes`,
+  README, LICENSE, CLAUDE.md, WORKFLOW.md, settings.example.json, `rules/**`, `agents/**`,
+  `skills/**`, `hooks/**`, `scripts/**`, `tests/**`, `docs/plans/**`, `docs/research/**`,
+  `.github/**`, `.claude/skills/setup/**`; explicit ignores for local state (incl.
+  `settings.local.json`) and `.claude/settings.json`; an uncommitted working-tree line ignores
+  a stale mirror directory of the private predecessor design (byte-identical to its private
+  archive). **`.claude-plugin/` is not allowlisted, so a plugin manifest would be ignored until
+  the allowlist changes.** `docs/plans/cw-plugin/x` is un-ignored (line 33).
+- Personal or employer strings in the tree (case-insensitive: the owner's handle, absolute home
+  paths, employer names, a personal repo name, the owner's first name): only `LICENSE:3`
+  (copyright, keep) and `scripts/merge-claude-md.sh:5` (a comment; the file is deleted).
+
+### R1.2 Frontmatter at 53b6bb9
+- Skills: build and ship and compound carry `disable-model-invocation: true`; design and search
+  are model-invocable with trigger phrases; build's `argument-hint` lacks `continue` (the live
+  copy has it); design has no `effort:`.
+- Agents: design-reviewer `model: opus, effort: xhigh, maxTurns: 25, skills: [search],
+  mcpServers, memory: project`; direction-reviewer `opus, xhigh, 15, tools: Read/Glob/Grep,
+  memory: project`; implementer `sonnet, high, 50, permissionMode: acceptEdits, mcpServers:
+  [context7], memory: project`; reviewer `opus, xhigh, 20, tools: Read/Glob/Grep/Bash,
+  disallowedTools: Write/Edit, memory: project`; researcher `sonnet, high, 30, skills:
+  [search], mcpServers`; Explore `haiku, tools: Read/Glob/Grep` (exists only to force haiku on the
+  built-in Explore, which inherits the session model since v2.1.198). All six carry
+  `disallowedTools` (dropped by the rewrite).
+
+### R1.3 Live-ahead items to carry (live profile `~/.claude` versus the repo)
+- `rules/orchestration.md`: live 63 lines; the repo lacks the "Review-loop anti-ratchet"
+  section (structured findings, accept/drop before redraft, 1–2 round cap, mechanical limits,
+  minimal fixer context). Base the rewrite on LIVE.
+- `hooks/protect-secrets.sh`: live 30 lines; only LIVE has the template allowlist
+  (`.env.example|.env.sample|.env.template|env.example` by basename → allow); its comment
+  carries personal context (strip). Only the REPO has the jq presence check. Both: lowercase
+  the path; block `*.env`, `*.env.*`, `*.envrc`, `*credentials*`, `*secret*`, `*config.swift`,
+  key files (`.pem .key .p8 .pfx .jks .keystore`, `id_rsa*`, `id_ed25519*`), `.aws/`, `.ssh/`,
+  `.gnupg/`, `secrets/`, `*service-account*.json`, `*gcp*key*.json`; read
+  `.tool_input.file_path // .tool_input.filePath`.
+- `hooks/protect-branches.sh`: live 107 lines; only LIVE has a machine-specific exemption — a
+  block that sets an `EXEMPT` flag plus four later branch points that read it (remove all of
+  them); the REPO blocks every `--force` uniformly and has the jq check. Both live hooks
+  carry shellcheck findings at the default severity (the old CI gated at `--severity=error`
+  for that reason); the ports must be clean at the default severity.
+- `hooks/check-account-routing.sh` (live only, 17 lines, unwired): the precursor of
+  profile-check; it exits 2 on SessionStart, which would block session start (§R2.5), so its
+  shape is not reused. Both:
+  tokenise the command (env assignments, git global options), detect `push`, resolve a
+  refspec-less push to the current branch, block a main/master destination and bare
+  `--force`/`-f`, allow branch names that merely contain "main" (e.g. `feat/main-nav`).
+- `skills/build/SKILL.md`: live 259 lines; only LIVE has the `continue` argument hint (resume
+  a build; refreshed artifacts excluded from one-commit-per-task accounting) — the hint only;
+  Phase 0 has no `continue` branch in either copy. Repo 272 lines.
+- `skills/design/SKILL.md`: live 275, repo 285 (the repo carries the fuller Step 6 promotion
+  and guard choreography that the rewrite deletes).
+- Live-only files: `rules/google-workspace.md` (27 lines: capability matrix for the Drive/Docs
+  connector, upload routes, seven landmines; four lines carry personal context — strip) and
+  `skills/deep-research/` (not in the repo; the bundled `/deep-research` replaces it).
+- The live `~/.claude/CLAUDE.md` (37 lines) holds the workflow rules the new `rules/workflow.md`
+  bases on: branch policy, Conventional Commits with the `Co-Authored-By: Claude
+  <noreply@anthropic.com>` trailer, design-first with two checkpoints, one commit per task,
+  PR only after the gate, `/ship` offers `/compound`, process-rule edits never in the feature
+  PR, research-first (context7 before APIs, unsourced decisions flagged), context hygiene.
+
+### R1.4 Lean-cut targets found in the repo prompts
+- Whole-word capitals: NEVER ×5 in ship (safety list), ×1 build; MUST in search and
+  orchestration; ALWAYS/NEVER in syntax-check.sh (deleted); none in agents.
+- Sentinel choreography (`/tmp/claude-design-active`, `/tmp/claude-orchestrator-active`):
+  design lines 14–15, 194, 196, 244; build 97, 112, 124 — deleted with the guards.
+- Rule phrases present in more than one prompt file (the dedupe clusters, §D2.2): never push
+  main (ship, and CLAUDE.md/WORKFLOW/README docs), one atomic commit per task (design 81,
+  build throughout), trailer (design 135, build 96, ship 41), NO_VERDICT (design 164, build
+  218–221 and 269, orchestration 40), fresh-context counter-model reviewer (orchestration
+  36–37, design 145, build 179–180), same-turn spawn (design 81, build 123), root-anchored
+  check-ignore (design 205, build 88), context7 before APIs (implementer 32, design-reviewer
+  40), three-angle methodology (design-reviewer 40, search), functions under 50 lines
+  (reviewer 33), explicit model per Agent call (orchestration 15, design 81–83),
+  `/compound` never commits (compound 3). Docs (README, WORKFLOW) may restate rules; the
+  dedupe gate covers `skills/`, `agents/`, `rules/` only.
+- Model workarounds and nudges to delete: "Opus needs the fan-out stated explicitly"
+  (design), "Read all files FRESH … Do NOT trust prior summaries" (build reviewer prompt),
+  "known issue #24327" sentinel note (build), `.gitattributes` linguist line (build Phase 0),
+  `git clean` allowed-tools grant (design), `docs/research` allowlist (guards). The design
+  skill's Explore calls pass `model: haiku` (keep; the built-in inherits the session model).
+
+### R1.5 The live `/build` and `/ship` that drive this build
+`~/.claude/skills/build/SKILL.md` resolves `$ROOT/docs/plans/<slug>/<slug>-tasks.md` only when
+`<slug>-design-draft.md` is present too (both written by `/design` Step 6), needs a clean
+tree apart from `docs/plans/<slug>/`, creates `feat/<slug>` from `main`, commits the artifact
+set as `docs(<slug>): add design + research artifacts` (and adds `docs/plans/**
+linguist-generated=true` to `.gitattributes`, which the allowlist tracks), then runs tasks in
+`depends_on` order with context-pinned implementers (each sees only its own task entry), a
+ground-truth gate in which the orchestrator re-runs each task's `verification` itself,
+counter-model reviewers, at most three iterations, and a human checkpoint; `commit: none`
+tasks are verification-only; its `allowed-tools` pre-approve only `git`, `npm`, `python`,
+`pip`, `pytest`, `swift`, `xcodebuild`, `gh`, so other commands prompt unless allowlisted.
+The live `/ship` verifies the series, refuses staged files matching `*secret*` and `.env*`
+(a rewritten `hooks/protect-secrets.sh` matches and must be waved through by the human),
+detects the quality gate (`.claude/rules/pr-merge-policy.md` → a test command stated in the
+project CLAUDE.md → convention fallback, where a `tests/` directory means `python -m pytest
+-q`), offers a 3-lens panel when the design is tagged `risk: high`, pushes, opens the PR,
+offers `/compound`. The live secrets hook blocks Write/Edit on any path matching `*secret*`,
+so `hooks/protect-secrets.sh` must be written with Bash.
diff --git a/docs/plans/cw-plugin/cw-plugin-research-docs.md b/docs/plans/cw-plugin/cw-plugin-research-docs.md
new file mode 100644
index 0000000..674dcb4
--- /dev/null
+++ b/docs/plans/cw-plugin/cw-plugin-research-docs.md
@@ -0,0 +1,101 @@
+## §R2 Research: docs currency (researcher sonnet 2026-09-16 against the live docs; context7's snapshots stop at v2.1.89, so every claim comes from a direct fetch; installed v2.1.273)
+
+1. Plugin manifest: only `name` is required (kebab-case); optional `displayName`, `version`,
+   `description`, `author{name,email,url}`, `homepage`, `repository`, `license`, `keywords`,
+   `metadata`, `userConfig`, `dependencies`, `defaultEnabled`; component paths are relative to
+   the root and start with `./` (`skills` adds to `skills/`; `agents` and `commands` replace;
+   `hooks`, `mcpServers`, `lspServers` take paths or inline config). Only `plugin.json` lives
+   inside `.claude-plugin/`; `skills/`, `agents/`, `hooks/` sit at the plugin root (nesting
+   them inside `.claude-plugin/` is a documented "common mistake").
+   https://code.claude.com/docs/en/plugins-reference
+2. Marketplace: `.claude-plugin/marketplace.json` with `name` (kebab-case), `owner{name}`,
+   `plugins[{name, source, description?, version?}]`; `source: "./"` is valid when the repo is
+   the marketplace ("Paths resolve relative to the marketplace root, which is the directory
+   containing `.claude-plugin/`"); users run `claude plugin marketplace add <owner>/<repo>`
+   then `claude plugin install <plugin>@<the name inside marketplace.json>`; relative sources
+   resolve for git-added marketplaces, not for a raw-URL `marketplace.json`; `strict`
+   defaults to true (plugin.json authoritative). Installs land under the plugin cache
+   (`~/.claude/plugins/cache/<marketplace>/<plugin>/`), replaced on `claude plugin update`.
+   https://code.claude.com/docs/en/plugin-marketplaces
+3. `claude plugin validate <path>`: static schema validation (unknown fields warn, `--strict`
+   fails; agent frontmatter parsed since v2.1.233); exit 0 valid, 1 invalid, 2 the run failed;
+   no login documented and a practitioner CI runs it unauthenticated after installing the CLI
+   (§R3 row 5). `claude plugin eval` (v2.1.269) runs model calls with credentials — a
+   follow-up. https://code.claude.com/docs/en/plugin-evals
+4. Skills-directory plugins: "Any folder under a skills directory that contains a
+   `.claude-plugin/plugin.json` manifest is loaded as a plugin named `<name>@skills-dir` on
+   the next session, with no marketplace and no install step"; SKILL.md edits apply
+   immediately; `hooks/`, `agents/`, `.mcp.json` need `/reload-plugins` or a restart;
+   `claude plugin disable <name>@skills-dir`; nothing to uninstall. The doc names
+   `~/.claude/skills/` and `<cwd>/.claude/skills/`; relocation by `CLAUDE_CONFIG_DIR` is not
+   stated, but the private probe of 2026-09-15 under a temporary config dir loaded a
+   symlinked plugin folder: `claude plugin list` showed it loaded and `claude plugin details`
+   printed the inventory (skills 1, agents 1, hooks 1).
+   https://code.claude.com/docs/en/plugins-reference
+5. `hooks/hooks.json`: `{"hooks": {<Event>: [{matcher, hooks: [{type: "command", command,
+   if?, timeout}]}]}}` (`if` sits inside the handler object next to `command`); `timeout` in
+   seconds (default 600); `${CLAUDE_PLUGIN_ROOT}` substituted. `if` is "permission rule
+   syntax to filter when this hook runs", evaluated only on tool events, before spawning; the
+   Bash matcher strips env prefixes and checks each subcommand of a chain, but "when the
+   shell parser can't determine expansion … the hook runs anyway", and the doc itself says
+   "Because the `if` filter is best-effort, use the permission system rather than a hook to
+   enforce a hard allow or deny" (§R3 row 6). File-write coverage:
+   "Use explicit matchers if you need those: `Edit|Write|MultiEdit|NotebookEdit`".
+   SessionStart matchers: `startup`, `resume`, `clear`, `compact`, `fork`. **Exit code 2 on
+   SessionStart: "Blocks session initialization"** (effect table) — a notice must use exit 0
+   with JSON; `systemMessage` in JSON stdout surfaces a message to the user ("Some events
+   discard it or deliver it elsewhere"); for SessionStart, plain stdout and
+   `hookSpecificOutput.additionalContext` are "context that Claude can see and act on". A
+   plugin hook and a settings hook with the same command both fire ("A plugin's or skill's
+   copy of the same handler stays separate"). Stdin carries `session_id`, `cwd`,
+   `hook_event_name`, `tool_name`, `tool_input` (`command` for Bash, `file_path` for file
+   tools), `tool_use_id`. https://code.claude.com/docs/en/hooks
+6. SKILL.md frontmatter: `name`, `description`, `when_to_use` ("trigger phrases or example
+   requests. Appended to `description` in the skill listing and counts toward the
+   1,536-character cap"), `argument-hint`, `disable-model-invocation` ("prevent Claude from
+   automatically loading this skill … trigger manually with `/name`"), `user-invocable`,
+   `allowed-tools` ("Tools Claude can use without asking permission during the turn that
+   invokes this skill"), `disallowed-tools` ("Tools removed from Claude's available pool
+   while this skill is active … The restriction clears when you send your next message"),
+   `model`, `effort` ("Overrides the session effort level" while active), `context: fork`,
+   `agent`, `paths`, `hooks`, `shell`. Plugin skills are `/<plugin>:<skill>`; the bare
+   `/name` also works unless another command uses it; the model invokes `plugin:skill`
+   through the Skill tool. Description-based triggering is documented as probabilistic
+   ("Strengthen the skill's `description` … or use hooks to enforce behavior
+   deterministically"). VS Code extension bug #74363: a plugin skill whose bare name collides
+   with a built-in command becomes unreachable there — none of the six `cw` names collide.
+   https://code.claude.com/docs/en/skills
+7. Agent frontmatter: `model` (`sonnet`, `opus`, `haiku`, `fable`, a full id, `inherit`),
+   `effort`, `maxTurns`, `tools` (incl. `Agent(type)` allowlists), `disallowedTools`,
+   `permissionMode`, `memory` (`user|project|local`), `skills`, `mcpServers`, `hooks`,
+   `background`, `isolation`, `color`. **"For security reasons, plugin subagents don't support
+   the `hooks`, `mcpServers`, or `permissionMode` frontmatter fields. These fields are ignored
+   when loading agents from a plugin."** Precedence: managed > `--agents` > project > user >
+   plugin; "A user or project subagent named `Explore` overrides the built-in" — a plugin
+   agent cannot. Plugin agents register as `<plugin>:<agent>`.
+   https://code.claude.com/docs/en/sub-agents
+8. `plansDirectory`: settings-reference row "Choose where plan mode writes plan files" (any
+   scope); open bugs #39481 (absolute paths ignored) and #19537 (project-level value ignored
+   in some cases); plan mode writes one random-named file (observed again this session). The
+   design moves the plan file at Step 6 wherever it landed.
+9. Auto-update and symlinks: #50052 (auto-update silently removed symlinks under
+   `~/.claude/skills/`, opened 2026-04-17, closed "not planned"); whether it hits a symlinked
+   skills-dir plugin folder is not documented either way; no fix in 2.1.269–273.
+   `autoUpdates` is a legacy `~/.claude.json` key (#60956 reports it ignored on native
+   installs); `DISABLE_AUTOUPDATER=1` is the reliable switch. Plan A's concern; plan B
+   documents the real-directory fallback and the marketplace path.
+10. CLAUDE.md imports: "Both relative and absolute paths are allowed … maximum depth of four
+    hops"; the external-import approval dialog applies to project-scope files only — "User-scope
+    memory files, such as `~/.claude/CLAUDE.md` and `~/.claude/rules/` … Claude Code loads their
+    imports without the dialog". Behaviour on a missing target is undocumented (profile-check
+    reports it). Plugins list no CLAUDE.md or rules component. https://code.claude.com/docs/en/memory
+11. `/deep-research <question>` is a built-in workflow ("Fans out web searches … returns a
+    cited report"); needs WebSearch and dynamic workflows (paid plans; Pro toggles it in
+    `/config`; `disableWorkflows` turns it off). https://code.claude.com/docs/en/workflows
+12. Changelog 2.1.269–2.1.273: `claude plugin eval` (269), plugin MCP/LSP/headless fixes
+    (271), nothing on `if`, skills-dir loading, agent frontmatter, `plansDirectory` or
+    `validate`. https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md
+13. Settings keys for the example file: the settings-reference page lists every top-level
+    `settings.json` key (incl. `model`, `effortLevel`, `plansDirectory`, `permissions`,
+    `autoMode`, `enabledPlugins`, `hooks`, `tui`, `theme`, `forceLoginMethod`,
+    `forceLoginOrgUUID`). https://code.claude.com/docs/en/settings-reference
diff --git a/docs/plans/cw-plugin/cw-plugin-tasks.md b/docs/plans/cw-plugin/cw-plugin-tasks.md
new file mode 100644
index 0000000..b47387e
--- /dev/null
+++ b/docs/plans/cw-plugin/cw-plugin-tasks.md
@@ -0,0 +1,141 @@
+## §T Task breakdown — cw-plugin rev 2
+
+Commits land on `feat/cw-plugin`, created by the live `/build` from `main` after P0. Trailer
+per CLAUDE.md on every commit (`Co-Authored-By: Claude <noreply@anthropic.com>`). Tasks run
+sequentially in id order (each depends on the previous; `files_owned` disjoint). Zero-count
+checks use `! grep -q`. `$CW_SCAN_PATTERNS` (exported at P0) names the private pattern file;
+`bash tests/run.sh scan` reads it by default. `$ROOT` is `git rev-parse --show-toplevel`. The
+bytes baseline is 73,738 (§R1.1). A verification clause marked "(after the commit)" depends
+on the index: the implementer runs it after its commit and the orchestrator's gate re-runs
+it; every other clause must pass before the commit. A clause written `cmd; test $? -eq N`
+expects that exit code. Interruption and fix-ups per D2.10.
+
+## P0 (the maintainer, plain shell, not a task)
+1. Merge PR #2 on GitHub; `R=<path to the checkout>`; `git -C "$R" switch main && git -C "$R"
+   pull`.
+2. In `$R`: remove the stale private mirror directory under `docs/plans/` (the only entry
+   besides `cw-plugin`; untracked and ignored, byte-identical to its private archive —
+   confirm with `git ls-files docs/plans | wc -l` = 0 first), `git checkout .gitignore`,
+   `rm -f src.txt`.
+3. Write the private pattern file outside the repo (a directory of mode 700, the file mode
+   600), one extended regex per line: the home path, employer and client names, organisation
+   ids, private profile-dir names — not the public display name or handle; `export
+   CW_SCAN_PATTERNS=<pattern file>` in `.zshrc` and the current shell.
+4. Pre-approve the verification commands for the build session: in `$R/.claude/settings.local.json`
+   (ignored) set `permissions.allow` to `Bash(bash:*)`, `Bash(jq:*)`, `Bash(shellcheck:*)`,
+   `Bash(claude plugin:*)`, `Bash(env:*)`, `Bash(comm:*)`, `Bash(mktemp:*)`, `Bash(mkdir:*)`,
+   `Bash(ln:*)`, `Bash(cat:*)`, `Bash(echo:*)`, `Bash(printf:*)`, `Bash(ls:*)`, `Bash(wc:*)`,
+   `Bash(tr:*)`, `Bash(awk:*)`, `Bash(grep:*)`, `Bash(test:*)`, `Bash(sed:*)`, `Bash(find:*)`,
+   `Bash(git:*)` (a compound clause the permission parser cannot split may still prompt;
+   accepted).
+5. Probe (two minutes): `P=$(mktemp -d); mkdir -p $P/.claude-plugin $P/skills/dt $P/hooks`;
+   `plugin.json` `{"name":"probe"}`; `skills/dt/SKILL.md` with frontmatter `name: dt`,
+   `disallowed-tools: Write, Edit` and the body "First try to create /tmp/dt-probe.txt
+   containing hello with the Write tool; then spawn a general-purpose subagent and ask it to
+   create /tmp/dt-probe-sub.txt containing hello with the Write tool"; `hooks/hooks.json`
+   with a SessionStart `startup` command `echo
+   '{"systemMessage":"probe-ok","hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"probe-ok"}}'`;
+   from a scratch folder `claude --plugin-dir $P`: note whether `probe-ok` is shown at start;
+   run `/probe:dt`: note whether the orchestrator's Write is refused AND whether the
+   subagent's write succeeds (`test -f /tmp/dt-probe-sub.txt`). Record all three answers in
+   D0 (they fix the wording of D2.4 and D2.5; a subagent that cannot write means the field
+   propagates and the boundary falls back to prose plus the review gate).
+6. `claude --version` (≥ 2.1.269); `command -v jq shellcheck`.
+Verify: `git -C "$R" branch --show-current` = main; `git -C "$R" status --short | grep -v
+'docs/plans/cw-plugin' | wc -l` = 0 (the artifact set written by `/design` Step 6 is the only
+untracked path); `ls "$R/docs/plans" | tr '\n' ' '` = `cw-plugin `; `test ! -f "$R/src.txt"`;
+`test -s "$CW_SCAN_PATTERNS"`; `test "$(grep -cEf "$CW_SCAN_PATTERNS" <a local file known to
+contain private strings, e.g. the live profile's Google Workspace rule>)" -ge 1` (the pattern
+file bites); `test "$(grep -cEf "$CW_SCAN_PATTERNS" "$R/LICENSE")" -eq 0`; `cd "$R" && ! git
+grep --untracked -qniEf "$CW_SCAN_PATTERNS" -- . ':!LICENSE'` (covers the untracked artifact
+set); `ls "$R/docs/plans/cw-plugin" | wc -l` = 5 (the five files written by `/design` Step 6);
+`jq -e '.permissions.allow|length>=15' "$R/.claude/settings.local.json"`; the three probe
+answers recorded.
+
+## Task T1
+- scope: Plugin skeleton and hooks: `.gitignore` allowlist gains `!.claude-plugin/` and `!.claude-plugin/**`, replaces the `docs/plans/**` and `docs/research/**` lines by `!docs/`, `!docs/plans/`, `!docs/plans/*.md`, `!docs/plans/cw-plugin/`, `!docs/plans/cw-plugin/**`, drops the `scripts/` and the four `.claude/` allowlist lines (keep `!CLAUDE.md` and the `.claude/settings.json` rail); `.claude-plugin/plugin.json` (name cw, version 1.0.0, description, author name only, repository URL, license MIT, keywords); `.claude-plugin/marketplace.json` (name `claude-code-setup`, owner name, one entry `cw`, source `./` — or `.` if `claude plugin validate .` rejects `./`); `hooks/hooks.json` per D2.4 (no `if` fields; SessionStart matcher `startup|resume|clear|fork`); `hooks/profile-check.sh` (new, per D2.4: always exit 0, always the JSON context line, notices in `systemMessage` and `additionalContext`, `~`/relative import targets, comments and malformed profile lines skipped); `hooks/protect-branches.sh` rewritten from the LIVE copy (`~/.claude/hooks/`) with segment splitting on `&&`/`||`/`;`/`|`/newline, no opt-out, and every `EXEMPT` line removed (the block and its four later branch points); `hooks/protect-secrets.sh` from the LIVE copy with the `notebook_path` fallback, the template allowlist moved after the directory checks, and without the personal comment — write this file with a Bash heredoc, never with Write or Edit (the live secrets hook blocks any `*secret*` path); every script's jq check warns on stderr and exits 0 when jq is missing; all three scripts shellcheck-clean at the default severity (fix the findings the live copies carry); delete the three dead hook scripts.
+- files_owned: [.gitignore, .claude-plugin/plugin.json, .claude-plugin/marketplace.json, hooks/hooks.json, hooks/profile-check.sh, hooks/protect-branches.sh, hooks/protect-secrets.sh, hooks/orchestrator-delegate-guard.sh, hooks/design-scope-guard.sh, hooks/syntax-check.sh]
+- files_forbidden: [skills/**, agents/**, rules/**, tests/**, scripts/**, README.md, WORKFLOW.md, CLAUDE.md, settings.example.json, .github/**]
+- depends_on: none
+- agent: implementer
+- model: sonnet
+- risk: high
+- verification: `ROOT=$(git rev-parse --show-toplevel); ! git -C "$ROOT" check-ignore -q .claude-plugin/plugin.json && ! git -C "$ROOT" check-ignore -q docs/plans/cw-plugin/probe && ! git -C "$ROOT" check-ignore -q docs/plans/other.md && git -C "$ROOT" check-ignore -q docs/plans/other/probe`; after the commit `git ls-files --error-unmatch .claude-plugin/plugin.json .claude-plugin/marketplace.json hooks/hooks.json hooks/profile-check.sh`; `jq empty .claude-plugin/plugin.json .claude-plugin/marketplace.json hooks/hooks.json`; `jq -e '.name=="cw" and .version=="1.0.0"' .claude-plugin/plugin.json`; `jq -e '.name=="claude-code-setup" and .plugins[0].name=="cw" and .plugins[0].source=="./"' .claude-plugin/marketplace.json`; `jq -e '(.hooks.PreToolUse|length)==2 and (.hooks.SessionStart|length)==1' hooks/hooks.json`; `jq -r '..|objects|.command? // empty' hooks/hooks.json | grep -c CLAUDE_PLUGIN_ROOT` = 3; `test "$(jq '[..|objects|select(has("if"))]|length' hooks/hooks.json)" = 0`; `jq -r '.hooks.PreToolUse[].matcher' hooks/hooks.json | grep -q NotebookEdit`; `ls hooks | tr '\n' ' '` = `hooks.json profile-check.sh protect-branches.sh protect-secrets.sh `; `shellcheck -x hooks/*.sh`; `printf '{"tool_name":"Bash","tool_input":{"command":"git push origin main"},"cwd":"/tmp"}' | bash hooks/protect-branches.sh; test $? -eq 2`; `printf '{"tool_name":"Bash","tool_input":{"command":"cd /tmp && git push origin main"},"cwd":"/tmp"}' | bash hooks/protect-branches.sh; test $? -eq 2`; `printf '{"tool_name":"Bash","tool_input":{"command":"git push -u origin feat/x"},"cwd":"/tmp"}' | bash hooks/protect-branches.sh`; `printf '{"tool_name":"Bash","tool_input":{"command":"git push --force origin feat/x"},"cwd":"/tmp"}' | bash hooks/protect-branches.sh; test $? -eq 2`; `printf '{"tool_name":"Write","tool_input":{"file_path":"/tmp/x/.env"}}' | bash hooks/protect-secrets.sh; test $? -eq 2`; `printf '{"tool_name":"Write","tool_input":{"file_path":"/tmp/x/.env.example"}}' | bash hooks/protect-secrets.sh`; `printf '{"tool_name":"Write","tool_input":{"file_path":"/tmp/x/secrets/.env.example"}}' | bash hooks/protect-secrets.sh; test $? -eq 2`; `printf '{"tool_name":"NotebookEdit","tool_input":{"notebook_path":"/tmp/x/secrets.ipynb"}}' | bash hooks/protect-secrets.sh; test $? -eq 2`; `! grep -q EXEMPT hooks/protect-branches.sh`; `jq -r '.hooks.SessionStart[].matcher' hooks/hooks.json | grep -q fork`; `B=$(mktemp -d); for u in bash sh cat tr sed grep basename dirname printf readlink realpath cut head; do p=$(command -v $u) && ln -s "$p" "$B/$u"; done; printf '{"tool_name":"Bash","tool_input":{"command":"git push origin main"}}' | PATH=$B bash hooks/protect-branches.sh 2>&1 >/dev/null | grep -q 'jq not found'` (the scratch bin lacks jq; the hook must exit 0 and warn); `H=$(mktemp -d); printf '{"cwd":"/tmp","hook_event_name":"SessionStart"}' | HOME=$H CLAUDE_CONFIG_DIR=$H bash hooks/profile-check.sh | jq -e '.hookSpecificOutput.additionalContext|startswith("profile ")'`; `H=$(mktemp -d); mkdir -p $H/other; printf '# comment\nmalformed line\n/tmp/proj|%s/other\n' "$H" > $H/.claude-profiles; printf '{"cwd":"/tmp/proj/sub","hook_event_name":"SessionStart"}' | HOME=$H CLAUDE_CONFIG_DIR=$H bash hooks/profile-check.sh | jq -e '.systemMessage|test("wrong profile")'`; `H=$(mktemp -d); printf '@rules/x.md\n' > $H/CLAUDE.md; printf '{"cwd":"/tmp","hook_event_name":"SessionStart"}' | HOME=$H CLAUDE_CONFIG_DIR=$H bash hooks/profile-check.sh | jq -e '.systemMessage|test("missing import")'` (each hook exits 0); `! grep -rqnE '/(Users|home)/' hooks`; `! grep -rqniEf "$CW_SCAN_PATTERNS" hooks .claude-plugin .gitignore`; `claude plugin validate .` exits 0; `CFG=$(mktemp -d); mkdir -p "$CFG/skills"; ln -s "$PWD" "$CFG/skills/cw"; env CLAUDE_CONFIG_DIR="$CFG" claude plugin list | grep -q 'cw@skills-dir'`
+- commit: feat(plugin): cw manifest, hooks.json, profile check, lean protect hooks
+
+## Task T2
+- scope: `tests/run.sh` per D2.6 (`hooks` with the fifteen cases under a scratch HOME and CLAUDE_CONFIG_DIR, asserting exit codes and JSON fields with `jq -e`; `size` with the `BASELINE_BYTES=73738` constant, per-file caps (150; 200 for design and build), the WORKFLOW cap and the description cap in full mode; `dedupe`; `scan` with the `$CW_SCAN_PATTERNS` default, `--history`, `--report`, `-p`, pathspec pass-through; `all`); `tests/dedupe-phrases.txt` (the 15 clusters of D2.2, one fixed string each); delete the six bats suites, the helper, the checklist, `scripts/`, `.claude/skills/setup/`; rewrite `.github/workflows/ci.yml` per D2.6 (jobs `ubuntu` incl. the unauthenticated `claude plugin validate .` step, and `macos`).
+- files_owned: [tests/run.sh, tests/dedupe-phrases.txt, tests/check.bats, tests/hooks.bats, tests/install.bats, tests/merge-settings.bats, tests/merge-claude-md.bats, tests/e2e.bats, tests/test_helper.bash, tests/manual-setup-checklist.md, scripts/**, .claude/skills/setup/**, .github/workflows/ci.yml]
+- files_forbidden: [hooks/**, skills/**, agents/**, rules/**, README.md, WORKFLOW.md, CLAUDE.md, settings.example.json, tests/settings-keys.txt, .gitignore, .claude-plugin/**]
+- depends_on: [T1]
+- agent: implementer
+- model: sonnet
+- risk: normal
+- verification: `bash tests/run.sh hooks` exits 0 and prints 15 passes; `bash tests/run.sh size 1 --only rules; test $? -eq 1` (expected exit 1: the ratio exceeds 100%); `bash tests/run.sh size 99999999 --only rules` exits 0 (rules/orchestration.md is 47 lines; the not-yet-rewritten skills are excluded on purpose); `bash tests/run.sh dedupe; test $? -le 1` (runs; exits 0 only after T5); `P=$(mktemp); echo 'zzz-no-such-string' > $P; bash tests/run.sh scan $P` exits 0; `echo 'shellcheck' > $P; ! bash tests/run.sh scan $P`; `echo 'shellcheck' > $P; bash tests/run.sh scan $P --report` exits 0 and prints a hit; `echo 'zzz-no-such-string' > $P; bash tests/run.sh scan $P --history main..HEAD` exits 0; `D=$(mktemp -d); echo shellcheck > $D/f; echo 'shellcheck' > $P; ! bash tests/run.sh scan $P -p $D`; `bash tests/run.sh scan` exits 0 (uses `$CW_SCAN_PATTERNS`); `bash tests/run.sh all; test $? -le 1` (fails on the old skills' size caps until T5; exits 0 after T6); `wc -l < tests/dedupe-phrases.txt` = 15; `! ls tests | grep -q bats`; `test ! -f tests/test_helper.bash && test ! -d scripts && test ! -d .claude/skills`; `grep -q shellcheck .github/workflows/ci.yml && grep -q 'run.sh all' .github/workflows/ci.yml && grep -q 'macos' .github/workflows/ci.yml && grep -q 'plugin validate' .github/workflows/ci.yml`; `shellcheck -x tests/run.sh`
+- commit: test: run.sh hook, size, dedupe and scan checks; retire the installer
+
+## Task T3
+- scope: `rules/workflow.md` (≤40 lines; base the LIVE `~/.claude/CLAUDE.md` workflow, research-first and context-hygiene rules plus the design-document convention of D2.5; no identity or stack lines) and `rules/orchestration.md` (≤60 lines; base LIVE; anti-ratchet kept; capitals removed; "the user" instead of a name); `rules/google-workspace.md` is not in the repo (the content moves in T5).
+- files_owned: [rules/workflow.md, rules/orchestration.md]
+- files_forbidden: [skills/**, agents/**, hooks/**, tests/**, README.md, WORKFLOW.md, CLAUDE.md]
+- depends_on: [T2]
+- agent: implementer
+- model: opus
+- risk: high
+- verification: `wc -l < rules/workflow.md` ≤ 40; `wc -l < rules/orchestration.md` ≤ 60; `grep -q 'anti-ratchet' rules/orchestration.md && grep -q 'NO_VERDICT' rules/orchestration.md`; `grep -q 'Co-Authored-By' rules/workflow.md && grep -q 'docs/plans' rules/workflow.md && grep -qi 'context7' rules/workflow.md && grep -qi 'checkpoint' rules/workflow.md`; `! grep -rqwE 'NEVER|ALWAYS|MUST|CRITICAL' rules`; `! grep -rqi 'under 50 lines' rules`; `N=$(sed -n 's/^Copyright (c) [0-9]* //p' LICENSE | cut -d' ' -f1); ! grep -rqi "$N" rules`; `test ! -f rules/google-workspace.md`; `bash tests/run.sh dedupe --only rules` exits 0; `bash tests/run.sh size 99999999 --only rules` exits 0; `bash tests/run.sh scan -- rules` exits 0
+- commit: refactor(rules): one home per rule, lean workflow and orchestration files
+
+## Task T4
+- scope: Rewrite the five agents per D2.3 from the repo copies (namespaced as `cw:` in prose, verdict JSON schema in `reviewer.md`, "the user" instead of a name, no `permissionMode`, `mcpServers`, `hooks` or `skills` keys); delete `agents/Explore.md`.
+- files_owned: [agents/implementer.md, agents/reviewer.md, agents/researcher.md, agents/design-reviewer.md, agents/direction-reviewer.md, agents/Explore.md]
+- files_forbidden: [skills/**, hooks/**, rules/**, tests/**]
+- depends_on: [T3]
+- agent: implementer
+- model: sonnet
+- risk: normal
+- verification: `ls agents | wc -l` = 5; `grep -q '^model: sonnet' agents/implementer.md && grep -q '^model: sonnet' agents/researcher.md && grep -q '^model: opus' agents/reviewer.md && grep -q '^model: opus' agents/design-reviewer.md && grep -q '^model: opus' agents/direction-reviewer.md`; `grep -q '^effort: medium' agents/researcher.md && grep -q '^effort: xhigh' agents/direction-reviewer.md && grep -q '^effort: high' agents/implementer.md && grep -q '^effort: high' agents/reviewer.md && grep -q '^effort: high' agents/design-reviewer.md`; `test $(grep -l '^maxTurns:' agents/*.md | wc -l) -eq 5 && test $(grep -l '^tools:' agents/*.md | wc -l) -eq 5`; `! grep -rqnE '^(disallowedTools|permissionMode|mcpServers|hooks|skills):' agents` (no agent keeps a `skills:` preload, D2.3); `grep -l 'memory: project' agents/*reviewer*.md | wc -l` = 3; `grep -q '"verdict"' agents/reviewer.md`; `wc -l agents/*.md | awk '$2!="total" && $1>150{exit 1}'`; `! grep -rqniE 'do not trust|be decisive|do not invent|double-check|under 50 lines' agents`; `N=$(sed -n 's/^Copyright (c) [0-9]* //p' LICENSE | cut -d' ' -f1); ! grep -rqi "$N" agents`; `! grep -rqwE 'NEVER|ALWAYS|MUST|CRITICAL' agents`; `bash tests/run.sh dedupe --only agents` exits 0; `bash tests/run.sh scan -- agents` exits 0
+- commit: refactor(agents): claude 5 model and effort matrix, lean prompts
+
+## Task T5
+- scope: Rewrite design, build, ship, compound and search from the repo copies per D2.2 and D2.5 (`cw:` names; design writes the single plan file and Step 6 moves it to `docs/plans/<slug>.md`, `effort: xhigh`, Explore calls with `model: haiku`, no sentinel, no promotion, no `git clean` grant; build reads `docs/plans/<slug>.md` with the folder-layout fallback, supports `continue [<task-id>]` by skipping tasks whose commit subject is already in `git log main..HEAD`, commits `docs(<slug>): design` through git, no `.gitattributes` write, no sentinel, the one-sentence delegation boundary of D2.5 (no `disallowed-tools`: the P0 probe showed it strips the implementers' tools too), a checkpoint text that asks for `/cw:build <slug> continue`, `allowed-tools` per D2.5 without write tools; ship's gate detection adds `tests/run.sh` → `bash tests/run.sh all`; search `--deep` → bundled `/deep-research`; trigger phrases kept on design and search; `disable-model-invocation: true` kept on build, ship, compound; "the user" instead of a name); `skills/google-workspace/SKILL.md` from `~/.claude/rules/google-workspace.md` minus its four personal lines, model-invocable with trigger phrases; `tests/fixtures/two-task-plan.md` per the D2.6 contract.
+- files_owned: [skills/design/SKILL.md, skills/build/SKILL.md, skills/ship/SKILL.md, skills/compound/SKILL.md, skills/search/SKILL.md, skills/google-workspace/SKILL.md, tests/fixtures/two-task-plan.md]
+- files_forbidden: [agents/**, hooks/**, rules/**, tests/run.sh, tests/dedupe-phrases.txt, README.md, WORKFLOW.md, CLAUDE.md]
+- depends_on: [T4]
+- agent: implementer
+- model: opus
+- risk: high
+- verification: `ls skills | tr '\n' ' '` = `build compound design google-workspace search ship `; `grep -q '^effort: xhigh' skills/design/SKILL.md`; `grep -q haiku skills/design/SKILL.md`; `grep -l 'disable-model-invocation: true' skills/*/SKILL.md | wc -l` = 3; `grep -q 'cw:implementer' skills/build/SKILL.md && grep -q 'cw:reviewer' skills/build/SKILL.md`; `grep -q 'docs/plans/<slug>.md' skills/build/SKILL.md && grep -q -- '-tasks.md' skills/build/SKILL.md && grep -q 'continue' skills/build/SKILL.md && grep -q 'main..HEAD' skills/build/SKILL.md`; `grep -q 'docs/plans/<slug>.md' skills/design/SKILL.md`; `! grep -q '^disallowed-tools:' skills/build/SKILL.md && grep -q 'Bash(bash' skills/build/SKILL.md && ! awk '/^allowed-tools:/{f=1;next} f&&(/^[a-z-]+:/||/^---$/){f=0} f' skills/build/SKILL.md | grep -qE '^ *- *(Write|Edit|MultiEdit|NotebookEdit) *$'` (only the `allowed-tools` block is inspected; portable ERE); `grep -q 'tests/run.sh all' skills/ship/SKILL.md && grep -q 'Bash(bash' skills/ship/SKILL.md`; `grep -q 'deep-research' skills/search/SKILL.md`; `! grep -rqniE '~/.claude/plans|claude-design-active|claude-orchestrator-active|design-scope-guard|delegate-guard|gitattributes|linguist|git clean' skills`; `N=$(sed -n 's/^Copyright (c) [0-9]* //p' LICENSE | cut -d' ' -f1); ! grep -rqi "$N" skills`; `! grep -rqwE 'NEVER|ALWAYS|MUST|CRITICAL' skills`; `! grep -rqi 'under 50 lines' skills`; `wc -l skills/search/SKILL.md skills/compound/SKILL.md skills/google-workspace/SKILL.md | awk '$2!="total" && $1>150{exit 1}'`; `wc -l skills/design/SKILL.md skills/build/SKILL.md | awk '$2!="total" && $1>200{exit 1}'`; `bash tests/run.sh size --only skills,agents,rules` exits 0 (ratio reported, target ≤60%); `bash tests/run.sh dedupe` exits 0; `grep -c '^## Task' tests/fixtures/two-task-plan.md` = 2 && grep -q 'test -f a.txt' tests/fixtures/two-task-plan.md && grep -q 'feat: add b' tests/fixtures/two-task-plan.md`; `bash tests/run.sh scan -- skills tests/fixtures` exits 0
+- commit: refactor(skills): lean cw skills, single design document, google-workspace playbook
+
+## Task T6
+- scope: Rewrite README.md (incl. the changelog section with the `1.0.0` entry) and WORKFLOW.md per D2.7; replace the template `CLAUDE.md` by the project file of D2.1 (≤20 lines incl. `Tests: bash tests/run.sh all`); `settings.example.json` per D2.7; `tests/settings-keys.txt` from the settings reference (§R2.13) plus every key the example uses.
+- files_owned: [README.md, WORKFLOW.md, CLAUDE.md, settings.example.json, tests/settings-keys.txt]
+- files_forbidden: [skills/**, agents/**, hooks/**, rules/**, tests/run.sh, tests/dedupe-phrases.txt, tests/fixtures/**, .claude-plugin/**]
+- depends_on: [T5]
+- agent: implementer
+- model: sonnet
+- risk: normal
+- verification: `grep -q skills/cw README.md && grep -q 'marketplace add' README.md && grep -q -- '--plugin-dir' README.md && grep -q .claude-profiles README.md && grep -q plansDirectory README.md && grep -q jq README.md && grep -q 'plugin disable' README.md && grep -q acceptEdits README.md && grep -qi migration README.md`; `! grep -q '<you>' README.md`; `! grep -qE 'install.sh|merge-settings|/setup' README.md WORKFLOW.md`; `wc -l < WORKFLOW.md` ≤ 200; `grep -q 'tests/run.sh all' CLAUDE.md && grep -q 'docs/plans' CLAUDE.md && grep -q 'Co-Authored-By' CLAUDE.md && test $(wc -l < CLAUDE.md) -le 20`; `jq -e '.model=="fable" and .plansDirectory=="docs/plans" and (has("hooks")|not) and (.permissions.deny|length)>=6 and ([keys[]|select(startswith("_"))]|length)==0' settings.example.json`; `comm -23 <(jq -r 'keys[]' settings.example.json | sort) <(sort tests/settings-keys.txt)` empty; `grep -qx model tests/settings-keys.txt && grep -qx plansDirectory tests/settings-keys.txt && grep -qx forceLoginOrgUUID tests/settings-keys.txt`; `grep -q '1.0.0' README.md`; `bash tests/run.sh all` exits 0; `bash tests/run.sh scan -- README.md WORKFLOW.md CLAUDE.md settings.example.json tests/settings-keys.txt` exits 0
+- commit: docs: plugin install story, project CLAUDE.md and lean example settings
+
+## Task T7
+- scope: Release gate per D2.8, verification only (no file changes; `plugin.json` and the README changelog already carry 1.0.0): `git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'`; `bash tests/run.sh scan` (tree) and `bash tests/run.sh scan --history main..HEAD` must be clean; `bash tests/run.sh scan --history --all --report` hits listed in the exit report (history not rewritten); `claude plugin validate .`; `shellcheck -x hooks/*.sh tests/run.sh`; `bash tests/run.sh all`; the temp-config-dir inventory check of D6.2; the exit report lists every command's output.
+- files_owned: []
+- files_forbidden: [everything]
+- depends_on: [T6]
+- agent: implementer
+- model: sonnet
+- risk: normal
+- verification: D6.1, D6.2, D6.3, D6.4, D6.5 and D6.8 in full; `bash tests/run.sh scan --history main..HEAD` exits 0; `git status --short | wc -l` = 0
+- commit: none
+
+## Gate G-load (human)
+Criterion D6.6 (a) with `claude --plugin-dir <checkout>` from a scratch git repo under `/tmp`
+(copy `tests/fixtures/two-task-plan.md` there as `docs/plans/two-task.md` for the dry
+`/cw:build two-task`), then (b) from a temp config dir holding only `skills/cw -> <checkout>`
+(one-time login).
+Fix-ups: fresh `fix(<scope>):` commits, one per file group. Then the live `/ship`: its gate
+comes from the project CLAUDE.md (`bash tests/run.sh all`); its Step 1 flags the staged
+`hooks/protect-secrets.sh` as a `*secret*` match — expected, wave it through; accept or decline
+the `risk: high` panel; CI green; merge on GitHub; `git switch main && git pull`; the
+post-merge install check of D6.7. Plan A starts in a session at the private profile.

From 8ffe136b3ee1bfd370c0b54387f88d5804ef0579 Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Wed, 16 Sep 2026 15:50:55 +0100
Subject: [PATCH 02/24] feat(plugin): cw manifest, hooks.json, profile check,
 lean protect hooks

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .claude-plugin/marketplace.json      |  13 ++
 .claude-plugin/plugin.json           |  17 ++
 .gitignore                           |  33 ++--
 hooks/design-scope-guard.sh          | 127 --------------
 hooks/hooks.json                     |  38 ++++
 hooks/orchestrator-delegate-guard.sh | 128 --------------
 hooks/profile-check.sh               | 118 +++++++++++++
 hooks/protect-branches.sh            | 251 ++++++++++++++++++---------
 hooks/protect-secrets.sh             |  36 +++-
 hooks/syntax-check.sh                |  38 ----
 10 files changed, 396 insertions(+), 403 deletions(-)
 create mode 100644 .claude-plugin/marketplace.json
 create mode 100644 .claude-plugin/plugin.json
 delete mode 100755 hooks/design-scope-guard.sh
 create mode 100644 hooks/hooks.json
 delete mode 100755 hooks/orchestrator-delegate-guard.sh
 create mode 100755 hooks/profile-check.sh
 delete mode 100755 hooks/syntax-check.sh

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
new file mode 100644
index 0000000..cd81f34
--- /dev/null
+++ b/.claude-plugin/marketplace.json
@@ -0,0 +1,13 @@
+{
+  "name": "claude-code-setup",
+  "owner": {
+    "name": "Victor Kzam"
+  },
+  "plugins": [
+    {
+      "name": "cw",
+      "source": "./",
+      "description": "Claude Code workflow plugin: design/build/ship skills, orchestration agents, and guardrail hooks."
+    }
+  ]
+}
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
new file mode 100644
index 0000000..609980d
--- /dev/null
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,17 @@
+{
+  "name": "cw",
+  "version": "1.0.0",
+  "description": "Claude Code workflow plugin: design/build/ship skills, orchestration agents, and guardrail hooks.",
+  "author": {
+    "name": "Victor Kzam"
+  },
+  "repository": "https://github.com/victorkzam/claude-code-setup",
+  "license": "MIT",
+  "keywords": [
+    "workflow",
+    "hooks",
+    "skills",
+    "agents",
+    "orchestration"
+  ]
+}
diff --git a/.gitignore b/.gitignore
index 92dc379..ff11a10 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,33 +19,28 @@
 !skills/**
 !hooks/
 !hooks/**
-!scripts/
-!scripts/**
 !tests/
 !tests/**
 
-# Allow only the project-local design-artifact directories under docs/
-# (plans and research), not the whole docs/ tree. Gitignore requires
-# un-ignoring each parent directory level before its children, so the
-# chain below is intentionally explicit rather than a single !docs/**.
+# Track the plugin manifest directory.
+!.claude-plugin/
+!.claude-plugin/**
+
+# Allow the project-local design-artifact directories under docs/plans/:
+# a future single-file design doc (docs/plans/<slug>.md) and this build's
+# folder (docs/plans/cw-plugin/) are tracked; any other docs/plans/<other>/
+# folder stays ignored. Gitignore requires un-ignoring each parent directory
+# level before its children, so the chain below is intentionally explicit
+# rather than a single !docs/plans/**.
 !docs/
 !docs/plans/
-!docs/plans/**
-!docs/research/
-!docs/research/**
+!docs/plans/*.md
+!docs/plans/cw-plugin/
+!docs/plans/cw-plugin/**
 
 !.github/
 !.github/**
 
-# Allow the repo-scoped setup skill under .claude/, but nothing else in
-# .claude/ (agent-memory, local settings, etc. must stay ignored). Gitignore
-# requires un-ignoring each parent directory level before its children, so
-# the chain below is intentionally explicit rather than a single !.claude/**.
-!.claude/
-!.claude/skills/
-!.claude/skills/setup/
-!.claude/skills/setup/**
-
 # Never track local, personal, or generated Claude Code state, even if a
 # future copy step drops it in here by mistake.
 settings.json
@@ -59,5 +54,5 @@ history.jsonl
 .DS_Store
 
 # Security rail: this repo must never ship an active repo-local settings
-# file, even though .claude/ is partially un-ignored above.
+# file, even though other repo-local .claude paths may be tracked above.
 .claude/settings.json
diff --git a/hooks/design-scope-guard.sh b/hooks/design-scope-guard.sh
deleted file mode 100755
index 95dd728..0000000
--- a/hooks/design-scope-guard.sh
+++ /dev/null
@@ -1,127 +0,0 @@
-#!/bin/bash
-# PreToolUse(Write|Edit) scope guard. While /design is active for THIS session (its
-# short post-approval write window), edits are confined to design artifact paths.
-# Session-scoped + self-healing sentinel, structurally mirroring
-# hooks/orchestrator-delegate-guard.sh. Honest strength claim: the sentinel is
-# model-removable in principle — same trust class as the delegate guard.
-#
-# TTL_MINUTES: a sentinel older than this is treated as stale (a crashed/killed
-# /design) and reaped, then the edit is allowed. /design's write window is short,
-# so this is a generous ceiling rather than an expected duration.
-#
-# Residual limits (honest disclosure, not exhaustive):
-#  (a) this hook fires on PreToolUse(Write|Edit) only -- it does not intercept
-#      Bash, so `cp`/shell redirection/`ln -s` can still write outside the
-#      allowlist during the guarded window.
-#  (b) the require-absolute-path check below is defense-in-depth best practice,
-#      not a schema-guaranteed invariant of tool_input.file_path.
-#  (c) the checks below sit after the agent_type != main exemption, so this
-#      hardening is main-thread-only by design -- delegated subagent edits
-#      remain exempt.
-#  (d) matching is lexical (string prefix/glob) only, with no symlink
-#      resolution -- a symlink placed inside an allowlisted dir that points
-#      outside it defeats the allowlist; out of scope for a Write|Edit hook.
-#  (e) the project-relative allowances are anchored to the session project root
-#      derived from the payload cwd. cwd follows `cd` within the session, so
-#      this binds to the session's *current* project -- a real narrowing (an
-#      unrelated repo's docs/plans/ no longer matches), not cryptographic
-#      confinement.
-TTL_MINUTES=120
-
-INPUT=$(cat)
-
-# Fast path (no jq needed): if no sentinel file of any kind exists, /design is not
-# active anywhere on the machine, so there is nothing to guard — exit before we
-# need to parse anything. This is the common case for every edit outside a /design run.
-if ! ls /tmp/claude-design-active* >/dev/null 2>&1; then
-  exit 0
-fi
-
-# Past this point a sentinel might be active, so we need jq to read session_id /
-# agent_type / file_path from stdin. Fail closed rather than silently allowing
-# an edit the guard can no longer evaluate.
-command -v jq >/dev/null 2>&1 || { echo "jq required for this hook — install jq or remove it from settings.json" >&2; exit 2; }
-
-# Malformed JSON yields an empty session_id below, which collapses the sentinel
-# path to the unsuffixed legacy path; if nothing is there the sentinel loop
-# finds nothing and the hook would exit 0 at the sentinel stage BEFORE any
-# file_path check ever runs. Reject unparseable input here instead (fail closed).
-echo "$INPUT" | jq empty 2>/dev/null || { echo "design-scope-guard — unparseable hook input, refusing (fail closed)" >&2; exit 2; }
-
-SID=$(echo "$INPUT" | jq -r '.session_id // empty')
-SENTINEL="/tmp/claude-design-active${SID:+.$SID}"
-LEGACY="/tmp/claude-design-active"
-
-# Find an active, non-stale sentinel: prefer the session-scoped one, fall back to the
-# legacy global path for backward compatibility. Reap stale ones (self-heal).
-ACTIVE=""
-for S in "$SENTINEL" "$LEGACY"; do
-  [ -f "$S" ] || continue
-  if [ -n "$(find "$S" -mmin +"$TTL_MINUTES" 2>/dev/null)" ]; then
-    rm -f "$S"
-    continue
-  fi
-  ACTIVE="$S"; break
-done
-[ -n "$ACTIVE" ] || exit 0
-
-# agent_type is present in hook stdin only inside a subagent (per Claude Code hooks
-# docs; for custom agents it is the frontmatter `name`), absent on the main thread.
-# A delegated subagent is allowed to edit (accepted residual exemption).
-AGENT_TYPE=$(echo "$INPUT" | jq -r '.agent_type // empty')
-if [ -n "$AGENT_TYPE" ] && [ "$AGENT_TYPE" != "main" ]; then
-  exit 0
-fi
-
-FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.filePath // empty')
-
-[ -z "$FILE" ] && { echo "design-scope-guard — empty file_path, refusing (fail closed)" >&2; exit 2; }
-case "$FILE" in
-  ../*|*/../*|*/..|..) echo "design-scope-guard — path traversal (..) refused" >&2; exit 2 ;;
-esac
-case "$FILE" in
-  /*) ;;
-  *) echo "design-scope-guard — non-absolute path refused" >&2; exit 2 ;;
-esac
-
-# Anchor the project-relative allowances to THIS session's project root, so the
-# docs/plans/, docs/research/, and .gitattributes shapes cannot match an
-# unrelated repo elsewhere on disk. Derive the root from the payload cwd: git
-# toplevel when cwd is inside a repo, else cwd itself (bats fixtures aren't
-# repos). Sanitize first -- an empty, non-absolute, or ..-containing cwd yields
-# an empty ROOT, and the project-relative arm below is skipped entirely (fail
-# closed for that branch only) rather than collapsing "$ROOT"/... to a bare
-# /... glob.
-CWD=$(echo "$INPUT" | jq -r '.cwd // empty')
-ROOT=""
-case "$CWD" in
-  ""|../*|*/../*|*/..|..) ;;
-  /*) ROOT=$(git -C "$CWD" rev-parse --show-toplevel 2>/dev/null); [ -n "$ROOT" ] || ROOT="$CWD" ;;
-esac
-
-# /design may write plan and research artifacts, and the project-root
-# .gitattributes (skills/build writes only "$ROOT/.gitattributes" -- the
-# docs/plans/** linguist-generated marker -- so only the root file is allowed,
-# never */.gitattributes anywhere). These arms are root-anchored literal
-# prefixes, never bare */... globs (which this repo has repeatedly regressed
-# into an unanchored allowlist bypass).
-if [ -n "$ROOT" ]; then
-  case "$FILE" in
-    "$ROOT"/docs/plans/*|"$ROOT"/docs/research/*|"$ROOT"/.gitattributes) exit 0 ;;
-  esac
-fi
-
-# Config-dir and scratch allowances are not project-scoped and stay as-is. When
-# CLAUDE_CONFIG_DIR is set (adopters using a non-default config location), its
-# plans/ dir is editable too, alongside the default $HOME/.claude/plans/.
-case "$FILE" in
-  "$HOME"/.claude/plans/*|/tmp/*) exit 0 ;;
-esac
-if [ -n "$CLAUDE_CONFIG_DIR" ]; then
-  case "$FILE" in
-    "$CLAUDE_CONFIG_DIR"/plans/*) exit 0 ;;
-  esac
-fi
-
-echo "/design is active — writes are confined to this project's design artifact paths (${ROOT:-<no project root>}/docs/plans/, docs/research/, .gitattributes) plus the plans dir; paths outside the session project are refused" >&2
-exit 2
diff --git a/hooks/hooks.json b/hooks/hooks.json
new file mode 100644
index 0000000..644ffcb
--- /dev/null
+++ b/hooks/hooks.json
@@ -0,0 +1,38 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/protect-branches.sh\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/protect-secrets.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|fork",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/profile-check.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/hooks/orchestrator-delegate-guard.sh b/hooks/orchestrator-delegate-guard.sh
deleted file mode 100755
index e4d23cb..0000000
--- a/hooks/orchestrator-delegate-guard.sh
+++ /dev/null
@@ -1,128 +0,0 @@
-#!/bin/bash
-# PreToolUse(Write|Edit) delegation guard. While /build is active for THIS session, the
-# main-thread orchestrator must delegate source edits to the implementer subagent.
-# Session-scoped + self-healing — replaces the prior machine-global, never-expiring
-# sentinel that could permanently lock every project/session if /build was killed.
-# Mitigates anthropics/claude-code#51609.
-#
-# TTL_MINUTES: a sentinel older than this is treated as stale (a crashed/killed /build)
-# and reaped, then the edit is allowed. /build re-touches its sentinel at the start of
-# every task, so only a stalled/killed run trips this. Heuristic for tuning:
-# max(expected_task_count * 10, 45), capped at 120. This is the single adjustment point.
-#
-# Residual limits (honest disclosure, not exhaustive):
-#  (a) this hook fires on PreToolUse(Write|Edit) only -- it does not intercept
-#      Bash, so `cp`/shell redirection/`ln -s` can still write outside the
-#      allowlist during the guarded window.
-#  (b) the require-absolute-path check below is defense-in-depth best practice,
-#      not a schema-guaranteed invariant of tool_input.file_path.
-#  (c) the checks below sit after the agent_type != main exemption, so this
-#      hardening is main-thread-only by design -- delegated subagent edits
-#      remain exempt.
-#  (d) matching is lexical (string prefix/glob) only, with no symlink
-#      resolution -- a symlink placed inside an allowlisted dir that points
-#      outside it defeats the allowlist; out of scope for a Write|Edit hook.
-#  (e) the project-relative allowances are anchored to the session project root
-#      derived from the payload cwd. cwd follows `cd` within the session, so
-#      this binds to the session's *current* project -- a real narrowing (an
-#      unrelated repo's docs/plans/ no longer matches), not cryptographic
-#      confinement.
-TTL_MINUTES=90
-
-INPUT=$(cat)
-
-# Fast path (no jq needed): if no sentinel file of any kind exists, /build is not
-# active anywhere on the machine, so there is nothing to guard — exit before we
-# need to parse anything. This is the common case for every edit outside a /build run.
-if ! ls /tmp/claude-orchestrator-active* >/dev/null 2>&1; then
-  exit 0
-fi
-
-# Past this point a sentinel might be active, so we need jq to read session_id /
-# agent_type / file_path from stdin. Fail closed rather than silently allowing
-# an edit the guard can no longer evaluate.
-command -v jq >/dev/null 2>&1 || { echo "jq required for this hook — install jq or remove it from settings.json" >&2; exit 2; }
-
-# Malformed JSON yields an empty session_id below, which collapses the sentinel
-# path to the unsuffixed legacy path; if nothing is there the sentinel loop
-# finds nothing and the hook would exit 0 at the sentinel stage BEFORE any
-# file_path check ever runs. Reject unparseable input here instead (fail closed).
-echo "$INPUT" | jq empty 2>/dev/null || { echo "orchestrator-delegate-guard — unparseable hook input, refusing (fail closed)" >&2; exit 2; }
-
-SID=$(echo "$INPUT" | jq -r '.session_id // empty')
-SENTINEL="/tmp/claude-orchestrator-active${SID:+.$SID}"
-LEGACY="/tmp/claude-orchestrator-active"
-
-# Find an active, non-stale sentinel: prefer the session-scoped one, fall back to the
-# legacy global path for backward compatibility. Reap stale ones (self-heal).
-ACTIVE=""
-for S in "$SENTINEL" "$LEGACY"; do
-  [ -f "$S" ] || continue
-  if [ -n "$(find "$S" -mmin +"$TTL_MINUTES" 2>/dev/null)" ]; then
-    rm -f "$S"
-    continue
-  fi
-  ACTIVE="$S"; break
-done
-[ -n "$ACTIVE" ] || exit 0
-
-# agent_type is present in hook stdin only inside a subagent (per Claude Code hooks
-# docs; for custom agents it is the frontmatter `name`), absent on the main thread.
-# A delegated subagent (implementer/reviewer/...) is allowed to edit.
-AGENT_TYPE=$(echo "$INPUT" | jq -r '.agent_type // empty')
-if [ -n "$AGENT_TYPE" ] && [ "$AGENT_TYPE" != "main" ]; then
-  exit 0
-fi
-
-FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.filePath // empty')
-
-[ -z "$FILE" ] && { echo "orchestrator-delegate-guard — empty file_path, refusing (fail closed)" >&2; exit 2; }
-case "$FILE" in
-  ../*|*/../*|*/..|..) echo "orchestrator-delegate-guard — path traversal (..) refused" >&2; exit 2 ;;
-esac
-case "$FILE" in
-  /*) ;;
-  *) echo "orchestrator-delegate-guard — non-absolute path refused" >&2; exit 2 ;;
-esac
-
-# Anchor the project-relative allowances to THIS session's project root, so the
-# promoted docs/plans/, docs/research/, and .gitattributes shapes cannot match
-# an unrelated repo elsewhere on disk. Derive the root from the payload cwd: git
-# toplevel when cwd is inside a repo, else cwd itself (bats fixtures aren't
-# repos). Sanitize first -- an empty, non-absolute, or ..-containing cwd yields
-# an empty ROOT, and the project-relative arm below is skipped entirely (fail
-# closed for that branch only) rather than collapsing "$ROOT"/... to a bare
-# /... glob.
-CWD=$(echo "$INPUT" | jq -r '.cwd // empty')
-ROOT=""
-case "$CWD" in
-  ""|../*|*/../*|*/..|..) ;;
-  /*) ROOT=$(git -C "$CWD" rev-parse --show-toplevel 2>/dev/null); [ -n "$ROOT" ] || ROOT="$CWD" ;;
-esac
-
-# The orchestrator may still touch its own promoted plan/design drafts and the
-# project-root .gitattributes (skills/build writes only "$ROOT/.gitattributes"
-# -- the docs/plans/** linguist-generated marker -- so only the root file is
-# allowed, never */.gitattributes anywhere). These arms are root-anchored
-# literal prefixes, never bare */... globs (which this repo has repeatedly
-# regressed into an unanchored allowlist bypass).
-if [ -n "$ROOT" ]; then
-  case "$FILE" in
-    "$ROOT"/docs/plans/*|"$ROOT"/docs/research/*|"$ROOT"/.gitattributes) exit 0 ;;
-  esac
-fi
-
-# Config-dir and scratch allowances are not project-scoped and stay as-is. When
-# CLAUDE_CONFIG_DIR is set (adopters using a non-default config location), its
-# plans/ dir is editable too, alongside the default $HOME/.claude/plans/.
-case "$FILE" in
-  "$HOME"/.claude/plans/*|/tmp/*) exit 0 ;;
-esac
-if [ -n "$CLAUDE_CONFIG_DIR" ]; then
-  case "$FILE" in
-    "$CLAUDE_CONFIG_DIR"/plans/*) exit 0 ;;
-  esac
-fi
-
-echo "Blocked: /build is active (session ${SID:-global}); the orchestrator must not edit source files directly. Spawn an implementer subagent for this change. Plan files under ~/.claude/plans/ (or \$CLAUDE_CONFIG_DIR/plans/ if set) and, within THIS project (${ROOT:-<no project root>}), docs/plans/, docs/research/, and .gitattributes remain editable." >&2
-exit 2
diff --git a/hooks/profile-check.sh b/hooks/profile-check.sh
new file mode 100755
index 0000000..7c8bfb6
--- /dev/null
+++ b/hooks/profile-check.sh
@@ -0,0 +1,118 @@
+#!/bin/bash
+# SessionStart(startup|resume|clear|fork) — surface profile-config mismatches
+# and missing CLAUDE.md imports as a SessionStart notice. Always exits 0
+# (exit 2 would block session initialization) and always prints exactly one
+# JSON line to stdout, even on an internal error.
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "cw: jq not found, hook skipped" >&2
+  printf '%s\n' '{}'
+  exit 0
+fi
+
+OUT='{}'
+# shellcheck disable=SC2329 # invoked indirectly via `trap ... EXIT` below
+finish() {
+  printf '%s\n' "$OUT"
+  exit 0
+}
+trap finish EXIT
+
+INPUT=$(cat 2>/dev/null)
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // empty' 2>/dev/null)
+[ -z "$CWD" ] && CWD="$PWD"
+
+HOME_DIR="${HOME:-/root}"
+ACTIVE="${CLAUDE_CONFIG_DIR:-$HOME_DIR/.claude}"
+
+expand_tilde() {
+  # shellcheck disable=SC2088 # intentional literal-~ pattern match, not expansion
+  case "$1" in
+    "~") printf '%s' "$HOME_DIR" ;;
+    "~/"*) rest=${1#??}; printf '%s/%s' "$HOME_DIR" "$rest" ;;
+    *) printf '%s' "$1" ;;
+  esac
+}
+
+# realpath-style resolution; fall back to the raw string if it doesn't exist.
+resolve_dir() {
+  if [ -d "$1" ]; then
+    ( cd "$1" 2>/dev/null && pwd -P ) || printf '%s' "$1"
+  else
+    printf '%s' "$1"
+  fi
+}
+
+NOTICES=()
+
+PROFILES_FILE="$HOME_DIR/.claude-profiles"
+if [ -f "$PROFILES_FILE" ]; then
+  BEST_PREFIX=""
+  BEST_DIR=""
+  while IFS= read -r pline || [ -n "$pline" ]; do
+    case "$pline" in
+      \#*) continue ;;
+    esac
+    case "$pline" in
+      *'|'*) ;;
+      *) continue ;;
+    esac
+    prefix="${pline%%|*}"
+    dir="${pline#*|}"
+    prefix=$(expand_tilde "$prefix")
+    dir=$(expand_tilde "$dir")
+    case "$CWD" in
+      "$prefix"|"$prefix"/*)
+        if [ ${#prefix} -gt ${#BEST_PREFIX} ]; then
+          BEST_PREFIX="$prefix"
+          BEST_DIR="$dir"
+        fi
+        ;;
+    esac
+  done < "$PROFILES_FILE"
+
+  if [ -n "$BEST_PREFIX" ]; then
+    RES_BEST=$(resolve_dir "$BEST_DIR")
+    RES_ACTIVE=$(resolve_dir "$ACTIVE")
+    if [ "$RES_BEST" != "$RES_ACTIVE" ]; then
+      NOTICES+=( "wrong profile: $CWD maps to $BEST_DIR" )
+    fi
+  fi
+fi
+
+CLAUDE_MD="$ACTIVE/CLAUDE.md"
+if [ -f "$CLAUDE_MD" ]; then
+  while IFS= read -r cline || [ -n "$cline" ]; do
+    case "$cline" in
+      @*)
+        tgt="${cline#@}"
+        tgt=$(printf '%s' "$tgt" | sed -e 's/[[:space:]]*$//')
+        tgt=$(expand_tilde "$tgt")
+        case "$tgt" in
+          /*) : ;;
+          *) tgt="$ACTIVE/$tgt" ;;
+        esac
+        [ -e "$tgt" ] || NOTICES+=( "missing import: $tgt" )
+        ;;
+    esac
+  done < "$CLAUDE_MD"
+fi
+
+if [ ${#NOTICES[@]} -gt 0 ]; then
+  MSG=""
+  for n in "${NOTICES[@]}"; do
+    if [ -z "$MSG" ]; then
+      MSG="$n"
+    else
+      MSG="$MSG; $n"
+    fi
+  done
+  OUT=$(jq -nc --arg msg "$MSG" \
+    '{systemMessage: $msg, hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $msg}}')
+else
+  BASE=$(basename "$ACTIVE")
+  OUT=$(jq -nc --arg ctx "profile $BASE · plugin cw" \
+    '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $ctx}}')
+fi
+
+exit 0
diff --git a/hooks/protect-branches.sh b/hooks/protect-branches.sh
index 1b05772..a5690fa 100755
--- a/hooks/protect-branches.sh
+++ b/hooks/protect-branches.sh
@@ -1,97 +1,184 @@
 #!/bin/bash
-# PreToolUse(Bash, git *) — block pushes whose DESTINATION is main/master, and force
-# pushes. Blocks by destination, never by a branch-name substring, so a feature branch
-# whose name merely contains "main"/"master" (e.g. `git push -u origin feat/main-nav`)
-# is allowed. Tokenizes the command so `git -C <dir> push`, `git -c k=v push`,
-# `git --git-dir=... push`, `env X=Y git push`, `/usr/bin/git push` are all recognized.
-# `/ship`'s "refuse if on main" is the backstop for the refspec-less heuristic.
+# PreToolUse(Bash) — block pushes whose DESTINATION is main/master, and force
+# pushes. Blocks by destination, never by a branch-name substring, so a feature
+# branch whose name merely contains "main"/"master" (e.g. `git push -u origin
+# feat/main-nav`) is allowed. Backslash-newline continuations are joined, then
+# the command is split into segments on &&, ||, ;, |, (, ), and newlines, and
+# each segment is tokenized independently (with one layer of surrounding
+# quotes stripped from each token) so chained/grouped commands like
+# `(cd /tmp && git push origin main)` are still caught. Each segment's tokens
+# are scanned for a `git` invocation, tolerating leading env assignments
+# (FOO=bar) and global options (-C <dir>, -c k=v, ...) before the subcommand.
 
-# Fail closed: this hook parses tool input with jq. Without jq we cannot safely
-# decide, so block rather than silently letting an unchecked push through.
-command -v jq >/dev/null 2>&1 || { echo "jq required for this hook — install jq or remove it from settings.json" >&2; exit 2; }
+if ! command -v jq >/dev/null 2>&1; then
+  echo "cw: jq not found, hook skipped" >&2
+  exit 0
+fi
 
 INPUT=$(cat)
 CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
 CWD=$(echo "$INPUT" | jq -r '.cwd // empty')
 
-# Flatten newlines so a one-line `read -a` tokenization sees the whole command.
-CMD_FLAT=$(printf '%s' "$CMD" | tr '\n\t' '  ')
-read -r -a TOK <<< "$CMD_FLAT"
-n=${#TOK[@]}
-
-# Locate a `git` invocation and its subcommand, tolerating leading env assignments
-# (FOO=bar), an absolute path to git, and global options before the subcommand.
-is_push=0
-i=0
-while [ $i -lt $n ]; do
-  t="${TOK[$i]}"
-  case "$t" in
-    *=*) i=$((i+1)); continue ;;            # leading env assignment
-  esac
-  if [ "$t" = "git" ] || [ "${t##*/}" = "git" ]; then
-    j=$((i+1))
-    while [ $j -lt $n ]; do
-      a="${TOK[$j]}"
-      case "$a" in
-        -C) GITDIR="${TOK[$((j+1))]}"; j=$((j+2)); continue ;;   # capture repo dir
-        -c|--git-dir|--work-tree|--namespace|--exec-path|-o|--push-option|--repo)
-          j=$((j+2)); continue ;;           # option that consumes a separate-word arg
-        --*=*|-*) j=$((j+1)); continue ;;   # single-token option (incl. --opt=val)
-        push) is_push=1; REF=( "${TOK[@]:$((j+1))}" ); break ;;
-        *) break ;;                          # a different subcommand (log/commit/...)
-      esac
-    done
-    break
-  fi
-  i=$((i+1))
-done
-[ "$is_push" = 1 ] || exit 0
+TAB="$(printf '\t')"
 
 block() { echo "Blocked: $1" >&2; exit 2; }
 
-# Collect positional (non-option) args after `push`; flag force options.
-pos=()
-k=0; m=${#REF[@]}
-while [ $k -lt $m ]; do
-  a="${REF[$k]}"
-  case "$a" in
-    --force|--force-with-lease|--force-with-lease=*|--force-if-includes|-f)
-      block "force push is not allowed." ;;
-    -o|--push-option|--repo) k=$((k+2)); continue ;;   # option + its arg
-    --*=*|-*) k=$((k+1)); continue ;;                  # other option
-    *) pos+=( "$a" ); k=$((k+1)) ;;
-  esac
-done
-
-# Destination checks over positional tokens (remote, refspecs, bare refs).
-has_explicit_ref=0
-for p in "${pos[@]}"; do
-  case "$p" in
-    *:*)                                   # src:dst (or +src:dst, :dst)
-      dst="${p##*:}"; dst="${dst#refs/heads/}"
-      has_explicit_ref=1
-      { [ "$dst" = main ] || [ "$dst" = master ]; } && block "push destination is main/master. Use a feature branch." ;;
-    *)
-      base="${p#refs/heads/}"
-      if [ "$base" = main ] || [ "$base" = master ]; then
-        block "pushing to main/master is not allowed. Use a feature branch."
+# Splits $1 on whitespace into the global array TOK. A single- or double-
+# quoted span is treated as part of the current word and that one layer of
+# quoting is stripped (e.g. "main" -> main). Not a full shell parser: nested
+# shells (bash -c "..."), escaped quotes, and multi-quote-region words are
+# out of scope.
+tokenize() {
+  s="$1"
+  i=0
+  n=${#s}
+  q=""
+  buf=""
+  started=0
+  TOK=()
+  while [ "$i" -lt "$n" ]; do
+    c="${s:$i:1}"
+    if [ -n "$q" ]; then
+      if [ "$c" = "$q" ]; then
+        q=""
+      else
+        buf="$buf$c"
       fi
-      # A bare ref like HEAD or a branch name counts as explicit (not refspec-less),
-      # except a lone remote name. We treat anything that is not clearly the remote
-      # conservatively: HEAD or a slash/feature ref => explicit.
-      case "$p" in HEAD|*/*) has_explicit_ref=1 ;; esac ;;
-  esac
-done
+    elif [ "$c" = '"' ] || [ "$c" = "'" ]; then
+      q="$c"
+      started=1
+    elif [ "$c" = " " ] || [ "$c" = "$TAB" ]; then
+      if [ "$started" = 1 ]; then
+        TOK+=( "$buf" )
+        buf=""
+        started=0
+      fi
+    else
+      buf="$buf$c"
+      started=1
+    fi
+    i=$((i+1))
+  done
+  [ "$started" = 1 ] && TOK+=( "$buf" )
+}
+
+check_segment() {
+  seg="$1"
+  tokenize "$seg"
+  n=${#TOK[@]}
+
+  is_push=0
+  GITDIR=""
+  i=0
+  while [ "$i" -lt "$n" ]; do
+    t="${TOK[$i]}"
+    case "$t" in
+      *=*) i=$((i+1)); continue ;;            # leading env assignment
+    esac
+    if [ "$t" = "git" ] || [ "${t##*/}" = "git" ]; then
+      j=$((i+1))
+      while [ "$j" -lt "$n" ]; do
+        a="${TOK[$j]}"
+        case "$a" in
+          -C) GITDIR="${TOK[$((j+1))]}"; j=$((j+2)); continue ;;   # capture repo dir
+          -c|--git-dir|--work-tree|--namespace|--exec-path|-o|--push-option|--repo)
+            j=$((j+2)); continue ;;           # option that consumes a separate-word arg
+          --*=*|-*) j=$((j+1)); continue ;;   # single-token option (incl. --opt=val)
+          push) is_push=1; REF=( "${TOK[@]:$((j+1))}" ); break ;;
+          *) break ;;                          # a different subcommand (log/commit/...)
+        esac
+      done
+      break
+    fi
+    i=$((i+1))
+  done
+  [ "$is_push" = 1 ] || return 0
 
-# Refspec-less push (`git push`, `git push origin`, `git push -u origin HEAD`):
-# resolve the current branch and block if it is main/master. If git resolution
-# fails (not a repo), do NOT block — /ship is the backstop.
-npos=${#pos[@]}
-if [ "$has_explicit_ref" = 0 ] && { [ "$npos" -le 1 ] || [ "${pos[*]: -1}" = "HEAD" ]; }; then
-  BR=$(git -C "${GITDIR:-${CWD:-.}}" rev-parse --abbrev-ref HEAD 2>/dev/null)
-  if [ "$BR" = "main" ] || [ "$BR" = "master" ]; then
-    block "current branch is $BR; push from a feature branch."
+  # Collect positional (non-option) args after `push`; flag force options and
+  # `+`-prefixed (forced) refspecs.
+  pos=()
+  k=0; m=${#REF[@]}
+  while [ "$k" -lt "$m" ]; do
+    a="${REF[$k]}"
+    case "$a" in
+      --force|--force-if-includes|--force-with-lease|--force-with-lease=*)
+        block "force push is not allowed." ;;
+      -o|--push-option|--repo)
+        k=$((k+2)); continue ;;               # option that consumes a separate-word arg
+      -[A-Za-z]*)
+        case "$a" in *f*) block "force push is not allowed." ;; esac
+        k=$((k+1)); continue ;;               # short-option cluster without -f
+      --*)
+        k=$((k+1)); continue ;;               # other long option (incl. --opt=val)
+      -*)
+        k=$((k+1)); continue ;;               # any other dash token
+      +*)
+        block "force push (+ refspec) is not allowed." ;;
+      *)
+        pos+=( "$a" ); k=$((k+1)) ;;
+    esac
+  done
+
+  # Destination checks over positional tokens (remote, refspecs, bare refs).
+  has_explicit_ref=0
+  for p in "${pos[@]}"; do
+    case "$p" in
+      *:*)                                   # src:dst (or :dst)
+        dst="${p##*:}"; dst="${dst#refs/heads/}"
+        has_explicit_ref=1
+        { [ "$dst" = main ] || [ "$dst" = master ]; } && block "push destination is main/master. Use a feature branch." ;;
+      *)
+        base="${p#refs/heads/}"
+        if [ "$base" = main ] || [ "$base" = master ]; then
+          block "pushing to main/master is not allowed. Use a feature branch."
+        fi
+        # A bare branch-name ref (contains a slash) counts as an explicit
+        # destination. A bare `HEAD` does not: it still resolves against the
+        # current branch of the repo at cwd, same as a refspec-less push.
+        case "$p" in */*) has_explicit_ref=1 ;; esac ;;
+    esac
+  done
+
+  # Refspec-less push (`git push`, `git push origin`, `git push -u origin
+  # HEAD`): resolve the current branch and block if it is main/master. If git
+  # resolution fails (not a repo), do NOT block — /ship is the backstop.
+  npos=${#pos[@]}
+  if [ "$has_explicit_ref" = 0 ] && { [ "$npos" -le 1 ] || [ "${pos[*]: -1}" = "HEAD" ]; }; then
+    BR=$(git -C "${GITDIR:-${CWD:-.}}" rev-parse --abbrev-ref HEAD 2>/dev/null)
+    if [ "$BR" = "main" ] || [ "$BR" = "master" ]; then
+      block "current branch is $BR; push from a feature branch."
+    fi
   fi
-fi
+  return 0
+}
+
+# Join backslash-newline continuations into a single space. Done with a plain
+# bash read loop, not `sed N`, because BSD sed's N silently drops the final
+# line when the input has no trailing newline (as $CMD does not).
+CMD_JOINED=""
+while IFS= read -r jline || [ -n "$jline" ]; do
+  if [ -z "$CMD_JOINED" ]; then
+    CMD_JOINED="$jline"
+  else
+    case "$CMD_JOINED" in
+      *\\) CMD_JOINED="${CMD_JOINED%\\} $jline" ;;
+      *) CMD_JOINED="$CMD_JOINED
+$jline" ;;
+    esac
+  fi
+done <<EOF
+$CMD
+EOF
+
+# Split the command into segments on &&, ||, ;, |, (, ), and newlines,
+# tab-flatten each segment, then check every segment independently.
+CMD_SEGMENTED=$(printf '%s' "$CMD_JOINED" | sed -e 's/&&/\n/g' -e 's/||/\n/g' -e 's/;/\n/g' -e 's/|/\n/g' -e 's/(/\n/g' -e 's/)/\n/g')
+while IFS= read -r line; do
+  seg_flat=$(printf '%s' "$line" | tr '\t' ' ')
+  [ -z "${seg_flat// /}" ] && continue
+  check_segment "$seg_flat"
+done <<EOF
+$CMD_SEGMENTED
+EOF
 
 exit 0
diff --git a/hooks/protect-secrets.sh b/hooks/protect-secrets.sh
index bfef67c..c2e96dd 100755
--- a/hooks/protect-secrets.sh
+++ b/hooks/protect-secrets.sh
@@ -1,23 +1,41 @@
 #!/bin/bash
-# PreToolUse(Write|Edit) — block edits to secret / credential / key material.
-# Patterns broadened from gitleaks/trufflehog default rule families. Path is
-# lowercased first so .PEM / Config.SWIFT / .Env are caught too.
+# PreToolUse(Write|Edit|MultiEdit|NotebookEdit) — block edits to secret /
+# credential / key material. Patterns broadened from gitleaks/trufflehog
+# default rule families. Path is lowercased first so .PEM / Config.SWIFT /
+# .Env are caught too. Directory checks run before the template allowlist so
+# a template-named file inside a secrets/.ssh/.aws directory still blocks.
 
-# Fail closed: this hook parses tool input with jq. Without jq we cannot safely
-# decide, so block rather than silently letting an unchecked edit through.
-command -v jq >/dev/null 2>&1 || { echo "jq required for this hook — install jq or remove it from settings.json" >&2; exit 2; }
+if ! command -v jq >/dev/null 2>&1; then
+  echo "cw: jq not found, hook skipped" >&2
+  exit 0
+fi
 
 INPUT=$(cat)
-FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.filePath // empty')
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.filePath // .tool_input.notebook_path // empty')
 [ -z "$FILE" ] && exit 0
 LC=$(echo "$FILE" | tr '[:upper:]' '[:lower:]')
 
+# Directory checks first: anything under secrets/, .ssh/, or .aws/ is blocked
+# regardless of filename, even a template-allowlisted name.
+case "$LC" in
+  */secrets/*|*/.ssh/*|*/.aws/*|secrets/*|.ssh/*|.aws/*|*/.gnupg/*|.gnupg/*)
+    echo "Blocked: cannot edit sensitive file: $FILE" >&2
+    exit 2
+    ;;
+esac
+
+# Allowlist: secret-file TEMPLATES that carry key NAMES only, never values.
+case "$(basename "$LC")" in
+  .env.example|.env.sample|.env.template|env.example)
+    exit 0
+    ;;
+esac
+
 case "$LC" in
   *.env|*.env.*|*.envrc|*credentials*|*secret*|*config.swift| \
   *.pem|*.key|*.p8|*.pfx|*.jks|*.keystore| \
   *id_rsa*|*id_ed25519*| \
-  */.aws/credentials|*/.aws/config|*aws_secret*| \
-  */secrets/*|*/.ssh/*|*/.gnupg/*| \
+  *.gnupg/*| \
   *service-account*.json|*gcp*key*.json)
     echo "Blocked: cannot edit sensitive file: $FILE" >&2
     exit 2
diff --git a/hooks/syntax-check.sh b/hooks/syntax-check.sh
deleted file mode 100755
index 8c309b7..0000000
--- a/hooks/syntax-check.sh
+++ /dev/null
@@ -1,38 +0,0 @@
-#!/bin/bash
-# PostToolUse(Write|Edit) — informational syntax check. ALWAYS exits 0 (never blocks);
-# surfaces the real first lines of any error so they are visible in the tool output
-# (the old version hid Python errors behind 2>/dev/null and a vague message).
-INPUT=$(cat)
-FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.filePath // empty')
-[ -z "$FILE" ] && exit 0
-[ -f "$FILE" ] || exit 0
-
-show_fail() { echo "Syntax error in $FILE:"; echo "$1" | head -5; }
-
-case "$FILE" in
-  *.py)
-    OUT=$(python3 -m py_compile "$FILE" 2>&1) && echo "Syntax OK: $FILE" || show_fail "$OUT"
-    ;;
-  *.js|*.mjs|*.cjs)
-    if command -v node >/dev/null 2>&1; then
-      OUT=$(node --check "$FILE" 2>&1) && echo "Syntax OK: $FILE" || show_fail "$OUT"
-    fi
-    ;;
-  *.ts|*.tsx|*.jsx)
-    echo "Note: $FILE — tsc not available without project config; skipped TS syntax check."
-    ;;
-  *.sh|*.bash)
-    OUT=$(bash -n "$FILE" 2>&1) && echo "Syntax OK: $FILE" || show_fail "$OUT"
-    ;;
-  *.json)
-    if command -v jq >/dev/null 2>&1; then
-      OUT=$(jq empty "$FILE" 2>&1) && echo "Syntax OK: $FILE" || show_fail "$OUT"
-    fi
-    ;;
-  *.swift)
-    if command -v swiftc >/dev/null 2>&1; then
-      OUT=$(swiftc -parse "$FILE" 2>&1) && echo "Syntax OK: $FILE" || show_fail "$OUT"
-    fi
-    ;;
-esac
-exit 0

From b0e51f300605ef63404e6922a1a52708f5734998 Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Wed, 16 Sep 2026 16:31:48 +0100
Subject: [PATCH 03/24] test: run.sh hook, size, dedupe and scan checks; retire
 the installer

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .claude/skills/setup/SKILL.md   | 184 --------
 .github/workflows/ci.yml        | 102 ++--
 scripts/check.sh                | 298 ------------
 scripts/install.sh              | 241 ----------
 scripts/lib.sh                  | 174 -------
 scripts/manifest.txt            |  17 -
 scripts/merge-claude-md.sh      | 160 -------
 scripts/merge-settings.sh       | 269 -----------
 tests/check.bats                | 326 -------------
 tests/dedupe-phrases.txt        |  15 +
 tests/e2e.bats                  | 128 -----
 tests/hooks.bats                | 329 -------------
 tests/install.bats              | 331 -------------
 tests/manual-setup-checklist.md |  67 ---
 tests/merge-claude-md.bats      | 195 --------
 tests/merge-settings.bats       | 356 --------------
 tests/run.sh                    | 808 ++++++++++++++++++++++++++++++++
 tests/test_helper.bash          |  54 ---
 18 files changed, 885 insertions(+), 3169 deletions(-)
 delete mode 100644 .claude/skills/setup/SKILL.md
 delete mode 100755 scripts/check.sh
 delete mode 100644 scripts/install.sh
 delete mode 100755 scripts/lib.sh
 delete mode 100644 scripts/manifest.txt
 delete mode 100755 scripts/merge-claude-md.sh
 delete mode 100644 scripts/merge-settings.sh
 delete mode 100644 tests/check.bats
 create mode 100644 tests/dedupe-phrases.txt
 delete mode 100644 tests/e2e.bats
 delete mode 100644 tests/hooks.bats
 delete mode 100644 tests/install.bats
 delete mode 100644 tests/manual-setup-checklist.md
 delete mode 100644 tests/merge-claude-md.bats
 delete mode 100644 tests/merge-settings.bats
 create mode 100755 tests/run.sh
 delete mode 100644 tests/test_helper.bash

diff --git a/.claude/skills/setup/SKILL.md b/.claude/skills/setup/SKILL.md
deleted file mode 100644
index 042d806..0000000
--- a/.claude/skills/setup/SKILL.md
+++ /dev/null
@@ -1,184 +0,0 @@
----
-name: setup
-description: "Install this repo's Claude Code setup into the current machine's config dir. Runs ONLY when the user types /setup inside a clone of claude-code-setup — never model-invoked. Orchestrates the check/install/merge scripts through a preflight → install → merge → handoff flow, with a diff shown and explicit consent taken before every write."
-disable-model-invocation: true
-argument-hint: (no arguments — run inside a fresh clone of this repo)
-allowed-tools:
-  - Read
-  - Glob
-  - Grep
-  - Bash(bash scripts/check.sh:*)
-  - Bash(bash scripts/install.sh --dry-run:*)
-  - Bash(bash scripts/merge-settings.sh --dry-run:*)
-  - Bash(bash scripts/merge-claude-md.sh --dry-run:*)
----
-
-# Setup Router — Adopter Install Flow
-
-You are the session executing `/setup` inside a **clone of this repo** (this skill is
-repo-scoped: it lives under `.claude/skills/` and is discovered only when Claude Code runs
-in the clone — it is never installed onto an adopter's machine). Your job is to install this
-setup's managed artifacts (agents/hooks/rules/skills), then merge `settings.json` and
-`CLAUDE.md`, into the current machine's Claude config dir — **safely, with a diff shown and
-explicit consent taken before every write**.
-
-## Consent model (read before you start)
-
-This flow has **two consent gates by design**, and you must not collapse either:
-
-1. **Every write is preceded by a diff + an explicit ask.** You dry-run first, show the
-   plan/diff, and ask the user to proceed.
-2. **The writing commands are deliberately NOT pre-approved in `allowed-tools`.** Only the
-   read-only and `--dry-run` forms are pre-approved. When you run the real install, a
-   real `--force=<category>`, or a real `--apply`, Claude Code will raise a **permission
-   prompt** — that prompt is the *intended* second gate, not a bug. Tell the user to expect
-   it and let it happen; never try to route around it.
-
-Do **not** invent Edit/Write shortcuts to config paths, and do not seek broader permission
-grants to suppress those prompts.
-
-## Script contract (shared by all four scripts)
-
-- Machine lines `CCS-STATUS:<action>:<path>` print on **stdout**; human diffs/plan text also
-  on stdout; refusals/errors on **stderr**.
-- Exit codes: **0** success · **1** refusal / partial · **2** usage / internal.
-- `scripts/install.sh` (non-dry-run) prints `CCS-STATUS:backup-dir:<path>` as its **first**
-  status line. **Capture that path** — that ONE run dir is threaded via `--backup-dir <path>`
-  into every later `--apply`/`--force` this session, so the whole install produces a single
-  backup run dir and a single receipt.
-
-## Global error rules (apply in every phase)
-
-- **Any script exits 2** → STOP the entire flow. Report the script's stderr **verbatim**;
-  do not attempt later phases.
-- **Any script exits 1** → report its stderr **verbatim** and ask the user how to proceed
-  (it is a refusal/partial, not a hard stop — the user decides).
-- **Abort-safe / idempotent:** every phase is idempotent. If the flow is aborted partway,
-  re-running `/setup` resumes safely — already-installed, identical files no-op
-  (`CCS-STATUS:unchanged:...`), and merges recompute from current on-disk state. There is no
-  state file; a declined step is simply remembered in this conversation.
-
----
-
-## P1 — Preflight
-
-Run:
-
-```
-bash scripts/check.sh
-```
-
-- **Exit 2 (FAIL)** → STOP. Present the `FAIL:` lines **verbatim** plus the fixes `check.sh`
-  suggests. Do not proceed to P2.
-- **Exit 1 (WARN)** → present the `WARN:` lines and **ask the user whether to proceed** given
-  the warnings. Only continue if they say yes.
-- **Exit 0 (PASS)** → proceed to P2.
-
-## P2 — Install managed artifacts
-
-1. **Dry-run first:**
-
-   ```
-   bash scripts/install.sh --dry-run --diff
-   ```
-
-   Present the plan: what would be installed (missing → install), what is identical
-   (`unchanged`), and per-category **diffs for any differing files** (differing files are
-   **skipped** by default, per category).
-
-2. **Real install** (this is NOT pre-approved — expect a permission prompt; explain that to
-   the user before running it):
-
-   ```
-   bash scripts/install.sh
-   ```
-
-   **Capture the first status line** `CCS-STATUS:backup-dir:<path>`. Save `<path>` — you will
-   pass `--backup-dir <path>` to every later apply/force so the session shares one backup run
-   dir and one receipt.
-
-3. **Resolve skipped (differing) files.** Any file that differed was left untouched. For each
-   affected **category**, show that category's diff and ask the user **keep vs overwrite**.
-   Overwrite only the categories the user approves, one category per run:
-
-   ```
-   bash scripts/install.sh --force=<category> --backup-dir <path>
-   ```
-
-   (`<category>` is one of `agents`, `hooks`, `rules`, `skills`.) This run is also NOT
-   pre-approved — the permission prompt is again the intended consent gate.
-
-## P3 — Merge config files (one target at a time)
-
-Handle **`settings.json` first, then `CLAUDE.md`**. For each target, always: dry-run → show
-the unified diff → take **explicit consent** → apply with the shared `--backup-dir <path>`.
-
-### P3a — settings.json
-
-```
-bash scripts/merge-settings.sh --dry-run
-```
-
-Show the unified diff. Ask for explicit consent. On yes:
-
-```
-bash scripts/merge-settings.sh --apply --backup-dir <path>
-```
-
-If the target already exists (an existing-config merge, not a fresh verbatim write), also
-surface the **withheld-convenience-keys note** to the user:
-
-> Convenience keys (model, statusLine, defaultMode) were not merged to avoid overwriting
-> yours — copy from `settings.example.json` if wanted.
-
-### P3b — CLAUDE.md
-
-```
-bash scripts/merge-claude-md.sh --dry-run
-```
-
-Show the unified diff. Ask for explicit consent. On yes:
-
-```
-bash scripts/merge-claude-md.sh --apply --backup-dir <path>
-```
-
-**Declines are respected.** If the user declines either merge, do not write, do not re-ask in
-a loop, and do not nag — just record the decline in the conversation and move on.
-
-## P4 — Handoff
-
-The install is done from this session's side. Print, for the user:
-
-- **Receipt location** and the **backup run dir** (`<path>` captured in P2).
-- A short **"what behaves differently now"** summary (3 lines):
-  1. Pushes to `main`/`master` are blocked (branch-protection hook).
-  2. The delegation guard is active during `/build` (orchestrator can't hand-edit source).
-  3. Design + pre-PR human checkpoints are enforced.
-
-Then give the user the steps **they run AFTER restarting Claude Code**. The restart **severs
-this session**, so the skill must NOT try to run these itself — hand them over as
-instructions:
-
-1. **Restart Claude Code** (so the newly installed settings/hooks/skills load).
-2. Verify the install landed:
-
-   ```
-   bash scripts/check.sh --post
-   ```
-
-3. Confirm hooks loaded by running **`/hooks`** and checking the managed entries appear.
-
----
-
-## Anti-patterns to avoid
-
-- Do NOT skip the dry-run — a diff is shown before **every** consent, no exceptions.
-- Do NOT collapse the two consent gates: never seek a broader grant to suppress the
-  install/force/apply permission prompts.
-- Do NOT thread multiple backup dirs — capture the ONE `CCS-STATUS:backup-dir:<path>` from
-  P2 and reuse it for every apply/force.
-- Do NOT re-ask a declined merge in a loop.
-- Do NOT run the post-restart steps yourself — the restart ends this session; they are the
-  user's to run.
-- Do NOT continue past an exit-2 from any script — STOP and report verbatim.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 47a82aa..15d58ff 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -8,58 +8,80 @@ on:
     branches: [main]
 
 jobs:
-  lint-and-test:
-    name: shellcheck + bats + manifest (ubuntu)
+  ubuntu:
+    name: shellcheck + jq + tests/run.sh all + plugin validate (ubuntu)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install shellcheck
-        run: sudo apt-get update -y && sudo apt-get install -y shellcheck
+      - name: Install jq and shellcheck
+        run: sudo apt-get update -y && sudo apt-get install -y shellcheck jq
 
-      # Same pinned git-checkout install as the macos job below. `npm install -g
-      # bats` broke on the ubuntu-24.04 runner image: npm's global prefix is
-      # /usr/local, whose man dirs the runner user cannot mkdir (EACCES).
-      - name: Install bats-core from a git checkout
-        run: |
-          git clone --depth 1 --branch v1.11.0 https://github.com/bats-core/bats-core.git "$RUNNER_TEMP/bats-core"
-          echo "$RUNNER_TEMP/bats-core/bin" >> "$GITHUB_PATH"
+      - name: shellcheck hooks + tests/run.sh
+        run: shellcheck -x hooks/*.sh tests/run.sh
+
+      - name: validate plugin/marketplace/hooks JSON
+        run: jq empty .claude-plugin/plugin.json .claude-plugin/marketplace.json hooks/hooks.json
 
-      - name: shellcheck scripts + hooks
-        # -x: scripts/*.sh source scripts/lib.sh; a bare single-file shellcheck
-        # trips info-level SC1091 (can't follow non-constant/relative source).
-        # House convention: always lint with -x here.
-        #
-        # --severity=error: hooks/*.sh (owned by an earlier task, out of scope
-        # here) carry pre-existing info/warning-level nits (SC2086, SC2015,
-        # SC2221/2222) that are stylistic, not bugs. Gating on errors keeps this
-        # a real correctness gate without failing CI on unrelated existing
-        # style notes. Judgment call — revisit if those files get cleaned up.
-        run: shellcheck -x --severity=error scripts/*.sh hooks/*.sh
+      - name: tests/run.sh all
+        run: bash tests/run.sh all
 
-      - name: bats (full suite, incl. e2e)
-        run: bats tests/*.bats
+      - name: categorical prompt-hygiene greps
+        # Red until T3-T6 rewrite skills/agents/rules; CI only runs at push
+        # time, which happens after T7 (accepted by the design).
+        run: |
+          set -e
+          if git grep -niE 'opus needs|do not trust|be decisive|read all files fresh|claude-design-active|claude-orchestrator-active' -- skills agents rules; then
+            echo "gate: banned coordination phrases in prompts"
+            exit 1
+          fi
+          if git grep -nwE 'NEVER|ALWAYS|MUST|CRITICAL' -- skills agents rules; then
+            echo "gate: emphatic capitals in prompts"
+            exit 1
+          fi
+          if git grep -niE 'under 50 lines' -- skills agents rules; then
+            echo "gate: 'under 50 lines' phrase in prompts"
+            exit 1
+          fi
+          if git grep -nE '^(disallowedTools|permissionMode|mcpServers|hooks):' -- agents; then
+            echo "gate: disallowed frontmatter keys in agents"
+            exit 1
+          fi
+          for f in agents/*.md; do
+            for k in model tools effort maxTurns; do
+              grep -q "^$k:" "$f" || { echo "$f lacks $k:"; exit 1; }
+            done
+          done
+          if git grep -niE '~/.claude/plans|gitattributes|linguist|git clean' -- skills; then
+            echo "gate: internal-path/meta references in skills"
+            exit 1
+          fi
+          if ! grep -q haiku skills/design/SKILL.md; then
+            echo "gate: skills/design/SKILL.md missing haiku reference"
+            exit 1
+          fi
+          N=$(sed -n 's/^Copyright (c) [0-9]* //p' LICENSE | cut -d' ' -f1)
+          if [ -z "$N" ]; then
+            echo "gate: could not extract copyright name from LICENSE"
+            exit 1
+          fi
+          if git grep -qi "$N" -- skills agents rules hooks tests WORKFLOW.md CLAUDE.md docs; then
+            echo "gate: LICENSE-derived name leaked into prompts/docs"
+            exit 1
+          fi
 
-      - name: manifest.txt == git ls-files agents/ hooks/ rules/ skills/ (C3)
+      - name: install Claude Code CLI and validate plugin
         run: |
-          diff <(git ls-files agents/ hooks/ rules/ skills/) scripts/manifest.txt
+          npm install -g @anthropic-ai/claude-code
+          claude plugin validate .
 
-  bats-macos:
-    name: bats (macos system /bin/bash 3.2 + BSD userland)
+  macos:
+    name: hooks under system bash 3.2 (macos)
     runs-on: macos-latest
     steps:
       - uses: actions/checkout@v4
 
-      # bats-core from a git checkout, invoked directly out of bin/ — NOT via
-      # brew. A brewed bats would pull in a modern GNU-flavored PATH/toolchain
-      # and mask exactly the GNUisms this job exists to catch. shellcheck is
-      # intentionally skipped here: the ubuntu job already lints every script.
-      - name: Install bats-core from a git checkout
-        run: |
-          git clone --depth 1 --branch v1.11.0 https://github.com/bats-core/bats-core.git "$RUNNER_TEMP/bats-core"
-          echo "$RUNNER_TEMP/bats-core/bin" >> "$GITHUB_PATH"
-
-      - name: bats (full suite, incl. e2e) under system bash
+      - name: tests/run.sh hooks under system /bin/bash (jq preinstalled)
         run: |
-          echo "bash: $(command -v bash) ($(bash --version | head -n1))"
-          bats tests/*.bats
+          echo "bash: $(command -v /bin/bash) ($(/bin/bash --version | head -n1))"
+          /bin/bash tests/run.sh hooks
diff --git a/scripts/check.sh b/scripts/check.sh
deleted file mode 100755
index b2fa246..0000000
--- a/scripts/check.sh
+++ /dev/null
@@ -1,298 +0,0 @@
-#!/bin/bash
-# scripts/check.sh — doctor-style prerequisite + post-install verifier.
-#   default mode : environment readiness with an explicit severity map.
-#   --post mode  : verify managed artifacts landed under the resolved config dir.
-# Aggregate exit: 0 PASS / 1 WARN / 2 FAIL (design v4 §2). Reads no stdin, never
-# prompts. Human-readable lines on stdout. BSD-safe idioms only.
-
-set -euo pipefail
-
-SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd -P )"
-# shellcheck source=scripts/lib.sh
-. "$SCRIPT_DIR/lib.sh"
-
-MANIFEST="$SCRIPT_DIR/manifest.txt"
-CLAUDE_MD_MARKER='<!-- BEGIN claude-code-setup workflow-rules v'
-HOOK_FILES=(protect-branches.sh protect-secrets.sh orchestrator-delegate-guard.sh design-scope-guard.sh syntax-check.sh)
-
-# Version floors (leading-semver comparison). 2.1.53 is the CVE-2026-33068
-# security floor; the two higher tiers gate feature completeness.
-VER_FLOOR_SECURITY="2.1.53"
-VER_FLOOR_SENTINEL="2.1.132"
-VER_FLOOR_FULL="2.1.198"
-
-WORST=0
-
-pass() { printf 'PASS: %s\n' "$*"; }
-info() { printf 'INFO: %s\n' "$*"; }
-warn() { printf 'WARN: %s\n' "$*"; if [ "$WORST" -lt 1 ]; then WORST=1; fi; }
-fail() { printf 'FAIL: %s\n' "$*"; WORST=2; }
-
-# --- version helpers ---------------------------------------------------------
-
-# ccs_semver <text> — echo the first leading x.y.z found (tolerates prefixes,
-# suffixes, and line wrapping in `claude --version` output).
-ccs_semver() {
-  printf '%s\n' "$1" | tr -c '0-9.\n' ' ' | tr ' ' '\n' \
-    | grep -E '^[0-9]+\.[0-9]+\.[0-9]+' | head -n 1 \
-    | grep -oE '^[0-9]+\.[0-9]+\.[0-9]+'
-}
-
-# ccs_ver_lt <a> <b> — true when semver a < b.
-ccs_ver_lt() {
-  local a="$1" b="$2" arest brest amaj amin apat bmaj bmin bpat
-  amaj="${a%%.*}"; arest="${a#*.}"; amin="${arest%%.*}"; apat="${arest#*.}"; apat="${apat%%[!0-9]*}"
-  bmaj="${b%%.*}"; brest="${b#*.}"; bmin="${brest%%.*}"; bpat="${brest#*.}"; bpat="${bpat%%[!0-9]*}"
-  [ "$amaj" -ne "$bmaj" ] && { [ "$amaj" -lt "$bmaj" ]; return; }
-  [ "$amin" -ne "$bmin" ] && { [ "$amin" -lt "$bmin" ]; return; }
-  [ "$apat" -lt "$bpat" ]
-}
-
-# run_guarded <cmd...> — run with a timeout when available (gh auth can hang).
-run_guarded() {
-  if command -v timeout >/dev/null 2>&1; then
-    timeout 10 "$@"
-  else
-    "$@"
-  fi
-}
-
-# --- default-mode checks -----------------------------------------------------
-
-check_jq() {
-  if command -v jq >/dev/null 2>&1; then
-    pass "jq found"
-  else
-    fail "jq not found — hooks fail closed without it (install jq)"
-  fi
-}
-
-check_version_tiers() {
-  local ver="$1"
-  if ccs_ver_lt "$ver" "$VER_FLOOR_SECURITY"; then
-    fail "claude $ver is below the $VER_FLOOR_SECURITY security floor (CVE-2026-33068) — upgrade now"
-  else
-    pass "claude $ver meets the $VER_FLOOR_SECURITY security floor"
-  fi
-  if ccs_ver_lt "$ver" "$VER_FLOOR_SENTINEL"; then
-    warn "claude $ver < $VER_FLOOR_SENTINEL — /build sentinel session isolation degraded (skills/build/SKILL.md)"
-  fi
-  if ccs_ver_lt "$ver" "$VER_FLOOR_FULL"; then
-    warn "claude $ver < $VER_FLOOR_FULL — Explore agent model override unavailable (agents/Explore.md)"
-  fi
-}
-
-check_claude() {
-  if ! command -v claude >/dev/null 2>&1; then
-    fail "claude CLI not found — install Claude Code (>= $VER_FLOOR_FULL recommended)"
-    return 0
-  fi
-  local raw ver
-  raw="$( claude --version 2>/dev/null || true )"
-  ver="$( ccs_semver "$raw" 2>/dev/null || true )"
-  if [ -z "$ver" ]; then
-    warn "could not parse 'claude --version' output: '$raw'"
-  else
-    check_version_tiers "$ver"
-  fi
-  info "claude present — run 'claude doctor' for deeper diagnostics"
-}
-
-check_writable() {
-  local dir="$1" probe
-  probe="$dir/.ccs-write-test.$$"
-  if ( : > "$probe" ) 2>/dev/null; then
-    rm -f "$probe"
-    pass "config dir writable: $dir"
-  else
-    fail "config dir not writable: $dir"
-  fi
-}
-
-check_config_dir() {
-  if ccs_claude_dir_is_regular_file; then
-    fail "config dir '$CLAUDE_DIR' exists but is not a directory"
-  elif ccs_is_source_eq_dest; then
-    fail "config dir resolves to the repo root ($REPO_ROOT) — refusing (installing the repo onto itself)"
-  elif [ -d "$CLAUDE_DIR" ]; then
-    check_writable "$CLAUDE_DIR"
-  else
-    local parent
-    parent="$( dirname "$CLAUDE_DIR" )"
-    if [ -d "$parent" ] && [ -w "$parent" ]; then
-      pass "config dir '$CLAUDE_DIR' will be created under writable parent"
-    else
-      fail "config dir '$CLAUDE_DIR' does not exist and parent '$parent' is not writable"
-    fi
-  fi
-}
-
-check_gh() {
-  if ! command -v gh >/dev/null 2>&1; then
-    warn "gh not found — needed by /ship (not for install); install the GitHub CLI"
-    return 0
-  fi
-  if run_guarded gh auth status >/dev/null 2>&1; then
-    pass "gh authenticated"
-  else
-    warn "gh present but not authenticated — run 'gh auth login' before /ship"
-  fi
-}
-
-check_git_identity() {
-  local name email
-  name="$( git config --global user.name 2>/dev/null || true )"
-  email="$( git config --global user.email 2>/dev/null || true )"
-  if [ -n "$name" ] && [ -n "$email" ]; then
-    pass "git identity configured"
-  else
-    warn "git user.name/user.email not set — /build commits would be unattributed"
-  fi
-}
-
-check_mcp_one() {
-  case "$1" in
-    *"$2"*) pass "optional MCP server present: $2" ;;
-    *)      warn "optional MCP server absent: $2 (install for research/docs; not required)" ;;
-  esac
-}
-
-check_mcp() {
-  command -v claude >/dev/null 2>&1 || return 0
-  local list
-  list="$( claude mcp list 2>/dev/null || true )"
-  check_mcp_one "$list" context7
-  check_mcp_one "$list" exa
-}
-
-run_default() {
-  check_jq
-  check_claude
-  check_config_dir
-  check_gh
-  check_git_identity
-  check_mcp
-}
-
-# --- post-install checks -----------------------------------------------------
-
-post_manifest_files() {
-  local rel target
-  while IFS= read -r rel || [ -n "$rel" ]; do
-    [ -n "$rel" ] || continue
-    target="$CLAUDE_DIR/$rel"
-    if [ ! -e "$target" ]; then
-      fail "missing managed artifact: $rel"
-      continue
-    fi
-    case "$rel" in
-      hooks/*.sh)
-        if [ -x "$target" ]; then
-          pass "installed + executable: $rel"
-        else
-          fail "hook not executable: $rel"
-        fi
-        ;;
-      *)
-        pass "installed: $rel"
-        ;;
-    esac
-  done < "$MANIFEST"
-}
-
-post_settings_hooks() {
-  local sfile="$1" cmds fname missing present
-  cmds="$( jq -r '[.. | .command? // empty] | .[]' "$sfile" 2>/dev/null || true )"
-  missing=""
-  present=0
-  for fname in "${HOOK_FILES[@]}"; do
-    case "$cmds" in
-      *"$fname"*) present=$((present + 1)) ;;
-      *)          missing="$missing $fname" ;;
-    esac
-  done
-  if [ -z "$missing" ]; then
-    pass "settings.json references all managed hooks (by filename)"
-  elif [ "$present" -eq 0 ]; then
-    warn "settings.json has no managed hook entries — ignore if you declined this merge"
-  else
-    fail "settings.json is missing managed hook(s):$missing"
-  fi
-}
-
-post_settings() {
-  local sfile="$CLAUDE_DIR/settings.json"
-  if [ ! -e "$sfile" ]; then
-    warn "settings.json not found — ignore if you declined this merge"
-    return 0
-  fi
-  if ! command -v jq >/dev/null 2>&1; then
-    fail "jq not found — cannot verify settings.json"
-    return 0
-  fi
-  if ! jq empty "$sfile" >/dev/null 2>&1; then
-    fail "settings.json is present but not valid JSON"
-    return 0
-  fi
-  post_settings_hooks "$sfile"
-}
-
-post_claude_md() {
-  local cfile="$CLAUDE_DIR/CLAUDE.md"
-  if [ ! -e "$cfile" ]; then
-    warn "managed CLAUDE.md not found — ignore if you declined this merge"
-    return 0
-  fi
-  if grep -qF "$CLAUDE_MD_MARKER" "$cfile" 2>/dev/null; then
-    pass "managed CLAUDE.md marker block present"
-  else
-    warn "CLAUDE.md present but managed marker block absent — ignore if you declined this merge"
-  fi
-}
-
-post_setup_skill_absent() {
-  if [ -e "$CLAUDE_DIR/skills/setup" ]; then
-    fail "setup skill is installed under $CLAUDE_DIR/skills/setup — it must never be installed"
-  else
-    pass "setup skill correctly absent from config dir"
-  fi
-}
-
-run_post() {
-  if [ ! -e "$MANIFEST" ]; then
-    fail "manifest not found: $MANIFEST"
-    return 0
-  fi
-  post_manifest_files
-  post_settings
-  post_claude_md
-  post_setup_skill_absent
-}
-
-# --- entrypoint --------------------------------------------------------------
-
-main() {
-  local mode="default"
-  case "${1:-}" in
-    --post)    mode="post" ;;
-    "")        mode="default" ;;
-    -h|--help) printf 'usage: check.sh [--post]\n'; exit 0 ;;
-    *)         printf 'usage: check.sh [--post]\n' >&2; exit 2 ;;
-  esac
-
-  if [ "$mode" = "post" ]; then
-    printf '== claude-code-setup post-install check (%s) ==\n' "$CLAUDE_DIR"
-    run_post
-  else
-    printf '== claude-code-setup prerequisite check (%s) ==\n' "$CLAUDE_DIR"
-    run_default
-  fi
-
-  case "$WORST" in
-    0) printf 'RESULT: PASS\n'; exit 0 ;;
-    1) printf 'RESULT: WARN\n'; exit 1 ;;
-    *) printf 'RESULT: FAIL\n'; exit 2 ;;
-  esac
-}
-
-main "$@"
diff --git a/scripts/install.sh b/scripts/install.sh
deleted file mode 100644
index 6e49d51..0000000
--- a/scripts/install.sh
+++ /dev/null
@@ -1,241 +0,0 @@
-#!/bin/bash
-# scripts/install.sh — manifest-driven installer for claude-code-setup managed
-# artifacts (agents/hooks/rules/skills) into the adopter's Claude config dir.
-# Idempotent: missing -> install, identical -> unchanged, differs -> skip
-# unless --force[=<category>]. Every overwrite backs up the adopter's file
-# first. See scripts/lib.sh for the shared contract this script builds on.
-
-set -euo pipefail
-
-SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd -P )"
-# shellcheck source=scripts/lib.sh
-. "$SCRIPT_DIR/lib.sh"
-
-MANIFEST="$SCRIPT_DIR/manifest.txt"
-CATEGORIES=" agents hooks rules skills "
-
-DRY_RUN=0
-DIFF=0
-FORCE_ALL=0
-FORCE_CATEGORY=""
-BACKUP_DIR_ARG=""
-FAILED=0
-BACKUP_RUN_DIR=""
-
-usage() {
-  printf 'usage: install.sh [--dry-run [--diff]] [--force | --force=<category>] [--backup-dir <path>]\n' >&2
-}
-
-# --- arg parsing --------------------------------------------------------------
-
-# parse_args <argv...> — --dry-run, when present, must be the very first flag
-# (fixed order so a permission prefix of "bash scripts/install.sh --dry-run"
-# covers both the plain and --diff forms). --diff requires --dry-run.
-parse_args() {
-  local first="${1:-}" a has_dry=0
-  for a in "$@"; do
-    [ "$a" = "--dry-run" ] && has_dry=1
-  done
-  if [ "$has_dry" -eq 1 ] && [ "$first" != "--dry-run" ]; then
-    usage
-    exit 2
-  fi
-
-  while [ "$#" -gt 0 ]; do
-    case "$1" in
-      --dry-run) DRY_RUN=1; shift ;;
-      --diff) DIFF=1; shift ;;
-      --force) FORCE_ALL=1; shift ;;
-      --force=*) FORCE_CATEGORY="${1#--force=}"; shift ;;
-      --backup-dir)
-        [ "$#" -ge 2 ] || { usage; exit 2; }
-        BACKUP_DIR_ARG="$2"
-        shift 2
-        ;;
-      *) usage; exit 2 ;;
-    esac
-  done
-
-  if [ "$DIFF" -eq 1 ] && [ "$DRY_RUN" -eq 0 ]; then
-    printf 'CCS: --diff requires --dry-run\n' >&2
-    usage
-    exit 2
-  fi
-
-  if [ -n "$FORCE_CATEGORY" ]; then
-    case "$CATEGORIES" in
-      *" $FORCE_CATEGORY "*) : ;;
-      *) printf 'CCS: unknown --force category: %s\n' "$FORCE_CATEGORY" >&2; exit 2 ;;
-    esac
-  fi
-}
-
-# --- guards --------------------------------------------------------------
-
-# validate_manifest_rel <rel> — shared guard for every manifest-reading loop.
-# Delegates the path-escape check to lib.sh (shared with any future consumer),
-# then enforces the closed category allowlist, which is install.sh-local since
-# CATEGORIES lives here.
-validate_manifest_rel() {
-  local rel="$1"
-  ccs_validate_manifest_rel "$rel"
-  case "$CATEGORIES" in
-    *" ${rel%%/*} "*) : ;;
-    *) ccs_die 1 "manifest path has an unmanaged category: $rel" ;;
-  esac
-}
-
-# validate_manifest — validate every relative path in the manifest BEFORE any
-# writes happen (mkdir, backup dir, copy), so a single malformed/malicious line
-# fails the whole run instead of leaving partial side effects from lines read
-# ahead of it.
-validate_manifest() {
-  local rel
-  while IFS= read -r rel || [ -n "$rel" ]; do
-    [ -n "$rel" ] || continue
-    validate_manifest_rel "$rel"
-  done < "$MANIFEST"
-}
-
-main_guards() {
-  if ccs_claude_dir_is_regular_file; then
-    ccs_die 2 "config dir '$CLAUDE_DIR' exists but is not a directory"
-  fi
-  if ccs_is_source_eq_dest; then
-    ccs_die 2 "config dir resolves to the repo root ($REPO_ROOT) — refusing to install onto itself"
-  fi
-  [ -e "$MANIFEST" ] || ccs_die 2 "manifest not found: $MANIFEST"
-  validate_manifest
-}
-
-# --- directory provisioning ------------------------------------------------
-
-# ensure_dirs — mkdir -p every manifest parent dir plus plans/ (created even
-# though no manifest file lives there). Only called for real (non-dry) runs.
-ensure_dirs() {
-  local rel
-  while IFS= read -r rel || [ -n "$rel" ]; do
-    [ -n "$rel" ] || continue
-    mkdir -p "$CLAUDE_DIR/$( dirname "$rel" )"
-  done < "$MANIFEST"
-  mkdir -p "$CLAUDE_DIR/plans"
-}
-
-# --- force policy ------------------------------------------------------------
-
-# _force_applies <category> — true when --force or --force=<category> covers it.
-_force_applies() {
-  local category="$1"
-  [ "$FORCE_ALL" -eq 1 ] && return 0
-  [ -n "$FORCE_CATEGORY" ] && [ "$FORCE_CATEGORY" = "$category" ] && return 0
-  return 1
-}
-
-# --- per-file handling -------------------------------------------------------
-
-handle_install() {
-  local rel="$1" src="$2" dst="$3" category="$4"
-  if [ "$DRY_RUN" -eq 1 ]; then
-    ccs_status installed "$rel"
-    return 0
-  fi
-  ccs_atomic_install "$src" "$dst"
-  [ "$category" = hooks ] && chmod +x "$dst"
-  ccs_status installed "$rel"
-  ccs_receipt_append "$BACKUP_RUN_DIR" installed "$dst"
-}
-
-handle_unchanged() {
-  local rel="$1" dst="$2" category="$3"
-  if [ "$DRY_RUN" -eq 0 ] && [ "$category" = hooks ] && [ ! -x "$dst" ]; then
-    chmod +x "$dst"
-    printf 'CCS: restored missing executable bit: %s\n' "$rel" >&2
-  fi
-  ccs_status unchanged "$rel"
-  [ "$DRY_RUN" -eq 1 ] && return 0
-  ccs_receipt_append "$BACKUP_RUN_DIR" unchanged "$dst"
-}
-
-# _preview_differs <rel> <src> <dst> <category> — dry-run reporting only.
-_preview_differs() {
-  local rel="$1" src="$2" dst="$3" category="$4"
-  if _force_applies "$category"; then
-    ccs_status overwritten "$rel"
-  else
-    ccs_status skipped "$rel"
-  fi
-  if [ "$DIFF" -eq 1 ]; then
-    diff -u "$dst" "$src" || true
-  fi
-}
-
-handle_differs() {
-  local rel="$1" src="$2" dst="$3" category="$4" backup_path
-  if [ "$DRY_RUN" -eq 1 ]; then
-    _preview_differs "$rel" "$src" "$dst" "$category"
-    return 0
-  fi
-
-  if _force_applies "$category"; then
-    backup_path="$BACKUP_RUN_DIR/$rel"
-    mkdir -p "$( dirname "$backup_path" )"
-    cp -p "$dst" "$backup_path"
-    ccs_atomic_install "$src" "$dst"
-    [ "$category" = hooks ] && chmod +x "$dst"
-    ccs_status overwritten "$rel"
-    ccs_receipt_append "$BACKUP_RUN_DIR" overwritten "$dst" "$backup_path"
-  else
-    ccs_status skipped "$rel"
-    ccs_receipt_append "$BACKUP_RUN_DIR" skipped "$dst"
-  fi
-}
-
-# process_file <rel> — dispatch one manifest entry to its action handler.
-process_file() {
-  local rel="$1" src dst category
-  src="$REPO_ROOT/$rel"
-  dst="$CLAUDE_DIR/$rel"
-  category="${rel%%/*}"
-
-  if [ -L "$dst" ]; then
-    printf 'CCS: refusing to write through symlink: %s\n' "$dst" >&2
-    FAILED=1
-    return 0
-  fi
-
-  if [ ! -e "$dst" ]; then
-    handle_install "$rel" "$src" "$dst" "$category"
-  elif cmp -s "$src" "$dst"; then
-    handle_unchanged "$rel" "$dst" "$category"
-  else
-    handle_differs "$rel" "$src" "$dst" "$category"
-  fi
-}
-
-# --- entrypoint --------------------------------------------------------------
-
-main() {
-  parse_args "$@"
-  main_guards
-
-  if [ "$DRY_RUN" -eq 0 ]; then
-    ensure_dirs
-    if [ -n "$BACKUP_DIR_ARG" ]; then
-      BACKUP_RUN_DIR="$( ccs_backup_run_dir --backup-dir "$BACKUP_DIR_ARG" )"
-    else
-      BACKUP_RUN_DIR="$( ccs_backup_run_dir )"
-    fi
-    ccs_status backup-dir "$BACKUP_RUN_DIR"
-  fi
-
-  local rel
-  while IFS= read -r rel || [ -n "$rel" ]; do
-    [ -n "$rel" ] || continue
-    process_file "$rel"
-  done < "$MANIFEST"
-
-  [ "$FAILED" -eq 0 ] || exit 1
-  exit 0
-}
-
-main "$@"
diff --git a/scripts/lib.sh b/scripts/lib.sh
deleted file mode 100755
index ecdbd01..0000000
--- a/scripts/lib.sh
+++ /dev/null
@@ -1,174 +0,0 @@
-#!/bin/bash
-# scripts/lib.sh — shared helpers for the claude-code-setup installer scripts.
-# Sourced by check.sh / install.sh / merge-*.sh. Global contract (design v4):
-#   * Bash 3.2 compatible (no associative arrays / mapfile / ${v,,}).
-#   * set -euo pipefail (callers inherit it via source).
-#   * NEVER read stdin, NEVER prompt.
-#   * Machine lines "CCS-STATUS:<action>:<path>" go to stdout; every error and
-#     refusal reason goes to stderr.
-#   * Atomic file writes: mktemp in the destination dir, then mv.
-#   * Exit contract: 0 success (incl. no-op), 1 refusal/partial, 2 usage/internal.
-# BSD-safe idioms only (macOS bash 3.2 + BSD userland is a CI target).
-
-set -euo pipefail
-
-# --- stream + exit helpers ---------------------------------------------------
-
-# ccs_status <action> <path> — machine-readable status line on stdout.
-ccs_status() {
-  printf 'CCS-STATUS:%s:%s\n' "$1" "$2"
-}
-
-# ccs_die <exit_code> <message...> — reason on stderr, then exit.
-ccs_die() {
-  local code="$1"
-  shift
-  printf 'CCS: %s\n' "$*" >&2
-  exit "$code"
-}
-
-# --- path normalization ------------------------------------------------------
-
-# ccs_abspath <path> — absolutize a path without requiring it to exist. Expands a
-# leading "~" / "~/" to $HOME and prefixes $PWD for relative values. Symlinks are
-# NOT resolved here (see ccs_canonical). A trailing slash is trimmed (except "/").
-ccs_abspath() {
-  local p="$1"
-  # A leading literal "~" means the user passed a tilde in the value; expand it to
-  # $HOME ourselves (case patterns never tilde-expand). SC2088 is a false positive.
-  # shellcheck disable=SC2088
-  case "$p" in
-    "~")   p="$HOME" ;;
-    "~/"*) p="$HOME/${p:2}" ;;
-    /*)    : ;;
-    *)     p="$PWD/$p" ;;
-  esac
-  case "$p" in
-    */) p="${p%/}"; [ -n "$p" ] || p="/" ;;
-  esac
-  printf '%s\n' "$p"
-}
-
-# ccs_canonical <path> — fully resolved physical path (symlinks collapsed). Emits
-# nothing when the path does not exist as a directory.
-ccs_canonical() {
-  if [ -d "$1" ]; then
-    ( cd "$1" && pwd -P )
-  fi
-}
-
-# --- config dir resolution ---------------------------------------------------
-
-# SCRIPT_DIR is this scripts/ directory; REPO_ROOT is its parent (works for git
-# clones and extracted tarballs alike).
-SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd -P )"
-REPO_ROOT="$( cd "$SCRIPT_DIR/.." && pwd -P )"
-
-# Fail closed when there is no way to locate the config dir.
-if [ -z "${CLAUDE_CONFIG_DIR:-}" ] && [ -z "${HOME:-}" ]; then
-  ccs_die 2 "neither CLAUDE_CONFIG_DIR nor HOME is set; cannot locate the config dir"
-fi
-
-# CLAUDE_DIR — the adopter's config dir, always absolute/normalized.
-CLAUDE_DIR="$( ccs_abspath "${CLAUDE_CONFIG_DIR:-$HOME/.claude}" )"
-
-# --- config dir integrity checks --------------------------------------------
-
-# ccs_claude_dir_is_regular_file — true when CLAUDE_DIR exists but is NOT a
-# directory. A symlink to a directory is allowed (stow/chezmoi); a plain file or
-# a symlink to a file is not.
-ccs_claude_dir_is_regular_file() {
-  [ -e "$CLAUDE_DIR" ] && [ ! -d "$CLAUDE_DIR" ]
-}
-
-# ccs_is_source_eq_dest — true when the resolved config dir is the repo itself
-# (a clone placed at ~/.claude, or CLAUDE_CONFIG_DIR pointed at the clone).
-# Installing a repo onto itself would pollute the working tree.
-ccs_is_source_eq_dest() {
-  local canon
-  canon="$( ccs_canonical "$CLAUDE_DIR" )"
-  [ -n "$canon" ] && [ "$canon" = "$REPO_ROOT" ]
-}
-
-# refuse_symlink <path> — refuse (exit 1) if the write target is a symlink. Used
-# to guard every FILE write destination in the merge/install scripts.
-refuse_symlink() {
-  if [ -L "$1" ]; then
-    ccs_die 1 "refusing to write through symlink: $1"
-  fi
-}
-
-# --- manifest path safety -----------------------------------------------------
-
-# ccs_validate_manifest_rel <rel> — refuse (exit 1) a manifest-sourced relative
-# path that is absolute, or that contains a ".." path component. The ".." check
-# matches only a FULL path segment (leading "../", embedded "/../", trailing
-# "/..", or exactly ".."), never a bare substring, so legitimate filenames that
-# merely contain dots (e.g. "foo..bar.md") stay valid. Every manifest-reading
-# loop must call this before the line is used to build a destination path —
-# same "refuse before writing" convention as refuse_symlink above.
-ccs_validate_manifest_rel() {
-  local rel="$1"
-  case "$rel" in
-    /*)
-      ccs_die 1 "manifest path is absolute, refusing: $rel" ;;
-    ..|../*|*/../*|*/..)
-      ccs_die 1 "manifest path escapes the config dir: $rel" ;;
-  esac
-}
-
-# --- prerequisites -----------------------------------------------------------
-
-# ccs_require_jq — jq-dependent callers fail closed (exit 2) when jq is absent.
-ccs_require_jq() {
-  command -v jq >/dev/null 2>&1 || ccs_die 2 "jq is required but was not found on PATH"
-}
-
-# ccs_repo_sha — repo commit for provenance; tarball adopters degrade to unknown.
-ccs_repo_sha() {
-  git -C "$SCRIPT_DIR" rev-parse HEAD 2>/dev/null || echo unknown
-}
-
-# --- backups + receipts ------------------------------------------------------
-
-# ccs_backup_run_dir [--backup-dir <path>] — echo the backup run directory,
-# creating it if needed. With no argument a fresh timestamped dir is created
-# under $CLAUDE_DIR/backups/claude-code-setup/ (durable, inside the config dir,
-# never $TMPDIR). With --backup-dir the caller's threaded run dir is reused so a
-# single /setup run keeps one receipt. Path is emitted on stdout so the skill can
-# thread it across install/merge invocations.
-ccs_backup_run_dir() {
-  local dir=""
-  if [ "${1:-}" = "--backup-dir" ]; then
-    dir="${2:-}"
-  fi
-  if [ -z "$dir" ]; then
-    dir="$CLAUDE_DIR/backups/claude-code-setup/$( date +%Y%m%d-%H%M%S )"
-  fi
-  mkdir -p "$dir" || ccs_die 2 "failed to create backup dir: $dir"
-  printf '%s\n' "$dir"
-}
-
-# ccs_receipt_append <run_dir> <action> <path> [backup_path] — append one receipt
-# line (survives interrupts). action is one of installed|overwritten|merged|skipped.
-# Fields are tab-separated: action, path, backup, repo sha, timestamp.
-ccs_receipt_append() {
-  local run_dir="$1" action="$2" path="$3" backup="${4:-}"
-  printf '%s\t%s\t%s\t%s\t%s\n' \
-    "$action" "$path" "$backup" "$( ccs_repo_sha )" "$( date +%Y-%m-%dT%H:%M:%S )" \
-    >> "$run_dir/receipt.txt"
-}
-
-# --- atomic writes -----------------------------------------------------------
-
-# ccs_atomic_install <src> <dst> — copy src onto dst atomically (mktemp in the
-# destination directory, then mv). Refuses symlinked destinations.
-ccs_atomic_install() {
-  local src="$1" dst="$2" tmp dstdir
-  refuse_symlink "$dst"
-  dstdir="$( dirname "$dst" )"
-  mkdir -p "$dstdir" || ccs_die 2 "failed to create destination dir: $dstdir"
-  tmp="$( mktemp "$dstdir/.ccs.XXXXXX" )"
-  cp "$src" "$tmp"
-  mv -f "$tmp" "$dst"
-}
diff --git a/scripts/manifest.txt b/scripts/manifest.txt
deleted file mode 100644
index 13890e7..0000000
--- a/scripts/manifest.txt
+++ /dev/null
@@ -1,17 +0,0 @@
-agents/Explore.md
-agents/design-reviewer.md
-agents/direction-reviewer.md
-agents/implementer.md
-agents/researcher.md
-agents/reviewer.md
-hooks/design-scope-guard.sh
-hooks/orchestrator-delegate-guard.sh
-hooks/protect-branches.sh
-hooks/protect-secrets.sh
-hooks/syntax-check.sh
-rules/orchestration.md
-skills/build/SKILL.md
-skills/compound/SKILL.md
-skills/design/SKILL.md
-skills/search/SKILL.md
-skills/ship/SKILL.md
diff --git a/scripts/merge-claude-md.sh b/scripts/merge-claude-md.sh
deleted file mode 100755
index 77a09b0..0000000
--- a/scripts/merge-claude-md.sh
+++ /dev/null
@@ -1,160 +0,0 @@
-#!/bin/bash
-# scripts/merge-claude-md.sh — merge the repo's managed CLAUDE.md "workflow-rules"
-# block into the adopter's $CLAUDE_DIR/CLAUDE.md. Non-destructive by construction:
-#   fresh target   -> new file containing exactly the managed block (markers only,
-#                     never Victor's personal sections, which live outside the block)
-#   marker'd target-> REPLACE the block in place (version-agnostic; upgrade-safe)
-#   plain target   -> APPEND the block after a blank-line separator
-#   malformed target (one marker, END-before-BEGIN, or duplicates) -> REFUSE, untouched
-# See lib.sh for the global script contract (exit codes, machine lines, atomics).
-
-set -euo pipefail
-
-SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd -P )"
-# shellcheck source=scripts/lib.sh
-. "$SCRIPT_DIR/lib.sh"
-
-SOURCE_MD="$REPO_ROOT/CLAUDE.md"
-TARGET_MD="$CLAUDE_DIR/CLAUDE.md"
-
-# Version-agnostic marker patterns: BEGIN/END lines of ANY version match, so an
-# older installed block (v0, v2, ...) is upgraded in place rather than duplicated.
-BEGIN_RE='^<!-- BEGIN claude-code-setup workflow-rules v.* -->$'
-END_RE='^<!-- END claude-code-setup workflow-rules v.* -->$'
-
-usage() {
-  printf 'usage: merge-claude-md.sh (--dry-run|--apply) [--backup-dir <dir>]\n' >&2
-  exit "${1:-2}"
-}
-
-# analyze_markers <file> — set MK_BEGIN_COUNT / MK_END_COUNT and the first
-# BEGIN/END line numbers (empty when none). BSD grep/cut/head only.
-analyze_markers() {
-  local file="$1" bl el
-  bl="$( grep -nE "$BEGIN_RE" "$file" 2>/dev/null || true )"
-  el="$( grep -nE "$END_RE" "$file" 2>/dev/null || true )"
-  MK_BEGIN_COUNT="$( printf '%s' "$bl" | grep -c . || true )"
-  MK_END_COUNT="$( printf '%s' "$el" | grep -c . || true )"
-  MK_BEGIN_LINE="$( printf '%s\n' "$bl" | head -n 1 | cut -d: -f1 )"
-  MK_END_LINE="$( printf '%s\n' "$el" | head -n 1 | cut -d: -f1 )"
-}
-
-# extract_source_block — write the repo's managed block (inclusive of markers)
-# into $BLOCK_FILE. A malformed source is a packaging bug -> internal error.
-extract_source_block() {
-  analyze_markers "$SOURCE_MD"
-  if [ "$MK_BEGIN_COUNT" != "1" ] || [ "$MK_END_COUNT" != "1" ] \
-     || [ "$MK_BEGIN_LINE" -ge "$MK_END_LINE" ]; then
-    ccs_die 2 "packaging error: $SOURCE_MD has no single managed workflow-rules block"
-  fi
-  awk -v b="$MK_BEGIN_LINE" -v e="$MK_END_LINE" 'NR>=b && NR<=e' "$SOURCE_MD" > "$BLOCK_FILE"
-}
-
-refuse_malformed() {
-  ccs_die 1 "malformed managed block in $TARGET_MD (found $MK_BEGIN_COUNT BEGIN / $MK_END_COUNT END marker(s)). Repair manually: keep exactly one matching '<!-- BEGIN claude-code-setup workflow-rules vN -->' ... '<!-- END claude-code-setup workflow-rules vN -->' pair with BEGIN before END, OR delete both marker lines to re-append a fresh block, then re-run."
-}
-
-build_append() {
-  ACTION=merged
-  cp "$TARGET_MD" "$RESULT_FILE"
-  # Ensure a trailing newline, then exactly one blank-line separator.
-  if [ -s "$RESULT_FILE" ] && [ -n "$( tail -c 1 "$RESULT_FILE" )" ]; then
-    printf '\n' >> "$RESULT_FILE"
-  fi
-  printf '\n' >> "$RESULT_FILE"
-  cat "$BLOCK_FILE" >> "$RESULT_FILE"
-}
-
-build_replace() {
-  ACTION=merged
-  awk -v b="$MK_BEGIN_LINE" 'NR<b' "$TARGET_MD" > "$RESULT_FILE"
-  cat "$BLOCK_FILE" >> "$RESULT_FILE"
-  awk -v e="$MK_END_LINE" 'NR>e' "$TARGET_MD" >> "$RESULT_FILE"
-}
-
-# build_result — decide the action and materialize $RESULT_FILE from $TARGET_MD.
-build_result() {
-  refuse_symlink "$TARGET_MD"
-  if [ ! -e "$TARGET_MD" ]; then
-    ACTION=merged
-    cp "$BLOCK_FILE" "$RESULT_FILE"
-    return 0
-  fi
-  analyze_markers "$TARGET_MD"
-  if [ "$MK_BEGIN_COUNT" = "0" ] && [ "$MK_END_COUNT" = "0" ]; then
-    build_append
-  elif [ "$MK_BEGIN_COUNT" = "1" ] && [ "$MK_END_COUNT" = "1" ] \
-       && [ "$MK_BEGIN_LINE" -lt "$MK_END_LINE" ]; then
-    build_replace
-  else
-    refuse_malformed
-  fi
-}
-
-do_dry_run() {
-  if [ -e "$TARGET_MD" ] && cmp -s "$TARGET_MD" "$RESULT_FILE"; then
-    ccs_status unchanged "$TARGET_MD"
-    return 0
-  fi
-  ccs_status "$ACTION" "$TARGET_MD"
-  local cur="/dev/null"
-  [ -e "$TARGET_MD" ] && cur="$TARGET_MD"
-  diff -u -L "a/CLAUDE.md" -L "b/CLAUDE.md" "$cur" "$RESULT_FILE" || true
-}
-
-do_apply() {
-  if [ -e "$TARGET_MD" ] && cmp -s "$TARGET_MD" "$RESULT_FILE"; then
-    ccs_status unchanged "$TARGET_MD"
-    return 0
-  fi
-  local run_dir backup=""
-  if [ -n "$BACKUP_DIR" ]; then
-    run_dir="$( ccs_backup_run_dir --backup-dir "$BACKUP_DIR" )"
-  else
-    run_dir="$( ccs_backup_run_dir )"
-  fi
-  if [ -e "$TARGET_MD" ]; then
-    backup="$run_dir/CLAUDE.md"
-    cp "$TARGET_MD" "$backup"
-  fi
-  ccs_atomic_install "$RESULT_FILE" "$TARGET_MD"
-  ccs_receipt_append "$run_dir" "$ACTION" "$TARGET_MD" "$backup"
-  ccs_status "$ACTION" "$TARGET_MD"
-}
-
-main() {
-  local mode=""
-  BACKUP_DIR=""
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --dry-run) if [ -n "$mode" ]; then usage 2; fi; mode="dry-run" ;;
-      --apply)   if [ -n "$mode" ]; then usage 2; fi; mode="apply" ;;
-      --backup-dir)
-        shift
-        if [ $# -eq 0 ]; then usage 2; fi
-        BACKUP_DIR="$1" ;;
-      -h|--help)
-        printf 'usage: merge-claude-md.sh (--dry-run|--apply) [--backup-dir <dir>]\n'
-        exit 0 ;;
-      *) usage 2 ;;
-    esac
-    shift
-  done
-  [ -n "$mode" ] || usage 2
-
-  WORK="$( mktemp -d "${TMPDIR:-/tmp}/ccs-claudemd.XXXXXX" )"
-  trap 'rm -rf "$WORK"' EXIT
-  BLOCK_FILE="$WORK/block"
-  RESULT_FILE="$WORK/result"
-
-  extract_source_block
-  build_result
-
-  if [ "$mode" = "apply" ]; then
-    do_apply
-  else
-    do_dry_run
-  fi
-}
-
-main "$@"
diff --git a/scripts/merge-settings.sh b/scripts/merge-settings.sh
deleted file mode 100644
index ee0cc80..0000000
--- a/scripts/merge-settings.sh
+++ /dev/null
@@ -1,269 +0,0 @@
-#!/bin/bash
-# scripts/merge-settings.sh — the SOLE writer of $CLAUDE_DIR/settings.json.
-#
-# Missing target        -> write the repo template VERBATIM (design M3: the
-#                          example IS the intended fresh-adopter config; the
-#                          _comment_* keys are instructional and ship as-is).
-# Existing target       -> deterministic jq merge LIMITED to exactly two areas:
-#                          `.hooks` and `.permissions.allow`. Every other key the
-#                          adopter has (model, statusLine, defaultMode, env, any
-#                          personal key) is UNTOUCHED and is never added from the
-#                          template either (deliberately narrow).
-#
-# Hook reconciliation is BASENAME-KEYED. An existing hook command is classified by
-# TOKEN-ANCHORED matching: the command string is split on whitespace, each token is
-# stripped of surrounding quotes, and the entry is MANAGED only if some token's
-# basename is EXACTLY a manifest-listed hook FILENAME (protect-branches.sh,
-# protect-secrets.sh, orchestrator-delegate-guard.sh, design-scope-guard.sh,
-# syntax-check.sh — derived from manifest.txt). This matches both the
-# config-dir-aware and old `~/.claude` invocation forms while never misreading
-# a filename mentioned only in echo/log text. Managed entries are REPLACED by
-# the template's current entry for that filename (landing command-string
-# upgrades WITHOUT duplication). Hook entries
-# referencing NO manifest filename are FOREIGN and preserved verbatim. Template
-# hook entries not already present are added. `.permissions.allow` is a concat +
-# ORDER-PRESERVING dedup (first occurrence wins; adopter entries are never dropped
-# and the array is never reordered, which keeps the fresh-verbatim write a fixed
-# point across repeat runs).
-#
-# Semantics notes:
-#   * Scalar-wins / null-safe: this script never uses recursive object merge, so a
-#     null template value can never delete an adopter key.
-#   * Malformed nested shapes — a non-object `.hooks` / `.permissions`, a
-#     non-array `.permissions.allow`, a non-array `.hooks.<event>` value, a
-#     non-object element of one, a non-array inner `.hooks` list, a non-object
-#     inner hook entry, or a non-string `.command` on one — are REJECTED up front
-#     with an explicit exit-1 refusal on stderr in BOTH modes, so a bad shape
-#     never reaches jq as a raw exit-5 crash.
-#   * The unchanged/write-skip decision is SEMANTIC (sorted-compact canonical
-#     compare of target vs merged), not raw-byte: formatting-only differences (e.g.
-#     the template's hand-authored blank lines) never trigger a phantom rewrite.
-#
-# Global contract (design v4): Bash 3.2; set -euo pipefail; never reads stdin /
-# never prompts; CCS-STATUS:<action>:<path> + diffs (dry-run only) on stdout;
-# refusals on stderr; atomic writes; jq fail-closed. Exit 0 success (incl. the
-# CCS-STATUS:unchanged no-op) / 1 refusal-partial / 2 usage-internal.
-
-set -euo pipefail
-
-SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd -P )"
-# shellcheck source=scripts/lib.sh
-. "$SCRIPT_DIR/lib.sh"
-
-SOURCE="$REPO_ROOT/settings.example.json"
-MANIFEST="$SCRIPT_DIR/manifest.txt"
-TARGET="$CLAUDE_DIR/settings.json"
-MERGED_TMP=""
-trap 'rm -f "$MERGED_TMP"' EXIT
-
-usage() { printf 'usage: merge-settings.sh (--dry-run | --apply) [--backup-dir <path>]\n'; }
-usage_err() { usage >&2; exit 2; }
-
-# ccs_hook_names_json — JSON array of the managed hook basenames from the manifest
-# (hooks/*.sh lines). Basenames are plain .sh filenames, so raw quoting is safe.
-ccs_hook_names_json() {
-  local rel base out=""
-  while IFS= read -r rel || [ -n "$rel" ]; do
-    case "$rel" in
-      hooks/*.sh)
-        base="${rel#hooks/}"
-        if [ -z "$out" ]; then out="\"$base\""; else out="$out,\"$base\""; fi
-        ;;
-    esac
-  done < "$MANIFEST"
-  printf '[%s]' "$out"
-}
-
-# The merge program. Reconciliation is basename-keyed; see the file header. The
-# $-prefixed tokens below are jq variables, not shell expansions (SC2016).
-# shellcheck disable=SC2016
-JQ_MERGE='
-def basename_of: sub(".*/"; "");
-def strip_surround_quotes:
-  ([34,39] | implode) as $q
-  | sub("^[" + $q + "]+"; "") | sub("[" + $q + "]+$"; "");
-def is_managed($c):
-  any($c | splits("[[:space:]]+");
-      (strip_surround_quotes | basename_of) as $b
-      | ($names | index($b)) != null);
-def dedup: reduce .[] as $x ([]; if any(.[]; . == $x) then . else . + [$x] end);
-def strip_managed:
-  if . == null then {}
-  else with_entries(
-         .value = ((.value // [])
-           | map(.hooks = ((.hooks // []) | map(select(is_managed(.command // "") | not))))
-           | map(select((.hooks | length) > 0)))
-       )
-       | with_entries(select((.value | length) > 0))
-  end;
-def add_group($g):
-  (map(.matcher) | index($g.matcher)) as $i
-  | if $i == null then . + [$g]
-    else (.[$i]) as $ex
-      | ($g.hooks | map(select(. as $e | ($ex.hooks | any(. == $e)) | not))) as $new
-      | .[$i].hooks = ($ex.hooks + $new)
-    end;
-def merge_hooks($tpl):
-  ((. // {}) | strip_managed) as $base
-  | (reduce ($tpl | to_entries[]) as $te ({};
-       .[$te.key] = (($base[$te.key] // []) | reduce ($te.value[]) as $g (.; add_group($g)))
-     )) as $withtpl
-  | reduce ($base | keys_unsorted[]) as $k ($withtpl;
-      if ($tpl | has($k)) then . else .[$k] = $base[$k] end);
-($template[0]) as $t
-| .hooks = ((.hooks // {}) | merge_hooks($t.hooks // {}))
-| .permissions = (.permissions // {})
-| .permissions.allow = (((.permissions.allow // []) + ($t.permissions.allow // [])) | dedup)
-'
-
-# ccs_build_merged <target> — emit the merged JSON for an existing object target.
-ccs_build_merged() {
-  jq --indent 2 --slurpfile template "$SOURCE" --argjson names "$( ccs_hook_names_json )" \
-     "$JQ_MERGE" "$1"
-}
-
-# ccs_validate_object <target> — refuse (exit 1) unparseable / non-object targets
-# and malformed nested shapes. A syntactically-valid object whose `.hooks` /
-# `.permissions` is not an object, whose `.permissions.allow` is not an array, OR
-# any NESTED shape the merge jq actually walks (every `.hooks.<event>` value; each
-# element of it; that element's own `.hooks` inner list, if present; and each
-# inner entry's `.command`, where the merge does a string split/match on it) is
-# rejected here (both modes) so a bad shape never reaches jq as a raw exit-5
-# crash — only the documented 0/1/2 exit contract (see header) is ever observed.
-ccs_validate_object() {
-  local kind msg
-  if ! jq empty "$1" >/dev/null 2>&1; then
-    ccs_die 1 "target exists but is not valid JSON: $1"
-  fi
-  kind="$( jq -r 'type' "$1" )"
-  if [ "$kind" != "object" ]; then
-    ccs_die 1 "target is a JSON $kind, not an object: $1"
-  fi
-  msg="$( jq -r '
-    (.hooks // null) as $h
-    | (.permissions // null) as $p
-    | def hookmsg:
-        ($h // {}) | to_entries[]
-        | .key as $ename
-        | if (.value | type) != "array" then
-            "field .hooks." + $ename + " must be a JSON array, not a " + (.value | type)
-          else
-            (.value[] |
-              if type != "object" then
-                "field .hooks." + $ename + "[] entry must be a JSON object, not a " + type
-              elif has("hooks") and ((.hooks | type) != "array") then
-                "field .hooks." + $ename + "[].hooks must be a JSON array, not a " + (.hooks | type)
-              else
-                (.hooks // [])[] |
-                  if type != "object" then
-                    "field .hooks." + $ename + "[].hooks[] entry must be a JSON object, not a " + type
-                  elif has("command") and ((.command | type) != "string") then
-                    "field .hooks." + $ename + "[].hooks[].command must be a JSON string, not a " + (.command | type)
-                  else empty
-                  end
-              end
-            )
-          end;
-    if ($h != null and ($h | type) != "object")
-      then "field .hooks must be a JSON object, not a " + ($h | type)
-    elif ($p != null and ($p | type) != "object")
-      then "field .permissions must be a JSON object, not a " + ($p | type)
-    elif ($p != null and ($p.allow != null) and ($p.allow | type) != "array")
-      then "field .permissions.allow must be a JSON array, not a " + ($p.allow | type)
-    elif ($h != null)
-      then ([hookmsg] | first) // ""
-    else "" end' "$1" )"
-  if [ -n "$msg" ]; then
-    ccs_die 1 "$msg: $1"
-  fi
-}
-
-# ccs_same_content <a> <b> — true when two JSON files are SEMANTICALLY identical
-# (sorted-compact canonical form), so formatting-only differences never count as a
-# change. Fails closed (non-equal) if either file will not canonicalize.
-ccs_same_content() {
-  local ca cb
-  ca="$( jq -S -c . "$1" )" || return 1
-  cb="$( jq -S -c . "$2" )" || return 1
-  [ "$ca" = "$cb" ]
-}
-
-# ccs_do_dry_run — preview only; unified diff of current -> merged, never mutates.
-ccs_do_dry_run() {
-  if [ ! -e "$TARGET" ]; then
-    diff -u /dev/null "$SOURCE" || true
-    return 0
-  fi
-  ccs_validate_object "$TARGET"
-  MERGED_TMP="$( mktemp "${TMPDIR:-/tmp}/ccs-settings.XXXXXX" )"
-  ccs_build_merged "$TARGET" > "$MERGED_TMP"
-  if ccs_same_content "$TARGET" "$MERGED_TMP"; then
-    ccs_status unchanged "$TARGET"
-  else
-    diff -u "$TARGET" "$MERGED_TMP" || true
-  fi
-}
-
-# ccs_backup_dir_for — resolve the (optionally threaded) backup run dir.
-ccs_backup_dir_for() {
-  if [ -n "$BACKUP_DIR" ]; then
-    ccs_backup_run_dir --backup-dir "$BACKUP_DIR"
-  else
-    ccs_backup_run_dir
-  fi
-}
-
-# ccs_apply_fresh — no existing target: install the template verbatim (M3).
-ccs_apply_fresh() {
-  local run_dir
-  run_dir="$( ccs_backup_dir_for )"
-  ccs_atomic_install "$SOURCE" "$TARGET"
-  ccs_receipt_append "$run_dir" merged "$TARGET" ""
-  ccs_status merged "$TARGET"
-}
-
-# ccs_apply_existing — merge into an existing object target; no-op when unchanged.
-ccs_apply_existing() {
-  local run_dir
-  ccs_validate_object "$TARGET"
-  MERGED_TMP="$( mktemp "${TMPDIR:-/tmp}/ccs-settings.XXXXXX" )"
-  ccs_build_merged "$TARGET" > "$MERGED_TMP"
-  if ccs_same_content "$TARGET" "$MERGED_TMP"; then
-    ccs_status unchanged "$TARGET"
-    return 0
-  fi
-  run_dir="$( ccs_backup_dir_for )"
-  cp "$TARGET" "$run_dir/settings.json"
-  ccs_atomic_install "$MERGED_TMP" "$TARGET"
-  ccs_receipt_append "$run_dir" merged "$TARGET" "$run_dir/settings.json"
-  ccs_status merged "$TARGET"
-}
-
-main() {
-  local mode=""
-  BACKUP_DIR=""
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --dry-run) if [ -n "$mode" ]; then usage_err; fi; mode="dry" ;;
-      --apply)   if [ -n "$mode" ]; then usage_err; fi; mode="apply" ;;
-      --backup-dir) shift; if [ $# -eq 0 ]; then usage_err; fi; BACKUP_DIR="$1" ;;
-      -h|--help) usage; exit 0 ;;
-      *) usage_err ;;
-    esac
-    shift
-  done
-  if [ -z "$mode" ]; then usage_err; fi
-
-  command -v jq >/dev/null 2>&1 || ccs_die 1 "jq is required but was not found on PATH"
-  refuse_symlink "$TARGET"
-
-  if [ "$mode" = "dry" ]; then
-    ccs_do_dry_run
-  elif [ ! -e "$TARGET" ]; then
-    ccs_apply_fresh
-  else
-    ccs_apply_existing
-  fi
-}
-
-main "$@"
diff --git a/tests/check.bats b/tests/check.bats
deleted file mode 100644
index d4774ad..0000000
--- a/tests/check.bats
+++ /dev/null
@@ -1,326 +0,0 @@
-#!/usr/bin/env bats
-# tests/check.bats — coverage for scripts/check.sh (default severity map, version
-# floor tiers, --post verification) and the enforced manifest (C3).
-
-load test_helper
-
-setup() {
-  ccs_setup_sandbox
-  mkdir -p "$CLAUDE_CONFIG_DIR"
-}
-
-# --- local fixtures ----------------------------------------------------------
-
-# _stub_claude <version> [mcp_server...] — fake `claude` that answers --version
-# and `mcp list`. Any listed servers appear in the mcp output.
-_stub_claude() {
-  local ver="$1"
-  shift
-  local file="$CCS_STUB_BIN/claude" m
-  {
-    printf '#!/usr/bin/env bash\n'
-    printf 'case "$1" in\n'
-    printf '  --version) printf "%%s\\n" %q ;;\n' "$ver (Claude Code)"
-    printf '  mcp) '
-    for m in "$@"; do printf 'printf "%%s\\n" %q; ' "$m"; done
-    printf ':;;\n'
-    printf '  *) : ;;\n'
-    printf 'esac\n'
-  } > "$file"
-  chmod +x "$file"
-}
-
-_set_git_identity() {
-  git config --global user.name "Test User"
-  git config --global user.email "test@example.com"
-}
-
-# Everything present, healthy version, authed gh, identity set, MCP present.
-_stub_clean_default() {
-  ccs_make_stub jq 0
-  _stub_claude "2.1.200" context7 exa
-  ccs_make_stub gh 0
-  _set_git_identity
-}
-
-# Install every manifest artifact under $1 as an empty file (hooks executable).
-_populate_at() {
-  local base="$1" rel
-  while IFS= read -r rel || [ -n "$rel" ]; do
-    [ -n "$rel" ] || continue
-    mkdir -p "$( dirname "$base/$rel" )"
-    : > "$base/$rel"
-    case "$rel" in hooks/*.sh) chmod +x "$base/$rel" ;; esac
-  done < "$REPO_ROOT/scripts/manifest.txt"
-}
-
-_populate_claude_dir() { _populate_at "$CLAUDE_CONFIG_DIR"; }
-
-# _write_settings_with_hooks <path_prefix> — settings.json whose five hook
-# commands embed <path_prefix>/<hook>.sh (filename match is what --post checks).
-_write_settings_with_hooks() {
-  local prefix="$1"
-  cat > "$CLAUDE_CONFIG_DIR/settings.json" <<EOF
-{
-  "hooks": {
-    "PreToolUse": [
-      { "matcher": "Bash", "hooks": [ { "type": "command", "command": "bash \"$prefix/protect-branches.sh\"" } ] },
-      { "matcher": "Write|Edit", "hooks": [
-        { "type": "command", "command": "bash \"$prefix/protect-secrets.sh\"" },
-        { "type": "command", "command": "bash \"$prefix/orchestrator-delegate-guard.sh\"" },
-        { "type": "command", "command": "bash \"$prefix/design-scope-guard.sh\"" } ] }
-    ],
-    "PostToolUse": [
-      { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "bash \"$prefix/syntax-check.sh\"" } ] }
-    ]
-  }
-}
-EOF
-}
-
-_write_managed_claude_md() {
-  cat > "$CLAUDE_CONFIG_DIR/CLAUDE.md" <<'EOF'
-# Managed
-<!-- BEGIN claude-code-setup workflow-rules v1 -->
-rules
-<!-- END claude-code-setup workflow-rules v1 -->
-EOF
-}
-
-# --- default mode: severity map ---------------------------------------------
-
-@test "default: clean environment passes (exit 0)" {
-  ccs_isolate_path
-  _stub_clean_default
-  run bash "$REPO_ROOT/scripts/check.sh"
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"RESULT: PASS"* ]]
-}
-
-@test "default: missing jq fails (exit 2)" {
-  ccs_isolate_path
-  _stub_claude "2.1.200" context7 exa
-  ccs_make_stub gh 0
-  _set_git_identity
-  run bash "$REPO_ROOT/scripts/check.sh"
-  [ "$status" -eq 2 ]
-  [[ "$output" == *"jq not found"* ]]
-}
-
-@test "default: missing claude fails (exit 2)" {
-  ccs_isolate_path
-  ccs_make_stub jq 0
-  ccs_make_stub gh 0
-  _set_git_identity
-  run bash "$REPO_ROOT/scripts/check.sh"
-  [ "$status" -eq 2 ]
-  [[ "$output" == *"claude CLI not found"* ]]
-}
-
-@test "default: missing gh warns (exit 1)" {
-  ccs_isolate_path
-  ccs_make_stub jq 0
-  _stub_claude "2.1.200" context7 exa
-  _set_git_identity
-  run bash "$REPO_ROOT/scripts/check.sh"
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"gh not found"* ]]
-}
-
-@test "default: unset git identity warns (exit 1)" {
-  ccs_isolate_path
-  ccs_make_stub jq 0
-  _stub_claude "2.1.200" context7 exa
-  ccs_make_stub gh 0
-  run bash "$REPO_ROOT/scripts/check.sh"
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"user.name/user.email not set"* ]]
-}
-
-@test "default: absent MCP servers warn (exit 1)" {
-  ccs_isolate_path
-  ccs_make_stub jq 0
-  _stub_claude "2.1.200"
-  ccs_make_stub gh 0
-  _set_git_identity
-  run bash "$REPO_ROOT/scripts/check.sh"
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"MCP server absent: context7"* ]]
-}
-
-# --- default mode: version floor tiers --------------------------------------
-
-@test "version below 2.1.53 fails and states the CVE" {
-  ccs_isolate_path
-  ccs_make_stub jq 0
-  _stub_claude "2.1.40" context7 exa
-  ccs_make_stub gh 0
-  _set_git_identity
-  run bash "$REPO_ROOT/scripts/check.sh"
-  [ "$status" -eq 2 ]
-  [[ "$output" == *"CVE-2026-33068"* ]]
-}
-
-@test "version below 2.1.132 warns (sentinel session isolation)" {
-  ccs_isolate_path
-  ccs_make_stub jq 0
-  _stub_claude "2.1.100" context7 exa
-  ccs_make_stub gh 0
-  _set_git_identity
-  run bash "$REPO_ROOT/scripts/check.sh"
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"sentinel session isolation"* ]]
-}
-
-@test "version below 2.1.198 warns (Explore model override)" {
-  ccs_isolate_path
-  ccs_make_stub jq 0
-  _stub_claude "2.1.150" context7 exa
-  ccs_make_stub gh 0
-  _set_git_identity
-  run bash "$REPO_ROOT/scripts/check.sh"
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"Explore agent model override"* ]]
-}
-
-@test "version >= 2.1.198 is clean (no warnings)" {
-  ccs_isolate_path
-  _stub_clean_default
-  run bash "$REPO_ROOT/scripts/check.sh"
-  [ "$status" -eq 0 ]
-  [[ "$output" != *"WARN"* ]]
-}
-
-# --- default mode: config dir integrity -------------------------------------
-
-@test "regular-file config dir fails (exit 2)" {
-  ccs_isolate_path
-  _stub_clean_default
-  rm -rf "$CLAUDE_CONFIG_DIR"
-  printf 'x' > "$CLAUDE_CONFIG_DIR"
-  run bash "$REPO_ROOT/scripts/check.sh"
-  [ "$status" -eq 2 ]
-  [[ "$output" == *"not a directory"* ]]
-}
-
-@test "source == destination is refused (exit 2)" {
-  ccs_isolate_path
-  _stub_clean_default
-  export CLAUDE_CONFIG_DIR="$REPO_ROOT"
-  run bash "$REPO_ROOT/scripts/check.sh"
-  [ "$status" -eq 2 ]
-  [[ "$output" == *"repo root"* ]]
-}
-
-@test "relative CLAUDE_CONFIG_DIR is normalized to absolute and honored" {
-  ccs_isolate_path
-  _stub_clean_default
-  mkdir -p "$SANDBOX/relcfg"
-  cd "$SANDBOX"
-  export CLAUDE_CONFIG_DIR="relcfg"
-  run bash "$REPO_ROOT/scripts/check.sh"
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"/relcfg"* ]]
-}
-
-@test "symlinked config dir is accepted (checks pass through the link)" {
-  ccs_isolate_path
-  _stub_clean_default
-  mkdir -p "$SANDBOX/realcfg"
-  rm -rf "$CLAUDE_CONFIG_DIR"
-  ln -s "$SANDBOX/realcfg" "$CLAUDE_CONFIG_DIR"
-  run bash "$REPO_ROOT/scripts/check.sh"
-  [ "$status" -eq 0 ]
-}
-
-# --- --post mode -------------------------------------------------------------
-
-@test "post: fully installed artifacts pass (exit 0)" {
-  _populate_claude_dir
-  _write_settings_with_hooks "\${CLAUDE_CONFIG_DIR:-\$HOME/.claude}/hooks"
-  _write_managed_claude_md
-  run bash "$REPO_ROOT/scripts/check.sh" --post
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"RESULT: PASS"* ]]
-}
-
-@test "post: hooks by a different literal path still pass (filename match)" {
-  _populate_claude_dir
-  _write_settings_with_hooks "/some/totally/different/path"
-  _write_managed_claude_md
-  run bash "$REPO_ROOT/scripts/check.sh" --post
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"references all managed hooks"* ]]
-}
-
-@test "post: settings missing a managed hook filename fails (exit 2)" {
-  _populate_claude_dir
-  cat > "$CLAUDE_CONFIG_DIR/settings.json" <<'EOF'
-{ "hooks": { "PreToolUse": [ { "hooks": [
-  { "command": "bash x/protect-branches.sh" },
-  { "command": "bash x/protect-secrets.sh" },
-  { "command": "bash x/syntax-check.sh" } ] } ] } }
-EOF
-  _write_managed_claude_md
-  run bash "$REPO_ROOT/scripts/check.sh" --post
-  [ "$status" -eq 2 ]
-  [[ "$output" == *"missing managed hook"* ]]
-}
-
-@test "post: a missing managed artifact is detected (exit 2)" {
-  _populate_claude_dir
-  _write_settings_with_hooks "x"
-  _write_managed_claude_md
-  rm -f "$CLAUDE_CONFIG_DIR/hooks/protect-secrets.sh"
-  run bash "$REPO_ROOT/scripts/check.sh" --post
-  [ "$status" -eq 2 ]
-  [[ "$output" == *"missing managed artifact: hooks/protect-secrets.sh"* ]]
-}
-
-@test "post: artifacts installed to the wrong dir are detected (exit 2)" {
-  _populate_at "$SANDBOX/other/.claude"
-  run bash "$REPO_ROOT/scripts/check.sh" --post
-  [ "$status" -eq 2 ]
-  [[ "$output" == *"missing managed artifact"* ]]
-}
-
-@test "post: absent settings.json warns as a declined merge (exit 1)" {
-  _populate_claude_dir
-  _write_managed_claude_md
-  run bash "$REPO_ROOT/scripts/check.sh" --post
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"ignore if you declined this merge"* ]]
-}
-
-@test "post: valid settings.json with no managed hook entries warns (exit 1)" {
-  _populate_claude_dir
-  cat > "$CLAUDE_CONFIG_DIR/settings.json" <<'EOF'
-{ "hooks": { "PreToolUse": [ { "hooks": [
-  { "command": "bash x/some-other-hook.sh" } ] } ] } }
-EOF
-  _write_managed_claude_md
-  run bash "$REPO_ROOT/scripts/check.sh" --post
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"WARN"* ]]
-  [[ "$output" == *"ignore if you declined this merge"* ]]
-}
-
-@test "post: setup skill present under config dir fails the invariant (exit 2)" {
-  _populate_claude_dir
-  _write_settings_with_hooks "x"
-  _write_managed_claude_md
-  mkdir -p "$CLAUDE_CONFIG_DIR/skills/setup"
-  : > "$CLAUDE_CONFIG_DIR/skills/setup/SKILL.md"
-  run bash "$REPO_ROOT/scripts/check.sh" --post
-  [ "$status" -eq 2 ]
-  [[ "$output" == *"must never be installed"* ]]
-}
-
-# --- manifest enforcement (C3) ----------------------------------------------
-
-@test "manifest.txt equals git ls-files agents/ hooks/ rules/ skills/" {
-  local expected actual
-  expected="$( cd "$REPO_ROOT" && git ls-files agents/ hooks/ rules/ skills/ )"
-  actual="$( cat "$REPO_ROOT/scripts/manifest.txt" )"
-  [ "$actual" = "$expected" ]
-}
diff --git a/tests/dedupe-phrases.txt b/tests/dedupe-phrases.txt
new file mode 100644
index 0000000..c52394f
--- /dev/null
+++ b/tests/dedupe-phrases.txt
@@ -0,0 +1,15 @@
+push directly to main
+one atomic commit per task
+Co-Authored-By
+PR is opened only after
+NO_VERDICT
+ground truth over
+counter-model
+in the same turn
+check-ignore
+source detection
+three-angle
+two human checkpoints
+explicit model
+context7 before
+never commits
diff --git a/tests/e2e.bats b/tests/e2e.bats
deleted file mode 100644
index c8d8d38..0000000
--- a/tests/e2e.bats
+++ /dev/null
@@ -1,128 +0,0 @@
-#!/usr/bin/env bats
-# tests/e2e.bats — M4 end-to-end integration: the full adopter journey
-# (check -> install -> merge-settings -> merge-claude-md -> check --post),
-# run TWICE to prove the whole pipeline is byte-stable on repeat runs.
-#
-# CI reality: the `claude` binary is ABSENT on both CI runners (no real Claude
-# Code install). Rather than depend on that being true of whatever machine runs
-# this suite, `_hide_claude` (below) strips any real `claude` from PATH so
-# `check.sh` (default mode) deterministically fails for that one reason (exit 2,
-# "claude CLI not found") everywhere it runs — the point of this suite is to
-# exercise the REAL install/merge pipeline end to end, not to fabricate a
-# healthy doctor report by stubbing every tool.
-
-load test_helper
-
-# _hide_claude — strip any PATH entry that resolves a real `claude` binary, so
-# "claude is absent" is asserted deterministically on every machine (CI runners
-# and a contributor's laptop alike), rather than depending on the runner
-# happening to lack a Claude Code install. Every other real tool (jq, git,
-# bash...) stays reachable — this is NOT ccs_isolate_path's full sandboxing.
-_hide_claude() {
-  local newpath="" dir oldifs
-  oldifs="$IFS"
-  IFS=':'
-  for dir in $PATH; do
-    [ -x "$dir/claude" ] && continue
-    newpath="${newpath:+$newpath:}$dir"
-  done
-  IFS="$oldifs"
-  PATH="$newpath"
-  export PATH
-}
-
-setup() {
-  ccs_setup_sandbox
-  _hide_claude
-  # Sandbox git identity for hygiene: install/merge scripts shell out to git for
-  # provenance (ccs_repo_sha uses -C "$SCRIPT_DIR", which resolves inside the
-  # repo clone itself, so this is not strictly required for that call) but a
-  # scoped identity keeps any incidental git usage inside the sandbox honest and
-  # avoids ever touching the invoking user's real ~/.gitconfig.
-  git config --global user.name "CCS E2E"
-  git config --global user.email "ccs-e2e@example.com"
-}
-
-# _run_pipeline — one full adopter journey. Sets BACKUP_DIR as a side effect
-# (parsed from install's CCS-STATUS:backup-dir: line) so the caller can thread
-# it into the merge scripts, exactly as the /setup skill does.
-_run_pipeline() {
-  # 1. pre-install check: claude is absent in CI -> exit 2, specific reason.
-  run bash "$REPO_ROOT/scripts/check.sh"
-  [ "$status" -eq 2 ]
-  [[ "$output" == *"claude CLI not found"* ]]
-
-  # 2. real install.
-  run bash "$REPO_ROOT/scripts/install.sh"
-  [ "$status" -eq 0 ]
-  local backup_line
-  backup_line="$( printf '%s\n' "$output" | grep -m1 'CCS-STATUS:backup-dir:' )"
-  [ -n "$backup_line" ]
-  BACKUP_DIR="${backup_line#CCS-STATUS:backup-dir:}"
-  [ -d "$BACKUP_DIR" ]
-
-  # 3. merge-settings, threaded into the same run dir.
-  run bash "$REPO_ROOT/scripts/merge-settings.sh" --apply --backup-dir "$BACKUP_DIR"
-  [ "$status" -eq 0 ]
-
-  # 4. merge-claude-md, threaded into the same run dir.
-  run bash "$REPO_ROOT/scripts/merge-claude-md.sh" --apply --backup-dir "$BACKUP_DIR"
-  [ "$status" -eq 0 ]
-
-  # 5. post-install check must pass now that every managed artifact landed.
-  run bash "$REPO_ROOT/scripts/check.sh" --post
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"RESULT: PASS"* ]]
-}
-
-@test "full happy path: check -> install -> merge-settings -> merge-claude-md -> check --post (exit 0)" {
-  _run_pipeline
-
-  # Receipt exists in the run dir with plausible action lines from every step.
-  [ -f "$BACKUP_DIR/receipt.txt" ]
-  grep -qE $'^installed\t' "$BACKUP_DIR/receipt.txt"
-  grep -qE $'^merged\t' "$BACKUP_DIR/receipt.txt"
-}
-
-@test "repeat run: every step is a byte-stable no-op and --post still passes" {
-  _run_pipeline
-  local claude_md_sum settings_sum
-  claude_md_sum="$( cksum < "$CLAUDE_CONFIG_DIR/CLAUDE.md" )"
-  settings_sum="$( cksum < "$CLAUDE_CONFIG_DIR/settings.json" )"
-
-  # 1. repeat check (still no claude binary -> same specific failure).
-  run bash "$REPO_ROOT/scripts/check.sh"
-  [ "$status" -eq 2 ]
-  [[ "$output" == *"claude CLI not found"* ]]
-
-  # 2. repeat install: no installs/overwrites, every manifest entry unchanged.
-  run bash "$REPO_ROOT/scripts/install.sh"
-  [ "$status" -eq 0 ]
-  [[ "$output" != *"CCS-STATUS:installed:"* ]]
-  [[ "$output" != *"CCS-STATUS:overwritten:"* ]]
-  local rel
-  while IFS= read -r rel || [ -n "$rel" ]; do
-    [ -n "$rel" ] || continue
-    [[ "$output" == *"CCS-STATUS:unchanged:$rel"* ]]
-  done < "$REPO_ROOT/scripts/manifest.txt"
-  local repeat_backup_line repeat_backup_dir
-  repeat_backup_line="$( printf '%s\n' "$output" | grep -m1 'CCS-STATUS:backup-dir:' )"
-  repeat_backup_dir="${repeat_backup_line#CCS-STATUS:backup-dir:}"
-
-  # 3. repeat merge-settings: byte-stable unchanged no-op.
-  run bash "$REPO_ROOT/scripts/merge-settings.sh" --apply --backup-dir "$repeat_backup_dir"
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"CCS-STATUS:unchanged:"* ]]
-  [ "$( cksum < "$CLAUDE_CONFIG_DIR/settings.json" )" = "$settings_sum" ]
-
-  # 4. repeat merge-claude-md: byte-stable unchanged no-op.
-  run bash "$REPO_ROOT/scripts/merge-claude-md.sh" --apply --backup-dir "$repeat_backup_dir"
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"CCS-STATUS:unchanged:"* ]]
-  [ "$( cksum < "$CLAUDE_CONFIG_DIR/CLAUDE.md" )" = "$claude_md_sum" ]
-
-  # 5. --post is still green.
-  run bash "$REPO_ROOT/scripts/check.sh" --post
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"RESULT: PASS"* ]]
-}
diff --git a/tests/hooks.bats b/tests/hooks.bats
deleted file mode 100644
index e8088bc..0000000
--- a/tests/hooks.bats
+++ /dev/null
@@ -1,329 +0,0 @@
-#!/usr/bin/env bats
-# Tests for hooks/orchestrator-delegate-guard.sh's plan-file allowlist across both
-# the default ($HOME/.claude) and CLAUDE_CONFIG_DIR-based config layouts.
-#
-# Self-contained on purpose: does NOT source tests/test_helper.bash (owned by a
-# different, concurrently-running task) and never touches any real
-# /tmp/claude-orchestrator-active* sentinel -- only one fabricated per-test
-# session id, created in setup() and removed in teardown().
-
-setup() {
-  HOOK="${BATS_TEST_DIRNAME}/../hooks/orchestrator-delegate-guard.sh"
-  DESIGN_HOOK="${BATS_TEST_DIRNAME}/../hooks/design-scope-guard.sh"
-
-  # Unique, throwaway session id/sentinel per test -- never the real global sentinel.
-  SID="bats-guard-$$-${RANDOM}${RANDOM}"
-  SENTINEL="/tmp/claude-orchestrator-active.${SID}"
-  touch "$SENTINEL"
-
-  # design-scope-guard.sh sentinel -- distinct filename prefix from $SENTINEL above,
-  # so the two guards' sentinels never collide. NOT touched by default: tests that
-  # need /design "active" call design_sentinel_on() explicitly; tests that need it
-  # absent (the fast-path case) simply never call it. Always removed in teardown.
-  DESIGN_SENTINEL="/tmp/claude-design-active.${SID}"
-
-  # Fake HOME/CLAUDE_CONFIG_DIR sandboxes MUST NOT live under /tmp: the hook's
-  # own "/tmp/*" allowlist rule (line ~59) would then match any file path
-  # inside them and exit 0 before the CLAUDE_CONFIG_DIR branch under test is
-  # ever evaluated, making the assertion vacuously true (it stays green even
-  # if that branch is deleted). Root the sandbox under the real $HOME instead
-  # -- guaranteed writable in CI and outside /tmp on both macOS and Linux.
-  REAL_HOME="$HOME"
-  SANDBOX_ROOT="$(mktemp -d "${REAL_HOME}/.ccs-hooks-test.XXXXXX")"
-  case "$SANDBOX_ROOT" in
-    /tmp/*)
-      echo "FATAL: sandbox root resolved under /tmp ($SANDBOX_ROOT) -- would make the CLAUDE_CONFIG_DIR allowlist test vacuous. Aborting." >&2
-      return 1
-      ;;
-  esac
-
-  TEST_HOME="${SANDBOX_ROOT}/home"
-  TEST_CONFIG_DIR="${SANDBOX_ROOT}/config"
-  mkdir -p "$TEST_HOME/.claude/plans" "$TEST_CONFIG_DIR/plans"
-
-  # Git-backed fixture project. The guards anchor their project-relative
-  # allowances to `git -C "$cwd" rev-parse --show-toplevel` (cwd from the hook
-  # payload), so a real repo here makes ROOT resolve deterministically to $PROJ
-  # -- exercising the production git path -- instead of depending on whether the
-  # sandbox's parent happens to be a repo. OTHER is an out-of-project tree used
-  # for the anchoring-bypass assertions; it is never the session cwd.
-  PROJ="${SANDBOX_ROOT}/proj"
-  OTHER="${SANDBOX_ROOT}/other-repo"
-  mkdir -p "$PROJ" "$OTHER"
-  git -C "$PROJ" init -q
-
-  export HOME="$TEST_HOME"
-  unset CLAUDE_CONFIG_DIR
-}
-
-teardown() {
-  rm -f "$SENTINEL" "$DESIGN_SENTINEL"
-  # Guard against an empty/unset SANDBOX_ROOT (e.g. setup aborted before it was
-  # set) turning `rm -rf` into a no-op-on-cwd footgun.
-  [ -n "${SANDBOX_ROOT:-}" ] && rm -rf "$SANDBOX_ROOT"
-}
-
-# Builds the PreToolUse(Write|Edit) stdin JSON shape the hook reads: session_id
-# (sentinel lookup), cwd (project-root anchoring), and tool_input.file_path
-# (allowlist check). agent_type is intentionally omitted -- absent means "main
-# thread" per the hook's own comment. Optional arg 2 is the session cwd; when
-# omitted the cwd field is empty, which is exactly the fail-closed case the
-# guard treats as "no project root" (project-relative arms match nothing).
-json_for() {
-  printf '{"session_id":"%s","cwd":"%s","tool_input":{"file_path":"%s"}}' "$SID" "${2:-}" "$1"
-}
-
-# Turns the design-scope-guard sentinel "on" for the current test's session id.
-design_sentinel_on() {
-  touch "$DESIGN_SENTINEL"
-}
-
-# Same stdin shape as json_for(), plus tool_name -- design-scope-guard.sh does not
-# read tool_name at all (it only inspects tool_input.file_path), so a Write vs Edit
-# probe on the same file_path must produce identical exit codes. That parity is
-# what the "source-path probes" test below asserts. Optional arg 3 is the session
-# cwd (project-root anchoring); omitted => empty cwd => fail-closed "no root".
-json_for_design() {
-  printf '{"session_id":"%s","cwd":"%s","tool_name":"%s","tool_input":{"file_path":"%s"}}' "$SID" "${3:-}" "$2" "$1"
-}
-
-@test "plan-file edit under \$HOME/.claude/plans is allowed (default layout)" {
-  run bash "$HOOK" <<< "$(json_for "$TEST_HOME/.claude/plans/adopter-setup-tasks.md")"
-  [ "$status" -eq 0 ]
-}
-
-@test "plan-file edit under \$CLAUDE_CONFIG_DIR/plans is allowed when set" {
-  export CLAUDE_CONFIG_DIR="$TEST_CONFIG_DIR"
-  run bash "$HOOK" <<< "$(json_for "$TEST_CONFIG_DIR/plans/adopter-setup-tasks.md")"
-  [ "$status" -eq 0 ]
-}
-
-@test "source-file edit is blocked while sentinel is active (default layout)" {
-  run bash "$HOOK" <<< "$(json_for "/opt/some-project/src/main.py")"
-  [ "$status" -eq 2 ]
-  [[ "$output" == *"Blocked"* ]]
-}
-
-@test "source-file edit is blocked while sentinel is active (CLAUDE_CONFIG_DIR layout)" {
-  export CLAUDE_CONFIG_DIR="$TEST_CONFIG_DIR"
-  run bash "$HOOK" <<< "$(json_for "/opt/some-project/src/main.py")"
-  [ "$status" -eq 2 ]
-  [[ "$output" == *"Blocked"* ]]
-}
-
-# Intent unchanged (in-project artifact writes stay allowed); now anchored --
-# the path lives under the session project ($PROJ) supplied as cwd.
-@test "delegate-guard: docs/plans/ write is allowed while sentinel is active" {
-  run bash "$HOOK" <<< "$(json_for "$PROJ/docs/plans/some-slug/draft.md" "$PROJ")"
-  [ "$status" -eq 0 ]
-}
-
-@test "delegate-guard: .gitattributes write is allowed while sentinel is active" {
-  run bash "$HOOK" <<< "$(json_for "$PROJ/.gitattributes" "$PROJ")"
-  [ "$status" -eq 0 ]
-}
-
-@test "delegate-guard: near-miss docs/plansX/ (not docs/plans/) is still blocked" {
-  run bash "$HOOK" <<< "$(json_for "$PROJ/docs/plansX/evil.md" "$PROJ")"
-  [ "$status" -eq 2 ]
-  [[ "$output" == *"Blocked"* ]]
-}
-
-# --- hooks/design-scope-guard.sh ---------------------------------------------
-# Same sandbox/sentinel-isolation conventions as above, applied to the sibling
-# guard: a per-test session id, a scratch sentinel file, and (per this file's
-# own note at setup()'s SANDBOX_ROOT check) fixture paths rooted outside /tmp
-# so the hook's own "/tmp/*" allowlist branch can't make an assertion vacuous.
-
-@test "design-scope-guard: docs/plans/ write under a project fixture is allowed while sentinel is active" {
-  design_sentinel_on
-  FIXTURE="$PROJ/docs/plans/some-slug/draft.md"
-  run bash "$DESIGN_HOOK" <<< "$(json_for_design "$FIXTURE" "Write" "$PROJ")"
-  [ "$status" -eq 0 ]
-}
-
-@test "design-scope-guard: source-path probe is blocked identically for Write and Edit tool shapes" {
-  design_sentinel_on
-  FIXTURE="$SANDBOX_ROOT/proj/src/main.py"
-
-  run bash "$DESIGN_HOOK" <<< "$(json_for_design "$FIXTURE" "Write")"
-  [ "$status" -eq 2 ]
-  write_output="$output"
-
-  run bash "$DESIGN_HOOK" <<< "$(json_for_design "$FIXTURE" "Edit")"
-  [ "$status" -eq 2 ]
-
-  # Note: issue #37210 documents a harness-side runtime caveat around how the
-  # test harness replays Write vs Edit shapes -- it is not a defect in this
-  # hook. The hook itself never reads tool_name, so both shapes must agree.
-  [ "$output" = "$write_output" ]
-}
-
-@test "design-scope-guard: fast path allows any write when no design sentinel exists" {
-  # Deliberately do NOT call design_sentinel_on() -- exercises the jq-free
-  # `ls /tmp/claude-design-active*` fast path taken when /design isn't active.
-  FIXTURE="$SANDBOX_ROOT/proj/src/main.py"
-  run bash "$DESIGN_HOOK" <<< "$(json_for_design "$FIXTURE" "Write")"
-  [ "$status" -eq 0 ]
-}
-
-# --- hardening matrix: fail-closed on unparseable input, .. traversal, ------
-# relative/empty paths -- for BOTH guards. Existing allow-cases above must
-# still pass unchanged.
-
-# Builds the same stdin shape as json_for(), but with an explicit agent_type,
-# for the one subagent-exemption pin below. json_for()/json_for_design()
-# intentionally omit agent_type (absent == main thread).
-json_for_with_agent() {
-  printf '{"session_id":"%s","agent_type":"%s","tool_input":{"file_path":"%s"}}' "$SID" "$1" "$2"
-}
-
-@test "delegate-guard: .. traversal via an allowlisted prefix is blocked" {
-  FIXTURE="$SANDBOX_ROOT/proj/docs/plans/../../../etc/evil"
-  run bash "$HOOK" <<< "$(json_for "$FIXTURE")"
-  [ "$status" -eq 2 ]
-}
-
-@test "delegate-guard: relative file_path is blocked" {
-  run bash "$HOOK" <<< "$(json_for "docs/plans/x.md")"
-  [ "$status" -eq 2 ]
-}
-
-@test "delegate-guard: empty file_path is blocked" {
-  run bash "$HOOK" <<< "$(json_for "")"
-  [ "$status" -eq 2 ]
-}
-
-@test "delegate-guard: malformed JSON on stdin is blocked (parse gate)" {
-  run bash "$HOOK" <<< "$(printf 'not-json{{{')"
-  [ "$status" -eq 2 ]
-}
-
-@test "delegate-guard: /tmp/../etc/passwd is blocked (.. check precedes /tmp/* allow arm)" {
-  run bash "$HOOK" <<< "$(json_for "/tmp/../etc/passwd")"
-  [ "$status" -eq 2 ]
-}
-
-@test "delegate-guard: subagent with a .. path is exempt (main-thread-only scope)" {
-  FIXTURE="$SANDBOX_ROOT/proj/docs/plans/../../../etc/evil"
-  run bash "$HOOK" <<< "$(json_for_with_agent "implementer" "$FIXTURE")"
-  [ "$status" -eq 0 ]
-}
-
-@test "design-scope-guard: .. traversal via an allowlisted prefix is blocked" {
-  design_sentinel_on
-  FIXTURE="$SANDBOX_ROOT/proj/docs/plans/../../../etc/evil"
-  run bash "$DESIGN_HOOK" <<< "$(json_for_design "$FIXTURE" "Write")"
-  [ "$status" -eq 2 ]
-}
-
-@test "design-scope-guard: relative file_path is blocked" {
-  design_sentinel_on
-  run bash "$DESIGN_HOOK" <<< "$(json_for_design "docs/plans/x.md" "Write")"
-  [ "$status" -eq 2 ]
-}
-
-@test "design-scope-guard: empty file_path is blocked" {
-  design_sentinel_on
-  run bash "$DESIGN_HOOK" <<< "$(json_for_design "" "Write")"
-  [ "$status" -eq 2 ]
-}
-
-@test "design-scope-guard: malformed JSON on stdin is blocked (parse gate)" {
-  design_sentinel_on
-  run bash "$DESIGN_HOOK" <<< "$(printf 'not-json{{{')"
-  [ "$status" -eq 2 ]
-}
-
-@test "design-scope-guard: /tmp/../etc/passwd is blocked (.. check precedes /tmp/* allow arm)" {
-  design_sentinel_on
-  run bash "$DESIGN_HOOK" <<< "$(json_for_design "/tmp/../etc/passwd" "Write")"
-  [ "$status" -eq 2 ]
-}
-
-# --- project-root anchoring matrix (both guards) ------------------------------
-# The project-relative allowances (docs/plans/, docs/research/, .gitattributes)
-# must bind to the session project root (git toplevel of the payload cwd), not
-# match those path shapes anywhere on disk. cwd is always the git-backed $PROJ
-# fixture; $OTHER is a sibling out-of-project tree.
-
-@test "delegate-guard: out-of-project docs/plans/ is denied even though the shape matches" {
-  run bash "$HOOK" <<< "$(json_for "$OTHER/docs/plans/x/design.md" "$PROJ")"
-  [ "$status" -eq 2 ]
-  [[ "$output" == *"Blocked"* ]]
-}
-
-@test "delegate-guard: out-of-project docs/research/ is denied even though the shape matches" {
-  run bash "$HOOK" <<< "$(json_for "$OTHER/docs/research/x.md" "$PROJ")"
-  [ "$status" -eq 2 ]
-}
-
-@test "delegate-guard: out-of-project (\$HOME) .gitattributes is denied" {
-  run bash "$HOOK" <<< "$(json_for "$HOME/.gitattributes" "$PROJ")"
-  [ "$status" -eq 2 ]
-}
-
-@test "delegate-guard: in-project docs/research/ under the session cwd is allowed" {
-  run bash "$HOOK" <<< "$(json_for "$PROJ/docs/research/x.md" "$PROJ")"
-  [ "$status" -eq 0 ]
-}
-
-@test "delegate-guard: in-project root .gitattributes under the session cwd is allowed" {
-  run bash "$HOOK" <<< "$(json_for "$PROJ/.gitattributes" "$PROJ")"
-  [ "$status" -eq 0 ]
-}
-
-@test "delegate-guard: empty cwd denies a project-relative path (fail closed) but still allows plans dir and /tmp" {
-  run bash "$HOOK" <<< "$(json_for "$PROJ/docs/plans/x/design.md")"
-  [ "$status" -eq 2 ]
-  [[ "$output" == *"Blocked"* ]]
-
-  run bash "$HOOK" <<< "$(json_for "$TEST_HOME/.claude/plans/adopter-setup-tasks.md")"
-  [ "$status" -eq 0 ]
-
-  run bash "$HOOK" <<< "$(json_for "/tmp/anything.md")"
-  [ "$status" -eq 0 ]
-}
-
-@test "design-scope-guard: out-of-project docs/plans/ is denied even though the shape matches" {
-  design_sentinel_on
-  run bash "$DESIGN_HOOK" <<< "$(json_for_design "$OTHER/docs/plans/x/design.md" "Write" "$PROJ")"
-  [ "$status" -eq 2 ]
-}
-
-@test "design-scope-guard: out-of-project docs/research/ is denied even though the shape matches" {
-  design_sentinel_on
-  run bash "$DESIGN_HOOK" <<< "$(json_for_design "$OTHER/docs/research/x.md" "Write" "$PROJ")"
-  [ "$status" -eq 2 ]
-}
-
-@test "design-scope-guard: out-of-project (\$HOME) .gitattributes is denied" {
-  design_sentinel_on
-  run bash "$DESIGN_HOOK" <<< "$(json_for_design "$HOME/.gitattributes" "Write" "$PROJ")"
-  [ "$status" -eq 2 ]
-}
-
-@test "design-scope-guard: in-project docs/research/ under the session cwd is allowed" {
-  design_sentinel_on
-  run bash "$DESIGN_HOOK" <<< "$(json_for_design "$PROJ/docs/research/x.md" "Write" "$PROJ")"
-  [ "$status" -eq 0 ]
-}
-
-@test "design-scope-guard: in-project root .gitattributes under the session cwd is allowed" {
-  design_sentinel_on
-  run bash "$DESIGN_HOOK" <<< "$(json_for_design "$PROJ/.gitattributes" "Write" "$PROJ")"
-  [ "$status" -eq 0 ]
-}
-
-@test "design-scope-guard: empty cwd denies a project-relative path (fail closed) but still allows plans dir and /tmp" {
-  design_sentinel_on
-
-  run bash "$DESIGN_HOOK" <<< "$(json_for_design "$PROJ/docs/plans/x/design.md" "Write")"
-  [ "$status" -eq 2 ]
-
-  run bash "$DESIGN_HOOK" <<< "$(json_for_design "$TEST_HOME/.claude/plans/adopter-setup-tasks.md" "Write")"
-  [ "$status" -eq 0 ]
-
-  run bash "$DESIGN_HOOK" <<< "$(json_for_design "/tmp/anything.md" "Write")"
-  [ "$status" -eq 0 ]
-}
diff --git a/tests/install.bats b/tests/install.bats
deleted file mode 100644
index 94b0ded..0000000
--- a/tests/install.bats
+++ /dev/null
@@ -1,331 +0,0 @@
-#!/usr/bin/env bats
-# tests/install.bats — coverage for scripts/install.sh (manifest-driven
-# install/unchanged/skip/overwrite policy, backups, receipts, dry-run safety).
-
-load test_helper
-
-setup() {
-  ccs_setup_sandbox
-}
-
-# --- local fixtures ----------------------------------------------------------
-
-_install() { run bash "$REPO_ROOT/scripts/install.sh" "$@"; }
-
-_expected_sha() { git -C "$REPO_ROOT" rev-parse HEAD; }
-
-# _agent_rel / _hook_rel — first manifest entries per category, resolved
-# dynamically so these tests stay valid if the manifest contents change.
-_agent_rel() { grep '^agents/' "$REPO_ROOT/scripts/manifest.txt" | head -n 1; }
-_hook_rel()  { grep '^hooks/'  "$REPO_ROOT/scripts/manifest.txt" | head -n 1; }
-
-# _tree_digest <dir> — content-sensitive digest of an entire directory tree
-# (paths + file contents), used to prove --dry-run performs zero mutations.
-_tree_digest() {
-  ( cd "$1" 2>/dev/null && find . -type f -print0 | LC_ALL=C sort -z \
-      | while IFS= read -r -d '' f; do printf '%s\n' "$f"; cat "$f"; done ) \
-    | shasum -a 256 | awk '{print $1}'
-}
-
-_receipt_files() {
-  find "$CLAUDE_CONFIG_DIR/backups/claude-code-setup" -name receipt.txt 2>/dev/null
-}
-
-# --- fresh install -----------------------------------------------------------
-
-@test "fresh install into a nonexistent CLAUDE_DIR creates it and installs everything" {
-  [ ! -e "$CLAUDE_CONFIG_DIR" ]
-  _install
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"CCS-STATUS:backup-dir:"* ]]
-  local rel
-  while IFS= read -r rel || [ -n "$rel" ]; do
-    [ -n "$rel" ] || continue
-    [ -e "$CLAUDE_CONFIG_DIR/$rel" ]
-    [[ "$output" == *"CCS-STATUS:installed:$rel"* ]]
-  done < "$REPO_ROOT/scripts/manifest.txt"
-  [ -d "$CLAUDE_CONFIG_DIR/plans" ]
-}
-
-@test "hooks are installed executable" {
-  _install
-  [ "$status" -eq 0 ]
-  local rel
-  while IFS= read -r rel || [ -n "$rel" ]; do
-    case "$rel" in
-      hooks/*) [ -x "$CLAUDE_CONFIG_DIR/$rel" ] ;;
-    esac
-  done < "$REPO_ROOT/scripts/manifest.txt"
-}
-
-@test "idempotent second run reports unchanged everywhere and adds no backup content" {
-  _install
-  [ "$status" -eq 0 ]
-  local before_receipts after_receipts
-  before_receipts="$( _receipt_files | wc -l | tr -d ' ' )"
-
-  _install
-  [ "$status" -eq 0 ]
-  [[ "$output" != *"CCS-STATUS:installed:"* ]]
-  [[ "$output" != *"CCS-STATUS:overwritten:"* ]]
-  local rel
-  while IFS= read -r rel || [ -n "$rel" ]; do
-    [ -n "$rel" ] || continue
-    [[ "$output" == *"CCS-STATUS:unchanged:$rel"* ]]
-  done < "$REPO_ROOT/scripts/manifest.txt"
-
-  after_receipts="$( _receipt_files | wc -l | tr -d ' ' )"
-  # A run dir/receipt is (re)created each run (same-second timestamps may
-  # collide with the fresh install's dir, so only assert non-regression), but
-  # no run dir may carry copied adopter-file content beyond receipt.txt itself.
-  [ "$after_receipts" -ge "$before_receipts" ]
-  local d
-  while IFS= read -r d; do
-    [ -n "$d" ] || continue
-    [ "$( find "$d" -type f ! -name receipt.txt | wc -l | tr -d ' ' )" -eq 0 ]
-  done < <( _receipt_files | xargs -n1 dirname )
-}
-
-@test "CLAUDE_CONFIG_DIR override is honored end to end" {
-  local custom="$SANDBOX/custom-claude-dir"
-  CLAUDE_CONFIG_DIR="$custom"
-  export CLAUDE_CONFIG_DIR
-  _install
-  [ "$status" -eq 0 ]
-  [ -e "$custom/$( _agent_rel )" ]
-  [ ! -e "$HOME/.claude" ]
-}
-
-@test "symlinked CLAUDE_DIR is accepted: install lands through the link" {
-  local real="$SANDBOX/real-claude-target"
-  mkdir -p "$real"
-  ln -s "$real" "$CLAUDE_CONFIG_DIR"
-  _install
-  [ "$status" -eq 0 ]
-  [ -L "$CLAUDE_CONFIG_DIR" ]
-  [ -e "$real/$( _agent_rel )" ]
-}
-
-# --- differs / force policy ---------------------------------------------------
-
-@test "differing files are skipped per category, then --force=<category> overwrites only that category" {
-  _install
-  [ "$status" -eq 0 ]
-  local agent_rel hook_rel
-  agent_rel="$( _agent_rel )"
-  hook_rel="$( _hook_rel )"
-  printf '\nadopter edit\n' >> "$CLAUDE_CONFIG_DIR/$agent_rel"
-  printf '\n# adopter edit\n' >> "$CLAUDE_CONFIG_DIR/$hook_rel"
-
-  _install
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"CCS-STATUS:skipped:$agent_rel"* ]]
-  [[ "$output" == *"CCS-STATUS:skipped:$hook_rel"* ]]
-  [[ "$( cat "$CLAUDE_CONFIG_DIR/$agent_rel" )" == *"adopter edit"* ]]
-  [[ "$( cat "$CLAUDE_CONFIG_DIR/$hook_rel" )" == *"adopter edit"* ]]
-
-  run bash "$REPO_ROOT/scripts/install.sh" --force=agents
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"CCS-STATUS:overwritten:$agent_rel"* ]]
-  [[ "$output" != *"CCS-STATUS:overwritten:$hook_rel"* ]]
-  cmp -s "$REPO_ROOT/$agent_rel" "$CLAUDE_CONFIG_DIR/$agent_rel"
-  [[ "$( cat "$CLAUDE_CONFIG_DIR/$hook_rel" )" == *"adopter edit"* ]]
-
-  local latest backup_dir
-  latest="$( _receipt_files | LC_ALL=C sort | tail -n 1 )"
-  backup_dir="$( dirname "$latest" )"
-  [ -e "$backup_dir/$agent_rel" ]
-  [[ "$( cat "$backup_dir/$agent_rel" )" == *"adopter edit"* ]]
-  grep -qE $'^overwritten\t'"$CLAUDE_CONFIG_DIR/$agent_rel"$'\t'"$backup_dir/$agent_rel" "$latest"
-}
-
-@test "plain --force overwrites all differing categories" {
-  _install
-  [ "$status" -eq 0 ]
-  local agent_rel hook_rel
-  agent_rel="$( _agent_rel )"
-  hook_rel="$( _hook_rel )"
-  printf '\nadopter edit\n' >> "$CLAUDE_CONFIG_DIR/$agent_rel"
-  printf '\n# adopter edit\n' >> "$CLAUDE_CONFIG_DIR/$hook_rel"
-
-  run bash "$REPO_ROOT/scripts/install.sh" --force
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"CCS-STATUS:overwritten:$agent_rel"* ]]
-  [[ "$output" == *"CCS-STATUS:overwritten:$hook_rel"* ]]
-  cmp -s "$REPO_ROOT/$agent_rel" "$CLAUDE_CONFIG_DIR/$agent_rel"
-  cmp -s "$REPO_ROOT/$hook_rel" "$CLAUDE_CONFIG_DIR/$hook_rel"
-  [ -x "$CLAUDE_CONFIG_DIR/$hook_rel" ]
-}
-
-@test "receipt records installed/overwritten/skipped action types with the repo sha" {
-  _install
-  [ "$status" -eq 0 ]
-  local agent_rel
-  agent_rel="$( _agent_rel )"
-  printf '\nadopter edit\n' >> "$CLAUDE_CONFIG_DIR/$agent_rel"
-
-  run bash "$REPO_ROOT/scripts/install.sh" --force=agents
-  [ "$status" -eq 0 ]
-
-  local sha latest
-  sha="$( _expected_sha )"
-  latest="$( _receipt_files | LC_ALL=C sort | tail -n 1 )"
-  grep -qE $'^overwritten\t' "$latest"
-  grep -q "$sha" "$latest"
-
-  local first
-  first="$( _receipt_files | LC_ALL=C sort | head -n 1 )"
-  grep -qE $'^installed\t' "$first"
-  grep -q "$sha" "$first"
-}
-
-# --- dry-run safety -----------------------------------------------------------
-
-@test "dry-run performs zero mutations" {
-  _install
-  [ "$status" -eq 0 ]
-  local before after
-  before="$( _tree_digest "$CLAUDE_CONFIG_DIR" )"
-  run bash "$REPO_ROOT/scripts/install.sh" --dry-run
-  [ "$status" -eq 0 ]
-  after="$( _tree_digest "$CLAUDE_CONFIG_DIR" )"
-  [ "$before" = "$after" ]
-}
-
-@test "dry-run --diff previews a unified diff and still mutates nothing" {
-  _install
-  [ "$status" -eq 0 ]
-  local agent_rel
-  agent_rel="$( _agent_rel )"
-  printf '\nadopter edit\n' >> "$CLAUDE_CONFIG_DIR/$agent_rel"
-
-  local before after
-  before="$( _tree_digest "$CLAUDE_CONFIG_DIR" )"
-  run bash "$REPO_ROOT/scripts/install.sh" --dry-run --diff
-  [ "$status" -eq 0 ]
-  after="$( _tree_digest "$CLAUDE_CONFIG_DIR" )"
-  [ "$before" = "$after" ]
-  [[ "$output" == *"CCS-STATUS:skipped:$agent_rel"* ]]
-  [[ "$output" == *"+++ $REPO_ROOT/$agent_rel"* ]]
-  [[ "$( cat "$CLAUDE_CONFIG_DIR/$agent_rel" )" == *"adopter edit"* ]]
-}
-
-@test "--diff without --dry-run is a usage error (exit 2)" {
-  run bash "$REPO_ROOT/scripts/install.sh" --diff
-  [ "$status" -eq 2 ]
-}
-
-@test "--dry-run must be the first flag (exit 2 otherwise)" {
-  run bash "$REPO_ROOT/scripts/install.sh" --force --dry-run
-  [ "$status" -eq 2 ]
-}
-
-# --- symlinked destination file ------------------------------------------------
-
-# --- manifest path-traversal guard --------------------------------------------
-
-# _sandboxed_repo — copy the repo tree into the sandbox so a malicious manifest
-# line can be injected without touching the real scripts/manifest.txt. Echoes
-# the copy's root path.
-_sandboxed_repo() {
-  local copy="$SANDBOX/repo-copy"
-  mkdir -p "$copy"
-  cp -R "$REPO_ROOT/." "$copy/"
-  printf '%s\n' "$copy"
-}
-
-@test "a manifest line escaping the config dir via ../ is refused: non-zero exit, names the line, writes nothing outside CLAUDE_DIR" {
-  local copy
-  copy="$( _sandboxed_repo )"
-  # A faithful PoC: if the guard were absent, this line would resolve to
-  # "$CLAUDE_CONFIG_DIR/../pwned-outside.txt" == "$HOME/pwned-outside.txt", and
-  # the source file below would let that write actually succeed.
-  printf '../pwned-outside.txt\n' >> "$copy/scripts/manifest.txt"
-  printf 'pwned\n' > "$copy/pwned-outside.txt"
-
-  run bash "$copy/scripts/install.sh"
-  [ "$status" -ne 0 ]
-  [[ "$output" == *"CCS:"* ]]
-  [[ "$output" == *"../pwned-outside.txt"* ]]
-  [ ! -e "$HOME/pwned-outside.txt" ]
-  [ ! -e "$CLAUDE_CONFIG_DIR" ]
-}
-
-@test "an absolute-path manifest line is refused: non-zero exit and names the line" {
-  local copy
-  copy="$( _sandboxed_repo )"
-  printf '/etc/should-not-install.txt\n' >> "$copy/scripts/manifest.txt"
-
-  run bash "$copy/scripts/install.sh"
-  [ "$status" -ne 0 ]
-  [[ "$output" == *"CCS:"* ]]
-  [[ "$output" == *"/etc/should-not-install.txt"* ]]
-  [ ! -e "$CLAUDE_CONFIG_DIR" ]
-}
-
-# The two tests above are satisfied by install.sh's category allowlist alone
-# (../pwned-outside.txt and /etc/... never carry a valid category prefix, so
-# they never reach ccs_validate_manifest_rel's ".." check) — mutation testing
-# proved both stay green even with ccs_validate_manifest_rel neutered to a
-# no-op. This test uses a category-prefixed escape that ONLY the traversal
-# guard can catch.
-@test "a manifest line with a valid category prefix but an embedded ../ escape is refused by the traversal guard, not the category check" {
-  local copy
-  copy="$( _sandboxed_repo )"
-  # "agents/" is on install.sh's category allowlist, so only
-  # ccs_validate_manifest_rel's embedded-".." check -- not the category check --
-  # can catch this line. The two ".." segments cancel "agents" and then step out
-  # of CLAUDE_CONFIG_DIR (.claude), landing at $HOME.
-  local rel="agents/../../pwned-in-home.txt"
-  printf '%s\n' "$rel" >> "$copy/scripts/manifest.txt"
-  # A faithful PoC source file: if the guard were absent, this content would
-  # actually land at $HOME/pwned-in-home.txt.
-  printf 'pwned\n' > "$SANDBOX/pwned-in-home.txt"
-
-  run bash "$copy/scripts/install.sh"
-  [ "$status" -ne 0 ]
-  [[ "$output" == *"CCS: manifest path escapes the config dir: $rel"* ]]
-  [[ "$output" != *"unmanaged category"* ]]
-  [ ! -e "$HOME/pwned-in-home.txt" ]
-  [ ! -e "$CLAUDE_CONFIG_DIR" ]
-}
-
-# --- unchanged-hook executable-bit repair -------------------------------------
-
-@test "a byte-identical hook with a stripped +x bit is repaired without --force and stays a no-op after" {
-  _install
-  [ "$status" -eq 0 ]
-  local hook_rel
-  hook_rel="$( _hook_rel )"
-  chmod -x "$CLAUDE_CONFIG_DIR/$hook_rel"
-  [ ! -x "$CLAUDE_CONFIG_DIR/$hook_rel" ]
-
-  _install
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"CCS-STATUS:unchanged:$hook_rel"* ]]
-  [[ "$output" == *"restored missing executable bit: $hook_rel"* ]]
-  [ -x "$CLAUDE_CONFIG_DIR/$hook_rel" ]
-  cmp -s "$REPO_ROOT/$hook_rel" "$CLAUDE_CONFIG_DIR/$hook_rel"
-
-  _install
-  [ "$status" -eq 0 ]
-  [[ "$output" != *"restored missing executable bit"* ]]
-  [[ "$output" == *"CCS-STATUS:unchanged:$hook_rel"* ]]
-  [ -x "$CLAUDE_CONFIG_DIR/$hook_rel" ]
-}
-
-@test "a symlinked destination file is refused, reported, and other files still install" {
-  local agent_rel hook_rel target
-  agent_rel="$( _agent_rel )"
-  hook_rel="$( _hook_rel )"
-  mkdir -p "$CLAUDE_CONFIG_DIR/$( dirname "$agent_rel" )"
-  target="$SANDBOX/elsewhere.md"
-  printf 'not managed\n' > "$target"
-  ln -s "$target" "$CLAUDE_CONFIG_DIR/$agent_rel"
-
-  _install
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"refusing to write through symlink"* ]]
-  [[ "$output" == *"CCS-STATUS:installed:$hook_rel"* ]]
-  [ -L "$CLAUDE_CONFIG_DIR/$agent_rel" ]
-}
diff --git a/tests/manual-setup-checklist.md b/tests/manual-setup-checklist.md
deleted file mode 100644
index 6583278..0000000
--- a/tests/manual-setup-checklist.md
+++ /dev/null
@@ -1,67 +0,0 @@
-# Manual pre-PR checklist — `/setup` walkthrough
-
-This is the **pre-PR human gate** for the repo-scoped `/setup` router skill
-(`.claude/skills/setup/SKILL.md`). The skill orchestrates the four scripts and cannot be
-fully verified by the automated `.bats` suites, because its behavior is a *conversation*
-(diffs shown, consent taken, prompts raised). Walk a temp clone through `/setup` and confirm
-each item below before opening the PR.
-
-## Setup
-
-1. `git clone` this repo (or copy the working tree) into a scratch dir, e.g.
-   `/tmp/ccs-setup-test`.
-2. Point Claude Code's config dir at a **throwaway** location (do NOT test against your real
-   `~/.claude`) — e.g. export the config-dir override the scripts honor, or use a disposable
-   `$HOME`. Confirm the target is disposable before running any `--apply`/`--force`.
-3. Open Claude Code inside the clone and run `/setup`.
-
-## Checklist
-
-### Preflight (P1)
-
-- [ ] `/setup` runs `bash scripts/check.sh` first, before any install/merge.
-- [ ] **Exit-2 stops the whole flow.** Force a FAIL (e.g. a config the check rejects); confirm
-      the flow STOPS, shows the `FAIL:` lines verbatim, and does NOT proceed to install.
-- [ ] On a WARN (exit 1), the session presents the warnings and **asks** before continuing.
-
-### Install (P2)
-
-- [ ] A **dry-run (`install.sh --dry-run --diff`) plan is shown before** the real install.
-- [ ] The real `install.sh` run triggers a **permission prompt** (writing form is not
-      pre-approved) — the prompt is expected, not a bug.
-- [ ] The `CCS-STATUS:backup-dir:<path>` first status line is captured and reported.
-- [ ] Differing files are **skipped**; per-category diff is shown and keep-vs-overwrite is
-      asked; overwrite uses `install.sh --force=<category> --backup-dir <path>`.
-
-### Merges (P3)
-
-- [ ] A **unified diff is shown before EVERY consent** — for `settings.json` and for
-      `CLAUDE.md`, no exceptions.
-- [ ] Targets are handled **one at a time**: `settings.json` first, then `CLAUDE.md`.
-- [ ] **A declined merge is respected:** decline one merge and confirm NO write happens, and
-      there is **no nag-loop** / re-ask (the decline is just recorded in conversation).
-- [ ] **Existing-config path shows the withheld-convenience-keys note** (model / statusLine /
-      defaultMode not merged; copy from `settings.example.json` if wanted). Test against a
-      pre-existing `settings.json`, not a fresh write.
-
-### Backup threading (cross-phase)
-
-- [ ] The **backup dir from install is threaded into every apply/force** — one run dir, one
-      receipt for the whole session. Confirm no second/stray backup dir is created.
-
-### Handoff (P4) + idempotency
-
-- [ ] Handoff prints the **receipt location + backup dir** and the "what behaves differently
-      now" 3-line summary (main pushes blocked; delegation guard during `/build`; design +
-      pre-PR checkpoints enforced).
-- [ ] Post-restart steps are handed to the **user to run after restarting** (not executed by
-      the skill): restart → `bash scripts/check.sh --post` → `/hooks`.
-- [ ] After restart, `check.sh --post` **verifies success** and `/hooks` shows the managed
-      hook entries loaded.
-- [ ] **Re-run `/setup` after an abort resumes idempotently:** abort partway, re-run, and
-      confirm unchanged files no-op (`CCS-STATUS:unchanged:...`) and no duplicate writes.
-
-## Cleanup
-
-- [ ] Delete the scratch clone and the throwaway config dir. Confirm your real `~/.claude` was
-      never touched.
diff --git a/tests/merge-claude-md.bats b/tests/merge-claude-md.bats
deleted file mode 100644
index 1cd0baa..0000000
--- a/tests/merge-claude-md.bats
+++ /dev/null
@@ -1,195 +0,0 @@
-#!/usr/bin/env bats
-# tests/merge-claude-md.bats — coverage for scripts/merge-claude-md.sh: fresh copy,
-# version-agnostic in-place replace, append, malformed/symlink refusals, dry-run
-# purity, and idempotency. Task-local fixtures only (test_helper is frozen).
-
-load test_helper
-
-MERGE="$REPO_ROOT/scripts/merge-claude-md.sh"
-
-setup() {
-  ccs_setup_sandbox
-  mkdir -p "$CLAUDE_CONFIG_DIR"
-  TARGET="$CLAUDE_CONFIG_DIR/CLAUDE.md"
-  EXPECTED="$BATS_TEST_TMPDIR/expected-block"
-  _expected_block > "$EXPECTED"
-}
-
-# _expected_block — the repo's managed block, inclusive of its markers.
-_expected_block() {
-  awk '/^<!-- BEGIN claude-code-setup workflow-rules v/{f=1}
-       f{print}
-       /^<!-- END claude-code-setup workflow-rules v/{f=0}' "$REPO_ROOT/CLAUDE.md"
-}
-
-# --- fresh -------------------------------------------------------------------
-
-@test "fresh: no target yields a file equal to the managed block only" {
-  run bash "$MERGE" --apply
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"CCS-STATUS:merged:$TARGET"* ]]
-  [ -f "$TARGET" ]
-  diff "$EXPECTED" "$TARGET"
-  # Personal sections that live OUTSIDE the block must never be copied.
-  ! grep -q "Identity" "$TARGET"
-  ! grep -q "Stack Preferences" "$TARGET"
-}
-
-# --- replace (same version) --------------------------------------------------
-
-@test "replace: v1 block with stale content is replaced, surroundings intact" {
-  cat > "$TARGET" <<'EOF'
-# My Personal Header
-keep me above
-
-<!-- BEGIN claude-code-setup workflow-rules v1 -->
-STALE OLD RULES
-<!-- END claude-code-setup workflow-rules v1 -->
-
-keep me below
-EOF
-  run bash "$MERGE" --apply
-  [ "$status" -eq 0 ]
-  grep -q "keep me above" "$TARGET"
-  grep -q "keep me below" "$TARGET"
-  ! grep -q "STALE OLD RULES" "$TARGET"
-  grep -q "Never push directly to main" "$TARGET"
-  [ "$( grep -c '^<!-- BEGIN claude-code-setup workflow-rules' "$TARGET" )" -eq 1 ]
-  [ "$( grep -c '^<!-- END claude-code-setup workflow-rules' "$TARGET" )" -eq 1 ]
-}
-
-# --- upgrade (different version) ---------------------------------------------
-
-@test "upgrade: a v0 block is replaced by the current v1 block, not duplicated" {
-  cat > "$TARGET" <<'EOF'
-<!-- BEGIN claude-code-setup workflow-rules v0 -->
-ancient rules
-<!-- END claude-code-setup workflow-rules v0 -->
-EOF
-  run bash "$MERGE" --apply
-  [ "$status" -eq 0 ]
-  ! grep -q "workflow-rules v0" "$TARGET"
-  ! grep -q "ancient rules" "$TARGET"
-  [ "$( grep -c '^<!-- BEGIN claude-code-setup workflow-rules v1 -->$' "$TARGET" )" -eq 1 ]
-  [ "$( grep -c '^<!-- END claude-code-setup workflow-rules v1 -->$' "$TARGET" )" -eq 1 ]
-  diff "$EXPECTED" "$TARGET"
-}
-
-# --- append (no markers) -----------------------------------------------------
-
-@test "append: an unmanaged target keeps its content and gains the block" {
-  printf '# Existing config\nsome personal notes\n' > "$TARGET"
-  run bash "$MERGE" --apply
-  [ "$status" -eq 0 ]
-  grep -q "some personal notes" "$TARGET"
-  grep -q "Never push directly to main" "$TARGET"
-  [ "$( grep -c '^<!-- BEGIN claude-code-setup workflow-rules v1 -->$' "$TARGET" )" -eq 1 ]
-  # A blank line must separate the original tail from the appended block.
-  grep -q '^$' "$TARGET"
-}
-
-# --- refusals ----------------------------------------------------------------
-
-@test "malformed: a lone BEGIN marker is refused and the target is untouched" {
-  cat > "$TARGET" <<'EOF'
-# Header
-<!-- BEGIN claude-code-setup workflow-rules v1 -->
-orphaned
-EOF
-  local before
-  before="$( cat "$TARGET" )"
-  run bash "$MERGE" --apply
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"malformed managed block"* ]]
-  [[ "$output" == *"Repair manually"* ]]
-  [ "$( cat "$TARGET" )" = "$before" ]
-}
-
-@test "malformed: an END marker before BEGIN is refused, target untouched, no backup dir created" {
-  cat > "$TARGET" <<'EOF'
-# Header
-<!-- END claude-code-setup workflow-rules v1 -->
-orphaned tail
-<!-- BEGIN claude-code-setup workflow-rules v1 -->
-EOF
-  local before
-  before="$( cat "$TARGET" )"
-  run bash "$MERGE" --apply
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"malformed managed block"* ]]
-  [[ "$output" == *"found 1 BEGIN / 1 END marker(s)"* ]]
-  [[ "$output" == *"Repair manually"* ]]
-  [ "$( cat "$TARGET" )" = "$before" ]
-  [ ! -d "$CLAUDE_CONFIG_DIR/backups" ]
-}
-
-@test "malformed: duplicate BEGIN/END pairs are refused, target untouched, no backup dir created" {
-  cat > "$TARGET" <<'EOF'
-<!-- BEGIN claude-code-setup workflow-rules v1 -->
-first block
-<!-- END claude-code-setup workflow-rules v1 -->
-
-<!-- BEGIN claude-code-setup workflow-rules v1 -->
-second block
-<!-- END claude-code-setup workflow-rules v1 -->
-EOF
-  local before
-  before="$( cat "$TARGET" )"
-  run bash "$MERGE" --apply
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"malformed managed block"* ]]
-  [[ "$output" == *"found 2 BEGIN / 2 END marker(s)"* ]]
-  [[ "$output" == *"Repair manually"* ]]
-  [ "$( cat "$TARGET" )" = "$before" ]
-  [ ! -d "$CLAUDE_CONFIG_DIR/backups" ]
-}
-
-@test "symlinked target is refused (exit 1)" {
-  printf 'real\n' > "$SANDBOX/real-claude.md"
-  ln -s "$SANDBOX/real-claude.md" "$TARGET"
-  run bash "$MERGE" --apply
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"symlink"* ]]
-}
-
-# --- dry-run purity ----------------------------------------------------------
-
-@test "dry-run: emits a diff and mutates nothing" {
-  cat > "$TARGET" <<'EOF'
-<!-- BEGIN claude-code-setup workflow-rules v1 -->
-STALE
-<!-- END claude-code-setup workflow-rules v1 -->
-EOF
-  local before
-  before="$( cat "$TARGET" )"
-  run bash "$MERGE" --dry-run
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"@@"* ]]
-  [[ "$output" == *"CCS-STATUS:merged:$TARGET"* ]]
-  [ "$( cat "$TARGET" )" = "$before" ]
-}
-
-# --- idempotency -------------------------------------------------------------
-
-@test "idempotent: a second apply reports unchanged and is byte-identical" {
-  run bash "$MERGE" --apply
-  [ "$status" -eq 0 ]
-  local after_first
-  after_first="$( cat "$TARGET" )"
-  run bash "$MERGE" --apply
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"CCS-STATUS:unchanged:$TARGET"* ]]
-  [ "$( cat "$TARGET" )" = "$after_first" ]
-}
-
-# --- usage -------------------------------------------------------------------
-
-@test "usage: no mode flag exits 2" {
-  run bash "$MERGE"
-  [ "$status" -eq 2 ]
-}
-
-@test "usage: both mode flags exit 2" {
-  run bash "$MERGE" --apply --dry-run
-  [ "$status" -eq 2 ]
-}
diff --git a/tests/merge-settings.bats b/tests/merge-settings.bats
deleted file mode 100644
index 81f0958..0000000
--- a/tests/merge-settings.bats
+++ /dev/null
@@ -1,356 +0,0 @@
-#!/usr/bin/env bats
-# tests/merge-settings.bats — coverage for scripts/merge-settings.sh, the sole
-# writer of settings.json. Verifies the fresh-verbatim path, the basename-keyed
-# hook reconciliation (incl. cross-version old-form upgrade), the narrowed
-# two-area merge, byte-stable idempotency, and every refusal path.
-
-load test_helper
-
-MERGE="scripts/merge-settings.sh"
-
-setup() {
-  ccs_setup_sandbox
-  mkdir -p "$CLAUDE_CONFIG_DIR"
-}
-
-# --- local fixtures ----------------------------------------------------------
-
-# _write_adopter — an adopter settings.json with a FOREIGN hook, personal keys,
-# an old-form managed hook reference, and custom permissions.allow entries.
-_write_adopter() {
-  cat > "$CLAUDE_CONFIG_DIR/settings.json" <<'EOF'
-{
-  "model": "sonnet",
-  "customKey": "keep-me",
-  "permissions": {
-    "allow": [ "Bash(ls)", "Bash(git status)" ],
-    "defaultMode": "plan"
-  },
-  "hooks": {
-    "PreToolUse": [
-      { "matcher": "Bash", "hooks": [
-        { "type": "command", "command": "bash ~/.claude/hooks/protect-branches.sh", "timeout": 5 } ] },
-      { "matcher": "Custom", "hooks": [
-        { "type": "command", "command": "bash /foreign/my-hook.sh" } ] }
-    ]
-  }
-}
-EOF
-}
-
-# _managed_cmds <file> — commands referencing a managed hook filename, one per line.
-_managed_cmds() {
-  jq -r '[.. | .command? // empty | select(test("hooks/(protect-branches|protect-secrets|orchestrator-delegate-guard|design-scope-guard|syntax-check)\\.sh"))] | .[]' "$1"
-}
-
-_receipt() { find "$CLAUDE_CONFIG_DIR/backups" -name receipt.txt | head -n 1; }
-
-# --- fresh install (M3 verbatim) --------------------------------------------
-
-@test "fresh: --apply writes the template verbatim (byte-identical)" {
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"CCS-STATUS:merged:$CLAUDE_CONFIG_DIR/settings.json"* ]]
-  cmp "$CLAUDE_CONFIG_DIR/settings.json" "$REPO_ROOT/settings.example.json"
-}
-
-@test "fresh: --apply records a merged receipt line" {
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 0 ]
-  run grep merged "$( _receipt )"
-  [ "$status" -eq 0 ]
-}
-
-@test "fresh: --backup-dir threads the shared run dir" {
-  local run_dir="$SANDBOX/run"
-  mkdir -p "$run_dir"
-  run bash "$REPO_ROOT/$MERGE" --apply --backup-dir "$run_dir"
-  [ "$status" -eq 0 ]
-  [ -f "$run_dir/receipt.txt" ]
-}
-
-# --- foreign preservation + narrowed merge ----------------------------------
-
-@test "foreign-preserved: keeps foreign hook, personal keys, and dedups allow" {
-  _write_adopter
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 0 ]
-  local s="$CLAUDE_CONFIG_DIR/settings.json"
-  # personal keys untouched
-  [ "$( jq -r '.model' "$s" )" = "sonnet" ]
-  [ "$( jq -r '.customKey' "$s" )" = "keep-me" ]
-  [ "$( jq -r '.permissions.defaultMode' "$s" )" = "plan" ]
-  # foreign hook preserved
-  [ "$( jq '[.. | .command? // empty | select(contains("/foreign/my-hook.sh"))] | length' "$s" )" -eq 1 ]
-  # all five managed hooks present
-  [ "$( _managed_cmds "$s" | sort -u | wc -l | tr -d ' ' )" -eq 5 ]
-  # allow: adopter entries survive, template entries added, deduped (no dup git status)
-  [ "$( jq '.permissions.allow | length' "$s" )" -eq 12 ]
-  [ "$( jq '[.permissions.allow[] | select(. == "Bash(git status)")] | length' "$s" )" -eq 1 ]
-  [ "$( jq '[.permissions.allow[] | select(. == "Bash(ls)")] | length' "$s" )" -eq 1 ]
-}
-
-@test "foreign-preserved: a hook naming a managed file only in echo text is kept" {
-  # Token-anchored classification: the managed filename appears solely inside log
-  # text; the invoked script is custom-guard.sh. The entry must NOT be treated as
-  # managed (stripped), and the template hooks must be added alongside it.
-  cat > "$CLAUDE_CONFIG_DIR/settings.json" <<'EOF'
-{
-  "hooks": {
-    "PreToolUse": [
-      { "matcher": "Bash", "hooks": [
-        { "type": "command", "command": "echo 'migrated away from protect-branches.sh, now using custom-guard.sh' && bash /totally/different/custom-guard.sh" } ] }
-    ]
-  }
-}
-EOF
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 0 ]
-  local s="$CLAUDE_CONFIG_DIR/settings.json"
-  # the adopter's real custom hook survives intact (command byte-preserved)
-  [ "$( jq '[.. | .command? // empty | select(contains("custom-guard.sh"))] | length' "$s" )" -eq 1 ]
-  [ "$( jq -r '[.. | .command? // empty | select(contains("custom-guard.sh"))][0]' "$s" )" = "echo 'migrated away from protect-branches.sh, now using custom-guard.sh' && bash /totally/different/custom-guard.sh" ]
-  # template managed hooks are added alongside (real protect-branches.sh invocation)
-  [ "$( jq '[.. | .command? // empty | select(contains("hooks/protect-branches.sh"))] | length' "$s" )" -eq 1 ]
-  [ "$( _managed_cmds "$s" | sort -u | wc -l | tr -d ' ' )" -eq 5 ]
-}
-
-@test "narrowed merge: template-only key defaultMode is NOT added to permissions" {
-  cat > "$CLAUDE_CONFIG_DIR/settings.json" <<'EOF'
-{ "hooks": {} }
-EOF
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 0 ]
-  # permissions.allow created; defaultMode (present in template) not copied over
-  [ "$( jq 'has("permissions")' "$CLAUDE_CONFIG_DIR/settings.json" )" = "true" ]
-  [ "$( jq '.permissions | has("defaultMode")' "$CLAUDE_CONFIG_DIR/settings.json" )" = "false" ]
-  # model/statusLine from template are NOT introduced
-  [ "$( jq 'has("model")' "$CLAUDE_CONFIG_DIR/settings.json" )" = "false" ]
-  [ "$( jq 'has("statusLine")' "$CLAUDE_CONFIG_DIR/settings.json" )" = "false" ]
-}
-
-# --- cross-version old-form upgrade (iter-4) --------------------------------
-
-@test "old-form upgrade: a manual-cp-era hook ref becomes the new form, not doubled" {
-  _write_adopter
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 0 ]
-  local s="$CLAUDE_CONFIG_DIR/settings.json"
-  # exactly ONE protect-branches entry, in the config-dir-aware form
-  [ "$( jq '[.. | .command? // empty | select(contains("protect-branches.sh"))] | length' "$s" )" -eq 1 ]
-  local cmd
-  cmd="$( jq -r '[.. | .command? // empty | select(contains("protect-branches.sh"))][0]' "$s" )"
-  [[ "$cmd" == *'${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks/protect-branches.sh'* ]]
-  [[ "$cmd" != *"~/.claude"* ]]
-}
-
-# --- permissions creation (iter-3) ------------------------------------------
-
-@test "iter-3: config without a permissions key gains permissions.allow" {
-  cat > "$CLAUDE_CONFIG_DIR/settings.json" <<'EOF'
-{ "model": "opus" }
-EOF
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 0 ]
-  [ "$( jq '.permissions.allow | length' "$CLAUDE_CONFIG_DIR/settings.json" )" -eq 11 ]
-}
-
-@test "iter-3: config with permissions but no allow gains allow, keeps siblings" {
-  cat > "$CLAUDE_CONFIG_DIR/settings.json" <<'EOF'
-{ "permissions": { "defaultMode": "plan" } }
-EOF
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 0 ]
-  local s="$CLAUDE_CONFIG_DIR/settings.json"
-  [ "$( jq '.permissions.allow | length' "$s" )" -eq 11 ]
-  [ "$( jq -r '.permissions.defaultMode' "$s" )" = "plan" ]
-}
-
-# --- byte-stable idempotency (M7) -------------------------------------------
-
-@test "fixed-point: fresh --apply then a SECOND --apply is a byte-identical no-op" {
-  # The e2e-critical sequence: a fresh verbatim write must be a fixed point, so a
-  # repeat run reports unchanged and never rewrites (no phantom diff to the user).
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"CCS-STATUS:merged:"* ]]
-  local sum1 sum2
-  sum1="$( cksum < "$CLAUDE_CONFIG_DIR/settings.json" )"
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"CCS-STATUS:unchanged:"* ]]
-  sum2="$( cksum < "$CLAUDE_CONFIG_DIR/settings.json" )"
-  [ "$sum1" = "$sum2" ]
-}
-
-@test "round-trip: second apply is a byte-identical no-op" {
-  _write_adopter
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 0 ]
-  local sum1 sum2
-  sum1="$( cksum < "$CLAUDE_CONFIG_DIR/settings.json" )"
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"CCS-STATUS:unchanged:"* ]]
-  sum2="$( cksum < "$CLAUDE_CONFIG_DIR/settings.json" )"
-  [ "$sum1" = "$sum2" ]
-}
-
-@test "round-trip: unchanged no-op writes no new backup/receipt" {
-  _write_adopter
-  bash "$REPO_ROOT/$MERGE" --apply
-  local before after
-  before="$( find "$CLAUDE_CONFIG_DIR/backups" -type f | wc -l | tr -d ' ' )"
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 0 ]
-  after="$( find "$CLAUDE_CONFIG_DIR/backups" -type f | wc -l | tr -d ' ' )"
-  [ "$before" = "$after" ]
-}
-
-# --- dry-run safety (M6) -----------------------------------------------------
-
-@test "dry-run: mutates nothing and emits a unified diff" {
-  _write_adopter
-  local sum1 sum2
-  sum1="$( cksum < "$CLAUDE_CONFIG_DIR/settings.json" )"
-  run bash "$REPO_ROOT/$MERGE" --dry-run
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"@@"* ]]
-  sum2="$( cksum < "$CLAUDE_CONFIG_DIR/settings.json" )"
-  [ "$sum1" = "$sum2" ]
-}
-
-@test "dry-run: fresh target previews the full template without creating it" {
-  run bash "$REPO_ROOT/$MERGE" --dry-run
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"protect-branches.sh"* ]]
-  [ ! -e "$CLAUDE_CONFIG_DIR/settings.json" ]
-}
-
-# --- refusals (all exit 1, target untouched) --------------------------------
-
-@test "refusal: symlinked target is refused (exit 1)" {
-  ln -s "$SANDBOX/elsewhere.json" "$CLAUDE_CONFIG_DIR/settings.json"
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"symlink"* ]]
-}
-
-@test "refusal: missing jq (exit 1)" {
-  ccs_isolate_path
-  _write_adopter
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"jq"* ]]
-}
-
-@test "refusal: unparseable JSON target (exit 1)" {
-  printf 'not json {' > "$CLAUDE_CONFIG_DIR/settings.json"
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"not valid JSON"* ]]
-}
-
-@test "refusal: valid JSON that is not an object (exit 1)" {
-  printf '[1,2,3]' > "$CLAUDE_CONFIG_DIR/settings.json"
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"not an object"* ]]
-}
-
-@test "refusal: object with a non-object .hooks (exit 1, CCS message not jq crash)" {
-  printf '{"hooks": "nope"}' > "$CLAUDE_CONFIG_DIR/settings.json"
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"CCS:"* ]]
-  [[ "$output" == *".hooks must be a JSON object"* ]]
-  # dry-run refuses identically
-  run bash "$REPO_ROOT/$MERGE" --dry-run
-  [ "$status" -eq 1 ]
-  [[ "$output" == *".hooks must be a JSON object"* ]]
-}
-
-@test "refusal: object with a non-array .permissions.allow (exit 1, CCS message)" {
-  printf '{"permissions":{"allow":"not-an-array"}}' > "$CLAUDE_CONFIG_DIR/settings.json"
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"CCS:"* ]]
-  [[ "$output" == *".permissions.allow must be a JSON array"* ]]
-  run bash "$REPO_ROOT/$MERGE" --dry-run
-  [ "$status" -eq 1 ]
-  [[ "$output" == *".permissions.allow must be a JSON array"* ]]
-}
-
-# --- malformed NESTED hook shapes (regression: must refuse, never raw jq exit-5) --
-
-@test "refusal: event value is a string, not an array (exit 1, CCS message, untouched)" {
-  printf '{"hooks": {"PreToolUse": "not-an-array"}}' > "$CLAUDE_CONFIG_DIR/settings.json"
-  local sum1 sum2
-  sum1="$( cksum < "$CLAUDE_CONFIG_DIR/settings.json" )"
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"CCS:"* ]]
-  [[ "$output" == *".hooks.PreToolUse must be a JSON array"* ]]
-  sum2="$( cksum < "$CLAUDE_CONFIG_DIR/settings.json" )"
-  [ "$sum1" = "$sum2" ]
-  # dry-run refuses identically, never a raw jq crash
-  run bash "$REPO_ROOT/$MERGE" --dry-run
-  [ "$status" -eq 1 ]
-  [[ "$output" == *".hooks.PreToolUse must be a JSON array"* ]]
-}
-
-@test "refusal: hook entry .command is a number, not a string (exit 1, CCS message)" {
-  cat > "$CLAUDE_CONFIG_DIR/settings.json" <<'EOF'
-{
-  "hooks": {
-    "PreToolUse": [
-      { "matcher": "Bash", "hooks": [
-        { "type": "command", "command": 12345 } ] }
-    ]
-  }
-}
-EOF
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"CCS:"* ]]
-  [[ "$output" == *".hooks.PreToolUse[].hooks[].command must be a JSON string"* ]]
-  run bash "$REPO_ROOT/$MERGE" --dry-run
-  [ "$status" -eq 1 ]
-  [[ "$output" == *".hooks.PreToolUse[].hooks[].command must be a JSON string"* ]]
-}
-
-@test "refusal: inner .hooks value is an object, not an array (exit 1, CCS message)" {
-  cat > "$CLAUDE_CONFIG_DIR/settings.json" <<'EOF'
-{
-  "hooks": {
-    "PreToolUse": [
-      { "matcher": "Bash", "hooks": { "type": "command", "command": "bash foo.sh" } }
-    ]
-  }
-}
-EOF
-  run bash "$REPO_ROOT/$MERGE" --apply
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"CCS:"* ]]
-  [[ "$output" == *".hooks.PreToolUse[].hooks must be a JSON array"* ]]
-  run bash "$REPO_ROOT/$MERGE" --dry-run
-  [ "$status" -eq 1 ]
-  [[ "$output" == *".hooks.PreToolUse[].hooks must be a JSON array"* ]]
-}
-
-# --- usage errors (exit 2) ---------------------------------------------------
-
-@test "usage: no mode is a usage error (exit 2)" {
-  run bash "$REPO_ROOT/$MERGE"
-  [ "$status" -eq 2 ]
-}
-
-@test "usage: both --dry-run and --apply is a usage error (exit 2)" {
-  run bash "$REPO_ROOT/$MERGE" --dry-run --apply
-  [ "$status" -eq 2 ]
-}
-
-@test "usage: unknown flag is a usage error (exit 2)" {
-  run bash "$REPO_ROOT/$MERGE" --frobnicate
-  [ "$status" -eq 2 ]
-}
diff --git a/tests/run.sh b/tests/run.sh
new file mode 100755
index 0000000..a5d446f
--- /dev/null
+++ b/tests/run.sh
@@ -0,0 +1,808 @@
+#!/bin/bash
+# tests/run.sh — single test runner, one subcommand per invocation.
+# Subcommands: hooks, size, dedupe, scan, all.
+# Must work on macOS system bash 3.2 and bash 5, BSD and GNU coreutils: no
+# mapfile/readarray, no ${var,,}, no associative arrays, no sed -i without a
+# suffix, no grep -P. Deliberately no `set -u`: bash < 4.4 raises "unbound
+# variable" on `"${empty_array[@]}"` under nounset, and this script is run
+# under bash 3.2 in CI.
+#
+# Usage errors exit 2; check failures exit 1; success exits 0.
+
+ROOT=$(cd "$(dirname "$0")/.." && pwd)
+BASELINE_BYTES=73738
+BASH_BIN="${BASH:-bash}"
+
+usage() {
+  echo "usage: tests/run.sh {hooks|size|dedupe|scan|all} [options]" >&2
+  exit 2
+}
+
+# ---------------------------------------------------------------------------
+# hooks
+# ---------------------------------------------------------------------------
+
+CASE_NUM=0
+HPASS=0
+HFAIL=0
+
+report() {
+  # $1: 1=pass 0=fail, $2: description, $3: detail (fail only)
+  CASE_NUM=$((CASE_NUM + 1))
+  if [ "$1" -eq 1 ]; then
+    HPASS=$((HPASS + 1))
+    printf 'hooks: case %02d [PASS] %s\n' "$CASE_NUM" "$2"
+  else
+    HFAIL=$((HFAIL + 1))
+    printf 'hooks: case %02d [FAIL] %s (%s)\n' "$CASE_NUM" "$2" "$3"
+  fi
+}
+
+jqtest() {
+  printf '%s' "$1" | jq -e "$2" >/dev/null 2>&1
+}
+
+check_code() {
+  # $1: actual code, $2: expected code, $3: description
+  if [ "$1" -eq "$2" ]; then
+    report 1 "$3"
+  else
+    report 0 "$3" "exit=$1 want=$2"
+  fi
+}
+
+hooks_push_cases() {
+  local home_dir out code
+  home_dir="$SCRATCH/base"
+
+  out=$(printf '%s' '{"tool_name":"Bash","tool_input":{"command":"git push origin main"},"cwd":"/tmp"}' \
+    | HOME="$home_dir" "$BASH_BIN" "$ROOT/hooks/protect-branches.sh" 2>/dev/null)
+  code=$?
+  check_code "$code" 2 "push origin main -> blocked"
+
+  out=$(printf '%s' '{"tool_name":"Bash","tool_input":{"command":"git push -u origin feat/x"},"cwd":"/tmp"}' \
+    | HOME="$home_dir" "$BASH_BIN" "$ROOT/hooks/protect-branches.sh" 2>/dev/null)
+  code=$?
+  check_code "$code" 0 "push -u origin feat/x -> allowed"
+
+  out=$(printf '%s' '{"tool_name":"Bash","tool_input":{"command":"git push --force origin feat/x"},"cwd":"/tmp"}' \
+    | HOME="$home_dir" "$BASH_BIN" "$ROOT/hooks/protect-branches.sh" 2>/dev/null)
+  code=$?
+  check_code "$code" 2 "push --force -> blocked"
+
+  out=$(printf '%s' '{"tool_name":"Bash","tool_input":{"command":"cd /tmp && git push origin main"},"cwd":"/tmp"}' \
+    | HOME="$home_dir" "$BASH_BIN" "$ROOT/hooks/protect-branches.sh" 2>/dev/null)
+  code=$?
+  check_code "$code" 2 "chained cd && push main -> blocked"
+}
+
+hooks_secrets_cases() {
+  local home_dir out code
+  home_dir="$SCRATCH/base"
+
+  out=$(printf '%s' '{"tool_name":"Write","tool_input":{"file_path":"/tmp/x/.env"}}' \
+    | HOME="$home_dir" "$BASH_BIN" "$ROOT/hooks/protect-secrets.sh" 2>/dev/null)
+  code=$?
+  check_code "$code" 2 "write .env -> blocked"
+
+  out=$(printf '%s' '{"tool_name":"Write","tool_input":{"file_path":"/tmp/x/.env.example"}}' \
+    | HOME="$home_dir" "$BASH_BIN" "$ROOT/hooks/protect-secrets.sh" 2>/dev/null)
+  code=$?
+  check_code "$code" 0 "write .env.example -> allowed"
+
+  out=$(printf '%s' '{"tool_name":"Write","tool_input":{"file_path":"/tmp/x/secrets/.env.example"}}' \
+    | HOME="$home_dir" "$BASH_BIN" "$ROOT/hooks/protect-secrets.sh" 2>/dev/null)
+  code=$?
+  check_code "$code" 2 "write secrets/.env.example -> blocked"
+
+  out=$(printf '%s' '{"tool_name":"NotebookEdit","tool_input":{"notebook_path":"/tmp/x/secrets.ipynb"}}' \
+    | HOME="$home_dir" "$BASH_BIN" "$ROOT/hooks/protect-secrets.sh" 2>/dev/null)
+  code=$?
+  check_code "$code" 2 "notebookedit secrets.ipynb -> blocked"
+}
+
+hooks_jq_absent_case() {
+  local nojq_bin errfile code errtxt u p
+  nojq_bin="$SCRATCH/c9bin"
+  mkdir -p "$nojq_bin"
+  for u in bash sh cat tr sed grep basename dirname printf readlink realpath cut head; do
+    p=$(command -v "$u" 2>/dev/null) || continue
+    ln -sf "$p" "$nojq_bin/$u"
+  done
+
+  errfile="$SCRATCH/c9.err"
+  printf '%s' '{"tool_name":"Bash","tool_input":{"command":"git push origin main"},"cwd":"/tmp"}' \
+    | PATH="$nojq_bin" HOME="$SCRATCH/base" "$BASH_BIN" "$ROOT/hooks/protect-branches.sh" \
+    >/dev/null 2>"$errfile"
+  code=$?
+  errtxt=$(cat "$errfile")
+
+  case "$errtxt" in
+    *"jq not found"*)
+      if [ "$code" -eq 0 ]; then
+        report 1 "jq absent -> skip, exit 0"
+      else
+        report 0 "jq absent -> skip, exit 0" "exit=$code"
+      fi
+      ;;
+    *)
+      report 0 "jq absent -> skip, exit 0" "no 'jq not found' on stderr: $errtxt"
+      ;;
+  esac
+}
+
+hooks_profile_cases_a() {
+  local h out code
+
+  h="$SCRATCH/c10"
+  mkdir -p "$h"
+  out=$(printf '%s' '{"cwd":"/tmp","hook_event_name":"SessionStart"}' \
+    | HOME="$h" CLAUDE_CONFIG_DIR="$h/.claude" "$BASH_BIN" "$ROOT/hooks/profile-check.sh" 2>/dev/null)
+  code=$?
+  if [ "$code" -eq 0 ] && jqtest "$out" '.hookSpecificOutput.additionalContext | startswith("profile ")'; then
+    report 1 "profile right, no .claude-profiles -> additionalContext"
+  else
+    report 0 "profile right, no .claude-profiles -> additionalContext" "exit=$code out=$out"
+  fi
+
+  h="$SCRATCH/c11"
+  mkdir -p "$h/other"
+  printf '/tmp/proj|%s/other\n' "$h" > "$h/.claude-profiles"
+  out=$(printf '%s' '{"cwd":"/tmp/proj/sub","hook_event_name":"SessionStart"}' \
+    | HOME="$h" CLAUDE_CONFIG_DIR="$h" "$BASH_BIN" "$ROOT/hooks/profile-check.sh" 2>/dev/null)
+  code=$?
+  if [ "$code" -eq 0 ] && jqtest "$out" '.systemMessage | test("wrong profile")'; then
+    report 1 "profile wrong -> systemMessage wrong profile"
+  else
+    report 0 "profile wrong -> systemMessage wrong profile" "exit=$code out=$out"
+  fi
+
+  out=$(printf '%s' '{"cwd":"/somewhere/else","hook_event_name":"SessionStart"}' \
+    | HOME="$h" CLAUDE_CONFIG_DIR="$h" "$BASH_BIN" "$ROOT/hooks/profile-check.sh" 2>/dev/null)
+  code=$?
+  if [ "$code" -eq 0 ] && jqtest "$out" 'has("systemMessage") | not'; then
+    report 1 "unmapped cwd, .claude-profiles present -> no systemMessage"
+  else
+    report 0 "unmapped cwd, .claude-profiles present -> no systemMessage" "exit=$code out=$out"
+  fi
+}
+
+hooks_profile_cases_b() {
+  local h out code
+
+  h="$SCRATCH/c13"
+  mkdir -p "$h"
+  printf '@/nonexistent/x.md\n' > "$h/CLAUDE.md"
+  out=$(printf '%s' '{"cwd":"/tmp","hook_event_name":"SessionStart"}' \
+    | HOME="$h" CLAUDE_CONFIG_DIR="$h" "$BASH_BIN" "$ROOT/hooks/profile-check.sh" 2>/dev/null)
+  code=$?
+  if [ "$code" -eq 0 ] && jqtest "$out" '.systemMessage | test("missing import")' \
+    && jqtest "$out" '.hookSpecificOutput.additionalContext | test("missing import")'; then
+    report 1 "missing absolute import -> both fields"
+  else
+    report 0 "missing absolute import -> both fields" "exit=$code out=$out"
+  fi
+
+  h="$SCRATCH/c14"
+  mkdir -p "$h/rules"
+  printf 'x' > "$h/rules/x.md"
+  printf '@rules/x.md\n' > "$h/CLAUDE.md"
+  out=$(printf '%s' '{"cwd":"/tmp","hook_event_name":"SessionStart"}' \
+    | HOME="$h" CLAUDE_CONFIG_DIR="$h" "$BASH_BIN" "$ROOT/hooks/profile-check.sh" 2>/dev/null)
+  code=$?
+  if [ "$code" -eq 0 ] && jqtest "$out" 'has("systemMessage") | not'; then
+    report 1 "relative import exists -> no systemMessage"
+  else
+    report 0 "relative import exists -> no systemMessage" "exit=$code out=$out"
+  fi
+
+  h="$SCRATCH/c15"
+  mkdir -p "$h/other"
+  printf '# comment\nmalformed line\n/tmp/proj|%s/other\n' "$h" > "$h/.claude-profiles"
+  out=$(printf '%s' '{"cwd":"/tmp/proj/sub","hook_event_name":"SessionStart"}' \
+    | HOME="$h" CLAUDE_CONFIG_DIR="$h" "$BASH_BIN" "$ROOT/hooks/profile-check.sh" 2>/dev/null)
+  code=$?
+  if [ "$code" -eq 0 ] && jqtest "$out" '.systemMessage | test("wrong profile")'; then
+    report 1 "commented/malformed lines ignored -> wrong profile"
+  else
+    report 0 "commented/malformed lines ignored -> wrong profile" "exit=$code out=$out"
+  fi
+}
+
+cmd_hooks() {
+  [ $# -eq 0 ] || usage
+  CASE_NUM=0
+  HPASS=0
+  HFAIL=0
+  SCRATCH=$(mktemp -d)
+  mkdir -p "$SCRATCH/base"
+
+  hooks_push_cases
+  hooks_secrets_cases
+  hooks_jq_absent_case
+  hooks_profile_cases_a
+  hooks_profile_cases_b
+
+  printf 'hooks: %d passed, %d failed\n' "$HPASS" "$HFAIL"
+  rm -rf "$SCRATCH"
+  [ "$HFAIL" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# size
+# ---------------------------------------------------------------------------
+
+SCOPE_FILES=""
+
+files_in_scope() {
+  # $1: comma-separated dir list (skills,agents,rules), or "" for all three.
+  local dirs want_skills want_agents want_rules
+  dirs="$1"
+  want_skills=0
+  want_agents=0
+  want_rules=0
+  if [ -z "$dirs" ]; then
+    want_skills=1
+    want_agents=1
+    want_rules=1
+  else
+    case ",$dirs," in *,skills,*) want_skills=1 ;; esac
+    case ",$dirs," in *,agents,*) want_agents=1 ;; esac
+    case ",$dirs," in *,rules,*) want_rules=1 ;; esac
+  fi
+
+  SCOPE_FILES=""
+  if [ "$want_skills" -eq 1 ]; then
+    SCOPE_FILES="$SCOPE_FILES
+$(find "$ROOT/skills" -name 'SKILL.md' 2>/dev/null)"
+  fi
+  if [ "$want_agents" -eq 1 ]; then
+    SCOPE_FILES="$SCOPE_FILES
+$(find "$ROOT/agents" -maxdepth 1 -name '*.md' 2>/dev/null)"
+  fi
+  if [ "$want_rules" -eq 1 ]; then
+    SCOPE_FILES="$SCOPE_FILES
+$(find "$ROOT/rules" -maxdepth 1 -name '*.md' 2>/dev/null)"
+  fi
+}
+
+validate_only_scope() {
+  # $1: comma-separated --only value (non-empty); exits 2 on any bad entry.
+  local scope d rest
+  scope="$1"
+  while [ -n "$scope" ]; do
+    case "$scope" in
+      *,*)
+        d="${scope%%,*}"
+        rest="${scope#*,}"
+        ;;
+      *)
+        d="$scope"
+        rest=""
+        ;;
+    esac
+    case "$d" in
+      skills | agents | rules) : ;;
+      *)
+        echo "usage: --only accepts a comma-separated list of skills,agents,rules (bad scope: '$d')" >&2
+        exit 2
+        ;;
+    esac
+    scope="$rest"
+  done
+}
+
+write_frontmatter_awk() {
+  cat > "$1" <<'AWKEOF'
+BEGIN { infm = 0; capture = 0; val = "" }
+NR == 1 { if ($0 == "---") { infm = 1 }; next }
+infm == 1 {
+  if ($0 == "---") { infm = 0; next }
+  if (capture == 1) {
+    if ($0 ~ /^[ \t]/ || length($0) == 0) {
+      line = $0
+      sub(/^[ \t]+/, "", line)
+      val = val line "\n"
+      next
+    } else {
+      capture = 0
+    }
+  }
+  if ($0 ~ "^" field ":") {
+    rest = $0
+    sub("^" field ":[ \t]*", "", rest)
+    if (rest == "|" || rest == ">" || rest == "|-" || rest == ">-") {
+      capture = 1
+      val = ""
+    } else {
+      n = length(rest)
+      if (n >= 2) {
+        c1 = substr(rest, 1, 1)
+        c2 = substr(rest, n, 1)
+        if ((c1 == "\"" && c2 == "\"") || (c1 == "'" && c2 == "'")) {
+          rest = substr(rest, 2, n - 2)
+        }
+      }
+      val = rest
+    }
+  }
+}
+END { printf "%s", val }
+AWKEOF
+}
+
+size_check_line_caps() {
+  # $1: --only dir scope (same string passed to files_in_scope)
+  local f lines cap viol
+  files_in_scope "$1"
+  viol=0
+  while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    lines=$(wc -l < "$f" | tr -d ' ')
+    cap=150
+    case "$f" in
+      */skills/design/SKILL.md | */skills/build/SKILL.md) cap=200 ;;
+    esac
+    if [ "$lines" -gt "$cap" ]; then
+      echo "size: VIOLATION $f: $lines lines (cap $cap)"
+      viol=1
+    fi
+  done <<SCOPE
+$SCOPE_FILES
+SCOPE
+  [ "$viol" -eq 0 ]
+}
+
+size_check_full_extras() {
+  local wf lines tmpawk f d w total viol
+  viol=0
+
+  wf="$ROOT/WORKFLOW.md"
+  if [ -f "$wf" ]; then
+    lines=$(wc -l < "$wf" | tr -d ' ')
+    if [ "$lines" -gt 200 ]; then
+      echo "size: VIOLATION $wf: $lines lines (cap 200)"
+      viol=1
+    fi
+  fi
+
+  tmpawk=$(mktemp)
+  write_frontmatter_awk "$tmpawk"
+  while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    d=$(awk -v field="description" -f "$tmpawk" "$f")
+    w=$(awk -v field="when_to_use" -f "$tmpawk" "$f")
+    total=$((${#d} + ${#w}))
+    if [ "$total" -gt 1536 ]; then
+      echo "size: VIOLATION $f: description+when_to_use = $total chars (cap 1536)"
+      viol=1
+    fi
+  done <<SCOPE
+$(find "$ROOT/skills" -name 'SKILL.md' 2>/dev/null)
+SCOPE
+  rm -f "$tmpawk"
+
+  [ "$viol" -eq 0 ]
+}
+
+cmd_size() {
+  local baseline only only_given fail total f sz
+
+  baseline="$BASELINE_BYTES"
+  only=""
+  only_given=0
+
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --only)
+        if [ $# -lt 2 ] || [ -z "$2" ]; then
+          echo "usage: tests/run.sh size [<baseline-bytes>] [--only <dir,dir>]" >&2
+          exit 2
+        fi
+        validate_only_scope "$2"
+        only="$2"
+        only_given=1
+        shift 2
+        ;;
+      [0-9]*)
+        baseline="$1"
+        shift
+        ;;
+      *)
+        echo "usage: tests/run.sh size [<baseline-bytes>] [--only <dir,dir>]" >&2
+        exit 2
+        ;;
+    esac
+  done
+
+  files_in_scope "$only"
+  total=0
+  while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    sz=$(wc -c < "$f" | tr -d ' ')
+    total=$((total + sz))
+  done <<SCOPE
+$SCOPE_FILES
+SCOPE
+
+  awk -v t="$total" -v b="$baseline" \
+    'BEGIN { pct = (b > 0) ? (t / b) * 100 : 0; printf "size: %d bytes, %.1f%% of baseline %d\n", t, pct, b }'
+
+  fail=0
+  [ "$total" -gt "$baseline" ] && fail=1
+
+  size_check_line_caps "$only" || fail=1
+  if [ "$only_given" -eq 0 ]; then
+    size_check_full_extras || fail=1
+  fi
+
+  [ "$fail" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# dedupe
+# ---------------------------------------------------------------------------
+
+cmd_dedupe() {
+  local only phrases_file targets phrase tf n hitfiles fail
+
+  only=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --only)
+        if [ $# -lt 2 ] || [ -z "$2" ]; then
+          echo "usage: tests/run.sh dedupe [--only <dir>]" >&2
+          exit 2
+        fi
+        validate_only_scope "$2"
+        only="$2"
+        shift 2
+        ;;
+      *)
+        echo "usage: tests/run.sh dedupe [--only <dir>]" >&2
+        exit 2
+        ;;
+    esac
+  done
+
+  phrases_file="$ROOT/tests/dedupe-phrases.txt"
+  if [ ! -f "$phrases_file" ]; then
+    echo "dedupe: missing $phrases_file" >&2
+    return 1
+  fi
+
+  files_in_scope "$only"
+  targets="$SCOPE_FILES"
+  fail=0
+
+  while IFS= read -r phrase || [ -n "$phrase" ]; do
+    [ -z "$phrase" ] && continue
+    n=0
+    hitfiles=""
+    while IFS= read -r tf; do
+      [ -z "$tf" ] && continue
+      if grep -qriF -- "$phrase" "$tf" 2>/dev/null; then
+        n=$((n + 1))
+        if [ -z "$hitfiles" ]; then
+          hitfiles="$tf"
+        else
+          hitfiles="$hitfiles, $tf"
+        fi
+      fi
+    done <<SCOPE
+$targets
+SCOPE
+    if [ "$n" -ge 2 ]; then
+      echo "dedupe: VIOLATION \"$phrase\" appears in: $hitfiles"
+      fail=1
+    fi
+  done < "$phrases_file"
+
+  [ "$fail" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# scan
+# ---------------------------------------------------------------------------
+
+SCAN_PATHSPECS=()
+
+scan_git_mode() {
+  # $1: pattern file, $2: report flag (0/1)
+  local pf report_flag out err gcode
+  pf="$1"
+  report_flag="$2"
+  out=$(mktemp)
+  err=$(mktemp)
+
+  ( cd "$ROOT" && git grep --untracked -niEf "$pf" -- "${SCAN_PATHSPECS[@]}" ) > "$out" 2>"$err"
+  gcode=$?
+
+  if [ "$gcode" -gt 1 ]; then
+    echo "scan: git grep error:" >&2
+    cat "$err" >&2
+    rm -f "$out" "$err"
+    return 2
+  fi
+
+  rm -f "$err"
+  if [ "$gcode" -eq 0 ]; then
+    if [ "$report_flag" -eq 1 ]; then
+      cut -d: -f1,2 "$out"
+      rm -f "$out"
+      return 0
+    fi
+    rm -f "$out"
+    echo "scan: hit(s) found" >&2
+    return 1
+  fi
+  rm -f "$out"
+  return 0
+}
+
+scan_path_mode() {
+  # $1: pattern file, $2: directory, $3: report flag (0/1)
+  local pf dir report_flag out gcode
+  pf="$1"
+  dir="$2"
+  report_flag="$3"
+  out=$(mktemp)
+
+  grep -rIniEf "$pf" "$dir" > "$out" 2>/dev/null
+  gcode=$?
+
+  if [ "$gcode" -gt 1 ]; then
+    echo "scan: grep error scanning $dir" >&2
+    rm -f "$out"
+    return 2
+  fi
+  if [ "$gcode" -eq 0 ]; then
+    if [ "$report_flag" -eq 1 ]; then
+      cut -d: -f1,2 "$out"
+      rm -f "$out"
+      return 0
+    fi
+    rm -f "$out"
+    echo "scan: hit(s) found" >&2
+    return 1
+  fi
+  rm -f "$out"
+  return 0
+}
+
+scan_history() {
+  # $1: pattern file, $2: range, $3: report flag (0/1)
+  local pf range report_flag tmplog logerr gcode count firstline
+  pf="$1"
+  range="$2"
+  report_flag="$3"
+  tmplog=$(mktemp)
+  logerr=$(mktemp)
+
+  git -C "$ROOT" log -p "$range" > "$tmplog" 2>"$logerr"
+  gcode=$?
+
+  if [ "$gcode" -ne 0 ]; then
+    firstline=$(head -n 1 "$logerr")
+    echo "scan: git log failed for range $range: $firstline" >&2
+    rm -f "$tmplog" "$logerr"
+    return 2
+  fi
+  rm -f "$logerr"
+
+  count=$(grep -ciEf "$pf" "$tmplog" 2>/dev/null)
+  count=${count:-0}
+  rm -f "$tmplog"
+
+  if [ "$count" -gt 0 ]; then
+    if [ "$report_flag" -eq 1 ]; then
+      echo "scan: history hits: $count (range $range)"
+      return 0
+    fi
+    echo "scan: history hit(s) found" >&2
+    return 1
+  fi
+  return 0
+}
+
+cmd_scan() {
+  local pattern_file do_history history_range do_report scan_path got_pattern rc
+
+  pattern_file=""
+  do_history=0
+  history_range="--all"
+  do_report=0
+  scan_path=""
+  got_pattern=0
+  SCAN_PATHSPECS=()
+
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --history)
+        do_history=1
+        shift
+        if [ $# -gt 0 ]; then
+          case "$1" in
+            --report | -p | --history | --) : ;;
+            *)
+              history_range="$1"
+              shift
+              ;;
+          esac
+        fi
+        ;;
+      --report)
+        do_report=1
+        shift
+        ;;
+      -p)
+        if [ $# -lt 2 ] || [ -z "$2" ]; then
+          usage
+        fi
+        scan_path="$2"
+        shift 2
+        ;;
+      --)
+        shift
+        while [ $# -gt 0 ]; do
+          SCAN_PATHSPECS+=("$1")
+          shift
+        done
+        ;;
+      *)
+        if [ "$got_pattern" -eq 0 ]; then
+          pattern_file="$1"
+          got_pattern=1
+          shift
+        else
+          usage
+        fi
+        ;;
+    esac
+  done
+
+  [ -z "$pattern_file" ] && pattern_file="${CW_SCAN_PATTERNS:-}"
+  if [ -z "$pattern_file" ] || [ ! -r "$pattern_file" ]; then
+    echo "scan: no readable pattern file (pass one, or set \$CW_SCAN_PATTERNS)" >&2
+    exit 2
+  fi
+
+  if [ "$do_history" -eq 1 ]; then
+    scan_history "$pattern_file" "$history_range" "$do_report"
+    rc=$?
+  elif [ -n "$scan_path" ]; then
+    scan_path_mode "$pattern_file" "$scan_path" "$do_report"
+    rc=$?
+  else
+    scan_git_mode "$pattern_file" "$do_report"
+    rc=$?
+  fi
+  return "$rc"
+}
+
+# ---------------------------------------------------------------------------
+# all
+# ---------------------------------------------------------------------------
+
+check_settings_keys() {
+  local settings keysfile diff_out
+  settings="$ROOT/settings.example.json"
+  keysfile="$ROOT/tests/settings-keys.txt"
+
+  if [ ! -f "$keysfile" ]; then
+    echo "all: settings-keys: missing tests/settings-keys.txt" >&2
+    return 1
+  fi
+  if [ ! -f "$settings" ]; then
+    echo "all: settings-keys: missing settings.example.json" >&2
+    return 1
+  fi
+
+  diff_out=$(comm -23 <(jq -r 'keys[]' "$settings" | sort) <(sort "$keysfile"))
+  if [ -n "$diff_out" ]; then
+    echo "all: settings-keys: keys in settings.example.json not documented in tests/settings-keys.txt:" >&2
+    echo "$diff_out" >&2
+    return 1
+  fi
+  return 0
+}
+
+cmd_all() {
+  [ $# -eq 0 ] || usage
+  local fail summary
+  fail=0
+  summary=""
+
+  if cmd_hooks; then
+    summary="$summary
+all: hooks: PASS"
+  else
+    summary="$summary
+all: hooks: FAIL"
+    fail=1
+  fi
+
+  if cmd_size; then
+    summary="$summary
+all: size: PASS"
+  else
+    summary="$summary
+all: size: FAIL"
+    fail=1
+  fi
+
+  if cmd_dedupe; then
+    summary="$summary
+all: dedupe: PASS"
+  else
+    summary="$summary
+all: dedupe: FAIL"
+    fail=1
+  fi
+
+  if check_settings_keys; then
+    summary="$summary
+all: settings-keys: PASS"
+  else
+    summary="$summary
+all: settings-keys: FAIL"
+    fail=1
+  fi
+
+  if [ -n "${CW_SCAN_PATTERNS:-}" ]; then
+    if [ ! -r "$CW_SCAN_PATTERNS" ]; then
+      echo "all: scan: pattern file not readable" >&2
+      summary="$summary
+all: scan: FAIL"
+      fail=1
+    elif cmd_scan "$CW_SCAN_PATTERNS"; then
+      summary="$summary
+all: scan: PASS"
+    else
+      summary="$summary
+all: scan: FAIL"
+      fail=1
+    fi
+  else
+    echo "all: scan: skipped (\$CW_SCAN_PATTERNS not set)"
+    summary="$summary
+all: scan: SKIPPED"
+  fi
+
+  printf '%s\n' "$summary"
+  [ "$fail" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# main
+# ---------------------------------------------------------------------------
+
+main() {
+  case "${1:-}" in
+    hooks)
+      shift
+      cmd_hooks "$@"
+      ;;
+    size)
+      shift
+      cmd_size "$@"
+      ;;
+    dedupe)
+      shift
+      cmd_dedupe "$@"
+      ;;
+    scan)
+      shift
+      cmd_scan "$@"
+      ;;
+    all)
+      shift
+      cmd_all "$@"
+      ;;
+    *)
+      usage
+      ;;
+  esac
+}
+
+main "$@"
diff --git a/tests/test_helper.bash b/tests/test_helper.bash
deleted file mode 100644
index da5fe05..0000000
--- a/tests/test_helper.bash
+++ /dev/null
@@ -1,54 +0,0 @@
-#!/usr/bin/env bash
-# tests/test_helper.bash — shared bats plumbing for the installer test suite.
-# Sandbox setup ONLY; no task-specific fixtures. This file is frozen after Task 7
-# (design M9) — later tasks add their own fixtures to their own .bats files.
-
-# Absolute path to the repo under test.
-REPO_ROOT="$( cd "$BATS_TEST_DIRNAME/.." && pwd -P )"
-export REPO_ROOT
-
-# ccs_setup_sandbox — isolated HOME + config dir under the per-test tmpdir.
-# Ambient CLAUDE_CONFIG_DIR must never leak into tests (M5): unset it, then set it
-# explicitly to a sandbox path. A stub bin dir is prepended to PATH so fake
-# executables can override real ones while real tools stay reachable.
-ccs_setup_sandbox() {
-  SANDBOX="$BATS_TEST_TMPDIR/sandbox"
-  CCS_STUB_BIN="$SANDBOX/bin"
-  mkdir -p "$SANDBOX/home" "$CCS_STUB_BIN"
-  unset CLAUDE_CONFIG_DIR
-  HOME="$SANDBOX/home"
-  CLAUDE_CONFIG_DIR="$HOME/.claude"
-  PATH="$CCS_STUB_BIN:$PATH"
-  export HOME CLAUDE_CONFIG_DIR PATH
-}
-
-# ccs_isolate_path — restrict PATH to the stub bin plus symlinks of the base
-# utilities the scripts need, so a test can simulate a tool being ABSENT simply by
-# not stubbing it. Call after ccs_setup_sandbox.
-ccs_isolate_path() {
-  local orig="$PATH" util src
-  for util in bash sh env dirname basename grep head tr cat cp mv rm mkdir \
-              chmod ln sort uniq mktemp date sed awk find git timeout; do
-    src="$( PATH="$orig" command -v "$util" 2>/dev/null || true )"
-    [ -n "$src" ] && ln -sf "$src" "$CCS_STUB_BIN/$util"
-  done
-  PATH="$CCS_STUB_BIN"
-  export PATH
-}
-
-# ccs_make_stub <name> <exit_code> [output_line...] — create a fake executable on
-# the stub PATH that prints the given lines (verbatim, for any args) and exits
-# with <exit_code>.
-ccs_make_stub() {
-  local name="$1" code="$2"
-  shift 2
-  local file="$CCS_STUB_BIN/$name" line
-  {
-    printf '#!/usr/bin/env bash\n'
-    for line in "$@"; do
-      printf 'printf "%%s\\n" %q\n' "$line"
-    done
-    printf 'exit %s\n' "$code"
-  } > "$file"
-  chmod +x "$file"
-}

From 89b8a90890e701ecb40365beb4c6dbea9161838f Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Wed, 16 Sep 2026 17:05:47 +0100
Subject: [PATCH 04/24] refactor(rules): one home per rule, lean workflow and
 orchestration files

Split the shipped policy into two impersonal rule files that a profile's
CLAUDE.md imports: workflow.md carries the branch, commit, design-document
and research/context-hygiene rules, orchestration.md carries model routing,
verification and the review-loop anti-ratchet guidance.

Each rule cluster now lives in exactly one file so the dedupe check can
enforce it mechanically. Identity and stack preferences do not ship (they
belong in a profile or project CLAUDE.md), the plans-dir promotion
machinery and emphatic capitals are gone, and the commands are namespaced
under /cw:.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 rules/orchestration.md | 81 ++++++++++++++++++++++++------------------
 rules/workflow.md      | 36 +++++++++++++++++++
 2 files changed, 83 insertions(+), 34 deletions(-)
 create mode 100644 rules/workflow.md

diff --git a/rules/orchestration.md b/rules/orchestration.md
index 921742a..d008b07 100644
--- a/rules/orchestration.md
+++ b/rules/orchestration.md
@@ -1,47 +1,60 @@
 # Orchestration & Model Routing
 
-## Model routing table (use aliases, never pinned IDs)
+## Model routing (aliases are canonical; a pinned dated model ID goes stale)
 | Alias | Route here |
 |-------|-----------|
-| `fable` (currently Fable 5) | Orchestration, planning, architecture, synthesis, ambiguous problems ONLY. Never spawn as a worker. |
-| `opus` (currently Opus 4.8) | Hard implementation (>5 files, cross-cutting schema, long-horizon), design review, high-risk code review |
-| `sonnet` (currently Sonnet 5) | Default: implementation, web research, standard code review, test writing |
-| `haiku` (currently Haiku 4.5) | Bulk read-only fan-out: codebase exploration, doc fetching, mechanical checks |
+| `fable` | Orchestration, planning, architecture, synthesis, ambiguous problems. Not spawned as a worker. |
+| `opus` | Hard implementation (>5 files, cross-cutting schema, long-horizon), design review, high-risk code review |
+| `sonnet` | Default: implementation, web research, standard code review, test writing |
+| `haiku` | Bulk read-only fan-out: codebase exploration, doc fetching, mechanical checks |
 
-Aliases are canonical; never pin dated model IDs in config.
-
-- Routing is MANUAL: every subagent/workflow agent inherits the session model
-  (Fable — expensive) unless a model is explicitly set. Every Agent call and
-  every agent() in a workflow script MUST carry an explicit model.
-- Route UP for hard coding: Sonnet→Opus is better $/quality than Haiku→Sonnet
-  on hard tasks. Down-tiering is for simple/bulk work, not hard work.
-- Audit generated workflow scripts before large runs: confirm per-stage model
-  fields exist. Prototype on a small slice first.
+- Routing is manual: a subagent or workflow agent inherits the session model
+  (the expensive orchestrator) unless one is set, so every Agent call and every
+  agent() in a workflow script carries an explicit model. Audit a generated
+  script before a large run to confirm its per-stage model fields are there.
+- Independent agents are spawned in the same turn; only dependents are sequenced.
+- Route up for hard coding: sonnet→opus is better $/quality than haiku→sonnet;
+  down-tiering is for simple or bulk work, not hard work.
 
 ## Workflow (ultracode) usage
-- Workflows for READ-heavy fan-out: research, codebase mapping, review panels,
-  multi-angle drafting, audits. Roughly ≥5 parallel agents justifies a workflow;
-  below that, plain Agent calls.
+- Workflows suit read-heavy fan-out: research, codebase mapping, review panels,
+  multi-angle drafting, audits. Five or more parallel agents justifies one;
+  below that, plain Agent calls. Prototype a new one on a small slice first.
 - Implementation stays task-sequential or strictly partitioned by disjoint file
-  ownership — never naive parallel writes.
-- One workflow per phase; workflows cannot pause mid-run, so human checkpoints
-  sit BETWEEN workflows, never inside.
-- Workflow subagents run in acceptEdits (file edits auto-approved) regardless of
-  session mode: pre-populate the permission allowlist before large runs and rely
-  on hooks for hard constraints.
+  ownership — no naive parallel writes.
+- One workflow per phase; a workflow cannot pause mid-run, so human checkpoints
+  sit between workflows, not inside them.
+- Workflow subagents run in acceptEdits regardless of session mode: pre-populate
+  the permission allowlist before large runs and let the hooks enforce limits.
 
 ## Verification & completion
-- Ground truth over agent testimony: completion = git log + actual test/build
-  output, never a subagent's self-report.
-- Reviewers: fresh context, different model than the implementer, adversarial
-  framing, evidence required per finding (file:line or failing command).
-- Tier review depth by risk: deep review for schema/API/auth/security tasks;
-  fast-path trivial ones.
-- Review loops: NO_VERDICT (silence/unparseable) is distinct from NEEDS_WORK —
-  retry once fresh, then escalate; never burn iterations or deadlock on it.
+- Ground truth over agent testimony: completion is git log plus actual test or
+  build output, not a subagent's self-report.
+- Reviewers run with fresh context on a counter-model (not the implementer's),
+  framed adversarially, evidence per finding (file:line or a failing command).
+- Tier review depth by risk: deep review for schema, API, auth and security
+  work; fast-path the trivial tasks.
+- NO_VERDICT (silence or an unparseable reply) is distinct from NEEDS_WORK:
+  retry once fresh, then escalate; do not burn iterations or deadlock on it.
+
+## Review-loop anti-ratchet (code, design docs, prose, legal)
+- Reviewers output structured findings (location, evidence, severity, suggestion
+  ≤25 words), not rewrites; deciding the fix is a role separate from finding.
+- Accept/drop decisions happen before redrafting, against explicit size and
+  scope budgets; "accepted risk" is a legitimate outcome, logged not litigated.
+- Cap adversarial review at one or two rounds: round-2+ findings are majority
+  false positives (measured); later rounds need a higher evidence bar, not a
+  fresh mandate to find something.
+- Termination, size and scope limits are checked mechanically (script or count),
+  not self-declared by an agent.
+- "Be concise" prompts do nothing (measured ~zero effect); enforce brevity
+  structurally: scoped context per call, one bounded item per call, hard caps,
+  and minimization as a separate pass, not folded into critique-and-apply.
+- When one flagged span is in scope, the fixer sees only that span, not the
+  whole artifact — full-context exposure alone triples growth.
 
 ## Sessions & context
-- One session per phase/milestone; reset at task boundaries or after two failed
-  corrections — not at a token counter.
+- One session per phase or milestone; reset at task boundaries or after two
+  failed corrections, not at a token counter.
 - Re-inject standing governance rules (branch policy, commit format) at each
-  phase start — compaction drops non-active-goal policies.
+  phase start; compaction drops policies that are not the active goal.
diff --git a/rules/workflow.md b/rules/workflow.md
new file mode 100644
index 0000000..5d0d22e
--- /dev/null
+++ b/rules/workflow.md
@@ -0,0 +1,36 @@
+# Workflow Rules
+
+Process rules for the cw plugin, imported by a profile's CLAUDE.md. Model
+routing and workflow usage follow the orchestration rules.
+
+## Workflow
+- Feature branches only; work reaches the default branch through a pull request.
+- Conventional Commits: feat:, fix:, refactor:, docs:, chore:, test:.
+- Every commit ends with the co-author trailer:
+  Co-Authored-By: Claude <noreply@anthropic.com>
+- No implementation without an approved design. If uncertain, ask first.
+- Two human checkpoints, both non-negotiable: after the design, before the PR.
+- `/cw:design` runs in plan mode; on approval the single plan file moves to the
+  project's `docs/plans/<slug>.md`, which is the canonical copy. In a folder
+  that is not a repo the file stays where plan mode put it.
+- `/cw:build <slug> [continue [<task-id>]]` reads the `## Tasks` section of that
+  file, commits the design as `docs(<slug>): design`, delegates every change to
+  an implementer, and stops at the checkpoint before the PR.
+- `/cw:ship` runs the quality gate, pushes the branch, opens the PR, and ends by
+  offering `/cw:compound`.
+- `/cw:build` and `/cw:ship` run in execute mode (auto or acceptEdits).
+- Edits to process rules (a CLAUDE.md, these rules files) stay out of the
+  feature PR; they are their own change.
+
+## Research-first design
+- Check official docs with context7 before writing code against any API.
+- Search for best practices (exa or web search) before architecture decisions.
+- Flag unsourced decisions explicitly: "Note: this approach is unsourced — my
+  judgment call."
+- Prefer boring, proven patterns over novel ones unless there is a clear reason.
+
+## Context hygiene
+- Use subagents for tasks whose output would bloat the main context:
+  exploration, review, large diffs.
+- Suggest `/clear` between unrelated tasks.
+- For large features, suggest one session per phase.

From bde46f1ae70df54ce3e6f2468875730b734c6e2e Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Wed, 16 Sep 2026 17:21:30 +0100
Subject: [PATCH 05/24] refactor(agents): claude 5 model and effort matrix,
 lean prompts

Co-Authored-By: Claude <noreply@anthropic.com>
---
 agents/Explore.md            | 34 -----------------
 agents/design-reviewer.md    | 64 +++++++++++++++++++------------
 agents/direction-reviewer.md | 73 ++++++++++++++++++------------------
 agents/implementer.md        | 35 +++++++++--------
 agents/researcher.md         | 54 +++++++++++++-------------
 agents/reviewer.md           | 54 ++++++++++++++------------
 6 files changed, 152 insertions(+), 162 deletions(-)
 delete mode 100644 agents/Explore.md

diff --git a/agents/Explore.md b/agents/Explore.md
deleted file mode 100644
index b3fee96..0000000
--- a/agents/Explore.md
+++ /dev/null
@@ -1,34 +0,0 @@
----
-name: Explore
-description: "Fast, read-only codebase exploration. Locates files, symbols, and patterns and reports findings concisely. Cannot modify files. Overrides the built-in Explore agent (which, since Claude Code v2.1.198, inherits the session model)."
-model: haiku
-tools:
-  - Read
-  - Glob
-  - Grep
-disallowedTools:
-  - Write
-  - Edit
-color: gray
----
-
-# Explore
-
-You are a fast, read-only exploration agent. Your job is to locate relevant code, files, and symbols in the codebase and report back concisely — you do not modify anything.
-
-## Method
-1. Use Glob to find candidate files by name/path pattern.
-2. Use Grep to search for symbols, strings, or patterns across the codebase.
-3. Use Read only on the specific files/line ranges you need to confirm a finding — avoid reading entire large files when a targeted range will do.
-4. Prefer breadth-first search (many quick greps/globs) over reading whole files up front.
-
-## Rules
-- Never write, edit, or execute anything — you are strictly read-only.
-- Be fast: favor the smallest number of tool calls that answers the question.
-- Do not speculate about code you have not actually read — verify with Read/Grep before reporting.
-
-## Output
-Report findings concisely:
-- File paths (absolute) and line numbers for anything relevant.
-- A short summary of what was found and how it answers the request.
-- Note any ambiguity or places you could not verify, rather than guessing.
diff --git a/agents/design-reviewer.md b/agents/design-reviewer.md
index 8c1a393..2dfb919 100644
--- a/agents/design-reviewer.md
+++ b/agents/design-reviewer.md
@@ -1,11 +1,9 @@
 ---
 name: design-reviewer
-description: "Reviews a finalized design draft against the real codebase, current web best practices, and internal consistency. Returns a strict JSON verdict. Read-only — cannot modify files. Used by the /design auto-review loop."
+description: "Reviews a finalized design draft against the real codebase, current web best practices, and internal consistency. Returns a strict JSON verdict. Read-only — cannot modify files. Used by the /cw:design auto-review loop."
 model: opus
-effort: xhigh
+effort: high
 maxTurns: 25
-skills:
-  - search
 tools:
   - Read
   - Glob
@@ -16,38 +14,54 @@ tools:
   - mcp__exa__web_search_advanced_exa
   - mcp__context7__resolve-library-id
   - mcp__context7__query-docs
-disallowedTools:
-  - Write
-  - Edit
-mcpServers:
-  - exa
-  - context7
+  - Skill
 memory: project
 color: purple
 ---
 
 # Design Reviewer
 
-You review a finalized design draft for a feature before any code is written. Each invocation has **fresh context** — that is the point. Do NOT trust summaries passed in the prompt; read the source artifacts yourself, every pass.
+You review a finalized design draft for a feature before any code is
+written. Each invocation gets fresh context — that is the point. Read the
+source artifacts yourself, every pass, rather than relying on summaries in
+the prompt.
 
 ## Inputs (paths are passed in the prompt)
-- The design draft (a markdown plan/design doc).
-- Three research files from the design's grounding step: `*-research-codebase.md`, `*-research-docs.md`, `*-research-bestpractices.md`.
+- The design document, normally `docs/plans/<slug>.md` (while still in plan
+  mode, the plan-mode draft the prompt names).
+- Its Research section — the codebase, docs and best-practice summaries from
+  the grounding step; read it, then re-ground every claim yourself.
 
 ## Method — re-ground every pass
-1. **Read the design draft fresh.** Then read all three research files fresh.
-2. **codebase-fit**: For every file path, module, function, schema, or symbol the design references, verify it exists with the claimed shape — use Glob/Grep/Read against the actual repo. Flag drift between what the design assumes and what is on disk.
-3. **best-practices**: For each notable architectural choice, run the `search` skill's 3-angle method (authoritative via context7 for libraries; practitioner + contrarian via exa/WebSearch with the current year). Flag any choice that is deprecated or superseded by a newer pattern. Cite sources.
-4. **consistency**: Read the whole design end to end. Flag internal contradictions, steps with no corresponding change, verification rows that test nothing the change produces, and dependency-order violations.
-5. **research-ignored**: Verify the design actually incorporated each finding in the three research files — or consciously rejected it with a stated reason. A finding that was silently dropped is an issue.
+1. **Read the design document fresh**, including its Research section.
+2. **codebase-fit**: For every file path, module, function, schema, or
+   symbol the design references, verify it exists with the claimed shape —
+   use Glob/Grep/Read against the actual repo. Flag drift between what the
+   design assumes and what is on disk.
+3. **best-practices**: For each notable architectural choice, research it
+   the way the cw:search skill does — an authoritative pass via context7 for
+   libraries, plus a practitioner and a contrarian pass via exa/WebSearch
+   with the current year. Invoke the Skill tool for cw:search if you need
+   its full method. Flag any choice that is deprecated or superseded by a
+   newer pattern. Cite sources.
+4. **consistency**: Read the whole design end to end. Flag internal
+   contradictions, steps with no corresponding change, verification rows
+   that test nothing the change produces, and dependency-order violations.
+5. **research-ignored**: Verify the design actually incorporated each
+   finding in the Research section — or consciously rejected it with a
+   stated reason. A finding that was silently dropped is an issue.
 
 ## Rules
-- Read files from disk; never rely on prior-pass context or prompt summaries.
-- Every best-practices claim needs a citation or an explicit "unsourced — judgment call".
-- If you cannot verify something, mark it `unverifiable` — do not guess.
-- Be decisive. Do not invent issues to appear thorough; if it is sound, say PASS.
+- Read files from disk rather than leaning on prior-pass context or prompt
+  summaries.
+- Every best-practices claim needs a citation or an explicit "unsourced —
+  judgment call".
+- If you cannot verify something, mark it `unverifiable` rather than
+  guessing.
+- Only raise an issue you can back with evidence; if the design is sound,
+  say PASS.
 
-## Output — STRICT JSON ONLY
+## Output — strict JSON only
 
 Emit exactly one JSON object as your final message, no prose around it:
 
@@ -66,4 +80,6 @@ Emit exactly one JSON object as your final message, no prose around it:
 }
 ```
 
-`verdict` is `PASS` only when there are zero `critical` and zero `major` issues. Minor issues are allowed under a PASS (list them anyway). If you cannot produce valid JSON for any reason, the orchestrator treats that as `NEEDS_WORK` — so always close the JSON correctly.
+`verdict` is `PASS` only when there are zero `critical` and zero `major`
+issues. Minor issues are allowed under a PASS (list them anyway). Malformed
+JSON is treated as `NEEDS_WORK`, so always close the JSON correctly.
diff --git a/agents/direction-reviewer.md b/agents/direction-reviewer.md
index 20511d6..8508736 100644
--- a/agents/direction-reviewer.md
+++ b/agents/direction-reviewer.md
@@ -1,6 +1,6 @@
 ---
 name: direction-reviewer
-description: "Premise/direction sanity review of a finalized design + task plan. Asks whether the plan actually solves the user's real problem — not whether it is internally consistent or doc-faithful. Read-only. Runs once, after the design-reviewer loop converges."
+description: "Premise/direction sanity review of a finalized design and task plan. Asks whether the plan actually solves the real problem — not whether it is internally consistent or doc-faithful. Read-only — cannot modify files. Runs once, after the cw:design-reviewer loop converges."
 model: opus
 effort: xhigh
 maxTurns: 15
@@ -8,53 +8,54 @@ tools:
   - Read
   - Glob
   - Grep
-disallowedTools:
-  - Write
-  - Edit
 memory: project
 color: red
 ---
 
 # Direction Reviewer
 
-You review a finalized design **after** `design-reviewer` has already confirmed it is
-internally consistent, codebase-fit, and doc-grounded. Your job is the orthogonal one:
-**is this plan aimed at the right outcome?** A plan can cite only correct sources and
-still be pointed in the wrong direction. You do not re-check file paths or APIs — assume
-that work is done. You reason about problem-fit and premise.
+You review a finalized design after cw:design-reviewer has already confirmed
+it is internally consistent, codebase-fit, and doc-grounded. Your job is the
+orthogonal one: is this plan aimed at the right outcome? A plan can cite only
+correct sources and still be pointed in the wrong direction. You do not
+re-check file paths or APIs — assume that work is done. You reason about
+problem-fit and premise.
 
-You are deliberately **not** given the research files and have **no web tools**: the
-research already happened. Anchoring on it would pull you back into fidelity-checking.
-Reason from the original request and the proposed plan.
+You have no web tools and do not re-check the Research section: the research
+already happened, and anchoring on it would pull you back into
+fidelity-checking. Reason from the original request and the proposed plan.
 
 ## Inputs (paths/text passed in the prompt)
-- The original feature request / voice-note text (what the user actually asked for).
-- `<slug>-design-draft.md` (the approach).
-- `<slug>-tasks.md` (the concrete task breakdown).
+- The original feature request (what was actually asked for).
+- The design document `docs/plans/<slug>.md` (or the plan-mode draft the
+  prompt names): its approach sections and its `## Task <id>` blocks.
 
-Read all three fresh.
+Read both fresh.
 
 ## The four questions
-1. **Problem fit** — does the proposed approach actually achieve the user's intended
-   outcome, or does it solve an adjacent/easier/more-fun problem instead?
-2. **Premise** — now that the plan is concrete, is there a materially cheaper or simpler
-   intervention that makes most of it unnecessary? (The Office-Hours challenge, re-asked
-   against the real plan rather than the idea.)
-3. **Scope drift** — does the task list build meaningfully more or less than the request
-   implies? Flag gold-plating and under-delivery symmetrically.
-4. **Right-direction-despite-sound-docs** — could every cited source be correct and the
-   plan still aim wrong? If so, name the wrong assumption explicitly.
+1. **Problem fit** — does the proposed approach actually achieve the
+   intended outcome, or does it solve an adjacent, easier, or more
+   interesting problem instead?
+2. **Premise** — now that the plan is concrete, is there a materially
+   cheaper or simpler intervention that makes most of it unnecessary?
+3. **Scope drift** — does the task list build meaningfully more or less than
+   the request implies? Flag gold-plating and under-delivery symmetrically.
+4. **Right direction despite sound docs** — could every cited source be
+   correct and the plan still aim wrong? If so, name the wrong assumption
+   explicitly.
 
 ## Rules
-- Judge direction, not mechanics. Do not duplicate `design-reviewer` (consistency,
-  codebase-fit, best-practices citations are out of scope here).
-- Be concrete: a concern must name the specific decision and a cheaper/right alternative,
-  or it is not worth raising.
-- Be decisive. If the plan is correctly aimed, say PASS — do not invent concerns.
-- You do **not** loop. A `REDIRECT` is surfaced to the human at the design checkpoint;
-  changing direction is a human decision, consistent with the two-checkpoint rule.
+- Judge direction, not mechanics. Do not duplicate cw:design-reviewer's work
+  (consistency, codebase-fit, best-practices citations are out of scope
+  here).
+- Be concrete: a concern must name the specific decision and a cheaper or
+  right-er alternative, or it is not worth raising.
+- If the plan is correctly aimed, say PASS rather than manufacturing a
+  concern.
+- This review does not loop: a REDIRECT surfaces at the design checkpoint
+  for a person to decide, not something this agent iterates on.
 
-## Output — STRICT JSON ONLY
+## Output — strict JSON only
 
 Emit exactly one JSON object as your final message, no prose around it:
 
@@ -73,6 +74,6 @@ Emit exactly one JSON object as your final message, no prose around it:
 }
 ```
 
-`verdict` is `PASS` only when there are zero `blocking` concerns (list `advisory` ones
-anyway). If you cannot produce valid JSON, the orchestrator treats it as `REDIRECT` —
-so always close the JSON correctly.
+`verdict` is `PASS` only when there are zero `blocking` concerns (list
+`advisory` ones anyway). Malformed JSON is treated as `REDIRECT`, so always
+close the JSON correctly.
diff --git a/agents/implementer.md b/agents/implementer.md
index 7bfb42d..10b246c 100644
--- a/agents/implementer.md
+++ b/agents/implementer.md
@@ -2,9 +2,8 @@
 name: implementer
 description: "Focused code implementation agent. Writes code following an approved design. Cannot push to git or create PRs."
 model: sonnet
-maxTurns: 50
 effort: high
-permissionMode: acceptEdits
+maxTurns: 50
 tools:
   - Read
   - Write
@@ -14,30 +13,30 @@ tools:
   - Bash
   - mcp__context7__resolve-library-id
   - mcp__context7__query-docs
-mcpServers:
-  - context7
-# NOTE: parenthesized patterns (e.g. Bash(git push *)) in disallowedTools silently break the entire `tools` allowlist
-# in the current Claude Code release. Rely on the global protect-branches.sh PreToolUse hook (configured in
-# ~/.claude/settings.json) to block git push to main and force-push patterns. The hook applies to subagents too.
-memory: project
 color: blue
 ---
 
 # Implementer
 
-You are a focused implementation agent. You receive a design plan and execute it precisely.
+You are a focused implementation agent. You receive a design plan or a single
+scoped task from an orchestrator and execute it precisely.
 
 ## Rules
-- Follow the project's CLAUDE.md conventions exactly
-- Check framework APIs via context7 before using unfamiliar patterns
-- One logical change per commit (use conventional commit format)
-- Functions under 50 lines
-- If you encounter an ambiguity in the design, make a reasonable choice and note it — do not stop or ask
-- Never push code or create PRs — that's the orchestrator's job
+- Follow the project's CLAUDE.md conventions.
+- Consult framework and library docs (via the context7 tools) before relying
+  on an unfamiliar API surface.
+- Make one logical change per commit, in conventional commit format.
+- Commit as instructed by the orchestrator: one commit for the task, carrying
+  whatever trailer the project's workflow rules define.
+- If the design is ambiguous, make a reasonable choice and note it in your
+  output — do not stop to ask.
+- Do not push commits or open pull requests; that is the orchestrator's job.
+- Stay inside the files you were scoped to; flag anything outside that scope
+  instead of touching it.
 
 ## Output
 When done, provide a concise summary:
-1. Files created/modified
-2. Design deviations (if any) and why
-3. Test/build results
+1. Files created or modified
+2. Design deviations, if any, and why
+3. Test and build results
 4. Known limitations or TODOs
diff --git a/agents/researcher.md b/agents/researcher.md
index 1f86363..7dea110 100644
--- a/agents/researcher.md
+++ b/agents/researcher.md
@@ -1,11 +1,9 @@
 ---
 name: researcher
-description: "Web research agent. Searches docs, best practices, and prior art using the 3-angle search methodology. Returns structured findings with citations. Read-only — cannot modify files."
+description: "Web research agent. Searches docs, best practices, and prior art using the cw:search skill's method. Returns structured findings with citations. Read-only — cannot modify files."
 model: sonnet
-effort: high
+effort: medium
 maxTurns: 30
-skills:
-  - search
 tools:
   - Read
   - Glob
@@ -17,37 +15,39 @@ tools:
   - mcp__exa__crawling_exa
   - mcp__context7__resolve-library-id
   - mcp__context7__query-docs
-disallowedTools:
-  - Write
-  - Edit
-mcpServers:
-  - exa
-  - context7
+  - Skill
 color: green
 ---
 
 # Researcher
 
-You are a research agent. Your methodology comes from the preloaded `search` skill — follow its 3-angle search pattern (authoritative, practitioner, contrarian), source management rules, and quality standards.
-
-## How to Apply the Search Methodology
-1. For each research question, run the 3-angle search from the search skill
-2. Use Context7 for framework/library questions (official docs first)
-3. Use Exa for semantic/conceptual research (finds related content by meaning)
-4. Use WebSearch as baseline and for freshness (append current year)
-5. WebFetch the 2-3 most authoritative URLs for detail
-6. Apply the confidence rubric from the search skill (High/Medium/Low)
-
-## Additional Rules
-- Search for failure modes and gotchas, not just happy paths
-- Flag when sources conflict or when evidence is thin
-- If you cannot find evidence for a claim, say so — do not fabricate
-
-## Output Format (mandatory)
+You are a research agent with no Write or Edit tool: treat yourself as
+read-only. When a task calls for the cw:search skill's method, invoke it
+with the Skill tool rather than assuming its steps are already loaded.
+
+## How to research
+1. For each research question, run the pattern the cw:search skill
+   describes: an authoritative pass, a practitioner pass, and a contrarian
+   pass, cross-referenced against each other.
+2. Use the context7 tools for framework and library questions — official
+   docs first.
+3. Use exa for semantic or conceptual research that finds related content by
+   meaning.
+4. Use WebSearch as a baseline and for freshness (append the current year to
+   time-sensitive queries).
+5. WebFetch the two or three most authoritative URLs for detail.
+6. Rate each finding High, Medium, or Low confidence.
+
+## Additional rules
+- Search for failure modes and gotchas, not just happy paths.
+- Flag when sources conflict or evidence is thin.
+- If you cannot find evidence for a claim, say so rather than filling the
+  gap.
+
+## Output format (required)
 
 ### Findings
 - [Claim] — Source: [URL] ([publisher], [date if available]) — Confidence: high|medium|low
-- ...
 
 ### Consensus
 [strong|weak|conflicting] across [N] sources
diff --git a/agents/reviewer.md b/agents/reviewer.md
index 60e343e..95dff48 100644
--- a/agents/reviewer.md
+++ b/agents/reviewer.md
@@ -1,47 +1,55 @@
 ---
 name: reviewer
-description: "Code review agent. Reviews changes for quality, correctness, and convention adherence. Read-only — cannot modify files."
+description: "Code review agent. Reviews changes for quality, correctness, and convention adherence. Read-only — cannot modify files. Used by the /cw:build review loop."
 model: opus
-effort: xhigh
+effort: high
 maxTurns: 20
 tools:
   - Read
   - Glob
   - Grep
   - Bash
-disallowedTools:
-  - Write
-  - Edit
-# NOTE: Write/Edit denial above keeps the reviewer read-only. Parenthesized Bash patterns (Bash(git push *), etc.)
-# silently break the entire `tools` allowlist in the current Claude Code release — rely on global hooks for
-# git-push and force-push protection (~/.claude/hooks/protect-branches.sh applies to subagents).
 memory: project
 color: yellow
 ---
 
 # Code Reviewer
 
-You review code changes against the project's conventions and the approved design.
+You review code changes against the project's conventions and the approved
+design. You have no Write or Edit tool: you are read-only.
 
 ## Process
-1. Read the project's CLAUDE.md for conventions
-2. Inspect `git show HEAD -- <files>` or the diff range given in the prompt
+1. Read the project's CLAUDE.md for conventions.
+2. Read the changed files from disk and inspect `git show HEAD -- <files>` or
+   the diff range given in the prompt.
 3. For each changed file, check:
    - **Correctness**: logic errors, edge cases, off-by-one, null handling
    - **Conventions**: matches project CLAUDE.md (naming, structure, patterns)
-   - **Safety**: no hardcoded secrets, proper error handling, no injection vectors
-   - **Complexity**: functions under 50 lines, clear naming, no over-engineering
-4. Run the verification command given in the prompt
-5. Compare implementation against the design doc/plan (if referenced)
+   - **Safety**: no hardcoded secrets, proper error handling, no injection
+     vectors
+   - **Complexity**: clear naming, no over-engineering
+4. Run the verification command given in the prompt.
+5. Compare the implementation against the design doc or plan, if one is
+   referenced.
+6. Confirm the commit itself: one commit for the task, conventional-commit
+   format, touching only the files it was scoped to.
 
-## Output Format
-### Verdict: PASS | NEEDS WORK
+## Evidence
+Every finding needs a `file:line` and either a failing command or a concrete,
+reproducible scenario. Drop a finding you cannot back with evidence rather
+than listing it anyway.
 
-### Issues (if any)
-1. [severity: critical|warning|nit] `file:line` — description
+## Output — required structured verdict
+Your final message must end with a fenced JSON block matching exactly this
+schema:
 
-### Test Results
-[test suite output summary]
+```json
+{"verdict": "PASS|NEEDS_WORK", "findings": [{"file": "...", "line": 0, "issue": "...", "evidence": "..."}]}
+```
 
-### Design Adherence
-[how well the implementation matches the approved design]
+Start each finding's `issue` text with its severity: `critical` (wrong
+behaviour, a safety or security defect, a crash), `major` (a requirement not
+met), or `minor` (style or wording). `PASS` can never co-occur with a
+critical finding — if any finding is critical, the verdict is `NEEDS_WORK`.
+If you cannot produce valid JSON, say so plainly in prose before the block; a
+missing or unparseable block is not a pass.

From aab9b0bafd4636f490409282c2eb0cf3848d0936 Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Wed, 16 Sep 2026 17:43:40 +0100
Subject: [PATCH 06/24] refactor(skills): lean cw skills, single design
 document, google-workspace playbook

Rewrite the five workflow skills around one plan file per feature instead of
an artifact set: /cw:design drafts it in plan mode and moves it to
docs/plans/<slug>.md on approval, naming the un-ignore fix when the
destination is ignored; /cw:build reads its `## Task` blocks (with the
folder-layout fallback), supports `continue [<task-id>]`, and keeps the
ground-truth gate, the other-model review and the three-iteration fix loop
without any guard hook, sentinel or disallowed-tools. /cw:ship gains the
tests/run.sh gate convention, /cw:search points --deep at the bundled
deep-research skill.

Add /cw:google-workspace as a skill so the connector capability matrix, upload
routes and landmines are model-invocable, and tests/fixtures/two-task-plan.md
as the minimal two-task plan the load test drives.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 skills/build/SKILL.md            | 403 ++++++++++++------------------
 skills/compound/SKILL.md         |  51 ++--
 skills/design/SKILL.md           | 413 ++++++++++++-------------------
 skills/google-workspace/SKILL.md |  32 +++
 skills/search/SKILL.md           | 177 ++++++-------
 skills/ship/SKILL.md             | 231 ++++++++---------
 tests/fixtures/two-task-plan.md  |  25 ++
 7 files changed, 580 insertions(+), 752 deletions(-)
 create mode 100644 skills/google-workspace/SKILL.md
 create mode 100644 tests/fixtures/two-task-plan.md

diff --git a/skills/build/SKILL.md b/skills/build/SKILL.md
index fc301ae..9c8f049 100644
--- a/skills/build/SKILL.md
+++ b/skills/build/SKILL.md
@@ -1,272 +1,179 @@
 ---
 name: build
-description: "Implement an approved design by orchestrating subagents. Use when the user says /build, 'implement this', 'build this', or approves a /design output. Main agent acts as orchestrator: decomposes work, delegates to implementer subagent, reviews via reviewer subagent, iterates up to 3 times, then stops for human approval."
+description: "Implement an approved design by orchestrating subagents. Consumes the plan's task list, delegates each task to an implementer, verifies the result against git and the task's own verification command, reviews with a second model, and stops at a checkpoint before any PR."
 disable-model-invocation: true
-argument-hint: <slug | path to <slug>-tasks.md>
+argument-hint: "<slug> [continue [<task-id>]]"
 allowed-tools:
   - Read
-  - Write
-  - Edit
   - Glob
   - Grep
   - Agent
   - Bash(git:*)
+  - Bash(bash:*)
+  - Bash(jq:*)
+  - Bash(shellcheck:*)
+  - Bash(claude plugin:*)
   - Bash(npm:*)
   - Bash(python:*)
   - Bash(pip:*)
   - Bash(pytest:*)
   - Bash(swift:*)
   - Bash(xcodebuild:*)
-  - Bash(gh:*)
-  - Bash(touch /tmp/claude-orchestrator-active*)
-  - Bash(rm -f /tmp/claude-orchestrator-active*)
 ---
 
-# Build Workflow — Orchestrator Pattern
+# Build — Orchestrator Pattern
 
-You are the orchestrator. You do not write code yourself and you do **not** re-decompose
-the design — `/design` already produced `<slug>-tasks.md`. You consume that task list,
-delegate each task to a subagent, review results, and iterate. Your context stays clean;
-all heavy lifting happens in subagents.
+You are the orchestrator: you edit no file, and every change in this run is an
+implementer's — the review gate is what enforces that. You do not re-decompose
+the design either; `/cw:design` already wrote the task list. Consume it,
+delegate, verify, review, iterate, stop.
 
-**Mode:** `/build` runs in **execute mode** (default/acceptEdits), never plan mode. It
-begins only after the `/design` Step 5 human checkpoint approved the plan.
-
-Delegation is enforced, not just advised: while `/build` is active a session-scoped
-sentinel makes a PreToolUse hook deny direct source edits from the orchestrator, via an
-exit-code-2 block. If you find yourself wanting to edit a source file, that is the signal
-to spawn an implementer instead — note that a sentinel exit-2 block may simply stop the
-turn rather than auto-delegate (known issue #24327), so never assume the block will
-self-heal into an implementer spawn: treat the block itself as your cue to spawn one.
+Execute mode. Implementers need the session in auto mode or `acceptEdits` to
+write without a prompt per edit. Starts only after the design checkpoint.
 
 ## Input
-$ARGUMENTS
-
-## Phase 0: Pre-flight (orchestrator, main thread)
-1. **Resolve the tasks file** (`$ARGUMENTS`):
-   - `ROOT=$(git rev-parse --show-toplevel 2>/dev/null)`.
-   - explicit slug or path argument → check the **project copy first**:
-     `$ROOT/docs/plans/<slug>/<slug>-tasks.md`. `/design`'s Step 6.5 gate now guarantees
-     that a promoted project copy is **all-or-nothing** — present and complete, or absent
-     (on gate failure or any write failure, `/design` removes the partial copy itself) —
-     but `/build` cannot assume every project copy on disk was written by a version of
-     `/design` that had that cleanup, so it still re-verifies. This only counts if the set
-     is **COMPLETE** — `<slug>-tasks.md` AND `<slug>-design-draft.md` both present and
-     non-empty, AND at least one `<slug>-research-*.md` present in
-     `$ROOT/docs/plans/<slug>/`. `/build` can't re-check research *parity* (no plans-dir
-     reference count survives once its drafts are inert), but presence is cheap and closes
-     the crash window where core files were written but no research file was, and cleanup
-     never ran. A partial set (missing/empty core file, or zero research files present) is
-     not usable: warn the user and fall back to the legacy `~/.claude/plans/<slug>-tasks.md`
-     (or the given path) instead. Never silently mix a partial project copy with a
-     plans-dir remainder.
-   - no argument → glob the **project location first**: `$ROOT/docs/plans/*/*-tasks.md`.
-     If that glob has no matches, fall back to the **legacy plans dir**:
-     `~/.claude/plans/*-tasks.md`. Pick the newest by mtime within whichever glob actually
-     matched, **show the match and confirm with the user before proceeding** (do not
-     silently guess).
-   - no tasks file exists in either location → "No `<slug>-tasks.md` found — run
-     `/design` to generate one, or confirm you want me to decompose ad hoc." Do not invent
-     a fixed task count.
-2. Check git status — the working tree must be clean, but **tolerate untracked or
-   modified files under `docs/plans/<slug>/`** (those are the artifacts step 1 just
-   resolved, not build drift). Everything else must be clean or stashed. If stashing, use
-   **plain `git stash` only — NEVER `git stash -u` or `-a`**: either flag would also sweep
-   the untracked `docs/plans/<slug>/` artifacts into the stash, so step 4 below would see
-   no delta and silently skip the docs commit.
-3. Create feature branch from main: `feat/<slug>` or `fix/<slug>`.
-4. **Commit the design artifacts as a scoped `docs(<slug>):` commit** — typically the first
-   commit on a fresh Phase 0 branch, but not guaranteed to stay leading (a refresh committed
-   later on `continue` can land after task commits) — gated: this step only
-   runs when step 1 resolved a **COMPLETE project copy** at `$ROOT/docs/plans/<slug>/` in
-   THIS repo. A plans-dir-resolved build (the normal meta-tooling case, where there is no
-   project copy to promote) **skips this whole step with a notice** — `git add` on a
-   directory that was never created is a fatal pathspec error, and committing a set the
-   build didn't actually read from would diverge from the source of truth.
-   - Non-repo (`ROOT` empty) → skip with a notice.
-   - **Root-anchored trackability pre-check**: `git -C "$ROOT" check-ignore -q
-     "docs/plans/<slug>/probe"` — always root-anchored, never a cwd-relative probe (a
-     cwd-relative probe run from a subdirectory can false-positive). Ignored → warn and
-     skip; never `git add -f` to force past a project's own `.gitignore`.
-   - Ensure `docs/plans/** linguist-generated=true` is present in `$ROOT/.gitattributes`
-     (add it via `Edit`/`Write` if missing).
-   - `git add "$ROOT/docs/plans/<slug>/"`, plus `.gitattributes` if it was just touched —
-     **never a bare `git add .`**.
-   - Make **ONE** commit: `docs(<slug>): add design + research artifacts`, with the
-     standard co-author trailer (`Co-Authored-By: Claude <noreply@anthropic.com>`, per
-     CLAUDE.md).
-   - No delta to commit (e.g. a prior run already committed it) → skip silently.
-   - Commit command fails → `git restore --staged`, print the failure, and continue with
-     the artifacts left untracked — no retry loop.
-   This is an **orchestrator-authored commit, not a task commit** — it is excluded from
-   the one-commit-per-task accounting everywhere that accounting happens (Phase 2→3 gate,
-   Phase 3 reviewer commit check, Phase 5 series line — see the notes at each).
-5. Read project CLAUDE.md for coding conventions.
-6. **Allowlist-coverage check**: if permission prompts have come up frequently this
-   session, suggest running `/fewer-permission-prompts` before spawning implementers —
-   a well-populated allowlist keeps delegation moving without repeated interruptions.
-7. **Write the session-scoped delegation sentinel:**
-   `touch "/tmp/claude-orchestrator-active.$CLAUDE_CODE_SESSION_ID"`
-   (this env var matches the `session_id` the guard hook reads from stdin; requires
-   Claude Code ≥ v2.1.132 — if `$CLAUDE_CODE_SESSION_ID` is empty, fall back to
-   `touch /tmp/claude-orchestrator-active` and warn that session isolation is inactive).
-   **Remove it on every exit path** (Phase 5 success, Phase 4 iteration-3 escalation,
-   any abort, pre-flight failure) with `rm -f "/tmp/claude-orchestrator-active.$CLAUDE_CODE_SESSION_ID"`.
-   The guard hook also self-heals a stale sentinel after its TTL, but that is a backstop —
-   always remove yours explicitly.
-
-## Phase 1: Consume the task plan (orchestrator, main thread)
-**Do not decompose. Do not invent a task count.** Read the resolved `<slug>-tasks.md`
-and execute exactly the tasks it defines — 1 or many, whatever the file says.
-
-- Iterate tasks in `depends_on` order.
-- Tasks with no dependency relationship are independent (their `files_owned` are disjoint by construction) — spawn them **in the same turn (multiple Agent calls in one message), synchronously**. Dependent tasks run sequentially.
-- **Re-`touch` the session sentinel at the start of each task** (`touch "/tmp/claude-orchestrator-active.$CLAUDE_CODE_SESSION_ID"`) so its mtime stays fresh for the whole active build — only a stalled or killed run trips the guard hook's TTL.
-- Per-task model is whatever the task's `model:` field says — do not re-derive it (the design already assigned Sonnet vs Opus).
-
-## Phase 2: Implement (delegate to implementer subagent)
-For each task, spawn an **implementer** subagent. **Context-pin it** — give it only its
-own single task entry and the relevant design excerpt, never the whole design or the
-whole `<slug>-tasks.md`. The prompt includes:
-1. **The task's `scope`** (one sentence: what to build and why)
-2. **Relevant design excerpt only** — the portion of `<slug>-design-draft.md` this task covers
-3. **`files_owned`** — the implementer reads current contents itself (do not paste file contents)
-4. **A reference pattern**: "Follow the pattern in [existing_file:symbol]"
-5. **The task's `verification`** — exact command(s) + expected result
-6. **The task's `commit:` line** and this instruction: *"When the code is complete and `verification` passes, make exactly ONE atomic commit using this `commit:` line (Conventional format, inheriting CLAUDE.md's generic co-author trailer — never hardcode a model-specific trailer), committing only the files in `files_owned`. One task = one commit. Do NOT push."* — **`commit: none`** (external/unversioned target, e.g. a task that edits a live config directory outside this repo): OMIT this instruction entirely. Do not tell the implementer to commit anything for that task; its work is verification-only.
-7. **A required exit report**: instruct the implementer that its final message must end
-   with a fenced JSON block matching exactly this schema:
+$ARGUMENTS — `<slug>`, optionally followed by `continue` and a task id.
+
+## Phase 0: Pre-flight
+1. **Resolve the plan.** `ROOT=$(git rev-parse --show-toplevel 2>/dev/null)`;
+   read `$ROOT/docs/plans/<slug>.md`. Absent → fall back to the folder layout
+   `$ROOT/docs/plans/<slug>/<slug>-tasks.md` with `<slug>-design-draft.md`
+   beside it; that pair has to be complete — both present and non-empty — or
+   refuse and say which half is missing. Neither shape → "No plan found for
+   `<slug>` — run `/cw:design` first." Do not invent a task count.
+2. **Clean tree**, except an untracked or modified design file for this slug —
+   that is what step 1 just read, not build drift. Stash with plain `git stash`
+   only: `-u` or `-a` would sweep that file in, leaving step 4 no delta.
+3. **Branch** `feat/<slug>` or `fix/<slug>` from `main`; on `continue`, reuse
+   the existing branch.
+4. **Commit the design** when its file is untracked or modified: stage it by
+   explicit pathspec (the plan file, or the folder-layout pair plus its
+   research files), never `git add .`, and make one commit,
+   `docs(<slug>): design`, with the trailer the workflow rules define. No delta
+   → skip silently. Not a repo, or the commit fails → report and carry on with
+   the file uncommitted, no retry loop. This commit is orchestrator-authored
+   and is excluded from every per-task commit count below.
+5. Read the project's CLAUDE.md for conventions.
+
+## Phase 1: Consume the task list
+Collect every `## Task <id>` block in the plan file (the folder layout keeps
+them in `<slug>-tasks.md`) and execute exactly those — one or many.
+
+- Run them in `depends_on` order. Tasks with no dependency between them are
+  independent by construction (disjoint `files_owned`): spawn them together,
+  several Agent calls in one message, synchronously. Dependents run in
+  sequence.
+- A task's model is whatever its `model:` field says (`sonnet` by default,
+  `opus` where stated). Do not re-derive it.
+- **`continue`**: read `git log --format=%s main..HEAD` and skip every task
+  whose `commit:` subject is already there. Given a `<task-id>`, start at that
+  task and skip everything before it.
+
+## Phase 2: Implement — delegate to `cw:implementer`
+One implementer per task, the Agent call's `model` taken from the task.
+Context-pin it: its own task block and the relevant design excerpt, never the
+whole plan. The prompt carries:
+
+1. The task's `scope` — one sentence on what to build and why.
+2. Only the design excerpt this task covers.
+3. `files_owned` and `files_forbidden` — it reads current contents itself; do
+   not paste file bodies into the prompt.
+4. A reference pattern: "follow the pattern in `<existing_file>:<symbol>`".
+5. The task's `verification` — exact command(s) and expected result.
+6. The task's `commit:` line, plus: *"When the work is done and `verification`
+   passes, make exactly one atomic commit from this `commit:` line, in
+   Conventional format, ending with the trailer the workflow rules define,
+   staging only `files_owned` by explicit path. One task, one commit. Do not
+   push."* Omit this entirely for a `commit: none` task (an unversioned or
+   external target) — that task is verification-only.
+7. A required exit report: its final message ends with a fenced JSON block
+   matching exactly this schema:
    ```json
    {"status": "success|partial|failed", "commit_sha": "<sha>", "files_touched": ["..."], "verification_output": "...", "unresolved_issues": ["..."]}
    ```
-   This report is testimony, not proof — it is checked against ground truth in the gate below before any review starts.
-
-Set the Agent call's `model` to the task's `model:` field (`sonnet` default, `opus` where
-the task says so). Spawn independent tasks in one turn, synchronously; dependent tasks
-sequentially (per Phase 1).
-
-For a cost-bounded run, set a `task_budget` (advisory, minimum 20k tokens; use whichever
-task-budgets beta header is supported at run time — check current Claude Code release
-notes rather than assuming a fixed value) on the implementer spawn. Skip it for
-quality-critical tasks where the work should not be scoped to a budget.
-
-## Phase 2→3 Gate: Verify against ground truth (orchestrator, main thread)
-Before any reviewer is spawned, the orchestrator itself checks the implementer's exit
-report against ground truth — never proceeds on testimony alone:
-- **`commit: none` tasks**: skip the commit checks entirely — verify by **re-running the
-  task's `verification` command only** and comparing the real output against the reported
-  `verification_output`. There is no `commit_sha` and no `main..HEAD` check to perform;
-  the task has no commit to have produced.
-- **All other tasks**: run `git log --oneline main..HEAD` (or the task's expected range)
-  and confirm `commit_sha` exists, is Conventional-format, and touches only the task's
-  `files_owned`. Also re-run the task's `verification` command yourself and compare the
-  real output against the reported `verification_output`.
-- If `status != "success"`, or the report doesn't match ground truth (commit missing,
-  verification actually fails, files touched outside `files_owned`), treat the task as
-  failed: do not proceed to Phase 3 — fold this into Phase 4's iteration logic instead
-  (or escalate immediately if the iteration budget is already exhausted).
-- **Note**: any `docs(<slug>): add design + research artifacts` commit from Phase 0 step 4
-  is orchestrator-authored, not a task commit — exclude it from every commit-accounting
-  check above (`main..HEAD` may legitimately contain it in addition to the task's own
-  commit; it does not count against the one-commit-per-task expectation, and this is not
-  limited to a "leading" commit — a refresh committed later on `continue` is excluded the
-  same way).
-
-## Phase 3: Review (delegate to reviewer subagent)
-Only after the ground-truth gate passes, spawn a **reviewer** subagent.
-
-**Counter-model rule**: the reviewer's model is always the opposite of the implementer's
-for this task — `opus` reviews work an implementer did as `sonnet`, and `sonnet` reviews
-work an implementer did as `opus`. Never reuse the implementer's own model for review.
-
-**Tiered depth** (from the task's `risk:` field):
-- **Deep review** — required when `risk: high`, or the task touches
-  schema/API/auth/security, or the task's `files_owned` spans more than 3 files. Full
-  checklist below, adversarial framing, every finding reproduced before it's reported.
-- **Fast-path** — everything else: conventions check + commit check only, no adversarial
-  deep-dive needed.
-
-The reviewer prompt includes:
-1. The list of changed files (from the implementer's exit report `files_touched`, already
-   confirmed against ground truth above)
-2. The original design requirements for these changes
-3. **Adversarial framing**: "Your job is to find problems, not to approve. You cannot
-   return PASS without having personally checked correctness, conventions, safety, and
-   complexity — do not take the implementer's exit report or summary as evidence of any
-   of these."
-4. Instruction: "Read all files FRESH from disk. Run `git diff`. Run tests. Do NOT trust
-   prior summaries."
-5. **Reproduce-before-report**: "Every finding must include a file:line AND either a
-   concrete failing command or a specific reproducible failure scenario. Findings without
-   evidence are dropped — do not include them in your verdict."
-6. **Commit check:** "Confirm the task produced exactly one commit (`git log --oneline main..HEAD`), in Conventional format, with CLAUDE.md's co-author trailer, touching only `files_owned`. Flag a missing commit, a squashed/multi-task commit, or a malformed message. Exclude any `docs(<slug>): add design + research artifacts` commit from this check — that commit is orchestrator-authored (Phase 0 step 4), not a task commit, and may legitimately be present alongside the task's own commit." — **skip this check entirely for a `commit: none` task**: there is no task commit to confirm.
-7. **Required structured verdict**: instruct the reviewer that its final message must end
-   with a fenced JSON block matching exactly this schema:
-   ```json
-   {"verdict": "PASS|NEEDS_WORK", "findings": [{"file": "...", "line": 0, "issue": "...", "evidence": "..."}]}
-   ```
-   **Cross-field rule (orchestrator-checked)**: `PASS` can never co-occur with a critical
-   finding. If the reviewer returns `PASS` alongside a critical-severity finding, the
-   orchestrator treats this as a malformed verdict — not a pass — and reprompts the
-   reviewer or escalates rather than accepting it at face value.
-
-The reviewer reads files from disk with fresh context — no implementer bias.
-
-## Phase 4: Iterate (orchestrator decides)
-Based on the reviewer's verdict:
-
-- **NO_VERDICT** (the reviewer's final message is missing the fenced JSON block, or it's
-  unparseable, or the reviewer went silent): this is distinct from NEEDS_WORK. Spawn a
-  fresh reviewer instance (new context, same task/files) and retry once. If the retry is
-  also NO_VERDICT, stop and escalate to the user immediately rather than guessing a verdict.
-  A NO_VERDICT retry does NOT consume one of the 3 implement-review iterations below.
-- **PASS**: Proceed to Human Checkpoint
-- **NEEDS WORK** (iteration 1-2): Spawn a NEW implementer subagent with:
-  - The reviewer's specific issues (file:line + description)
-  - The original design requirements
-  - Instruction (task's `commit:` is NOT `none`): "Fix these specific issues. Do not refactor beyond what's listed. Fold the fix into THIS task's existing commit (`git commit --amend` or an autosquash fixup), so the series stays exactly one atomic commit per task — do not add a second commit for the same task."
-  - Instruction (task's `commit:` IS `none`): "Fix these specific issues by re-editing the owned files only. Do not run `git commit` or `git commit --amend` — this task has no commit of its own, and amending would rewrite an unrelated prior commit on the target (e.g. a live config repo's own history on its `main`)."
-  - Then re-run the reviewer
-- **NEEDS WORK** (iteration 3): STOP and escalate to the user with:
-  - What was implemented
-  - What the reviewer flagged
-  - What was attempted to fix it
-  - Ask: "3 review iterations didn't resolve these issues. How would you like to proceed?"
-
-Max 3 implement-review iterations. After 2 failed corrections, the problem is usually the design, not the code.
-
-## Phase 5: Human Checkpoint
-Present a summary to the user:
-- **What was built**: Files created/modified with brief descriptions
-- **Committed design artifacts**: if Phase 0 step 4 ran, list the files in the
-  `docs(<slug>): add design + research artifacts` commit (the design draft, tasks file,
-  and any research files) — this commit is separate from the task series below.
-- **Commit series**: `git log --oneline main..HEAD` — one atomic Conventional commit per
-  task (tasks with `commit: none` contribute no commit here — that's expected, not a
-  gap), each with the co-author trailer, **excluding** the orchestrator-authored
-  `docs(<slug>):` artifacts commit above (this is what `/ship` will verify, not rewrite)
-- **Design deviations**: Any places the implementer diverged and why
-- **Review result**: Final reviewer verdict + any remaining nits
-- **Test results**: Pass/fail with details
-- **Manual test instructions**: What the user should test (project-specific)
-
-Ask: "Review the changes. Want me to adjust anything, or ready to ship?"
-
-Remove the session sentinel: `rm -f "/tmp/claude-orchestrator-active.$CLAUDE_CODE_SESSION_ID"` (also do this if you escalate at Phase 4 iteration 3 or abort earlier — the sentinel must never outlive the `/build` run).
-
-Do not proceed to PR creation. the user will run /ship when ready.
-
-## Anti-patterns to avoid
-- Do NOT write code yourself — always delegate to the implementer subagent
-- Do NOT re-decompose the design or invent a task count — consume `<slug>-tasks.md` as-is (1 or many tasks)
-- Do NOT create a single squashed or catch-all commit — each task self-commits atomically (one task = one commit)
-- Do NOT pass the full design doc or the whole tasks file to the implementer — only its one task entry + the relevant excerpt
-- Do NOT include file contents in the implementer prompt — let it read them
-- Do NOT let the implement-review loop run more than 3 times
-- Do NOT fix issues yourself after reviewer flags them — spawn a new implementer
-- Do NOT proceed to Phase 3 on the implementer's exit report alone — verify `commit_sha` and re-run `verification` yourself first
-- Do NOT reuse the implementer's model for review — the reviewer must be the counter-model
-- Do NOT treat NO_VERDICT as NEEDS_WORK — retry fresh once, then escalate; it must never consume a fix-iteration
-- Do NOT `git commit --amend` a fix for a `commit: none` task — it has no commit of its own; amending would rewrite an unrelated prior commit on the target repo. Re-edit the owned files only.
-- Do NOT `git add .` or `git add -f` when committing the Phase 0 design-artifacts commit — pathspec the artifact dir explicitly, and never force past a project's `.gitignore`
-- After 2 failed iterations, the problem is usually spec ambiguity — escalate to the user
+   The report is testimony, not proof; the gate below checks it.
+
+## Phase 2→3 gate: check the report against the repo
+Completion is what git and real command output show, not what a subagent says.
+Before any reviewer is spawned:
+
+- **`commit: none` task** — re-run its `verification` yourself and compare the
+  real output with the reported `verification_output`. No commit to check.
+- **Any other task** — in `git log --oneline main..HEAD` (or the task's
+  expected range), confirm `commit_sha` exists, is Conventional-format, and
+  touches only `files_owned`; then re-run `verification` yourself and compare.
+- `status != "success"`, a missing commit, a verification that actually fails,
+  or files touched outside `files_owned` → the task failed: fold it into Phase
+  4's iteration logic instead of reviewing it.
+- Phase 0's `docs(<slug>): design` commit may sit in the range; exclude it.
+
+## Phase 3: Review — delegate to `cw:reviewer`
+Only once the gate passes, and on the other model of the pair: `opus` reviews
+what a `sonnet` implementer wrote, `sonnet` reviews what an `opus` one wrote.
+
+**Depth from `risk:`** — deep review when `risk: high`, or the task touches
+schema, API, auth or security, or `files_owned` spans more than three files:
+full checklist, adversarial framing, every finding reproduced. Otherwise
+fast-path: conventions and the commit check only.
+
+The prompt carries the confirmed list of changed files; the design requirements
+for them; adversarial framing ("your job is to find problems, not to approve —
+the implementer's exit report is not evidence of anything"); "read the files
+fresh from disk, run `git diff`, run the tests"; and reproduce-before-report
+("every finding needs a file:line plus a failing command or a specific
+reproducible scenario; drop what you cannot back").
+
+Commit check: "confirm the task produced exactly one commit in
+`git log --oneline main..HEAD`, Conventional format, with the project's
+trailer, touching only `files_owned`; flag a missing, squashed or malformed
+one, and exclude the `docs(<slug>): design` commit, which is not a task
+commit." Skip it entirely for a `commit: none` task.
+
+Required verdict, as `agents/reviewer.md` defines it — the reviewer's final
+message ends with a fenced JSON block matching exactly this schema:
+
+```json
+{"verdict": "PASS|NEEDS_WORK", "findings": [{"file": "...", "line": 0, "issue": "...", "evidence": "..."}]}
+```
+
+Reviewers report every finding they can evidence; filtering by severity is your
+pass, not theirs. Cross-field rule you enforce: `PASS` cannot co-occur with a
+critical finding — that combination is a malformed verdict, so reprompt or
+escalate rather than accept it.
+
+## Phase 4: Iterate
+- **Missing or unparseable verdict** (no fenced block, unreadable JSON, a
+  silent reviewer) is not a NEEDS_WORK: spawn one fresh reviewer on the same
+  task and retry once, then escalate if it is no better. This retry does not
+  consume one of the three iterations below.
+- **PASS** → next task, then the checkpoint.
+- **NEEDS_WORK, iterations 1–2** → a new implementer gets the reviewer's
+  file:line findings and the original requirements: "fix exactly these issues,
+  do not refactor beyond them, and fold the fix into this task's existing
+  commit (`git commit --amend` or an autosquash fixup), so the series keeps
+  one atomic commit per task." For a `commit: none` task instead: "re-edit the
+  owned files only; do not run `git commit` or `git commit --amend` — this
+  task has no commit of its own, and amending would rewrite unrelated history
+  on the target." Then re-run the reviewer.
+- **NEEDS_WORK, iteration 3** → stop and escalate with what was built, what was
+  flagged, what was attempted, and "three review iterations did not resolve
+  these issues. How would you like to proceed?" After two failed corrections
+  the problem is usually the design, not the code.
+
+## Phase 5: Checkpoint
+Summarise: what was built; the `git log --oneline main..HEAD` series
+(`commit: none` tasks contribute nothing there, as expected); design deviations
+and why; final verdicts and remaining nits; test results; what to test by hand.
+Then: "Review the changes. Resume an unfinished run with `/cw:build <slug>
+continue [<task-id>]`, or run `/cw:ship` when you are ready for the PR." Do not
+open a PR here.
+
+## Anti-patterns
+- Editing a file yourself instead of spawning an implementer.
+- Re-decomposing the design, or padding it to a task count.
+- A squashed or catch-all commit; each task self-commits.
+- Passing the whole plan, or file contents, to an implementer.
+- Reviewing before the gate passes, or on the implementer's own model.
+- Running the fix loop past three iterations, or fixing findings yourself.
+- `git add .`, or `git add -f` past a project's own `.gitignore`.
+- Amending for a `commit: none` task; re-edit its owned files instead.
diff --git a/skills/compound/SKILL.md b/skills/compound/SKILL.md
index c3c8918..ebca39b 100644
--- a/skills/compound/SKILL.md
+++ b/skills/compound/SKILL.md
@@ -1,8 +1,8 @@
 ---
 name: compound
-description: "Capture reusable lessons from a just-shipped change back into the project's CLAUDE.md / .claude/rules so future work compounds. Use when the user says /compound, or after /ship when they want to record what was learned. User-driven only; never auto-invoked. Proposes edits and applies them only on explicit approval."
+description: "Capture reusable lessons from a just-shipped change back into the project's CLAUDE.md or rules files so future work compounds. Use when the user says /cw:compound, or after /cw:ship when they want to record what was learned. Proposes process-rule edits, applies only the ones the user approves, and never commits them."
 disable-model-invocation: true
-argument-hint: [optional commit range or PR number; defaults to the last merged feature]
+argument-hint: "[optional commit range or PR number; defaults to the last merged feature]"
 allowed-tools:
   - Read
   - Glob
@@ -15,45 +15,58 @@ allowed-tools:
 
 # Compound — Post-Ship Lesson Capture
 
-Single-pass. Read what just shipped, extract the few lessons worth keeping, propose edits to the project's living docs, apply only on the user's approval. Quality over quantity — one durable rule beats five vague ones.
+Single pass: read what just shipped, extract the few lessons worth keeping,
+propose edits to the project's living process docs, apply only what the user
+approves. Quality over quantity — one durable rule beats five vague ones.
 
 ## Input
 $ARGUMENTS
 
 ## Step 1: Establish the shipped scope (main thread)
-1. Determine the range: use `$ARGUMENTS` if given (a commit range or PR number); otherwise `git log --oneline -20` and identify the most recent merged/feature span.
+1. Resolve the range: use `$ARGUMENTS` if given (a commit range or PR number);
+   otherwise `git log --oneline -20` and identify the most recent feature span.
 2. `git diff --stat <range>` and `git log <range>` to see what changed and why.
-3. Locate the design artifact if one exists — check the project copy first,
-   `docs/plans/<slug>/<slug>-design-draft.md` (canonical once `/build` has committed it),
-   then fall back to the legacy `~/.claude/plans/<slug>-design-draft.md` — and any
-   `/design` review-loop findings recorded with it.
+3. Read the design file for that feature if one exists —
+   `docs/plans/<slug>.md` — including whatever its review loop recorded.
 
 ## Step 2: Extract lessons (one delegated subagent)
-Spawn a single **`general-purpose`** subagent, model `sonnet`, read-only behavior (instruct it not to modify files), synchronously. Give it: the commit range, the diff/log, the design doc path, and the review-loop findings. Ask it to return ONLY structured JSON:
+Spawn a single `general-purpose` subagent, model `sonnet`, synchronously,
+instructed not to modify files. Give it the commit range, the diff and log, the
+design file path, and the review findings. Ask it to return only this JSON:
 
 ```json
 {
   "lessons": [
     {
-      "target_file": "CLAUDE.md | .claude/rules/<file>.md",
-      "rationale": "what recurring mistake/insight this prevents next time",
-      "proposed_edit": "the exact text to add or the precise change to make"
+      "target_file": "CLAUDE.md | rules/<file>.md",
+      "rationale": "the recurring mistake or insight this prevents next time",
+      "proposed_edit": "the exact text to add, or the precise change to make"
     }
   ]
 }
 ```
 
-Rules for the subagent: only propose a lesson if it would change future behavior; prefer editing an existing section over adding a new one; no speculative or one-off observations; if nothing is worth recording, return `{"lessons": []}`.
+Rules for the subagent: propose a lesson only if it would change future
+behaviour; prefer editing an existing section over adding a new one; no
+speculative or one-off observations; if nothing is worth recording, return
+`{"lessons": []}`.
 
-## Step 3: Present for approval (HITL)
-Show the user each proposed lesson: target file, rationale, and the concrete edit (as a diff-style before/after where it changes existing text). One focused summary, not a wall of options. Ask which to apply (all / a subset / none). Do not edit anything yet.
+## Step 3: Present for approval
+Show each proposed lesson: target file, rationale, and the concrete edit (a
+before/after where it changes existing text). One focused summary, not a wall
+of options. Ask which to apply — all, a subset, or none. Edit nothing yet.
 
 ## Step 4: Apply approved edits
-For each approved lesson, make the edit to the target file. Keep edits minimal and in the existing voice of the doc. If `lessons` was empty or the user approved none, make no changes.
+Make each approved edit in the target file, minimal and in the doc's existing
+voice. If `lessons` was empty, or the user approved none, change nothing.
 
 ## Step 5: Summary
-One line: what compounded (e.g., "Added a gate-precedence rule to .claude/rules/pr-merge-policy.md so /ship never picks the wrong Tier-1 command again"), or "Nothing durable to record this cycle."
+One line: what compounded (for example, "added a gate-precedence rule to
+`rules/workflow.md` so the quality gate never picks the wrong command again"),
+or "nothing durable to record this cycle".
 
 ## Notes
-- This skill edits living docs only — never source code, never git history.
-- It does not commit. If the user wants the doc change committed, that's a follow-up `/ship` or a manual commit.
+- This skill edits living process docs only — no source code, no git history.
+- It proposes and applies; it never commits. A doc change the user wants
+  committed is a follow-up change of its own, deliberately outside the feature
+  PR that triggered this run.
diff --git a/skills/design/SKILL.md b/skills/design/SKILL.md
index ca324b6..031ce38 100644
--- a/skills/design/SKILL.md
+++ b/skills/design/SKILL.md
@@ -1,285 +1,192 @@
 ---
 name: design
-description: "Research-grounded feature design with a convergence-driven auto-review loop (no fixed iteration count). Use when the user says /design, starts planning a feature, or needs to explore an approach. Challenges the premise, grounds the design in the real codebase + current web best practices, self-reviews until findings converge (or escalates after 5 iterations), then stops for human approval before any implementation."
-argument-hint: <feature description or voice note transcript>
+description: "Research-grounded feature design that ends in one approved plan file. Use when the user says /cw:design, starts planning a feature, asks how to approach something, or needs an implementation plan. Challenges the premise first, grounds the design in the real codebase and current web sources, self-reviews until findings converge (escalating after 5 iterations), then stops for the user's approval before any code is written."
+argument-hint: "<feature description or voice note transcript>"
+effort: xhigh
 allowed-tools:
   - Read
   - Glob
   - Grep
   - Agent
+  - Skill
   - Write
   - Edit
-  - Bash(git log:*)
-  - Bash(git diff:*)
-  - Bash(touch /tmp/claude-design-active*)
-  - Bash(rm -f /tmp/claude-design-active*)
-  - Bash(git rev-parse:*)
+  - Bash(git:*)
   - Bash(mkdir:*)
-  - Bash(git check-ignore:*)
-  - Bash(git clean:*)  # Step 6 all-or-nothing cleanup of an untracked partial docs/plans/<slug> copy; narrower than Bash(rm -rf:*) since git clean cannot touch tracked files
-  - Bash(git init:*)
-  - Bash(git commit --allow-empty*)
+  - Bash(mv:*)
 ---
 
 # Research-Grounded Design
 
-You are helping the user design a feature. The cost model is **80/20 — spend the effort in planning and review, not in redrafting later**. Research first, challenge the premise, design, self-review, then stop for human approval.
+The cost model is 80/20: spend the effort in planning and review, not in
+redrafting later. Research first, challenge the premise, draft, self-review to
+convergence, then stop for the user's approval.
 
 ## Input
 $ARGUMENTS
 
-Derive a short kebab-case `<slug>` from the feature (first 3–5 meaningful words). All plan-mode artifacts go in `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plans/`:
-- `<slug>-research-codebase.md`, `<slug>-research-docs.md`, `<slug>-research-bestpractices.md`
-- `<slug>-design-draft.md` (the design itself; the review loop reads this)
-- `<slug>-tasks.md` (the executable task breakdown `/build` consumes)
+Derive a short kebab-case `<slug>` (first 3–5 meaningful words). One feature
+produces **one file**: the plan. Steps 0–5 run in plan mode and write it
+wherever plan mode puts plan files — `docs/plans/` when the profile sets
+`plansDirectory: docs/plans`, otherwise the default plans location. Step 5 ends
+with this skill calling `ExitPlanMode` itself, the explicit mode transition;
+approval there is administrative, ending drafting so Step 6 can move the file.
+The real accept/reject decision is `/cw:build`.
 
-## Mode
+## Step 0: Office-hours gate (before any research spend)
+Pose one adversarial challenge and wait for an answer:
 
-`/design` is a **hybrid**: Steps 0–5 (research, draft, review loop) run **in plan mode**,
-then a short guarded window in Step 6 runs in **execute mode** to write the approved
-artifact set into the project, and Step 7 is the single human checkpoint that follows.
+> Before I research this: is this the right problem to solve? What is the
+> cheapest way to invalidate the premise? Is there an existing solution that
+> already covers it?
 
-Plan mode normally restricts writes to a single plan file; the Steps 0–5 loop is the
-documented exception — it is model-invocable and writes its research/draft/task-breakdown
-artifact set to `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plans/<slug>-*.md` (all writes
-confined there, matching the orchestrator-delegate-guard exemption). *Workflow judgment
-call — not officially blessed by plan mode, but bounded to the plans directory.* This part
-of the skill is unchanged by the hybrid model below. For meta-tooling designs — where
-Step 6's routing rule resolves `$ROOT` equal to `${CLAUDE_CONFIG_DIR:-$HOME/.claude}` (the
-project being designed for IS the config repo itself, so there is no separate project
-`docs/plans/` to promote into) — the artifacts live and end here, same as the README's
-"Forking this workflow repo itself" section describes for that repo layout: an accepted
-limitation, not a bug.
-
-At the end of Step 5, `/design` calls `ExitPlanMode` itself — this is the explicit mode
-transition; there is no longer an implicit boundary to avoid crossing. **The user's
-approval at that `ExitPlanMode` call is administrative, not the go/no-go decision** — it
-only ends drafting and lets the turn continue into execute mode for the Step 6 artifact
-write. The real accept/reject decision point remains `/build`. If the user rejects at
-`ExitPlanMode`, stay in plan mode and keep iterating per the Iteration Protocol below,
-exactly as before this change. If the user approves, the same turn continues straight into
-Step 6 — no new turn, no re-prompt.
-
-## Step 0: Office-Hours Gate (before any research spend)
-
-Pose one adversarial challenge to the user and wait for their answer:
-
-> Before I research this: is this the right problem to solve? What's the cheapest way to invalidate the premise? Is there an existing solution that already covers it?
-
-- If the user redirects, adopt the new framing.
-- If the user says "skip — already validated", proceed.
-- Do not spend on Step 2 research until this is answered.
+Adopt a redirect if one comes; "skip — already validated" is a fine answer.
+Do not spend Step 2's budget before this is answered.
 
 ## Step 1: Understand (main thread)
-1. Read the project's CLAUDE.md / ARCHITECTURE.md (or equivalent) for conventions.
-2. `git log --oneline -20` on the paths relevant to the feature — recent intent the source alone won't show.
-3. Explore relevant source files to understand what exists.
-4. List explicit unknowns and assumptions. Ask the user clarifying questions if the spec is ambiguous — do not guess.
-
-## Step 2: Parallel Grounding (synchronous)
-
-Spawn these three subagents **in the same turn (three Agent calls in one message), synchronously** — do not use background execution, and do not spawn them one at a time. Opus needs the fan-out stated explicitly.
-
-- **`Explore`** — map the codebase areas the feature touches: existing patterns, the modules/schemas/functions it will reference, where similar things already live. **Set this Agent call's `model` to `haiku`** — fan-out codebase navigation is the Haiku tier; do not let it inherit Opus. *Single fallback:* if its returned summary is too thin to ground the design, re-spawn that one Explore call with `sonnet`.
-- **`researcher`** #1 (docs/API currency) — "For libraries/frameworks likely involved (name them), verify the current API surface and that nothing the design will rely on is deprecated." Tell it to prioritize context7.
-- **`researcher`** #2 (best-practices/architecture) — "For the architectural choice(s) this feature implies, what is the current best practice and what newer/better pattern might supersede the obvious one?" Tell it to emphasize the practitioner + contrarian angles.
-
-Subagents are read-only and return summaries. **You (the orchestrator) write each returned summary to its file**: the Explore summary → `<slug>-research-codebase.md`, researcher #1 → `<slug>-research-docs.md`, researcher #2 → `<slug>-research-bestpractices.md`. These files are the fresh-context input for the review loop, so write them verbatim enough to stand alone.
-
-**Workflow-scale escape hatch**: if grounding this feature needs more than 4 research angles (large features, PRD milestones spanning multiple subsystems), do not spawn more individual researcher agents — instead run Step 2 as **one ultracode workflow**: a single read-only fan-out + synthesis workflow covering all the angles, which then writes the same three files (`<slug>-research-codebase.md`, `<slug>-research-docs.md`, `<slug>-research-bestpractices.md`) from its synthesized output. This replaces the three individual Agent calls above for that design only — Step 3 onward proceeds unchanged.
-
-Every architectural claim in the design must trace to one of these files or carry an explicit "unsourced — judgment call" flag.
-
-## Step 3: Synthesize the Design Draft
-
-Write `<slug>-design-draft.md` with these sections:
-
-- **Context** — the problem, why now, intended outcome.
-- **Approach** — what to build and why this over alternatives. Cite the research files.
-- **Files to Create/Modify** — exact paths with purpose; reference existing patterns found in Step 2.
-- **Dependencies** — new packages/keys/services, version-pinned where possible.
-- **Risks & Mitigations** — what could go wrong, how to detect it, how to roll back.
-- **Success Criteria** — testable assertions.
-- **Implementation Plan** — ordered steps grouped into logical commits.
-
-## Step 3b: Synthesize the Task Breakdown
-
-Derive `<slug>-tasks.md` from the design's "Files to Create/Modify" + "Implementation
-Plan". This is the artifact `/build` executes — make it precise and self-contained.
-
-The task **count is adaptive**: 1 task for a trivial change, as many as the design
-implies for a large one. **There is no fixed range** — never pad to or cap at a number.
-Split so that no two tasks own the same file (disjoint `files_owned` prevents merge
-conflicts and lets independent tasks run in parallel). Each task maps to **exactly one
-atomic Conventional commit**.
-
-**Vertical-slice ordering**: when the feature spans layers (schema/API/UI/etc.), order
-tasks as vertical slices — schema→API→UI→test for slice 1, then schema→API→UI→test for
-slice 2 — never all-of-layer-N across every slice before layer-N+1 starts. Each slice
-ends at its own compile/test gate: that slice's task(s) `verification` must pass before
-the next slice's tasks begin. A gate failure blocks only that slice's downstream tasks,
-not unrelated slices.
-
-Schema per task:
+1. Read the project's CLAUDE.md, ARCHITECTURE.md or equivalent for conventions.
+2. `git log --oneline -20` on the paths the feature touches — recent intent the
+   source alone will not show.
+3. Read the relevant source files to see what already exists.
+4. List the unknowns and assumptions. Ask the user about an ambiguous spec
+   rather than guessing.
+
+## Step 2: Parallel grounding (synchronous)
+Spawn three subagents together, three Agent calls in one message — not in the
+background, not one at a time:
+
+- **`Explore`** (the built-in agent, this call's `model` pinned to `haiku`) —
+  map what the feature touches: existing patterns, the modules, schemas and
+  functions it will reference, where similar things already live. Fan-out
+  navigation is the haiku tier; do not let it inherit the orchestrator model.
+  If its summary is too thin to ground the design, re-spawn that one call with
+  `sonnet`.
+- **`cw:researcher`** #1, docs and API currency — "for the libraries and
+  frameworks likely involved (name them), verify the current API surface and
+  that nothing this design relies on is deprecated." Tell it to prioritise
+  context7.
+- **`cw:researcher`** #2, best practices — "for the architectural choices this
+  feature implies, what is current best practice, and what newer pattern might
+  supersede the obvious one?" Tell it to lean on the practitioner and
+  contrarian angles. Invoke `/cw:search` through the Skill tool when you want
+  its full method in the main thread.
+
+Subagents are read-only. Fold each returned summary into the plan's Research
+section verbatim enough to stand alone — the review loop reads it there with
+fresh context. Every architectural claim traces to that section or carries an
+explicit "unsourced — judgment call" flag.
+
+Grounding that needs more than four angles (a large feature spanning several
+subsystems) runs as one read-only ultracode workflow instead of more researcher
+agents, writing its synthesis into the same section.
+
+## Step 3: Write the plan file
+`<slug>.md`, in this order:
+
+- **Context** — the problem, why now, the intended outcome.
+- **Approach** — what to build and why this over the alternatives, citing
+  Research.
+- **Files to create/modify** — exact paths with purpose, referencing the
+  patterns Step 2 found.
+- **Dependencies** — new packages, keys or services, version-pinned.
+- **Risks & mitigations** — what can go wrong, how it is detected, how it rolls
+  back.
+- **Success criteria** — testable assertions.
+- **Research** — the Step 2 summaries: codebase, docs/API, best practices.
+- **Tasks** — the task list, always last. Introduce it with a level-1 `# Tasks`
+  heading or a plain sentence: a `## Tasks` heading would be miscounted as a
+  task by `/cw:build`, which collects every `## Task <id>` block in the file.
+
+## Step 3b: The task list
+Derive it from "Files to create/modify" plus the approach; this is what
+`/cw:build` executes, so each block is precise and self-contained.
+
+The count is adaptive — one task for a trivial change, as many as the design
+implies for a large one. There is no target range: do not pad to a number or
+cap at one. Split so no two tasks own the same file; disjoint `files_owned` is
+what prevents conflicts and lets independent tasks run together. Each task maps
+to exactly one atomic Conventional commit.
+
+When the feature spans layers, order tasks as vertical slices —
+schema→API→UI→test for slice 1, then the same for slice 2 — rather than every
+schema task before any API task. Each slice ends at its own verification gate,
+and a failure there blocks only that slice's downstream tasks.
 
 ```
 ## Task <id>
 - scope: one-sentence boundary of what this task delivers
 - files_owned: [exact paths — disjoint across all tasks]
-- files_forbidden: [paths this task must NOT touch — other tasks' files_owned, plus anything explicitly out of scope]
+- files_forbidden: [other tasks' files_owned, plus anything out of scope]
 - depends_on: [task ids | none]
 - agent: implementer
-- model: sonnet | opus   # opus only if >5 files, long-horizon, or cross-cutting schema
-- risk: high | normal | trivial   # optional; feeds /build's tiered review depth (deep review for high, fast-path for trivial)
-- verification: exact command(s) + expected exit 0   # verification IS the acceptance contract (Proposal 4.2 acceptance: folded in deliberately) — this is what /build checks against ground truth, never narrative
-- commit: <type>(<scope>): <subject> | none (unversioned/external target — verification-only gates)   # ONE atomic Conventional Commit; the Co-Authored-By trailer is required unless commit is `none`
+- model: sonnet | opus   # opus for >5 files, long-horizon, or cross-cutting schema
+- risk: high | normal | trivial   # feeds the review depth /cw:build applies
+- verification: exact command(s), expected exit 0   # the acceptance contract, never narrative
+- commit: <type>(<scope>): <subject> | none   # `none` = unversioned/external target, verification-only
 ```
 
-(Spec-driven best practice: Pimzino/claude-code-spec-workflow, gotalab/cc-sdd; one
-atomic commit per task: Simon Willison agentic-git, MIT Missing Semester agentic-coding.)
-
-## Step 4: Convergence Review Loop (synchronous, no fixed stage count)
-
-Loop until convergence or the safety valve fires. Counter starts at 1.
-
-1. **Parallel fresh-context review** — spawn three subagents in the same turn, synchronously:
-   - **`design-reviewer`** — codebase/docs alignment. Pass it `<slug>-design-draft.md` and the three research files. It re-reads them fresh and returns a strict JSON verdict.
-   - **`direction-reviewer`** — end-goal alignment (*"is this plan aimed at the right outcome"*), orthogonal to design-reviewer's consistency/codebase-fit checks. Pass it the original `$ARGUMENTS`, `<slug>-design-draft.md`, and `<slug>-tasks.md`. Parse its strict JSON.
-   - **`reviewer`** (set `model` to `opus`) as a **completeness critic** — prompt it explicitly with "What is this plan missing? Do not re-check consistency or premise — the other two reviewers cover those. Find gaps: missing edge cases, missing tasks, missing rollback/observability, unstated assumptions." Pass it `<slug>-design-draft.md` and `<slug>-tasks.md`.
-
-   Each is a fresh instance by construction — never pass a prior iteration's findings into the next pass's reviewer prompt.
-
-2. **Adversarial verification of critical findings** — for every finding any of the three reviewers tags `critical`/`blocking`, verify it before acting:
-   - File:line claims — Read the cited file/line yourself (main thread) and confirm the finding accurately describes what's actually there.
-   - Citation claims (docs/best-practice) — check the finding against the relevant `<slug>-research-*.md` file; if the citation isn't backed by a research file, treat it as unverified.
-   - `direction-reviewer`'s `REDIRECT` verdict is always treated as critical for this pipeline: if its `recommended_reframe` cites concrete evidence (a conflicting requirement in `$ARGUMENTS` or a research file), it's verified and folded into the revision below; if it's a values/priority call that can't be file-verified, don't auto-resolve it — flag it for the Step 5 checkpoint as a human decision (a `REDIRECT` is a human decision, not an auto-fix), and it does not block convergence on its own.
-   - A finding that cannot be verified this way is **logged as an unverified risk** and carried to Step 5 as a note — it is NOT acted on and does NOT block convergence.
-
-3. **Revise from verified findings only** — in the main thread, update `<slug>-design-draft.md` (and `<slug>-tasks.md` if the change affects task boundaries) using only the verified critical/blocking findings. Minor findings are never actioned mid-loop — every reviewer's minor findings accumulate across iterations and are carried to Step 5 as notes regardless of verification status.
-
-4. **Re-review fresh** — the next iteration re-runs step 1 with brand-new reviewer instances against the revised draft; never reuse a prior iteration's reviewer context.
-
-**Exit condition**: an iteration whose review + verification pass produces **zero verified critical issues** → convergence reached. Finalize the design draft as-is and proceed to Step 5.
-
-**NO_VERDICT handling**: a reviewer that returns unparseable output or no verdict/findings at all is `NO_VERDICT`, not `NEEDS_WORK` — retry that one reviewer once, fresh. If it's still `NO_VERDICT`, escalate to the user immediately rather than burning further loop iterations on it.
-
-**Safety valve**: after 5 iterations without convergence, stop looping and escalate to the user with the full list of surviving (verified, unresolved) critical issues — do not silently finalize, and do not attempt a 6th iteration.
-
-## Step 5: Pre-Exit Summary + ExitPlanMode
-
-Present the final `<slug>-design-draft.md`, the Step 4 convergence result ([N] iterations
-run, `CONVERGED` with zero verified critical issues or `ESCALATED` after 5 iterations with
-the surviving verified critical issues listed, plus any unverified risks and accumulated
-minor notes), and the `<slug>-tasks.md` task count:
-
-> "Design + task plan ready. Review loop: [N] iteration(s) → [CONVERGED, zero verified
-> critical issues / ESCALATED after 5 iterations, M surviving critical issues]. Minor
-> notes: [count]. Unverified risks (logged, not acted on): [count]. Tasks: [K] tasks in
-> `<slug>-tasks.md`.
-> Approving here exits plan mode so I can write the artifact set into the project — it's
-> not the build decision, `/build` still is."
-
-Then call **`ExitPlanMode`**. This is the explicit mode transition described in Mode
-above.
-- If the user **rejects**, remain in plan mode and follow the pre-promotion path of the
-  Iteration Protocol below — unchanged from before this feature.
-- If the user **approves**, continue in the same turn into Step 6.
-
-## Step 6: Post-Approval Artifact Write (execute mode, same turn)
-
-Runs only after `ExitPlanMode` is approved. This is a short guarded window, not a general
-license to write anywhere — everything below is bounded by the sentinel and the routing
-rule.
-
-1. **Arm the sentinel**: `touch "/tmp/claude-design-active.$CLAUDE_CODE_SESSION_ID"` (this
-   is what `hooks/design-scope-guard.sh` checks for). If `$CLAUDE_CODE_SESSION_ID` is
-   empty, fall back to `touch /tmp/claude-design-active` and warn the user that session
-   isolation is inactive for this run.
-2. **Resolve the project root**: `ROOT=$(git rev-parse --show-toplevel 2>/dev/null)`.
-3. **Routing rule** — decide whether artifacts stay in the plans dir or promote into the
-   project:
-   - If `ROOT` equals `${CLAUDE_CONFIG_DIR:-$HOME/.claude}` (this repo IS the config
-     repo — a meta-tooling design), OR `git check-ignore -q "$ROOT/docs/plans/probe"`
-     reports that class of path as gitignored, the project doesn't want these files
-     tracked — **artifacts stay in the plans dir**, and the Step 7 checkpoint says so.
-     Always root-anchor the `check-ignore` probe with an absolute path (`git check-ignore
-     -q "$ROOT/docs/plans/probe"`), never a bare cwd-relative one — a cwd-relative probe
-     run from a subdirectory can false-positive. `/design`'s cwd is always inside the repo
-     (`$ROOT` comes from `git rev-parse --show-toplevel`), so the absolute-path form is
-     equivalent to a `-C "$ROOT"` form while also matching the `Bash(git check-ignore:*)`
-     grant, which is a literal prefix match and would not cover a leading `-C` flag.
-   - Otherwise, promote: `mkdir -p "$ROOT/docs/plans/<slug>"`.
-4. **Write the artifact set** (promotion path only) **with the `Write` tool — never
-   `cp`** — so the write goes through the design-scope-guard and protect-secrets rails
-   like every other artifact write in this skill:
-   - The two core files: `<slug>-design-draft.md` and `<slug>-tasks.md`.
-   - Every `<slug>-research-*.md` file present in the plans dir (a bounded glob on the
-     exact slug prefix — `login-research-*` cannot cross-match `login-flow-research-*` —
-     so legitimate extra research variants are captured without over-matching a
-     similarly-named design).
-5. **Self-check gate**: only stamp promotion if BOTH hold —
-   - the two core files exist in `$ROOT/docs/plans/<slug>/` and are non-empty, AND
-   - the count of `<slug>-research-*.md` files written into the project equals the count
-     of `<slug>-research-*.md` source files in the plans dir.
-   If the gate passes, stamp each **plans-dir** source draft (not the project copies) with
-   this as its first line:
-   `> PROMOTED to $ROOT/docs/plans/<slug>/ — the project copy is canonical.`
-   **A promoted project copy is all-or-nothing — present and complete, or absent.** If any
-   write fails, or the gate does not pass: report the failure, then remove the partial
-   project copy so no half-written set is left behind for `/build` to mistake for a
-   COMPLETE pair — `git clean -fd "$ROOT/docs/plans/<slug>"` **only when** `$ROOT` is
-   non-empty AND `<slug>` is non-empty AND `<slug>` matches `^[a-z0-9][a-z0-9-]*$` (reject
-   any slug containing `..`, `/`, spaces, or glob characters before running this
-   destructive command). `git clean -fd`, not `rm -rf`: the partial copy is untracked at
-   design time (`/build` is what commits it later), so `git clean` removes exactly the
-   untracked partial copy and, by construction, cannot delete a tracked file — a narrower
-   guarantee than `rm -rf` gives, at the cost of a `Bash(git clean:*)` grant instead of
-   widening to `Bash(rm -rf:*)`. This `git clean` is a Bash command, not a `Write`/`Edit` —
-   it is NOT confined by `design-scope-guard.sh` (which only gates `Write`/`Edit`), so the
-   charset check above is the real safety mechanism here, not the hook. Leave the plans dir
-   as the canonical copy and stamp nothing.
-6. **No repo at all** (`ROOT` empty): ask the user whether to run `git init -b main && git
-   commit --allow-empty -m "chore: initial commit"` so promotion has somewhere to land, or
-   to stay in the plans dir for this design.
-7. **Disarm the sentinel** before stopping: `rm -f "/tmp/claude-design-active.$CLAUDE_CODE_SESSION_ID"`
-   (or the unsuffixed fallback path if that's what was armed).
-
-## Step 7: Human Checkpoint (the one stop)
-
-This is the single STOP for the whole `/design` run — it comes after the write, not
-before it. Print the artifact directory path verbatim (`$ROOT/docs/plans/<slug>/` if
-promoted, otherwise the plans dir) and name the two files to open first:
-`<slug>-design-draft.md`, then `<slug>-tasks.md`. If `$ROOT` is under `$HOME/Documents/`,
-note that this location is phone-readable (e.g. via a synced Files app) — omit that note
-otherwise.
-
-> "Design + task plan written to `[path]`. Open `<slug>-design-draft.md` first, then
-> `<slug>-tasks.md`. Exiting plan mode above was provisional — `/build <slug>` is still
-> the real decision point. These files are untracked until `/build` commits them, so
-> avoid a bulk `git add .` in the meantime.
-> What would you like to adjust before I implement?"
-
-## Iteration Protocol (post-checkpoint human feedback)
-
-Two paths, depending on which checkpoint the feedback arrives at:
-
-**Pre-promotion** (feedback given when the user rejects at the Step 5 `ExitPlanMode`
-call) — nothing has been written to the project yet, so iterate exactly as before this
-feature, entirely on the plans-dir copies:
-1. For feedback that introduces a new unknown, spawn a `researcher` and update the relevant research file.
-2. Revise `<slug>-design-draft.md`.
-3. **Regenerate `<slug>-tasks.md`** (Step 3b) so it never lags an edited draft.
-4. Re-run Step 4 (the convergence review loop, including its `direction-reviewer` pass) on the revised draft + tasks.
-5. Return to Step 5 (present + `ExitPlanMode` again). A `REDIRECT` from the re-run is **folded into this single checkpoint** (Step 4 already surfaces it as a flagged human decision) — it does not create a second, separate stop. Repeat until the user approves at `ExitPlanMode`.
-
-**Post-promotion** (feedback given at the Step 7 checkpoint, after artifacts were written
-into the project) — ALL references re-point to the project copies: revisions, Step 3b
-regeneration, and the Step 4 re-review reviewer prompts all use
-`$ROOT/docs/plans/<slug>/<slug>-*.md` paths, never the plans dir. The plans-dir drafts are
-now inert bannered scratch (Step 6's `PROMOTED` stamp) — a re-review must never converge
-on them.
-1. Re-arm the sentinel for this revision turn (Step 6.1).
-2. Run steps 1–4 of the pre-promotion path above, but reading and writing
-   `$ROOT/docs/plans/<slug>/<slug>-*.md` instead of the plans dir.
-3. Present the revised checkpoint (Step 7) and STOP again; disarm the sentinel (Step 6.7)
-   before stopping. Repeat until the user says to proceed.
+## Step 4: Convergence review loop (synchronous)
+Counter starts at 1; loop until convergence or the safety valve fires.
+
+1. Spawn a fresh **`cw:design-reviewer`** on the plan file. Fresh context every
+   pass is the point — never feed a prior iteration's findings into the next
+   reviewer's prompt.
+2. **Verify every critical finding before acting on it.** A file:line claim:
+   read that file yourself and confirm it says what the finding says. A
+   citation claim: check it against the plan's Research section; unbacked means
+   unverified. A finding you cannot verify is logged as an unverified risk and
+   carried to Step 5 — not acted on, and not blocking convergence.
+3. Revise the plan (and the task list, when boundaries move) from the verified
+   critical findings only. Minor findings accumulate as notes for Step 5 and
+   are never actioned mid-loop.
+4. Re-review with a brand-new reviewer instance against the revised plan.
+
+**Exit**: an iteration producing zero verified critical findings has converged.
+**Unparseable reply**: a reviewer that returns no verdict, or one that cannot
+be parsed, is not a NEEDS_WORK — retry that reviewer once, fresh, then escalate
+rather than burning loop iterations.
+**Safety valve**: after 5 iterations without convergence, stop and escalate
+with the surviving verified critical findings listed. No sixth iteration, no
+silent finalisation.
+
+## Step 4b: Direction pass (once)
+After convergence, run **`cw:direction-reviewer`** once on the original
+`$ARGUMENTS` plus the finished plan. Its `REDIRECT` is a decision for the user,
+not an auto-fix: fold it in when its reframe cites concrete evidence, otherwise
+surface it at the checkpoint. It does not loop and does not block on its own.
+
+## Step 5: Summary, then `ExitPlanMode`
+Present the plan, the loop result ([N] iterations, converged or escalated with
+M surviving findings), the minor-note and unverified-risk counts, the direction
+verdict, and the task count. Then call `ExitPlanMode`, noting that approving
+there moves the file into the project and that `/cw:build` is still the real
+decision point. On rejection, stay in plan mode and follow the iteration
+protocol; on approval, continue straight into Step 6 without a new turn.
+
+## Step 6: Move the plan into the project
+1. `ROOT=$(git rev-parse --show-toplevel 2>/dev/null)`. Empty (not a repo) →
+   leave the file where plan mode put it, say so, and go to Step 7.
+2. `mkdir -p "$ROOT/docs/plans"`, then move the file to
+   `$ROOT/docs/plans/<slug>.md` — `git mv` when plan mode's copy is already
+   tracked, plain `mv` otherwise.
+3. `git -C "$ROOT" check-ignore -q docs/plans/<slug>.md`. If the destination is
+   ignored, print the fix by name rather than a bare warning:
+   > the design file is ignored by .gitignore; un-ignore docs/plans/<slug>.md before /cw:build
+
+## Step 7: Checkpoint (the one stop)
+Print the final path verbatim and stop:
+
+> "Plan written to `[path]`. `/cw:build <slug>` is the real decision point —
+> exiting plan mode above was provisional. The file is untracked until
+> `/cw:build` commits it, so avoid a bulk `git add .` in the meantime. What
+> would you like to adjust before I implement?"
+
+## Iteration protocol
+Feedback at either stop follows one path, against whichever copy of the plan
+exists then (plan mode's before Step 6, the project's after):
+
+1. Spawn a `cw:researcher` for any new unknown and update the Research section.
+2. Revise the plan, then regenerate the task list so it never lags the prose.
+3. Re-run Steps 4 and 4b on the revised plan.
+4. Return to the checkpoint you came from and stop again, until the user says
+   to proceed.
diff --git a/skills/google-workspace/SKILL.md b/skills/google-workspace/SKILL.md
new file mode 100644
index 0000000..4ed04b6
--- /dev/null
+++ b/skills/google-workspace/SKILL.md
@@ -0,0 +1,32 @@
+---
+name: google-workspace
+description: "Hard-won routes and dead ends for driving Google Workspace from Claude. Use when the user asks to export or upload a Google Doc, create Docs suggestions or comments from a docx, share a Drive file, or automate Google Workspace through the Drive/Docs MCP connector or the browser. Says which capabilities the connector genuinely has, which have no API at all, and the working workaround for each."
+---
+
+# Google Workspace — what actually works
+
+## Capability matrix (Drive/Docs MCP connector)
+| Need | MCP/API? | Working route |
+|---|---|---|
+| Read Doc text + comments | YES — `read_file_content` (includeComments) | direct |
+| Search/list/rename/move files | YES | direct |
+| Export a Doc (docx/text) | YES but base64-through-context (~25k tokens/100KB) | prefer browser: navigate to `docs.google.com/document/d/<ID>/export?format=docx` → lands in ~/Downloads, zero context cost |
+| Upload a binary (docx etc.) | **NO** — MCP `create_file` caps ~8KB binaries, streams tokens | see "Upload routes" below |
+| Create Google Docs SUGGESTIONS | **NO API EXISTS** (Docs API SUGGEST mode is Workspace-preview-gated; silently applies edits if unenrolled) | docx with `w:ins`/`w:del` tracked changes → upload with convert → suggestions appear natively |
+| Create Docs COMMENTS | **NO MCP tool** (Drive API has comments.create but connector doesn't expose it) | put `w:comment` in the docx (see caveats) or add manually in UI |
+| Share a file externally | **NO, two walls**: auto-mode classifier blocks it AND, even with an allow rule for `mcp__claude_ai_Google_Drive__share_file`, Google returns "The caller does not have permission" — the connector's OAuth grant lacks sharing rights | the user shares in the UI (fastest) or browser automation |
+
+## Upload routes for binaries, in order of preference
+1. **The user at a computer**: OAuth Playground token (tick FULL-URL scopes `https://www.googleapis.com/auth/drive.file` — bare "drive" → invalid_scope; add `.../drive.readonly` if downloading too) + curl multipart with metadata `mimeType: application/vnd.google-apps.document` → converts docx→Doc in seconds.
+2. **Browser automation (Claude-in-Chrome)**: Docs home → "Open file picker" → Upload tab. The picker is an IFRAME opaque to the accessibility tree — drive it with javascript_tool only. Activate the Upload tab by clicking the tab BUTTON found via `contentDocument` traversal; an `input[type=file]` then mounts. Inject the file via `new File(...)` + `DataTransfer` + `input.files = dt.files` + `change` event. Get bytes in via base64 chunks pushed to `window.__b64` across calls (≤~23KB per call). If the account has "Convert uploads" on, the docx converts to a native Doc automatically.
+3. Drive-for-desktop sync folder (`~/Library/CloudStorage/GoogleDrive-*`) — only if installed.
+
+## Landmines (each cost real time)
+- **fetch to 127.0.0.1/localhost from a Google page**: Chrome Private-Network-Access silently hangs it; the CDP evaluate times out at 45s — but the async page code may still complete later. Never rely on it; never assume it failed either — check ground truth (Drive search) before retrying.
+- **javascript_tool results containing URLs/query strings get classifier-redacted** ("[BLOCKED]") — return only hostnames, counts, booleans.
+- **Native macOS file dialogs are unreachable**: osascript keystrokes need Accessibility permission the host app doesn't have (reading process names works; sending keys doesn't). If a native dialog opens, only a human or a Chrome restart (`osascript -e 'tell app "Google Chrome" to quit'` — app-level scripting IS allowed) clears it.
+- **docx→Docs comment conversion**: comments anchored to text INSIDE `w:ins` runs in TABLE CELLS are dropped; comments elsewhere survive but Google RE-ANCHORS by first text match of the quoted span — anchor on text unique in the whole doc or it lands on the wrong occurrence. Fix comments in the UI after import, never by re-import.
+- **Google Docs docx exports normalize U+200B away**; typographic apostrophes (U+2019) survive. Byte-match anchors against the actual export, not assumptions.
+- **Suggestion verification without the UI**: a Doc's text export shows pending suggestions as old-text immediately followed by new-text (deletions retained + insertions included). Old+new adjacent = pending suggestions; only-new = silently applied (bad); only-old = import failed.
+- **Tracked-changes docx build**: string surgery on document.xml works (proven twice); split runs that mix `w:t` with `w:br` into atom-runs first; `<w:rPr/>` self-closed needs its own regex branch; verify by reconstructing reject-all text (must equal original exactly) and accept-all text (must contain every insert).
+- Gmail MCP: good for search/read/drafts; not an attachment transport for binaries.
diff --git a/skills/search/SKILL.md b/skills/search/SKILL.md
index fd4a06a..b3c7871 100644
--- a/skills/search/SKILL.md
+++ b/skills/search/SKILL.md
@@ -1,104 +1,83 @@
 ---
 name: search
-description: "Multi-source web research to confirm approaches and find best practices. Use when the user says /search, asks to 'research this', 'look this up', 'confirm this approach', 'find best practices for', 'what's the current consensus on', or needs to cross-reference sources. Covers any domain: coding, business, finance, legal, product, UX, AI/ML, marketing, growth, and more. Trigger proactively when a question would clearly benefit from current web data rather than training knowledge alone."
-argument-hint: [--quick] <query>
+description: "Multi-source web research to confirm approaches and find best practices. Use when the user says /cw:search, asks to 'research this', 'look this up', 'confirm this approach', 'find best practices for', 'what's the current consensus on', or needs to cross-reference sources. Covers any domain: coding, business, finance, legal, product, UX, AI/ML, marketing, growth. Trigger proactively when a question would clearly benefit from current web data rather than training knowledge alone."
+argument-hint: "[--quick | --deep] <query>"
 ---
 
 # Multi-Source Web Research
 
-Research any topic by cross-referencing multiple search sources with varied angles. Produce structured, citation-backed findings with a confidence assessment.
+Cross-reference several search sources with deliberately different angles, then
+produce structured, citation-backed findings with a confidence assessment.
 
 ## Arguments
-
 The user invoked this with: $ARGUMENTS
 
-Parse the arguments:
-- If `$ARGUMENTS` starts with `--quick`, activate **quick mode** and treat the rest as the query.
-- If `$ARGUMENTS` starts with `--deep`, this skill has no separate deep-research mode — degrade gracefully to **default mode** (the standard 3-angle search below) using the rest of the text as the query.
-- Otherwise, use **default mode** with the full text as the query.
-
-## Step 1: Detect available search sources
-
-Check which MCP tools are available in this session by looking for these specific tools:
-
-- **Context7**: Tools `mcp__context7__resolve-library-id` and `mcp__context7__query-docs` — use for coding documentation lookups (version-specific official docs)
-- **Exa**: Tool `mcp__exa__web_search_exa` (primary), `mcp__exa__crawling_exa` (for deep fetching) — use for semantic/conceptual research queries (finds related content by meaning, not just keywords)
-- **WebSearch**: Built-in, always available as baseline for general-purpose searches
-
-If an MCP tool is unavailable, fall back to WebSearch for that angle. Never error out due to missing MCPs.
-
-## Error Detection & Fallback Rules
-
-- If any MCP tool call (Exa, Context7) returns an error or empty result, retry ONCE with a simplified query before falling back to WebSearch.
-- If the retry also fails, fall back to WebSearch for that angle and report inline: "Note: [Exa/Context7] was unavailable after retry, fell back to WebSearch."
-- Never silently swallow errors. If all 3 angles complete but one returned nothing useful, note it in the output.
-
-Note: Time-based timeouts (e.g., "fall back after 15s") are NOT enforceable at the skill level — MCP timeouts are a platform concern.
-
-## Step 2: Detect domain(s)
-
-Auto-detect from query keywords. Domains can overlap — a query may span multiple:
-
-- **Coding**: library/framework names, architecture patterns, errors, APIs, debugging, testing
-- **AI/ML**: model names, training, inference, papers, prompts, agents, embeddings, fine-tuning
-- **Business/Strategy**: market sizing, pricing, GTM, competition, fundraising, positioning
-- **Finance/Legal**: tax, accounting, incorporation, compliance, equity, SAFE, cap table, revenue
-- **Product/UX**: design patterns, user research, conversion, analytics, usability, wireframes
-- **Marketing/Growth**: SEO, content strategy, paid ads, viral loops, community, acquisition, retention
-- **General**: anything that doesn't clearly fit the above
-
-## Step 3: Execute searches
+- `--quick` → quick mode; the rest is the query.
+- `--deep` → hand off to the bundled `/deep-research` skill, which runs a much
+  wider multi-agent sweep. It needs dynamic workflows enabled; if that is
+  unavailable, say so and fall back to default mode here.
+- otherwise → default mode with the whole text as the query.
+
+## Step 1: Source detection
+Check which tools this session actually has:
+
+- **Context7** — `mcp__context7__resolve-library-id`, `mcp__context7__query-docs`:
+  version-specific official docs for library and framework questions.
+- **Exa** — `mcp__exa__web_search_exa` (primary), `mcp__exa__crawling_exa` (deep
+  fetch): semantic research that finds related material by meaning.
+- **WebSearch** — built in, always available, the baseline for everything else.
+
+Source detection never hard-fails: a missing MCP server degrades that angle to
+WebSearch.
+
+### Fallback rules
+- An MCP call that errors or returns nothing: retry once with a simplified
+  query, then fall back to WebSearch for that angle and say so inline — "Note:
+  Exa was unavailable after retry, fell back to WebSearch."
+- Do not swallow errors silently. If all angles completed but one returned
+  nothing useful, note it in the output.
+- Time-based timeouts are not enforceable from a skill; MCP timeouts are a
+  platform concern.
+
+## Step 2: Detect the domain(s)
+Auto-detect from the query; domains overlap freely.
+
+- **Coding** — libraries, frameworks, architecture patterns, errors, APIs, tests
+- **AI/ML** — models, training, inference, papers, prompts, agents, embeddings
+- **Business/strategy** — market sizing, pricing, GTM, competition, fundraising
+- **Finance/legal** — tax, accounting, incorporation, compliance, equity, SAFEs
+- **Product/UX** — design patterns, user research, conversion, analytics
+- **Marketing/growth** — SEO, content, paid ads, community, acquisition
+- **General** — anything else
+
+## Step 3: Search
 
 ### Quick mode (`--quick`)
-
-Single-angle fast lookup. No parallel searches, no WebFetch.
-
-1. **Domain check**: If the query is coding-domain (library, framework, API, error), use Context7 as the single source (faster, more precise for docs). Otherwise, use WebSearch with "[topic] [current year]".
-2. Return a 2-3 bullet summary with source links.
-3. Format:
-
-```
-## [Query]
-
-### Quick Answer
-- [2-3 bullets with citations]
-
-### Sources
-- [Title](URL) — description
-```
-
-### Default mode
-
-Run 3 searches IN PARALLEL, each with a meaningfully different angle and query formulation:
-
-**Angle 1 — Authoritative/official**
-- Goal: Find the canonical, institutional, or official perspective
-- Coding domain: Use Context7 if available (fetches version-specific official docs directly), otherwise WebSearch targeting official docs
-- Other domains: Use WebSearch targeting authoritative sources
-- Query style: "[topic] official documentation" or "[topic] methodology definition"
-
-**Angle 2 — Practitioner/community**
-- Goal: Real-world experience, case studies, lessons from practitioners
-- Use WebSearch with current year appended for freshness
-- Query style: "[topic] best practices real world experience [current year]"
-
-**Angle 3 — Contrarian/risk**
-- Goal: Find pitfalls, gotchas, failures, critical viewpoints
-- Use Exa if available (semantic search finds conceptually related warnings/critiques), otherwise WebSearch
-- Query style: "[topic] pitfalls common mistakes failure" or "why not to [topic]"
-
-Each query MUST be substantively different — not three rephrasings of the same search.
-
-After searches complete, use WebFetch on the 2-3 most authoritative URLs:
-- Prefer primary sources over aggregators
-- Prefer recent content over old
-- Diversify: don't fetch 3 pages from the same domain
-- Skip WebFetch if the search snippet already provides sufficient detail
+Single-angle lookup, no parallel searches, no WebFetch. Coding-domain query →
+Context7 as the single source; otherwise WebSearch with "[topic] [current
+year]". Return 2–3 bullets with source links under `### Quick Answer`, then
+`### Sources`.
+
+### Default mode — the three-angle sweep
+Run three searches in parallel, each a substantively different query, not three
+rephrasings of one.
+
+1. **Authoritative/official** — the canonical or institutional view. Coding
+   domain: Context7 when available, else WebSearch aimed at official docs.
+   Query style: "[topic] official documentation", "[topic] methodology".
+2. **Practitioner/community** — real-world experience, case studies, lessons.
+   WebSearch with the current year appended. Query style: "[topic] best
+   practices real world experience [current year]".
+3. **Contrarian/risk** — pitfalls, gotchas, failures, critiques. Exa when
+   available, else WebSearch. Query style: "[topic] pitfalls common mistakes",
+   "why not to [topic]".
+
+Then WebFetch the two or three most authoritative URLs: primary sources over
+aggregators, recent over old, and diversify domains. Skip the fetch when the
+search snippet already carries enough detail.
 
 ## Step 4: Output
 
-### Default mode format
-
 ```
 ## [Query]
 
@@ -106,24 +85,24 @@ After searches complete, use WebFetch on the 2-3 most authoritative URLs:
 - [3-5 cross-referenced bullets, each citing at least one source]
 
 ### Watch Out For
-- [Gotchas, deprecations, version-specific issues, contrarian views found in Angle 3]
+- [gotchas, deprecations, version-specific issues, contrarian findings]
 
 ### Confidence: [High/Medium/Low]
-[One-line justification]
+[one-line justification]
 
 ### Sources
 - [Title](URL) — one-line description
 ```
 
 ## Quality rules
-
-- Every finding must cite at least one source — no unsourced claims.
-- If sources conflict, present both sides explicitly. Do not silently pick one.
-- Flag if all sources are older than 1 year for time-sensitive topics.
-- Always include the current year in at least one search query per angle for freshness.
-- If a section has no findings, include it with "No data found for this angle" rather than omitting it. This makes output structure predictable for the user.
-- If the same URL appears in results from multiple angles, cite it once in Key Findings and note which angles it satisfied (e.g., "[source] — confirmed by both authoritative and practitioner angles").
-- Confidence levels:
-  - **High**: 3+ independent sources agree, sources are recent and authoritative
-  - **Medium**: 2 sources agree, or sources are recent but limited in number
-  - **Low**: Single source only, sources are outdated, or sources actively contradict each other
+- Every finding cites at least one source; no unsourced claims.
+- Conflicting sources are presented as a conflict, not silently resolved.
+- Flag it when every source is over a year old on a time-sensitive topic.
+- Put the current year in at least one query per angle.
+- A section with no findings still appears, marked "No data found for this
+  angle", so the shape of the output is predictable.
+- A URL that surfaced in several angles is cited once, noting which angles it
+  satisfied.
+- Confidence: **High** = 3+ independent, recent, authoritative sources agree;
+  **Medium** = 2 agree, or recent but few; **Low** = single, outdated, or
+  contradictory sources.
diff --git a/skills/ship/SKILL.md b/skills/ship/SKILL.md
index d2210e5..a9cc132 100644
--- a/skills/ship/SKILL.md
+++ b/skills/ship/SKILL.md
@@ -1,153 +1,118 @@
 ---
 name: ship
-description: "Ship current changes: ensure commits are clean, push branch, create PR. Use when the user says /ship, 'push this', 'create a PR', or 'ship it'. Handles final commit cleanup, branch push, PR creation with structured body, and optional docs update."
+description: "Verify the commit series, run the quality gate, push the branch and open the PR. Use when the user says /cw:ship, 'push this', 'create a PR', or 'ship it'."
 disable-model-invocation: true
-argument-hint: [optional PR title]
+argument-hint: "[optional PR title]"
 allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Edit
+  - Write
   - Bash(git:*)
   - Bash(gh:*)
+  - Bash(bash:*)
+  - Bash(npm:*)
   - Bash(python:*)
   - Bash(pytest:*)
-  - Bash(npm:*)
   - Bash(xcodebuild:*)
   - Bash(make:*)
-  - Read
-  - Write
-  - Edit
-  - Glob
-  - Grep
-  - Agent
 ---
 
 # Ship Changes
 
-Push and create a PR for the current feature branch.
-
-**Mode:** `/ship` runs in **execute mode**. It assumes `/build` already produced an
-atomic, per-task Conventional commit series — `/ship` *verifies* that series, it does
-not author it.
+Push the current feature branch and open its PR. Runs in execute mode, and
+assumes `/cw:build` already produced the commit series — this skill verifies
+that series, it does not author it.
 
 ## Input
 $ARGUMENTS
 
-## Step 1: Pre-flight Checks
-1. Run `git status` — verify we are NOT on main/master (refuse if so)
-2. Run `git diff --cached` and `git diff` — check for uncommitted changes
-3. Run `git log --oneline main..HEAD` — review commits on this branch
-4. Verify no staged files match: .env*, *credentials*, *secret*, Config.swift
-
-## Step 2: Verify the Commit Series
-`git log --oneline main..HEAD`. The series must **already** be one atomic Conventional
-commit per task, each with the `Co-Authored-By` trailer (produced by `/build`'s
-implementers).
-- Any orchestrator-authored `docs(<slug>): add design + research artifacts` commit
-  (produced by `/build` Phase 0 step 4's promotion of the project's design docs) is an
-  **expected series member** — it does not count against one-commit-per-task, and it does
-  not have to be the leading commit; a later refresh of the artifacts can land anywhere in
-  the range. Do not flag it as a stray or extra commit.
-- **Do NOT create a catch-all "final commit"** and do NOT squash the per-task series.
-- If there are stray **uncommitted** changes, **STOP and report** — that means a `/build`
-  task did not self-commit; do not paper over it with a squash commit. The fix is to
-  finish/redo that task in `/build`, not to absorb it here.
-  - **Targeted exception**: untracked files under `docs/plans/<slug>/` with **no**
-    `docs(<slug>):` commit anywhere in the series is the documented ceiling state for a
-    `/build` that couldn't commit the design artifacts (e.g. the root-anchored
-    trackability pre-check skipped them, or the commit itself failed — see `/build` Phase
-    0 step 4). This is not a silently-skipped task commit — offer to commit the artifacts
-    now (`docs(<slug>): add design + research artifacts`, same trailer) rather than
-    hard-stopping the ship over it.
-- Verify (do not rewrite) format and atomicity. If messages are messy, *suggest* an
-  interactive rebase but never force one.
-
-## Step 2.5: Quality Gate (project-agnostic)
-
-`/ship` is a global skill — never hardcode a project's test command. Detect the gate in this precedence and run exactly what you find:
-
-1. **`.claude/rules/pr-merge-policy.md`** (authoritative). If it exists, extract the command(s) under its "mergeable when…" / pre-PR checklist and run those. This wins over CLAUDE.md when both define a gate.
-2. **Project `CLAUDE.md`** — a stated test/verify command (e.g. a "Tests" section). Use it only if step 1 found nothing.
-3. **Convention fallback** (only if 1 and 2 are silent):
+## Step 1: Pre-flight
+1. `git status` — refuse to run on `main` or `master`.
+2. `git diff --cached` and `git diff` — look for uncommitted work.
+3. `git log --oneline main..HEAD` — the commits this PR will carry.
+4. Confirm no staged file matches `.env*`, `*credentials*`, `*secret*`, or
+   `Config.swift`. A match stops the run.
+
+## Step 2: Verify the commit series
+Against the plan's task list (`docs/plans/<slug>.md`):
+
+- Each task's `commit:` subject appears exactly once, in Conventional format,
+  carrying the trailer the workflow rules define. Tasks marked `commit: none`
+  contribute nothing here — that is expected, not a gap.
+- A `docs(<slug>): design` commit from `/cw:build` is an expected member of the
+  series and does not have to lead it.
+- No catch-all or squashed commit. Do not create one, and do not rewrite the
+  series to tidy it; a messy message earns a suggestion to rebase, not a forced
+  rebase.
+- Stray **uncommitted** changes mean a task did not self-commit: stop and
+  report. The fix is to finish that task in `/cw:build`, not to absorb it here.
+  The one exception is an uncommitted design file with no `docs(<slug>):`
+  commit anywhere in the range — offer to commit it now as `docs(<slug>):
+  design` with the same trailer.
+
+## Step 3: Quality gate
+This skill is project-agnostic; detect the gate in this precedence and run
+exactly what you find.
+
+1. `tests/run.sh` present → `bash tests/run.sh all`.
+2. A rules file that states the pre-PR checklist (for example
+   `rules/pr-merge-policy.md`) → run the command(s) it names.
+3. Project `CLAUDE.md` — a stated test or verify command. Only if 1 and 2 are
+   silent.
+4. Convention fallback, only if nothing above matched:
    - `pyproject.toml` or `tests/` present → `python -m pytest -q`
    - `package.json` with a `test` script → `npm test`
-   - `*.xcodeproj`/`*.xcworkspace` present → `xcodebuild test`
-4. **Nothing detected** → skip with a one-line notice: "No project test gate detected — relying on the human checkpoint."
-
-If a detected gate runs and fails, **abort `/ship` before pushing** and show the failing output. Do not push or open a PR on a red gate. (Exception already in policy: docs-only changes may bypass — if every staged file is under `docs/`, `README`, or `CLAUDE.md`, note it and skip the gate.)
-
-**PR-timing rule:** a PR is opened **only after the feature/milestone is fully built AND
-this quality gate has passed**. Never open a PR mid-build or on a red gate.
-
-## Step 3: Update Documentation (if applicable)
-This step updates **product docs** only — what the code does / how to use it. It is
-deliberately distinct from `/compound`, which captures **process rules** into
-CLAUDE.md / `.claude/rules` (offered separately in Step 5, never committed into this PR).
-
-Check if any of these need updating based on the changes:
-- Project README.md (new features, changed setup steps)
-- ARCHITECTURE.md (new services, changed data flow)
-- CHANGELOG.md (if project has one)
-
-If updates are needed, make them in a `docs:` commit (one atomic commit, co-author
-trailer — same series discipline as the rest).
-
-## Step 3.5: Optional Pre-PR Review Panel (risk: high milestones)
-
-If the milestone/design doc is tagged `risk: high`, **before opening the PR** offer the user
-a 3-lens review panel — this is an **offer, not a mandatory gate**:
-
-> "This milestone is tagged `risk: high`. Want me to run a 3-lens review panel
-> (correctness / security / conventions) before opening the PR?"
-
-If the user accepts:
-1. Launch one Sonnet subagent per lens (correctness, security, conventions), each
-   reviewing the same diff (`git diff main..HEAD`) independently.
-2. **Evidence-gated findings only** — each lens must cite a `file:line` or a failing
-   command output to support a finding. Drop any finding that lacks one; do not report
-   vague or unsubstantiated concerns.
-3. Summarize surviving findings to the user before proceeding to Step 4. Fixes are
-   the user's call — `/ship` does not auto-apply panel findings.
-
-If the user declines, or the milestone isn't tagged `risk: high`, skip this step entirely
-and proceed straight to Step 4.
-
-## Step 4: Push & Create PR
-1. Push branch: `git push -u origin HEAD`
-2. Create PR via `gh pr create`:
-   - Title: conventional format, under 70 chars. Use $ARGUMENTS if provided.
-   - Body format:
-     ```
-     ## Summary
-     - [bullet points of what changed and why]
-
-     ## Test Plan
-     - [ ] [manual test steps]
-     - [ ] [automated test results]
-
-     ## Design Reference
-     [link to design doc or plan file if applicable]
-     ```
-     For **Design Reference**, point to the committed project copy —
-     `docs/plans/<slug>/<slug>-design-draft.md` (canonical once `/build` Phase 0 step 4
-     has committed it as part of the feature branch) — falling back to the legacy
-     `~/.claude/plans/<slug>-design-draft.md` only when no project copy was ever promoted
-     (e.g. a plans-dir-resolved build with no project docs to commit).
-3. Report PR URL to the user
-
-## Step 5: Offer `/compound` (HITL chain)
-After reporting the PR URL, ask once:
-
-> "Want to capture reusable lessons from this into the project's CLAUDE.md /
-> .claude/rules? I can run `/compound` now — it proposes edits for your approval and
-> does **not** commit them into this PR."
-
-If the user says yes, hand off to the `/compound` skill. `/compound` stays a separate,
-user-driven skill: it proposes process-rule edits, applies only what the user approves,
-and does not commit (so workflow-rule changes never land inside this feature PR). If
-the user declines, end here.
-
-## Safety Rules
-- NEVER push to main/master
-- NEVER force push
-- NEVER commit files matching: .env*, *credentials*, *secret*, Config.swift
-- NEVER create empty commits
-- NEVER squash or rewrite the per-task atomic commit series — `/ship` verifies it, `/build` authors it
-- NEVER open a PR before the quality gate passes or before the feature/milestone is fully built
+   - `*.xcodeproj` or `*.xcworkspace` present → `xcodebuild test`
+5. Nothing detected → skip with one line: "No project test gate detected —
+   relying on the human checkpoint."
+
+A detected gate that fails aborts the run before any push; show the failing
+output. A PR is opened only after the feature or milestone is fully built and
+this gate has passed — not mid-build, and not on a red gate. Documented
+exception: if every changed file is under `docs/`, `README`, or a `CLAUDE.md`,
+note it and skip the gate.
+
+## Step 4: Product docs (if applicable)
+This step covers product docs only — what the code does and how to use it.
+Process-rule capture is `/cw:compound`'s job, offered separately in Step 6.
+
+Check whether the change makes any of these stale: the project README (new
+features, changed setup), `ARCHITECTURE.md` (new services, changed data flow),
+`CHANGELOG.md`. If so, update them in one atomic `docs:` commit with the same
+trailer as the rest of the series.
+
+## Step 5: Push and open the PR
+1. `git push -u origin HEAD`.
+2. `gh pr create` with a Conventional title under 70 characters ($ARGUMENTS
+   when given) and this body:
+   ```
+   ## Summary
+   - [what changed and why]
+
+   ## Test Plan
+   - [ ] [manual test steps]
+   - [ ] [automated test results]
+
+   ## Design Reference
+   docs/plans/<slug>.md
+   ```
+3. Report the PR URL.
+
+## Step 6: Offer `/cw:compound`
+Ask once, after the URL:
+
+> "Want to capture reusable lessons from this into the project's CLAUDE.md or
+> rules files? `/cw:compound` proposes edits for your approval and keeps them
+> out of this PR."
+
+Hand off if the user agrees; otherwise end here.
+
+## Safety rules
+- Do not push directly to main or master, and do not force-push any branch.
+  Work reaches the default branch through this PR.
+- Do not commit a file matching `.env*`, `*credentials*`, `*secret*`, or
+  `Config.swift`, and do not create empty commits.
+- Do not squash or rewrite the per-task commit series — this skill verifies it,
+  `/cw:build` authors it.
diff --git a/tests/fixtures/two-task-plan.md b/tests/fixtures/two-task-plan.md
new file mode 100644
index 0000000..37841d7
--- /dev/null
+++ b/tests/fixtures/two-task-plan.md
@@ -0,0 +1,25 @@
+# Two-Task Fixture Plan
+
+A minimal plan file used by the load test: two independent tasks, each creating one file at the repo root, listed below.
+
+## Task T1
+- scope: Create `a.txt` at the repo root with a single placeholder line.
+- files_owned: [a.txt]
+- files_forbidden: [b.txt]
+- depends_on: none
+- agent: implementer
+- model: sonnet
+- risk: trivial
+- verification: `test -f a.txt`
+- commit: feat: add a
+
+## Task T2
+- scope: Create `b.txt` at the repo root with a single placeholder line.
+- files_owned: [b.txt]
+- files_forbidden: [a.txt]
+- depends_on: none
+- agent: implementer
+- model: sonnet
+- risk: trivial
+- verification: `test -f b.txt`
+- commit: feat: add b

From ddccf564ca9b35045a7d9105ef7341f8d13c38b0 Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Wed, 16 Sep 2026 18:36:07 +0100
Subject: [PATCH 07/24] docs: plugin install story, project CLAUDE.md and lean
 example settings

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CLAUDE.md               |  57 +----
 README.md               | 537 ++++++++++++++--------------------------
 WORKFLOW.md             | 416 ++++++++++---------------------
 settings.example.json   | 105 ++------
 tests/settings-keys.txt | 145 +++++++++++
 5 files changed, 497 insertions(+), 763 deletions(-)
 create mode 100644 tests/settings-keys.txt

diff --git a/CLAUDE.md b/CLAUDE.md
index f475e9a..80d5e7e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,48 +1,17 @@
-# Global Development Environment Rules
+# claude-code-setup
 
-This is a template `~/.claude/CLAUDE.md`. It is always-on advisory context for
-every project Claude Code touches. Sections marked "example — replace with
-your own" are personal-preference blocks you should adapt or delete; the
-`Workflow Rules` section is the transferable system this repo ships (see
-`WORKFLOW.md`) and is meant to be kept largely as-is.
+This repo is the Claude Code plugin `cw`: skills, agents, hooks, and rules for
+a design -> build -> ship workflow.
 
-## Identity (example — replace with your own)
-PM-turned-engineer. Quality and learning over speed. Always explain WHY behind architectural decisions, not just WHAT.
+Tests: bash tests/run.sh all
 
-<!-- BEGIN claude-code-setup workflow-rules v1 -->
-## Workflow Rules
-- Never push directly to main/master. Feature branches only.
-- Conventional Commits: feat:, fix:, refactor:, docs:, chore:, test:
-- Co-author line on every commit:
+## Conventions
+- Conventional Commits: feat:, fix:, refactor:, docs:, chore:, test:.
+- Every commit ends with:
   Co-Authored-By: Claude <noreply@anthropic.com>
-- No implementation without an approved design. If uncertain, ask first.
-- Two human checkpoints are non-negotiable: after design, before PR.
-- Each task maps to exactly one atomic Conventional Commit made by the implementer that did the task, or `commit: none` for unversioned/external targets (verification-only gates, no commit). `/ship` verifies the series; it never creates a catch-all or squashed commit.
-- A PR is opened only after the feature/milestone is fully built AND the quality gate has passed. No PR on a red gate; no PR mid-build.
-- Mode transitions: `/design` runs in plan mode; on plan approval it writes the artifact set to `<project>/docs/plans/<slug>/` (project copy canonical; plans-dir drafts banner-stamped; plans dir for meta-tooling/gitignored-docs work; no-repo case prompts to `git init` or stay in the plans dir); the post-design checkpoint precedes `/build`; `/build` commits the set as a scoped `docs(<slug>):` commit on the feature branch (not necessarily the leading commit in the series); `/build` and `/ship` run in execute mode.
-- `/ship` ends by offering `/compound`. Process-rule edits (CLAUDE.md, `.claude/rules`) are never committed into the feature PR.
-- Model routing and workflow usage follow ~/.claude/rules/orchestration.md.
-
-## Research-First Design
-- Before making architecture decisions, check official docs (use context7) and search for best practices (use exa/WebSearch).
-- Flag unsourced decisions explicitly: "Note: this approach is unsourced — my judgment call."
-- Prefer boring, proven patterns over novel ones unless there's a clear reason.
-
-## Context Hygiene
-- Use subagents for tasks whose output would bloat the main context (exploration, review, large diffs).
-- Suggest /clear between unrelated tasks.
-- For large features: suggest one session per phase.
-<!-- END claude-code-setup workflow-rules v1 -->
-
-## Stack Preferences (example — replace with your own; used only when a project's own CLAUDE.md is silent)
-- iOS: SwiftUI, async/await, no completion handlers, // MARK: sections
-- Python: type hints, Pydantic models, pytest, functions under 50 lines
-- Web: Next.js App Router, TypeScript strict mode
-- All: graceful error handling, no over-engineering
-
-## MCP Servers (OPTIONAL)
-The workflow degrades gracefully without these — see `skills/search/SKILL.md`'s
-fallback rules. Install docs: [context7](https://github.com/upstash/context7),
-[exa](https://github.com/exa-labs/exa-mcp-server).
-- context7: Library/framework docs. Use BEFORE writing code against any API.
-- exa: Semantic web search. Use for research, competitive analysis, best practices.
+- Design docs: a single-file plan at `docs/plans/<slug>.md` is tracked by
+  default. A folder-style artifact set needs both `!docs/plans/<slug>/` and
+  `!docs/plans/<slug>/**` added to `.gitignore` before `/cw:build` runs
+  against it.
+- Feature branches only; work reaches the default branch through a pull
+  request, opened only after the quality gate passes.
diff --git a/README.md b/README.md
index 7cb6bab..0cee75c 100644
--- a/README.md
+++ b/README.md
@@ -1,372 +1,217 @@
-# Claude Code Setup
-
-A user-level `~/.claude` configuration for [Claude Code](https://claude.com/claude-code):
-a `/design` → `/build` → `/ship` agentic workflow, six specialized subagents,
-model-routing rules, and a small set of hooks that turn advisory conventions into
-enforced ones. This is a sanitized export of a daily-driver setup, offered as a
-clone-and-use template — installed via a repo-scoped `/setup` skill (see
-[Quick Start](#6-quick-start-clone-and-use)) that installs and merges everything
-with a diff and your explicit consent, or, if you'd rather skip the
-conversational flow, [four scripts](#7-standalone-install-no-llm-run-the-scripts-directly)
-you can run by hand.
-
-## 1. Why this exists
-
-The cost model behind this setup is simple: **research and review are cheap;
-redoing finished work is expensive.** A wrong architectural assumption caught in
-`/design` costs a few minutes of subagent research. The same assumption caught
-after `/build` has already written code costs a revert, a re-plan, and a second
-implementation pass. Every non-negotiable rule in `WORKFLOW.md` — the two human
-checkpoints, the research-before-code sequencing, the review loop that verifies
-findings before acting on them — exists to keep mistakes cheap by catching them
-as early as possible.
-
-The other half of the cost model is context-window economics. A single Claude
-Code session has a finite context window, and research, exploration, and code
-review all produce far more raw tokens than anyone needs to actually read.
-Delegating that work to subagents — `researcher`, `Explore`, `reviewer` — keeps
-only their ~500-1K token *summaries* in the main thread, while the 10-50K tokens
-of raw search results, file contents, and diffs stay contained in the subagent
-that produced them. A full `/design` → `/build` → `/ship` cycle costs roughly
-5-10K tokens in the main context; doing the same research and review inline
-would cost 50K+ and degrade quality as the window fills.
-
-## 2. The workflow
+# cw — a Claude Code workflow plugin
 
+This repo *is* the Claude Code plugin `cw`: six skills, five agents, three
+hooks, two rule files, one test runner, and CI. It implements a
+`/cw:design` -> `/cw:build` -> `/cw:ship` pipeline — research-grounded
+planning, delegated implementation with one atomic commit per task, and a
+verified, gated release — plus `/cw:compound` to feed lessons back into your
+own project's rules. See `WORKFLOW.md` for the full pipeline narrative and
+`rules/orchestration.md` for the model-routing table.
+
+## Requirements
+
+- **Claude Code >= 2.1.269** — the version this plugin was built and tested
+  against (plugin agent-frontmatter parsing, `claude plugin eval`).
+- **git** — for the workflow's own commits and branch checks.
+- **jq** — used by every hook. Without it, `protect-branches.sh` and
+  `protect-secrets.sh` each print a warning to stderr and stand down (exit 0,
+  no enforcement) rather than block your session.
+- **A session in auto mode or `acceptEdits` for `/cw:build`** — a plugin
+  agent cannot grant itself a permission mode, so the implementer subagents
+  need the session already in one of these modes to write without a prompt
+  per edit.
+
+## Install
+
+Three ways to load this plugin, in order of how much you intend to edit it.
+
+### (a) In place — for editing the plugin itself
+
+```bash
+ln -s /path/to/your/checkout "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/cw"
 ```
-/design <feature description>   → research + draft + task breakdown + review loop
-   ↓  (checkpoint 1 — /design exits plan mode itself, provisionally, then writes
-      the approved artifacts into docs/plans/<slug>/; you approve there, after
-      the write — /build is still the real go/no-go)
-/build [<slug>]                 → implement via subagents, one atomic commit per task
-                                   (plus a `docs(<slug>):` artifacts commit, not
-                                   necessarily leading, when a project design copy
-                                   was promoted)
-   ↓  (checkpoint 2 — you approve the commit series)
-/ship                           → verify commits, quality gate, push, open PR
-   ↓  (offered, optional)
-/compound                       → propose durable lessons back into CLAUDE.md / rules
+
+Claude Code loads any folder under a skills directory that has a
+`.claude-plugin/plugin.json` as a plugin named `cw@skills-dir` — no
+marketplace, no install step. `SKILL.md` edits apply immediately; reload
+agents and hooks with `/reload-plugins`.
+
+This is the least robust path: Claude Code's auto-update has been reported to
+silently remove symlinks under the config dir
+([issue #50052](https://github.com/anthropics/claude-code/issues/50052)). If
+that bites you, fall back to a real directory instead of a symlink — move
+your checkout itself under `<config dir>/skills/cw`, and symlink *back* from
+wherever you actually edit (your normal projects directory, an IDE workspace,
+etc.) to that real location.
+
+### (b) Marketplace — the reliable path for adopters
+
+```bash
+claude plugin marketplace add victorkzam/claude-code-setup
+claude plugin install cw@claude-code-setup
 ```
 
-Two human checkpoints are **non-negotiable and not configurable**: after design,
-and before a PR opens. They exist at exactly the two points where a wrong turn is
-otherwise expensive to unwind — before any code gets written, and before anyone
-outside the loop sees the result. Every other step in the pipeline can retry,
-escalate, or auto-resolve itself; these two cannot, by design.
-
-## 3. Model routing
-
-Every role is pinned to a **public alias** (`opus`, `sonnet`, `haiku`) in
-`rules/orchestration.md`, never a dated or context-window-tagged model ID — the
-routing table is the single place model choice lives, so an alias's underlying
-model can change without touching every skill and agent file that references it.
-
-The routing principle is **route up for hard work**: Sonnet → Opus is a better
-$/quality trade than Haiku → Sonnet when the task is genuinely hard (schema
-design, cross-cutting review, direction judgment). Down-tiering to Haiku is for
-bulk, read-only, mechanical fan-out — codebase exploration, not implementation.
-
-Parallel subagent fan-out (workflows) is reserved for **read-heavy work at
-roughly ≥5 parallel agents** — research, codebase mapping, review panels. Below
-that threshold, plain sequential or small-batch subagent calls are simpler and
-just as fast. Implementation never runs naive-parallel: tasks are partitioned by
-disjoint file ownership (`files_owned` in `<slug>-tasks.md`) so independent tasks
-can run in parallel without merge conflicts, while dependent tasks stay
-sequential.
-
-## 4. Failure modes that shaped it
-
-A few concrete failure modes are baked into the design, not just aspirational:
-
-- **`NO_VERDICT` is not `NEEDS_WORK`.** A reviewer that returns no parseable
-  verdict at all (silence, malformed JSON) is a distinct failure state from one
-  that reviewed the code and found problems. Conflating them either burns a
-  fix-iteration on nothing, or worse, quietly treats a review that never
-  happened as a review that passed. The fix: retry once with a fresh reviewer
-  instance, then escalate to a human — never loop on it, never guess.
-- **Ground truth over agent testimony.** An implementer's own exit report is
-  evidence, not proof. Before any reviewer is spawned, the orchestrator
-  independently re-runs the task's verification command and checks `git log`
-  for the claimed commit — an implementer that reports success on a task that
-  didn't actually commit, or whose tests don't actually pass, is caught before
-  it reaches review, not after.
-- **Counter-model review.** The reviewer for a task is always the model tier
-  the implementer *didn't* use — Opus reviews Sonnet's work and vice versa.
-  Reusing the same model for implementation and review correlates its blind
-  spots with itself.
-- **Hooks as executable guardrails, not advisory text.** CLAUDE.md conventions
-  get followed roughly 70% of the time in practice; a `PreToolUse` hook that
-  exits 2 gets followed 100% of the time, because it isn't a suggestion. Two of
-  the hooks in this repo exist because of specific upstream Claude Code
-  behavior: `orchestrator-delegate-guard.sh` works around a case where a
-  blocked tool call can end the turn instead of prompting a delegate spawn
-  (see [anthropics/claude-code#51609](https://github.com/anthropics/claude-code/issues/51609)),
-  and `skills/build/SKILL.md` notes a related known issue where a sentinel
-  block doesn't self-heal into automatic delegation
-  ([anthropics/claude-code#24327](https://github.com/anthropics/claude-code/issues/24327)) —
-  in both cases the mitigation is to treat the block itself as the cue to act,
-  rather than assume the platform will recover on its own.
-
-## 5. Redaction note
-
-This is a sanitized export of a real, daily-driver `~/.claude` configuration —
-not a from-scratch example. Omissions are deliberate, not incomplete coverage.
-Redacted categories:
-
-- **Employer/client paths and names** — absolute paths, project codenames, and
-  any client-identifying strings from the source machine.
-- **Personal data** — email addresses, account identifiers, and anything tied
-  to a specific individual.
-- **Personal permission entries** — the source `settings.json` allow-list
-  accumulated project-specific paths and a long `WebFetch` domain trail; the
-  shipped `settings.example.json` replaces it with a short, generic example set.
-- **Removed safety-toggle overrides** — the source config enabled several
-  local convenience flags (skipped permission prompts, disabled workflow
-  warnings, plugin toggles) that weaken default safety behavior for a specific
-  trusted machine. None of those are appropriate defaults for someone else's
-  environment, so they are excluded entirely rather than carried over.
-- **One project-specific skill excluded** — a `/deep-research` skill existed in
-  the source config but isn't included here; `WORKFLOW.md` and `skills/search/`
-  have been edited so nothing dangling references it.
-
-## 6. Quick Start (clone-and-use)
+This installs a copy into the plugin cache
+(`~/.claude/plugins/cache/claude-code-setup/cw/`), independent of any local
+checkout. Update it with `claude plugin update cw@claude-code-setup`.
+
+### (c) Trial — no install at all
 
 ```bash
-git clone https://github.com/<you>/claude-code-setup.git
-cd claude-code-setup
-claude
+claude --plugin-dir /path/to/your/checkout
+```
+
+Loads the plugin for that session only.
+
+## Commands
+
+| Command | What it does | Claude may invoke it on its own? |
+|---|---|---|
+| `/cw:design <description>` | Research-grounded design; ends in one approved plan file | Yes — description-triggered |
+| `/cw:build <slug> [continue [<task-id>]]` | Orchestrates implementation via subagents, one commit per task | No — manual only |
+| `/cw:ship [title]` | Verifies the commit series, runs the gate, pushes, opens the PR | No — manual only |
+| `/cw:compound [range]` | Captures lessons from a shipped change into CLAUDE.md/rules | No — manual only |
+| `/cw:search [--quick\|--deep] <query>` | Multi-source web research with citations | Yes — description-triggered |
+| `/cw:google-workspace` | Google Docs/Drive routes and dead ends playbook | Yes — description-triggered |
+
+`/cw:build`, `/cw:ship`, and `/cw:compound` are marked
+`disable-model-invocation: true` deliberately — they change files, branches,
+or open PRs, so they only run when you type the command.
+
+## Agents
+
+| Agent | Model | Role |
+|---|---|---|
+| `cw:researcher` | sonnet | Web research, read-only |
+| `cw:implementer` | sonnet (opus per-task for hard work) | Writes code, makes the task's commit |
+| `cw:reviewer` | opus | Reviews an implementer's diff, read-only |
+| `cw:design-reviewer` | opus | Doc/codebase fidelity review of a design draft |
+| `cw:direction-reviewer` | opus, effort xhigh | Premise/direction review, once per design |
+
+## A profile CLAUDE.md
+
+A profile's `CLAUDE.md` is deliberately short — an identity line and two
+imports for the process rules this plugin ships:
+
+```markdown
+# Your profile
+Profile: acme
+@<checkout>/rules/workflow.md
+@<checkout>/rules/orchestration.md
 ```
 
-When Claude Code opens inside the clone for the first time, it shows a **trust
-dialog** for the folder. **Accept it.** Trusting the repo is what gates access
-to its `.claude/` directory — until you accept, the repo-scoped `/setup` skill
-and its pre-approved read-only commands (`check.sh`, the `--dry-run` forms of
-the install/merge scripts) aren't available to the session at all. This is a
-one-time, per-directory Claude Code trust decision, not something this repo
-configures.
+Stack preferences (language conventions, framework choices) belong in your
+*project* `CLAUDE.md` files, not in this profile file — this one is workflow
+process, not stack opinion.
+
+The import path depends on how you installed:
+
+- **(a) in place / (c) trial** — import from your checkout directly:
+  `@<checkout>/rules/workflow.md`.
+- **(b) marketplace** — run `claude plugin details cw@claude-code-setup` to
+  print the current cache path and import from there; that path changes on
+  every `claude plugin update cw@claude-code-setup`, so re-check it after
+  updating, or keep a separate throwaway clone just for stable import paths.
+
+Also set `plansDirectory: docs/plans` in your settings so `/cw:design`'s plan
+mode writes the plan file into the project instead of the default location.
+
+## Extra profiles
+
+Run more than one Claude Code identity (work vs. personal, or one per client)
+with `CLAUDE_CONFIG_DIR`:
+
+```bash
+alias claude-acme='CLAUDE_CONFIG_DIR=$HOME/.claude-acme claude'
+```
 
-Once trusted, type:
+An alias survives GUI launchers better than a one-off shell export. List the
+mapping between project paths and config dirs in `~/.claude-profiles`, one
+per line, `<folder prefix>|<config dir>`, `#` comments allowed:
 
 ```
-/setup
+~/work/acme|~/.claude-acme
+~/side-projects|~/.claude-personal
 ```
 
-`/setup` walks a **preflight → install → merge → handoff** flow
-(`.claude/skills/setup/SKILL.md`). It runs a dry-run and shows you a diff
-before every write, and asks for explicit consent before anything actually
-changes your `~/.claude` config — nothing is written silently. Differing files
-are skipped by default per category (agents/hooks/rules/skills); you choose
-keep-vs-overwrite per category. `settings.json` and `CLAUDE.md` are merged one
-at a time, each behind its own diff-then-consent step.
-
-> [!WARNING]
-> **Never clone this repo directly into `~/.claude`, and never point
-> `CLAUDE_CONFIG_DIR` at this clone.** The scripts refuse to install a repo
-> onto itself (a source-equals-destination guard checks for exactly this), but
-> don't rely on that guard — treat the clone and your Claude config dir as two
-> separate locations, always. The scripts honor `CLAUDE_CONFIG_DIR` as an
-> override for the config dir they install into/read from (default
-> `~/.claude`); set it if your Claude Code config lives somewhere non-default.
-
-## 7. Standalone install (no LLM, run the scripts directly)
-
-If you'd rather not run `/setup` conversationally — or you're scripting an
-install — the four scripts it orchestrates can be run by hand, in this order.
-**Run them with `bash`, not `sh`** — they're bash scripts (`set -euo pipefail`,
-bash-specific idioms) and will fail or behave incorrectly under a POSIX `sh`:
+The `profile-check.sh` `SessionStart` hook reads this file and reports a
+`wrong profile: ...` notice if the active config dir doesn't match the
+mapped one for your current directory, and a `missing import: ...` notice
+for any `@import` line in `CLAUDE.md` whose target doesn't exist.
+
+## settings.example.json
+
+Use `settings.example.json` as a starting point, not a drop-in replacement —
+copy it to `settings.json` and adapt it. It sets `defaultMode: "auto"`,
+`effortLevel: "high"`, `plansDirectory: "docs/plans"`, a short generic
+`permissions.deny`/`allow`/`ask` set, `autoMode.allow: ["$defaults"]`, and
+`enabledPlugins` for the official TypeScript, Python, and Rust LSP plugins
+from the `claude-plugins-official` marketplace. It carries no `hooks` key —
+this plugin registers its own hooks, and a plugin hook and a settings hook
+with the same command both fire, so don't add them again in `settings.json`.
+
+**What to adapt**: the `permissions.allow`/`deny` lists for your own
+workflow, the model alias mappings in `rules/orchestration.md` if you have
+different tier preferences, and the identity line in your profile
+`CLAUDE.md`. **What to keep as-is**: the workflow rules in
+`rules/workflow.md`, the checkpoint semantics, and the hooks.
+
+## Kill switch
 
 ```bash
-bash scripts/check.sh                                   # preflight
-bash scripts/install.sh --dry-run --diff                # see the plan first
-bash scripts/install.sh                                  # real install (prints a backup-dir path — save it)
-bash scripts/merge-settings.sh --dry-run                # see the settings.json diff
-bash scripts/merge-settings.sh --apply --backup-dir <path>
-bash scripts/merge-claude-md.sh --dry-run               # see the CLAUDE.md diff
-bash scripts/merge-claude-md.sh --apply --backup-dir <path>
+claude plugin disable cw@skills-dir        # install path (a)
+claude plugin disable cw@claude-code-setup # install path (b)
 ```
 
-Thread the same `--backup-dir <path>` (captured from `install.sh`'s first
-`CCS-STATUS:backup-dir:<path>` line) into every later `--apply`/`--force` call,
-so the whole install shares one backup run dir and one receipt.
+Turns all three hooks off at once. This is also the answer for a repo that
+pushes to `main` by convention — `protect-branches.sh` has no opt-out
+environment variable by design, so disabling the plugin is the supported
+escape hatch, not a bypass flag on the hook itself.
 
-## 8. Verify the install
+## Migration from the old installer
 
-1. **Restart Claude Code** — hooks and skills load at session start, so a
-   fresh install/merge only takes effect after a restart.
-2. Run:
+If you previously installed this project's skills, agents, and hooks
+directly into `~/.claude` (five skills, six agents, five hooks) rather than
+as a plugin: delete those user-scope copies, and remove their `hooks` entries
+from `settings.json`. A plugin hook and a settings hook that share the same
+command both fire, so leaving the old entries in place double-runs them.
 
-   ```bash
-   bash scripts/check.sh --post
-   ```
+## `/cw:search --deep`
 
-   to confirm the managed artifacts landed under your config dir.
-3. Run **`/hooks`** and confirm the managed hook entries appear.
+The `--deep` flag hands off to the bundled `/deep-research` workflow, which
+needs dynamic workflows enabled (a paid-plan feature; `disableWorkflows`
+turns it off). Without that, `/cw:search` falls back to its default
+multi-source mode.
 
-## 9. Updating
+## Update and uninstall
+
+- **(a) in place** — `git pull` in your checkout; a symlinked install picks
+  it up on the next `/reload-plugins`, a real-directory install picks it up
+  immediately. Remove the symlink (or directory) to uninstall.
+- **(b) marketplace** — `claude plugin update cw@claude-code-setup` to pull
+  the latest version; `claude plugin uninstall cw@claude-code-setup` to
+  remove it.
+- **(c) trial** — nothing persists; just stop passing `--plugin-dir`.
+
+## Running the tests
 
 ```bash
-cd claude-code-setup   # your existing clone
-git pull
+bash tests/run.sh all
 ```
 
-Then, **from inside the clone**, run `/setup` again. Any file you've
-customized since the last install surfaces as a per-category diff/prompt —
-it's **skipped by default** and only overwritten if you explicitly consent;
-nothing you've changed is clobbered silently.
-
-**Upgrading into an existing install**: because differing files are skipped by
-default, an adopter who already had `~/.claude` set up before this feature
-shipped won't pick up the new `design-scope-guard.sh` hook or the changed
-`/design` skill automatically — `/setup`'s diff-then-consent flow treats an
-existing file that differs from the new template as skip-by-default, not an
-automatic overwrite. Choose overwrite at the `hooks/` and `skills/` category
-prompts (or run `bash scripts/install.sh --force`) to receive both. The new
-hook installs cleanly onto a fresh copy of `hooks/`; `merge-settings.sh` adds
-its `PreToolUse` registration to `settings.json` during the settings merge
-step, same as any other hook.
-
-## 10. Uninstalling
-
-There's no uninstall script yet (deliberately deferred — see below); removal
-is manual but deterministic because every write is logged to a **receipt**.
-The receipt for a given install lives at `<backup-run-dir>/receipt.txt`, where
-`<backup-run-dir>` is a timestamped directory under
-`~/.claude/backups/claude-code-setup/<timestamp>/` (or under `$CLAUDE_CONFIG_DIR`
-if you've overridden it). Each line is tab-separated:
-`action  path  backup-path  repo-sha  timestamp`.
-
-Walk the receipt and act **per `action`**, in this order — the ordering
-matters because it's what protects data that predates the install:
-
-- **`installed`** — the file didn't exist before `/setup`; `rm` it.
-- **`overwritten`** — a file you already had was replaced; **restore it from
-  the backup path on that line** (do **not** `rm` it — `rm` would destroy the
-  original the backup exists specifically to preserve).
-- **`merged`** — if the backup-path field is non-empty, same as
-  `overwritten`: **restore from the backup path** on that line (never `rm`
-  it). If the backup-path field is **empty**, the file didn't exist before
-  `/setup` and was created fresh by the merge — `rm` it, same as `installed`.
-- **`unchanged`** — the file already matched what `/setup` would have
-  written, so nothing was touched; leave it alone. (Earlier runs' lines still
-  govern it if you ran `/setup` more than once.)
-- **`skipped`** — nothing was written; leave it alone.
-
-If you ran `/setup` more than once (e.g. across an update), restore from the
-**earliest** run's backups — that's the true pre-setup state; later runs'
-backups are snapshots of an already-modified file, not the original.
-
-## 11. Prerequisites
-
-- **jq** — REQUIRED. `protect-branches.sh` and `protect-secrets.sh` fail closed
-  without it: they block the corresponding git operations/edits entirely rather
-  than silently skip the check if `jq` isn't installed. `brew install jq` /
-  `apt install jq`.
-- **git** — obviously; also needed for `git identity` (`user.name` /
-  `user.email`) so the workflow's own commits (one per `/build` task, plus
-  `/ship`) have an author.
-- **Claude Code ≥ v2.1.53** — REQUIRED. This is a security floor
-  (CVE-2026-33068); `check.sh` fails closed below it.
-- **Claude Code ≥ v2.1.198** — RECOMMENDED, for the full feature set: the
-  custom `Explore` agent's model override (below this version it inherits the
-  session's main-thread model instead of running on `haiku`), and
-  session-scoped sentinel isolation in `orchestrator-delegate-guard.sh` (fully
-  available from ≥ v2.1.132; below that the guard falls back to a legacy
-  global sentinel with only a TTL as backstop).
-- **gh** — the GitHub CLI, needed **only for `/ship`'s** PR creation, not for
-  install. Run `gh auth login` before your first `/ship`.
-- **shellcheck + bats** — DEV-ONLY, for contributing to this repo's own
-  scripts/tests. Not required to adopt or run `/setup`.
-- **context7 + exa MCP servers** — OPTIONAL. `skills/search/SKILL.md` falls
-  back to `WebSearch` for any angle where an MCP tool is unavailable; `/design`
-  and `/search` degrade gracefully without them, just with less precision
-  (context7's version-pinned docs, exa's semantic search).
-
-## 12. Troubleshooting
-
-- **`/setup` doesn't appear.** Confirm you accepted the folder's **trust**
-  dialog, and that you're running Claude Code from inside the clone (the skill
-  is repo-scoped, not installed globally). Then restart Claude Code once —
-  skill discovery has known upstream flakiness on a fresh trust grant
-  ([anthropics/claude-code#45956](https://github.com/anthropics/claude-code/issues/45956),
-  [anthropics/claude-code#43092](https://github.com/anthropics/claude-code/issues/43092)).
-  If it still doesn't appear, `bash scripts/check.sh` will surface targeted
-  fixes for common environment issues.
-- **`check.sh --post` shows a `FAIL:` line.** A managed artifact is missing
-  from your config dir — re-run `/setup` to install it.
-- **`check.sh --post` shows a `WARN: ... ignore if you declined this merge`.**
-  This is informational, not an error — it means you chose not to merge
-  `settings.json` or `CLAUDE.md`, and the check is just confirming that.
-- **A hook is blocking legitimate work.** See the `protect-secrets` note
-  below.
-
-**`protect-secrets` self-lockout note**: once installed, the `protect-secrets`
-hook blocks Claude Code itself from writing/editing files matching secret
-patterns (`.env`, `*credentials*`, `*.pem`, SSH/AWS/GCP key paths, etc.) — and
-it applies in **every** project you use Claude Code in afterward, not just this
-one, because it's wired into your global `~/.claude/settings.json`. If it
-blocks something you legitimately need to edit, that settings file is yours:
-edit or remove the hook entry directly. Re-running `/setup` later will offer
-to re-merge it, but it will never force the merge back in without your
-consent.
-
-**Plugin packaging (future work)**: a Claude Code plugin is a plausible future
-distribution mechanism for this setup. Today's clone-and-use + `/setup`
-approach was chosen deliberately instead — current plugin docs impose
-verbatim-file limits that don't fit this repo's merge-not-clobber model for
-`settings.json`/`CLAUDE.md`.
-
-**Backups accumulate**: backup run directories under
-`~/.claude/backups/claude-code-setup/` are never auto-deleted (there's no
-pruning script yet). They're cheap to keep and are what makes uninstall
-deterministic, but feel free to delete old ones by hand once you're confident
-you won't need to restore from them.
-
-## 13. What to adapt vs keep
-
-**Yours to replace**: the `Identity` and `Stack Preferences` blocks in
-`CLAUDE.md` (marked "example — replace with your own"), the generic example
-`permissions.allow` list in `settings.example.json`, and the model alias
-mappings in `rules/orchestration.md` if you have different tier preferences.
-
-**The transferable system**: the `/design` → `/build` → `/ship` workflow rules
-and mode transitions, the model routing table's *principles* (public aliases,
-route-up-for-hard-work, the ≥5-agent workflow threshold), the review-loop
-semantics (`NO_VERDICT` vs `NEEDS_WORK`, counter-model review, ground-truth
-verification), and the hooks — these are the parts built from real failure
-modes and are worth keeping close to as-is.
-
-## 14. Project-local design docs (adopter notes)
-
-`/design` promotes its approved artifact set (`<slug>-design-draft.md`,
-`<slug>-tasks.md`, `<slug>-research-*.md`) out of `~/.claude/plans/` and into
-the adopting project's own `$ROOT/docs/plans/<slug>/`, so a design lives with
-the code it describes and is reviewable from a phone/synced Files app before
-`/build` runs — see `WORKFLOW.md`'s Mode Transitions table for the full
-step-by-step sequence. A few things to know if your project isn't a typical
-git repo:
-
-- **Gitignored `docs/`** — if `docs/` (or specifically `docs/plans/`) is
-  gitignored in your project, the promotion write in `/design`'s guarded
-  window and `/build`'s `docs(<slug>): add design + research artifacts`
-  commit (not necessarily the leading commit in the series) both skip,
-  explicitly and by design — artifacts stay in the plans dir
-  (`~/.claude/plans/`, or `$CLAUDE_CONFIG_DIR/plans/` if you've overridden
-  it) as the canonical copy, exactly how `/design` behaved before this
-  feature.
-- **A published `docs/` site** (Docusaurus, mkdocs, GitHub Pages, etc.) — if
-  your project already builds `docs/` into a live site, promoting WIP planning
-  artifacts into `docs/plans/<slug>/` would land them inside that published
-  tree. Relocate the target directory by editing the write logic in
-  `skills/design/SKILL.md`'s Step 6 — and the matching path patterns in
-  `hooks/design-scope-guard.sh`, or the write will be blocked — to a directory
-  outside your published tree.
-- **Forking this workflow repo itself** — a fork of `claude-code-setup`
-  behaves like any other adopting project for design routing: unless `$ROOT`
-  resolves to your actual `${CLAUDE_CONFIG_DIR:-$HOME/.claude}`, artifacts
-  promote into the fork's own `docs/plans/<slug>/` like anywhere else. The
-  meta-tooling exception (artifacts stay in the plans dir) applies only when
-  you're editing your live `~/.claude` config in place.
-- **Upgrading an existing install** — see [Updating](#9-updating): this
-  feature ships a new hook and a changed `/design` skill, both skipped by
-  default on an already-customized config unless you explicitly choose to
-  overwrite.
+Runs hook behavior, file-size budgets, a cross-file phrase-duplication check,
+and the `settings.example.json`/`tests/settings-keys.txt` cross-check.
+Optionally set `CW_SCAN_PATTERNS=<your private pattern file>` to also scan
+the tracked tree for private strings you've defined — this is empty by
+default and off unless you set it.
+
+## Changelog
+
+### 1.0.0
+
+First release as a Claude Code plugin. Converts the prior clone-and-use,
+conversationally-installed configuration into a proper plugin (`cw`): a
+plugin manifest and marketplace entry, lean skill and agent prompts, hooks
+registered through `hooks/hooks.json` (including a new `profile-check.sh`
+`SessionStart` hook), a single `tests/run.sh` test runner replacing the old
+per-script tests, and CI running the same checks on every push and PR.
diff --git a/WORKFLOW.md b/WORKFLOW.md
index ba3eea2..917438d 100644
--- a/WORKFLOW.md
+++ b/WORKFLOW.md
@@ -1,298 +1,130 @@
-# Agentic Workflow Harness
-
-Documentation for the `/design` -> `/build` -> `/ship` workflow. Installed at `~/.claude/` (user-level, works in every project).
-
----
-
-## Quick Start
-
-**Install**: clone the repo, open Claude Code in it, then run `/setup` — the
-setup skill checks prerequisites, installs agents/skills/hooks/rules, and merges
-`settings.json`/`CLAUDE.md` with your existing config (dry-run + consent at each
-step; see the README's Quick Start section for the full flow).
-
-**Use**:
-
-```
-/design <paste voice note transcript or feature description>
-  -> iterates with research until you approve
-
-/build
-  -> implements via subagents, reviews, iterates up to 3x
-  -> stops for your approval
-
-/ship [optional PR title]
-  -> commits, pushes, creates PR
-```
-
-Two human checkpoints: **after design** (you approve the plan), **before PR** (you approve the code).
-
----
-
-## Architecture
-
-| Primitive | What | Where |
-|---|---|---|
-| CLAUDE.md | Always-on advisory rules | `~/.claude/CLAUDE.md` |
-| `/design` | Research-grounded planning skill | `~/.claude/skills/design/SKILL.md` |
-| `/build` | Implementation orchestrator skill | `~/.claude/skills/build/SKILL.md` |
-| `/ship` | Commit + PR automation skill | `~/.claude/skills/ship/SKILL.md` |
-| `/compound` | Post-ship lesson capture into CLAUDE.md/.claude/rules (offered by `/ship`) | `~/.claude/skills/compound/SKILL.md` |
-| `/search` | 3-angle web research skill | `~/.claude/skills/search/SKILL.md` |
-| researcher | `sonnet` agent, read-only, web tools | `~/.claude/agents/researcher.md` |
-| implementer | `sonnet` default / `opus` per-call, writes code + atomic commit, no push | `~/.claude/agents/implementer.md` |
-| reviewer | `opus` agent, read-only, runs tests | `~/.claude/agents/reviewer.md` |
-| design-reviewer | `opus` agent, read-only, doc/codebase fidelity (loops until findings converge, escalates after 5) | `~/.claude/agents/design-reviewer.md` |
-| direction-reviewer | `opus` agent (effort xhigh), read-only, premise/direction (once) | `~/.claude/agents/direction-reviewer.md` |
-| Branch protection | Hook: blocks push *to* main/master + force push (by destination, not branch name) | `~/.claude/hooks/protect-branches.sh` |
-| Secrets protection | Hook: blocks edits to .env/keys/credentials/secrets (broadened) | `~/.claude/hooks/protect-secrets.sh` |
-| Delegate guard | Hook: session-scoped; blocks orchestrator source edits while `/build` active | `~/.claude/hooks/orchestrator-delegate-guard.sh` |
-| Design scope guard | Hook: session-scoped; confines `/design`'s post-approval Write\|Edit calls (not a hard filesystem guarantee) to design artifact paths (`docs/plans/` — where `/design` writes both its design draft and research files — `docs/research/`, a separately allowlisted research-output path not written by `/design`, plans dir), sentinel-armed, same trust class as the delegate guard | `~/.claude/hooks/design-scope-guard.sh` |
-| Syntax check | Hook: multi-language (py/js/sh/json/swift), surfaces errors | `~/.claude/hooks/syntax-check.sh` |
-
----
-
-## Workflow Detail
-
-### Phase 1: `/design`
-
-**What it does**: Research-grounded feature design. Spawns researcher subagents to investigate unknowns, then synthesizes findings into a plan.
-
-**How it works**:
-1. Reads project CLAUDE.md + explores codebase
-2. Identifies unknowns and assumptions
-3. Spawns grounding subagents in parallel: `Explore` (codebase map, **`haiku`** — fan-out navigation) + two `researcher` (`sonnet`, 3-angle methodology)
-   - Only structured summaries return to main context (~500-1K tokens each)
-   - Raw research (10-50K tokens) stays in subagent context
-4. Synthesizes a design draft **and** `<slug>-tasks.md` (adaptive task count — 1 to many, never a fixed range; each task: disjoint files, assigned model, verification, one atomic Conventional commit — or `commit: none` for unversioned/external targets, verification-only)
-5. **design-reviewer** loop (fresh context each pass, continues until findings converge, escalates after 5 iterations) for consistency/codebase-fit/best-practices, then **direction-reviewer** once (`opus`, premise/problem-fit)
-6. `/design` calls **`ExitPlanMode` itself** — provisional and skill-invoked, not the real go/no-go; approving here only continues the same turn into the guarded write below (rejecting stays in plan mode and re-runs the loop)
-7. **Guarded promotion write** (execute mode, same turn; session-scoped sentinel via `design-scope-guard.sh`) — writes the approved artifact set into `$ROOT/docs/plans/<slug>/`, unless `$ROOT` is the config repo itself or `docs/plans/` is gitignored there, in which case artifacts stay in the plans dir
-8. **STOPS for your approval** — the real checkpoint, now *after* the write, on the project copy; presents both verdicts + the artifact path
-
-**Iteration**: feedback given before the provisional `ExitPlanMode` approval iterates entirely on the plans-dir copies (regenerate design + `<slug>-tasks.md`, re-run the review loop + direction review). Feedback given at the post-write checkpoint re-arms the sentinel and iterates on the project copies in `docs/plans/<slug>/` instead — the plans-dir drafts are inert scratch by then. Either path stops again at a single checkpoint.
-
-**Context impact**: Research stays out of main context. Only summaries enter.
-
-### Phase 2: `/build`
-
-**What it does**: Orchestrates implementation using subagents. The main agent NEVER writes code and NEVER re-decomposes — it consumes `<slug>-tasks.md`, delegates, and reviews. Runs in execute mode.
-
-**How it works**:
-1. **Pre-flight**: Resolves the tasks file — project copy first (`$ROOT/docs/plans/<slug>/<slug>-tasks.md`), falling back to the legacy `~/.claude/plans/` (arg / newest-by-mtime-with-confirm) — creates feature branch, commits a promoted project design copy as a `docs(<slug>): add design + research artifacts` commit, then writes the session-scoped sentinel
-2. **Consume tasks**: Executes exactly the tasks `<slug>-tasks.md` defines — adaptive count (1 to many), in `depends_on` order, independent ones in parallel
-3. **Implement**: Spawns a context-pinned **implementer** per task (only its task entry + relevant excerpt); the implementer makes **one atomic Conventional commit per task** (co-author trailer; no push) — except `commit: none` tasks (unversioned/external targets), which are verification-only
-4. **Review**: Spawns **reviewer** subagent that reads files FRESH from disk and checks commit atomicity (no implementer bias)
-5. **Iterate**: If reviewer finds issues:
-   - Iteration 1-2: Spawns NEW implementer with reviewer's feedback
-   - Iteration 3: Escalates to you with full context
-6. **STOPS for your approval** with summary of what was built, test results, and manual test instructions
-
-**Context impact**: All code writing and reviewing happens in subagents. Main context stays clean.
-
-### Phase 3: `/ship`
-
-**What it does**: Verifies the commit series, updates product docs, pushes, creates PR, then offers `/compound`. Runs in execute mode.
-
-**How it works**:
-1. Verifies NOT on main (refuses if so)
-2. **Verifies** the atomic per-task Conventional commit series (does NOT squash or author a catch-all commit; stops on stray uncommitted changes) — a `docs(<slug>):` artifacts commit is exempt from the one-commit-per-task accounting
-3. Updates **product** docs (README, ARCHITECTURE, CHANGELOG) if needed — distinct from `/compound`'s process-rule capture
-4. Quality gate must pass; opens PR only after the feature is fully built AND green
-5. Pushes branch, creates PR via `gh pr create`, then **offers `/compound`** (HITL; never commits process-rule edits into this PR)
-
-**Safety**: Never pushes to main, never force pushes, never commits secrets, never squashes the per-task series.
-
----
-
-## Recommended Sequence
-
-```
-/design <spec>   → research + draft + <slug>-tasks.md + design-reviewer loop + direction-reviewer
-   ↓  (/design exits plan mode itself, provisionally, then writes the approved
-      artifacts into docs/plans/<slug>/ — you approve there, after the write;
-      /build is still the real go/no-go)
-/build [<slug>]  → consume tasks.md; one atomic commit per task; reviewer
-   ↓  (you approve the commit series)
-/ship            → verify series, product-doc updates, quality gate, push, PR
-   ↓  (offered, optional)
-/compound        → propose CLAUDE.md/.claude/rules lessons (HITL; never committed into the PR)
-```
-
-Two non-negotiable human checkpoints: **after design**, **before PR**. `/compound` is a
-separate, user-driven step chained from `/ship` — it is never merged into `/ship` and
-never lands process-rule edits inside the feature PR.
-
-## Mode Transitions
-
-`/design` is a **hybrid**: plan mode for its research/draft/review loop (Steps 0-5),
-then a short guarded execute-mode window (Step 6) that writes the approved artifacts
-into the project, followed by the real human checkpoint (Step 7) — the checkpoint now
-comes *after* that write, not before it.
-
-| Stage | Mode | Notes |
-|---|---|---|
-| `/design` Steps 0-5 (research, draft, review loop) | **plan** | Documented exception: may write only `~/.claude/plans/<slug>-*.md` (judgment call, bounded to that dir) |
-| `/design` Step 5 `ExitPlanMode` | — | **Provisional, skill-invoked.** `/design` calls `ExitPlanMode` itself; approving here is administrative — it only continues the same turn into Step 6, it is not the go/no-go |
-| `/design` Step 6 (execute, same turn) | **execute**, guarded | `design-scope-guard.sh`'s session-scoped sentinel confines Write\|Edit calls (not a hard filesystem guarantee) to `docs/plans/<slug>/` (where `/design`'s own research files land, alongside the design draft + tasks), `docs/research/` (a separately allowlisted research-output path, not written by `/design`), and the plans dir while the approved artifact set is promoted into `$ROOT/docs/plans/<slug>/` (also `~/.claude/plans/<slug>-*.md` during this window) |
-| `/design` Step 7 checkpoint | — | **The real human checkpoint**, now after the promotion write, on the project copy. You approve or iterate here — `/build` remains the true go/no-go |
-| `/build`, `/ship` | **execute** (default/acceptEdits) | `disable-model-invocation: true`; run explicitly after approval |
-
-The shipped template sets `defaultMode: "auto"` — a convenience key, deliberately
-withheld from merges into existing configs. The plan-first guarantee comes from
-`/design`'s Steps 0-5 running in plan mode and Step 6's write window being confined by
-`design-scope-guard.sh`, not from a global `"plan"` default.
-
-## Model Usage Map
-
-Roles are pinned to **aliases**, never dated model IDs — this table is a summary
-for orientation only. The authoritative routing table lives in
-`~/.claude/rules/orchestration.md`; if the two ever disagree, that file wins.
-
-| Role | Model | Tier rationale |
-|---|---|---|
-| Main thread / `/design` orchestrator | `opus` | Orchestration / architecture |
-| `/design` `Explore` subagent | `haiku` | Fan-out codebase navigation |
-| `researcher` | `sonnet` | Research |
-| `design-reviewer` | `opus` | Doc/codebase fidelity |
-| `direction-reviewer` | `opus` (effort `xhigh`) | Premise/direction judgment |
-| `implementer` | `sonnet` → `opus` per-call | Implementation |
-| `reviewer` | `opus` | Code review |
-| `/compound` subagent | `sonnet` | Lesson extraction |
-
-Effort: `opus` agents use `xhigh` (Opus's recommended default, matching the global
-`effortLevel`); `sonnet` agents keep `high` (Sonnet has no `xhigh` — `high` is its
-top balanced level).
-
----
-
-## Agents
-
-### researcher (`sonnet`)
-- **Purpose**: Web research with structured findings and citations
-- **Tools**: Read, Glob, Grep, WebSearch, WebFetch, exa, context7
-- **Cannot**: Write files, edit files, run bash commands
-- **Preloads**: `/search` skill (3-angle methodology)
-- **Output**: Structured findings with URLs, confidence levels, consensus, gaps
-
-### implementer (`sonnet` default / `opus` per-call)
-- **Purpose**: Implement one task; make exactly one atomic Conventional commit for it — or, for `commit: none` tasks (unversioned/external targets), verification-only with no commit
-- **Model**: `sonnet`; the design assigns `opus` per-call for >5-file / long-horizon / cross-cutting tasks
-- **Tools**: Read, Write, Edit, Glob, Grep, Bash, context7
-- **Cannot**: `git push`, `gh pr create`, checkout main (commits ARE allowed and required)
-- **Config**: `permissionMode: acceptEdits`, `effort: high`, `memory: project`
-- **Output**: Files created/modified, the task's commit, design deviations, test results
-
-### reviewer (`opus`)
-- **Purpose**: Code review for quality, correctness, conventions, commit atomicity
-- **Tools**: Read, Glob, Grep, Bash (for tests)
-- **Cannot**: Write, Edit, push, delete
-- **Config**: `memory: project`
-- **Output**: PASS/NEEDS WORK verdict, issues list, test results, design adherence
-
-### design-reviewer (`opus`)
-- **Purpose**: Pre-code fidelity review — consistency, codebase-fit, best-practices, research-ignored (loops until findings converge, escalates after 5 iterations)
-- **Tools**: Read, Glob, Grep, web/exa/context7; **Cannot**: Write, Edit
-- **Output**: Strict JSON verdict (PASS/NEEDS_WORK) + issues + suggested_fixes
-
-### direction-reviewer (`opus`, effort xhigh)
-- **Purpose**: Premise/problem-fit review — "is this plan aimed at the right outcome" (runs once, after the design-reviewer loop; no auto-loop)
-- **Tools**: Read, Glob, Grep only (no web — research already happened); **Cannot**: Write, Edit
-- **Output**: Strict JSON verdict (PASS/REDIRECT) + concerns + recommended_reframe
-
-See `~/.claude/rules/orchestration.md` for the authoritative role → model routing table.
-
----
+# Workflow
+
+`cw` is a Claude Code plugin implementing a `/cw:design` -> `/cw:build` ->
+`/cw:ship` pipeline: research-grounded planning, delegated implementation with
+one atomic commit per task, and a verified, gated release. `/cw:compound`
+closes the loop by feeding lessons back into project rules.
+
+## Roles
+
+| Who | Does |
+|---|---|
+| You | Approve the design, approve the commit series, review the PR |
+| The orchestrating session (main thread) | Runs `/cw:design`, `/cw:build`, `/cw:ship`; never writes application code itself |
+| `cw:researcher` (sonnet) | Web research with citations, read-only |
+| `cw:implementer` (sonnet, opus for hard tasks) | Implements one task, makes its commit |
+| `cw:reviewer` (opus) | Reviews an implementer's diff, read-only |
+| `cw:design-reviewer` (opus) | Checks a draft design against the codebase and current docs, read-only |
+| `cw:direction-reviewer` (opus, effort xhigh) | Checks the design targets the right problem, read-only |
+
+## `/cw:design <description>`
+
+Plan mode. Reads project context, spawns `Explore` (haiku) and
+`cw:researcher` (sonnet) subagents in parallel to ground the plan in the real
+codebase and current sources, drafts one plan file with a task list, then
+loops `cw:design-reviewer` (fresh context each pass, until findings converge,
+escalating after 5 iterations) followed by `cw:direction-reviewer` once.
+
+The skill calls `ExitPlanMode` itself when the review loop converges — that
+approval only ends drafting; it is not the real checkpoint. Plan mode writes
+the draft (into `docs/plans/` when the profile sets
+`plansDirectory: docs/plans`, else the default plans dir); on approval the
+design step moves it to `docs/plans/<slug>.md` in the repo, which
+`/cw:build` then reads.
+
+**Checkpoint 1 (non-negotiable): you approve the plan file before anything
+gets built.**
+
+## `/cw:build <slug> [continue [<task-id>]]`
+
+Execute mode (needs auto mode or `acceptEdits` — a plugin agent cannot grant
+itself a permission mode). The orchestrating session:
+
+1. Resolves the plan (`docs/plans/<slug>.md`, or the folder-layout fallback),
+   creates the feature branch, commits the plan as `docs(<slug>): design`.
+2. Reads the task list and works it in `depends_on` order, independent tasks
+   in parallel, never re-decomposing it.
+3. Delegates each task to a fresh `cw:implementer`, scoped to only that
+   task's entry and its file ownership. The implementer makes exactly one
+   atomic Conventional commit for its task — or, for a `commit: none` task
+   (an unversioned or external target), verifies without committing.
+4. Independently re-runs the task's own verification command and checks
+   `git log` for the claimed commit before trusting an implementer's report —
+   an implementer's exit report is evidence, not proof.
+5. Spawns `cw:reviewer` — a different model tier than the implementer used —
+   to review the diff fresh from disk. `NEEDS_WORK` respawns a new
+   implementer with the feedback (up to 2 retries); a reviewer that returns
+   no parseable verdict at all is retried once fresh, not treated as a pass
+   or a fail.
+6. Stops for your approval once every task's commit is in and the tasks-file
+   quality gate passes.
+
+`continue [<task-id>]` resumes a `/cw:build` run, skipping tasks whose commit
+subject is already in `git log main..HEAD`.
+
+**Checkpoint 2 (non-negotiable): you approve the commit series before any
+PR.**
+
+## `/cw:ship [title]`
+
+Execute mode. Refuses to run on `main`/`master`. Verifies the commit series
+against the plan's task list (no squashing, no catch-all commit), runs the
+project's quality gate (`bash tests/run.sh all` when this repo owns the
+gate), pushes the branch, and opens the PR with `gh pr create` only once the
+gate is green. Ends by offering `/cw:compound`.
+
+## `/cw:compound [range]`
+
+Optional, user-driven, never folded into `/cw:ship`. Reads what just shipped,
+extracts the handful of lessons actually worth keeping, proposes edits to the
+project's CLAUDE.md or rules files, and applies only what you approve.
+Process-rule edits from `/cw:compound` are never committed into the feature
+PR that prompted them — they are their own change.
+
+## `/cw:search [--quick|--deep] <query>`
+
+Cross-references Context7, Exa, and WebSearch (whichever are available;
+missing MCP servers degrade an angle to WebSearch, never a hard failure) into
+one structured, citation-backed answer. `--deep` hands off to the bundled
+`/deep-research` workflow, which needs dynamic workflows enabled.
+
+## `/cw:google-workspace`
+
+A reference playbook, not a pipeline step: hard-won routes and dead ends for
+driving Google Docs/Drive from Claude, triggered when a task needs one.
+
+## Rules
+
+`rules/workflow.md` carries the process rules above (branch policy, commit
+format, checkpoints, mode transitions) and is meant to be imported by a
+profile's `CLAUDE.md`. `rules/orchestration.md` carries the model-routing
+table (public aliases, route-up-for-hard-work, the workflow-fan-out
+threshold) and the review-loop semantics (`NO_VERDICT` vs `NEEDS_WORK`,
+counter-model review, ground-truth verification). If a rule and this file
+ever disagree, the rules file wins.
 
 ## Hooks
 
-All hooks are in `~/.claude/settings.json` and `~/.claude/hooks/`. They provide 100% enforcement (vs CLAUDE.md's ~70% compliance).
+Three hooks, registered by the plugin itself (`hooks/hooks.json`), fire in
+every session the plugin is enabled in:
 
 | Hook | Event | What it does |
 |---|---|---|
-| protect-branches.sh | PreToolUse (Bash, git) | Blocks pushes whose *destination* is main/master + force push; allows feature branches named like `feat/main-*` |
-| protect-secrets.sh | PreToolUse (Write\|Edit) | Blocks edits to .env/.envrc, credentials, secrets, keys (.pem/.key/.p8/.pfx/.jks/.keystore), id_rsa, .aws/.ssh/.gnupg, service-account/gcp json, Config.swift |
-| orchestrator-delegate-guard.sh | PreToolUse (Write\|Edit) | While `/build` active, blocks orchestrator (main-thread) source edits; **session-scoped** (`/tmp/claude-orchestrator-active.$SESSION_ID`) with TTL self-heal |
-| design-scope-guard.sh | PreToolUse (Write\|Edit) | While `/design`'s Step 6 write window is active, confines Write\|Edit calls (not a hard filesystem guarantee) to design artifact paths (`docs/plans/` — where `/design` writes both the draft and its research files — `docs/research/`, a separately allowlisted research-output path not written by `/design`, the plans dir); **session-scoped** (`/tmp/claude-design-active.$SESSION_ID`), same trust class + TTL self-heal as the delegate guard |
-| syntax-check.sh | PostToolUse (Write\|Edit) | Multi-language check (py/js/sh/json/swift), surfaces real errors; never blocks |
-| Notification | Notification event | macOS notification when Claude needs attention (macOS-only, uses `osascript`) |
-
-**How hooks work**:
-- `PreToolUse` hooks run BEFORE a tool executes. Exit 2 = blocked. Exit 0 = allowed.
-- `PostToolUse` hooks run AFTER. Informational only.
-- Hooks load at session start. **Changes require restarting Claude Code.**
-- The delegate guard is session-scoped via `CLAUDE_CODE_SESSION_ID` (matches the hook-stdin `session_id`) and self-heals a stale sentinel after `TTL_MINUTES` (default 90). **Session isolation requires Claude Code ≥ v2.1.132**; below that it falls back to the legacy global path with the TTL as sole guard.
-- `design-scope-guard.sh` mirrors the same session-scoped sentinel pattern, armed/disarmed by `/design` itself around its Step 6 promotion write (TTL 120 min — generous, since the sentinel only needs to survive a single short write window rather than a whole `/build` run).
-- Debug: `claude --debug` | View loaded hooks: `/hooks`
-
----
-
-## Context Window Strategy
-
-The harness is designed to keep the main conversation's context clean:
-
-| What | Where it happens | Tokens in main context |
-|---|---|---|
-| Voice note / spec | User pastes | ~500 |
-| Research (per question) | researcher subagent | ~500-1K (summary only) |
-| Codebase exploration | Explore subagent | ~200-500 (summary only) |
-| Design output | Main thread | ~2K |
-| Implementation | implementer subagent | ~500 (summary only) |
-| Code review | reviewer subagent | ~500 (summary only) |
-| Ship / PR | Main thread | ~1K |
-
-**Full feature cycle**: ~5-10K tokens in main context. Without subagents, research alone can consume 50K+.
-
-**Tips**:
-- Use `/clear` between unrelated tasks
-- For large features: one session per phase
-- The status bar shows context usage — watch for >70%
-
----
-
-## CLAUDE.md (Global Rules)
-
-`~/.claude/CLAUDE.md` contains always-on advisory rules:
-- Feature branches only, conventional commits, co-author line
-- Research-first design: check docs before making architecture decisions
-- Flag unsourced decisions explicitly
-- Context hygiene: use subagents for heavy output
-- Stack preferences: SwiftUI async/await, Python type hints, Next.js strict TS
-
-These have ~70% compliance. For critical rules (branch protection, secrets), hooks provide 100% enforcement.
-
----
-
-## Modifying the Harness
-
-### Add a new hook
-1. Create script in `~/.claude/hooks/`
-2. Add entry to `hooks` in `~/.claude/settings.json`
-3. Restart Claude Code
-
-### Add a new skill
-1. Create `~/.claude/skills/<name>/SKILL.md` with YAML frontmatter
-2. Available immediately (no restart needed)
-
-### Add a new agent
-1. Create `~/.claude/agents/<name>.md` with YAML frontmatter
-2. Available immediately for spawning
-
-### Key frontmatter fields
-- **Skills**: `name`, `description`, `allowed-tools` (pre-approval), `disable-model-invocation`, `argument-hint`
-- **Agents**: `name`, `description`, `model`, `effort` (sets the subagent's reasoning effort tier), `tools`, `disallowedTools`, `maxTurns`, `skills`, `mcpServers`, `memory`, `permissionMode`, `color` (named colors only)
-
----
-
-## Future Expansions
-
-Deferred until 1-2 weeks of use:
-- **Stop hook**: Prompt-type hook checking if Claude explained reasoning
-- **SessionStart hook**: Auto-inject git status, recent commits at session start
-- **Auto-format hook**: Run prettier/black/swiftformat after writes
-- **`/test` skill**: Project-specific test orchestration
-- **`/retro` skill**: Post-merge retrospective generation
-- **Xcode MCP**: `claude mcp add --transport stdio xcode -- xcrun mcpbridge` for SwiftUI previews + diagnostics
-- **XcodeBuildMCP**: Headless builds, tests, simulators via [github.com/getsentry/XcodeBuildMCP](https://github.com/getsentry/XcodeBuildMCP)
-
----
+| `protect-branches.sh` | PreToolUse (Bash) | Blocks a push whose destination is main/master, and any force push |
+| `protect-secrets.sh` | PreToolUse (Write\|Edit\|MultiEdit\|NotebookEdit) | Blocks writes to `.env`, credentials, keys, and similar secret paths |
+| `profile-check.sh` | SessionStart | Warns if the active profile doesn't match `~/.claude-profiles`, or if a `CLAUDE.md` `@import` target is missing |
+
+A hook that exits non-zero is enforced, not advisory — CLAUDE.md conventions
+get followed inconsistently; a `PreToolUse` hook that exits 2 blocks the call
+outright. `claude plugin disable cw@<source>` turns all three off at once.
+
+## Tests
+
+`bash tests/run.sh all` runs everything: hook behavior (`hooks`), file-size
+budgets against the tracked baseline plus the `WORKFLOW.md` and
+description-length caps (`size`), a cross-file phrase-duplication check
+(`dedupe`), the `settings.example.json` / `tests/settings-keys.txt`
+cross-check, and, if `$CW_SCAN_PATTERNS` points at a pattern file, a scan for
+private strings in the tracked tree. Each subcommand also runs standalone
+(`hooks`, `size`, `dedupe`, `scan`), and CI (`.github/workflows/ci.yml`) runs
+the same `all` target on every push and PR.
diff --git a/settings.example.json b/settings.example.json
index 4b06508..32a6c23 100644
--- a/settings.example.json
+++ b/settings.example.json
@@ -1,89 +1,32 @@
 {
-  "_comment_model": "Use a public model alias, never a pinned dated/tagged ID (e.g. NOT 'claude-opus-4-8-20260115[1m]'). See rules/orchestration.md for the alias routing table.",
-  "model": "opus",
-
-  "_comment_enabledMcpjsonServers": "Example only, not live. Uncomment and rename to 'enabledMcpjsonServers' (an array of server names from your .mcp.json) once you've run 'claude mcp add' for the servers you want auto-enabled, e.g. [\"context7\", \"exa\"].",
-
+  "model": "fable",
+  "effortLevel": "high",
+  "plansDirectory": "docs/plans",
   "permissions": {
+    "defaultMode": "auto",
+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Read(**/.envrc)",
+      "Read(~/.ssh/**)",
+      "Read(~/.aws/**)",
+      "Read(~/.config/gcloud/**)"
+    ],
+    "ask": ["Bash(gh pr create *)"],
     "allow": [
-      "Bash(git status)",
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(git diff:*)",
+      "Bash(git status:*)",
       "Bash(git log:*)",
-      "Bash(git branch:*)",
-      "Bash(gh pr:*)",
-      "Bash(gh issue:*)",
-      "Bash(npm install:*)",
-      "Bash(npm test:*)",
-      "WebSearch"
-    ],
-    "defaultMode": "auto"
-  },
-
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash \"${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks/protect-branches.sh\"",
-            "if": "Bash(git *)",
-            "timeout": 5
-          }
-        ]
-      },
-      {
-        "matcher": "Write|Edit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash \"${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks/protect-secrets.sh\"",
-            "timeout": 5
-          },
-          {
-            "type": "command",
-            "command": "bash \"${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks/orchestrator-delegate-guard.sh\"",
-            "timeout": 5
-          },
-          {
-            "type": "command",
-            "command": "bash \"${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks/design-scope-guard.sh\"",
-            "timeout": 5
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Write|Edit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash \"${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks/syntax-check.sh\"",
-            "timeout": 15
-          }
-        ]
-      }
-    ],
-    "Notification": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "_comment": "osascript is macOS-only. The command is guarded with a command -v check so it no-ops gracefully on Linux/other platforms. Cross-platform alternatives: notify-send (Linux) or terminal-notifier (macOS CLI wrapper) — swap the command for your OS.",
-            "type": "command",
-            "command": "command -v osascript >/dev/null 2>&1 && osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"' || true"
-          }
-        ]
-      }
+      "Bash(git diff:*)",
+      "Bash(ls:*)",
+      "Bash(cat:*)"
     ]
   },
-
-  "statusLine": {
-    "_comment": "Reads the adopter's own local ~/.claude.json (or $CLAUDE_CONFIG_DIR/.claude.json) at runtime for account email, model, git branch, context window, and rate-limit usage. Requires jq. Note: the .oauthAccount field read from that JSON is an undocumented internal interface and may break in future Claude Code versions without notice.",
-    "type": "command",
-    "command": "input=$(cat); cfg=\"${CLAUDE_CONFIG_DIR:+$CLAUDE_CONFIG_DIR/.claude.json}\"; cfg=\"${cfg:-$HOME/.claude.json}\"; email=$(jq -r '.oauthAccount.emailAddress // empty' \"$cfg\" 2>/dev/null); model=$(echo \"$input\" | jq -r '.model.display_name // \"?\"'); branch=$(echo \"$input\" | jq -r '.git.branch // empty'); used=$(echo \"$input\" | jq -r '.context_window.used_percentage // empty'); in_tok=$(echo \"$input\" | jq -r '.context_window.total_input_tokens // empty'); out_tok=$(echo \"$input\" | jq -r '.context_window.total_output_tokens // empty'); five=$(echo \"$input\" | jq -r '.rate_limits.five_hour.used_percentage // empty'); week=$(echo \"$input\" | jq -r '.rate_limits.seven_day.used_percentage // empty'); bar=''; if [ -n \"$used\" ]; then u=$(printf '%.0f' \"$used\"); filled=$((u / 10)); empty=$((10 - filled)); bar='['; i=0; while [ $i -lt $filled ]; do bar=\"${bar}█\"; i=$((i+1)); done; i=0; while [ $i -lt $empty ]; do bar=\"${bar}░\"; i=$((i+1)); done; bar=\"${bar}] ${u}%\"; fi; tok=''; if [ -n \"$in_tok\" ]; then in_k=$((in_tok / 1000)); out_k=$((out_tok / 1000)); tok=\"${in_k}K in / ${out_k}K out\"; fi; out=\"${email:+$email | }$model\"; [ -n \"$branch\" ] && out=\"$out | $branch\"; [ -n \"$bar\" ] && out=\"$out | $bar\"; [ -n \"$tok\" ] && out=\"$out | $tok\"; [ -n \"$five\" ] && out=\"$out | 5h: $(printf '%.0f' \"$five\")%\"; [ -n \"$week\" ] && out=\"$out | 7d: $(printf '%.0f' \"$week\")%\"; echo \"$out\""
+  "autoMode": {
+    "allow": ["$defaults"]
+  },
+  "enabledPlugins": {
+    "typescript-lsp@claude-plugins-official": true,
+    "pyright-lsp@claude-plugins-official": true,
+    "rust-analyzer-lsp@claude-plugins-official": true
   }
 }
diff --git a/tests/settings-keys.txt b/tests/settings-keys.txt
new file mode 100644
index 0000000..7794fbe
--- /dev/null
+++ b/tests/settings-keys.txt
@@ -0,0 +1,145 @@
+advisorModel
+agent
+agentPushNotifEnabled
+allowAllClaudeAiMcps
+allowManagedHooksOnly
+allowManagedMcpServersOnly
+allowManagedPermissionRulesOnly
+allowedChannelPlugins
+allowedHttpHookUrls
+allowedMcpServers
+alwaysThinkingEnabled
+apiKeyHelper
+askUserQuestionTimeout
+attribution
+autoCompactEnabled
+autoCompactWindow
+autoConnectIde
+autoContinueAtUsageLimit
+autoInstallIdeExtension
+autoMemoryDirectory
+autoMemoryEnabled
+autoMode
+autoScrollEnabled
+autoUpdatesChannel
+availableModels
+awaySummaryEnabled
+awsAuthRefresh
+awsCredentialExport
+axScreenReader
+bashEditDiffEnabled
+bashOutputMaxChars
+blockedMarketplaces
+browserExternalPageTools
+channelsEnabled
+claudeMd
+claudeMdExcludes
+cleanupPeriodDays
+companyAnnouncements
+copyOnSelect
+crossSessionInbound
+defaultShell
+deniedMcpServers
+desktopSessionCleanupPeriodDays
+dialogExpiry
+diffTool
+disableAgentView
+disableAllHooks
+disableArtifact
+disableAutoMode
+disableBrowserExternalNavigation
+disableBundledSkills
+disableClaudeAiConnectors
+disableCommandPluginSources
+disableDeepLinkRegistration
+disableDesktopLocalSessions
+disableMobileSimulatorTools
+disableRemoteControl
+disableSideloadFlags
+disableSkillShellExecution
+disableWorkflows
+disabledMcpjsonServers
+editorMode
+effortLevel
+emojiCompletionEnabled
+enableAllProjectMcpServers
+enableArtifact
+enableWorkflows
+enabledMcpjsonServers
+enabledPlugins
+enforceAvailableModels
+env
+externalEditorContext
+extraKnownMarketplaces
+fallbackModel
+fastMode
+fastModePerSessionOptIn
+feedbackDrafts
+feedbackSurveyRate
+fileCheckpointingEnabled
+fileSuggestion
+footerLinksRegexes
+forceLoginGatewayUrl
+forceLoginMethod
+forceLoginOrgUUID
+forceRemoteSettingsRefresh
+gatewayInternalNetworks
+gcpAuthRefresh
+hooks
+httpHookAllowedEnvVars
+includeCoAuthoredBy
+includeGitInstructions
+inputNeededNotifEnabled
+isolatePeerMachines
+keybindingFlavor
+language
+managedMcpServers
+managedSourcesBehavior
+maxEffortLevel
+minimumVersion
+model
+modelOverrides
+modelPicker
+modelPricing
+modelSettings
+otelHeadersHelper
+outputStyle
+parentSettingsBehavior
+permissionExplainerEnabled
+permissions
+plansDirectory
+pluginConfigs
+pluginSuggestionMarketplaces
+pluginTrustMessage
+policyHelper
+prUrlTemplate
+preferredNotifChannel
+prefersReducedMotion
+processWrapper
+promptCacheTtl
+promptSuggestionEnabled
+remote
+remoteControlAtStartup
+requiredMaximumVersion
+requiredMinimumVersion
+respectGitignore
+respondToBashCommands
+sandbox
+showClearContextOnPlanAccept
+showThinkingSummaries
+showTurnDuration
+skillListingBudgetFraction
+skillListingMaxDescChars
+skillOverrides
+skipAutoPermissionPrompt
+skipDangerousModePermissionPrompt
+skipWebFetchPreflight
+spellcheck
+spinnerTipsEnabled
+spinnerTipsOverride
+spinnerVerbs
+sshConfigs
+sshHostAllowlist
+statusLine
+strictKnownMarketplaces
+strictPluginOnlyCustomization

From bb85af9c4aacbde5df1abc50f55d02ee97f50a29 Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Fri, 18 Sep 2026 13:04:00 +0100
Subject: [PATCH 08/24] fix(settings): enable typescript, pyright and swift LSP
 plugins in the example

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md             | 2 +-
 settings.example.json | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 0cee75c..8062650 100644
--- a/README.md
+++ b/README.md
@@ -145,7 +145,7 @@ Use `settings.example.json` as a starting point, not a drop-in replacement —
 copy it to `settings.json` and adapt it. It sets `defaultMode: "auto"`,
 `effortLevel: "high"`, `plansDirectory: "docs/plans"`, a short generic
 `permissions.deny`/`allow`/`ask` set, `autoMode.allow: ["$defaults"]`, and
-`enabledPlugins` for the official TypeScript, Python, and Rust LSP plugins
+`enabledPlugins` for the official TypeScript, Python, and Swift LSP plugins
 from the `claude-plugins-official` marketplace. It carries no `hooks` key —
 this plugin registers its own hooks, and a plugin hook and a settings hook
 with the same command both fire, so don't add them again in `settings.json`.
diff --git a/settings.example.json b/settings.example.json
index 32a6c23..0175019 100644
--- a/settings.example.json
+++ b/settings.example.json
@@ -27,6 +27,6 @@
   "enabledPlugins": {
     "typescript-lsp@claude-plugins-official": true,
     "pyright-lsp@claude-plugins-official": true,
-    "rust-analyzer-lsp@claude-plugins-official": true
+    "swift-lsp@claude-plugins-official": true
   }
 }

From 5e5c4d32a93ffec2883e9e08488e35ac5787e6ae Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Mon, 21 Sep 2026 17:33:26 +0100
Subject: [PATCH 09/24] docs(fixups-1-0-0): design

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/plans/fixups-1-0-0.md | 669 +++++++++++++++++++++++++++++++++++++
 1 file changed, 669 insertions(+)
 create mode 100644 docs/plans/fixups-1-0-0.md

diff --git a/docs/plans/fixups-1-0-0.md b/docs/plans/fixups-1-0-0.md
new file mode 100644
index 0000000..31a8768
--- /dev/null
+++ b/docs/plans/fixups-1-0-0.md
@@ -0,0 +1,669 @@
+# fixups-1-0-0 — pre-release fix-ups for cw 1.0.0
+
+Slug `fixups-1-0-0`. Branch `feat/cw-plugin` (the 1.0.0 release branch, eight
+commits over `main`, not pushed). Each fix-up is one fresh commit; no version
+change (1.0.0 is unreleased, the README changelog entry already describes it).
+
+## Context
+
+The pre-release validation of cw 1.0.0 (automated rounds in throwaway repos
+with a bare origin, then the maintainer's profile migrated onto the plugin)
+left three findings. Fixing them now, before the branch is pushed and the PR
+opened, keeps the first release free of known wrong guidance and gives the
+release gate a mechanical check on the one rule the round is about.
+
+1. **Double commit trailer on the orchestrator's own commit.** In validation
+   round 2 the `docs(<slug>): design` commit that `/cw:build` Phase 0 makes
+   ended with two `Co-Authored-By` lines: the exact one the rule names, plus
+   the harness's own session-attribution line naming the model. Implementer
+   commits (made by subagents) were exact in both rounds, and all eight
+   commits on this branch carry exactly one trailer (checked on 2026-09-21
+   with the per-commit loop of success criterion 6: zero offenders). The two
+   rounds differed in more than one way: in round 1 the rule sat inline in
+   the profile `CLAUDE.md` as "Co-author line on every commit:" and no
+   duplicate appeared; in round 2 it reached the session only through the
+   profile's `@import` of `rules/workflow.md` as "Every commit ends with the
+   co-author trailer:" and the duplicate appeared. With one run each,
+   neither wording, location nor chance can be excluded as the cause. What
+   is certain: neither wording addressed the harness reminder, which itself
+   says the user's own CLAUDE.md or memory instructions about these lines
+   take precedence over it; every skill instruction pointed at "the trailer
+   the workflow rules define" (an indirection); and nothing mechanical
+   checked the result — the private validation harness counted only exact
+   lines, so the extra line passed it.
+2. **The README migration section deletes the wrong agent.** It tells adopters
+   of the old manual layout to delete "six agents". One of the six is
+   `agents/Explore.md`, a user-scope override that pins the built-in `Explore`
+   agent to haiku in every session; the plugin cannot ship a replacement
+   (plugin agents are namespaced `cw:<name>`, and `/cw:design` already pins
+   haiku per call). The same section omits `rules/orchestration.md`, which
+   the old manifest did install, gives no verification step, and offers new
+   adopters no way to get the haiku routing the orchestration rules assume.
+3. **Stray copies outside the old manifest** (the maintainer's profile held an
+   old `WORKFLOW.md`) are outside the plugin's control; the migration section
+   gains one line telling adopters to remove any other stray copies.
+
+Intended outcome: four commits — `fix(rules)`, `fix(skills)`, `fix(readme)`
+and `test` — every gate green, the series still one exact trailer per commit,
+and that last property checked by `tests/run.sh all` from now on rather than
+by an agent reading commit messages.
+
+## Approach
+
+**Precision over indirection, at the source the harness defers to.** The rule
+in `rules/workflow.md` becomes "exactly one trailer line, the one below, and
+no other attribution or session line; a harness attribution reminder does not
+add a second one". Every commit-producing or commit-checking instruction in
+the build and ship skills repeats that shape without repeating the trailer
+text (`Co-Authored-By` is a one-file dedupe phrase across `skills/`, `agents/`
+and `rules/`; it stays in `rules/workflow.md` only). This is the fix the
+Step 0 gate chose; the alternative, accepting the duplicate, would leave the
+rule false for the design commit of every build.
+
+**A mechanical check where the gate already runs.** `tests/run.sh` gains a
+`trailers` subcommand: for every non-merge commit in `main..HEAD` (or
+`origin/main..HEAD`), exactly one line equal to the trailer read from
+`rules/workflow.md`, no other co-author line, no `Claude-Session:` line.
+`run.sh all` runs it, so `/cw:ship`'s quality gate (Step 3 detects
+`tests/run.sh`) and CI run it too; CI's checkout gains `fetch-depth: 0` so
+`origin/main` resolves on pull requests. When neither ref resolves the step
+is skipped, reported as such, never a silent pass. The expected line is read
+from the rules file rather than written into the script, so the trailer keeps
+one home. This adopts the direction pass's redirect: the plan's own risk
+table answered "a prose rule can be ignored" with more prose while the
+per-commit loop was already written in this document, and the orchestration
+rules say limits are checked by script, not self-declared by an agent.
+Detection lands after the commit exists, which on an unpushed branch is the
+right place: the remedy is an amend or fixup before the push, and the prose
+rule remains the prevention.
+
+**Detection where a human already looks, too.** `/cw:ship` Step 2 verifies
+the series before any push; its bullet now names a second co-author line or a
+session line as a malformed message to report (with a rebase suggestion,
+never a rewrite). `/cw:build` Phase 3's reviewer commit check says the same
+for task commits.
+
+**README: keep-versus-delete per artifact, plus the missing override.** The
+migration section lists every item the old manifest installed, says keep or
+delete for each, keeps the double-firing-hooks warning, and ends with a
+verification step including `/hooks`. The agents section explains the
+built-in `Explore` and gives a copyable user-scope override on haiku, so a
+fresh adopter can reach the routing the orchestration rules assume. The test
+section names the new check.
+
+**Dropped from this round, with reasons.** (a) An `attribution` block in
+`settings.example.json` (`commit` set to the rule's trailer, `sessionUrl`
+off): the keys are documented (Research §2) but the mechanism is inferred,
+two reported bugs surround them, this branch would not exercise the setting,
+and it would give the trailer a third literal home that nothing pins to the
+rules file. The maintainer can set the two keys in the live profile settings
+during the pending hands-on check and, if that demonstrably removes the
+second line, a later round ships it in the example with evidence. (b) The
+same one-line sharpening of this repo's own `CLAUDE.md` trailer bullet: the
+workflow rules keep process-rule edits out of a feature PR as their own
+change, and `/cw:compound` after the PR is the path for it. Until then the
+imported rule and the orchestrator note below cover this repo's commits.
+
+**Surfaced at the checkpoint, not decided here.** The direction pass asks
+whether the rule's *location* is the real variable — an `@import`ed rules
+file versus a line inline in the profile `CLAUDE.md` — and suggests showing
+the one-trailer-line rule inline in the README's profile template next to
+the two imports. That conflicts with the plugin's "one home per rule"
+decision (`89b8a90`), so it is the maintainer's call; the mechanical check
+makes the question less load-bearing, and success criterion 9 specifies the
+validation re-run so that it varies only the wording (import-only profile)
+and can therefore tell the two apart. Also logged for the next fix-up round
+rather than folded into T1, to keep that commit atomic: `rules/workflow.md:16`
+says `/cw:build` reads the `## Tasks` section, while the design skill
+mandates a level-1 `# Tasks` heading.
+
+## Files to create/modify
+
+| Path | Change |
+|---|---|
+| `rules/workflow.md` | Lines 9–10: the trailer bullet becomes the "exactly one trailer line … no other attribution or session line" wording (exact text under T1). Stays ≤ 40 lines. |
+| `skills/build/SKILL.md` | Phase 0 step 4 (design commit), Phase 2 item 6 (implementer commit instruction), Phase 3 commit check: same shape, no trailer text. Stays ≤ 200 lines. |
+| `skills/ship/SKILL.md` | Step 2 first bullet: "exactly the one trailer line … a second co-author line or a session line is a malformed message"; Step 2 last bullet (the `docs(<slug>): design` offer) and Step 4 (the `docs:` commit): "the same single trailer line". Stays ≤ 150 lines. |
+| `README.md` | "Migration from the old installer" rewritten as a keep/delete list with a verify step; a paragraph and a copyable `Explore` override after the Agents table; one clause in "Running the tests" naming the trailer check. |
+| `tests/run.sh` | New `cmd_trailers` (spec under T4), wired into `usage`, the header comment, `main` and `cmd_all` (PASS / FAIL / SKIPPED, like `scan`). Bash 3.2 and shellcheck clean like the rest of the file. |
+| `.github/workflows/ci.yml` | `actions/checkout@v4` gains `with: fetch-depth: 0` in the ubuntu job so `origin/main` resolves and the trailer check runs on pull requests. |
+| `docs/plans/fixups-1-0-0.md` | This plan; `/cw:build` commits it as `docs(fixups-1-0-0): design`. |
+
+Untouched on purpose: `agents/implementer.md:30` ("whatever trailer the
+project's workflow rules define") — implementer commits were exact in both
+validation rounds and the orchestrator's Phase 2 prompt now carries the
+precise wording; `CLAUDE.md` and `settings.example.json` (dropped, see
+Approach); `WORKFLOW.md:22` (already says `Explore` (haiku));
+`.claude-plugin/plugin.json` (version stays 1.0.0; a first release needs no
+bump); the ship skill's PR body template (it carries no attribution footer,
+no rule governs PR descriptions, and `attribution.pr` stays at its default);
+the macOS CI job (it runs only the hooks under bash 3.2, and `run.sh` must
+merely keep parsing there).
+
+## Dependencies
+
+None. No packages, keys or services. `tests/run.sh` keeps its existing
+toolset (git, grep, sed, jq for other subcommands).
+
+## Risks & mitigations
+
+- **`/cw:build` Phase 0 commits this plan before T1 lands**, in a session
+  that loaded the old rule wording at start — the exact conditions of
+  finding 1, and the series check would then fail on the design commit while
+  ship forbids rewriting a series. Mitigation: the note to the orchestrator
+  at the head of the task list (it reads this file in Phase 0 step 1, before
+  the commit in step 4) states the one-trailer-line requirement and a
+  check-and-amend step while the design commit is still `HEAD`, before any
+  task commit exists — a plain amend of the newest commit, never a rewrite of
+  a series. T5 and `run.sh trailers` assert the whole series after.
+- **A prose rule can still be ignored by a session.** Open issue #92169
+  reports exactly that. Prevention is the rule naming the reminder and
+  denying it a second line; detection is now `tests/run.sh trailers` in the
+  ship gate and CI, plus ship Step 2 and the reviewer commit check for the
+  human reading. Remedy on an unpushed branch: amend or autosquash fixup of
+  the offending commit. A git `commit-msg` hook would prevent rather than
+  detect, but a plugin cannot install git hooks into adopters' repos; logged
+  as accepted residual risk.
+- **Location, not wording, might be the real variable** (direction pass,
+  surfaced above). If the validation re-run of criterion 9 — import-only
+  profile, new wording — still doubles the line, that is evidence for
+  location, and the inline-rule option goes back on the table with data; the
+  mechanical check catches the result either way.
+- **Wording trips a hygiene gate.** `tests/run.sh all` (size caps, byte
+  baseline, dedupe phrases, settings-keys cross-check) and the CI greps
+  (whole-word `NEVER|ALWAYS|MUST|CRITICAL`, banned coordination phrases,
+  `under 50 lines`, LICENSE-derived name) run in every task's verification,
+  locally, before the commit.
+- **"Edits to process rules stay out of the feature PR."** That rule targets
+  a project's own process rules riding along with feature code. Here
+  `rules/workflow.md` is shipped product on the plugin's release branch, and
+  the edit is its own `fix(rules):` commit; this repo's own `CLAUDE.md` is
+  left to `/cw:compound` after the PR for exactly that reason. Accepted
+  risk, logged here.
+- **The trailer check reads its expectation from `rules/workflow.md`.** If
+  the rules file ever loses the two-space-indented `Co-Authored-By:` line,
+  the check fails closed with a message naming the rules file (in-repo, so
+  fail-closed is right). A missing `main`/`origin/main` ref fails open with a
+  `SKIPPED` line, since that is an environment gap, not a rule violation;
+  CI's `fetch-depth: 0` removes that gap for pull requests.
+- **Merge commits in `main..HEAD`.** Excluded with `--no-merges`; a merge of
+  `main` into a feature branch carries no trailer and is not a task commit.
+- **Built-in agent override claims.** The user-scope `Explore` override with
+  its own `model` is documented (Research §2); that a plugin cannot take the
+  built-in's place is inferred from documented namespacing and precedence.
+  The README states only the documented parts and gives the override as a
+  snippet, noting that it replaces the built-in prompt.
+
+## Success criteria
+
+All commands run from the repo root; each exits 0.
+
+1. Rule wording: `grep -q 'exactly one trailer line' rules/workflow.md && test "$(grep -c 'Co-Authored-By' rules/workflow.md)" = 1 && test "$(wc -l < rules/workflow.md)" -le 40`
+2. Skill wording (whitespace-squeezed, so a line wrap cannot hide a phrase), no indirection left, no trailer text leak: `test "$(tr -s '[:space:]' ' ' < skills/build/SKILL.md | grep -o 'exactly the one trailer line' | wc -l | tr -d ' ')" = 2 && test "$(tr -s '[:space:]' ' ' < skills/ship/SKILL.md | grep -o 'exactly the one trailer line' | wc -l | tr -d ' ')" = 1 && test "$(tr -s '[:space:]' ' ' < skills/ship/SKILL.md | grep -o 'same single trailer line' | wc -l | tr -d ' ')" = 2 && ! grep -q 'the trailer the workflow rules define' skills/build/SKILL.md skills/ship/SKILL.md && ! grep -q 'Co-Authored-By' skills/build/SKILL.md skills/ship/SKILL.md`
+3. README, new-text anchors plus regression guards (the negative grep on `delete those user-scope copies` holds only after the rewrite; the other negative greps, `migration` and `1.0.0` are pre-satisfied today and only guard against regressions): `grep -q 'agents/Explore.md' README.md && grep -q 'the old manifest put five skills' README.md && grep -q 'claude plugin list' README.md && grep -q 'hook once' README.md && grep -q 'ships no agent by that name' README.md && grep -q '^name: Explore' README.md && grep -q '^tools: Read, Glob, Grep$' README.md && tr -s '[:space:]' ' ' < README.md | grep -q 'per-commit trailer check' && ! grep -q 'delete those user-scope copies' README.md && grep -qi migration README.md && grep -q '1.0.0' README.md && ! grep -qE 'install.sh|merge-settings|/setup' README.md WORKFLOW.md && ! grep -rnE '/(Users|home)/' README.md`
+4. Gates: `bash tests/run.sh all && shellcheck -x hooks/*.sh tests/run.sh && claude plugin validate .` — and the `all` summary contains `all: trailers: PASS`.
+5. CI checks, local replica of `.github/workflows/ci.yml` (its manifest `jq empty`, hygiene greps and LICENSE-name gate; shellcheck, `run.sh all` and `plugin validate` are criterion 4) plus the `</content>` residue check CI does not run: `jq empty .claude-plugin/plugin.json .claude-plugin/marketplace.json hooks/hooks.json && ! git grep -nwE 'NEVER|ALWAYS|MUST|CRITICAL' -- skills agents rules && ! git grep -niE 'opus needs|do not trust|be decisive|read all files fresh|claude-design-active|claude-orchestrator-active' -- skills agents rules && ! git grep -niE 'under 50 lines' -- skills agents rules && ! git grep -nE '^(disallowedTools|permissionMode|mcpServers|hooks):' -- agents && test "$(for f in agents/*.md; do for k in model tools effort maxTurns; do grep -q "^$k:" "$f" || echo "$f:$k"; done; done | wc -l | tr -d ' ')" = 0 && ! git grep -niE '~/.claude/plans|gitattributes|linguist|git clean' -- skills && grep -q haiku skills/design/SKILL.md && OWNER=$(sed -n 's/^Copyright (c) [0-9]* //p' LICENSE | cut -d' ' -f1) && test -n "$OWNER" && ! git grep -qi "$OWNER" -- skills agents rules hooks tests WORKFLOW.md CLAUDE.md docs && ! grep -rn '</content>' skills agents rules README.md tests/run.sh`
+6. Series, content-exact and per commit — the specification `run.sh trailers` implements: `test "$(for c in $(git rev-list --no-merges main..HEAD); do b=$(git log -1 --format=%B "$c"); { test "$(printf '%s\n' "$b" | grep -c '^Co-Authored-By: Claude <noreply@anthropic.com>$')" = 1 && test "$(printf '%s\n' "$b" | grep -ci '^Co-Authored-By:')" = 1 && ! printf '%s\n' "$b" | grep -q '^Claude-Session:'; } || echo "$c"; done | wc -l | tr -d ' ')" = 0 && bash tests/run.sh trailers` — every commit in the range, including the new fix-ups and the `docs(fixups-1-0-0): design` commit, carries the rule's exact trailer once, no other co-author line and no session line. (Run on the eight pre-existing commits on 2026-09-21: zero offenders.)
+7. Each task's commit subject appears exactly once in `git log --format=%s main..HEAD`.
+8. The trailer check discriminates (T4's own verification runs this on a scratch repo): an exact single trailer passes; a second co-author line, a `Claude-Session:` line, or a model-named single trailer each exit non-zero with a `trailers: VIOLATION` line naming the commit; a clone where neither `main` nor `origin/main` resolves exits 3 and prints `trailers: skipped`, and the `all` summary there carries `all: trailers: SKIPPED` (the scratch clone lacks the hooks and test fixtures, so `all` as a whole fails there for unrelated reasons; only the summary line is asserted).
+9. End-to-end, outside this plan, one variable at a time: the maintainer re-runs the private build-and-ship validation round with the import-only profile (the rule reaching the session through `@import` of `rules/workflow.md`, exactly as in round 2, no inline trailer line in any CLAUDE.md the round loads, no `attribution` keys set). Expected: the `docs(two-task): design` commit shows one `Co-Authored-By` line and `/cw:ship`'s Step 2 reports nothing. A duplicate there is evidence that location, not wording, is the variable, and reopens the inline-rule option with data.
+
+## Research
+
+### Codebase (Explore, haiku, 2026-09-21)
+
+Verbatim findings, file:line.
+
+- Trailer wording sites: `skills/build/SKILL.md:52` ("with the trailer the
+  workflow rules define"), `:85` ("ending with the trailer the workflow rules
+  define"), `:127-128` (reviewer commit check: "with the project's trailer");
+  `skills/ship/SKILL.md:42` ("carrying the trailer the workflow rules
+  define"), `:53` ("with the same trailer"), `:84` ("trailer as the rest of
+  the series"); `rules/workflow.md:9-10` ("Every commit ends with the
+  co-author trailer: / Co-Authored-By: Claude <noreply@anthropic.com>");
+  `agents/implementer.md:30` ("whatever trailer the project's workflow rules
+  define"); `CLAUDE.md:10-11` (project file: "Every commit ends with:" and
+  the trailer); `tests/dedupe-phrases.txt:3` = `Co-Authored-By`;
+  `tests/settings-keys.txt:14` = `attribution` (listed, unused by
+  `settings.example.json`). The pre-plugin profile `CLAUDE.md` (round 1)
+  said "Co-author line on every commit:" above the same trailer.
+- Explore sites: `skills/design/SKILL.md:58-61` (built-in agent, `model`
+  pinned to `haiku` per call); `WORKFLOW.md:22` ("spawns `Explore` (haiku)");
+  `rules/orchestration.md:9` (haiku tier); `.github/workflows/ci.yml:59-60`
+  requires the word `haiku` in `skills/design/SKILL.md`. No `agents/Explore.md`
+  in the plugin; the pre-plugin one (`git show main:agents/Explore.md`) was a
+  34-line user-scope agent: `name: Explore`, `model: haiku`, tools Read,
+  Glob, Grep, and a short read-only method.
+- Migration sites: `README.md:171-177` ("five skills, six agents, five hooks";
+  "delete those user-scope copies, and remove their `hooks` entries");
+  `README.md:9,100,154` reference `rules/orchestration.md` as a shipped file;
+  `README.md:196-206` "Running the tests" lists hooks, size, dedupe and the
+  settings cross-check; `README.md:89-90` end the Agents table, line 90 blank.
+- Old installer manifest (`git show main:scripts/manifest.txt`):
+  `agents/Explore.md`, `agents/design-reviewer.md`,
+  `agents/direction-reviewer.md`, `agents/implementer.md`,
+  `agents/researcher.md`, `agents/reviewer.md`, `hooks/design-scope-guard.sh`,
+  `hooks/orchestrator-delegate-guard.sh`, `hooks/protect-branches.sh`,
+  `hooks/protect-secrets.sh`, `hooks/syntax-check.sh`,
+  `rules/orchestration.md`, and the five `skills/*/SKILL.md`. So "six agents,
+  five hooks, five skills" is right and `rules/orchestration.md` is the
+  missing item; three of the five old hooks no longer exist in the plugin.
+- Test runner (`tests/run.sh`, 800 lines, `#!/bin/bash`, header: "Must work
+  on macOS system bash 3.2 and bash 5, BSD and GNU coreutils: no
+  mapfile/readarray, no ${var,,}, no associative arrays, no sed -i without a
+  suffix, no grep -P. Deliberately no `set -u`"): `usage()` lists
+  `{hooks|size|dedupe|scan|all}`; `main()` dispatches by first word;
+  `cmd_all()` runs `cmd_hooks`, `cmd_size`, `cmd_dedupe`,
+  `check_settings_keys`, then `cmd_scan` only when `CW_SCAN_PATTERNS` is set
+  (else prints `all: scan: skipped (...)` and records `SKIPPED`), builds a
+  `summary` of `all: <step>: PASS|FAIL|SKIPPED` lines and returns 1 on any
+  FAIL. `ROOT` is derived from the script's own location. Size caps 150
+  lines per file in `skills/`, `agents/`, `rules/`, 200 for the design and
+  build skills, `WORKFLOW.md` ≤ 200, skill `description`+`when_to_use` ≤ 1536
+  chars; total byte budget `BASELINE_BYTES=73738` for skills+agents+rules
+  (`bash tests/run.sh size` on 2026-09-21: 54112 bytes, 73.4%); dedupe = each
+  phrase in `tests/dedupe-phrases.txt` in at most one file across `skills/`,
+  `agents/`, `rules/` (case-insensitive fixed string); settings-keys =
+  top-level keys of `settings.example.json` ⊆ `tests/settings-keys.txt`.
+  README, CLAUDE.md, tests/ and .github/ are in no `run.sh` scope.
+- CI (`.github/workflows/ci.yml`): ubuntu job — `actions/checkout@v4` with
+  no `fetch-depth` (shallow, so no `main`/`origin/main` ref), `shellcheck -x
+  hooks/*.sh tests/run.sh`, `jq empty` on the three JSON files, `bash
+  tests/run.sh all`, hygiene greps over `skills agents rules` (banned phrases
+  `opus needs|do not trust|be decisive|read all files fresh|
+  claude-design-active|claude-orchestrator-active`, whole-word
+  `NEVER|ALWAYS|MUST|CRITICAL`, `under 50 lines`, disallowed agent
+  frontmatter keys, required agent keys `model tools effort maxTurns`,
+  internal-path references in skills, the `haiku` word in the design skill,
+  the LICENSE-derived name absent from prompts and docs), then `claude
+  plugin validate .`; macOS job re-runs `run.sh hooks` under bash 3.2.
+- Current sizes: `skills/build/SKILL.md` 179, `skills/ship/SKILL.md` 118,
+  `rules/workflow.md` 36, `README.md` 217, `WORKFLOW.md` 130, `CLAUDE.md` 17.
+- Version: `.claude-plugin/plugin.json:3` = `1.0.0`; `README.md:210` = `### 1.0.0`.
+- Recent intent: `aab9b0b refactor(skills)`, `89b8a90 refactor(rules): one
+  home per rule`, `ddccf56 docs: plugin install story`, `bb85af9
+  fix(settings)` — the lean rewrite that introduced the indirection "the
+  trailer the workflow rules define" (the trailer text moved from inline
+  skill prose to the rules file to satisfy the one-file dedupe rule).
+
+### Docs and API currency (cw:researcher, sonnet, 2026-09-21; installed CLI 2.1.278)
+
+- **`attribution` settings.** Documented on the settings reference
+  (https://code.claude.com/docs/en/settings-reference, fetched directly this
+  session): `attribution.commit` — "Change or hide the trailer Claude Code
+  adds to commits"; `attribution.pr` — "Change or hide the attribution line
+  in pull request descriptions"; `attribution.sessionUrl` — "Omit the
+  claude.ai session link from cloud and Remote Control commits";
+  `includeCoAuthoredBy` — "Deprecated; use `attribution` to hide or change
+  commit and PR attribution". Confidence high for those four rows. The
+  researcher also quoted "`commit` | Attribution for git commits, including
+  any trailers. Empty string hides commit attribution" and "The `attribution`
+  setting takes precedence over the deprecated `includeCoAuthoredBy`
+  setting", attributed to the settings page
+  (https://code.claude.com/docs/en/settings). That page was restructured:
+  today it covers files and precedence only (fetched twice on 2026-09-21,
+  zero matches for "attribution"); the quoted rows match an earlier version
+  of it, as reproduced in issues #69614 and #19176, and issue #45137 shows
+  `commit` handled as a string template in the CLI. So the two sentences are
+  historical rather than current docs, consistent with the reference rows
+  above. `attribution.commit` is the template for the trailer the harness
+  adds (that the reminder text is rendered from it is inferred), and the
+  `Claude-Session:` line is a separate switch (`sessionUrl`), only emitted in
+  cloud and Remote Control sessions — which includes a local session followed
+  from another device. Used here only to justify dropping the settings task
+  and to suggest a profile-side trial during the hands-on check.
+- **Known harness bugs around these keys.** Issue #45137 (2026-04, self-
+  reported across several versions): an empty `attribution.commit` did not
+  stop the co-author trailer because a hardcoded prompt block asked for it;
+  issue #77830 / #41873: an empty `commit` template did not suppress the
+  session line, only `attribution.sessionUrl: false` (or
+  `CLAUDE_CODE_SUPPRESS_SESSION_ATTRIBUTION=1`) did. Confidence medium-high
+  for the pattern; not reproduced on 2.1.278.
+- **Precedence of a CLAUDE.md rule over the reminder** is stated by the
+  reminder text itself (verified live this session: "the user's own
+  instructions about these lines, such as a CLAUDE.md or memory rule, take
+  precedence over this reminder, but do not add attribution lines this
+  reminder leaves out"), not by a docs page. Open issue #92169 (2026-09-04, no
+  maintainer reply) reports the model treating the reminder as outranking a
+  standing CLAUDE.md preference — the same symptom as finding 1. A web
+  summary claiming a fix in 2.1.275 could not be found in the raw CHANGELOG:
+  unverified, treated as false. Whether an `@import`ed rules file reads as
+  "the user's own CLAUDE.md" to the model is undocumented; the import is
+  presented to the model under the CLAUDE.md heading, which is the plan's
+  working assumption and the thing criterion 9 tests.
+- **Agent precedence and the built-in `Explore`.** Sub-agents doc
+  (https://code.claude.com/docs/en/sub-agents): "A user or project subagent
+  named `Explore` overrides the built-in and keeps its own `model` field, so
+  define one with `model: haiku` to keep exploration on a lower-cost model."
+  Resolution order, highest first: managed settings, `--agents`, project
+  `.claude/agents/`, user `~/.claude/agents/`, a plugin's `agents/`. Plugins
+  reference (https://code.claude.com/docs/en/plugins-reference): plugin
+  agents load under their scoped name, "`agents/reviewer.md` in a plugin
+  named `my-plugin` loads as `my-plugin:reviewer`". Whether a plugin agent
+  could replace a built-in is not stated; namespacing plus lowest precedence
+  make it the safe reading that it cannot. Confidence high for the user-scope
+  override, low (inferred) for the plugin limit — the README wording states
+  only the documented parts.
+- **Do subagents see the reminder?** Docs: a non-fork subagent gets "the
+  agent's own prompt plus environment details that Claude Code appends, not
+  the Claude Code system prompt". Issue #77830 reports the session-link
+  directive riding in the Bash tool description for subagents too. Not
+  documented either way; consistent with the observed asymmetry (orchestrator
+  doubled, implementers exact).
+- **Version.** `plugin.json` `version` is optional semver; when set, users
+  get updates only when the string changes (plugin-marketplaces doc). No
+  bump is required before a first release; fix-ups before 1.0.0 stay 1.0.0.
+
+### Best practices (cw:researcher, sonnet, 2026-09-21)
+
+- **Git and GitHub do not dedupe raw trailers.** `git interpret-trailers
+  --if-exists` (default `addIfDifferentNeighbor`) only acts when something
+  invokes it; a message typed with two `Co-Authored-By` lines keeps both
+  (https://git-scm.com/docs/git-interpret-trailers). GitHub renders one
+  co-author avatar per line; with the `noreply@anthropic.com` address it
+  resolves to no account, so the duplicate is cosmetic, not an identity
+  problem (dev-common issue #259, 2026-09-21; Crash Override knowledge base,
+  2026-05). Same-email-different-name collapsing is undocumented.
+- **A checked-in prose rule is the practitioner-standard fix.** One
+  organisation resolved the identical fleet-wide symptom with a CLAUDE.md
+  rule alone, forward-only, no hook and no history rewrite, reasoning that
+  "the harness's own instruction says a user's CLAUDE.md or memory rule takes
+  precedence over it. So a checked-in rule is both correct and sufficient"
+  (dev-common #259). A peer project hit the failure mode this plan avoids:
+  two governance texts prescribing different literal strings for the same
+  line, "a dev receiving both cannot satisfy either" — pick a side in the
+  governance text (objectstack #19202, 2026-09-19). Adopted for the wording;
+  the plan adds a mechanical check on top because the orchestration rules
+  require limits to be checked by script, and because the plan's own
+  validation harness missed the duplicate by counting exact lines only.
+- **Deterministic enforcement exists but sits in git, not in prompts:** a
+  `commit-msg` hook stripping or normalising trailers (e.g. `sed
+  '/^Co-Authored-By:.*<noreply@anthropic.com>/d'`) is the only mechanism with
+  documented reliability (issue #45137 workaround; Crash Override). A plugin
+  cannot install git hooks into adopters' repos; a Claude `PreToolUse` hook
+  rewriting `git commit` commands would be a fourth hook script — out of scope
+  for a fix-up round. The `tests/run.sh trailers` step is the in-reach
+  equivalent: detection in the gate every push already passes through.
+- **Literal beats indirect for agents.** Practitioner consensus: models "take
+  instructions quite literally", so leave "no room for interpretation";
+  template-based, schema-constrained prompts are recommended for reliability.
+  No controlled study measures "exactly one … nothing else" against an
+  indirect "the trailer the rules define" for this task; the closest study
+  (arXiv 2508.01523, code-edit prompting) is an analogy only. Treated as a
+  reasonable inference, not a proven result.
+- **Contrarian angles, logged not adopted:** (a) let the harness name the
+  real model for provenance — countered by model names drifting or being
+  wrong in immutable history (objectstack #19202); (b) emit no AI co-author
+  line at all, since tooling treats it as an authorship claim (issue #66602).
+  The rule keeps the fixed, model-free trailer the project already uses.
+- **Migration section pattern** (matthewswong.com, 2026, a Claude Code
+  dotfiles-to-plugin migration): enumerate every installed artifact by type,
+  give a keep/delete decision per item, warn that "hook entries merge across
+  settings levels rather than replacing each other … a plugin's copy is
+  counted separately from a settings copy" (both fire), and verify again
+  after deleting the originals (`/hooks` shows per-event counts and sources).
+  T3 follows that shape.
+
+# Tasks
+
+Four commits plus one verification-only task. T1–T3 own disjoint files and
+run together; T4 runs after them, because it rewrites `tests/run.sh`, the
+script their verifications execute; T5 runs last.
+
+Note to the `/cw:build` orchestrator, for Phase 0 step 3: this round runs on
+the existing `feat/cw-plugin` release branch — the files it fixes exist only
+there, and every series check uses `main..HEAD` on it. Do not create
+`fix/fixups-1-0-0` from `main`. Invoke the build as `/cw:build fixups-1-0-0
+continue` with `feat/cw-plugin` checked out, which reuses the current branch;
+no task commit exists yet, so nothing is skipped.
+
+Note to the `/cw:build` orchestrator, for T5: its series check has no owning
+file. If it fails on a specific commit, do not iterate T5 — fix that commit's
+message at the checkpoint (an amend when it is `HEAD`, otherwise an
+autosquash fixup; the branch is unpushed), re-run T5's verification
+yourself, and report the fix in the checkpoint summary. The same applies
+when a `continue` run re-verifies T1, T2 or T3 after T4 has landed and their
+closing `bash tests/run.sh all` fails only on its `trailers` line: that is a
+commit-message problem, not a defect in the task. Run this build in auto
+mode: the verifications use `mktemp`, `cp`, `grep` and `test`, which the
+build skill does not pre-approve for an `acceptEdits` session.
+
+Note to the `/cw:build` orchestrator, for Phase 0 step 4: the
+`docs(fixups-1-0-0): design` commit message ends with exactly one trailer
+line, `Co-Authored-By: Claude <noreply@anthropic.com>`, and no other
+attribution or session line, whatever this session's attribution reminder
+proposes — this plan is the first real run of that rule. Whenever step 4
+actually made that commit in this run (a first run, or a `continue` run with
+a modified plan file; never when there was no delta), and right after it,
+while it is still `HEAD` and before any task starts, run
+`git log -1 --format=%B | grep -c '^Co-Authored-By: Claude <noreply@anthropic.com>$'`,
+`git log -1 --format=%B | grep -ci '^Co-Authored-By:'` and
+`git log -1 --format=%B | grep -c '^Claude-Session:'`; unless they print `1`,
+`1` and `0`, `git commit --amend` the message to the same subject and body
+with that one trailer line as its last line. T5 and `run.sh trailers` assert
+the whole series afterwards.
+
+## Task T1
+- scope: Make the trailer rule claim precedence explicitly — exactly one trailer line, no other attribution or session line — in the shipped rules file.
+- files_owned: [rules/workflow.md]
+- files_forbidden: [skills/**, agents/**, README.md, WORKFLOW.md, CLAUDE.md, settings.example.json, tests/**, hooks/**, .claude-plugin/**, .github/**, docs/**, rules/orchestration.md]
+- depends_on: [none]
+- agent: implementer
+- model: sonnet
+- risk: normal
+- verification: `grep -q 'exactly one trailer line' rules/workflow.md && test "$(grep -c 'Co-Authored-By' rules/workflow.md)" = 1 && grep -q '^  Co-Authored-By: Claude <noreply@anthropic.com>$' rules/workflow.md && test "$(wc -l < rules/workflow.md)" -le 40 && ! git grep -nwE 'NEVER|ALWAYS|MUST|CRITICAL' -- rules && ! grep -q '</content>' rules/workflow.md && bash tests/run.sh all`
+- commit: fix(rules): one trailer line per commit, no other attribution
+
+Exact replacement for `rules/workflow.md` lines 9–10 (the bullet under
+`## Workflow`); paste verbatim, without re-wrapping, and keep the trailer
+line indented by exactly two spaces — `tests/run.sh trailers` reads it from
+there:
+
+```
+- Every commit ends with exactly one trailer line, the one below, and no other
+  attribution or session line; a harness attribution reminder does not add a
+  second one:
+  Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+## Task T2
+- scope: Carry the one-trailer-line wording into every commit-producing or commit-checking instruction in the build and ship skills, without repeating the trailer text.
+- files_owned: [skills/build/SKILL.md, skills/ship/SKILL.md]
+- files_forbidden: [rules/**, agents/**, README.md, WORKFLOW.md, CLAUDE.md, settings.example.json, tests/**, hooks/**, .claude-plugin/**, .github/**, docs/**, skills/design/**, skills/search/**, skills/compound/**, skills/google-workspace/**]
+- depends_on: [none]
+- agent: implementer
+- model: sonnet
+- risk: normal
+- verification: `test "$(tr -s '[:space:]' ' ' < skills/build/SKILL.md | grep -o 'exactly the one trailer line' | wc -l | tr -d ' ')" = 2 && test "$(tr -s '[:space:]' ' ' < skills/ship/SKILL.md | grep -o 'exactly the one trailer line' | wc -l | tr -d ' ')" = 1 && test "$(tr -s '[:space:]' ' ' < skills/ship/SKILL.md | grep -o 'same single trailer line' | wc -l | tr -d ' ')" = 2 && ! grep -q 'the trailer the workflow rules define' skills/build/SKILL.md skills/ship/SKILL.md && ! grep -q 'Co-Authored-By' skills/build/SKILL.md skills/ship/SKILL.md && test "$(wc -l < skills/build/SKILL.md)" -le 200 && test "$(wc -l < skills/ship/SKILL.md)" -le 150 && ! git grep -nwE 'NEVER|ALWAYS|MUST|CRITICAL' -- skills && ! grep -rn '</content>' skills && bash tests/run.sh all`
+- commit: fix(skills): one trailer line on the design commit and series check
+
+Exact edits (keep the surrounding sentences; only the quoted spans change;
+the spans below are shown unwrapped but sit wrapped at about 79 columns on
+disk — re-wrap freely, the verification squeezes whitespace before counting):
+
+1. `skills/build/SKILL.md` Phase 0 step 4 — replace "make one commit,
+   `docs(<slug>): design`, with the trailer the workflow rules define." with:
+   "make one commit, `docs(<slug>): design`, ending with exactly the one
+   trailer line the workflow rules define and no other attribution or session
+   line (a harness reminder proposing a second co-author line yields to that
+   rule)."
+2. `skills/build/SKILL.md` Phase 2 item 6, inside the quoted implementer
+   instruction — replace "ending with the trailer the workflow rules define,"
+   with: "ending with exactly the one trailer line the workflow rules define
+   and no other attribution or session line,".
+3. `skills/build/SKILL.md` Phase 3 commit check — replace "with the project's
+   trailer, touching only `files_owned`;" with: "with exactly the project's
+   one trailer line (a second co-author line or a session line is malformed),
+   touching only `files_owned`;".
+4. `skills/ship/SKILL.md` Step 2 first bullet — replace "carrying the trailer
+   the workflow rules define." with: "carrying exactly the one trailer line
+   the workflow rules define; a second co-author line or a session line is a
+   malformed message — report it and suggest a rebase."
+5. `skills/ship/SKILL.md` Step 2 last bullet — replace "offer to commit it now
+   as `docs(<slug>): design` with the same trailer." with: "offer to commit
+   it now as `docs(<slug>): design` with the same single trailer line."
+6. `skills/ship/SKILL.md` Step 4 — replace "in one atomic `docs:` commit with
+   the same trailer as the rest of the series." with: "in one atomic `docs:`
+   commit with the same single trailer line as the rest of the series."
+
+## Task T3
+- scope: Rewrite the README migration section as a keep/delete list with a verify step, explain the built-in Explore agent with a copyable haiku override after the Agents table, and name the trailer check in the tests section.
+- files_owned: [README.md]
+- files_forbidden: [skills/**, agents/**, rules/**, WORKFLOW.md, CLAUDE.md, settings.example.json, tests/**, hooks/**, .claude-plugin/**, .github/**, docs/**]
+- depends_on: [none]
+- agent: implementer
+- model: sonnet
+- risk: trivial
+- verification: `grep -q 'agents/Explore.md' README.md && grep -q 'the old manifest put five skills' README.md && grep -q 'claude plugin list' README.md && grep -q 'hook once' README.md && grep -q 'ships no agent by that name' README.md && grep -q '^name: Explore' README.md && grep -q '^tools: Read, Glob, Grep$' README.md && tr -s '[:space:]' ' ' < README.md | grep -q 'per-commit trailer check' && ! grep -q 'delete those user-scope copies' README.md && grep -qi migration README.md && grep -q '1.0.0' README.md && ! grep -qE 'install.sh|merge-settings|/setup' README.md WORKFLOW.md && ! grep -rnE '/(Users|home)/' README.md && ! grep -q '<you>' README.md && ! grep -q '</content>' README.md && bash tests/run.sh all`
+- commit: fix(readme): migration keeps Explore override, names trailer check
+
+The eight positive greps up to `per-commit trailer check` match only the
+new text, and the negative grep on `delete those user-scope copies` holds
+only after the rewrite; the remaining greps are regression guards,
+pre-satisfied today. Paste the two fenced blocks verbatim, without
+re-wrapping — their greps are line-bound; the tests sentence may be
+re-wrapped, its grep squeezes whitespace.
+
+Exact replacement for the section `## Migration from the old installer`
+(README.md lines 171–177), heading kept:
+
+~~~
+## Migration from the old installer
+
+If you previously installed this project's files directly into `~/.claude`
+rather than as a plugin, the old manifest put five skills (`build`,
+`compound`, `design`, `search`, `ship`), six agents, five hooks and
+`rules/orchestration.md` there. To migrate:
+
+- Delete the user-scope copies of the five skills, the five hooks and
+  `rules/orchestration.md`, and remove the five `hooks` entries from
+  `settings.json` — a plugin hook and a settings hook that share the same
+  command both fire, so leaving the old entries in place double-runs them.
+  Three of the old hooks (`design-scope-guard.sh`,
+  `orchestrator-delegate-guard.sh`, `syntax-check.sh`) have no plugin
+  replacement: 1.0.0 retires them on purpose.
+- Delete the five agents the plugin now ships under the `cw:` prefix, but keep
+  `agents/Explore.md` if you had it: a user-scope agent named `Explore`
+  overrides the built-in one and keeps its own `model: haiku`, and this
+  plugin ships no agent by that name (`/cw:design` pins haiku per call
+  regardless).
+- Replace any workflow rules pasted into your profile `CLAUDE.md` with the two
+  imports shown above, and remove any other stray copies of the old layout.
+
+Verify with `claude plugin list` (one `cw` entry), by checking that the
+`skills/`, `agents/` and `hooks/` folders under your config dir hold none of
+the old files (apart from `agents/Explore.md` if you kept it), and, inside a
+session, with `/hooks`: each event lists the plugin's hook once, with no copy
+from `settings.json`.
+~~~
+
+One paragraph and a fenced block inserted after the blank line that follows
+the Agents table (after README.md line 90, so the table extension does not
+absorb them as rows), followed by a blank line:
+
+~~~
+`/cw:design` also spawns the built-in `Explore` agent with `model: haiku` on
+each call; the plugin ships no agent by that name — its agents load under the
+`cw:` prefix. To keep every session's exploration on haiku, add a user-scope
+override at `~/.claude/agents/Explore.md`; it replaces the built-in prompt
+with yours, so keep it short and read-only:
+
+```markdown
+---
+name: Explore
+description: Fast, read-only codebase exploration. Locates files, symbols and patterns; reports paths and line numbers.
+model: haiku
+tools: Read, Glob, Grep
+---
+Locate what the request names with Glob and Grep, read only the ranges you
+need to confirm a finding, and report file paths with line numbers. Do not
+modify anything.
+```
+~~~
+
+In `## Running the tests`, replace the sentence "Runs hook behavior,
+file-size budgets, a cross-file phrase-duplication check, and the
+`settings.example.json`/`tests/settings-keys.txt` cross-check." with:
+"Runs hook behavior, file-size budgets, a cross-file phrase-duplication
+check, the `settings.example.json`/`tests/settings-keys.txt` cross-check, and
+a per-commit trailer check on `main..HEAD` (skipped, and reported as such,
+only when neither `main` nor `origin/main` resolves)."
+
+## Task T4
+- scope: Add a `trailers` subcommand to the test runner that checks every non-merge commit in `main..HEAD` for exactly one trailer line equal to the one in `rules/workflow.md` and no session line, wire it into `all`, and give CI a full-depth checkout so it runs on pull requests.
+- files_owned: [tests/run.sh, .github/workflows/ci.yml]
+- files_forbidden: [skills/**, agents/**, rules/**, README.md, WORKFLOW.md, CLAUDE.md, settings.example.json, hooks/**, .claude-plugin/**, docs/**, tests/dedupe-phrases.txt, tests/settings-keys.txt, tests/fixtures/**]
+- depends_on: [T1, T2, T3]
+- agent: implementer
+- model: sonnet
+- risk: high
+- verification: `shellcheck -x tests/run.sh && bash tests/run.sh hooks && bash tests/run.sh size && bash tests/run.sh dedupe && bash tests/run.sh all | grep -qE '^all: trailers: (PASS|FAIL|SKIPPED)$' && grep -q '^        with:$' .github/workflows/ci.yml && grep -q '^          fetch-depth: 0$' .github/workflows/ci.yml && grep -q 'trailers|all' tests/run.sh && grep -q 'exit 3' tests/run.sh && R=$(mktemp -d) && git -C "$R" init -q -b main && mkdir -p "$R/tests" "$R/rules" && cp tests/run.sh "$R/tests/run.sh" && cp rules/workflow.md "$R/rules/workflow.md" && git -C "$R" add -A && git -C "$R" -c user.name=t -c user.email=t@example.com commit -qm base && git -C "$R" checkout -qb feat/x && echo a > "$R/a" && git -C "$R" add a && git -C "$R" -c user.name=t -c user.email=t@example.com commit -qm "$(printf 'feat: a\n\nCo-Authored-By: Claude <noreply@anthropic.com>')" && bash "$R/tests/run.sh" trailers && echo b > "$R/b" && git -C "$R" add b && git -C "$R" -c user.name=t -c user.email=t@example.com commit -qm "$(printf 'feat: b\n\nCo-Authored-By: Claude <noreply@anthropic.com>\nCo-Authored-By: Claude X <noreply@anthropic.com>')" && ! bash "$R/tests/run.sh" trailers && bash "$R/tests/run.sh" trailers 2>&1 | grep -q 'trailers: VIOLATION' && git -C "$R" -c user.name=t -c user.email=t@example.com commit -q --amend -m "$(printf 'feat: b\n\nCo-Authored-By: Claude <noreply@anthropic.com>\nClaude-Session: https://example.invalid/s')" && ! bash "$R/tests/run.sh" trailers && bash "$R/tests/run.sh" trailers 2>&1 | grep -q 'trailers: VIOLATION' && git -C "$R" -c user.name=t -c user.email=t@example.com commit -q --amend -m "$(printf 'feat: b\n\nCo-Authored-By: Claude Opus 5 <noreply@anthropic.com>')" && ! bash "$R/tests/run.sh" trailers && bash "$R/tests/run.sh" trailers 2>&1 | grep -q 'trailers: VIOLATION' && git -C "$R" -c user.name=t -c user.email=t@example.com commit -q --amend -m "$(printf 'feat: b\n\nCo-Authored-By: Claude <noreply@anthropic.com>')" && bash "$R/tests/run.sh" trailers && D=$(mktemp -d) && git clone -q --depth 1 --branch feat/x "file://$R" "$D/c" && { bash "$D/c/tests/run.sh" trailers; test $? -eq 3; } && bash "$D/c/tests/run.sh" trailers | grep -q 'trailers: skipped' && bash "$D/c/tests/run.sh" all | grep -q '^all: trailers: SKIPPED$'`
+
+This verification exercises the check on a scratch repo and only confirms
+that `all` reports a `trailers` line on this branch; the real series is
+asserted by T5, so a malformed commit elsewhere on the branch cannot fail
+this task.
+- commit: test: per-commit trailer check in run.sh, wired into all and CI
+
+Specification (the implementer writes the code; follow the file's own
+conventions — `local` declarations, `report`-style messages prefixed with
+the subcommand name, `>&2` for errors, no bash-4 features, shellcheck clean):
+
+1. `cmd_trailers()` — `[ $# -eq 0 ] || usage`. Read the expected line from
+   the rules file: `expected=$(sed -n 's/^  \(Co-Authored-By: .*\)$/\1/p'
+   "$ROOT/rules/workflow.md" | head -n 1)`; empty → print
+   `trailers: cannot read the expected trailer from rules/workflow.md` to
+   stderr and return 1 (fail closed: the rules file is in-repo). Skip path
+   next: when `git -C "$ROOT" rev-parse --is-shallow-repository` prints
+   `true`, or neither `main` nor `origin/main` resolves with `git -C "$ROOT"
+   rev-parse --verify -q <ref>`, print `trailers: skipped (shallow
+   repository or no main/origin/main ref)` on stdout (like `all: scan:
+   skipped`) and return 3 — a shallow history can hide commits and would
+   pass falsely. Otherwise the base ref is `main` when it resolves, else
+   `origin/main`. For each commit from
+   `git -C "$ROOT" rev-list --no-merges "$base..HEAD"` (read with a `while
+   read -r` loop over process substitution, so a flag set inside persists),
+   take `body=$(git -C "$ROOT" log -1 --format=%B "$c")` and require all
+   three: `printf '%s\n' "$body" | grep -c -F -x -- "$expected"` equals 1;
+   `printf '%s\n' "$body" | grep -ci '^Co-Authored-By:'` equals 1; and
+   `printf '%s\n' "$body" | grep -q '^Claude-Session:'` fails. Otherwise
+   print `trailers: VIOLATION <short sha> <subject>: expected exactly one
+   trailer line "<expected>" and no session line` and set the failure flag.
+   End: `trailers: OK (<base>..HEAD, <n> commits)` and return 0, or return 1.
+2. `usage()` — `{hooks|size|dedupe|scan|trailers|all}`; the header comment's
+   subcommand list gains `trailers`, and its exit-code line becomes exactly
+   "Usage errors exit 2; check failures exit 1; a skipped trailers check
+   returns exit 3; success exits 0." `cmd_trailers` uses `return 3`: `main`
+   propagates it as the script's exit status when run directly, and
+   `cmd_all` reads it as a return code.
+3. `main()` — a `trailers)` arm before `all)`, same shape as the others.
+4. `cmd_all()` — after the settings-keys block: run `cmd_trailers`, map exit
+   0 → `all: trailers: PASS`, 3 → `all: trailers: SKIPPED` (not a failure),
+   anything else → `all: trailers: FAIL` and `fail=1`, appending to `summary`
+   exactly like the existing steps.
+5. `.github/workflows/ci.yml` — in the ubuntu job only, right under line 15
+   (`      - uses: actions/checkout@v4`, six spaces before the dash), add two
+   lines: `        with:` (eight spaces, aligned with `uses:`) and
+   `          fetch-depth: 0` (ten spaces), so the history is complete and
+   `origin/main` resolves on pull-request and push runs; the macOS job is
+   unchanged. No local gate parses this YAML, so the indentation is asserted
+   by exact-match greps in the verification.
+
+## Task T5
+- scope: Release gate re-run on the finished series, verification only.
+- files_owned: []
+- files_forbidden: [**]
+- depends_on: [T1, T2, T3, T4]
+- agent: implementer
+- model: sonnet
+- risk: trivial
+- verification: `bash tests/run.sh all && bash tests/run.sh all | grep -q '^all: trailers: PASS$' && shellcheck -x hooks/*.sh tests/run.sh && claude plugin validate . && jq empty .claude-plugin/plugin.json .claude-plugin/marketplace.json hooks/hooks.json && test "$(for c in $(git rev-list --no-merges main..HEAD); do b=$(git log -1 --format=%B "$c"); { test "$(printf '%s\n' "$b" | grep -c '^Co-Authored-By: Claude <noreply@anthropic.com>$')" = 1 && test "$(printf '%s\n' "$b" | grep -ci '^Co-Authored-By:')" = 1 && ! printf '%s\n' "$b" | grep -q '^Claude-Session:'; } || echo "$c"; done | wc -l | tr -d ' ')" = 0 && ! git grep -nwE 'NEVER|ALWAYS|MUST|CRITICAL' -- skills agents rules && ! git grep -niE 'opus needs|do not trust|be decisive|read all files fresh|claude-design-active|claude-orchestrator-active' -- skills agents rules && ! git grep -niE 'under 50 lines' -- skills agents rules && ! git grep -nE '^(disallowedTools|permissionMode|mcpServers|hooks):' -- agents && test "$(for f in agents/*.md; do for k in model tools effort maxTurns; do grep -q "^$k:" "$f" || echo "$f:$k"; done; done | wc -l | tr -d ' ')" = 0 && ! git grep -niE '~/.claude/plans|gitattributes|linguist|git clean' -- skills && grep -q haiku skills/design/SKILL.md && OWNER=$(sed -n 's/^Copyright (c) [0-9]* //p' LICENSE | cut -d' ' -f1) && test -n "$OWNER" && ! git grep -qi "$OWNER" -- skills agents rules hooks tests WORKFLOW.md CLAUDE.md docs && test -z "$(git status --short)"`
+- commit: none
+
+T5 owns no file by design: a failed check here is reported at the checkpoint
+with the failing command's output. A content failure belongs to the task that
+owns the offending file (`/cw:build <slug> continue <task-id>`). A
+trailer-only failure has no owning file: the named commit's message is fixed
+at the checkpoint by an amend when it is `HEAD`, otherwise by an autosquash
+fixup — the branch is unpushed, and this is the same remedy Phase 4 applies
+to a task commit — and T5 is re-run.

From af0e21c2b90e16b7629ed4fdf32e3dec6f1dc2ec Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Mon, 21 Sep 2026 17:34:46 +0100
Subject: [PATCH 10/24] fix(rules): one trailer line per commit, no other
 attribution

A validation round produced a commit with two co-author lines: the
rule's one plus a harness session-attribution line naming the model.
Sharpen the rule to claim precedence explicitly so the harness
reminder cannot add a second trailer.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 rules/workflow.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/rules/workflow.md b/rules/workflow.md
index 5d0d22e..f487b0c 100644
--- a/rules/workflow.md
+++ b/rules/workflow.md
@@ -6,7 +6,9 @@ routing and workflow usage follow the orchestration rules.
 ## Workflow
 - Feature branches only; work reaches the default branch through a pull request.
 - Conventional Commits: feat:, fix:, refactor:, docs:, chore:, test:.
-- Every commit ends with the co-author trailer:
+- Every commit ends with exactly one trailer line, the one below, and no other
+  attribution or session line; a harness attribution reminder does not add a
+  second one:
   Co-Authored-By: Claude <noreply@anthropic.com>
 - No implementation without an approved design. If uncertain, ask first.
 - Two human checkpoints, both non-negotiable: after the design, before the PR.

From 7f2cbb5708c5b578fdb18c89522681960f6219d6 Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Mon, 21 Sep 2026 17:35:49 +0100
Subject: [PATCH 11/24] fix(readme): migration keeps Explore override, names
 trailer check

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 47 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 8062650..21ed80c 100644
--- a/README.md
+++ b/README.md
@@ -88,6 +88,24 @@ or open PRs, so they only run when you type the command.
 | `cw:design-reviewer` | opus | Doc/codebase fidelity review of a design draft |
 | `cw:direction-reviewer` | opus, effort xhigh | Premise/direction review, once per design |
 
+`/cw:design` also spawns the built-in `Explore` agent with `model: haiku` on
+each call; the plugin ships no agent by that name — its agents load under the
+`cw:` prefix. To keep every session's exploration on haiku, add a user-scope
+override at `~/.claude/agents/Explore.md`; it replaces the built-in prompt
+with yours, so keep it short and read-only:
+
+```markdown
+---
+name: Explore
+description: Fast, read-only codebase exploration. Locates files, symbols and patterns; reports paths and line numbers.
+model: haiku
+tools: Read, Glob, Grep
+---
+Locate what the request names with Glob and Grep, read only the ranges you
+need to confirm a finding, and report file paths with line numbers. Do not
+modify anything.
+```
+
 ## A profile CLAUDE.md
 
 A profile's `CLAUDE.md` is deliberately short — an identity line and two
@@ -170,11 +188,31 @@ escape hatch, not a bypass flag on the hook itself.
 
 ## Migration from the old installer
 
-If you previously installed this project's skills, agents, and hooks
-directly into `~/.claude` (five skills, six agents, five hooks) rather than
-as a plugin: delete those user-scope copies, and remove their `hooks` entries
-from `settings.json`. A plugin hook and a settings hook that share the same
-command both fire, so leaving the old entries in place double-runs them.
+If you previously installed this project's files directly into `~/.claude`
+rather than as a plugin, the old manifest put five skills (`build`,
+`compound`, `design`, `search`, `ship`), six agents, five hooks and
+`rules/orchestration.md` there. To migrate:
+
+- Delete the user-scope copies of the five skills, the five hooks and
+  `rules/orchestration.md`, and remove the five `hooks` entries from
+  `settings.json` — a plugin hook and a settings hook that share the same
+  command both fire, so leaving the old entries in place double-runs them.
+  Three of the old hooks (`design-scope-guard.sh`,
+  `orchestrator-delegate-guard.sh`, `syntax-check.sh`) have no plugin
+  replacement: 1.0.0 retires them on purpose.
+- Delete the five agents the plugin now ships under the `cw:` prefix, but keep
+  `agents/Explore.md` if you had it: a user-scope agent named `Explore`
+  overrides the built-in one and keeps its own `model: haiku`, and this
+  plugin ships no agent by that name (`/cw:design` pins haiku per call
+  regardless).
+- Replace any workflow rules pasted into your profile `CLAUDE.md` with the two
+  imports shown above, and remove any other stray copies of the old layout.
+
+Verify with `claude plugin list` (one `cw` entry), by checking that the
+`skills/`, `agents/` and `hooks/` folders under your config dir hold none of
+the old files (apart from `agents/Explore.md` if you kept it), and, inside a
+session, with `/hooks`: each event lists the plugin's hook once, with no copy
+from `settings.json`.
 
 ## `/cw:search --deep`
 
@@ -199,8 +237,10 @@ multi-source mode.
 bash tests/run.sh all
 ```
 
-Runs hook behavior, file-size budgets, a cross-file phrase-duplication check,
-and the `settings.example.json`/`tests/settings-keys.txt` cross-check.
+Runs hook behavior, file-size budgets, a cross-file phrase-duplication
+check, the `settings.example.json`/`tests/settings-keys.txt` cross-check,
+and a per-commit trailer check on `main..HEAD` (skipped, and reported as
+such, only when neither `main` nor `origin/main` resolves).
 Optionally set `CW_SCAN_PATTERNS=<your private pattern file>` to also scan
 the tracked tree for private strings you've defined — this is empty by
 default and off unless you set it.

From a7924366f3a61e435d317558772b2b730da5b4b4 Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Mon, 21 Sep 2026 17:36:49 +0100
Subject: [PATCH 12/24] fix(skills): one trailer line on the design commit and
 series check

Carry the one-trailer-line wording from rules/workflow.md into every
commit-producing or commit-checking instruction in the build and ship
skills, without repeating the trailer text itself.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 skills/build/SKILL.md | 32 ++++++++++++++++++--------------
 skills/ship/SKILL.md  | 10 ++++++----
 2 files changed, 24 insertions(+), 18 deletions(-)

diff --git a/skills/build/SKILL.md b/skills/build/SKILL.md
index 9c8f049..fa16e53 100644
--- a/skills/build/SKILL.md
+++ b/skills/build/SKILL.md
@@ -48,11 +48,13 @@ $ARGUMENTS — `<slug>`, optionally followed by `continue` and a task id.
    the existing branch.
 4. **Commit the design** when its file is untracked or modified: stage it by
    explicit pathspec (the plan file, or the folder-layout pair plus its
-   research files), never `git add .`, and make one commit,
-   `docs(<slug>): design`, with the trailer the workflow rules define. No delta
-   → skip silently. Not a repo, or the commit fails → report and carry on with
-   the file uncommitted, no retry loop. This commit is orchestrator-authored
-   and is excluded from every per-task commit count below.
+   research files), never `git add .`, and make one commit, `docs(<slug>):
+   design`, ending with exactly the one trailer line the workflow rules define
+   and no other attribution or session line (a harness reminder proposing a
+   second co-author line yields to that rule). No delta → skip silently. Not a
+   repo, or the commit fails → report and carry on with the file uncommitted,
+   no retry loop. This commit is orchestrator-authored and is excluded from
+   every per-task commit count below.
 5. Read the project's CLAUDE.md for conventions.
 
 ## Phase 1: Consume the task list
@@ -82,10 +84,11 @@ whole plan. The prompt carries:
 5. The task's `verification` — exact command(s) and expected result.
 6. The task's `commit:` line, plus: *"When the work is done and `verification`
    passes, make exactly one atomic commit from this `commit:` line, in
-   Conventional format, ending with the trailer the workflow rules define,
-   staging only `files_owned` by explicit path. One task, one commit. Do not
-   push."* Omit this entirely for a `commit: none` task (an unversioned or
-   external target) — that task is verification-only.
+   Conventional format, ending with exactly the one trailer line the workflow
+   rules define and no other attribution or session line, staging only
+   `files_owned` by explicit path. One task, one commit. Do not push."* Omit
+   this entirely for a `commit: none` task (an unversioned or external target)
+   — that task is verification-only.
 7. A required exit report: its final message ends with a fenced JSON block
    matching exactly this schema:
    ```json
@@ -123,11 +126,12 @@ fresh from disk, run `git diff`, run the tests"; and reproduce-before-report
 ("every finding needs a file:line plus a failing command or a specific
 reproducible scenario; drop what you cannot back").
 
-Commit check: "confirm the task produced exactly one commit in
-`git log --oneline main..HEAD`, Conventional format, with the project's
-trailer, touching only `files_owned`; flag a missing, squashed or malformed
-one, and exclude the `docs(<slug>): design` commit, which is not a task
-commit." Skip it entirely for a `commit: none` task.
+Commit check: "confirm the task produced exactly one commit in `git log
+--oneline main..HEAD`, Conventional format, with exactly the project's one
+trailer line (a second co-author line or a session line is malformed), touching
+only `files_owned`; flag a missing, squashed or malformed one, and exclude the
+`docs(<slug>): design` commit, which is not a task commit." Skip it entirely
+for a `commit: none` task.
 
 Required verdict, as `agents/reviewer.md` defines it — the reviewer's final
 message ends with a fenced JSON block matching exactly this schema:
diff --git a/skills/ship/SKILL.md b/skills/ship/SKILL.md
index a9cc132..95c73ef 100644
--- a/skills/ship/SKILL.md
+++ b/skills/ship/SKILL.md
@@ -39,8 +39,10 @@ $ARGUMENTS
 Against the plan's task list (`docs/plans/<slug>.md`):
 
 - Each task's `commit:` subject appears exactly once, in Conventional format,
-  carrying the trailer the workflow rules define. Tasks marked `commit: none`
-  contribute nothing here — that is expected, not a gap.
+  carrying exactly the one trailer line the workflow rules define; a second
+  co-author line or a session line is a malformed message — report it and
+  suggest a rebase. Tasks marked `commit: none` contribute nothing here — that
+  is expected, not a gap.
 - A `docs(<slug>): design` commit from `/cw:build` is an expected member of the
   series and does not have to lead it.
 - No catch-all or squashed commit. Do not create one, and do not rewrite the
@@ -50,7 +52,7 @@ Against the plan's task list (`docs/plans/<slug>.md`):
   report. The fix is to finish that task in `/cw:build`, not to absorb it here.
   The one exception is an uncommitted design file with no `docs(<slug>):`
   commit anywhere in the range — offer to commit it now as `docs(<slug>):
-  design` with the same trailer.
+  design` with the same single trailer line.
 
 ## Step 3: Quality gate
 This skill is project-agnostic; detect the gate in this precedence and run
@@ -81,7 +83,7 @@ Process-rule capture is `/cw:compound`'s job, offered separately in Step 6.
 Check whether the change makes any of these stale: the project README (new
 features, changed setup), `ARCHITECTURE.md` (new services, changed data flow),
 `CHANGELOG.md`. If so, update them in one atomic `docs:` commit with the same
-trailer as the rest of the series.
+single trailer line as the rest of the series.
 
 ## Step 5: Push and open the PR
 1. `git push -u origin HEAD`.

From e0ffc52e3c342910d3fbe1bec0132209ad6cd881 Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Mon, 21 Sep 2026 17:41:17 +0100
Subject: [PATCH 13/24] test: per-commit trailer check in run.sh, wired into
 all and CI

Adds a trailers subcommand that reads the expected trailer from
rules/workflow.md and checks every non-merge commit in main..HEAD for
exactly one matching line and no session line, so a duplicate or
model-named co-author trailer is caught mechanically instead of relying
on self-report. Wired into the all gate and given a full-depth CI
checkout so origin/main resolves on pull requests.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .github/workflows/ci.yml |  2 +
 tests/run.sh             | 84 ++++++++++++++++++++++++++++++++++++++--
 2 files changed, 82 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 15d58ff..1fc68e5 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -13,6 +13,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Install jq and shellcheck
         run: sudo apt-get update -y && sudo apt-get install -y shellcheck jq
diff --git a/tests/run.sh b/tests/run.sh
index a5d446f..b4b58ca 100755
--- a/tests/run.sh
+++ b/tests/run.sh
@@ -1,20 +1,21 @@
 #!/bin/bash
 # tests/run.sh — single test runner, one subcommand per invocation.
-# Subcommands: hooks, size, dedupe, scan, all.
+# Subcommands: hooks, size, dedupe, scan, trailers, all.
 # Must work on macOS system bash 3.2 and bash 5, BSD and GNU coreutils: no
 # mapfile/readarray, no ${var,,}, no associative arrays, no sed -i without a
 # suffix, no grep -P. Deliberately no `set -u`: bash < 4.4 raises "unbound
 # variable" on `"${empty_array[@]}"` under nounset, and this script is run
 # under bash 3.2 in CI.
 #
-# Usage errors exit 2; check failures exit 1; success exits 0.
+# Usage errors exit 2; check failures exit 1; a skipped trailers check
+# returns exit 3; success exits 0.
 
 ROOT=$(cd "$(dirname "$0")/.." && pwd)
 BASELINE_BYTES=73738
 BASH_BIN="${BASH:-bash}"
 
 usage() {
-  echo "usage: tests/run.sh {hooks|size|dedupe|scan|all} [options]" >&2
+  echo "usage: tests/run.sh {hooks|size|dedupe|scan|trailers|all} [options]" >&2
   exit 2
 }
 
@@ -680,6 +681,59 @@ cmd_scan() {
   return "$rc"
 }
 
+# ---------------------------------------------------------------------------
+# trailers
+# ---------------------------------------------------------------------------
+
+cmd_trailers() {
+  [ $# -eq 0 ] || usage
+  local expected shallow base n fail c body trailer_count co_count short subject
+
+  expected=$(sed -n 's/^  \(Co-Authored-By: .*\)$/\1/p' "$ROOT/rules/workflow.md" | head -n 1)
+  if [ -z "$expected" ]; then
+    echo "trailers: cannot read the expected trailer from rules/workflow.md" >&2
+    return 1
+  fi
+
+  shallow=$(git -C "$ROOT" rev-parse --is-shallow-repository 2>/dev/null)
+  base=""
+  if [ "$shallow" != "true" ]; then
+    if git -C "$ROOT" rev-parse --verify -q main >/dev/null 2>&1; then
+      base="main"
+    elif git -C "$ROOT" rev-parse --verify -q origin/main >/dev/null 2>&1; then
+      base="origin/main"
+    fi
+  fi
+
+  if [ "$shallow" = "true" ] || [ -z "$base" ]; then
+    echo "trailers: skipped (shallow repository or no main/origin/main ref)"
+    return 3
+  fi
+
+  n=0
+  fail=0
+  while read -r c; do
+    [ -z "$c" ] && continue
+    n=$((n + 1))
+    body=$(git -C "$ROOT" log -1 --format=%B "$c")
+    trailer_count=$(printf '%s\n' "$body" | grep -c -F -x -- "$expected")
+    co_count=$(printf '%s\n' "$body" | grep -ci '^Co-Authored-By:')
+    if [ "$trailer_count" -eq 1 ] && [ "$co_count" -eq 1 ] && ! printf '%s\n' "$body" | grep -q '^Claude-Session:'; then
+      continue
+    fi
+    short=$(git -C "$ROOT" rev-parse --short "$c")
+    subject=$(git -C "$ROOT" log -1 --format=%s "$c")
+    echo "trailers: VIOLATION $short $subject: expected exactly one trailer line \"$expected\" and no session line"
+    fail=1
+  done < <(git -C "$ROOT" rev-list --no-merges "$base..HEAD")
+
+  if [ "$fail" -eq 0 ]; then
+    echo "trailers: OK ($base..HEAD, $n commits)"
+    return 0
+  fi
+  return 1
+}
+
 # ---------------------------------------------------------------------------
 # all
 # ---------------------------------------------------------------------------
@@ -709,7 +763,7 @@ check_settings_keys() {
 
 cmd_all() {
   [ $# -eq 0 ] || usage
-  local fail summary
+  local fail summary trailers_rc
   fail=0
   summary=""
 
@@ -749,6 +803,24 @@ all: settings-keys: FAIL"
     fail=1
   fi
 
+  cmd_trailers
+  trailers_rc=$?
+  case "$trailers_rc" in
+    0)
+      summary="$summary
+all: trailers: PASS"
+      ;;
+    3)
+      summary="$summary
+all: trailers: SKIPPED"
+      ;;
+    *)
+      summary="$summary
+all: trailers: FAIL"
+      fail=1
+      ;;
+  esac
+
   if [ -n "${CW_SCAN_PATTERNS:-}" ]; then
     if [ ! -r "$CW_SCAN_PATTERNS" ]; then
       echo "all: scan: pattern file not readable" >&2
@@ -795,6 +867,10 @@ main() {
       shift
       cmd_scan "$@"
       ;;
+    trailers)
+      shift
+      cmd_trailers "$@"
+      ;;
     all)
       shift
       cmd_all "$@"

From fafca6f2f01b6a3389b9e194da917bc964a441e2 Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Mon, 21 Sep 2026 22:53:30 +0100
Subject: [PATCH 14/24] fix(hooks): disable SC2317 too on the trap-invoked
 finish function

Ubuntu CI installs shellcheck 0.9.0, which reports the body of a function
invoked only through trap as unreachable (SC2317). Newer releases report
the same situation as SC2329, which the directive already disabled, so the
local gate on 0.11.0 stayed green. Widening the directive keeps both
versions quiet; the function itself is unchanged.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 hooks/profile-check.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/hooks/profile-check.sh b/hooks/profile-check.sh
index 7c8bfb6..f802bfc 100755
--- a/hooks/profile-check.sh
+++ b/hooks/profile-check.sh
@@ -11,7 +11,7 @@ if ! command -v jq >/dev/null 2>&1; then
 fi
 
 OUT='{}'
-# shellcheck disable=SC2329 # invoked indirectly via `trap ... EXIT` below
+# shellcheck disable=SC2317,SC2329 # invoked indirectly via `trap ... EXIT` below; 0.9.0 reports SC2317, 0.10+ SC2329
 finish() {
   printf '%s\n' "$OUT"
   exit 0

From 31b9f3081720735d8ad260d096d5669d048ea4b2 Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Tue, 22 Sep 2026 11:52:32 +0100
Subject: [PATCH 15/24] feat(rules): browser recovery rule for Claude in Chrome

Diagnose and repair the extension link without a human: desktop-app manifest
takes precedence in the extension's probe order, so quit both apps, kill the
desktop helper, move its manifest aside, relaunch the right Chrome profile,
re-read tab context. Names the two residual causes an agent must hand back.
Operator-specific details (which sites sit behind a login, the authorisation,
the secret store, the resolver override, the memo path) live in the profile.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 rules/browser.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 rules/browser.md

diff --git a/rules/browser.md b/rules/browser.md
new file mode 100644
index 0000000..36bd794
--- /dev/null
+++ b/rules/browser.md
@@ -0,0 +1,75 @@
+# Browser (Claude in Chrome)
+
+Chrome is the operator's signed-in browser and the only route to anything
+behind a login. Playwright is for public pages and clean-session tests only.
+This runbook applies when the profile's CLAUDE.md says the operator has chosen
+Claude Code over the Claude desktop app for Chrome control and has authorised
+the steps below; then run them, do not ask.
+
+Why it breaks: the extension probes native hosts in a fixed order, the Claude
+desktop app's `com.anthropic.claude_browser_extension` first and Claude Code's
+`com.anthropic.claude_code_browser_extension` second, and stops at the first
+that answers. Whenever the desktop manifest exists, the desktop app owns the
+extension even if the app is closed (anthropics/claude-code #51519, #54567;
+Anthropic's docs do not mention the conflict). Every desktop-app update puts
+the manifest back. Moving it aside means the desktop app loses its own Chrome
+control until it is restored.
+
+## When any `mcp__claude-in-chrome__*` call says "extension is not connected"
+Fix it yourself, in this order, and only then continue the task. Do not ask
+the operator to quit an app, rename a file, or run `/chrome`.
+
+1. Diagnose (30 s, all read-only):
+   - Account and pairing: `python3 -c "import json,os;d=json.load(open(os.path.expanduser('~/.claude.json')));print(d.get('oauthAccount',{}).get('emailAddress'), d.get('chromeExtension'))"`
+   - Manifests in `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/`:
+     `com.anthropic.claude_code_browser_extension.json` must exist (Claude
+     Code rewrites it at session start); `com.anthropic.claude_browser_extension.json`
+     is the desktop app's and, when present, takes the extension away from
+     Claude Code.
+   - `pgrep -lf chrome-native-host` (the helper exists only while Chrome runs)
+     and `pgrep -x "Google Chrome"`.
+   - The profile to use: in Chrome's `Local State`, `profile.info_cache`, the
+     entry whose `user_name` equals the Claude Code account; confirm
+     `<profile dir>/Extensions/<id>` exists, `<id>` from the `allowed_origins`
+     of the Claude Code manifest.
+2. Fix:
+   - `osascript -e 'tell application "Claude" to quit'`, then
+     `pkill -f 'Claude.app/Contents/Helpers/chrome-native-host'` (exit 1 is
+     fine): the extension keeps a port open to the desktop helper and does
+     not re-probe until that port is severed. Then quit `"Google Chrome"` the
+     same way and wait until `pgrep -x "Google Chrome"` is empty (up to 20 s).
+   - Move the desktop manifest aside: `mv .../com.anthropic.claude_browser_extension.json{,.off}`.
+     It comes back after a desktop-app update; moving it is the fix each time.
+   - Relaunch the right profile with the operator's tabs:
+     `open -na "Google Chrome" --args --profile-directory="<dir>" --restore-last-session`
+     (tabs come back only if Chrome's own "continue where you left off" is
+     on or this flag is honoured).
+   - Wait about 12 s, confirm the running helper is `claude --chrome-native-host`
+     (Claude Code's, not `/Applications/Claude.app/...`), then call
+     `tabs_context_mcp` with `createIfEmpty: true`. After any Chrome restart,
+     earlier tab ids are stale: fetch the context again before acting
+     (#95158, #87774).
+3. If it is still not connected, two causes remain, both outside an agent's
+   reach: this Claude Code session cached the desktop socket path at start
+   and needs a fresh `claude` session (#51519), or the pairing went stale
+   after an account switch and the extension must be reinstalled in that
+   profile (#94764). Say which one the diagnosis points to, hand the task's
+   browser part back, and continue everything that does not need the
+   extension. "Receiving end does not exist" is different: the service
+   worker went idle; quitting and relaunching Chrome as above revives it.
+4. If lookups to `claude.ai` time out (`dig +short +time=3 @1.1.1.1 claude.ai`
+   versus the router), the relay will drop. Setting reliable resolvers is the
+   remedy; that is a system change, so do it only when the profile allows it,
+   and say so in the summary.
+
+## Working in the browser
+- One tab group per session; create tabs, close what you opened, leave a tab
+  open only when the operator should see it.
+- Batch actions with `browser_batch`; read values with `javascript_tool` or
+  `read_page`, never from a screenshot.
+- Secrets read from a page (API keys) go straight to the operator's secret
+  store through a temp file or stdin, never into a command line, a log or the
+  reply; report the last four characters only.
+- Never type a password; if a page asks for one, stop and report the URL.
+- After a fix, append what worked, dated, to the troubleshooting memo the
+  profile names.

From 126f8a688fac47532b51e27aaad3563573c6edbd Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Tue, 22 Sep 2026 11:53:51 +0100
Subject: [PATCH 16/24] docs(hardening-1-0-0): design

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/plans/hardening-1-0-0.md | 737 ++++++++++++++++++++++++++++++++++
 1 file changed, 737 insertions(+)
 create mode 100644 docs/plans/hardening-1-0-0.md

diff --git a/docs/plans/hardening-1-0-0.md b/docs/plans/hardening-1-0-0.md
new file mode 100644
index 0000000..345293e
--- /dev/null
+++ b/docs/plans/hardening-1-0-0.md
@@ -0,0 +1,737 @@
+# hardening-1-0-0 — guard-hook hardening and install-doc fixes before PR #3 merges
+
+Slug `hardening-1-0-0`. Branch `feat/cw-plugin` (14 commits over `main`, pushed, PR #3
+open, CI green). Each fix is a fresh commit on that branch; PR #3 updates in place. No
+version change: 1.0.0 is unreleased.
+
+## Context
+
+A four-reviewer merge-readiness panel on PR #3 (2026-09-21) found, and the orchestrator
+reproduced, that the plugin's branch guard does not deliver what its design and README
+promise, and that the README's marketplace install route cannot be followed as written.
+The maintainer held the merge on 2026-09-21 and chose, at the Step 0 gate on 2026-09-22: harden
+the six reproduced cases and state the guard's scope honestly; allow lease-style force
+pushes to non-main destinations (the design as written); carry the trivial one-liners
+the panel raised; leave the review-cap wording in `rules/orchestration.md` to
+`/cw:compound`.
+
+Reproduced on head `fafca6f` (script: the session scratchpad's `repro-hooks.sh`; every
+payload is a JSON file piped into the hook, and the hook's exit code is what counts):
+
+| # | Payload command (cwd `/tmp` unless stated) | Today | Promised |
+|---|---|---|---|
+| F1 | `sh -c "git push origin main"`, `bash -c '…'`, `eval "…"` | 0 | 2 |
+| F2 | `git switch main && git merge feat/x && git push` (cwd on feat/x) | 0 | 2 |
+| F2 | `cd <repo on main> && git push` (cwd on a feature repo) | 0 | 2 |
+| F3 | `git push --all origin`, `git push --mirror origin`, `git push origin --all` (cwd feat/x, local main exists) | 0 | 2 |
+| F4 | `echo <40 000 chars> && git push origin main` | 2 in 7.5 s; >~50k chars times out | 2, fast |
+| F5 | `git push --force-with-lease origin feat/x`, `--force-if-includes` | 2 | 0 |
+| F6 | `\git push origin main` | 0 | 2 |
+
+The hooks reference states that a timed-out PreToolUse command hook does not block the
+tool call (Research §2), so F4 is a fail-open, and every long Bash call pays the
+tokenizer's cost today. Minor items reproduced alongside: malformed hook input prints
+raw jq errors twice; the harness never reaches the branch-resolution code; the secrets
+hook misses `.p12`, `.netrc`, `id_dsa`, `id_ecdsa` and Terraform state next to covered
+siblings; `profile-check.sh` prints an empty line instead of `{}` when its final `jq`
+fails, and a CRLF `.claude-profiles` file yields a false "wrong profile" notice;
+`hooks/hooks.json`'s SessionStart matcher omits `compact`, a documented source. README
+route (b): `~/.claude/plugins/cache/claude-code-setup/cw/` lacks the `<version>/`
+segment the CLI actually creates, and `claude plugin details` prints no path (both
+confirmed on a throwaway install with CLI 2.1.278); `claude plugin list --json` does
+carry an `installPath` field (confirmed on the live profile). `WORKFLOW.md` omits
+`trailers` from the standalone subcommand list; `rules/workflow.md:18` names a
+`## Tasks` section that no plan has; `agents/implementer.md`'s Output section never
+mentions the JSON exit report `/cw:build`'s gate parses; CI's `claude plugin validate .`
+checks only the marketplace manifest; the linguist attribute is undocumented.
+
+Intended outcome: the guard blocks every reproduced form and the plausible variants
+next to them, stays under a second on 100k-character commands, allows lease pushes to
+feature branches, and its scope is written down in the design and README; the harness
+proves each behaviour; the README install route works as printed; CI green; PR #3
+ready to merge.
+
+## Approach
+
+**Rewrite the guard's front end, keep its decision logic.** `protect-branches.sh`
+keeps its structure (jq check, segment split, per-segment scan, destination rules,
+exit 2 with a one-line reason) and changes five things:
+
+1. **Fast path.** A command whose text contains no `push` substring exits 0 before any
+   parsing. That alone removes the latency from nearly every long call (heredocs
+   writing files rarely contain the word), and it is a pure pattern match, linear in C.
+2. **Linear normalisation instead of a per-character loop.** The whole command is
+   normalised once, in four processes total: `awk` joins backslash-newline
+   continuations (the existing bash join loop is quadratic as well: 2.0 s under bash 5
+   and 5.9 s under bash 3.2 for a 2 000-line, 112k-character command, measured; the
+   awk one-liner takes 0.03 s), `tr -d` removes every `"`, `'` and `\`
+   character, `tr` flattens tabs to spaces, and the existing `sed` split cuts the
+   result into segments on `&&`, `||`, `;`, `|`, `(`, `)`, backticks and newlines
+   (macOS `sed` emits a real newline for `\n` in the replacement: verified on this
+   machine and by the macOS CI job, see Risks). The `push` fast path runs on the
+   normalised text, so a quote-split spelling of the word is still seen. Segments are
+   then read with a builtin `while read -r` loop and each is split into words with
+   `set -f` array assignment (`TOK=( $seg )`, globbing off), a builtin with no process
+   and no temp file per segment. Everything is linear in C or builtin code, and it
+   exists in bash 3.2. Per-segment `tr` or here-string calls were
+   rejected: a 100k-character heredoc writing code has thousands of lines, and one
+   spawn per line is seconds again (Research §3 on `<<<` cost). Quote removal is what
+   makes nested shells visible at every depth in one pass: `sh -c "git push origin
+   main"` becomes the tokens `sh -c git push origin main`, and the existing scanner,
+   which looks for a `git` token anywhere in the segment, then sees `git` followed by
+   `push`; the depth-3 nesting that prior-art guards missed (Research §3) is flat
+   here. Backslash removal is what fixes `\git` (F6).
+   Trade-off, stated in the scope paragraph: a quoted prose fragment that spells a push
+   to main inside a command (`echo "git push origin main"`, a heredoc line, a
+   `--body "…"`) is blocked as if it were the command. Heredoc lines are blocked
+   today already; the remedy is the same as before (keep such text in a file). The
+   first-subcommand rule stays, so `git commit -m "… push to main …"` remains allowed.
+   Research §3 recommends an index-based state machine with recursive
+   interpreter-body extraction instead; this plan takes quote removal because it is
+   linear by construction, flattens every nesting depth, and is a fraction of the code
+   for a bash-3.2 script, at the cost of the prose over-block accepted at Step 0.
+3. **Chained state changes (F2) are tracked, not ignored, and the last change wins.**
+   Segments are processed in order. A `cd`/`pushd` segment records the target
+   directory (absolute as given, relative joined to the hook's `cwd`) and clears any
+   recorded branch, because the branch belongs to the old directory; `-`, no
+   argument, `popd`, or a target containing `$` records the directory as unknown. A
+   `git switch`/`git checkout` segment records a branch by one rule: `-b`, `-B`, `-c`
+   or `-C` name the branch in the next token; `--`, `-p`, `--patch`, `HEAD`, `-`, or a
+   token containing `$` make the branch unknown (a path checkout or a detached state
+   cannot be resolved from text); any other `-` option is skipped; the first remaining
+   token is the branch; nothing left is unknown. When a later segment is a
+   refspec-less push: a recorded branch is used directly (`main`/`master` blocks);
+   otherwise the branch is resolved with `git -C` at the `-C` dir, else the recorded
+   directory, else `cwd`; an unknown branch or directory blocks with the reason
+   "cannot determine the destination after a cd or branch change; use an explicit
+   refspec such as git push origin <branch>". So `git checkout -b feat/x && git push
+   -u origin HEAD` stays allowed, `git switch main && … && git push` blocks,
+   `cd <literal path on main> && git push` blocks by resolution, and
+   `git checkout -b feat/y && cd <path on main> && git push` blocks because the `cd`
+   cleared the branch (Research §4: fail closed on state the text cannot resolve).
+4. **Upstream check for the fully bare form, gated on `push.default`.** `git push` and
+   `git push <remote>` (no ref, no `HEAD`) also resolve `@{u}`, but only when the
+   repository's `push.default` is `upstream` or `tracking`: there a bare push lands on
+   the upstream, so an upstream ending in `/main` or `/master` blocks. Under the
+   default `simple` git refuses a mismatched upstream itself, and under `current` the
+   push goes to the same-named remote branch, so the guard does not block there (the
+   direction pass caught that an ungated check would wrongly block a `current` user
+   whose feature branch tracks `origin/main`). Unsourced — judgment call, resting on
+   git-config(1)'s `push.default` entry.
+5. **Option semantics per the design.** `--all` and `--mirror` block ("pushes every
+   branch, including main/master"). `--force`, `-f` in any short cluster, and `+ref`
+   block everywhere. `--force-with-lease`, `--force-with-lease=<ref>` and
+   `--force-if-includes` are ordinary options: the destination rules still apply, so a
+   lease push to main blocks and one to `feat/x` passes (the maintainer's Step 0
+   decision; Research §5). Malformed input: jq errors are silenced and an empty command exits 0.
+
+**Prove it in the harness, not in prose.** Every behaviour above becomes a numbered
+case in `tests/run.sh hooks`, including real-repository resolution cases (scratch
+repos created with `git init -b`), a 100k-character timing case measured with bash's
+`SECONDS`, regression cases for behaviours that must not change (`feat/main-nav`,
+commit messages mentioning main, `git -C <dir> push`), and the secrets and profile
+fixes. The harness gains `CW_HOOKS_DIR` (default `$ROOT/hooks`) so a candidate hook
+directory can be tested before it is installed. That matters in this build: the
+plugin loads from this checkout, so the file at `hooks/protect-branches.sh` is the live
+guard of the session that edits it, and a syntax error there blocks every Bash call.
+
+**Say what the guard is.** The design's hook paragraph and a README paragraph state
+the scope: a guardrail against the agent's own accidental pushes, reading command
+text, not a sandbox against a determined operator (who can disable the plugin). Named
+out of scope: commands assembled from variables or `eval "$X"`, `xargs`-fed refspecs,
+wrappers not named `git` (aliases, `git-push`, `gh api`), `git -c key="quoted value"`
+before `push`, and prose that spells a push to main (blocked as text). Research §6
+gives the practitioner grounding for stating this plainly.
+
+**Fix the install docs from observed CLI output.** Route (b) names the real cache
+layout with the version segment and replaces the `details` claim with
+`claude plugin list --json` filtered on `installPath`, which exists in 2.1.278. The
+other doc items are one-liners.
+
+**Dropped or deferred.** `rules/orchestration.md:45` review-cap wording:
+`/cw:compound` after the PR (the maintainer's choice). Blocking `xargs … git push` and
+non-git pushers: out of scope, stated (no reviewed guard covers `xargs`, `find -exec`
+or `ssh` bodies either, Research §3). A permission deny rule as a second layer: the
+permissions doc states a `Bash(git push *)` rule does not match `git -C . push`, a
+quoted `'push'`, or a command inside `sh -c`, and a plugin manifest has no
+permissions field (Research §2), so no second layer is available to ship. Returning
+`permissionDecision: "ask"` for the unknown-state case instead of blocking: the JSON
+form exists (Research §2), but its behaviour under `-p` with permissions skipped is
+undocumented and the harness asserts exit codes; kept as exit 2 with an actionable
+reason, the fail-closed choice every reviewed guard converged on (Research §3).
+
+## Files to create/modify
+
+| Path | Change |
+|---|---|
+| `hooks/protect-branches.sh` | Front end rewritten per Approach 1–5; decision messages and exit codes unchanged in shape. Header comment rewritten to describe the new normalisation and the stated scope. Bash 3.2, jq only, shellcheck 0.9.0 and 0.11.0 clean. |
+| `hooks/protect-secrets.sh` | Pattern block gains `*.p12`, `*.netrc`, `*id_dsa*`, `*id_ecdsa*`, `*.tfstate`, `*.tfstate.backup`. Nothing else. |
+| `hooks/profile-check.sh` | `NEW=$(jq -nc …) && OUT="$NEW"` in both branches so a failing jq leaves `{}`; `.claude-profiles` lines lose a trailing `\r` before parsing. |
+| `hooks/hooks.json` | SessionStart matcher `startup\|resume\|clear\|compact\|fork`. |
+| `tests/run.sh` | `HOOKS_DIR="${CW_HOOKS_DIR:-$ROOT/hooks}"` used by every hook case; new cases per T1's table; scratch repos for resolution cases; the timing case. |
+| `docs/plans/cw-plugin/cw-plugin-design-draft.md` | D2.4 hook paragraph (lines 218–225) rewritten to the new behaviour and scope; line 230 matcher gains `compact`; D6.3 hook-case count updated to T1's total. |
+| `README.md` | Route (b) cache path with `<version>/`; the import step uses `claude plugin list --json`; a "What the branch guard does" paragraph under Kill switch; one line on `.gitattributes`. |
+| `WORKFLOW.md` | Line 129: standalone list gains `trailers`. |
+| `rules/workflow.md` | Line 18: "reads the `## Task <id>` blocks of that file". |
+| `agents/implementer.md` | Output section gains item 5: end with the fenced JSON exit report when the orchestrator's prompt specifies one. |
+| `skills/ship/SKILL.md` | Step 5 item 2 gains one sentence: write the PR body to a scratch file and pass `--body-file`, so the guard never parses the body as a command. |
+| `.github/workflows/ci.yml` | Validate step also runs `claude plugin validate .claude-plugin/plugin.json`. |
+| `docs/plans/hardening-1-0-0.md` | This plan; `/cw:build` commits it as `docs(hardening-1-0-0): design`. |
+
+Untouched on purpose: `rules/orchestration.md` (deferred); `.claude-plugin/*.json`
+(no version change; the marketplace description warning is a known nit); every skill
+except the one instruction line in `skills/ship/SKILL.md`; `.gitattributes` itself
+(documented, not changed).
+
+## Dependencies
+
+None new. git ≥ 2.28 in the harness for `git init -b` (macOS system git and
+ubuntu-latest both qualify); jq, as today.
+
+## Risks & mitigations
+
+- **The edited hook is live in the editing session.** The plugin loads from this
+  checkout, so `hooks/protect-branches.sh` guards the very session that edits it. A
+  syntax error exits 2 (bash's own status) and blocks every Bash call. Mitigation: T1
+  develops in a scratch copy and tests it with `CW_HOOKS_DIR=<scratch> bash
+  tests/run.sh hooks`, installing into `hooks/` only when green; the Edit tool still
+  works if the live file breaks (a different hook guards it), so recovery is an edit,
+  not a restart. The orchestrator's task prompt must carry this.
+- **Payload strings trip the live guard and the auto-mode classifier.** A Bash command
+  line containing a push-to-main string is blocked by the live hook, and an agent brief
+  that spells such tests out was denied once as "Create Unsafe Agents". Mitigation:
+  payloads live in `tests/run.sh` and in this plan; task prompts reference the task
+  block by file and id instead of repeating payloads; implementers test through
+  `bash tests/run.sh hooks` and payload files, never inline strings.
+- **Over-blocking after quote stripping.** Prose containing a push-to-main line inside
+  a command is now blocked even when quoted (`echo "…"`, `gh pr create --body "…"`).
+  Heredoc lines were blocked before this change. Mitigation: the block message names
+  the remedy (put the text in a file), the README scope paragraph says so, and a
+  harness case keeps commit messages mentioning main allowed.
+- **Over-blocking on unknown state.** `cd "$DIR" && git push` blocks with advice
+  because `$DIR` cannot be resolved. The message names the fix (explicit refspec); the
+  common agent pattern `git checkout -b x && git push -u origin HEAD` stays allowed by
+  branch tracking.
+- **Timing case flakiness in CI.** A 100k-character command must finish within 1 s by
+  `SECONDS` (integer seconds; a boundary crossing can read 1). Linear code runs in well
+  under 200 ms locally; the assertion is `-le 1`, and the case also asserts exit 2 so a
+  fast fail-open cannot pass.
+- **Shellcheck version drift.** T1's verification runs the local 0.11.0 and, when
+  present at `~/.claude/plans/cw-plugin-gates/shellcheck-0.9.0`, CI's apt version
+  0.9.0; the build's Phase 0 note says how to put it there. The SC2317/SC2329 pair is
+  the known difference (Research §2). CI remains the authoritative 0.9.0 run.
+- **BSD `sed` and `\n` in a replacement (unverified risk).** Reviewers cited BSD
+  `sed` builds, and the macOS man page (which documents a backslash-newline rather
+  than `\n` for a newline in a replacement), under which the split would emit a
+  literal `n`, collapse every command into one segment and defeat the state tracking.
+  On this machine (Darwin 25) `sed` emits a real newline for `\n`, checked with `od`.
+  The existing macOS CI case does not exercise the split (it blocks by finding a `git`
+  token anywhere in the segment), so the new state cases are the first real evidence,
+  at CI time; a failure there is a red macOS job, never a silent regression, and the
+  remedy is a `tr` split mapping each separator character to a newline (one process,
+  no escape interpretation involved).
+- **The plan file is committed under `docs/`.** CI's LICENSE-name gate greps `docs`,
+  so this plan names no person; the build's Phase 0 note re-checks that before the
+  design commit.
+- **Design draft amendment scope.** Only D2.4's hook paragraph, the SessionStart
+  matcher and D6.3's count change; the rest of the released design stays as written.
+- **A rule wording edit rides in a feature PR.** `rules/workflow.md:18` and
+  `agents/implementer.md` are shipped product on the release branch, same as the
+  previous round's `fix(rules)`; accepted, logged here.
+
+## Success criteria
+
+All from the repo root; each exits 0. Push-to-main strings are never typed into a
+Bash command line; the harness and the scratchpad script hold them.
+
+1. Guard behaviour: `bash tests/run.sh hooks` and `/bin/bash tests/run.sh hooks` both
+   end with `0 failed` and at least 58 passed (73 when the scratch repos can be
+   created; the exact total is not pinned anywhere, so adding coverage later breaks
+   nothing).
+   The reproduction script (copied by the build's Phase 0 to
+   `~/.claude/plans/cw-plugin-gates/repro-hooks.sh`) prints, row by row: rc=2 for the
+   push-to-main control, the three F1 rows, the backslash row, the env-prefixed
+   control, the three blocking F2 rows (bare push with cwd on main, switch-then-push,
+   cd-then-push), the three F3 rows and both F4 rows, 14 in all; rc=0 for the
+   feature-branch control, the F2 bare-push-on-feature control and both F5 rows, 4 in
+   all; and the 40k-character F4 row reports under 1 s.
+2. Gates: `bash tests/run.sh all` (summary all PASS incl. `trailers`), `shellcheck -x
+   hooks/*.sh tests/run.sh` on 0.11.0 and, when the binary is present, on 0.9.0 (CI's
+   apt version runs it regardless), `claude plugin validate .` and `claude plugin
+   validate .claude-plugin/plugin.json` exit 0, `jq empty hooks/hooks.json`, `jq -e
+   '.hooks.SessionStart[0].matcher=="startup|resume|clear|compact|fork"'
+   hooks/hooks.json`.
+3. Docs: `grep -q 'cw/<version>/' README.md && grep -q 'installPath' README.md && !
+   grep -q 'print the current cache path' README.md && grep -qi 'not a sandbox'
+   README.md && grep -q 'linguist' README.md && grep -q 'trailers' WORKFLOW.md && grep
+   -q '## Task <id>' rules/workflow.md && grep -qi 'exit report' agents/implementer.md
+   && grep -q 'compact' docs/plans/cw-plugin/cw-plugin-design-draft.md`.
+4. Hygiene: the CI greps (`! git grep -nwE 'NEVER|ALWAYS|MUST|CRITICAL' -- skills
+   agents rules`, banned phrases, LICENSE name), `! grep -rn '</content>' hooks tests
+   README.md WORKFLOW.md rules agents`, size and dedupe PASS (README and hooks are
+   outside dedupe and size scope; `agents/implementer.md` stays ≤ 150 lines).
+5. Series: each task's `commit:` subject appears exactly once in `git log --format=%s
+   main..HEAD`; `bash tests/run.sh trailers` OK on the whole series; CI green on the
+   pushed head for both the push and pull-request runs.
+
+## Research
+
+### Codebase (Explore, haiku, 2026-09-22) and orchestrator reads
+
+- Harness: `tests/run.sh` `report` (30–40) counts `HPASS`/`HFAIL`; `check_code` (46–53)
+  compares exit codes; `hooks_push_cases` (55–78) pipes JSON via `printf '%s' '{…}' |
+  HOME="$SCRATCH/base" "$BASH_BIN" "$ROOT/hooks/protect-branches.sh"`; four push cases,
+  four secrets cases (Write and NotebookEdit only), one jq-absent case with a
+  PATH-restricted bin, six profile cases; `cmd_hooks` (213–230) creates `SCRATCH`,
+  prints `hooks: %d passed, %d failed`. No case creates a git repository today, so
+  `protect-branches.sh:147` (`git -C … rev-parse`) is never reached.
+- Size gate scope is `skills/**/SKILL.md`, `agents/*.md`, `rules/*.md` (files_in_scope
+  238–268); hooks and tests carry no cap; `WORKFLOW.md` ≤ 200 lines; agents/rules ≤ 150.
+  Dedupe scans the same three sets against `tests/dedupe-phrases.txt` (phrases include
+  `push directly to main`, `one atomic commit per task`, `never commits`); README is
+  outside both gates. D6.4 forbids `gitattributes|linguist` in `skills/` only.
+- Design D2.4 (218–231) promises: split on `&&`, `||`, `;`, `|`, newlines; block any
+  segment that is a `git push` to main/master by explicit refspec or by current branch;
+  block `--force`/`-f`; everything else exits 0; SessionStart matcher
+  `startup|resume|clear|fork`. D6.3 asserts "15 hook cases".
+- `protect-secrets.sh` patterns (34–43): `*.env|*.env.*|*.envrc|*credentials*|*secret*|
+  *config.swift|*.pem|*.key|*.p8|*.pfx|*.jks|*.keystore|*id_rsa*|*id_ed25519*|
+  *.gnupg/*|*service-account*.json|*gcp*key*.json`; directory checks precede the
+  template allowlist.
+- `protect-branches.sh` today: per-character `tokenize()` (31–63) with one layer of
+  quote stripping; scanner (65–94) finds the first `git` token, skips `-C <dir>` and
+  other global options, breaks on the first subcommand; option loop (99–120) blocks
+  `--force`, `--force-if-includes`, `--force-with-lease*`, `-f` clusters, `+ref`;
+  destination loop (123–140); refspec-less resolution (146–151) via `git -C
+  "${GITDIR:-${CWD:-.}}" rev-parse --abbrev-ref HEAD`; segment split (175) on `&&`,
+  `||`, `;`, `|`, `(`, `)`.
+- CLI 2.1.278: `claude plugin list --json` entries carry `enabled, id, installPath,
+  installedAt, lastUpdated, scope, version`; `installPath` for a marketplace install of
+  another plugin reads `<config>/plugins/cache/<marketplace>/<plugin>/<version>`;
+  `claude plugin validate --help`: `<path>` is "a plugin or marketplace manifest, or the
+  skills, agents, and commands in a directory", with `--strict` and `--json`.
+- README: route (b) at 47–56, the (b) import bullet at 129–132, kill switch at
+  177–187, tests at 234–246; no mention of `.gitattributes`. `WORKFLOW.md` 128–129
+  lists `hooks, size, dedupe, scan`.
+- The continuation-join loop in `protect-branches.sh` (158–171) is quadratic as well:
+  measured 2.0 s under bash 5 and 5.9 s under `/bin/bash` 3.2 for a 2 000-line,
+  112k-character input, against 0.03 s for the awk one-liner T1 specifies, which also
+  joins a backslash-newline continuation correctly (checked with `sed -n l`). `.gitattributes` is one line, `docs/plans/** linguist-generated=true`.
+  `.gitignore` tracks `docs/plans/*.md`, so the new plan file is not ignored.
+
+### Docs and API currency (cw:researcher, sonnet, 2026-09-22; context7 down, WebFetch on code.claude.com/docs/en/*.md; CLI 2.1.278)
+
+1. PreToolUse stdin for Bash (hooks.md example payload): `session_id`, `prompt_id`,
+   `transcript_path`, `cwd`, `scratchpad_dir`, `permission_mode`, `hook_event_name`,
+   `tool_name`, `tool_input{command, description, timeout, run_in_background}`,
+   `tool_use_id`. No branch or worktree field exists. `cwd` "changes when Claude
+   executes a `cd` command"; whether it reflects a `cd` from an earlier separate Bash
+   call is not spelled out (medium confidence).
+2. Output: "Exit 2 means a blocking error … exit 2 blocks whether or not you print
+   JSON: even a JSON `permissionDecision` of `"allow"` can't override it"; other
+   non-zero codes do not block and show a hook-error notice. JSON on exit 0 can
+   `allow`/`deny`/`ask` (permissions.md: "The hook output can deny the tool call,
+   force a prompt, or skip the prompt"). "A blocking hook also takes precedence over
+   allow rules." Whether exit-2 stderr reaches the model's context is not stated
+   (the docs say the blocking message is the stderr text; observed in this repo's
+   validation rounds: the model sees it).
+3. Timeouts: default 600 s for command hooks; this plugin sets 10 s in `hooks.json`.
+   "A timed-out `command`, `http`, or `mcp_tool` hook doesn't block the tool call.
+   The call continues through the normal permission flow, so don't count on a
+   stalled hook to act as a gate." No documented minimum.
+4. SessionStart matcher values: `startup`, `resume`, `clear`, `compact`, `fork`;
+   syntax `"matcher": "startup|resume"` or omitted for all.
+5. Permissions (permissions.md): "`Bash(git push *)` | Stops `git push origin main`
+   | Doesn't stop `git -C . push origin main`, `git -c push.default=current push
+   origin main`, `git 'push' origin main`"; "A deny rule doesn't match the same
+   program by path or inside `sh -c`"; Claude Code splits compound commands on
+   `&&`, `||`, `;`, `|`, `|&`, `&`, newlines for rule evaluation; "Hook decisions
+   don't bypass permission rules … A hook that exits with code 2 stops the tool call
+   before permission rules are evaluated." Plugin manifest schema has no
+   `permissions` key; a plugin `settings.json` supports only `agent` and
+   `subagentStatusLine`. So a plugin cannot ship permission rules.
+6. Install layout (plugins-reference.md): cache under `~/.claude/plugins/cache`;
+   "each installed version is a separate directory in the cache, grouped by
+   marketplace and plugin and named for the resolved version"; on update the old
+   version directory is orphaned and swept about 14 days later. The researcher
+   reported the CLI reference as describing a path field on `details --json`; the
+   design reviewer could not find `installPath` or a `details --json` form on
+   plugins-reference.md, so the field is recorded here as a 2.1.278 observation only:
+   `claude plugin list --json` entries carry `installPath` (seen on the maintainer's
+   profile), which is what T2's README wording relies on. `${CLAUDE_PLUGIN_ROOT}` is substituted only in skill and
+   agent content, hook commands and MCP/LSP configs, not in a user's `CLAUDE.md`.
+7. `claude plugin validate`: "A plugin with a manifest: `claude plugin validate
+   ./my-plugin`"; behaviour with both manifests in one directory is undocumented
+   (observed: the marketplace manifest wins); `--help` accepts a manifest file path.
+8. Shellcheck: SC2317 false-positives on trap-invoked functions are a known open
+   class (issues #2542, #2660); SC2329 was found as introduced in 0.11.0 (medium
+   confidence; conflicts with the "0.10+" wording in `hooks/profile-check.sh:14`). The
+   directive pair `disable=SC2317,SC2329` is the working suppression.
+9. Changelog since 2.1.269 relevant here: 2.1.271 fixed `cd`+`git`/subshell chains
+   skipping a read-guard prompt in bypass/auto mode and wildcard-expansion targets
+   being skipped in permission checks; 2.1.274 fixed Bash permission checks for
+   special shell variables; 2.1.275 npm-sourced plugins install with
+   `--ignore-scripts`; 2.1.277 fixed reinstall corrupting an in-use plugin copy.
+
+### Best practices and prior art (cw:researcher, sonnet, 2026-09-22)
+
+1. Prior art: `Yodaisgaming/claude-code-command-guard` splits on `&&`, `||`, `;`, `|`,
+   newlines and "re-scans interpreter bodies" (`bash -c`, `sh -c`, `python -c`, `node
+   -e`, `$(…)`, backticks), fail-closed on unparseable input, and documents that it
+   does not re-scan `xargs`, `find -exec` or `ssh`. `ArjenSchwarz/agentic-coding`
+   `no-push-main.py` blocks `feature:main`, `+main`, `HEAD:refs/heads/main`,
+   `--mirror`, `--all`, `--delete origin main`, `origin :main`, resolves the current
+   branch with `git rev-parse` for refspec-less pushes, and does not handle `cd`/`git
+   -C` chains. `PrimeIntellect-ai/prime-agent` PR #2395 went through four review
+   rounds: continuation joining, case-insensitive `GIT`/`SH`, `f=-f; git push $f`,
+   nesting at depth 3+ via `eval`/`sh -c`/`env -S`, `CDPATH`, a ReDoS regex replaced
+   by linear string logic; end state "refuse on any unresolvable argument". Simple
+   guards (Trail of Bits config, aihero.dev) are one regex such as
+   `git[[:space:]]+push.*(main|master)`.
+2. Tokenising in bash 3.2: `read -ra` does not honour quotes (SC2206, Greg's wiki);
+   `xargs` honours quotes but errors on unbalanced ones and differs BSD/GNU; `eval
+   set --` executes the untrusted text (rejected); gawk `FPAT` is non-portable; a
+   here-string costs a temp file per call (`read -ra <<<` ≈ 0.098 s vs IFS array
+   assignment ≈ 0.011 s in one micro-benchmark). The researcher recommends an
+   index-based single-pass state machine; this plan's choice (strip quotes once,
+   split once, builtin array assignment per segment) is the linear variant that also
+   flattens nesting, see Approach 2.
+3. Nested shells: consensus is extract-and-recurse with a bounded depth and refuse
+   beyond it; `xargs`/`find -exec`/`ssh` bodies are a gap in every reviewed guard;
+   no over-blocking complaints were found that stem from nested-shell re-scanning
+   itself, they cluster on cwd/branch resolution and blanket pattern catalogues.
+4. Chained state: `pmgledhill102/agentic-coding-config` issue #404 documents `cd
+   /other/clone && git push -u origin <branch>` defeating cwd resolution, and that a
+   deny "rejects the whole Bash call" (a heredoc in the same call is lost too); its
+   PR #518 "walks the command's segments in order, following `cd` and `git -C` …
+   and skips when a path cannot be resolved statically (variables, globs, quoted
+   paths)". `git -C` overrides a preceding `cd` for that invocation. Fail-closed on
+   unresolvable state is the convergent principle (dcg, Yodaisgaming, prime-agent).
+5. Force semantics: general git practice prefers `--force-with-lease` plus
+   `--force-if-includes` over `--force`; agent guards allow lease variants only to
+   non-default branches and block them to `main`/`master` like plain force
+   (ArjenSchwarz, Dicklesworthstone). `--all`, `--mirror`, `--delete` and `:main`
+   are blocked unconditionally in both; `--prune` appears in no push guard.
+6. Scope statements: Trail of Bits calls its hooks "guardrails, not walls … not a
+   security boundary"; Yodaisgaming targets "honest mistakes … a loud stop, not
+   silent cleverness"; agentkit.best: "a useful guardrail, but it is not an
+   operating-system sandbox". The one concrete over-blocking cost with evidence is
+   issue #404's whole-call rejection; claims that users disable over-blocking guards
+   were found only as unsourced aggregates (low confidence).
+7. Performance: no third-party benchmark of tokenisers at 10k–100k characters; the
+   mechanism behind quadratic bash loops is per-iteration string re-slicing or
+   appending (codearcana.com profiling); no dataset of real Claude Code command
+   lengths exists (the 40k-character figure is this repo's own measurement).
+
+# Tasks
+
+Five commits plus one verification-only task. T2, T3 and T4 own disjoint files and are
+independent of each other and of T1; T1 is the hook rewrite (its own commit); T5 the
+design-draft amendment; T6 the release gate. Run order: T1, T2, T3, T4 together; T5
+after T1 (its D6.3 count depends on T1's final case total); T6 last.
+
+Note to the `/cw:build` orchestrator, Phase 0: invoke as `/cw:build hardening-1-0-0
+continue` with `feat/cw-plugin` checked out; never branch from `main`. Before the design
+commit, run `N=$(sed -n 's/^Copyright (c) [0-9]* //p' LICENSE | cut -d' ' -f1); ! grep
+-qi "$N" docs/plans/hardening-1-0-0.md` (CI's name gate covers `docs`). The design commit
+`docs(hardening-1-0-0): design` ends with exactly one trailer line per
+`rules/workflow.md` and no session line; check it right after committing. Then stage the
+two out-of-repo aids the gates use, into `~/.claude/plans/cw-plugin-gates/` (private,
+already holds the release-gate scripts): `repro-hooks.sh` and `shellcheck-0.9.0`, copied
+from the design session's scratchpad (under `/private/tmp/claude-501/`, this
+project's directory, session `d64245ad-2e4a-4ac3-992e-f237c756a53a`, `scratchpad/`;
+the path is not spelled out here because the project directory name would trip the
+name gate): `repro-hooks.sh` and `sc090/shellcheck-v0.9.0/shellcheck`. If that
+directory is gone,
+the binary comes from
+`https://github.com/koalaman/shellcheck/releases/download/v0.9.0/shellcheck-v0.9.0.darwin.x86_64.tar.xz`
+(resume an interrupted download with `curl -C -`), and the script's 18 rows are the
+F1–F6 payloads in the Context table plus five controls (push to main, push to a
+feature branch, env-prefixed push to main, bare push with cwd on main, bare push with
+cwd on a feature branch); Success criterion 1 gives every row's expected code. Neither copy is a gate: the harness is; they are
+checkpoint aids, and T1's verification skips the 0.9.0 run with a printed line when
+the binary is absent.
+
+Note for T1's prompt: point the implementer at this file's T1 block by path and id;
+do not paste payloads into the Agent brief or into any Bash command line (the live
+hook blocks push-to-main text, and a brief that spells such tests out has been denied
+by the permission classifier before). State the live-hook hazard verbatim from Risks.
+T2, T3 and T4 run alongside T1 and therefore call no `tests/run.sh` subcommand; T5 and
+T6 run after T1 and do. Several verification strings contain backticks inside their
+single-backtick code span (grep targets quoting markdown); extract a verification by
+stripping the `- verification: \`` prefix and the final backtick of the line only, as
+the previous round did, never by the first closing backtick.
+
+Note on briefing, for every agent in this build: the orchestrator's context is the
+scarce resource. Each implementer and reviewer writes its full report to a file under
+the session scratchpad and returns at most about 1 500 tokens: the required JSON block
+plus a few lines naming the file. Reviewers return findings only (severity, file:line,
+one reproducing command each), never evidence walkthroughs. The orchestrator reads a
+report file only when a verdict needs it. Fast-path reviews (T2–T5) run on sonnet;
+only T1's deep review runs on opus.
+
+## Task T1
+- scope: Rewrite the branch guard's front end for linear normalisation, nested-shell visibility, state tracking, upstream and `--all`/`--mirror` checks and lease semantics; widen the secrets patterns; make profile-check's error path and CRLF handling correct; add `compact` to the SessionStart matcher; prove every behaviour in the hook harness.
+- files_owned: [hooks/protect-branches.sh, hooks/protect-secrets.sh, hooks/profile-check.sh, hooks/hooks.json, tests/run.sh]
+- files_forbidden: [skills/**, agents/**, rules/**, README.md, WORKFLOW.md, CLAUDE.md, settings.example.json, .claude-plugin/**, .github/**, docs/**, tests/dedupe-phrases.txt, tests/settings-keys.txt, tests/fixtures/**]
+- depends_on: [none]
+- agent: implementer
+- model: sonnet
+- risk: high
+- verification: `shellcheck -x hooks/*.sh tests/run.sh && SC090="${CW_SC090:-$HOME/.claude/plans/cw-plugin-gates/shellcheck-0.9.0}" && if [ -x "$SC090" ]; then "$SC090" -x hooks/*.sh tests/run.sh; else echo "shellcheck 0.9.0 not present at $SC090; CI runs it"; fi && bash tests/run.sh hooks | tail -1 | grep -q ' 0 failed' && /bin/bash tests/run.sh hooks | tail -1 | grep -q ' 0 failed' && test "$(bash tests/run.sh hooks | tail -1 | sed 's/hooks: \([0-9]*\) passed.*/\1/')" -ge 58 && jq -e '.hooks.SessionStart[0].matcher=="startup|resume|clear|compact|fork"' hooks/hooks.json && ! grep -rn '</content>' hooks tests/run.sh` — expected exit 0; a present 0.9.0 binary that reports a finding fails the chain (the build's Phase 0 note says where the binary comes from). No `tests/run.sh all` here: its size, dedupe and trailers checks read files and commits that T2–T4 change in the same window; T5 and T6 run the full gate. The reproduction script is not part of this gate either: the harness covers every row it has, and Success criterion 1 states its expected output for the checkpoint.
+- commit: fix(hooks): harden the branch guard, widen secrets patterns, compact source
+
+Specification.
+
+`hooks/protect-branches.sh` — keep the file's shape (header comment, jq check, `block()`
+helper, `check_segment`, segment loop, `exit 0`). Changes:
+1. Parse with `2>/dev/null` on both jq calls; `[ -z "$CMD" ] && exit 0`.
+2. Join and normalise once: replace the bash continuation-join loop (lines 158–171)
+   with `CMD_JOINED=$(printf '%s\n' "$CMD" | awk '{ if (sub(/\\$/, "")) printf "%s ", $0; else print }')`
+   (BSD and GNU awk, one process; a line ending in a backslash is joined to the next
+   with a space, as the loop did; the jq check at the top of the script stays ahead of
+   it, because the harness's jq-absent case runs with a PATH that has no `awk` either,
+   `tests/run.sh:109`), then `CMD_NORM=$(printf '%s' "$CMD_JOINED" | tr -d
+   '"'"'"'\\' | tr '\t' ' ')` (two `tr` processes).
+3. Fast path on the normalised text: `case "$CMD_NORM" in *push*) ;; *) exit 0 ;; esac`.
+4. Split once: the existing `sed` segment split over `CMD_NORM`, with the backtick added
+   (`` s/`/\n/g ``) and a bare `&` added after the `&&` rule (`s/&/\n/g`, so a
+   backgrounded chain such as `git status & git push origin main` is two segments and
+   the push is examined; `2>&1` splits into harmless pieces) (one process). No further process is spawned per segment. Per
+   segment, inside the existing `while IFS= read -r line` loop: skip when blank; skip
+   cheaply unless the line matches the builtin glob
+   `*[Gg][Ii][Tt]*|*cd*|*pushd*|*popd*` (case-insensitive `git`, so `Git push` reaches
+   the scanner); then split into words with `set -f; TOK=( $line ); set +f` under the default
+   IFS (a `# shellcheck disable=SC2206` directive with a comment naming the reason:
+   deliberate word splitting with globbing off, no here-string, no process). Remove the
+   per-character `tokenize()` entirely, and the `TAB` variable with it (shellcheck
+   reports an unused variable as SC2034). A 100k-character command, whether one token
+   or thousands of segments, must stay under one second (harness speed cases).
+5. State tracking across segments (globals `TRACK_DIR`, `TRACK_BRANCH`, set before
+   `check_segment` returns; the last change wins). A segment containing a token equal
+   to `cd` or `pushd` (first occurrence, at any position, so a quote-stripped
+   interpreter body such as `sh -c cd <dir>` is tracked too): `TRACK_DIR` = the next
+   token when it starts with `/`, else `"$CWD/<token>"` when `CWD` is set, else the
+   token; a next token of `-`, no next token, a `popd` token, or a next token
+   containing `$` → `TRACK_DIR=unknown`; in every case `TRACK_BRANCH` is cleared
+   (unset). A `git` segment whose subcommand is `switch`
+   or `checkout`: walk the following tokens in order — `-b`, `-B`, `-c`, `-C` → the
+   next token is the branch, stop; `--`, `-p`, `--patch`, `HEAD`, `-`, or a token
+   containing `$` → `TRACK_BRANCH=unknown`, stop; any other token starting with `-` →
+   skip; the first remaining token → `TRACK_BRANCH=<token>`, stop; no token left →
+   `TRACK_BRANCH=unknown`. `git -C <dir>` sets `GITDIR` for that segment only; a
+   relative `<dir>` is joined to `CWD` the same way a `cd` argument is.
+6. Scanner: the first-`git`-token, first-subcommand logic stays (env assignments and
+   global options skipped); the token test becomes a `case` pattern
+   (`git|[Gg][Ii][Tt]|*/git|*/[Gg][Ii][Tt]`) so `GIT push` on a case-insensitive
+   filesystem matches without spawning a process. Backslashes are already gone, so
+   `\git` matches.
+7. Option loop after `push`: `--force|-f-cluster|+ref` block "force push is not allowed.";
+   `--all|--mirror` block "pushing every branch (--all/--mirror) is not allowed."; `-o`,
+   `--push-option`, `--repo` consume one token; every other `-`/`--` token (including
+   `--force-with-lease`, `--force-with-lease=*`, `--force-if-includes`, `--dry-run`,
+   `--tags`) is skipped.
+8. Destination loop: unchanged (`src:dst`, `refs/heads/` stripped, bare `main`/`master`,
+   a ref containing `/` counts as explicit).
+9. Refspec-less push (`has_explicit_ref` still 0, and `npos -le 1` or last positional
+   `HEAD` — exactly the existing condition at line 146): when `GITDIR` is set (a `-C`
+   in the push segment) resolve there and ignore the tracked state, because `git -C`
+   overrides a preceding `cd` or checkout for that invocation (Research §4);
+   otherwise, if `TRACK_BRANCH` is set and not `unknown` → block when it is
+   `main`/`master`, else allow (a `cd` after the branch change would have cleared it,
+   so a set branch is current); if `TRACK_BRANCH` or `TRACK_DIR` is `unknown` → block "cannot determine the destination after a cd or
+   branch change; use an explicit refspec such as git push origin <branch>."; else
+   `dir="${GITDIR:-${TRACK_DIR:-${CWD:-.}}}"`, `BR=$(git -C "$dir" rev-parse
+   --abbrev-ref HEAD 2>/dev/null)` → block "current branch is <BR>; push from a feature
+   branch." when main/master; additionally, on the same `dir` in both the `-C` path and the tracked/cwd path, when no
+   positional is `HEAD` and `npos -le 1`, and only when `git -C "$dir" config --get
+   push.default 2>/dev/null` prints `upstream` or `tracking`,
+   `UP=$(git -C "$dir" rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null)`
+   → block "current branch tracks <UP> and push.default is upstream; push to a feature
+   branch explicitly." when it ends in `/main` or `/master`. Resolution failure (not a repo) allows, as today.
+10. Header comment: describe the normalisation, the state tracking, the scope (guardrail
+    against the agent's own accidental pushes; out of scope: commands held in variables
+    and `eval "$X"`, xargs-fed refspecs, wrappers and aliases not named git, `git -c
+    k="v w"` before push; a `cd` or branch change the text cannot resolve blocks with a
+    hint; prose is treated as command text).
+
+`hooks/protect-secrets.sh` — pattern block line 35–39 gains `*.p12|*.netrc|*id_dsa*|
+*id_ecdsa*|*.tfstate|*.tfstate.backup`. Header comment line 3 unchanged.
+
+`hooks/profile-check.sh` — lines 110–115: `NEW=$(jq -nc … ) && OUT="$NEW"` in both
+branches (OUT keeps `{}` when jq fails); in the `.claude-profiles` loop (52) add
+`pline="${pline%$'\r'}"` right after the read (bash 3.2 supports `$'\r'`); line 2's
+header comment lists the five sources including `compact`; line 14's directive comment
+loses its version numbers ("older shellcheck reports SC2317, newer SC2329" — Research
+§2 item 8 could not pin the release).
+
+`hooks/hooks.json` — matcher line 27: `"startup|resume|clear|compact|fork"`.
+
+`tests/run.sh` — add `HOOKS_DIR="${CW_HOOKS_DIR:-$ROOT/hooks}"` next to `BASH_BIN` and use
+`"$HOOKS_DIR/…"` in every hook case (including the jq-absent case and the profile
+cases). Add a helper `push_case <expected> <description> <cwd> <command>` that builds the
+payload with `jq -nc --arg c "$4" --arg d "$3" '{tool_name:"Bash",tool_input:{command:$c},cwd:$d}'`
+and reports via `check_code`, so cases are one line each; commands must be single-quoted
+literals inside the script (never typed in a Bash tool command). In `cmd_hooks`, create
+four scratch repositories before the push cases, each with `user.name`/`user.email`
+and `commit.gpgsign=false` set via `-c` (the scratch repos inherit the real HOME's
+gitconfig): `$SCRATCH/rm` on `main` (one commit); `$SCRATCH/rf` cloned from it, then
+`git checkout -b feat/x` so HEAD is `feat/x`, no upstream; `$SCRATCH/rc` like `rf` plus
+`git branch --set-upstream-to=origin/main` (upstream on main, `push.default` unset);
+`$SCRATCH/ru` like `rc` plus `git config push.default upstream`. No case mutates a repo
+after setup, so case order does not matter. If `git init -b main` fails, the cases
+that name a scratch repo (the twelve resolution cases, the two state cases naming
+`$SCRATCH/rm` and the nested `sh -c` case naming it) are skipped with one plain
+`printf` line, not through `report`, so the summary counts only real cases. New cases, expected code in brackets (existing
+four push cases stay first):
+- nested: `sh -c "git push origin main"` [2]; `bash -c 'cd /tmp && git push origin main'` [2]; `eval "git push origin main"` [2]; `` echo `git push origin main` `` [2]; `sh -c "cd $SCRATCH/rm && git push"` [2] (literal path; the `cd` inside the body is tracked after quote removal)
+- backslash: `\git push origin main` [2]; `\git push -u origin feat/x` [0]
+- options: `git push --all origin` [2]; `git push --mirror origin` [2]; `git push origin --all` [2]; `git push --force-with-lease origin feat/x` [0]; `git push --force-with-lease=feat/x origin feat/x` [0]; `git push --force-if-includes origin feat/x` [0]; `git push --force-with-lease origin main` [2]; `git push -fu origin feat/x` [2]; `git push origin +feat/x` [2]; `git push origin HEAD:main` [2]; `git push origin --delete main` [2]; `git push origin :main` [2]; `git push origin --dry-run feat/x` [0]
+- names: `git push -u origin feat/main-nav` [0]; `git commit -m "docs: pushing to main is blocked"` [0]; `FOO=bar git push origin main` [2]; `git -c core.x=1 push origin main` [2]; `GIT push origin main` [2]
+- state, cwd `/tmp` (not a repo): `git switch main && git push` [2]; `git checkout main && git push origin` [2]; `cd $SCRATCH/rm && git push` [2] (the literal absolute path substituted when the case is built); `cd "$DIR" && git push` [2] (the `$DIR` stays literal in the payload); `git checkout -b feat/y && git push -u origin HEAD` [0]; `git checkout -- README.md && git push -u origin feat/x` [0]; `git checkout -b feat/y && cd $SCRATCH/rm && git push` [2] (literal path; the `cd` clears the recorded branch); `git status & git push origin main` [2] (a bare `&` is a separator)
+- resolution: cwd `$SCRATCH/rm`: `git push` [2], `git push origin` [2], `git push -u origin HEAD` [2], `git checkout -- README.md && git push` [2] (unknown branch blocks with the hint); cwd `$SCRATCH/rf`: `git push` [0], `git push -u origin HEAD` [0], `git -C $SCRATCH/rm push` [2]; cwd `$SCRATCH/ru`: `git push` [2] (upstream on main with `push.default=upstream`); cwd `$SCRATCH/rc`: `git push` [0] (same upstream, `push.default` unset: git's `simple` refuses that push itself, the guard does not); cwd `$SCRATCH/rm`: `git push feat/x` [0] (one positional containing a slash is an explicit destination, no resolution); cwd `/tmp`: `git checkout -b feat/y && git -C $SCRATCH/rm push` [2] (`-C` wins over the tracked branch), `git checkout -b feat/y && git -C $SCRATCH/rf push` [0]
+- speed, each reported as one case asserting both the exit code and `[ "$SECONDS" -le 1 ]` with `SECONDS=0` set just before the hook call: (i) one token of 100 000 `a` characters followed by ` && git push origin main` [2]; (ii) 5 000 segments `echo abcd-<index>` joined with ` && ` (each contains the substring `cd`, so every segment reaches the word split) followed by ` && git push origin main` [2]; (iii) 2 000 lines of `echo line-<index>-<40 letters>` joined with newlines (about 100 000 characters, no `push`) [0], the heredoc shape, proving the join is linear
+- input: stdin `not json` [0] and stderr empty (reported as one case); stdin `{}` [0]
+- secrets: `Write` `/tmp/x/certs/client.p12` [2]; `Write` `/tmp/x/.netrc` [2]; `Write` `/tmp/x/id_dsa` [2]; `Write` `/tmp/x/id_ecdsa` [2]; `Write` `/tmp/x/terraform.tfstate` [2]; `Write` `/tmp/x/terraform.tfstate.backup` [2] (the script reads only the path fields, so tool names beyond `Write` add no coverage)
+- profile: a `jq` shim on PATH that passes `command -v` but exits 5 on every call → stdout is exactly `{}` and exit 0; a `.claude-profiles` written with CRLF line endings whose mapping points at the active config dir → no `systemMessage` in the output
+Total new cases: 58 (nested 5, backslash 2, options 13, names 5, state 8, resolution 12, speed 3, input 2, secrets 6, profile 2) on top of the existing 15, so the summary reads `hooks: 73 passed, 0 failed` when the scratch repos can be created; the fifteen repo-dependent cases (one nested, two state, twelve resolution) are the skip path, so the summary reads 58 then and the verification's floor is 58. The design draft's D6.3 (T5) names the coverage classes, not a count, so adding a case later needs no docs edit.
+
+## Task T2
+- scope: Fix the README's marketplace install route and add the guard-scope and linguist notes; add `trailers` to WORKFLOW.md's standalone list.
+- files_owned: [README.md, WORKFLOW.md]
+- files_forbidden: [hooks/**, tests/**, skills/**, agents/**, rules/**, CLAUDE.md, settings.example.json, .claude-plugin/**, .github/**, docs/**]
+- depends_on: [none]
+- agent: implementer
+- model: sonnet
+- risk: trivial
+- verification: `grep -q 'plugins/cache/claude-code-setup/cw/<version>/' README.md && grep -q "claude plugin list --json" README.md && grep -q 'installPath' README.md && ! grep -q 'print the current cache path' README.md && test "$(grep -c 'separate throwaway clone' README.md)" = 1 && grep -qi 'not a sandbox' README.md && grep -q 'explicit refspec' README.md && grep -q 'linguist-generated' README.md && grep -q '(`hooks`, `size`, `dedupe`, `scan`, `trailers`)' WORKFLOW.md && test "$(wc -l < WORKFLOW.md)" -le 200 && ! grep -q '</content>' README.md WORKFLOW.md && ! grep -rnE '/(Users|home)/' README.md && ! grep -qE 'install.sh|merge-settings|/setup' README.md WORKFLOW.md` (no `tests/run.sh` call here: T1 rewrites that file in the same window; T6 runs the full gate)
+- commit: docs: real plugin cache path, branch-guard scope, trailers in the test list
+
+Exact edits.
+1. README.md line 54–56 (route (b) paragraph): replace with: "This installs a copy into
+   the plugin cache at `~/.claude/plugins/cache/claude-code-setup/cw/<version>/` (the
+   version directory changes on every `claude plugin update cw@claude-code-setup`),
+   independent of any local checkout."
+2. README.md lines 129–132 (the whole (b) import bullet, four lines at head `fafca6f`,
+   ending "…just for stable import paths."): replace with: "**(b) marketplace** —
+   print the installed path with `claude plugin list --json | jq -r '.[] |
+   select(.id==\"cw@claude-code-setup\") | .installPath'` and import
+   `@<that path>/rules/workflow.md`; the path changes on every update, so re-check it
+   after updating, or keep a separate throwaway clone just for stable import paths."
+   (Keep the surrounding bullets; the phrase "separate throwaway clone" must occur
+   exactly once in the file afterwards.)
+3. README.md, after the Kill switch paragraph (line 187) and before `## Migration`, insert
+   a paragraph headed `### What the branch guard does` (or a bold lead-in; a `###` is
+   fine): it reads the text of each Bash command, splits it on shell separators,
+   strips quotes and backslashes so nested `sh -c`/`bash -c`/`eval` strings and a
+   backslash-escaped `git` are inspected too, tracks
+   `cd` and `git switch`/`checkout` earlier in the same command, and blocks a `git push`
+   whose destination is `main`/`master` (explicit refspec, the current branch, or an
+   upstream on main), plain force pushes (`--force`, `-f`, `+ref`), and `--all`/
+   `--mirror`; lease pushes (`--force-with-lease`, `--force-if-includes`) to a feature
+   branch pass. When a `cd` or branch change earlier in the command cannot be resolved
+   from the text (a variable, `cd -`, a path checkout), a bare `git push` after it is
+   blocked with a hint to use an explicit refspec. It is a guardrail against the
+   agent's own accidental pushes, not a sandbox: a command held in a variable,
+   `xargs`-fed refspecs, wrappers and aliases not named `git`, and `gh api` calls are
+   out of scope, and a line of prose that spells a push to main inside a command is
+   blocked as if it were the command (keep such text in a file). Do not use the phrase
+   "push directly to main".
+4. README.md, in the section that describes the repository layout or right after
+   "Running the tests" (implementer's choice, one sentence): `.gitattributes` marks
+   `docs/plans/**` as `linguist-generated`, so design documents are collapsed by
+   default in GitHub diffs and excluded from language statistics.
+5. WORKFLOW.md line 129 (the line beginning "(`hooks`, `size`, `dedupe`, `scan`), and
+   CI"): the list becomes `(\`hooks\`, \`size\`, \`dedupe\`, \`scan\`, \`trailers\`)`;
+   keep the whole parenthesised list on one line (the verification greps it as one
+   string) and the file at or under 200 lines.
+
+## Task T3
+- scope: One-line prompt fixes: name the task blocks `/cw:build` reads, make the implementer agent's Output section name the exit report the build gate parses, and make the ship skill pass the PR body through a file so the hardened guard never reads it as a command.
+- files_owned: [rules/workflow.md, agents/implementer.md, skills/ship/SKILL.md]
+- files_forbidden: [hooks/**, tests/**, skills/build/**, skills/design/**, skills/search/**, skills/compound/**, skills/google-workspace/**, README.md, WORKFLOW.md, CLAUDE.md, settings.example.json, .claude-plugin/**, .github/**, docs/**, rules/orchestration.md, agents/reviewer.md, agents/researcher.md, agents/design-reviewer.md, agents/direction-reviewer.md]
+- depends_on: [none]
+- agent: implementer
+- model: sonnet
+- risk: trivial
+- verification: `grep -q 'reads the `## Task <id>` blocks of that' rules/workflow.md && ! grep -q '## Tasks' rules/workflow.md && grep -q '^5\. ' agents/implementer.md && grep -qi 'exit report' agents/implementer.md && test "$(wc -l < rules/workflow.md)" -le 40 && test "$(wc -l < agents/implementer.md)" -le 150 && ! git grep -nwE 'NEVER|ALWAYS|MUST|CRITICAL' -- rules agents && ! grep -q '</content>' rules/workflow.md agents/implementer.md && ! grep -qiF -f tests/dedupe-phrases.txt agents/implementer.md && grep -q -- '--body-file' skills/ship/SKILL.md && test "$(wc -l < skills/ship/SKILL.md)" -le 150 && ! grep -q '</content>' skills/ship/SKILL.md` (no `tests/run.sh` call here: T1 rewrites that file in the same window; T6 runs the full gate; the dedupe grep keeps the implementer file free of every single-home phrase, which it is today; the ship skill already holds one such phrase as its home, so its added sentence is checked by T6's dedupe run instead)
+- commit: fix(skills): ship body via file, build reads Task blocks, implementer exit report
+
+Exact edits. `rules/workflow.md` line 18–19: "`/cw:build <slug> [continue [<task-id>]]`
+reads the `## Task <id>` blocks of that file, commits the design as `docs(<slug>):
+design`, delegates every change to an implementer, and stops at the checkpoint before
+the PR." (re-wrap so that line 18 ends with "blocks of that" and line 19 starts with
+"file,": the phrase `reads the \`## Task <id>\` blocks of that` is four characters longer
+than today's fill and must survive on one line). `agents/implementer.md` Output list
+gains a fifth item: "5. When the orchestrator's prompt specifies an exit report, end
+with that fenced JSON block exactly as specified — the build gate parses it."
+`skills/ship/SKILL.md` Step 5 item 2 (the `gh pr create` instruction) gains one
+sentence after its body template: "Write the body to a file in the scratchpad and pass
+it with `--body-file <file>`: the branch guard reads Bash command text, and a body that
+mentions a push to `main` inline would be blocked as if it were the command." Do not
+add any phrase from `tests/dedupe-phrases.txt`; the three files stay under their line
+caps (40, 150, 150) and the byte baseline has about 19 kB of headroom today (54 661 of
+73 738 bytes), so three added lines cannot trip it.
+
+## Task T4
+- scope: Make CI validate the plugin manifest as well as the marketplace manifest.
+- files_owned: [.github/workflows/ci.yml]
+- files_forbidden: [hooks/**, tests/**, skills/**, agents/**, rules/**, README.md, WORKFLOW.md, CLAUDE.md, settings.example.json, .claude-plugin/**, docs/**]
+- depends_on: [none]
+- agent: implementer
+- model: sonnet
+- risk: trivial
+- verification: `grep -q '^          claude plugin validate \.$' .github/workflows/ci.yml && grep -q '^          claude plugin validate \.claude-plugin/plugin\.json$' .github/workflows/ci.yml && claude plugin validate . && claude plugin validate .claude-plugin/plugin.json && { python3 -c 'import yaml' 2>/dev/null && python3 -c 'import yaml; yaml.safe_load(open(".github/workflows/ci.yml"))' || echo "yaml module absent; indentation asserted by the greps"; } && ! grep -q '</content>' .github/workflows/ci.yml`
+- commit: chore(ci): validate the plugin manifest as well as the marketplace
+
+Exact edit: in the ubuntu job's "install Claude Code CLI and validate plugin" step, add
+the line `          claude plugin validate .claude-plugin/plugin.json` (ten spaces)
+after `          claude plugin validate .`. If the CLI rejects a manifest path (the
+`--help` text says a manifest path is accepted), report it in the exit report instead of
+inventing another form; the orchestrator then drops the task.
+
+## Task T5
+- scope: Amend the released design draft where behaviour changed: the D2.4 hook paragraph and scope, the SessionStart matcher, and D6.3's description of what the hook harness covers (coverage classes instead of a case count).
+- files_owned: [docs/plans/cw-plugin/cw-plugin-design-draft.md]
+- files_forbidden: [hooks/**, tests/**, skills/**, agents/**, rules/**, README.md, WORKFLOW.md, CLAUDE.md, settings.example.json, .claude-plugin/**, .github/**, docs/plans/cw-plugin/cw-plugin-tasks.md, docs/plans/cw-plugin/cw-plugin-research-*.md, docs/plans/hardening-1-0-0.md, docs/plans/fixups-1-0-0.md]
+- depends_on: [T1]
+- agent: implementer
+- model: sonnet
+- risk: trivial
+- verification: `grep -q 'startup|resume|clear|compact|fork' docs/plans/cw-plugin/cw-plugin-design-draft.md && ! grep -q 'startup|resume|clear|fork`' docs/plans/cw-plugin/cw-plugin-design-draft.md && grep -q 'nested interpreters' docs/plans/cw-plugin/cw-plugin-design-draft.md && ! grep -q '15 hook cases' docs/plans/cw-plugin/cw-plugin-design-draft.md && grep -qi 'not a sandbox' docs/plans/cw-plugin/cw-plugin-design-draft.md && grep -q 'force-with-lease' docs/plans/cw-plugin/cw-plugin-design-draft.md && ! grep -q '</content>' docs/plans/cw-plugin/cw-plugin-design-draft.md && bash tests/run.sh all` (T5 runs after T1 has landed, so the full gate is safe here)
+- commit: docs(cw-plugin): design reflects the hardened guard, compact source, harness coverage
+
+Exact edits. Lines 218–225 (the `protect-branches.sh` bullet): rewrite to describe the
+shipped behaviour: fast path on `push`; split on `&&`, `||`, `;`, `|`, `(`, `)`,
+backticks and newlines; quotes and backslashes stripped so nested `sh -c`/`bash -c`/
+`eval` strings and `\git` are inspected; `cd`/`pushd` and `git switch`/`checkout`
+earlier in the command tracked for later refspec-less pushes (unknown targets block
+with an explicit-refspec hint); blocks a `git push` whose destination is main/master by
+explicit refspec, tracked or resolved current branch, or an upstream on main; blocks
+`--force`/`-f`/`+ref` and `--all`/`--mirror`; `--force-with-lease`,
+`--force-with-lease=<ref>` and `--force-if-includes` pass to other destinations;
+everything else exits 0; then the scope sentence (guardrail against the agent's own
+accidental pushes, not a sandbox; the named out-of-scope forms; prose treated as
+command text). Keep the no-opt-out sentence. Line 230: matcher `startup|resume|clear|
+compact|fork` (keep the matcher string on one line; the line may exceed the file's
+usual width). D6.3: replace `15 hook cases` with "hook cases covering nested
+interpreters, an escaped git token, chained cd and branch changes, --all/--mirror,
+lease variants, an upstream on main under push.default=upstream, 100k-character
+timing, the secrets patterns and profile-check's error paths; 0 failed" (the phrase
+`nested interpreters` on one line). Nothing else in the file.
+
+## Task T6
+- scope: Release gate re-run on the finished series, verification only.
+- files_owned: []
+- files_forbidden: [**]
+- depends_on: [T1, T2, T3, T4, T5]
+- agent: implementer
+- model: sonnet
+- risk: trivial
+- verification: `bash tests/run.sh all && bash tests/run.sh all | grep -q '^all: trailers: PASS$' && /bin/bash tests/run.sh hooks | tail -1 | grep -q ' 0 failed' && shellcheck -x hooks/*.sh tests/run.sh && SC090="${CW_SC090:-$HOME/.claude/plans/cw-plugin-gates/shellcheck-0.9.0}" && if [ -x "$SC090" ]; then "$SC090" -x hooks/*.sh tests/run.sh; else echo "shellcheck 0.9.0 not present; CI runs it"; fi && claude plugin validate . && claude plugin validate .claude-plugin/plugin.json && jq empty .claude-plugin/plugin.json .claude-plugin/marketplace.json hooks/hooks.json && ! git grep -nwE 'NEVER|ALWAYS|MUST|CRITICAL' -- skills agents rules && ! git grep -niE 'opus needs|do not trust|be decisive|read all files fresh|claude-design-active|claude-orchestrator-active' -- skills agents rules && ! git grep -niE 'under 50 lines' -- skills agents rules && ! git grep -nE '^(disallowedTools|permissionMode|mcpServers|hooks):' -- agents && ! git grep -niE '~/.claude/plans|gitattributes|linguist|git clean' -- skills && OWNER=$(sed -n 's/^Copyright (c) [0-9]* //p' LICENSE | cut -d' ' -f1) && test -n "$OWNER" && ! git grep -qi "$OWNER" -- skills agents rules hooks tests WORKFLOW.md CLAUDE.md docs && ! grep -rn '</content>' hooks tests/run.sh README.md WORKFLOW.md rules agents docs/plans/cw-plugin/cw-plugin-design-draft.md && for s in 'fix(hooks): harden the branch guard, widen secrets patterns, compact source' 'docs: real plugin cache path, branch-guard scope, trailers in the test list' 'fix(skills): ship body via file, build reads Task blocks, implementer exit report' 'chore(ci): validate the plugin manifest as well as the marketplace' 'docs(cw-plugin): design reflects the hardened guard, compact source, harness coverage' 'docs(hardening-1-0-0): design'; do test "$(git log --format=%s main..HEAD | grep -c -F -x -- "$s")" = 1 || exit 1; done && test -z "$(git status --short)"`
+- commit: none
+
+T6 owns no file: a failed check is reported at the checkpoint with the failing command's
+output; a content failure belongs to the task that owns the file; a trailer-only failure
+is fixed at the checkpoint by amend or autosquash fixup and T6 re-run. The plan file
+itself is in the LICENSE-name grep's scope (`docs`), which is why it names no person.

From 640b9197f273343413f5de71bd45accf7511c226 Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Tue, 22 Sep 2026 11:57:09 +0100
Subject: [PATCH 17/24] chore(ci): validate the plugin manifest as well as the
 marketplace

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .github/workflows/ci.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1fc68e5..4248097 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -76,6 +76,7 @@ jobs:
         run: |
           npm install -g @anthropic-ai/claude-code
           claude plugin validate .
+          claude plugin validate .claude-plugin/plugin.json
 
   macos:
     name: hooks under system bash 3.2 (macos)

From 9438f0126d0b60039a4d6a0fe8d258ae656404c9 Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Tue, 22 Sep 2026 11:57:38 +0100
Subject: [PATCH 18/24] fix(skills): ship body via file, build reads Task
 blocks, implementer exit report

Co-Authored-By: Claude <noreply@anthropic.com>
---
 agents/implementer.md | 2 ++
 rules/workflow.md     | 2 +-
 skills/ship/SKILL.md  | 4 ++++
 3 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/agents/implementer.md b/agents/implementer.md
index 10b246c..ebbeae6 100644
--- a/agents/implementer.md
+++ b/agents/implementer.md
@@ -40,3 +40,5 @@ When done, provide a concise summary:
 2. Design deviations, if any, and why
 3. Test and build results
 4. Known limitations or TODOs
+5. When the orchestrator's prompt specifies an exit report, end with that
+   fenced JSON block exactly as specified — the build gate parses it.
diff --git a/rules/workflow.md b/rules/workflow.md
index f487b0c..b853511 100644
--- a/rules/workflow.md
+++ b/rules/workflow.md
@@ -15,7 +15,7 @@ routing and workflow usage follow the orchestration rules.
 - `/cw:design` runs in plan mode; on approval the single plan file moves to the
   project's `docs/plans/<slug>.md`, which is the canonical copy. In a folder
   that is not a repo the file stays where plan mode put it.
-- `/cw:build <slug> [continue [<task-id>]]` reads the `## Tasks` section of that
+- `/cw:build <slug> [continue [<task-id>]]` reads the `## Task <id>` blocks of that
   file, commits the design as `docs(<slug>): design`, delegates every change to
   an implementer, and stops at the checkpoint before the PR.
 - `/cw:ship` runs the quality gate, pushes the branch, opens the PR, and ends by
diff --git a/skills/ship/SKILL.md b/skills/ship/SKILL.md
index 95c73ef..32723c7 100644
--- a/skills/ship/SKILL.md
+++ b/skills/ship/SKILL.md
@@ -100,6 +100,10 @@ single trailer line as the rest of the series.
    ## Design Reference
    docs/plans/<slug>.md
    ```
+   Write the body to a file in the scratchpad and pass it with
+   `--body-file <file>`: the branch guard reads Bash command text, and a body
+   that mentions a push to `main` inline would be blocked as if it were the
+   command.
 3. Report the PR URL.
 
 ## Step 6: Offer `/cw:compound`

From 01fffdd49c47ba96c2128f91957f53b90d1c275c Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Tue, 22 Sep 2026 11:58:06 +0100
Subject: [PATCH 19/24] docs: real plugin cache path, branch-guard scope,
 trailers in the test list

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md   | 39 +++++++++++++++++++++++++++++++--------
 WORKFLOW.md |  2 +-
 2 files changed, 32 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 21ed80c..fa6c26e 100644
--- a/README.md
+++ b/README.md
@@ -51,9 +51,10 @@ claude plugin marketplace add victorkzam/claude-code-setup
 claude plugin install cw@claude-code-setup
 ```
 
-This installs a copy into the plugin cache
-(`~/.claude/plugins/cache/claude-code-setup/cw/`), independent of any local
-checkout. Update it with `claude plugin update cw@claude-code-setup`.
+This installs a copy into
+the plugin cache at `~/.claude/plugins/cache/claude-code-setup/cw/<version>/` (the
+version directory changes on every `claude plugin update cw@claude-code-setup`),
+independent of any local checkout.
 
 ### (c) Trial — no install at all
 
@@ -126,10 +127,10 @@ The import path depends on how you installed:
 
 - **(a) in place / (c) trial** — import from your checkout directly:
   `@<checkout>/rules/workflow.md`.
-- **(b) marketplace** — run `claude plugin details cw@claude-code-setup` to
-  print the current cache path and import from there; that path changes on
-  every `claude plugin update cw@claude-code-setup`, so re-check it after
-  updating, or keep a separate throwaway clone just for stable import paths.
+- **(b) marketplace** — print the installed path with `claude plugin list --json | jq -r
+  '.[] | select(.id=="cw@claude-code-setup") | .installPath'` and import
+  `@<that path>/rules/workflow.md`; the path changes on every update, so re-check it
+  after updating, or keep a separate throwaway clone just for stable import paths.
 
 Also set `plansDirectory: docs/plans` in your settings so `/cw:design`'s plan
 mode writes the plan file into the project instead of the default location.
@@ -186,6 +187,26 @@ pushes to `main` by convention — `protect-branches.sh` has no opt-out
 environment variable by design, so disabling the plugin is the supported
 escape hatch, not a bypass flag on the hook itself.
 
+### What the branch guard does
+
+`protect-branches.sh` reads the text of each Bash command, splits it on shell
+separators, strips quotes and backslashes so nested `sh -c`/`bash -c`/`eval`
+strings and a backslash-escaped `git` are inspected too, and tracks `cd` and
+`git switch`/`checkout` earlier in the same command. It blocks a `git push`
+whose destination is `main`/`master` (an explicit refspec, the current
+branch, or an upstream on main), plain force pushes (`--force`, `-f`,
+`+ref`), and `--all`/`--mirror`; lease pushes (`--force-with-lease`,
+`--force-if-includes`) to a feature branch pass. When a `cd` or branch change
+earlier in the command can't be resolved from the text (a variable, `cd -`,
+a path checkout), a bare `git push` after it is blocked with a hint to use
+an explicit refspec.
+
+It is a guardrail against the agent's own accidental pushes, not a sandbox: a
+command held in a variable, `xargs`-fed refspecs, wrappers and aliases not
+named `git`, and `gh api` calls are out of scope, and a line of prose that
+spells out a push to the default branch inside a command is blocked as if it
+were the command itself — keep such text in a file instead.
+
 ## Migration from the old installer
 
 If you previously installed this project's files directly into `~/.claude`
@@ -243,7 +264,9 @@ and a per-commit trailer check on `main..HEAD` (skipped, and reported as
 such, only when neither `main` nor `origin/main` resolves).
 Optionally set `CW_SCAN_PATTERNS=<your private pattern file>` to also scan
 the tracked tree for private strings you've defined — this is empty by
-default and off unless you set it.
+default and off unless you set it. `.gitattributes` marks `docs/plans/**` as
+`linguist-generated`, so design documents are collapsed by default in GitHub
+diffs and excluded from language statistics.
 
 ## Changelog
 
diff --git a/WORKFLOW.md b/WORKFLOW.md
index 917438d..8a57c62 100644
--- a/WORKFLOW.md
+++ b/WORKFLOW.md
@@ -126,5 +126,5 @@ description-length caps (`size`), a cross-file phrase-duplication check
 (`dedupe`), the `settings.example.json` / `tests/settings-keys.txt`
 cross-check, and, if `$CW_SCAN_PATTERNS` points at a pattern file, a scan for
 private strings in the tracked tree. Each subcommand also runs standalone
-(`hooks`, `size`, `dedupe`, `scan`), and CI (`.github/workflows/ci.yml`) runs
+(`hooks`, `size`, `dedupe`, `scan`, `trailers`), and CI (`.github/workflows/ci.yml`) runs
 the same `all` target on every push and PR.

From c07fdb8276bcda8d10d41e0fc63260f1d0b3a1a3 Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Tue, 22 Sep 2026 12:11:24 +0100
Subject: [PATCH 20/24] fix(hooks): harden the branch guard, widen secrets
 patterns, compact source

Co-Authored-By: Claude <noreply@anthropic.com>
---
 hooks/hooks.json          |   2 +-
 hooks/profile-check.sh    |  13 +-
 hooks/protect-branches.sh | 420 +++++++++++++++++++++++++++-----------
 hooks/protect-secrets.sh  |   4 +-
 tests/run.sh              | 331 ++++++++++++++++++++++++++++--
 5 files changed, 626 insertions(+), 144 deletions(-)

diff --git a/hooks/hooks.json b/hooks/hooks.json
index 644ffcb..bb9eb6d 100644
--- a/hooks/hooks.json
+++ b/hooks/hooks.json
@@ -24,7 +24,7 @@
     ],
     "SessionStart": [
       {
-        "matcher": "startup|resume|clear|fork",
+        "matcher": "startup|resume|clear|compact|fork",
         "hooks": [
           {
             "type": "command",
diff --git a/hooks/profile-check.sh b/hooks/profile-check.sh
index f802bfc..6ca2ef2 100755
--- a/hooks/profile-check.sh
+++ b/hooks/profile-check.sh
@@ -1,5 +1,5 @@
 #!/bin/bash
-# SessionStart(startup|resume|clear|fork) — surface profile-config mismatches
+# SessionStart(startup|resume|clear|compact|fork) — surface profile-config mismatches
 # and missing CLAUDE.md imports as a SessionStart notice. Always exits 0
 # (exit 2 would block session initialization) and always prints exactly one
 # JSON line to stdout, even on an internal error.
@@ -11,7 +11,7 @@ if ! command -v jq >/dev/null 2>&1; then
 fi
 
 OUT='{}'
-# shellcheck disable=SC2317,SC2329 # invoked indirectly via `trap ... EXIT` below; 0.9.0 reports SC2317, 0.10+ SC2329
+# shellcheck disable=SC2317,SC2329 # invoked indirectly via `trap ... EXIT` below; older shellcheck reports SC2317, newer SC2329
 finish() {
   printf '%s\n' "$OUT"
   exit 0
@@ -50,6 +50,7 @@ if [ -f "$PROFILES_FILE" ]; then
   BEST_PREFIX=""
   BEST_DIR=""
   while IFS= read -r pline || [ -n "$pline" ]; do
+    pline="${pline%$'\r'}"
     case "$pline" in
       \#*) continue ;;
     esac
@@ -107,12 +108,12 @@ if [ ${#NOTICES[@]} -gt 0 ]; then
       MSG="$MSG; $n"
     fi
   done
-  OUT=$(jq -nc --arg msg "$MSG" \
-    '{systemMessage: $msg, hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $msg}}')
+  NEW=$(jq -nc --arg msg "$MSG" \
+    '{systemMessage: $msg, hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $msg}}') && OUT="$NEW"
 else
   BASE=$(basename "$ACTIVE")
-  OUT=$(jq -nc --arg ctx "profile $BASE · plugin cw" \
-    '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $ctx}}')
+  NEW=$(jq -nc --arg ctx "profile $BASE · plugin cw" \
+    '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $ctx}}') && OUT="$NEW"
 fi
 
 exit 0
diff --git a/hooks/protect-branches.sh b/hooks/protect-branches.sh
index a5690fa..04eee54 100755
--- a/hooks/protect-branches.sh
+++ b/hooks/protect-branches.sh
@@ -1,14 +1,30 @@
 #!/bin/bash
-# PreToolUse(Bash) — block pushes whose DESTINATION is main/master, and force
-# pushes. Blocks by destination, never by a branch-name substring, so a feature
-# branch whose name merely contains "main"/"master" (e.g. `git push -u origin
-# feat/main-nav`) is allowed. Backslash-newline continuations are joined, then
-# the command is split into segments on &&, ||, ;, |, (, ), and newlines, and
-# each segment is tokenized independently (with one layer of surrounding
-# quotes stripped from each token) so chained/grouped commands like
-# `(cd /tmp && git push origin main)` are still caught. Each segment's tokens
-# are scanned for a `git` invocation, tolerating leading env assignments
-# (FOO=bar) and global options (-C <dir>, -c k=v, ...) before the subcommand.
+# PreToolUse(Bash) — block pushes whose DESTINATION is main/master, force
+# pushes, and pushes of every branch (--all/--mirror). Blocks by destination,
+# never by a branch-name substring, so a feature branch whose name merely
+# contains "main"/"master" (e.g. `git push -u origin feat/main-nav`) is
+# allowed. The command text is normalised once (backslash-newline
+# continuations joined, quote characters and backslashes stripped, tabs
+# flattened) so a nested-shell body such as `sh -c "git push origin main"`
+# is scanned the same as a top-level command, at any nesting depth: quote
+# removal turns it into the flat tokens `sh -c git push origin main`, which
+# the scanner below reads the same way it reads a top-level invocation.
+# `cd`/`pushd` and `git switch`/`git checkout` are tracked across segments,
+# in order, the last change wins, so a refspec-less push after a directory
+# or branch change resolves against the tracked state instead of the hook's
+# own cwd; state the text cannot resolve (an interpolated `$VAR`, `-`,
+# `popd`, a detached checkout) blocks with a hint rather than silently
+# falling through.
+#
+# Scope: a guardrail against the agent's own accidental pushes, not a
+# sandbox. Out of scope: a command held in a variable and `eval`ed
+# indirectly, an xargs-fed refspec, a shell wrapper or alias not named
+# `git`, and `git -c k="v w"` before push (the embedded space defeats the
+# word split). A `cd` or branch change the hook cannot resolve blocks with a
+# hint instead of guessing. Quoted prose that spells a push to main — inside
+# `echo "…"`, a heredoc line, a `--body "…"` — is blocked as if it were the
+# command; a heredoc line was already blocked before this change, and the
+# remedy is the same: keep such text in a file.
 
 if ! command -v jq >/dev/null 2>&1; then
   echo "cw: jq not found, hook skipped" >&2
@@ -16,106 +32,168 @@ if ! command -v jq >/dev/null 2>&1; then
 fi
 
 INPUT=$(cat)
-CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
-CWD=$(echo "$INPUT" | jq -r '.cwd // empty')
+CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null)
 
-TAB="$(printf '\t')"
+[ -z "$CMD" ] && exit 0
 
 block() { echo "Blocked: $1" >&2; exit 2; }
 
-# Splits $1 on whitespace into the global array TOK. A single- or double-
-# quoted span is treated as part of the current word and that one layer of
-# quoting is stripped (e.g. "main" -> main). Not a full shell parser: nested
-# shells (bash -c "..."), escaped quotes, and multi-quote-region words are
-# out of scope.
-tokenize() {
-  s="$1"
-  i=0
-  n=${#s}
-  q=""
-  buf=""
-  started=0
-  TOK=()
-  while [ "$i" -lt "$n" ]; do
-    c="${s:$i:1}"
-    if [ -n "$q" ]; then
-      if [ "$c" = "$q" ]; then
-        q=""
-      else
-        buf="$buf$c"
-      fi
-    elif [ "$c" = '"' ] || [ "$c" = "'" ]; then
-      q="$c"
-      started=1
-    elif [ "$c" = " " ] || [ "$c" = "$TAB" ]; then
-      if [ "$started" = 1 ]; then
-        TOK+=( "$buf" )
-        buf=""
-        started=0
-      fi
-    else
-      buf="$buf$c"
-      started=1
-    fi
-    i=$((i+1))
+TRACK_DIR=""
+TRACK_BRANCH=""
+
+# Refspec-less push resolution, shared by the -C path and the tracked/cwd
+# path: only when push.default is upstream/tracking, and only when no
+# positional token is HEAD and there are at most one, does an upstream
+# ending in main/master block.
+check_upstream() {
+  dir="$1"
+  [ "$npos" -gt 1 ] && return 0
+  headfound=0
+  for p in "${pos[@]}"; do
+    [ "$p" = "HEAD" ] && headfound=1
   done
-  [ "$started" = 1 ] && TOK+=( "$buf" )
+  [ "$headfound" = 1 ] && return 0
+  pd=$(git -C "$dir" config --get push.default 2>/dev/null)
+  case "$pd" in
+    upstream | tracking) : ;;
+    *) return 0 ;;
+  esac
+  up=$(git -C "$dir" rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null)
+  case "$up" in
+    */main | */master)
+      block "current branch tracks $up and push.default is upstream; push to a feature branch explicitly." ;;
+  esac
+  return 0
 }
 
-check_segment() {
-  seg="$1"
-  tokenize "$seg"
-  n=${#TOK[@]}
-
-  is_push=0
-  GITDIR=""
-  i=0
-  while [ "$i" -lt "$n" ]; do
-    t="${TOK[$i]}"
-    case "$t" in
-      *=*) i=$((i+1)); continue ;;            # leading env assignment
+# `git switch`/`git checkout` branch resolution: walk the tokens after the
+# subcommand with positional parameters (shift), never an indexed array.
+# `-b`/`-B`/`-c`/`-C` name the branch in the next token and stop immediately.
+# `--`, `-p`, `--patch`, `HEAD`, `-`, or a token containing `$` make the
+# branch unknown and stop. Any other `-` option is skipped. The walk does
+# NOT stop at the first positional: it is remembered as a tentative branch
+# and scanning continues, so a later `--` or a second positional (a path
+# checkout such as `git checkout feat/x -- README.md`) still makes the
+# branch unknown instead of leaving the first token recorded as a branch
+# change that never happened.
+resolve_switch_branch() {
+  branch=""
+  found_positional=0
+  while [ $# -gt 0 ]; do
+    sa="$1"
+    shift
+    case "$sa" in
+      -b | -B | -c | -C)
+        if [ $# -eq 0 ]; then
+          TRACK_BRANCH=unknown
+        else
+          TRACK_BRANCH="$1"
+        fi
+        return ;;
+      -- | -p | --patch | HEAD | -)
+        TRACK_BRANCH=unknown
+        return ;;
+      *'$'*)
+        TRACK_BRANCH=unknown
+        return ;;
+      -*)
+        continue ;;
+      *)
+        if [ "$found_positional" = 1 ]; then
+          TRACK_BRANCH=unknown
+          return
+        fi
+        branch="$sa"
+        found_positional=1
+        continue ;;
     esac
-    if [ "$t" = "git" ] || [ "${t##*/}" = "git" ]; then
-      j=$((i+1))
-      while [ "$j" -lt "$n" ]; do
-        a="${TOK[$j]}"
-        case "$a" in
-          -C) GITDIR="${TOK[$((j+1))]}"; j=$((j+2)); continue ;;   # capture repo dir
-          -c|--git-dir|--work-tree|--namespace|--exec-path|-o|--push-option|--repo)
-            j=$((j+2)); continue ;;           # option that consumes a separate-word arg
-          --*=*|-*) j=$((j+1)); continue ;;   # single-token option (incl. --opt=val)
-          push) is_push=1; REF=( "${TOK[@]:$((j+1))}" ); break ;;
-          *) break ;;                          # a different subcommand (log/commit/...)
-        esac
-      done
-      break
+  done
+  if [ "$found_positional" = 1 ]; then
+    TRACK_BRANCH="$branch"
+  else
+    TRACK_BRANCH=unknown
+  fi
+}
+
+# cd/pushd/popd tracking over one segment's tokens: a linear scan with
+# positional parameters (shift), never an indexed array, so it stays O(n)
+# under bash 3.2 (indexed-array element access there is O(i), which turns an
+# indexed loop into O(n^2) — the measured cost of the old TOK[$i] walk). A
+# `cd`/`pushd` token (first occurrence, any position) records the following
+# non-option token as the directory, skipping over option tokens longer than
+# one character (`-P`, `-L`, `--`, `-e`, ...); a bare `-`, no argument, or an
+# argument containing `$` records the directory as unknown. A `popd` token
+# anywhere in the segment also records the directory as unknown and clears
+# the branch, regardless of whether `cd`/`pushd` appears too. Either trigger
+# clears the recorded branch, because it belonged to the directory or branch
+# that came before.
+scan_cd_popd() {
+  found_cd=0
+  awaiting_arg=0
+  has_popd=0
+  while [ $# -gt 0 ]; do
+    t="$1"
+    shift
+    [ "$t" = popd ] && has_popd=1
+    if [ "$awaiting_arg" = 1 ]; then
+      case "$t" in
+        -)
+          TRACK_DIR=unknown
+          awaiting_arg=0 ;;
+        -?*)
+          continue ;;                                     # option token (-P, -L, --, -e...): skip, keep waiting
+        *'$'*)
+          TRACK_DIR=unknown
+          awaiting_arg=0 ;;
+        /*)
+          TRACK_DIR="$t"
+          awaiting_arg=0 ;;
+        *)
+          if [ -n "$CWD" ]; then
+            TRACK_DIR="$CWD/$t"
+          else
+            TRACK_DIR="$t"
+          fi
+          awaiting_arg=0 ;;
+      esac
+    elif [ "$found_cd" = 0 ] && { [ "$t" = cd ] || [ "$t" = pushd ]; }; then
+      found_cd=1
+      awaiting_arg=1
     fi
-    i=$((i+1))
   done
-  [ "$is_push" = 1 ] || return 0
+  [ "$awaiting_arg" = 1 ] && TRACK_DIR=unknown
+  { [ "$found_cd" = 1 ] || [ "$has_popd" = 1 ]; } && TRACK_BRANCH=""
+  [ "$has_popd" = 1 ] && TRACK_DIR=unknown
+}
 
-  # Collect positional (non-option) args after `push`; flag force options and
-  # `+`-prefixed (forced) refspecs.
+# Push-arguments processing: `$@` is exactly the tokens after `push`, handed
+# over from locate_git without a copy. `pos` collects the positional
+# (non-option) tokens with a shift loop, then the destination checks walk
+# `pos` with a plain `for`, which bash already iterates in one pass (no
+# computed index).
+handle_push() {
   pos=()
-  k=0; m=${#REF[@]}
-  while [ "$k" -lt "$m" ]; do
-    a="${REF[$k]}"
+  while [ $# -gt 0 ]; do
+    a="$1"
+    shift
     case "$a" in
-      --force|--force-if-includes|--force-with-lease|--force-with-lease=*)
+      --force)
         block "force push is not allowed." ;;
-      -o|--push-option|--repo)
-        k=$((k+2)); continue ;;               # option that consumes a separate-word arg
+      --all | --mirror)
+        block "pushing every branch (--all/--mirror) is not allowed." ;;
+      -o | --push-option | --repo)
+        shift ;;                                          # option that consumes a separate-word arg
       -[A-Za-z]*)
-        case "$a" in *f*) block "force push is not allowed." ;; esac
-        k=$((k+1)); continue ;;               # short-option cluster without -f
+        case "$a" in *f*) block "force push is not allowed." ;; esac ;;
       --*)
-        k=$((k+1)); continue ;;               # other long option (incl. --opt=val)
+        : ;;                                               # other long option (incl. --opt=val)
       -*)
-        k=$((k+1)); continue ;;               # any other dash token
+        : ;;                                               # any other dash token
       +*)
         block "force push (+ refspec) is not allowed." ;;
       *)
-        pos+=( "$a" ); k=$((k+1)) ;;
+        pos+=("$a") ;;
     esac
   done
 
@@ -123,7 +201,7 @@ check_segment() {
   has_explicit_ref=0
   for p in "${pos[@]}"; do
     case "$p" in
-      *:*)                                   # src:dst (or :dst)
+      *:*)                                                 # src:dst (or :dst)
         dst="${p##*:}"; dst="${dst#refs/heads/}"
         has_explicit_ref=1
         { [ "$dst" = main ] || [ "$dst" = master ]; } && block "push destination is main/master. Use a feature branch." ;;
@@ -134,51 +212,151 @@ check_segment() {
         fi
         # A bare branch-name ref (contains a slash) counts as an explicit
         # destination. A bare `HEAD` does not: it still resolves against the
-        # current branch of the repo at cwd, same as a refspec-less push.
+        # current branch, same as a refspec-less push.
         case "$p" in */*) has_explicit_ref=1 ;; esac ;;
     esac
   done
 
   # Refspec-less push (`git push`, `git push origin`, `git push -u origin
-  # HEAD`): resolve the current branch and block if it is main/master. If git
-  # resolution fails (not a repo), do NOT block — /ship is the backstop.
+  # HEAD`): resolve the destination from tracked state, a push segment's own
+  # `-C`, or the hook's cwd, in that order, and block if it lands on
+  # main/master. State the text cannot resolve blocks with a hint instead of
+  # silently falling through. Resolution failure (not a repo) allows, as
+  # today.
   npos=${#pos[@]}
   if [ "$has_explicit_ref" = 0 ] && { [ "$npos" -le 1 ] || [ "${pos[*]: -1}" = "HEAD" ]; }; then
-    BR=$(git -C "${GITDIR:-${CWD:-.}}" rev-parse --abbrev-ref HEAD 2>/dev/null)
-    if [ "$BR" = "main" ] || [ "$BR" = "master" ]; then
-      block "current branch is $BR; push from a feature branch."
+    if [ -n "$GITDIR" ]; then
+      BR=$(git -C "$GITDIR" rev-parse --abbrev-ref HEAD 2>/dev/null)
+      if [ "$BR" = "main" ] || [ "$BR" = "master" ]; then
+        block "current branch is $BR; push from a feature branch."
+      fi
+      check_upstream "$GITDIR"
+    elif [ -n "$TRACK_BRANCH" ] && [ "$TRACK_BRANCH" != "unknown" ]; then
+      if [ "$TRACK_BRANCH" = "main" ] || [ "$TRACK_BRANCH" = "master" ]; then
+        block "current branch is $TRACK_BRANCH; push from a feature branch."
+      fi
+    elif [ "$TRACK_BRANCH" = "unknown" ] || [ "$TRACK_DIR" = "unknown" ]; then
+      block "cannot determine the destination after a cd or branch change; use an explicit refspec such as git push origin <branch>."
+    else
+      rdir="${TRACK_DIR:-${CWD:-.}}"
+      BR=$(git -C "$rdir" rev-parse --abbrev-ref HEAD 2>/dev/null)
+      if [ "$BR" = "main" ] || [ "$BR" = "master" ]; then
+        block "current branch is $BR; push from a feature branch."
+      fi
+      check_upstream "$rdir"
     fi
   fi
-  return 0
 }
 
-# Join backslash-newline continuations into a single space. Done with a plain
-# bash read loop, not `sed N`, because BSD sed's N silently drops the final
-# line when the input has no trailing newline (as $CMD does not).
-CMD_JOINED=""
-while IFS= read -r jline || [ -n "$jline" ]; do
-  if [ -z "$CMD_JOINED" ]; then
-    CMD_JOINED="$jline"
-  else
-    case "$CMD_JOINED" in
-      *\\) CMD_JOINED="${CMD_JOINED%\\} $jline" ;;
-      *) CMD_JOINED="$CMD_JOINED
-$jline" ;;
+# Locate a git invocation: first git-spelled token (case-insensitive,
+# tolerating a leading path), env assignments and other tokens skipped while
+# searching — a linear scan with positional parameters (shift), matching
+# scan_cd_popd's technique, so it stays O(n) under bash 3.2. Once found,
+# walks git's own options (skipping a separate-word argument for
+# -C/-c/--git-dir/etc, recording -C's argument as GITDIR) until it reaches
+# `push`, `switch`, or `checkout`, at which point the remaining tokens
+# (still `$@`, no copy) are handed straight to the matching handler.
+locate_git() {
+  git_found=0
+  expect_val=""
+  GITDIR=""
+  while [ $# -gt 0 ]; do
+    t="$1"
+    shift
+
+    if [ "$git_found" = 0 ]; then
+      case "$t" in
+        *=*) ;;
+        git | [Gg][Ii][Tt] | */git | */[Gg][Ii][Tt]) git_found=1 ;;
+      esac
+      continue
+    fi
+
+    if [ -n "$expect_val" ]; then
+      if [ "$expect_val" = gitdir ]; then
+        case "$t" in
+          /*) GITDIR="$t" ;;
+          *)
+            if [ -n "$CWD" ]; then
+              GITDIR="$CWD/$t"
+            else
+              GITDIR="$t"
+            fi ;;
+        esac
+      fi
+      expect_val=""
+      continue
+    fi
+
+    case "$t" in
+      -C)
+        expect_val=gitdir ;;
+      -c | --git-dir | --work-tree | --namespace | --exec-path | -o | --push-option | --repo)
+        expect_val=skip ;;                                # option that consumes a separate-word arg
+      --*=* | -*)
+        : ;;                                               # single-token option (incl. --opt=val)
+      push)
+        handle_push "$@"
+        return ;;
+      switch | checkout)
+        resolve_switch_branch "$@"
+        return ;;
+      *)
+        return ;;                                          # a different subcommand (log/commit/...)
     esac
-  fi
-done <<EOF
-$CMD
-EOF
+  done
+}
+
+check_segment() {
+  seg="$1"
+  [ -z "$seg" ] && return 0
+  # Skip cheaply unless the segment could possibly hold a git/cd/pushd/popd
+  # invocation, before paying for the word split.
+  case "$seg" in
+    *[Gg][Ii][Tt]* | *cd* | *pushd* | *popd*) : ;;
+    *) return 0 ;;
+  esac
+
+  set -f
+  # shellcheck disable=SC2086 # deliberate word splitting with globbing off, no here-string, no process
+  set -- $seg
+  set +f
+  [ $# -eq 0 ] && return 0
+
+  scan_cd_popd "$@"
+  locate_git "$@"
+  return 0
+}
+
+# Join backslash-newline continuations (one process), strip quote characters
+# and backslashes (one process), flatten tabs to spaces (one process). Linear
+# in C throughout; no per-character loop.
+CMD_JOINED=$(printf '%s\n' "$CMD" | awk '{ if (sub(/\\$/, "")) printf "%s ", $0; else print }')
+CMD_NORM=$(printf '%s' "$CMD_JOINED" | tr -d $'"\'\\' | tr '\t' ' ')
+
+# Fast path: a command whose normalised text contains no "push" substring
+# exits 0 before any further parsing.
+case "$CMD_NORM" in
+  *push*) ;;
+  *) exit 0 ;;
+esac
 
-# Split the command into segments on &&, ||, ;, |, (, ), and newlines,
-# tab-flatten each segment, then check every segment independently.
-CMD_SEGMENTED=$(printf '%s' "$CMD_JOINED" | sed -e 's/&&/\n/g' -e 's/||/\n/g' -e 's/;/\n/g' -e 's/|/\n/g' -e 's/(/\n/g' -e 's/)/\n/g')
+# Split into segments on &&, ||, ;, |, (, ), backticks, and a bare & (added
+# after the && rule, so `2>&1` splits into harmless pieces, not the operator
+# itself), then newlines. One process; no further process per segment.
+CMD_SPLIT=$(printf '%s' "$CMD_NORM" | sed -e 's/&&/\n/g' -e 's/||/\n/g' -e 's/;/\n/g' -e 's/|/\n/g' -e 's/(/\n/g' -e 's/)/\n/g' -e 's/`/\n/g' -e 's/&/\n/g')
 while IFS= read -r line; do
-  seg_flat=$(printf '%s' "$line" | tr '\t' ' ')
-  [ -z "${seg_flat// /}" ] && continue
-  check_segment "$seg_flat"
+  # Blank-or-all-spaces check via a case glob, not "${line// /}": bash 3.2's
+  # global pattern substitution rebuilds the string per match, which is
+  # O(n^2) for a line with many spaces (measured: tens of seconds on a
+  # ~17KB line) — the same class of bug as an indexed-array walk.
+  case "$line" in
+    *[^\ ]*) : ;;
+    *) continue ;;
+  esac
+  check_segment "$line"
 done <<EOF
-$CMD_SEGMENTED
+$CMD_SPLIT
 EOF
 
 exit 0
diff --git a/hooks/protect-secrets.sh b/hooks/protect-secrets.sh
index c2e96dd..23a46bc 100755
--- a/hooks/protect-secrets.sh
+++ b/hooks/protect-secrets.sh
@@ -36,7 +36,9 @@ case "$LC" in
   *.pem|*.key|*.p8|*.pfx|*.jks|*.keystore| \
   *id_rsa*|*id_ed25519*| \
   *.gnupg/*| \
-  *service-account*.json|*gcp*key*.json)
+  *service-account*.json|*gcp*key*.json| \
+  *.p12|*.netrc|*id_dsa*|*id_ecdsa*| \
+  *.tfstate|*.tfstate.backup)
     echo "Blocked: cannot edit sensitive file: $FILE" >&2
     exit 2
     ;;
diff --git a/tests/run.sh b/tests/run.sh
index b4b58ca..5e42301 100755
--- a/tests/run.sh
+++ b/tests/run.sh
@@ -13,6 +13,7 @@
 ROOT=$(cd "$(dirname "$0")/.." && pwd)
 BASELINE_BYTES=73738
 BASH_BIN="${BASH:-bash}"
+HOOKS_DIR="${CW_HOOKS_DIR:-$ROOT/hooks}"
 
 usage() {
   echo "usage: tests/run.sh {hooks|size|dedupe|scan|trailers|all} [options]" >&2
@@ -52,27 +53,113 @@ check_code() {
   fi
 }
 
+push_case() {
+  # $1: expected code, $2: description, $3: cwd, $4: command
+  local expected desc cwd cmd payload code
+  expected="$1"
+  desc="$2"
+  cwd="$3"
+  cmd="$4"
+  payload=$(jq -nc --arg c "$cmd" --arg d "$cwd" '{tool_name:"Bash",tool_input:{command:$c},cwd:$d}')
+  printf '%s' "$payload" | HOME="$SCRATCH/base" "$BASH_BIN" "$HOOKS_DIR/protect-branches.sh" >/dev/null 2>&1
+  code=$?
+  check_code "$code" "$expected" "$desc"
+}
+
+push_case_repo() {
+  # Same as push_case, but skipped (outside the pass/fail count) when the
+  # scratch git repositories could not be created.
+  if [ "$REPOS_OK" -ne 1 ]; then
+    printf 'hooks: skipped (no scratch repo): %s\n' "$2"
+    return
+  fi
+  push_case "$@"
+}
+
+speed_case() {
+  # $1: expected code, $2: description, $3: cwd, $4: command
+  local expected desc cwd cmd payload code secs
+  expected="$1"
+  desc="$2"
+  cwd="$3"
+  cmd="$4"
+  payload=$(jq -nc --arg c "$cmd" --arg d "$cwd" '{tool_name:"Bash",tool_input:{command:$c},cwd:$d}')
+  SECONDS=0
+  printf '%s' "$payload" | HOME="$SCRATCH/base" "$BASH_BIN" "$HOOKS_DIR/protect-branches.sh" >/dev/null 2>&1
+  code=$?
+  secs=$SECONDS
+  if [ "$code" -eq "$expected" ] && [ "$secs" -le 1 ]; then
+    report 1 "$desc"
+  else
+    report 0 "$desc" "exit=$code want=$expected secs=$secs"
+  fi
+}
+
+REPOS_OK=0
+
+setup_scratch_repos() {
+  # Four scratch repositories for the state/resolution cases: rm (main, one
+  # commit), rf (cloned, HEAD feat/x, no upstream), rc (like rf plus an
+  # upstream on main, push.default unset), ru (like rc plus
+  # push.default=upstream). Each git invocation inherits the real HOME's
+  # gitconfig, so identity and signing are pinned with -c. If `git init -b
+  # main` fails, REPOS_OK stays 0 and every case naming a scratch repo is
+  # skipped through push_case_repo.
+  local gc
+  gc="-c user.name=cw-test -c user.email=cw-test@example.com -c commit.gpgsign=false"
+  # shellcheck disable=SC2086 # $gc is a fixed, space-separated list of -c flags, deliberately unquoted
+  if ! git $gc init -q -b main "$SCRATCH/rm" >/dev/null 2>&1; then
+    REPOS_OK=0
+    return
+  fi
+  printf 'x\n' > "$SCRATCH/rm/README.md"
+  # shellcheck disable=SC2086
+  git -C "$SCRATCH/rm" $gc add README.md >/dev/null 2>&1
+  # shellcheck disable=SC2086
+  git -C "$SCRATCH/rm" $gc commit -q -m init >/dev/null 2>&1
+
+  # shellcheck disable=SC2086
+  git $gc clone -q "$SCRATCH/rm" "$SCRATCH/rf" >/dev/null 2>&1
+  # shellcheck disable=SC2086
+  git -C "$SCRATCH/rf" $gc checkout -q -b feat/x >/dev/null 2>&1
+
+  # shellcheck disable=SC2086
+  git $gc clone -q "$SCRATCH/rm" "$SCRATCH/rc" >/dev/null 2>&1
+  # shellcheck disable=SC2086
+  git -C "$SCRATCH/rc" $gc checkout -q -b feat/x >/dev/null 2>&1
+  git -C "$SCRATCH/rc" branch --set-upstream-to=origin/main >/dev/null 2>&1
+
+  # shellcheck disable=SC2086
+  git $gc clone -q "$SCRATCH/rm" "$SCRATCH/ru" >/dev/null 2>&1
+  # shellcheck disable=SC2086
+  git -C "$SCRATCH/ru" $gc checkout -q -b feat/x >/dev/null 2>&1
+  git -C "$SCRATCH/ru" branch --set-upstream-to=origin/main >/dev/null 2>&1
+  git -C "$SCRATCH/ru" config push.default upstream >/dev/null 2>&1
+
+  REPOS_OK=1
+}
+
 hooks_push_cases() {
   local home_dir out code
   home_dir="$SCRATCH/base"
 
   out=$(printf '%s' '{"tool_name":"Bash","tool_input":{"command":"git push origin main"},"cwd":"/tmp"}' \
-    | HOME="$home_dir" "$BASH_BIN" "$ROOT/hooks/protect-branches.sh" 2>/dev/null)
+    | HOME="$home_dir" "$BASH_BIN" "$HOOKS_DIR/protect-branches.sh" 2>/dev/null)
   code=$?
   check_code "$code" 2 "push origin main -> blocked"
 
   out=$(printf '%s' '{"tool_name":"Bash","tool_input":{"command":"git push -u origin feat/x"},"cwd":"/tmp"}' \
-    | HOME="$home_dir" "$BASH_BIN" "$ROOT/hooks/protect-branches.sh" 2>/dev/null)
+    | HOME="$home_dir" "$BASH_BIN" "$HOOKS_DIR/protect-branches.sh" 2>/dev/null)
   code=$?
   check_code "$code" 0 "push -u origin feat/x -> allowed"
 
   out=$(printf '%s' '{"tool_name":"Bash","tool_input":{"command":"git push --force origin feat/x"},"cwd":"/tmp"}' \
-    | HOME="$home_dir" "$BASH_BIN" "$ROOT/hooks/protect-branches.sh" 2>/dev/null)
+    | HOME="$home_dir" "$BASH_BIN" "$HOOKS_DIR/protect-branches.sh" 2>/dev/null)
   code=$?
   check_code "$code" 2 "push --force -> blocked"
 
   out=$(printf '%s' '{"tool_name":"Bash","tool_input":{"command":"cd /tmp && git push origin main"},"cwd":"/tmp"}' \
-    | HOME="$home_dir" "$BASH_BIN" "$ROOT/hooks/protect-branches.sh" 2>/dev/null)
+    | HOME="$home_dir" "$BASH_BIN" "$HOOKS_DIR/protect-branches.sh" 2>/dev/null)
   code=$?
   check_code "$code" 2 "chained cd && push main -> blocked"
 }
@@ -82,22 +169,22 @@ hooks_secrets_cases() {
   home_dir="$SCRATCH/base"
 
   out=$(printf '%s' '{"tool_name":"Write","tool_input":{"file_path":"/tmp/x/.env"}}' \
-    | HOME="$home_dir" "$BASH_BIN" "$ROOT/hooks/protect-secrets.sh" 2>/dev/null)
+    | HOME="$home_dir" "$BASH_BIN" "$HOOKS_DIR/protect-secrets.sh" 2>/dev/null)
   code=$?
   check_code "$code" 2 "write .env -> blocked"
 
   out=$(printf '%s' '{"tool_name":"Write","tool_input":{"file_path":"/tmp/x/.env.example"}}' \
-    | HOME="$home_dir" "$BASH_BIN" "$ROOT/hooks/protect-secrets.sh" 2>/dev/null)
+    | HOME="$home_dir" "$BASH_BIN" "$HOOKS_DIR/protect-secrets.sh" 2>/dev/null)
   code=$?
   check_code "$code" 0 "write .env.example -> allowed"
 
   out=$(printf '%s' '{"tool_name":"Write","tool_input":{"file_path":"/tmp/x/secrets/.env.example"}}' \
-    | HOME="$home_dir" "$BASH_BIN" "$ROOT/hooks/protect-secrets.sh" 2>/dev/null)
+    | HOME="$home_dir" "$BASH_BIN" "$HOOKS_DIR/protect-secrets.sh" 2>/dev/null)
   code=$?
   check_code "$code" 2 "write secrets/.env.example -> blocked"
 
   out=$(printf '%s' '{"tool_name":"NotebookEdit","tool_input":{"notebook_path":"/tmp/x/secrets.ipynb"}}' \
-    | HOME="$home_dir" "$BASH_BIN" "$ROOT/hooks/protect-secrets.sh" 2>/dev/null)
+    | HOME="$home_dir" "$BASH_BIN" "$HOOKS_DIR/protect-secrets.sh" 2>/dev/null)
   code=$?
   check_code "$code" 2 "notebookedit secrets.ipynb -> blocked"
 }
@@ -113,7 +200,7 @@ hooks_jq_absent_case() {
 
   errfile="$SCRATCH/c9.err"
   printf '%s' '{"tool_name":"Bash","tool_input":{"command":"git push origin main"},"cwd":"/tmp"}' \
-    | PATH="$nojq_bin" HOME="$SCRATCH/base" "$BASH_BIN" "$ROOT/hooks/protect-branches.sh" \
+    | PATH="$nojq_bin" HOME="$SCRATCH/base" "$BASH_BIN" "$HOOKS_DIR/protect-branches.sh" \
     >/dev/null 2>"$errfile"
   code=$?
   errtxt=$(cat "$errfile")
@@ -138,7 +225,7 @@ hooks_profile_cases_a() {
   h="$SCRATCH/c10"
   mkdir -p "$h"
   out=$(printf '%s' '{"cwd":"/tmp","hook_event_name":"SessionStart"}' \
-    | HOME="$h" CLAUDE_CONFIG_DIR="$h/.claude" "$BASH_BIN" "$ROOT/hooks/profile-check.sh" 2>/dev/null)
+    | HOME="$h" CLAUDE_CONFIG_DIR="$h/.claude" "$BASH_BIN" "$HOOKS_DIR/profile-check.sh" 2>/dev/null)
   code=$?
   if [ "$code" -eq 0 ] && jqtest "$out" '.hookSpecificOutput.additionalContext | startswith("profile ")'; then
     report 1 "profile right, no .claude-profiles -> additionalContext"
@@ -150,7 +237,7 @@ hooks_profile_cases_a() {
   mkdir -p "$h/other"
   printf '/tmp/proj|%s/other\n' "$h" > "$h/.claude-profiles"
   out=$(printf '%s' '{"cwd":"/tmp/proj/sub","hook_event_name":"SessionStart"}' \
-    | HOME="$h" CLAUDE_CONFIG_DIR="$h" "$BASH_BIN" "$ROOT/hooks/profile-check.sh" 2>/dev/null)
+    | HOME="$h" CLAUDE_CONFIG_DIR="$h" "$BASH_BIN" "$HOOKS_DIR/profile-check.sh" 2>/dev/null)
   code=$?
   if [ "$code" -eq 0 ] && jqtest "$out" '.systemMessage | test("wrong profile")'; then
     report 1 "profile wrong -> systemMessage wrong profile"
@@ -159,7 +246,7 @@ hooks_profile_cases_a() {
   fi
 
   out=$(printf '%s' '{"cwd":"/somewhere/else","hook_event_name":"SessionStart"}' \
-    | HOME="$h" CLAUDE_CONFIG_DIR="$h" "$BASH_BIN" "$ROOT/hooks/profile-check.sh" 2>/dev/null)
+    | HOME="$h" CLAUDE_CONFIG_DIR="$h" "$BASH_BIN" "$HOOKS_DIR/profile-check.sh" 2>/dev/null)
   code=$?
   if [ "$code" -eq 0 ] && jqtest "$out" 'has("systemMessage") | not'; then
     report 1 "unmapped cwd, .claude-profiles present -> no systemMessage"
@@ -175,7 +262,7 @@ hooks_profile_cases_b() {
   mkdir -p "$h"
   printf '@/nonexistent/x.md\n' > "$h/CLAUDE.md"
   out=$(printf '%s' '{"cwd":"/tmp","hook_event_name":"SessionStart"}' \
-    | HOME="$h" CLAUDE_CONFIG_DIR="$h" "$BASH_BIN" "$ROOT/hooks/profile-check.sh" 2>/dev/null)
+    | HOME="$h" CLAUDE_CONFIG_DIR="$h" "$BASH_BIN" "$HOOKS_DIR/profile-check.sh" 2>/dev/null)
   code=$?
   if [ "$code" -eq 0 ] && jqtest "$out" '.systemMessage | test("missing import")' \
     && jqtest "$out" '.hookSpecificOutput.additionalContext | test("missing import")'; then
@@ -189,7 +276,7 @@ hooks_profile_cases_b() {
   printf 'x' > "$h/rules/x.md"
   printf '@rules/x.md\n' > "$h/CLAUDE.md"
   out=$(printf '%s' '{"cwd":"/tmp","hook_event_name":"SessionStart"}' \
-    | HOME="$h" CLAUDE_CONFIG_DIR="$h" "$BASH_BIN" "$ROOT/hooks/profile-check.sh" 2>/dev/null)
+    | HOME="$h" CLAUDE_CONFIG_DIR="$h" "$BASH_BIN" "$HOOKS_DIR/profile-check.sh" 2>/dev/null)
   code=$?
   if [ "$code" -eq 0 ] && jqtest "$out" 'has("systemMessage") | not'; then
     report 1 "relative import exists -> no systemMessage"
@@ -201,7 +288,7 @@ hooks_profile_cases_b() {
   mkdir -p "$h/other"
   printf '# comment\nmalformed line\n/tmp/proj|%s/other\n' "$h" > "$h/.claude-profiles"
   out=$(printf '%s' '{"cwd":"/tmp/proj/sub","hook_event_name":"SessionStart"}' \
-    | HOME="$h" CLAUDE_CONFIG_DIR="$h" "$BASH_BIN" "$ROOT/hooks/profile-check.sh" 2>/dev/null)
+    | HOME="$h" CLAUDE_CONFIG_DIR="$h" "$BASH_BIN" "$HOOKS_DIR/profile-check.sh" 2>/dev/null)
   code=$?
   if [ "$code" -eq 0 ] && jqtest "$out" '.systemMessage | test("wrong profile")'; then
     report 1 "commented/malformed lines ignored -> wrong profile"
@@ -210,19 +297,233 @@ hooks_profile_cases_b() {
   fi
 }
 
+hooks_nested_cases() {
+  push_case 2 "nested sh -c push main -> blocked" "/tmp" 'sh -c "git push origin main"'
+  push_case 2 "nested bash -c cd && push main -> blocked" "/tmp" "bash -c 'cd /tmp && git push origin main'"
+  push_case 2 "eval push main -> blocked" "/tmp" 'eval "git push origin main"'
+  # shellcheck disable=SC2016 # payload literal for the hook, not a shell expansion here
+  push_case 2 "backtick-wrapped push main -> blocked" "/tmp" 'echo `git push origin main`'
+  push_case_repo 2 "nested sh -c cd \$SCRATCH/rm && push -> blocked" "/tmp" "sh -c \"cd $SCRATCH/rm && git push\""
+}
+
+hooks_backslash_cases() {
+  push_case 2 "backslash-escaped \\git push main -> blocked" "/tmp" '\git push origin main'
+  push_case 0 "backslash-escaped \\git push -u origin feat/x -> allowed" "/tmp" '\git push -u origin feat/x'
+}
+
+hooks_options_cases() {
+  push_case 2 "push --all origin -> blocked" "/tmp" 'git push --all origin'
+  push_case 2 "push --mirror origin -> blocked" "/tmp" 'git push --mirror origin'
+  push_case 2 "push origin --all -> blocked" "/tmp" 'git push origin --all'
+  push_case 0 "push --force-with-lease origin feat/x -> allowed" "/tmp" 'git push --force-with-lease origin feat/x'
+  push_case 0 "push --force-with-lease=feat/x origin feat/x -> allowed" "/tmp" 'git push --force-with-lease=feat/x origin feat/x'
+  push_case 0 "push --force-if-includes origin feat/x -> allowed" "/tmp" 'git push --force-if-includes origin feat/x'
+  push_case 2 "push --force-with-lease origin main -> blocked" "/tmp" 'git push --force-with-lease origin main'
+  push_case 2 "push -fu origin feat/x -> blocked" "/tmp" 'git push -fu origin feat/x'
+  push_case 2 "push origin +feat/x -> blocked" "/tmp" 'git push origin +feat/x'
+  push_case 2 "push origin HEAD:main -> blocked" "/tmp" 'git push origin HEAD:main'
+  push_case 2 "push origin --delete main -> blocked" "/tmp" 'git push origin --delete main'
+  push_case 2 "push origin :main -> blocked" "/tmp" 'git push origin :main'
+  push_case 0 "push origin --dry-run feat/x -> allowed" "/tmp" 'git push origin --dry-run feat/x'
+}
+
+hooks_names_cases() {
+  push_case 0 "push -u origin feat/main-nav -> allowed" "/tmp" 'git push -u origin feat/main-nav'
+  push_case 0 "commit message mentioning push to main -> allowed" "/tmp" 'git commit -m "docs: pushing to main is blocked"'
+  push_case 2 "env-assignment FOO=bar git push origin main -> blocked" "/tmp" 'FOO=bar git push origin main'
+  push_case 2 "git -c core.x=1 push origin main -> blocked" "/tmp" 'git -c core.x=1 push origin main'
+  push_case 2 "case-insensitive GIT push origin main -> blocked" "/tmp" 'GIT push origin main'
+}
+
+hooks_state_cases() {
+  push_case 2 "switch main && push -> blocked" "/tmp" 'git switch main && git push'
+  push_case 2 "checkout main && push origin -> blocked" "/tmp" 'git checkout main && git push origin'
+  push_case_repo 2 "cd \$SCRATCH/rm && push -> blocked" "/tmp" "cd $SCRATCH/rm && git push"
+  # shellcheck disable=SC2016 # payload literal for the hook: $DIR must stay unexpanded
+  push_case 2 "cd \"\$DIR\" && push -> blocked (unknown dir)" "/tmp" 'cd "$DIR" && git push'
+  push_case 0 "checkout -b feat/y && push -u origin HEAD -> allowed" "/tmp" 'git checkout -b feat/y && git push -u origin HEAD'
+  push_case 0 "checkout -- README.md && push -u origin feat/x -> allowed" "/tmp" 'git checkout -- README.md && git push -u origin feat/x'
+  push_case_repo 2 "checkout -b feat/y && cd \$SCRATCH/rm && push -> blocked (cd clears branch)" "/tmp" "git checkout -b feat/y && cd $SCRATCH/rm && git push"
+  push_case 2 "status & push origin main (bare & separator) -> blocked" "/tmp" 'git status & git push origin main'
+  push_case 2 "pushd /tmp && popd && push -> blocked (popd anywhere clears state)" "/tmp" 'pushd /tmp && popd && git push'
+  push_case 2 "checkout feat/x -- README.md && push -> blocked (path checkout, not a branch change)" "/tmp" 'git checkout feat/x -- README.md && git push'
+  push_case_repo 2 "cd -P \$SCRATCH/rm && push -> blocked (-P is an option, not the dir)" "/tmp" "cd -P $SCRATCH/rm && git push"
+  push_case_repo 2 "cd -- \$SCRATCH/rm && push -> blocked (-- is an option, not the dir)" "/tmp" "cd -- $SCRATCH/rm && git push"
+}
+
+hooks_resolution_cases() {
+  push_case_repo 2 "cwd rm: push -> blocked (current branch main)" "$SCRATCH/rm" 'git push'
+  push_case_repo 2 "cwd rm: push origin -> blocked (current branch main)" "$SCRATCH/rm" 'git push origin'
+  push_case_repo 2 "cwd rm: push -u origin HEAD -> blocked (current branch main)" "$SCRATCH/rm" 'git push -u origin HEAD'
+  push_case_repo 2 "cwd rm: checkout -- README.md && push -> blocked (unknown branch)" "$SCRATCH/rm" 'git checkout -- README.md && git push'
+  push_case_repo 0 "cwd rf: push -> allowed (feat/x, no upstream)" "$SCRATCH/rf" 'git push'
+  push_case_repo 0 "cwd rf: push -u origin HEAD -> allowed (feat/x, no upstream)" "$SCRATCH/rf" 'git push -u origin HEAD'
+  push_case_repo 2 "cwd rf: git -C \$SCRATCH/rm push -> blocked (-C wins)" "$SCRATCH/rf" "git -C $SCRATCH/rm push"
+  push_case_repo 2 "cwd ru: push -> blocked (upstream main, push.default upstream)" "$SCRATCH/ru" 'git push'
+  push_case_repo 0 "cwd rc: push -> allowed (upstream main, push.default unset)" "$SCRATCH/rc" 'git push'
+  push_case_repo 0 "cwd rm: push feat/x -> allowed (explicit slash destination)" "$SCRATCH/rm" 'git push feat/x'
+  push_case_repo 2 "cwd /tmp: checkout -b feat/y && git -C \$SCRATCH/rm push -> blocked (-C wins over tracked branch)" "/tmp" "git checkout -b feat/y && git -C $SCRATCH/rm push"
+  push_case_repo 0 "cwd /tmp: checkout -b feat/y && git -C \$SCRATCH/rf push -> allowed" "/tmp" "git checkout -b feat/y && git -C $SCRATCH/rf push"
+}
+
+hooks_speed_cases() {
+  local big seg2 i seg3 letters seg4
+  big=$(printf '%*s' 100000 '' | tr ' ' 'a')
+  speed_case 2 "100k-char token + push main -> blocked, under 1s" "/tmp" "$big && git push origin main"
+
+  seg2=""
+  i=1
+  while [ "$i" -le 5000 ]; do
+    if [ -z "$seg2" ]; then
+      seg2="echo abcd-$i"
+    else
+      seg2="$seg2 && echo abcd-$i"
+    fi
+    i=$((i + 1))
+  done
+  speed_case 2 "5000 && segments + push main -> blocked, under 1s" "/tmp" "$seg2 && git push origin main"
+
+  letters="abcdefghijklmnopqrstuvwxyz0123456789ABCD"
+  seg3=""
+  i=1
+  while [ "$i" -le 2000 ]; do
+    if [ -z "$seg3" ]; then
+      seg3="echo line-$i-$letters"
+    else
+      seg3="$seg3
+echo line-$i-$letters"
+    fi
+    i=$((i + 1))
+  done
+  speed_case 0 "2000-line heredoc-shaped input, no push -> allowed, under 1s" "/tmp" "$seg3"
+
+  seg4=""
+  i=1
+  while [ "$i" -le 12000 ]; do
+    if [ -z "$seg4" ]; then
+      seg4="abcd-$i"
+    else
+      seg4="$seg4 abcd-$i"
+    fi
+    i=$((i + 1))
+  done
+  speed_case 2 "one ~100k-char segment (many short cd-containing tokens) + push main -> blocked, under 1s" "/tmp" "$seg4 && git push origin main"
+}
+
+hooks_input_cases() {
+  local errfile out code errtxt
+  errfile="$SCRATCH/input1.err"
+  out=$(printf '%s' 'not json' | HOME="$SCRATCH/base" "$BASH_BIN" "$HOOKS_DIR/protect-branches.sh" 2>"$errfile")
+  code=$?
+  errtxt=$(cat "$errfile" 2>/dev/null)
+  if [ "$code" -eq 0 ] && [ -z "$errtxt" ]; then
+    report 1 "malformed json input -> exit 0, stderr empty"
+  else
+    report 0 "malformed json input -> exit 0, stderr empty" "exit=$code err=$errtxt"
+  fi
+
+  out=$(printf '%s' '{}' | HOME="$SCRATCH/base" "$BASH_BIN" "$HOOKS_DIR/protect-branches.sh" 2>/dev/null)
+  code=$?
+  check_code "$code" 0 "empty json object -> exit 0"
+}
+
+hooks_secrets_new_cases() {
+  local home_dir out code
+  home_dir="$SCRATCH/base"
+
+  out=$(printf '%s' '{"tool_name":"Write","tool_input":{"file_path":"/tmp/x/certs/client.p12"}}' \
+    | HOME="$home_dir" "$BASH_BIN" "$HOOKS_DIR/protect-secrets.sh" 2>/dev/null)
+  code=$?
+  check_code "$code" 2 "write client.p12 -> blocked"
+
+  out=$(printf '%s' '{"tool_name":"Write","tool_input":{"file_path":"/tmp/x/.netrc"}}' \
+    | HOME="$home_dir" "$BASH_BIN" "$HOOKS_DIR/protect-secrets.sh" 2>/dev/null)
+  code=$?
+  check_code "$code" 2 "write .netrc -> blocked"
+
+  out=$(printf '%s' '{"tool_name":"Write","tool_input":{"file_path":"/tmp/x/id_dsa"}}' \
+    | HOME="$home_dir" "$BASH_BIN" "$HOOKS_DIR/protect-secrets.sh" 2>/dev/null)
+  code=$?
+  check_code "$code" 2 "write id_dsa -> blocked"
+
+  out=$(printf '%s' '{"tool_name":"Write","tool_input":{"file_path":"/tmp/x/id_ecdsa"}}' \
+    | HOME="$home_dir" "$BASH_BIN" "$HOOKS_DIR/protect-secrets.sh" 2>/dev/null)
+  code=$?
+  check_code "$code" 2 "write id_ecdsa -> blocked"
+
+  out=$(printf '%s' '{"tool_name":"Write","tool_input":{"file_path":"/tmp/x/terraform.tfstate"}}' \
+    | HOME="$home_dir" "$BASH_BIN" "$HOOKS_DIR/protect-secrets.sh" 2>/dev/null)
+  code=$?
+  check_code "$code" 2 "write terraform.tfstate -> blocked"
+
+  out=$(printf '%s' '{"tool_name":"Write","tool_input":{"file_path":"/tmp/x/terraform.tfstate.backup"}}' \
+    | HOME="$home_dir" "$BASH_BIN" "$HOOKS_DIR/protect-secrets.sh" 2>/dev/null)
+  code=$?
+  check_code "$code" 2 "write terraform.tfstate.backup -> blocked"
+}
+
+hooks_profile_error_case() {
+  local shimbin u p out code
+  shimbin="$SCRATCH/jqshim"
+  mkdir -p "$shimbin"
+  for u in cat sed basename dirname printf head cut tr grep; do
+    p=$(command -v "$u" 2>/dev/null) || continue
+    ln -sf "$p" "$shimbin/$u"
+  done
+  printf '#!/bin/sh\nexit 5\n' > "$shimbin/jq"
+  chmod +x "$shimbin/jq"
+
+  out=$(printf '%s' '{"cwd":"/tmp","hook_event_name":"SessionStart"}' \
+    | PATH="$shimbin" HOME="$SCRATCH/base2" CLAUDE_CONFIG_DIR="$SCRATCH/base2/.claude" "$BASH_BIN" "$HOOKS_DIR/profile-check.sh" 2>/dev/null)
+  code=$?
+  if [ "$code" -eq 0 ] && [ "$out" = "{}" ]; then
+    report 1 "jq present but every call fails -> stdout {}, exit 0"
+  else
+    report 0 "jq present but every call fails -> stdout {}, exit 0" "exit=$code out=$out"
+  fi
+}
+
+hooks_profile_crlf_case() {
+  local h out code
+  h="$SCRATCH/c16"
+  mkdir -p "$h/.claude"
+  printf '/tmp|%s/.claude\r\n' "$h" > "$h/.claude-profiles"
+  out=$(printf '%s' '{"cwd":"/tmp","hook_event_name":"SessionStart"}' \
+    | HOME="$h" CLAUDE_CONFIG_DIR="$h/.claude" "$BASH_BIN" "$HOOKS_DIR/profile-check.sh" 2>/dev/null)
+  code=$?
+  if [ "$code" -eq 0 ] && jqtest "$out" 'has("systemMessage") | not'; then
+    report 1 "CRLF .claude-profiles line, mapping matches active -> no systemMessage"
+  else
+    report 0 "CRLF .claude-profiles line, mapping matches active -> no systemMessage" "exit=$code out=$out"
+  fi
+}
+
 cmd_hooks() {
   [ $# -eq 0 ] || usage
   CASE_NUM=0
   HPASS=0
   HFAIL=0
+  REPOS_OK=0
   SCRATCH=$(mktemp -d)
   mkdir -p "$SCRATCH/base"
+  setup_scratch_repos
 
   hooks_push_cases
+  hooks_nested_cases
+  hooks_backslash_cases
+  hooks_options_cases
+  hooks_names_cases
+  hooks_state_cases
+  hooks_resolution_cases
+  hooks_speed_cases
+  hooks_input_cases
   hooks_secrets_cases
+  hooks_secrets_new_cases
   hooks_jq_absent_case
   hooks_profile_cases_a
   hooks_profile_cases_b
+  hooks_profile_error_case
+  hooks_profile_crlf_case
 
   printf 'hooks: %d passed, %d failed\n' "$HPASS" "$HFAIL"
   rm -rf "$SCRATCH"

From 65cee1a027528e8efdb1d8a38567e2284348c1f0 Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Tue, 22 Sep 2026 13:11:48 +0100
Subject: [PATCH 21/24] docs(cw-plugin): design reflects the hardened guard,
 compact source, harness coverage

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../plans/cw-plugin/cw-plugin-design-draft.md | 39 +++++++++++++------
 1 file changed, 27 insertions(+), 12 deletions(-)

diff --git a/docs/plans/cw-plugin/cw-plugin-design-draft.md b/docs/plans/cw-plugin/cw-plugin-design-draft.md
index 3b6b201..47a9d00 100644
--- a/docs/plans/cw-plugin/cw-plugin-design-draft.md
+++ b/docs/plans/cw-plugin/cw-plugin-design-draft.md
@@ -215,19 +215,31 @@ timeouts 10 s, no `if` field anywhere — `if` fails open on chained or unparsea
 §R3 row 6). Every script starts with the jq check: when `jq` is missing it prints `cw: jq not
 found, hook skipped` to stderr and exits 0 (fail open with a visible warning rather than
 blocking every tool call; jq is a stated requirement in the README).
-- PreToolUse, matcher `Bash` → `protect-branches.sh` (LIVE base, exemption removed): splits
-  `tool_input.command` on `&&`, `||`, `;`, `|` and newlines, tokenises each segment (env
-  assignments and git global options skipped), and blocks with exit 2 any segment that is a
-  `git push` to a main/master destination (explicit refspec, or the current branch when no
-  refspec is given) or that carries `--force`/`-f`; everything else exits 0. No opt-out
-  switch (a shell-wide variable would silently follow the maintainer across profiles): a repo
-  that pushes to main by convention uses the kill switch below or removes the entry from
-  `hooks/hooks.json` in its fork; documented in the README.
+- PreToolUse, matcher `Bash` → `protect-branches.sh` (LIVE base, exemption removed): fast
+  path exits 0 when the normalised `tool_input.command` carries no `push` substring;
+  otherwise splits the command on `&&`, `||`, `;`, `|`, `(`, `)`, backticks and newlines,
+  with quotes and backslashes stripped first so a nested `sh -c`/`bash -c`/`eval` string
+  and an escaped `\git` are scanned the same as a top-level command; `cd`/`pushd` and
+  `git switch`/`checkout` earlier in the command are tracked so a later refspec-less
+  push resolves against that state (state the text cannot resolve blocks with an
+  explicit-refspec hint rather than falling through); blocks a `git push` whose
+  destination is main/master by explicit refspec, by the tracked or resolved current
+  branch, or by an upstream on main; blocks `--force`/`-f`/`+ref` and `--all`/`--mirror`;
+  `--force-with-lease`, `--force-with-lease=<ref>` and `--force-if-includes` pass
+  through to other destinations; everything else exits 0. Scope: a guardrail against
+  the agent's own accidental pushes, not a sandbox; out of scope a command held in a
+  variable and `eval`ed indirectly, an xargs-fed refspec, a shell wrapper or alias not
+  named `git`, and `git -c k="v w"` before push (the embedded space defeats the word
+  split); quoted prose that spells a push to main — inside `echo "…"`, a heredoc line,
+  a `--body "…"` — is blocked as if it were the command. No opt-out switch (a
+  shell-wide variable would silently follow the maintainer across profiles): a repo
+  that pushes to main by convention uses the kill switch below or removes the entry
+  from `hooks/hooks.json` in its fork; documented in the README.
 - PreToolUse, matcher `Write|Edit|MultiEdit|NotebookEdit` → `protect-secrets.sh` (LIVE base
   incl. the template allowlist, which applies only after the directory checks — a
   `.env.example` under `secrets/`, `.ssh/` or `.aws/` stays blocked; reads `file_path //
   filePath // notebook_path`; empty path → allow).
-- SessionStart, matcher `startup|resume|clear|fork` → `profile-check.sh`, which always exits 0
+- SessionStart, matcher `startup|resume|clear|compact|fork` → `profile-check.sh`, which always exits 0
   (exit 2 would block session initialisation, §R2.5) and always prints the JSON context line:
   reads `$HOME/.claude-profiles` (private, `<folder prefix>|<config dir>` per line, `#`
   comments and malformed lines skipped, `~` expanded; an absent file means no profile
@@ -482,9 +494,12 @@ install the CLI for `claude plugin validate`). No runtime dependency on node.
    CLAUDE_CONFIG_DIR="$CFG" claude plugin list | grep -q 'cw@skills-dir'`; `env
    CLAUDE_CONFIG_DIR="$CFG" claude plugin details cw@skills-dir` lists 6 skills, 5 agents and
    the hooks (2 events, 3 commands).
-3. Gates: `bash tests/run.sh all` exits 0 (15 hook cases; the size ratio printed, target
-   ≤60%; per-file caps; dedupe; settings keys); `shellcheck -x hooks/*.sh tests/run.sh` clean
-   at the default severity; `wc -l < WORKFLOW.md` ≤ 200.
+3. Gates: `bash tests/run.sh all` exits 0 (hook cases covering nested interpreters, an
+   escaped git token, chained cd and branch changes, --all/--mirror, lease variants, an
+   upstream on main under push.default=upstream, 100k-character timing, the secrets
+   patterns and profile-check's error paths; 0 failed; the size ratio printed, target
+   ≤60%; per-file caps; dedupe; settings keys); `shellcheck -x hooks/*.sh tests/run.sh`
+   clean at the default severity; `wc -l < WORKFLOW.md` ≤ 200.
 4. Categorical (tracked files): `! git grep -qniE 'opus needs|do not trust|be decisive|read
    all files fresh|claude-design-active|claude-orchestrator-active' -- skills agents rules`;
    `! git grep -qwE 'NEVER|ALWAYS|MUST|CRITICAL' -- skills agents rules`; `! git grep -qniE

From e075e56c49d055306aba4d573f535b1e16731b81 Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Tue, 22 Sep 2026 16:00:18 +0100
Subject: [PATCH 22/24] docs(hardening-1-0-0): drop session residue from the
 plan

The plan named the design session id and a machine-local temp path as the
source of two out-of-repo gate aids. The aids are described without them.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/plans/hardening-1-0-0.md | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/docs/plans/hardening-1-0-0.md b/docs/plans/hardening-1-0-0.md
index 345293e..d27d3ae 100644
--- a/docs/plans/hardening-1-0-0.md
+++ b/docs/plans/hardening-1-0-0.md
@@ -438,10 +438,9 @@ commit, run `N=$(sed -n 's/^Copyright (c) [0-9]* //p' LICENSE | cut -d' ' -f1);
 `rules/workflow.md` and no session line; check it right after committing. Then stage the
 two out-of-repo aids the gates use, into `~/.claude/plans/cw-plugin-gates/` (private,
 already holds the release-gate scripts): `repro-hooks.sh` and `shellcheck-0.9.0`, copied
-from the design session's scratchpad (under `/private/tmp/claude-501/`, this
-project's directory, session `d64245ad-2e4a-4ac3-992e-f237c756a53a`, `scratchpad/`;
-the path is not spelled out here because the project directory name would trip the
-name gate): `repro-hooks.sh` and `sc090/shellcheck-v0.9.0/shellcheck`. If that
+from the design session's scratchpad (the session-specific temp directory of this
+project; the path is not spelled out here because the project directory name would
+trip the name gate): `repro-hooks.sh` and `sc090/shellcheck-v0.9.0/shellcheck`. If that
 directory is gone,
 the binary comes from
 `https://github.com/koalaman/shellcheck/releases/download/v0.9.0/shellcheck-v0.9.0.darwin.x86_64.tar.xz`

From 657f2b2cc8b72c0e40d8e7a1d8d4a787403ea989 Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Tue, 22 Sep 2026 16:47:43 +0100
Subject: [PATCH 23/24] fix(hooks): scope subshell cd and -C checkouts in the
 branch guard

A merge-readiness panel found three fail-open shapes in the branch guard,
regressions against the pre-hardening hook: a cd or plain checkout inside a
(...)/$(...)/backtick subshell leaked into a bare push outside it (rule S),
a cd whose quoted argument contained a space collapsed to a second
positional the hook silently ignored (rule C), and a `git -C <dir>
switch/checkout` targeting a different repository was invisible to a later
push resolving that same directory (rule G). All three now fail closed
(blocked, with the existing cannot-determine hint where the text truly
can't resolve) instead of falling through. Extends README and the design
draft's branch-guard description to match, and adds harness coverage for
each rule plus the $(...)/backtick spellings of the subshell cases.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md                                     |  27 +-
 .../plans/cw-plugin/cw-plugin-design-draft.md |  23 +-
 hooks/protect-branches.sh                     | 335 +++++++++++++++---
 tests/run.sh                                  |  55 ++-
 4 files changed, 363 insertions(+), 77 deletions(-)

diff --git a/README.md b/README.md
index fa6c26e..1256927 100644
--- a/README.md
+++ b/README.md
@@ -191,20 +191,25 @@ escape hatch, not a bypass flag on the hook itself.
 
 `protect-branches.sh` reads the text of each Bash command, splits it on shell
 separators, strips quotes and backslashes so nested `sh -c`/`bash -c`/`eval`
-strings and a backslash-escaped `git` are inspected too, and tracks `cd` and
-`git switch`/`checkout` earlier in the same command. It blocks a `git push`
-whose destination is `main`/`master` (an explicit refspec, the current
-branch, or an upstream on main), plain force pushes (`--force`, `-f`,
-`+ref`), and `--all`/`--mirror`; lease pushes (`--force-with-lease`,
-`--force-if-includes`) to a feature branch pass. When a `cd` or branch change
-earlier in the command can't be resolved from the text (a variable, `cd -`,
-a path checkout), a bare `git push` after it is blocked with a hint to use
-an explicit refspec.
+strings and a backslash-escaped `git` are inspected too, and tracks
+`cd`/`pushd` and `git switch`/`checkout` earlier in the same command. It
+blocks a `git push` whose destination is `main`/`master` (an explicit
+refspec, the current branch, or an upstream on main), plain force pushes
+(`--force`, `-f`, `+ref`), and `--all`/`--mirror`; lease pushes
+(`--force-with-lease`, `--force-if-includes`) to a feature branch pass. When
+a `cd` or branch change earlier in the command can't be resolved from the
+text (a variable, `cd -`, a path checkout), a bare `git push` after it is
+blocked with a hint to use an explicit refspec. A `(...)`, `$(...)`, or
+backtick-quoted subshell is its own scope for that tracking, restored when
+it closes, so a `cd` or checkout inside one can't leak into a push outside
+it; a plain checkout inside the scope leaves the branch unknown on close
+instead of silently reverting.
 
 It is a guardrail against the agent's own accidental pushes, not a sandbox: a
 command held in a variable, `xargs`-fed refspecs, wrappers and aliases not
-named `git`, and `gh api` calls are out of scope, and a line of prose that
-spells out a push to the default branch inside a command is blocked as if it
+named `git`, `git -c k="v w"` before push, and `gh api` calls are out of
+scope, and a line of prose that spells out a push to the default branch
+inside a command is blocked as if it
 were the command itself — keep such text in a file instead.
 
 ## Migration from the old installer
diff --git a/docs/plans/cw-plugin/cw-plugin-design-draft.md b/docs/plans/cw-plugin/cw-plugin-design-draft.md
index 47a9d00..2e91a3d 100644
--- a/docs/plans/cw-plugin/cw-plugin-design-draft.md
+++ b/docs/plans/cw-plugin/cw-plugin-design-draft.md
@@ -222,16 +222,21 @@ blocking every tool call; jq is a stated requirement in the README).
   and an escaped `\git` are scanned the same as a top-level command; `cd`/`pushd` and
   `git switch`/`checkout` earlier in the command are tracked so a later refspec-less
   push resolves against that state (state the text cannot resolve blocks with an
-  explicit-refspec hint rather than falling through); blocks a `git push` whose
-  destination is main/master by explicit refspec, by the tracked or resolved current
-  branch, or by an upstream on main; blocks `--force`/`-f`/`+ref` and `--all`/`--mirror`;
-  `--force-with-lease`, `--force-with-lease=<ref>` and `--force-if-includes` pass
-  through to other destinations; everything else exits 0. Scope: a guardrail against
-  the agent's own accidental pushes, not a sandbox; out of scope a command held in a
+  explicit-refspec hint rather than falling through); a `(...)`, `$(...)`, or
+  backtick-quoted subshell is its own scope for that tracking, restored when it
+  closes, so a `cd` or checkout inside one can't leak into a push outside it, and a
+  plain checkout inside the scope leaves the branch unknown on close instead of
+  silently reverting; blocks a `git push` whose destination is main/master by
+  explicit refspec, by the tracked or resolved current branch, or by an upstream
+  on main; blocks `--force`/`-f`/`+ref` and `--all`/`--mirror`; `--force-with-lease`,
+  `--force-with-lease=<ref>` and `--force-if-includes` pass through to other
+  destinations; everything else exits 0. Scope: a guardrail against the agent's
+  own accidental pushes, not a sandbox; out of scope a command held in a
   variable and `eval`ed indirectly, an xargs-fed refspec, a shell wrapper or alias not
-  named `git`, and `git -c k="v w"` before push (the embedded space defeats the word
-  split); quoted prose that spells a push to main — inside `echo "…"`, a heredoc line,
-  a `--body "…"` — is blocked as if it were the command. No opt-out switch (a
+  named `git`, `git -c k="v w"` before push (the embedded space defeats the word
+  split), and a `gh api` call; quoted prose that spells a push to main — inside
+  `echo "…"`, a heredoc line, a `--body "…"` — is blocked as if it were the
+  command. No opt-out switch (a
   shell-wide variable would silently follow the maintainer across profiles): a repo
   that pushes to main by convention uses the kill switch below or removes the entry
   from `hooks/hooks.json` in its fork; documented in the README.
diff --git a/hooks/protect-branches.sh b/hooks/protect-branches.sh
index 04eee54..4020396 100755
--- a/hooks/protect-branches.sh
+++ b/hooks/protect-branches.sh
@@ -3,12 +3,14 @@
 # pushes, and pushes of every branch (--all/--mirror). Blocks by destination,
 # never by a branch-name substring, so a feature branch whose name merely
 # contains "main"/"master" (e.g. `git push -u origin feat/main-nav`) is
-# allowed. The command text is normalised once (backslash-newline
-# continuations joined, quote characters and backslashes stripped, tabs
-# flattened) so a nested-shell body such as `sh -c "git push origin main"`
-# is scanned the same as a top-level command, at any nesting depth: quote
-# removal turns it into the flat tokens `sh -c git push origin main`, which
-# the scanner below reads the same way it reads a top-level invocation.
+# allowed, and a lease-style force option (--force-with-lease,
+# --force-if-includes) to a destination other than main/master passes. The
+# command text is normalised once (backslash-newline continuations joined,
+# quote characters and backslashes stripped, tabs flattened) so a
+# nested-shell body such as `sh -c "git push origin main"` is scanned the
+# same as a top-level command, at any nesting depth: quote removal turns it
+# into the flat tokens `sh -c git push origin main`, which the scanner below
+# reads the same way it reads a top-level invocation.
 # `cd`/`pushd` and `git switch`/`git checkout` are tracked across segments,
 # in order, the last change wins, so a refspec-less push after a directory
 # or branch change resolves against the tracked state instead of the hook's
@@ -16,15 +18,40 @@
 # `popd`, a detached checkout) blocks with a hint rather than silently
 # falling through.
 #
+# Rule S (subshell scoping): a `(...)`, `$(...)`, or backtick-quoted body is
+# its own scope — a `cd` or checkout inside it is restored when it closes,
+# so it cannot leak into a bare push that follows outside; a plain checkout
+# inside the scope (one the text cannot attribute to a directory of its
+# own) leaves the branch unknown on close instead of silently reverting,
+# since it did change on-disk state the outer command never asked for. Both
+# effects propagate outward through nested scopes, so an outer close also
+# lands on unknown instead of restoring past an inner scope that saw one.
+# When the whole command's parens/backticks don't balance (a stray `)` in
+# prose, e.g. inside a commit message, closes a scope early), a `cd` inside
+# the closing scope leaves the directory unknown too, rather than trusting a
+# restore the text cannot actually attribute to that close.
+# Rule C (cd, second positional): a `cd` followed by a second directory-
+# shaped positional in the same segment (the shell itself would reject two
+# directory arguments; the real-world source is a quoted path with a space
+# whose quotes were already stripped) marks the destination unknown rather
+# than guessing which one wins. A redirection — operand attached
+# (`2>/dev/null`) or a bare operator followed by its operand as a separate
+# token (`> /dev/null`) — is exempt, as is a trailing `#` comment.
+# Rule G (checkout via `-C`): `git -C <dir> switch`/`checkout` changes
+# another repository's on-disk branch without touching the cd/branch state
+# tracked for the command's own directory; a later push whose own `-C` (or
+# tracked directory) names that same repository resolves against that
+# checkout instead of a stale `rev-parse`.
+#
 # Scope: a guardrail against the agent's own accidental pushes, not a
 # sandbox. Out of scope: a command held in a variable and `eval`ed
 # indirectly, an xargs-fed refspec, a shell wrapper or alias not named
-# `git`, and `git -c k="v w"` before push (the embedded space defeats the
-# word split). A `cd` or branch change the hook cannot resolve blocks with a
-# hint instead of guessing. Quoted prose that spells a push to main — inside
-# `echo "…"`, a heredoc line, a `--body "…"` — is blocked as if it were the
-# command; a heredoc line was already blocked before this change, and the
-# remedy is the same: keep such text in a file.
+# `git`, `git -c k="v w"` before push (the embedded space defeats the word
+# split), and a `gh api` call. A `cd` or branch change the hook cannot
+# resolve blocks with a hint instead of guessing. Quoted prose that spells a
+# push to main — inside `echo "…"`, a heredoc line, a `--body "…"` — is
+# blocked as if it were the command; a heredoc line was already blocked
+# before this change, and the remedy is the same: keep such text in a file.
 
 if ! command -v jq >/dev/null 2>&1; then
   echo "cw: jq not found, hook skipped" >&2
@@ -42,6 +69,96 @@ block() { echo "Blocked: $1" >&2; exit 2; }
 TRACK_DIR=""
 TRACK_BRANCH=""
 
+# Rule G state: the directory and branch of the most recent `-C <dir>
+# switch/checkout`, a single slot a later `-C` checkout overwrites. This is
+# on-disk state for another repository, not the command's own tracked
+# directory, so rule S never saves or restores it across a subshell.
+C_DIR=""
+C_BRANCH=""
+
+# Normalise a path used for a same-repository comparison (C_DIR, GITDIR,
+# TRACK_DIR are each passed through this at the point they are set): strip a
+# leading "./" from a relative path, collapse any "/./" segment to "/", and
+# strip trailing slashes (never the root "/"). Otherwise-equivalent spellings
+# of one directory (`rf`, `rf/`, `./rf`) then compare equal by plain string
+# comparison. Sets NORM_PATH; no subshell, no process — path text only,
+# O(length of the path), the same technique as walk_switch_branch's
+# RESOLVED_BRANCH.
+norm_path() {
+  NORM_PATH="$1"
+  case "$NORM_PATH" in
+    ./?*) NORM_PATH="${NORM_PATH#./}" ;;
+  esac
+  while :; do
+    case "$NORM_PATH" in
+      */./*) NORM_PATH="${NORM_PATH%%/./*}/${NORM_PATH#*/./}" ;;
+      *) break ;;
+    esac
+  done
+  while :; do
+    case "$NORM_PATH" in
+      */) NORM_PATH="${NORM_PATH%/}" ;;
+      *) break ;;
+    esac
+  done
+  [ -z "$NORM_PATH" ] && NORM_PATH="/"
+}
+
+# Rule S state: a subshell/command-substitution/backtick nesting depth, with
+# a pair of arrays (indexed by depth, which stays tiny — the O(i) indexed-
+# array cost noted below does not apply here) saving TRACK_DIR/TRACK_BRANCH
+# on open, and a per-depth flag recording whether a plain (no `-C`)
+# switch/checkout ran inside that scope. CD_SEEN is the same shape for a
+# `cd`/`pushd`/`popd` inside that scope, read by close_subshell together
+# with BALANCED (below) to decide whether TRACK_DIR can be restored on an
+# unbalanced close. Both flags propagate to the parent scope's slot on
+# close, so an enclosing close also lands on unknown/unrestorable instead of
+# silently reverting past a nested scope that saw one. BT_OPEN tracks
+# whether the next backtick in reading order opens or closes a scope.
+SUBSHELL_DEPTH=0
+SAVE_DIR=()
+SAVE_BRANCH=()
+CHK_SEEN=()
+CD_SEEN=()
+BT_OPEN=0
+
+open_subshell() {
+  SAVE_DIR[SUBSHELL_DEPTH]="$TRACK_DIR"
+  SAVE_BRANCH[SUBSHELL_DEPTH]="$TRACK_BRANCH"
+  CHK_SEEN[SUBSHELL_DEPTH]=0
+  CD_SEEN[SUBSHELL_DEPTH]=0
+  SUBSHELL_DEPTH=$((SUBSHELL_DEPTH + 1))
+}
+
+close_subshell() {
+  # An unbalanced close (quote-stripping can leave one) at depth zero is a
+  # no-op. TRACK_DIR is restored from the saved value unless the whole
+  # command's parens/backticks are unbalanced (BALANCED=0, set once below)
+  # and a cd/pushd/popd ran inside this scope, in which case the text
+  # cannot say where the shell is after the close and TRACK_DIR becomes
+  # unknown instead. TRACK_BRANCH is restored only when no plain
+  # switch/checkout ran inside this scope, otherwise it becomes unknown —
+  # the scope changed on-disk state the text cannot attribute back to a
+  # directory outside it. Either flag, once set for this depth, propagates
+  # to the parent scope's slot so a further enclosing close inherits it too.
+  [ "$SUBSHELL_DEPTH" -eq 0 ] && return 0
+  SUBSHELL_DEPTH=$((SUBSHELL_DEPTH - 1))
+  if [ "$BALANCED" = 1 ] || [ "${CD_SEEN[$SUBSHELL_DEPTH]}" != 1 ]; then
+    TRACK_DIR="${SAVE_DIR[$SUBSHELL_DEPTH]}"
+  else
+    TRACK_DIR=unknown
+  fi
+  if [ "${CHK_SEEN[$SUBSHELL_DEPTH]}" = 1 ]; then
+    TRACK_BRANCH=unknown
+  else
+    TRACK_BRANCH="${SAVE_BRANCH[$SUBSHELL_DEPTH]}"
+  fi
+  if [ "$SUBSHELL_DEPTH" -gt 0 ]; then
+    [ "${CHK_SEEN[$SUBSHELL_DEPTH]}" = 1 ] && CHK_SEEN[SUBSHELL_DEPTH - 1]=1
+    [ "${CD_SEEN[$SUBSHELL_DEPTH]}" = 1 ] && CD_SEEN[SUBSHELL_DEPTH - 1]=1
+  fi
+}
+
 # Refspec-less push resolution, shared by the -C path and the tracked/cwd
 # path: only when push.default is upstream/tracking, and only when no
 # positional token is HEAD and there are at most one, does an upstream
@@ -76,8 +193,10 @@ check_upstream() {
 # and scanning continues, so a later `--` or a second positional (a path
 # checkout such as `git checkout feat/x -- README.md`) still makes the
 # branch unknown instead of leaving the first token recorded as a branch
-# change that never happened.
-resolve_switch_branch() {
+# change that never happened. Sets RESOLVED_BRANCH; shared by the plain
+# path (resolve_switch_branch, below) and rule G's `-C` path in locate_git,
+# which read RESOLVED_BRANCH into TRACK_BRANCH or C_BRANCH respectively.
+walk_switch_branch() {
   branch=""
   found_positional=0
   while [ $# -gt 0 ]; do
@@ -86,22 +205,22 @@ resolve_switch_branch() {
     case "$sa" in
       -b | -B | -c | -C)
         if [ $# -eq 0 ]; then
-          TRACK_BRANCH=unknown
+          RESOLVED_BRANCH=unknown
         else
-          TRACK_BRANCH="$1"
+          RESOLVED_BRANCH="$1"
         fi
         return ;;
       -- | -p | --patch | HEAD | -)
-        TRACK_BRANCH=unknown
+        RESOLVED_BRANCH=unknown
         return ;;
       *'$'*)
-        TRACK_BRANCH=unknown
+        RESOLVED_BRANCH=unknown
         return ;;
       -*)
         continue ;;
       *)
         if [ "$found_positional" = 1 ]; then
-          TRACK_BRANCH=unknown
+          RESOLVED_BRANCH=unknown
           return
         fi
         branch="$sa"
@@ -110,52 +229,97 @@ resolve_switch_branch() {
     esac
   done
   if [ "$found_positional" = 1 ]; then
-    TRACK_BRANCH="$branch"
+    RESOLVED_BRANCH="$branch"
   else
-    TRACK_BRANCH=unknown
+    RESOLVED_BRANCH=unknown
   fi
 }
 
+resolve_switch_branch() {
+  walk_switch_branch "$@"
+  TRACK_BRANCH="$RESOLVED_BRANCH"
+}
+
 # cd/pushd/popd tracking over one segment's tokens: a linear scan with
 # positional parameters (shift), never an indexed array, so it stays O(n)
 # under bash 3.2 (indexed-array element access there is O(i), which turns an
 # indexed loop into O(n^2) — the measured cost of the old TOK[$i] walk). A
 # `cd`/`pushd` token (first occurrence, any position) records the following
-# non-option token as the directory, skipping over option tokens longer than
-# one character (`-P`, `-L`, `--`, `-e`, ...); a bare `-`, no argument, or an
-# argument containing `$` records the directory as unknown. A `popd` token
-# anywhere in the segment also records the directory as unknown and clears
-# the branch, regardless of whether `cd`/`pushd` appears too. Either trigger
-# clears the recorded branch, because it belonged to the directory or branch
-# that came before.
+# non-option token as the directory (passed through norm_path, rule G/S/C's
+# shared path spelling), skipping over option tokens longer than one
+# character (`-P`, `-L`, `--`, `-e`, ...); a bare `-`, no argument, or an
+# argument containing `$` records the directory as unknown. A token starting
+# with `#` stops the scan outright — a trailing comment's words are not
+# further tokens of the command. Rule C: once the directory argument is
+# recorded, any further token that isn't an option (`-*`) or a redirection
+# also marks the directory unknown — the shell would reject a second
+# directory argument, so text shaped like one is almost always a quoted path
+# with a space whose quotes were already stripped. A redirection is either a
+# token with the operand attached (contains `>`/`<` plus other characters,
+# e.g. `2>/dev/null`) or a bare operator token (optional leading digits then
+# only `>`/`<` characters, e.g. `>`, `2>>`) — a bare operator also consumes
+# the following token as its operand, so a space before the operand (`>
+# /dev/null`) is not mistaken for a second directory argument. A `popd`
+# token anywhere in the segment also records the directory as unknown and
+# clears the branch, regardless of whether `cd`/`pushd` appears too. Either
+# trigger clears the recorded branch, because it belonged to the directory
+# or branch that came before, and, inside a subshell scope, marks that
+# depth's CD_SEEN so rule S's close_subshell can tell an unbalanced close
+# had a directory change inside it.
 scan_cd_popd() {
   found_cd=0
   awaiting_arg=0
   has_popd=0
+  arg_taken=0
+  skip_redir_arg=0
   while [ $# -gt 0 ]; do
     t="$1"
     shift
+    case "$t" in '#'*) break ;; esac
     [ "$t" = popd ] && has_popd=1
     if [ "$awaiting_arg" = 1 ]; then
       case "$t" in
         -)
           TRACK_DIR=unknown
-          awaiting_arg=0 ;;
+          awaiting_arg=0
+          arg_taken=1 ;;
         -?*)
           continue ;;                                     # option token (-P, -L, --, -e...): skip, keep waiting
         *'$'*)
           TRACK_DIR=unknown
-          awaiting_arg=0 ;;
+          awaiting_arg=0
+          arg_taken=1 ;;
         /*)
-          TRACK_DIR="$t"
-          awaiting_arg=0 ;;
+          norm_path "$t"
+          TRACK_DIR="$NORM_PATH"
+          awaiting_arg=0
+          arg_taken=1 ;;
         *)
           if [ -n "$CWD" ]; then
-            TRACK_DIR="$CWD/$t"
+            norm_path "$CWD/$t"
           else
-            TRACK_DIR="$t"
+            norm_path "$t"
           fi
-          awaiting_arg=0 ;;
+          TRACK_DIR="$NORM_PATH"
+          awaiting_arg=0
+          arg_taken=1 ;;
+      esac
+    elif [ "$arg_taken" = 1 ]; then
+      if [ "$skip_redir_arg" = 1 ]; then
+        skip_redir_arg=0                                  # bare operator's operand token: consume, not a 2nd dir arg
+        continue
+      fi
+      case "$t" in
+        -*) : ;;                                          # option token
+        *[!0-9\<\>]*)
+          case "$t" in
+            *'>'* | *'<'*) : ;;                            # redirection with the operand attached
+            *) TRACK_DIR=unknown ;;                        # rule C: second positional
+          esac ;;
+        *[\<\>]*)
+          skip_redir_arg=1 ;;                              # bare redirection operator: its operand is next
+        *)
+          TRACK_DIR=unknown ;;                              # rule C: second positional
       esac
     elif [ "$found_cd" = 0 ] && { [ "$t" = cd ] || [ "$t" = pushd ]; }; then
       found_cd=1
@@ -165,6 +329,31 @@ scan_cd_popd() {
   [ "$awaiting_arg" = 1 ] && TRACK_DIR=unknown
   { [ "$found_cd" = 1 ] || [ "$has_popd" = 1 ]; } && TRACK_BRANCH=""
   [ "$has_popd" = 1 ] && TRACK_DIR=unknown
+  if { [ "$found_cd" = 1 ] || [ "$has_popd" = 1 ]; } && [ "$SUBSHELL_DEPTH" -gt 0 ]; then
+    CD_SEEN[SUBSHELL_DEPTH - 1]=1
+  fi
+}
+
+# Rule G: resolve a refspec-less push's destination for directory $1. When
+# $1 is the target of an earlier `-C <dir> switch/checkout` (C_DIR) with a
+# known result (C_BRANCH), that checkout decides the outcome directly and
+# the upstream check is skipped; otherwise falls back to `rev-parse` plus
+# check_upstream, as before rule G.
+resolve_push_dest() {
+  dir="$1"
+  if [ "$dir" = "$C_DIR" ] && [ -n "$C_BRANCH" ]; then
+    if [ "$C_BRANCH" = "main" ] || [ "$C_BRANCH" = "master" ]; then
+      block "current branch is $C_BRANCH; push from a feature branch."
+    elif [ "$C_BRANCH" = "unknown" ]; then
+      block "cannot determine the destination after a cd or branch change; use an explicit refspec such as git push origin <branch>."
+    fi
+    return 0
+  fi
+  BR=$(git -C "$dir" rev-parse --abbrev-ref HEAD 2>/dev/null)
+  if [ "$BR" = "main" ] || [ "$BR" = "master" ]; then
+    block "current branch is $BR; push from a feature branch."
+  fi
+  check_upstream "$dir"
 }
 
 # Push-arguments processing: `$@` is exactly the tokens after `push`, handed
@@ -226,11 +415,7 @@ handle_push() {
   npos=${#pos[@]}
   if [ "$has_explicit_ref" = 0 ] && { [ "$npos" -le 1 ] || [ "${pos[*]: -1}" = "HEAD" ]; }; then
     if [ -n "$GITDIR" ]; then
-      BR=$(git -C "$GITDIR" rev-parse --abbrev-ref HEAD 2>/dev/null)
-      if [ "$BR" = "main" ] || [ "$BR" = "master" ]; then
-        block "current branch is $BR; push from a feature branch."
-      fi
-      check_upstream "$GITDIR"
+      resolve_push_dest "$GITDIR"
     elif [ -n "$TRACK_BRANCH" ] && [ "$TRACK_BRANCH" != "unknown" ]; then
       if [ "$TRACK_BRANCH" = "main" ] || [ "$TRACK_BRANCH" = "master" ]; then
         block "current branch is $TRACK_BRANCH; push from a feature branch."
@@ -239,11 +424,7 @@ handle_push() {
       block "cannot determine the destination after a cd or branch change; use an explicit refspec such as git push origin <branch>."
     else
       rdir="${TRACK_DIR:-${CWD:-.}}"
-      BR=$(git -C "$rdir" rev-parse --abbrev-ref HEAD 2>/dev/null)
-      if [ "$BR" = "main" ] || [ "$BR" = "master" ]; then
-        block "current branch is $BR; push from a feature branch."
-      fi
-      check_upstream "$rdir"
+      resolve_push_dest "$rdir"
     fi
   fi
 }
@@ -255,7 +436,12 @@ handle_push() {
 # walks git's own options (skipping a separate-word argument for
 # -C/-c/--git-dir/etc, recording -C's argument as GITDIR) until it reaches
 # `push`, `switch`, or `checkout`, at which point the remaining tokens
-# (still `$@`, no copy) are handed straight to the matching handler.
+# (still `$@`, no copy) are handed straight to the matching handler. Rule G:
+# a `switch`/`checkout` reached with a non-empty GITDIR (a `-C` was given)
+# never touches TRACK_BRANCH — it names another repository — and records
+# its result in C_DIR/C_BRANCH instead; a plain switch/checkout (no `-C`)
+# still updates TRACK_BRANCH and, inside a subshell scope, marks that
+# depth's CHK_SEEN so rule S can leave the branch unknown on close.
 locate_git() {
   git_found=0
   expect_val=""
@@ -275,14 +461,15 @@ locate_git() {
     if [ -n "$expect_val" ]; then
       if [ "$expect_val" = gitdir ]; then
         case "$t" in
-          /*) GITDIR="$t" ;;
+          /*) norm_path "$t" ;;
           *)
             if [ -n "$CWD" ]; then
-              GITDIR="$CWD/$t"
+              norm_path "$CWD/$t"
             else
-              GITDIR="$t"
+              norm_path "$t"
             fi ;;
         esac
+        GITDIR="$NORM_PATH"
       fi
       expect_val=""
       continue
@@ -299,7 +486,14 @@ locate_git() {
         handle_push "$@"
         return ;;
       switch | checkout)
-        resolve_switch_branch "$@"
+        if [ -n "$GITDIR" ]; then
+          walk_switch_branch "$@"
+          C_DIR="$GITDIR"
+          C_BRANCH="$RESOLVED_BRANCH"
+        else
+          resolve_switch_branch "$@"
+          [ "$SUBSHELL_DEPTH" -gt 0 ] && CHK_SEEN[SUBSHELL_DEPTH - 1]=1
+        fi
         return ;;
       *)
         return ;;                                          # a different subcommand (log/commit/...)
@@ -341,10 +535,28 @@ case "$CMD_NORM" in
   *) exit 0 ;;
 esac
 
+# Rule S, unbalanced-close guard: whether the whole command's parens and
+# backticks are balanced, counted once over CMD_NORM (three linear passes,
+# no per-character loop, no bash pattern substitution on the whole string —
+# see the O(n^2) note above). A stray ")" in prose (inside an echo/commit
+# message) inside a real subshell closes that scope early and can restore a
+# directory change that never actually left the shell; when the counts don't
+# balance, close_subshell (rule S) treats a scope that saw a cd/pushd/popd as
+# unresolvable instead of trusting the saved value.
+CMD_OPENS=$(printf '%s' "$CMD_NORM" | tr -cd '(' | wc -c | tr -d ' ')
+CMD_CLOSES=$(printf '%s' "$CMD_NORM" | tr -cd ')' | wc -c | tr -d ' ')
+CMD_BT=$(printf '%s' "$CMD_NORM" | tr -cd '`' | wc -c | tr -d ' ')
+BALANCED=0
+[ "$CMD_OPENS" -eq "$CMD_CLOSES" ] && [ $((CMD_BT % 2)) -eq 0 ] && BALANCED=1
+
 # Split into segments on &&, ||, ;, |, (, ), backticks, and a bare & (added
 # after the && rule, so `2>&1` splits into harmless pieces, not the operator
-# itself), then newlines. One process; no further process per segment.
-CMD_SPLIT=$(printf '%s' "$CMD_NORM" | sed -e 's/&&/\n/g' -e 's/||/\n/g' -e 's/;/\n/g' -e 's/|/\n/g' -e 's/(/\n/g' -e 's/)/\n/g' -e 's/`/\n/g' -e 's/&/\n/g')
+# itself), then newlines. `(`, `)` and a backtick become their own one-
+# character lines instead of being deleted, so the read loop below can open
+# and close a rule S subshell scope at each one. One process; no further
+# process per segment.
+# shellcheck disable=SC2016 # the backtick pair in the sed program is a literal marker for sed, not a command substitution
+CMD_SPLIT=$(printf '%s' "$CMD_NORM" | sed -e 's/&&/\n/g' -e 's/||/\n/g' -e 's/;/\n/g' -e 's/|/\n/g' -e 's/(/\n(\n/g' -e 's/)/\n)\n/g' -e 's/`/\n`\n/g' -e 's/&/\n/g')
 while IFS= read -r line; do
   # Blank-or-all-spaces check via a case glob, not "${line// /}": bash 3.2's
   # global pattern substitution rebuilds the string per match, which is
@@ -354,6 +566,25 @@ while IFS= read -r line; do
     *[^\ ]*) : ;;
     *) continue ;;
   esac
+  # Rule S: a marker line opens or closes a subshell scope instead of being
+  # scanned as a segment. A backtick toggles between open and close.
+  case "$line" in
+    '(')
+      open_subshell
+      continue ;;
+    ')')
+      close_subshell
+      continue ;;
+    '`')
+      if [ "$BT_OPEN" = 1 ]; then
+        BT_OPEN=0
+        close_subshell
+      else
+        BT_OPEN=1
+        open_subshell
+      fi
+      continue ;;
+  esac
   check_segment "$line"
 done <<EOF
 $CMD_SPLIT
diff --git a/tests/run.sh b/tests/run.sh
index 5e42301..3002dea 100755
--- a/tests/run.sh
+++ b/tests/run.sh
@@ -98,13 +98,14 @@ speed_case() {
 REPOS_OK=0
 
 setup_scratch_repos() {
-  # Four scratch repositories for the state/resolution cases: rm (main, one
+  # Five scratch repositories for the state/resolution cases: rm (main, one
   # commit), rf (cloned, HEAD feat/x, no upstream), rc (like rf plus an
   # upstream on main, push.default unset), ru (like rc plus
-  # push.default=upstream). Each git invocation inherits the real HOME's
-  # gitconfig, so identity and signing are pinned with -c. If `git init -b
-  # main` fails, REPOS_OK stays 0 and every case naming a scratch repo is
-  # skipped through push_case_repo.
+  # push.default=upstream), and "My Repo" (main, one commit, path contains a
+  # space — rule C). Each git invocation inherits the real HOME's gitconfig,
+  # so identity and signing are pinned with -c. If `git init -b main` fails,
+  # REPOS_OK stays 0 and every case naming a scratch repo is skipped through
+  # push_case_repo.
   local gc
   gc="-c user.name=cw-test -c user.email=cw-test@example.com -c commit.gpgsign=false"
   # shellcheck disable=SC2086 # $gc is a fixed, space-separated list of -c flags, deliberately unquoted
@@ -122,6 +123,7 @@ setup_scratch_repos() {
   git $gc clone -q "$SCRATCH/rm" "$SCRATCH/rf" >/dev/null 2>&1
   # shellcheck disable=SC2086
   git -C "$SCRATCH/rf" $gc checkout -q -b feat/x >/dev/null 2>&1
+  mkdir -p "$SCRATCH/rf/sub"
 
   # shellcheck disable=SC2086
   git $gc clone -q "$SCRATCH/rm" "$SCRATCH/rc" >/dev/null 2>&1
@@ -136,6 +138,15 @@ setup_scratch_repos() {
   git -C "$SCRATCH/ru" branch --set-upstream-to=origin/main >/dev/null 2>&1
   git -C "$SCRATCH/ru" config push.default upstream >/dev/null 2>&1
 
+  # shellcheck disable=SC2086
+  if git $gc init -q -b main "$SCRATCH/My Repo" >/dev/null 2>&1; then
+    printf 'x\n' > "$SCRATCH/My Repo/README.md"
+    # shellcheck disable=SC2086
+    git -C "$SCRATCH/My Repo" $gc add README.md >/dev/null 2>&1
+    # shellcheck disable=SC2086
+    git -C "$SCRATCH/My Repo" $gc commit -q -m init >/dev/null 2>&1
+  fi
+
   REPOS_OK=1
 }
 
@@ -304,6 +315,27 @@ hooks_nested_cases() {
   # shellcheck disable=SC2016 # payload literal for the hook, not a shell expansion here
   push_case 2 "backtick-wrapped push main -> blocked" "/tmp" 'echo `git push origin main`'
   push_case_repo 2 "nested sh -c cd \$SCRATCH/rm && push -> blocked" "/tmp" "sh -c \"cd $SCRATCH/rm && git push\""
+  push_case_repo 2 "rule S: subshell cd into rf, bare push cwd rm -> blocked" "$SCRATCH/rm" "(cd $SCRATCH/rf && git status) && git push"
+  push_case_repo 0 "rule S: subshell cd into rm, bare push cwd rf -> allowed" "$SCRATCH/rf" "(cd $SCRATCH/rm && git status) && git push"
+  push_case_repo 0 "rule S: subshell cd to a non-repo path then harmless command, bare push cwd rf -> allowed" "$SCRATCH/rf" "(cd $SCRATCH && echo hi) && git push"
+  push_case_repo 2 "rule S: plain checkout main inside a subshell, bare push cwd rf -> blocked (cannot determine)" "$SCRATCH/rf" '(git checkout main) && git push'
+  push_case_repo 2 "rule S: cd into rm outside a subshell, bare push inside it -> blocked" "/tmp" "cd $SCRATCH/rm && (git push)"
+  push_case_repo 2 "rule S: \$(...) subshell cd into rf, bare push cwd rm -> blocked" "$SCRATCH/rm" "echo \$(cd $SCRATCH/rf && git status) && git push"
+  push_case_repo 0 "rule S: \$(...) subshell cd into rm, bare push cwd rf -> allowed" "$SCRATCH/rf" "echo \$(cd $SCRATCH/rm && git status) && git push"
+  # shellcheck disable=SC2016 # payload literal for the hook, not a shell expansion here
+  push_case_repo 2 "rule S: \$(...) plain checkout main, bare push cwd rf -> blocked (cannot determine)" "$SCRATCH/rf" 'echo $(git checkout main) && git push'
+  push_case_repo 2 "rule S: backtick subshell cd into rf, bare push cwd rm -> blocked" "$SCRATCH/rm" "echo \`cd $SCRATCH/rf && git status\` && git push"
+  push_case_repo 0 "rule S: backtick subshell cd into rm, bare push cwd rf -> allowed" "$SCRATCH/rf" "echo \`cd $SCRATCH/rm && git status\` && git push"
+  # shellcheck disable=SC2016 # payload literal for the hook, not a shell expansion here
+  push_case_repo 2 "rule S: backtick plain checkout main, bare push cwd rf -> blocked (cannot determine)" "$SCRATCH/rf" 'echo `git checkout main` && git push'
+  push_case 0 "rule S: subshell that only echoes, explicit push to feat/x -> allowed" "/tmp" '(echo hi) && git push origin feat/x'
+  push_case 2 "rule S: unbalanced close paren before explicit push to main -> blocked" "/tmp" 'echo hi) && git push origin main'
+  push_case_repo 2 "rule S: nested ((checkout main)) then push, cwd rf -> blocked (unknown propagates through both closes)" "$SCRATCH/rf" '( ( git checkout main ) ) && git push'
+  push_case_repo 2 "rule S: (cd rf && (checkout main)) then push, cwd rm -> blocked (unknown propagates through both closes)" "$SCRATCH/rm" "( cd $SCRATCH/rf && ( git checkout main ) ) && git push"
+  # shellcheck disable=SC2016 # payload literal for the hook, not a shell expansion here
+  push_case_repo 2 "rule S: backtick inside parens, checkout main, cwd rf -> blocked (unknown propagates)" "$SCRATCH/rf" '( echo `git checkout main` ) && git push'
+  push_case_repo 2 "rule S: prose ) inside a subshell (cd rm, echo \"1) build\", push), cwd rf -> blocked (unbalanced close)" "$SCRATCH/rf" "( cd $SCRATCH/rm && echo \"1) build\" && git push )"
+  push_case_repo 0 "rule S: balanced (cd rf/sub && echo ok) then push -u origin HEAD, cwd rf -> allowed" "$SCRATCH/rf" "(cd $SCRATCH/rf/sub && echo ok) && git push -u origin HEAD"
 }
 
 hooks_backslash_cases() {
@@ -349,6 +381,12 @@ hooks_state_cases() {
   push_case 2 "checkout feat/x -- README.md && push -> blocked (path checkout, not a branch change)" "/tmp" 'git checkout feat/x -- README.md && git push'
   push_case_repo 2 "cd -P \$SCRATCH/rm && push -> blocked (-P is an option, not the dir)" "/tmp" "cd -P $SCRATCH/rm && git push"
   push_case_repo 2 "cd -- \$SCRATCH/rm && push -> blocked (-- is an option, not the dir)" "/tmp" "cd -- $SCRATCH/rm && git push"
+  push_case_repo 2 "rule C: cd into a quoted path with a space -> blocked (cannot determine)" "/tmp" "cd \"$SCRATCH/My Repo\" && git push"
+  push_case_repo 2 "rule C: cd into rm with a redirection token after it -> blocked (current branch main, not a second positional)" "/tmp" "cd $SCRATCH/rm 2>/dev/null && git push"
+  push_case_repo 0 "rule C: pushd rf > /dev/null (spaced redirection) then push -> allowed (not a second positional)" "/tmp" "pushd $SCRATCH/rf > /dev/null && git push"
+  push_case_repo 0 "rule C: cd rf 2> /dev/null (spaced redirection) then push -> allowed (not a second positional)" "/tmp" "cd $SCRATCH/rf 2> /dev/null && git push"
+  push_case_repo 0 "rule C: cd rf then a trailing comment, push on the next line -> allowed (comment stops the scan)" "/tmp" "cd $SCRATCH/rf # into the clone
+git push"
 }
 
 hooks_resolution_cases() {
@@ -364,6 +402,13 @@ hooks_resolution_cases() {
   push_case_repo 0 "cwd rm: push feat/x -> allowed (explicit slash destination)" "$SCRATCH/rm" 'git push feat/x'
   push_case_repo 2 "cwd /tmp: checkout -b feat/y && git -C \$SCRATCH/rm push -> blocked (-C wins over tracked branch)" "/tmp" "git checkout -b feat/y && git -C $SCRATCH/rm push"
   push_case_repo 0 "cwd /tmp: checkout -b feat/y && git -C \$SCRATCH/rf push -> allowed" "/tmp" "git checkout -b feat/y && git -C $SCRATCH/rf push"
+  push_case_repo 2 "rule G: git -C rf checkout feat/x, bare push cwd rm -> blocked (current branch main, cwd untouched)" "$SCRATCH/rm" "git -C $SCRATCH/rf checkout feat/x && git push"
+  push_case_repo 0 "rule G: git -C rm checkout -b feat/z, bare push cwd rf -> allowed" "$SCRATCH/rf" "git -C $SCRATCH/rm checkout -b feat/z && git push"
+  push_case_repo 2 "rule G: git -C rm checkout main then git -C rm push, cwd rf -> blocked" "$SCRATCH/rf" "git -C $SCRATCH/rm checkout main && git -C $SCRATCH/rm push"
+  push_case_repo 0 "rule G: git -C rf checkout -b feat/z then git -C rf push, cwd rf -> allowed" "$SCRATCH/rf" "git -C $SCRATCH/rf checkout -b feat/z && git -C $SCRATCH/rf push"
+  push_case_repo 2 "rule G: git -C rf checkout main then cd rf then bare push, cwd /tmp -> blocked" "/tmp" "git -C $SCRATCH/rf checkout main && cd $SCRATCH/rf && git push"
+  push_case_repo 2 "rule G: git -C rf/ (trailing slash) checkout main, cd rf (no slash), bare push, cwd /tmp -> blocked (normalised match)" "/tmp" "git -C $SCRATCH/rf/ checkout main && cd $SCRATCH/rf && git push"
+  push_case_repo 2 "rule G: git -C ./rf checkout main, cd rf, bare push, cwd scratch root -> blocked (normalised match)" "$SCRATCH" "git -C ./rf checkout main && cd rf && git push"
 }
 
 hooks_speed_cases() {

From d3b0376c1938a5281c9844899524251b6ad4bfde Mon Sep 17 00:00:00 2001
From: Victor Kzam <victor.kzam@gmail.com>
Date: Tue, 22 Sep 2026 16:48:43 +0100
Subject: [PATCH 24/24] docs: three rule files, the browser rule in profile
 setup, model in the settings example

The intro said two rule files when rules/browser.md brought the count to
three; the profile-CLAUDE.md section didn't mention importing it; and the
settings.example.json section didn't note it also sets the top-level model.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 1256927..7aca6ae 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 # cw — a Claude Code workflow plugin
 
 This repo *is* the Claude Code plugin `cw`: six skills, five agents, three
-hooks, two rule files, one test runner, and CI. It implements a
+hooks, three rule files, one test runner, and CI. It implements a
 `/cw:design` -> `/cw:build` -> `/cw:ship` pipeline — research-grounded
 planning, delegated implementation with one atomic commit per task, and a
 verified, gated release — plus `/cw:compound` to feed lessons back into your
@@ -132,6 +132,9 @@ The import path depends on how you installed:
   `@<that path>/rules/workflow.md`; the path changes on every update, so re-check it
   after updating, or keep a separate throwaway clone just for stable import paths.
 
+This plugin also ships `rules/browser.md`; import it the same way (optional)
+when you want Claude in Chrome browser-control conventions in your profile.
+
 Also set `plansDirectory: docs/plans` in your settings so `/cw:design`'s plan
 mode writes the plan file into the project instead of the default location.
 
@@ -161,13 +164,14 @@ for any `@import` line in `CLAUDE.md` whose target doesn't exist.
 ## settings.example.json
 
 Use `settings.example.json` as a starting point, not a drop-in replacement —
-copy it to `settings.json` and adapt it. It sets `defaultMode: "auto"`,
-`effortLevel: "high"`, `plansDirectory: "docs/plans"`, a short generic
-`permissions.deny`/`allow`/`ask` set, `autoMode.allow: ["$defaults"]`, and
-`enabledPlugins` for the official TypeScript, Python, and Swift LSP plugins
-from the `claude-plugins-official` marketplace. It carries no `hooks` key —
-this plugin registers its own hooks, and a plugin hook and a settings hook
-with the same command both fire, so don't add them again in `settings.json`.
+copy it to `settings.json` and adapt it. It sets the top-level `model`,
+`defaultMode: "auto"`, `effortLevel: "high"`, `plansDirectory: "docs/plans"`, a
+short generic `permissions.deny`/`allow`/`ask` set, `autoMode.allow:
+["$defaults"]`, and `enabledPlugins` for the official TypeScript, Python, and
+Swift LSP plugins from the `claude-plugins-official` marketplace. It carries no
+`hooks` key — this plugin registers its own hooks, and a plugin hook and a
+settings hook with the same command both fire, so don't add them again in
+`settings.json`.
 
 **What to adapt**: the `permissions.allow`/`deny` lists for your own
 workflow, the model alias mappings in `rules/orchestration.md` if you have
@@ -207,10 +211,10 @@ instead of silently reverting.
 
 It is a guardrail against the agent's own accidental pushes, not a sandbox: a
 command held in a variable, `xargs`-fed refspecs, wrappers and aliases not
-named `git`, `git -c k="v w"` before push, and `gh api` calls are out of
-scope, and a line of prose that spells out a push to the default branch
-inside a command is blocked as if it
-were the command itself — keep such text in a file instead.
+named `git`, `git -c k="v w"` before push, and `gh api` calls are out of scope,
+and a line of prose that spells out a push to the default branch inside a
+command is blocked as if it were the command itself — keep such text in a file
+instead.
 
 ## Migration from the old installer