docs(spec): phase 0 claude-md split design
This commit is contained in:
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.
|
||||||
Reference in new issue
Block a user