docs(spec): phase 0 claude-md split design

This commit is contained in:
bchanot committed 2026-10-26 01:02:02 +01:00
1 parent aaeaac82f7
commit 2c8e4a20c0
1 file changed
+191
@@ -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/<name>.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 `# <section
title>`. 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
`<file>: <reason>` line per failure. An empty or absent dir is exit 0
with `0 rule(s)` (a project without rules is not an error).
- `sections <CLAUDE.md>`: prints `<chars>\t<line>\t## <heading>` per
top-level section, for the split-mode classification table.
- `extract <CLAUDE.md> "<heading>" <out.md> <globs-json>`: writes
`<out.md>` 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 →
`<name>.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/<name>.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.