diff --git a/docs/superpowers/specs/2026-10-26-claude-md-split-design.md b/docs/superpowers/specs/2026-10-26-claude-md-split-design.md new file mode 100644 index 0000000..39e9fd1 --- /dev/null +++ b/docs/superpowers/specs/2026-10-26-claude-md-split-design.md @@ -0,0 +1,191 @@ +# Phase 0 — split project CLAUDE.md into `.claude/rules/` (design) + +Date: 2026-10-26 · flow: /ship-feature · branch: feature/claude-md-split +Contract: `.claude/tasks/contracts/2026-10-26-claude-md-split-0042.md` +Parent: BDR-125 (context mod queue), TODO.md "Phase 0, no mod". + +## Intent + +The project CLAUDE.md of this repo (5,285 chars) loads in every session of +this repo; four of its five sections only matter when a matching file is +being read. Move those four into project-scope path rules +(`.claude/rules/.md` with `paths:` frontmatter), prove they load, and +give the other projects the same lever through a `/onboard split` mode and +generators that emit path rules from day one. No mod, subtract-only. + +Decided with the user (2026-10-26): this run covers this repo, the mode and +the generators; the per-repo pass over the six other repos runs after the +merge through the shipped `/onboard split`, one `chore/claude-md-split` +branch per repo, user approval per repo, never an automatic merge. The +InstructionsLoaded proof hook is permanent. The transient-artifacts rule +carries a `# static-check: skip` marker. The gitignore socle gains +`!.claude/rules/`. Generator skeleton set: docker, testing, ci. + +## 1. This repo's rules + +| Rule file | `paths:` | Source section (CLAUDE.md, verbatim) | +|---|---|---| +| `.claude/rules/rules-maintenance.md` | `rules/**`, `CLAUDE.global.md` | `## rules/ maintenance` | +| `.claude/rules/graphify-vendored.md` | `skills/graphify/**`, `install-plugins.sh`, `.graphify_version` | `## Machine-owned: the vendored graphify skill` | +| `.claude/rules/mods.md` | `mods/**`, `skills/model-router/**`, `lib/tests/mods.test.sh` | `## mods/ — function-hooks plugins (Claude Code mods)` | +| `.claude/rules/transient-artifacts.md` | `docs/superpowers/**`, `.audit/**` (+ `# static-check: skip`) | `## Transient planning artifacts` | + +Frontmatter shape = `rules/a11y.md`: `paths: ["glob", ...]` on one line. +The skip marker is a YAML comment line inside the frontmatter, invisible to +the engine. Body text moves verbatim; the title line becomes `#
`. CLAUDE.md keeps its header, `## Health Stack`, and a two-line +pointer: path-scoped rules live in `.claude/rules/` and load on Read of a +matching file; the four names listed. + +`.gitignore`: `!.claude/rules/` right after `.claude/*` (line 122). +`templates/gitignore/standard.gitignore`: same line after `.claude/*` +(order matters: a negation must follow the ignore it carves; reconcile +appends missing lines at the end, which is after any existing `.claude/*`). +`lib/gitflow-test.sh`: one `chk "socle: !.claude/rules/"` beside the +`!.claude/deploy/` assertion. + +## 2. Static check and proof hook + +`lib/project-rules.sh` (our code, strict limits, shellcheck): +- `check [dir]` (default `.claude/rules`): for each `*.md`: frontmatter + delimited by `---` present; a `paths:` line whose value is a JSON-style + array of double-quoted globs; each glob matches ≥1 path in the working + tree (`shopt -s globstar dotglob nullglob`, so the symlinked + `skills/model-router/**` and the gitignored `skills/graphify/SKILL.md` + count, and a typo matches nothing). A frontmatter line + `# static-check: skip` exempts that file's globs (printed as SKIP). Exit 0 + and `project-rules: N rule(s) ok` on success; exit 2 and one + `: ` line per failure. An empty or absent dir is exit 0 + with `0 rule(s)` (a project without rules is not an error). +- `sections `: prints `\t\t## ` per + top-level section, for the split-mode classification table. +- `extract "" `: writes + `` with the frontmatter and the section body (title demoted to + `#`), removes the section from CLAUDE.md. Deterministic, idempotent + failure (heading absent → exit 2, nothing written). Used by the onboarder + in MODE: split and by the per-repo pass. + +`lib/tests/project-rules.test.sh` (picked up by `make test` via the +`lib/tests/*.test.sh` glob): fixtures in `mktemp -d`: a good rule passes; +an unmatched glob fails with the culprit; a missing frontmatter fails; the +skip marker passes an unmatched glob; `sections` lists sizes; `extract` +round-trips (rule written, section gone, second call exit 2); then the real +check on this repo's `.claude/rules` (exit 0). PASS/FAIL tally like +`doctrine-citers.test.sh`. + +`hooks/instructions-loaded.sh`: reads the hook JSON on stdin, appends one +`jq -c` line `{ts, cwd, file_path, memory_type, load_reason, +trigger_file_path}` to `~/.claude/logs/instructions-loaded.jsonl` +(`mkdir -p`), always exits 0, never prints to stdout (a stdout line would +reach the model). Registered in `settings.json` under `"InstructionsLoaded"` +beside the other classic hooks. No hooks suite exists: the hook test lives +in `lib/tests/project-rules.test.sh` (fixture JSON on stdin, `HOME` pointed +at a temp dir, the appended line asserted, stdout asserted empty). + +Proof for this repo (recorded in the journal): `claude -p "/context"` on +develop BEFORE any edit (baseline, same measure as 2026-10-23), the same on +the branch after the split, one fresh interactive session that Reads one +matching file per rule, then `grep path_glob_match +~/.claude/logs/instructions-loaded.jsonl | tail -4` pasted. + +## 3. `/onboard split` + +`skills/onboard/SKILL.md`: right after the MODEL GATE, a MODE DISPATCH +paragraph: `$ARGUMENTS` starting with the token `split` → § SPLIT MODE; +anything else → the existing flow unchanged. The description gains the +trigger ("split CLAUDE.md", "découpe le CLAUDE.md"), the argument-hint gains +`split`, RULES line "NO skipping STEP 0, 1, 2" gains "(split mode runs its +own steps, § SPLIT MODE)". Routing rows, test locks (`model-routing`, +`effort-routing`, `loops-heavy`, `plan-challenger`, `security-auditor`) and +`routing.json:67` keep their anchors. + +§ SPLIT MODE (steps): +1. Precondition: `CLAUDE.md` at the project root, else print "nothing to + split, run /onboard" and stop. `git status --porcelain` clean on the + CLAUDE.md path, else stop (an in-flight edit would be lost). +2. Baseline: `claude -p "/context"` at the root; refused → the user runs + `! claude -p "/context"`; the always-on total is noted. +3. `bash ~/.claude/lib/project-rules.sh sections CLAUDE.md`; classify each + `##` section: always-on (overview, stack, build/test/lint commands, + conventions, workflow expectations, exceptions) or path-scoped (one + module, one folder, Docker, migrations, CI, a tool's gotchas); propose a + file name and globs from `git ls-files` for each path-scoped one, and + verify every proposed glob matches ≥1 tracked path before showing it. +4. Gate (prose table, per project): section · chars · keep / move → + `.md` · globs. The user edits or approves; "keep everything" is a + valid answer that ends the mode. +5. `bash ~/.claude/lib/gitflow.sh start chore claude-md-split` (a project + without gitflow: a plain branch, said so). +6. Dispatch `Agent(subagent_type="onboarder")` with `MODE: split`, the + project root, and the approved table verbatim (LRN-126: every field + crosses the prompt). It runs `extract` per row, writes the pointer lines + into CLAUDE.md, adds `!.claude/rules/` after `.claude/*` when that line + is present and the negation absent, runs `check`, commits + `chore(claude-md): split N sections into .claude/rules/`, reports. +7. After: `claude -p "/context"` again, the delta and the rule list go to + that project's `.claude/memory/journal.md`; the InstructionsLoaded proof + is the user's next session there (one Read per rule, grep the log). + Never `finish`: merge on the user's signal. + +Skill edit through /writing-skills: RED first (a sonnet subagent given the +CURRENT skill and a scratch repo holding a copy of this repo's pre-split +CLAUDE.md, asked to "/onboard split": it has no mode and runs or asks for +the full onboard), then the edit, then GREEN on the same scratch (the +subagent produces the classification table and stops at the gate). + +`agents/onboarder.md`: a `MODE:` header: absent → today's PHASES 1-5 +(generate config); `MODE: split` → the split executor above (PHASES +S1-S4: extract rows, pointer lines, gitignore negation, check + commit). +Stays sonnet, effort medium (BDR-077). + +## 4. Generators born split + +`templates/project-rules/` skeletons, each with `paths:` and 3-6 lines of +section stubs (HTML comments like the CLAUDE.md template): +- `docker.md`: `["Dockerfile*", "docker-compose*", "compose*.y*ml", ".dockerignore"]` +- `testing.md`: `["tests/**", "test/**", "**/*.test.*", "**/*.spec.*", "**/conftest.py"]` +- `ci.md`: `[".github/workflows/**", ".gitlab-ci.yml", ".circleci/**"]` + +onboarder (default mode) PHASE 1b and scaffolder PHASE 1b: for each +skeleton, emit `.claude/rules/.md` when ≥1 of its globs matches a +path in the project tree (onboarder: the real tree; scaffolder: the tree it +just scaffolded, so a Docker-relevant project gets `docker.md`), filled from +the BRIEF where known, else the template stubs. Then run `project-rules.sh +check` and report the emitted list. The onboarder's PHASE 4 gitignore check +also appends `!.claude/rules/` after an existing `.claude/*` line +(the socle covers gitflow-init projects; this covers the rest). The +scaffolder's `.gitignore` is reconciled by STEP 5f `gitflow init` before +the root commit, so the socle line lands first (LRN-066, BLK-010). +`templates/project-CLAUDE.md` keeps every section (commands stay always-on); +its header comment gains one line naming `.claude/rules/`. + +## 5. Cleanup and citers + +- `rules/README.md:9` → "see `.claude/rules/rules-maintenance.md` in the + claude-config repo". +- `doctor.sh:76` comment: "the project CLAUDE.md" (drop "29-line"). +- `ARCHITECTURE.md` tree gains `.claude/rules/` (doc pipeline, STEP 8). +- `install-plugins.sh` GUARDED_CONFIGS unchanged: `graphify claude install` + still rewrites CLAUDE.md and the trap still reverts it. +- `.claude/tasks/TODO.md`: phase 0 item updated (done parts, per-repo pass + queued as its own item with the repo order). +- Registries append-only: BDR-065 and LRN-154 keep their old location text. +- Manual step (user): `claude mcp remove -s user higgsfield`; journal line. + +## 6. Testing and proof + +- `make test` green (new suite + gitflow-test socle assertion + hook test). +- `shellcheck *.sh hooks/*.sh lib/*.sh` clean. +- `project-rules.sh check` exit 0 on this repo. +- `/context` before/after at the repo root; the four `path_glob_match` + log lines from one real session. +- RED → GREEN pressure test transcript summary for `/onboard split`. + +## 7. Out of scope, risks kept + +- The per-repo pass (six repos) and whether path rules load inside + sub-agents: measured on faunosteo first, during that pass. +- A `paths:` rule loads on Read, not on Write of a new file: generator + rules load once the scaffolded file is edited (Edit needs a Read). +- The pre-commit `.claude/**` exemption lets a rules-only commit land on + develop; split mode always branches first.