Merge feature/claude-md-split into develop

This commit is contained in:
bchanot committed 2026-10-27 13:24:37 +01:00
commit 925dafa4bc
31 files changed
+1015 -114

No files matched your search

+8
View File
@@ -143,6 +143,7 @@ rules:
| BDR-123 | 2026-10-21 | Routing policy: opus session model, Fable via best-tier rows for orchestrator reflection + merge gates, sonnet writes, doctrine ceiling on Fable main; supersedes parts of BDR-066 / BDR-115 | accepted | | BDR-123 | 2026-10-21 | Routing policy: opus session model, Fable via best-tier rows for orchestrator reflection + merge gates, sonnet writes, doctrine ceiling on Fable main; supersedes parts of BDR-066 / BDR-115 | accepted |
| BDR-124 | 2026-10-23 | Foreign code keeps its own style (lib/code-origin.sh, `git config claude.origin`), limits strict in our code only | accepted | | BDR-124 | 2026-10-23 | Foreign code keeps its own style (lib/code-origin.sh, `git config claude.origin`), limits strict in our code only | accepted |
| BDR-125 | 2026-10-23 | Context mod: subtract-only JIT injection + deterministic guards; supersedes BDR-031 (conditional load proven reliable) | accepted · phases 0-5 planned | | BDR-125 | 2026-10-23 | Context mod: subtract-only JIT injection + deterministic guards; supersedes BDR-031 (conditional load proven reliable) | accepted · phases 0-5 planned |
| BDR-128 | 2026-10-27 | Project path rules: one bash oracle (lib/project-rules.sh), /onboard split subtract-only, generators born split, InstructionsLoaded proof hook | accepted · 0b pending |
--- ---
@@ -1523,3 +1524,10 @@ Branch feature/user-writing-web-rules, UNMERGED (human gate).
- **Alternatives rejected**: `$.ui.ask` inside hook (never renders, spike); bypass inside `upgradeCall`/`downgradeCall` (breaker never checked on target: 2 BLOCKERs r1); handCall `keep(cur)` when unusable (pins down model when hand pick == cur: BLOCKER r2); mod restoring user settings.json after native write (BDR-116); alias pins (user kept full id). - **Alternatives rejected**: `$.ui.ask` inside hook (never renders, spike); bypass inside `upgradeCall`/`downgradeCall` (breaker never checked on target: 2 BLOCKERs r1); handCall `keep(cur)` when unusable (pins down model when hand pick == cur: BLOCKER r2); mod restoring user settings.json after native write (BDR-116); alias pins (user kept full id).
- **Residuals**: `/config` Model row still native (PreModelSwitch source `command`, same as Everywhere's own run); hand pick dropped at `/clear`; no timeout on never-answered dialog (slot held → picks denied, no leak); window guard needs a `windows` entry (none shipped); PostModelSwitch on denied pick unverified live (guarded). - **Residuals**: `/config` Model row still native (PreModelSwitch source `command`, same as Everywhere's own run); hand pick dropped at `/clear`; no timeout on never-answered dialog (slot held → picks denied, no leak); window guard needs a `windows` entry (none shipped); PostModelSwitch on denied pick unverified live (guarded).
- **Refs**: contract `.claude/tasks/contracts/2026-10-25-picker-scope-1952.md`, plan r3 same name in `plans/`, commits 2202964, 5d262d3. [[BDR-126]], [[BDR-116]], [[BLK-036]], [[LRN-231]], [[EVAL-050]]. - **Refs**: contract `.claude/tasks/contracts/2026-10-25-picker-scope-1952.md`, plan r3 same name in `plans/`, commits 2202964, 5d262d3. [[BDR-126]], [[BDR-116]], [[BLK-036]], [[LRN-231]], [[EVAL-050]].
## BDR-128 — Project path rules: one bash oracle, `/onboard split` subtract-only, generators born split [accepted] (2026-10-27)
- **Decision**: `.claude/rules/<name>.md`, frontmatter `paths: ["a", "b"]` one line (block list refused by the oracle, named in the error). One oracle `lib/project-rules.sh [-C dir] check | matches | sections | extract | emit`: globs on the WORKING TREE (`compgen -G` globstar dotglob, dep dirs filtered unless the glob names one: `vendor/**` valid), `# static-check: skip` marker exempts a rule whose files exist mid-run, a section ends at next `#`/`##` outside a fence, `extract` refuses (heading count ≠ 1, target exists, glob no match, failed rewrite rc 2 + rule removed). This repo: 4 rules (rules-maintenance, graphify-vendored, mods, transient-artifacts + skip), CLAUDE.md keeps header + Health Stack + `## Path-scoped rules` pointer. `/onboard split`: main loop classifies (`sections`), verifies every glob (`matches`), row shape `[a-z0-9][a-z0-9-]*` / no `'` `|` `/` `..`, gate, onboarder `MODE: split` executes (S0 preflight incl. `check` + gitignore negation ordered a-f, S1 extract per row, S2 pointer + `cat -s`, S3 check + commit + `cat-file -e HEAD:` per rule, two STOP shapes, rollback `reset -q` + `checkout`). Generators: onboarder PHASE 5b + scaffolder 3b `emit` docker/testing/ci from `templates/project-rules/` when a glob matches. `hooks/instructions-loaded.sh` permanent (`InstructionsLoaded` → `~/.claude/logs/instructions-loaded.jsonl`, field allowlist, exit 0 always, rotate 5 MB). `!.claude/rules/` after `.claude/*` here + socle.
- **Why**: project CLAUDE.md 5,285 → 584 bytes, `/context` Memory files 11.6k → 9.6k, project row 2.1k → 166 tokens; rules load on Read only, proven in main + sub-agent ([[LRN-232]]). Phase 0 of [[BDR-125]]: no mod, subtract-only, deterministic oracle in `make test`.
- **Alternatives rejected**: block-list `paths:` parsing (spec shape inline; pre-flight `check` at S0/S1 moves the failure before any write); mod-based injection (BDR-125 says phase 0 no mod); dep-dir filter unconditional (vetoed `vendor/**`); `git add .claude/rules` dir (a pre-existing rule made visible by the negation would ride along); whole-file Write for the pointer (subtract-only).
- **Residuals**: `###` granularity before faunosteo (12.6 KB path-bound content under always-on `## Project conventions`; `##`-only moves 1.5%), user decides (TODO 0b); `game` heading with `'` refused until renamed or extract by index; `extract -n` dry run deferred; T11b + AC2 hardcode 4 rules; `InstructionsLoaded` key on older CLIs unverified (check `claude --version` on work machine before pull); pre-commit `.claude/**` exemption lets a rules-only commit land on develop → phase 2.
- **Refs**: spec `docs/superpowers/specs/2026-10-26-claude-md-split-design.md`, plan r3 `docs/superpowers/plans/2026-10-26-claude-md-split.md`, contract `.claude/tasks/contracts/2026-10-26-claude-md-split-0042.md`, commits abfa416..0b59687. [[BDR-125]], [[BDR-003]], [[BDR-065]], [[LRN-154]], [[LRN-232]], [[LRN-233]], [[EVAL-051]].
+6
View File
@@ -67,6 +67,7 @@ rules:
| EVAL-044 | 2026-10-11 | model-router W3-B (dialog with context): 3 lenses converged on 2 BLOCKERs of my r1 (inline rows, phase edits) + 1 confirmation; feater DONE + 2 coverage rounds; verifier 3× to CONFORME; security PASS; user's first real decision through the new dialog | the lenses pay most when the plan adds a data shape; coverage criteria still cost rounds; live dialogs during the gates must be announced and their data reconciled before commit | | EVAL-044 | 2026-10-11 | model-router W3-B (dialog with context): 3 lenses converged on 2 BLOCKERs of my r1 (inline rows, phase edits) + 1 confirmation; feater DONE + 2 coverage rounds; verifier 3× to CONFORME; security PASS; user's first real decision through the new dialog | the lenses pay most when the plan adds a data shape; coverage criteria still cost rounds; live dialogs during the gates must be announced and their data reconciled before commit |
| EVAL-045 | 2026-10-11 | model-router W4-B (prompt classifier): 3 lenses (BLOCKER: unbounded classify await) + 1 confirmation; feater DONE + 1 round; verifier ECARTS(2) → CONFORME; security PASS 0 findings; LRN-210 applied (one coverage clause per criterion) | first wave since W2 with no verifier cap: per-clause criteria + abort paths declared unverifiable up front cut the rounds to one | | EVAL-045 | 2026-10-11 | model-router W4-B (prompt classifier): 3 lenses (BLOCKER: unbounded classify await) + 1 confirmation; feater DONE + 1 round; verifier ECARTS(2) → CONFORME; security PASS 0 findings; LRN-210 applied (one coverage clause per criterion) | first wave since W2 with no verifier cap: per-clause criteria + abort paths declared unverifiable up front cut the rounds to one |
| EVAL-048 | 2026-10-23 | model-router feat C keyword cap: 3 lenses FATAL(4)/FATAL(5)/CONCERNS on r1 (3 BLOCKER: run-slot shadow, probe-test hang, reload fail-open), mechanism rewritten, confirmation SOLID; verifier CONFORME 1st pass; 1st verifier died 429 on Fable | | EVAL-048 | 2026-10-23 | model-router feat C keyword cap: 3 lenses FATAL(4)/FATAL(5)/CONCERNS on r1 (3 BLOCKER: run-slot shadow, probe-test hang, reload fail-open), mechanism rewritten, confirmation SOLID; verifier CONFORME 1st pass; 1st verifier died 429 on Fable |
| EVAL-051 | 2026-10-27 | CLAUDE.md split: plan r1→r3 FATAL(5), 12 SDD tasks clean, RED/GREEN + dry run, sonnet final 3 Important, opus 2 Important 8 Minor; extract rc 0 on failed rewrite survived 5 reviews | failure-path test per rewriting function; review a cross-repo tool on real inputs |
--- ---
@@ -447,3 +448,8 @@ Dogfood: 3 blind lenses attacked the v1 plan for the plan-challenge feature itse
- **Method**: dev-mod spike, 2 live runs by user (ask-inside froze; deny + continuation worked) before any plan. Plan r1: correctness FATAL(5), robustness FATAL(2), simplicity SOLID. r2 confirm FATAL(1). r3 inline. feater DONE 29 tests (574 total); GATE 0 MET; verifier CONFORME 14/14 1st pass; auditor PASS 1st pass; doc-sync SIGNIFICANT 12 patches. - **Method**: dev-mod spike, 2 live runs by user (ask-inside froze; deny + continuation worked) before any plan. Plan r1: correctness FATAL(5), robustness FATAL(2), simplicity SOLID. r2 confirm FATAL(1). r3 inline. feater DONE 29 tests (574 total); GATE 0 MET; verifier CONFORME 14/14 1st pass; auditor PASS 1st pass; doc-sync SIGNIFICANT 12 patches.
- **Anomalies**: both FATAL rounds on breaker-vs-target: r1 bypass skipped target-down check across turns; r2 early branch pinned a down model when hand pick == cur (user's exact scenario). Main wrote "leaveDown untouched: down still wins" without tracing which model `decideMain` checks. - **Anomalies**: both FATAL rounds on breaker-vs-target: r1 bypass skipped target-down check across turns; r2 early branch pinned a down model when hand pick == cur (user's exact scenario). Main wrote "leaveDown untouched: down still wins" without tracing which model `decideMain` checks.
- **Action**: a new routing branch gets a trace of every exit against `st.down` for cur AND target, across a turn boundary, before challenge. Spike-first paid: zero rework on the UI mechanism. Links [[BDR-127]], [[LRN-231]]. - **Action**: a new routing branch gets a trace of every exit against `st.down` for cur AND target, across a turn boundary, before challenge. Spike-first paid: zero rework on the UI mechanism. Links [[BDR-127]], [[LRN-231]].
## EVAL-051 — CLAUDE.md split: 5 review layers, the I/O failure path survived 4 of them (2026-10-27)
- **Method**: 0d analyzer; brainstorm 4 user answers; plan r1 → r3 (correctness FATAL(5): SIGPIPE, rc 127, dry run on develop blocked, unchecked commit rc, 80 cols). SDD 12 tasks sonnet/medium, 12 task reviews clean (1 controller resolve avg, mostly attribution lines + oracle facts). RED (current skill stops at plugin-probe) → GREEN (S5 table, nothing written) → dry run on a branched scratch (2 rules in HEAD). Sonnet final review 3 Important → 89334f2. GATE 0 MET 14/20 runnable; verifier ECARTS(3) → ECARTS(1 = user MCP step); security PASS, 1 LOW. Opus/xhigh craft: 0 Critical, 2 Important, 8 Minor, ran the lib on the 6 real 0b targets (56 sections conserved) → 0b59687, re-review 0 open. `make test` all GREEN, suite PASS=93.
- **Anomalies**: `extract` rc 0 on a failed rewrite passed 3 challengers + 12 task reviews + 1 final review: nobody tested an I/O failure (only logic refusals). `##`-only granularity misses faunosteo's payload (12.6 KB under `###`): found only because the reviewer ran the tool on the real targets. Headless proof 0 lines (model skipped Read). T10h-j named a guard the test could not observe. Brief tally arithmetic wrong (96 vs 93). Final review found 3 Important the 12 task reviews missed (dep-dir veto of `vendor/**`, misleading error, gitignore newline glue): per-task scope hides cross-task consequences.
- **Action**: Review Focus lists a failure-path test per function that rewrites a file; a tool meant for other repos gets a reviewer run on their real inputs before merge; a load proof prompt names the tool call ([[LRN-232]]); test names state the observable. Links [[BDR-128]], [[LRN-233]].
+6
View File
@@ -655,3 +655,9 @@ rules:
- BLK-036: bare /model picker wrote haiku into tracked user settings (integration_alphalink intent). Restored opus, haiku pinned in alphalink settings.local.json. /bugfix haiku table 2c39524 (BLK-035, LRN-230): verifier CONFORME 7/7, auditor PASS. Next: haiku effort bugfix, picker scope feat. Merge of feature/model-scope-dialog held. - BLK-036: bare /model picker wrote haiku into tracked user settings (integration_alphalink intent). Restored opus, haiku pinned in alphalink settings.local.json. /bugfix haiku table 2c39524 (BLK-035, LRN-230): verifier CONFORME 7/7, auditor PASS. Next: haiku effort bugfix, picker scope feat. Merge of feature/model-scope-dialog held.
- /feat picker scope (BLK-036): spike (user ran 2 live picker tests: ask inside hook froze, deny + continuation works), plan r1 FATAL x2 / r2 FATAL(1) on breaker-vs-target, r3 inline; verifier CONFORME 14/14, auditor PASS. 2202964 + docs 5d262d3. BDR-127, LRN-231, EVAL-050. Spike mod neutralized. Next: haiku effort bugfix; live check picker in fresh session. - /feat picker scope (BLK-036): spike (user ran 2 live picker tests: ask inside hook froze, deny + continuation works), plan r1 FATAL x2 / r2 FATAL(1) on breaker-vs-target, r3 inline; verifier CONFORME 14/14, auditor PASS. 2202964 + docs 5d262d3. BDR-127, LRN-231, EVAL-050. Spike mod neutralized. Next: haiku effort bugfix; live check picker in fresh session.
- /bugfix haiku effort (bugfix/router-haiku-effort): 3 lenses no BLOCKER (2 caught delete-instead-of-scope), user pick Haiku 5.x like any model; guard = Haiku 4.x; verifier CONFORME 10/10, auditor PASS. 8e93507. BDR-123 + BDR-107 amended, BLK-035 closed, LRN-230 addendum. feature/model-scope-dialog merged a6b94a4. Next: merge bugfix on go, /clear, phase 0. - /bugfix haiku effort (bugfix/router-haiku-effort): 3 lenses no BLOCKER (2 caught delete-instead-of-scope), user pick Haiku 5.x like any model; guard = Haiku 4.x; verifier CONFORME 10/10, auditor PASS. 8e93507. BDR-123 + BDR-107 amended, BLK-035 closed, LRN-230 addendum. feature/model-scope-dialog merged a6b94a4. Next: merge bugfix on go, /clear, phase 0.
## 2026-10-26
- Phase 0 claude-md split (feature/claude-md-split, BDR-125): spec 2c8e4a2, plan r1→r3 (3 lenses FATAL, confirmation FATAL(5): `matches` SIGPIPE rc 141 under pipefail, `PATH=/nonexistent bash` rc 127, dry run on develop blocked by pre-commit), SDD 11 tasks sonnet, every task review clean, final review With fixes → 89334f2. Proof: `/context` 32.2k → 30.5k total, Memory files 11.6k → 9.6k, project CLAUDE.md 2.1k → 166 tokens; headless session 17:00:07Z: 4 Project `path_glob_match` (rules-maintenance ← rules/a11y.md, graphify-vendored ← install-plugins.sh, mods ← mods/model-router/.claude-plugin/plugin.json, transient-artifacts ← docs/superpowers/specs/…); sub-agent 17:00:33Z: rules-maintenance + graphify-vendored loaded with agent_id → path rules DO load in sub-agents. First probe answered without Read (0 lines): proof prompt must force the Read tool. RED (plugin-probe dispatch, no classify) → GREEN (S5 table) → dry run a092b88 on scratch chore branch, 2 rules in HEAD. User step pending: `claude mcp remove -s user higgsfield`. Merge on user go.
## 2026-10-27
- Phase 0 split STEP 6: opus/xhigh review 0 Critical 2 Important 8 Minor (extract rc 0 on failed rewrite; `###` granularity for faunosteo = 0b decision, TODO) → 0b59687, re-review 0 open, make test all GREEN. Capitalized BDR-128, LRN-232/233, EVAL-051. Next: doc-sync, merge on user go; user step still pending: `claude mcp remove -s user higgsfield`.
+10
View File
@@ -247,6 +247,8 @@ rules:
| LRN-225 | 2026-10-22 | Gate on tool's exit-code contract, never its prose; positive control through gate's own helper on clean/dirty fixture pair; mktemp EXIT trap script-level | any test that wraps a CLI verdict | | LRN-225 | 2026-10-22 | Gate on tool's exit-code contract, never its prose; positive control through gate's own helper on clean/dirty fixture pair; mktemp EXIT trap script-level | any test that wraps a CLI verdict |
| LRN-226 | 2026-10-23 | Cap one axis of a layered route at the WRITER (effort-only route), never by filtering at the reader: reader cap shadows lower slots + depends on a baseline that can be unknown | any slot/precedence router, per-axis caps | | LRN-226 | 2026-10-23 | Cap one axis of a layered route at the WRITER (effort-only route), never by filtering at the reader: reader cap shadows lower slots + depends on a baseline that can be unknown | any slot/precedence router, per-axis caps |
| LRN-227 | 2026-10-23 | Root-commit author ≠ name the user remembers: check `git log --max-parents=0`; every root email the user ever used goes in `claude.identity` | code-origin claims, identity lists | | LRN-227 | 2026-10-23 | Root-commit author ≠ name the user remembers: check `git log --max-parents=0`; every root email the user ever used goes in `claude.identity` | code-origin claims, identity lists |
| LRN-232 | 2026-10-27 | Path rules load inside sub-agents (agent_id in hook log); a "does X load" proof prompt must name the Read tool call | per-repo split pass, any load proof |
| LRN-233 | 2026-10-27 | Bash under pipefail: head after producer = rc 141, blanked PATH hides bash (rc 127), unchecked mktemp+rewrite chain = rc 0 with source unchanged; compgen -G no braces, dotglob over-matches, globstar skips symlinks under ** | any bash lib with pipes, temp files, globs |
--- ---
@@ -1907,3 +1909,11 @@ Rule: when editing a doctrine file under structure locks, grep the test's lock s
## LRN-231 — PreModelSwitch hook: no dialog inside; deny at once, ask in a continuation ## LRN-231 — PreModelSwitch hook: no dialog inside; deny at once, ask in a continuation
- **Context**: picker spike 2026-10-25 (dev mod, user-run). `$.ui.ask` awaited inside `classic.PreModelSwitch` never renders: UI frozen on "Running PreModelSwitch hooks… (Esc to cancel)". Returning `{ permissionDecision: 'deny', permissionDecisionReason }` at once blocks switch AND user settings.json write; engine prints "Model switch to X was blocked by a PreModelSwitch hook: <reason>". - **Context**: picker spike 2026-10-25 (dev mod, user-run). `$.ui.ask` awaited inside `classic.PreModelSwitch` never renders: UI frozen on "Running PreModelSwitch hooks… (Esc to cancel)". Returning `{ permissionDecision: 'deny', permissionDecisionReason }` at once blocks switch AND user settings.json write; engine prints "Model switch to X was blocked by a PreModelSwitch hook: <reason>".
- **Apply**: launch `void (async () => { await $.clock.sleep(300); … $.ui.ask … })()` before returning the deny; hold any shared dialog slot synchronously before return, free it in the continuation's `finally`. `$.command.run({ command: 'model', args })` from the continuation re-enters as PreModelSwitch source `command` + command.run origin plugin: gate both. Links [[BDR-127]]. - **Apply**: launch `void (async () => { await $.clock.sleep(300); … $.ui.ask … })()` before returning the deny; hold any shared dialog slot synchronously before return, free it in the continuation's `finally`. `$.command.run({ command: 'model', args })` from the continuation re-enters as PreModelSwitch source `command` + command.run origin plugin: gate both. Links [[BDR-127]].
## LRN-232 — Path rules load inside sub-agents; a load proof prompt must name the Read tool call
- **Context**: phase 0 proof 2026-10-26. `InstructionsLoaded` hook fields: `session_id`, `agent_id` (sub-agents only), `agent_type`, `cwd`, `file_path`, `memory_type`, `load_reason`, `globs`, `trigger_file_path`. General-purpose sub-agent Reading `rules/a11y.md` → `.claude/rules/rules-maintenance.md` logged, `load_reason: path_glob_match`, `agent_id` set. First headless probe `claude -p "read these 4 files"` → 0 log lines: model answered from memory, never called Read. Re-run "Use the Read tool, one call per file" → 4 lines.
- **Apply**: per-repo split pass may move sub-agent-needed sections; verify per repo: `jq -c 'select(.memory_type=="Project" and (.file_path|contains("/.claude/rules/")))' ~/.claude/logs/instructions-loaded.jsonl | tail`. Any "does X load / fire" proof prompt names the tool and the call count; 0 lines first means "did the model act", not "the feature is off". A `paths:` rule loads on Read, not on Write of a new file. Links [[BDR-128]], [[BDR-125]].
## LRN-233 — Bash under pipefail: `head` after a producer, blanked PATH, unchecked temp-file rewrite
- **Context**: `lib/project-rules.sh` 2026-10-26, caught by plan challenger r2 + opus review after 2 sonnet reviews. (1) `compgen -G '**/*' | head -3` → producer SIGPIPE on > pipe buffer of hits, pipeline rc 141 under `pipefail`. (2) `PATH=/nonexistent bash hook.sh` → rc 127: blank PATH applies to the lookup of `bash` itself. (3) `tmp=$(mktemp); f > "$tmp" && cat "$tmp" > src` unchecked → `TMPDIR=/nonexistent` gives rc 0, "moved" printed, src unchanged (I/O failure path untested by 5 reviewers). (4) `compgen -G`: no brace expansion; dotglob matches dotfiles the engine skips; globstar never descends a symlink met under `**` (`top/link/**` finds, `top/**` misses).
- **Apply**: a bounded reader after a producer is awk, reads to the end: `awk 'NR <= 3 { print } END { exit NR == 0 }'`. `"$BASH"` when PATH is blanked in a test. `tmp=$(mktemp) || return 2`; rewrite as `if ! { f > "$tmp" && cat "$tmp" > src; }; then rm -f "$tmp" "$out"; return 2; fi` (SC2015 forbids `a && b || c`). Plan Review Focus: one failure-path test per file-rewriting function (`TMPDIR=/nonexistent`, `chmod a-w`; root ignores chmod). One glob per extension; test names say what they prove (a guard the final `exit 0` swallows is unobservable). Links [[BDR-128]], [[LRN-096]].
+32
View File
@@ -0,0 +1,32 @@
---
paths: ["skills/graphify/**", "install-plugins.sh"]
---
# Machine-owned: the vendored graphify skill
`skills/graphify/SKILL.md`, `skills/graphify/references/` and
`.graphify_version` are written by `graphify claude install`
(`install-plugins.sh` STEP graphify), which lands in the repo because
`~/.claude/skills` is a symlink to `skills/`. They are gitignored: a
`pipx upgrade graphifyy` used to dirty the tree and cost a
`chore(graphify): sync vendored skill X -> Y` commit each time.
Two graphify commands, easy to confuse, and only one restores the skill:
- `graphify install --platform claude` copies SKILL.md + `references/` +
`.graphify_version` into `skills/graphify/`. Touches nothing else.
This is the recovery command.
- `graphify claude install` writes the CLAUDE.md graphify section and the
`.claude/settings.json` PreToolUse hooks. It **rewrites both guarded
configs** (EVAL-020, verified again 2026-09-15), so revert them after. It does NOT copy
the skill.
`make plugin` runs both (`install-plugins.sh` STEP graphify) behind the
guarded-config EXIT trap, so a fresh clone is covered.
Trade-off accepted: an upstream release can now change the skill's prompt
with no diff to review. `skills/graphify/test-prompts.json` is hand-written
for darwin and stays tracked.
Gotcha, learned the hard way: `git rm --cached` keeps the working file,
but if the branch you merge into still tracks it, the merge deletes it
from disk. Untrack and merge, then restore with the command above.
+25
View File
@@ -0,0 +1,25 @@
---
paths: ["mods/**", "skills/model-router/**", "lib/tests/mods.test.sh"]
---
# mods/ — function-hooks plugins (Claude Code mods)
A mod lives in `mods/<name>/` (`.claude-plugin/plugin.json` + hooks). It
loads through the tracked relative symlink `skills/<name>` -> `../mods/<name>`
(`~/.claude/skills` links to `skills/`) as `<name>@skills-dir`, in place,
live at the next session or `/reload-plugins`. New mod: `ln -s ../mods/<name>
skills/<name>` from the repo root (guard with `[ -L ]`, a re-run nests a link).
Not `CLAUDE_CODE_PLUGIN_DIRS` (absolute path, settings `env` has no `$HOME`
expansion, settings.json is tracked), nor a local marketplace (`add` writes
an absolute path into settings.json).
- The engine lays `mods/<name>/tsconfig.json` and `.claude-plugin/types/`;
both are gitignored.
- Optional user config: `~/.claude/<name>.json`. Its `"enabled": false` is the
per-machine off switch (untracked). `"<name>@skills-dir": false` in
`enabledPlugins` also works but lands in the TRACKED settings.json and
dirties every machine's tree.
- A dev copy of the same name (`--plugin-dir`, hot-reload link in
`~/.claude/dev-mods/<session>/`) shadows the skills-dir copy for that
session: remove it before reading `/reload-plugins` as a test of the link.
- Tests: `make test suite=lib/tests/mods.test.sh` (manifest, link,
`claude plugin validate`, `claude plugin test`). `doctor.sh` has a Mods section.
+27
View File
@@ -0,0 +1,27 @@
---
paths: ["rules/**", "CLAUDE.global.md"]
---
# rules/ maintenance
Modular instruction files loaded by Claude Code alongside the global memory.
`rules/` is symlinked to `~/.claude/rules` by `link.sh` (user scope, ALL
projects). One rule = one file = one concern.
A rule WITH `paths:` YAML frontmatter (glob list) loads lazily — only when
Claude reads a file matching a glob; a rule WITHOUT it loads at session
start, same cost as the global memory. Extract from CLAUDE.global.md only
what can be path-scoped (the token win) or what is generated; always-on
doctrine stays in CLAUDE.global.md. Exception: a standalone user-authored
rule set that would bust the 320-line density budget may live here WITHOUT
`paths:` (always-on load) — writing-style.md (BDR-085), default-language.md
(BDR-118), secure-by-default.md (BDR-120). `paths:` globs match against the
CURRENT project's tree — a broad glob (e.g. `rules/**`) can fire in foreign
projects; keep rule bodies tiny.
Docs: https://code.claude.com/docs/en/memory.md#path-specific-rules
Machine-owned: `rules/context7.md` is DELETED BY DESIGN (BDR-053,
2026-07-06) — `ctx7 setup --claude --cli` still writes it, but
install-plugins.sh STEP ctx7 purges it right after; the find-docs skill is
the single ctx7 surface. If it reappears (manual `ctx7 setup`), delete it
or re-run `make plugin`.
+19
View File
@@ -0,0 +1,19 @@
---
paths: ["docs/superpowers/**", ".audit/**"]
# static-check: skip
---
# Transient planning artifacts
`docs/superpowers/specs/**` and `docs/superpowers/plans/**` are run-time
artifacts of a feature pipeline (subagent briefs, reviewer references).
They are committed DURING the run (the SDD worktree + reviewers read them
from disk — NOT gitignored), then AUTO-PURGED by `gitflow finish` on a
`feature`/`bugfix` branch, before the merge, so develop's tip stays clean
(BDR-065, `lib/gitflow.sh` `_gitflow_purge_transient`). The feature commits
stay reachable from develop, so `git show <sha>:docs/…` is still the archive.
Opt out with `GITFLOW_PURGE_TRANSIENT=0`. NOT in scope: `.claude/tasks/{contracts,plans}`
(durable, versioned, referenced by decisions.md). Durable knowledge goes to
`.claude/memory/` registries, never to these files. Derived scan/audit
outputs (`.audit/**`) are gitignored and never committed, even redacted
(LRN-124).
+6 -11
View File
@@ -17,17 +17,12 @@ Shared rules for every phase:
- [x] **/bugfix model-router haiku effort strip** (done 2026-10-25, 8e93507; merge on user signal) (BLK-035 residual, user pick 2026-10-25): Haiku 5.5 takes effort; drop 4.5-era "haiku takes no effort" (effortWord, step plan omission, isHaiku sites, census `lib/tests/effort-routing.test.sh:170`), so `mechanical` runs low. - [x] **/bugfix model-router haiku effort strip** (done 2026-10-25, 8e93507; merge on user signal) (BLK-035 residual, user pick 2026-10-25): Haiku 5.5 takes effort; drop 4.5-era "haiku takes no effort" (effortWord, step plan omission, isHaiku sites, census `lib/tests/effort-routing.test.sh:170`), so `mechanical` runs low.
- [x] **/feat picker scope** (done 2026-10-25, 2202964 + docs 5d262d3, BDR-127; live check pending: picker in a fresh session, PostModelSwitch on a denied pick) (BLK-036, user ask 2026-10-25): bare `/model` → pick in native picker → ask project scope (`.claude/settings.local.json`) or user scope. First: engine types for a settings-write intercept; none → mod restores user settings.json = BDR-116 amendment, user decides before code. - [x] **/feat picker scope** (done 2026-10-25, 2202964 + docs 5d262d3, BDR-127; live check pending: picker in a fresh session, PostModelSwitch on a denied pick) (BLK-036, user ask 2026-10-25): bare `/model` → pick in native picker → ask project scope (`.claude/settings.local.json`) or user scope. First: engine types for a settings-write intercept; none → mod restores user settings.json = BDR-116 amendment, user decides before code.
- [ ] **Phase 0, no mod: split project CLAUDE.md** - [x] **Phase 0, no mod: split project CLAUDE.md** (this repo + the lever, feature/claude-md-split, 2026-10-26; merge on user signal). Four rules under `.claude/rules/` (rules-maintenance, graphify-vendored, mods, transient-artifacts `# static-check: skip`), `lib/project-rules.sh` check/matches/sections/extract/emit (`-C <dir>`) + suite, `hooks/instructions-loaded.sh` (log `~/.claude/logs/instructions-loaded.jsonl`, session + agent ids), `!.claude/rules/` here + socle, `/onboard split` + onboarder `MODE: split`, generators emit docker/testing/ci from `templates/project-rules/`. Baseline 2026-10-26 `/context`: 32.2k total, Memory files 11.6k, project CLAUDE.md 2.1k.
- Move the 4 project CLAUDE.md sections (graphify vendored skill 1.4k chars, mods/ 1.3k, rules/ maintenance 1.3k, transient planning artifacts 0.9k) to `.claude/rules/<name>.md` with `paths:` (`skills/graphify/**`; `mods/**`, `skills/model-router`; `rules/**`; `docs/superpowers/**`). Project scope only: no ~/.claude link points at `.claude/` (checked 2026-10-24); never into `rules/` (= ~/.claude/rules, every project). - [ ] Proof, this repo: `/context` after the merge; one fresh session Reading one file per rule → 4 Project `path_glob_match` lines; one sub-agent Read → does a path rule load inside a sub-agent (decides what the per-repo pass may move). Results in the journal.
- `.gitignore:122` ignores `.claude/*`: add `!.claude/rules/` (a directory-form ignore would untrack the rules). - [ ] User step: `claude mcp remove -s user higgsfield` (user-scope MCP, no toggle ownership, no doctor check; phase 5 `.mcp.json` owns it).
- Higgsfield MCP: user-scope in ~/.claude.json while `toggle-external.sh` says disabled. The user runs `claude mcp remove -s user higgsfield` once; no toggle ownership, no doctor check: the phase 5 pack `.mcp.json` owns it (guide 2026-10-25: `disabledMcpjsonServers` never reaches a user-scope server, the `/mcp` toggle writes `~/.claude.json`). - [ ] Phase 2 folds: narrow the pre-commit `.claude/**` exemption so a rules-only commit cannot land on develop/main (deferred 2026-10-26).
- Proof: static check per moved rule + one InstructionsLoaded-logged session; `/context` delta (~1.9k memory files + higgsfield MCP share). - [ ] **Phase 0b, per-repo pass** (after phase 0 merges; via `/onboard split`, one `chore/claude-md-split` per repo off develop, approval per repo, never an automatic merge; `/context` before/after in that repo's journal). Order by size: faunosteo 52,322 chars (on feature/v1-1-clients-animals with 5 dirty files: finish or stash first, S1 refuses otherwise), zenquality 23,378, game 14,918 (on feature/replay-hint), robin_petier 12,895, config 4,990, integration_alphalink 4,249. None has `.claude/rules/` yet; all use the `.claude/*` file form (BDR-003). Sections a sub-agent needs stay always-on unless the phase 0 sub-agent proof says path rules load there (proof 2026-10-26: they do; verify per repo).
- Cleanup: CLAUDE.md keeps a 2-line pointer ("rules under .claude/rules load on path"); fix citers of the moved headings. - [ ] Before faunosteo: decide `###` granularity (STEP 6 review 2026-10-26). Its path-bound content (i18n, Schemas, Stores, PDF, Supabase, Storage, 12.6 KB) sits in `###` subsections of the always-on `## Project conventions`; `##`-only extract moves ~1.5% of the file. Option: `extract` accepts a `###` heading (section ends at the next heading of the same or higher level), `sections --depth 3`. User decides; `game` also has a `'` in `## 4. POINTS D'ATTENTION…` (S4 refuses it until renamed, or extract by index).
- Other projects (user ask 2026-10-24). Measured project CLAUDE.md, loaded every session of that project: faunosteo 50,228 chars (bigger than the global one), zenquality 23,378, game 14,918, robin_petier 12,895, config 4,990, integration_alphalink 4,249; none has `.claude/rules/`. Splitting is judgment (always-on: overview, stack, commands, conventions; path-scoped: one module, Docker, a folder), so no background automation and no new skill:
- `/onboard` gets a `split` mode (skill edit through /writing-skills: pressure test RED first): read the project CLAUDE.md, classify each section always-on vs path-scoped, propose globs from the real tree, user approves per project, write `.claude/rules/<name>.md` + slim CLAUDE.md + `!.claude/rules/` in .gitignore when `.claude/*` is ignored.
- Generators fixed at the source: onboarder + scaffolder (init-project) emit path rules from day one, so new projects are born split.
- One pass over the git repos in ~/Documents/ (this repo first, then by size: faunosteo, zenquality, game, robin_petier, config, integration_alphalink): one `chore/claude-md-split` branch per repo, per-project approval, never an automatic merge (user signal per repo), `/context` before/after per project recorded in that project's journal.
- Proof: per project, the static glob check + one logged session; total always-on delta across the 7 projects.
- [ ] **Phase 4a, memory v2 write side: shell, no mod** (shrunk 2026-10-25: the measured recall channels never read Meta; the measured status bug is a reconcile parser bug) - [ ] **Phase 4a, memory v2 write side: shell, no mod** (shrunk 2026-10-25: the measured recall channels never read Meta; the measured status bug is a reconcile parser bug)
- Facts 2026-10-24 (scratchpad memeval, 434 entries): registries ~1M chars, never in always-on context, read only by /feat /bugfix /ship-feature (analyze-before-plan); Index drift 6 rows; status in 3 places (title tag, body Status line, Index column) → reconcile false-open BLK-032..034; no single writer (Edit needs a Read of a 357k file, so real writes are ad hoc python/bash); 8 projects on this machine hold v1 registries. Verified 2026-10-25: `lib/reconcile.sh:60-67` drops the entry's OWN header while BLK-032..034 carry `[resolved]` there (the false-open); nothing machine-reads `## Index` (analyze-before-plan.md:42, reconcile.sh:9, test T1); 1 of 1,290 entries across the 8 projects above a 1% accent ratio. - Facts 2026-10-24 (scratchpad memeval, 434 entries): registries ~1M chars, never in always-on context, read only by /feat /bugfix /ship-feature (analyze-before-plan); Index drift 6 rows; status in 3 places (title tag, body Status line, Index column) → reconcile false-open BLK-032..034; no single writer (Edit needs a Read of a 357k file, so real writes are ad hoc python/bash); 8 projects on this machine hold v1 registries. Verified 2026-10-25: `lib/reconcile.sh:60-67` drops the entry's OWN header while BLK-032..034 carry `[resolved]` there (the false-open); nothing machine-reads `## Index` (analyze-before-plan.md:42, reconcile.sh:9, test T1); 1 of 1,290 entries across the 8 projects above a 1% accent ratio.
@@ -0,0 +1,93 @@
# CONTRACT — claude-md-split
- date: 2026-10-26 | flow: ship-feature | branch: feature/claude-md-split (to be started off develop)
- status: active
## REQUEST (verbatim — IMMUTABLE)
Phase 0 of the context mod queue (BDR-125), TODO.md "Phase 0, no mod: split project CLAUDE.md": move the 4 project CLAUDE.md sections to .claude/rules/<name>.md with paths: frontmatter, .gitignore !.claude/rules/, higgsfield MCP user step, /onboard split mode, onboarder + scaffolder emit path rules, then per-repo pass. Shared rules at TODO.md lines 8-13 (baseline /context first, static glob check + InstructionsLoaded session proof, cleanup + citers).
(TODO.md lines 6-30 at commit aaeaac8 are the detailed spec this request points at.)
## CLARIFICATIONS
Pass A (gaps found by the read-before analysis, asked in the STEP 1 brainstorm batch, answered 2026-10-26):
- Q: Scope of this run: the per-repo pass cannot live in this repo's feature branch. / A: this run = this repo's split + static check suite + gitignore socle + proof hook + `/onboard split` mode + onboarder/scaffolder path rules. The per-repo pass over the 6 other repos runs AFTER merge through the shipped `/onboard split`, one chore branch per repo, user approval per repo. [gated 2026-10-26]
- Q: No InstructionsLoaded hook exists anywhere. Throwaway bench or permanent? / A: permanent logging hook `hooks/instructions-loaded.sh` registered in settings.json, one JSON line per loaded instruction file into `~/.claude/logs/instructions-loaded.jsonl`; reused by phase 1 and the per-repo proofs. [gated 2026-10-26]
- Q: `docs/superpowers/**` matches 0 tracked files at rest and those files are Written, never Read: static check fails by construction. / A: path rule `.claude/rules/transient-artifacts.md` (paths `docs/superpowers/**`, `.audit/**`) with a YAML comment `# static-check: skip` in the frontmatter that the checker honors; its proof is the logged session. [gated 2026-10-26]
- Q: Patch `templates/gitignore/standard.gitignore` (the socle) too? / A: yes, socle + this repo's `.gitignore`, gitflow-test assertions updated. [gated 2026-10-26]
Brainstorm (design approved 2026-10-26): rule files `rules-maintenance.md`, `graphify-vendored.md`, `mods.md`, `transient-artifacts.md`; lib `lib/project-rules.sh` (check / sections / extract); generator skeleton set docker + testing + ci under `templates/project-rules/`; onboarder `MODE: split` executes the approved table; RED-then-GREEN pressure test on the skill edit. [gated 2026-10-26]
Pass B (plan, 2026-10-26):
- Q: name of the fourth lib subcommand that writes a skeleton with the matching globs only? / A: `emit <skeleton> <out>`. [gated 2026-10-26]
- Q: heading of the pointer section left in a split CLAUDE.md? / A: `## Path-scoped rules`. [gated 2026-10-26]
- Q: language of the new onboard § SPLIT MODE and onboarder MODE: split inside a French skill? / A: English. [gated 2026-10-26]
## ACCEPTANCE CRITERIA
1. Project `CLAUDE.md` no longer holds the 4 sections (rules/ maintenance, graphify vendored skill, mods/, transient planning artifacts); it keeps Health Stack plus a short pointer to `.claude/rules/`.
CHECK: cd /home/bchanot/Documents/claude && ! grep -qE '^## (rules/ maintenance|Machine-owned: the vendored graphify skill|mods/ — function-hooks|Transient planning artifacts)' CLAUDE.md && grep -q '.claude/rules' CLAUDE.md && echo SPLIT-OK
EXPECT: SPLIT-OK
EVIDENCE: MET exit=0 marker-found :: SPLIT-OK
2. Each moved section lives in `.claude/rules/<name>.md` with a `paths:` frontmatter that parses (same shape as `rules/a11y.md`), is tracked by git (`!.claude/rules/` negation in `.gitignore`), and each glob matches at least one path in the working tree (the static check, `lib/project-rules.sh check`), unless the rule carries the `# static-check: skip` marker (transient-artifacts only).
CHECK: cd /home/bchanot/Documents/claude && test "$(git ls-files .claude/rules | wc -l)" -ge 4 && bash lib/project-rules.sh check | grep -q '4 rule(s) ok' && echo RULES-STATIC-OK
EXPECT: RULES-STATIC-OK
EVIDENCE: MET exit=0 marker-found :: RULES-STATIC-OK
3. The static glob check is a `make test` suite (`lib/tests/project-rules.test.sh`) with flip tests (an unmatched glob, a literal typo, a dep-dir-only match each fail it).
CHECK: cd /home/bchanot/Documents/claude && make test suite=lib/tests/project-rules.test.sh 2>&1 | grep -q 'all suites green' && grep -c 'T2c-literal-typo-fails\|T2d-dep-dir-only' lib/tests/project-rules.test.sh | grep -qx 2 && echo SUITE-OK
EXPECT: SUITE-OK
EVIDENCE: MET exit=0 marker-found :: SUITE-OK
4. One real session shows each moved rule loading on `load_reason: path_glob_match` (`~/.claude/logs/instructions-loaded.jsonl`, filtered on `memory_type == "Project"` and `/.claude/rules/`), plus one sub-agent probe recording whether a path rule loads inside a sub-agent; evidence pasted into the journal.
5. `/context` measured before and after at the repo root; the always-on delta recorded in the journal.
6. The higgsfield user-scope MCP is removed by the user (`claude mcp remove -s user higgsfield`), recorded as a manual step, no toggle ownership and no doctor check added.
7. Every citer of the moved headings or of "project CLAUDE.md" as their location is patched (rules/README.md:9, doctor.sh:76 comment, ARCHITECTURE.md tree, any skill/lib/agent grep hit); append-only registries untouched.
CHECK: cd /home/bchanot/Documents/claude && ! grep -rnE 'CLAUDE\.md`? \(project scope\)|29-line project CLAUDE.md' rules/ doctor.sh skills/ agents/ lib/ hooks/ --include='*.md' --include='*.sh' | grep -v skills-external && echo CITERS-OK
EXPECT: CITERS-OK
EVIDENCE: MET exit=0 marker-found :: CITERS-OK
8. `/onboard` gains a `split` mode (public name per pass B) that classifies an existing project CLAUDE.md's sections always-on vs path-scoped, proposes globs from the real tree, gets per-project approval, writes `.claude/rules/<name>.md` + slimmed CLAUDE.md + the `!.claude/rules/` negation when `.claude/*` is ignored. Skill edit goes through /writing-skills with a RED pressure test first.
9. onboarder and scaffolder emit path rules from day one (the sections classified path-scoped per the brainstorm), with the gitignore negation reaching the project through the gitflow socle: before the root commit for a scaffold (init-project STEP 5f `gitflow init`), at /onboard STEP 2.6 `gitflow init` for an onboarded project (after the onboarder's write, before any commit); the onboarder's own PHASE 4 is unchanged. [amended 2026-10-26, plan r2/r3]
10. Full suite green: `make test`.
CHECK: cd /home/bchanot/Documents/claude && make test 2>&1 | tail -3 | grep -q 'all suites green' && echo MAKE-TEST-OK
EXPECT: MAKE-TEST-OK
EVIDENCE: MET exit=0 marker-found :: MAKE-TEST-OK
11. shellcheck clean on the Health Stack scope.
CHECK: cd /home/bchanot/Documents/claude && shellcheck ./*.sh hooks/*.sh lib/*.sh && echo SHELLCHECK-OK
EXPECT: SHELLCHECK-OK
EVIDENCE: MET exit=0 marker-found :: SHELLCHECK-OK
12. `lib/project-rules.sh matches <glob>`: rc 0 + up to 3 hits on stdout; rc 1 + `no match: <glob>` on stderr; a glob with more than a pipe buffer of hits is still a match (no `head` after the producer; T5k/T5l). [gated 2026-10-26]
CHECK: cd /home/bchanot/Documents/claude && bash lib/project-rules.sh matches 'skills/**' >/dev/null && ! bash lib/project-rules.sh matches 'nowhere/**' 2>/dev/null && grep -c 'T5k-many-hits-rc\|T5l-three-lines' lib/tests/project-rules.test.sh | grep -qx 2 && echo MATCHES-OK
EXPECT: MATCHES-OK
EVIDENCE: MET exit=0 marker-found :: MATCHES-OK
13. Every subcommand takes a leading `-C <dir>` (a dispatched agent's cwd is the session's); a missing dir is rc 2. [gated 2026-10-26]
CHECK: cd / && bash /home/bchanot/Documents/claude/lib/project-rules.sh -C /home/bchanot/Documents/claude check | grep -q '4 rule(s) ok' && ! bash /home/bchanot/Documents/claude/lib/project-rules.sh -C /nonexistent-dir check 2>/dev/null && echo DASH-C-OK
EXPECT: DASH-C-OK
EVIDENCE: MET exit=0 marker-found :: DASH-C-OK
14. `emit <skeleton> <out>` writes the skeleton with the matching globs only, rc 1 and nothing written when none matches, rc 2 when the target exists; the three skeletons `templates/project-rules/{docker,testing,ci}.md` exist with `paths:` frontmatter and `TODO(/onboard STEP 3)` stubs. [gated 2026-10-26]
CHECK: cd /home/bchanot/Documents/claude && test -f templates/project-rules/docker.md && test -f templates/project-rules/testing.md && test -f templates/project-rules/ci.md && grep -c 'T12b-docker-globs-pruned\|T12f-ci-not-emitted-rc\|T12h-existing-target-rc' lib/tests/project-rules.test.sh | grep -qx 3 && echo EMIT-OK
EXPECT: EMIT-OK
EVIDENCE: MET exit=0 marker-found :: EMIT-OK
15. The hook logs `ts, session_id, agent_id, agent_type, cwd, file_path, memory_type, load_reason, globs, trigger_file_path`, honors `CLAUDE_INSTRUCTIONS_LOG`, rotates above 5 MB, exits 0 with no stdout when jq is absent or the log is unwritable; registered in `settings.json` under `InstructionsLoaded`. [gated 2026-10-26]
CHECK: cd /home/bchanot/Documents/claude && jq -r '.hooks.InstructionsLoaded[0].hooks[0].command' settings.json | grep -q 'instructions-loaded.sh' && grep -c 'T10e-ids-kept\|T10h-no-jq-rc0\|T10k-rotated' lib/tests/project-rules.test.sh | grep -qx 3 && echo HOOK-OK
EXPECT: HOOK-OK
EVIDENCE: MET exit=0 marker-found :: HOOK-OK
16. `skills/onboard/SKILL.md` gains `## MODE DISPATCH` and `## SPLIT MODE` (S1 preconditions, S2 baseline, S3 branch, S4 classify with `matches`, S5 mandatory gate, S6 onboarder dispatch, S7 after, never `finish`); `agents/onboarder.md` gains `## MODE: split` (S0 preflight incl. gitignore negation, S1 extract with rollback, S2 pointer, S3 check + commit rc checked + `cat-file -e HEAD:` per rule, two STOP shapes); the routing locks stay green. [gated 2026-10-26]
CHECK: cd /home/bchanot/Documents/claude && grep -q '^## MODE DISPATCH' skills/onboard/SKILL.md && grep -q '^## SPLIT MODE' skills/onboard/SKILL.md && grep -q '^## MODE: split' agents/onboarder.md && grep -q 'cat-file -e HEAD:' agents/onboarder.md && grep -q 'not in HEAD after commit' agents/onboarder.md && echo SPLIT-MODE-OK
EXPECT: SPLIT-MODE-OK
EVIDENCE: MET exit=0 marker-found :: SPLIT-MODE-OK
17. onboarder `## PHASE 5b` and scaffolder `## PHASE 3b` emit `docker`/`testing`/`ci` through `emit`, then run `check`; `templates/project-CLAUDE.md` header names `.claude/rules/`. [gated 2026-10-26]
CHECK: cd /home/bchanot/Documents/claude && grep -q '^## PHASE 5b' agents/onboarder.md && grep -q '^## PHASE 3b' agents/scaffolder.md && grep -q 'Path-scoped rules: .claude/rules' templates/project-CLAUDE.md && echo GENERATORS-OK
EXPECT: GENERATORS-OK
EVIDENCE: MET exit=0 marker-found :: GENERATORS-OK
18. Socle: `templates/gitignore/standard.gitignore` carries `!.claude/rules/` after `.claude/*`, `lib/gitflow-test.sh` asserts it, and `.claude/rules/` is not ignored in this repo. [gated 2026-10-26]
CHECK: cd /home/bchanot/Documents/claude && grep -qxF '!.claude/rules/' templates/gitignore/standard.gitignore && grep -q 'socle: !.claude/rules/' lib/gitflow-test.sh && ! git check-ignore -q .claude/rules/probe.md && echo SOCLE-OK
EXPECT: SOCLE-OK
EVIDENCE: MET exit=0 marker-found :: SOCLE-OK
19. RED then GREEN pressure test on the `/onboard split` skill text (Tasks 6 and 8: RED = the current skill runs archetype detection on `split`; GREEN = the edited skill reaches the S5 table and stops; the onboarder dry run on a branched scratch commits 2 rules with `all rules in HEAD` and leaves this repo's status unchanged). Outcomes recorded for the STEP 7 EVAL entry. Manual. [gated 2026-10-26]
20. `.claude/tasks/TODO.md`: phase 0 item checked with what shipped, the proof / higgsfield / phase-2 sub-items open, phase 0b per-repo pass queued with the repo order. [gated 2026-10-26]
CHECK: cd /home/bchanot/Documents/claude && grep -q 'Phase 0b, per-repo pass' .claude/tasks/TODO.md && grep -q '\[x\] \*\*Phase 0, no mod' .claude/tasks/TODO.md && echo TODO-OK
EXPECT: TODO-OK
EVIDENCE: MET exit=0 marker-found :: TODO-OK
## FILE SCOPE
- `CLAUDE.md`, `.claude/rules/*.md` (new), `.gitignore`, `templates/gitignore/standard.gitignore` (pending clarification), `rules/README.md`
- `skills/onboard/SKILL.md`, `agents/onboarder.md`, `agents/scaffolder.md`, `skills/init-project/SKILL.md`, `templates/project-CLAUDE.md`, `templates/` (new path-rule template)
- `lib/project-rules.sh` (new), `lib/tests/project-rules.test.sh` (new), `lib/gitflow-test.sh` (socle assertion), `templates/project-rules/` (new skeletons)
- `doctor.sh`, `ARCHITECTURE.md`, `README.md` (doc pipeline), `hooks/instructions-loaded.sh` (new) + `settings.json` (hook registration)
- `docs/superpowers/specs/`, `docs/superpowers/plans/` (run artifacts, purged at finish)
- `.claude/tasks/TODO.md`, `.claude/memory/*` (capitalize)
- Out of scope in this repo: the 6 other projects' trees (per-repo pass, pending clarification).
+1
View File
@@ -124,6 +124,7 @@ skills-disabled/
!.claude/memory/ !.claude/memory/
!.claude/audits/ !.claude/audits/
!.claude/settings.json !.claude/settings.json
!.claude/rules/
# But keep local stuff ignored within .claude/ # But keep local stuff ignored within .claude/
.claude/settings.local.json .claude/settings.local.json
.claude/agent-memory/ .claude/agent-memory/
+4 -3
View File
@@ -20,16 +20,17 @@ claude-config/
├── update-all.sh # One-command update for all components ├── update-all.sh # One-command update for all components
├── Makefile # Unified entry point: make install / doctor / update / test (make help) ├── Makefile # Unified entry point: make install / doctor / update / test (make help)
├── plugins.lock.json # Version pinning for non-marketplace dependencies and vendored skills ├── plugins.lock.json # Version pinning for non-marketplace dependencies and vendored skills
├── hooks/ # Claude Code hooks: session start, statusline, RTK rewrite, ctx7 + design-toolchain reminders, attention notify, unpushed-work guard, manual-mode push guard ├── hooks/ # Claude Code hooks: session start, statusline, RTK rewrite, ctx7 + design-toolchain reminders, attention notify, unpushed-work guard, manual-mode push guard, instruction-load log
├── githooks/ # Generated git hooks (pre-commit, post-commit, post-merge, reference-transaction), git's global core.hooksPath ├── githooks/ # Generated git hooks (pre-commit, post-commit, post-merge, reference-transaction), git's global core.hooksPath
├── .githooks/ # This repo's own copy of the same hooks ├── .githooks/ # This repo's own copy of the same hooks
├── .claude/rules/ # This repo's project path rules (paths: frontmatter), loaded on Read of a matching file
├── rules/ # Rule files deployed to ~/.claude/rules (path-scoped or always-on) ├── rules/ # Rule files deployed to ~/.claude/rules (path-scoped or always-on)
├── agents/ # Execution units called by skills (never invoked directly) ├── agents/ # Execution units called by skills (never invoked directly)
├── skills/ # Entry points invoked via /skill-name ├── skills/ # Entry points invoked via /skill-name
├── mods/ # Claude Code mods (function-hooks plugins), loaded through the skills/<name> symlink ├── mods/ # Claude Code mods (function-hooks plugins), loaded through the skills/<name> symlink
├── skills-external/ # Vendored skill packs: gstack submodule, design skills, superpowers, agent-skills, MengTo scroll skills, 21st and Higgsfield packs (machine-owned copies gitignored) ├── skills-external/ # Vendored skill packs: gstack submodule, design skills, superpowers, agent-skills, MengTo scroll skills, 21st and Higgsfield packs (machine-owned copies gitignored)
├── templates/ # Per-project templates (CLAUDE.md, settings, memory registries, deploy runbook, gitignore) ├── templates/ # Per-project templates (CLAUDE.md, settings, memory registries, path-rule skeletons, deploy runbook, gitignore)
└── lib/ # Shared libs: gitflow, profiles, vendoring, route doctrine, gates, archetypes, tests └── lib/ # Shared libs: gitflow, profiles, vendoring, route doctrine, gates, archetypes, project-rule oracle, tests
``` ```
## Architecture principles ## Architecture principles
+3
View File
@@ -17,6 +17,8 @@ Format follows [Keep a Changelog](https://keepachangelog.com/) and this project
- **model-router prompt classifier**: a plain prompt typed in the composer (12 characters or more, not a slash command, not mid-turn, never under `-p` or in a sub-agent) that no keyword rule, skill, run slot, `/route` or floor covers is labelled by one call to the engine's small model (`design`, `analysis`, `coding`, `bookkeeping`, `chat`), bounded to 3 s. The label maps to plan, reflect, implement or apply and the turn takes that phase's route: its effort, and its model under the switch and the downgrade cap, never above the session model (an `ultrathink` floor raises the effort only, the guess's model holds); no dialog, no file write, gone at the end of the turn, replaced by any route call or typed skill, and dropped for that turn by a `/effort` typed between turns. Three failures in a row pause it for `cooldownMinutes` (one toast, `classifier: paused` in the status line). `"classify": false` in `~/.claude/model-router.json` and `/route classify on|off` turn it off; `/route show` prints `classify:`. The status line reads `route: classifier <phase>` and `/route verbose on` adds `(<phase>: classifier)`. - **model-router prompt classifier**: a plain prompt typed in the composer (12 characters or more, not a slash command, not mid-turn, never under `-p` or in a sub-agent) that no keyword rule, skill, run slot, `/route` or floor covers is labelled by one call to the engine's small model (`design`, `analysis`, `coding`, `bookkeeping`, `chat`), bounded to 3 s. The label maps to plan, reflect, implement or apply and the turn takes that phase's route: its effort, and its model under the switch and the downgrade cap, never above the session model (an `ultrathink` floor raises the effort only, the guess's model holds); no dialog, no file write, gone at the end of the turn, replaced by any route call or typed skill, and dropped for that turn by a `/effort` typed between turns. Three failures in a row pause it for `cooldownMinutes` (one toast, `classifier: paused` in the status line). `"classify": false` in `~/.claude/model-router.json` and `/route classify on|off` turn it off; `/route show` prints `classify:`. The status line reads `route: classifier <phase>` and `/route verbose on` adds `(<phase>: classifier)`.
- **model-router cold-read caps**: both main-loop caps measure the cold read a switch costs, from a per-model record of main's last step, warm within the engine's prompt-cache TTL (`cache_ttl` 5m or 1h from main's model-switch events, 1 h before the first, kept across `/clear`; records cleared by `/clear` and `/route reload`), plus the submitted prompt the engine's usage may not count yet (code points / 3 of its text, context entries and a typed skill's body, added at the turn's first main step unless usage already grew by half of it; a `document` attachment blocks the switch for that step); `downgradeMaxTokens` (default 120000) joins `upgradeMaxTokens` (200000). A model-loaded helper skill inside a best-tier run moves effort only; main routed onto a model whose window the context outgrew returns to the session model. `/route show` prints `switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`, the status line shows ` · switch off` only when the switch is off, the skip line is logged once per cap crossing and the change toast names a cap hold. A built-in `general-purpose` agent that main spawns with no model while main sits below the session model starts on the session model instead of inheriting the lower one. - **model-router cold-read caps**: both main-loop caps measure the cold read a switch costs, from a per-model record of main's last step, warm within the engine's prompt-cache TTL (`cache_ttl` 5m or 1h from main's model-switch events, 1 h before the first, kept across `/clear`; records cleared by `/clear` and `/route reload`), plus the submitted prompt the engine's usage may not count yet (code points / 3 of its text, context entries and a typed skill's body, added at the turn's first main step unless usage already grew by half of it; a `document` attachment blocks the switch for that step); `downgradeMaxTokens` (default 120000) joins `upgradeMaxTokens` (200000). A model-loaded helper skill inside a best-tier run moves effort only; main routed onto a model whose window the context outgrew returns to the session model. `/route show` prints `switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`, the status line shows ` · switch off` only when the switch is off, the skip line is logged once per cap crossing and the change toast names a cap hold. A built-in `general-purpose` agent that main spawns with no model while main sits below the session model starts on the session model instead of inheriting the lower one.
- **/explain-diff skill**: turns a change (commit, range, branch, merge, PR, staged or uncommitted work) into one self-contained HTML page saved outside the repo, under `~/Documents/explanations/<project>/YYYY-MM-DD-<slug>.html`. The page has a background, an intuition built on toy data with HTML diagrams, a code walkthrough grouped by concern and a 5-question interactive quiz. Adapted from Geoffrey Litt's explain-diff gist. A bundled template (light and dark, works offline) and a checker (`scripts/check_explanation.py`: file name, location, sections, quiz, code escaping, no ASCII art, no em-dash) hold every page to the same floor. Routing row `reflect`; profiles full, max and dev. - **/explain-diff skill**: turns a change (commit, range, branch, merge, PR, staged or uncommitted work) into one self-contained HTML page saved outside the repo, under `~/Documents/explanations/<project>/YYYY-MM-DD-<slug>.html`. The page has a background, an intuition built on toy data with HTML diagrams, a code walkthrough grouped by concern and a 5-question interactive quiz. Adapted from Geoffrey Litt's explain-diff gist. A bundled template (light and dark, works offline) and a checker (`scripts/check_explanation.py`: file name, location, sections, quiz, code escaping, no ASCII art, no em-dash) hold every page to the same floor. Routing row `reflect`; profiles full, max and dev.
- **Project path rules (CLAUDE.md split)**: `lib/project-rules.sh` (`check`, `matches`, `sections`, `extract`, `emit`, optional `-C <dir>`) is the glob oracle for `.claude/rules/<name>.md` rules, one-line `paths:` frontmatter, loaded on Read of a matching file; suite `lib/tests/project-rules.test.sh`. `/onboard split` classifies an existing project CLAUDE.md section by section behind a gate and moves the path-bound ones into rules on a `chore/claude-md-split` branch. `/onboard` and `/init-project` emit `docker`, `testing` and `ci` rules from `templates/project-rules/` when their globs match. This repo's CLAUDE.md now keeps its header, Health Stack and a pointer; four sections load as path rules.
- **InstructionsLoaded logger**: `hooks/instructions-loaded.sh`, wired in `settings.json`, appends one JSON line per instruction file loaded to `~/.claude/logs/instructions-loaded.jsonl` (rotated above 5 MB), the proof that a path rule loaded.
### Changed ### Changed
- impeccable is the Build path for all UI: it replaces `frontend-design` on the design gate's `# GATE-BLOCK:` list and leads the Build line of the design doctrine. `frontend-design` stays installed as the light path for a one-off visual. Detector rule count corrected 45 to 61 (BDR-119). - impeccable is the Build path for all UI: it replaces `frontend-design` on the design gate's `# GATE-BLOCK:` list and leads the Build line of the design doctrine. `frontend-design` stays installed as the light path for a one-off visual. Detector rule count corrected 45 to 61 (BDR-119).
@@ -33,6 +35,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/) and this project
- `/release-candidate` STEP 6: in manual push mode, with an invalid mode value, or when main or develop is not on origin, Claude pushes nothing and prints one command for the user, `! git push --atomic origin main develop v<X.Y.Z>`. The tag-push question remains for auto-push mode with both branches on origin. The version must match `^[0-9]+\.[0-9]+\.[0-9]+$` before it enters a command or tag; `release-executor` checks it too and blocks on anything else. - `/release-candidate` STEP 6: in manual push mode, with an invalid mode value, or when main or develop is not on origin, Claude pushes nothing and prints one command for the user, `! git push --atomic origin main develop v<X.Y.Z>`. The tag-push question remains for auto-push mode with both branches on origin. The version must match `^[0-9]+\.[0-9]+\.[0-9]+$` before it enters a command or tag; `release-executor` checks it too and blocks on anything else.
- `/tour`: each summary row says `on origin` or `local only` with the `! git -C "<project>" push -u origin <branch>` to run. The tour never pushes or retries. - `/tour`: each summary row says `on origin` or `local only` with the `! git -C "<project>" push -u origin <branch>` to run. The tour never pushes or retries.
- model-router keyword prompt rules (`plan|design|architecture…`, `why|review|audit…`), the `ultrathink` floor and the derived `orchestrate` route of a main Agent dispatch set the turn's effort only, never a model: they no longer lift main above the session model, and a held best-tier run keeps its model. Fable on main comes only from a skill row, the `route` tool, a typed `/route` or a `/model` hand pick (BDR-123). Tests: `mods/model-router/hooks/register.test.ts`. - model-router keyword prompt rules (`plan|design|architecture…`, `why|review|audit…`), the `ultrathink` floor and the derived `orchestrate` route of a main Agent dispatch set the turn's effort only, never a model: they no longer lift main above the session model, and a held best-tier run keeps its model. Fable on main comes only from a skill row, the `route` tool, a typed `/route` or a `/model` hand pick (BDR-123). Tests: `mods/model-router/hooks/register.test.ts`.
- `.gitignore` and `templates/gitignore/standard.gitignore` un-ignore `.claude/rules/` (`!.claude/rules/` after `.claude/*`); `lib/gitflow-test.sh` asserts the socle line.
### Removed ### Removed
- The five `effort-low` … `effort-max` skills, `lib/effort-pins.txt`, `lib/effort-pins.sh` and `lib/model-check.sh`, with their tests and the effort-pin re-apply steps of `install-plugins.sh` and `update-all.sh`. The model-router rows replace them. A typed `/effort-<level>` no longer exists: use `ultrathink` or `/route effort=max`. Breaking: the next release is 3.0.0. - The five `effort-low` … `effort-max` skills, `lib/effort-pins.txt`, `lib/effort-pins.sh` and `lib/model-check.sh`, with their tests and the effort-pin re-apply steps of `install-plugins.sh` and `update-all.sh`. The model-router rows replace them. A typed `/effort-<level>` no longer exists: use `ultrathink` or `/route effort=max`. Breaking: the next release is 3.0.0.
+5 -89
View File
@@ -7,92 +7,8 @@
## Health Stack ## Health Stack
- shell: `shellcheck *.sh hooks/*.sh lib/*.sh` - shell: `shellcheck *.sh hooks/*.sh lib/*.sh`
## rules/ maintenance ## Path-scoped rules
Project rules live in `.claude/rules/<name>.md` and load on Read of a file
Modular instruction files loaded by Claude Code alongside the global memory. matching their `paths:` (never at session start): rules-maintenance,
`rules/` is symlinked to `~/.claude/rules` by `link.sh` (user scope, ALL graphify-vendored, mods, transient-artifacts. Check: `bash
projects). One rule = one file = one concern. lib/project-rules.sh check` (runs in `make test`).
A rule WITH `paths:` YAML frontmatter (glob list) loads lazily — only when
Claude reads a file matching a glob; a rule WITHOUT it loads at session
start, same cost as the global memory. Extract from CLAUDE.global.md only
what can be path-scoped (the token win) or what is generated; always-on
doctrine stays in CLAUDE.global.md. Exception: a standalone user-authored
rule set that would bust the 320-line density budget may live here WITHOUT
`paths:` (always-on load) — writing-style.md (BDR-085), default-language.md
(BDR-118), secure-by-default.md (BDR-120). `paths:` globs match against the
CURRENT project's tree — a broad glob (e.g. `rules/**`) can fire in foreign
projects; keep rule bodies tiny.
Docs: https://code.claude.com/docs/en/memory.md#path-specific-rules
Machine-owned: `rules/context7.md` is DELETED BY DESIGN (BDR-053,
2026-07-06) — `ctx7 setup --claude --cli` still writes it, but
install-plugins.sh STEP ctx7 purges it right after; the find-docs skill is
the single ctx7 surface. If it reappears (manual `ctx7 setup`), delete it
or re-run `make plugin`.
## Machine-owned: the vendored graphify skill
`skills/graphify/SKILL.md`, `skills/graphify/references/` and
`.graphify_version` are written by `graphify claude install`
(`install-plugins.sh` STEP graphify), which lands in the repo because
`~/.claude/skills` is a symlink to `skills/`. They are gitignored: a
`pipx upgrade graphifyy` used to dirty the tree and cost a
`chore(graphify): sync vendored skill X -> Y` commit each time.
Two graphify commands, easy to confuse, and only one restores the skill:
- `graphify install --platform claude` copies SKILL.md + `references/` +
`.graphify_version` into `skills/graphify/`. Touches nothing else.
This is the recovery command.
- `graphify claude install` writes the CLAUDE.md graphify section and the
`.claude/settings.json` PreToolUse hooks. It **rewrites both guarded
configs** (EVAL-020, verified again 2026-09-15), so revert them after. It does NOT copy
the skill.
`make plugin` runs both (`install-plugins.sh` STEP graphify) behind the
guarded-config EXIT trap, so a fresh clone is covered.
Trade-off accepted: an upstream release can now change the skill's prompt
with no diff to review. `skills/graphify/test-prompts.json` is hand-written
for darwin and stays tracked.
Gotcha, learned the hard way: `git rm --cached` keeps the working file,
but if the branch you merge into still tracks it, the merge deletes it
from disk. Untrack and merge, then restore with the command above.
## mods/ — function-hooks plugins (Claude Code mods)
A mod lives in `mods/<name>/` (`.claude-plugin/plugin.json` + hooks). It
loads through the tracked relative symlink `skills/<name>` -> `../mods/<name>`
(`~/.claude/skills` links to `skills/`) as `<name>@skills-dir`, in place,
live at the next session or `/reload-plugins`. New mod: `ln -s ../mods/<name>
skills/<name>` from the repo root (guard with `[ -L ]`, a re-run nests a link).
Not `CLAUDE_CODE_PLUGIN_DIRS` (absolute path, settings `env` has no `$HOME`
expansion, settings.json is tracked), nor a local marketplace (`add` writes
an absolute path into settings.json).
- The engine lays `mods/<name>/tsconfig.json` and `.claude-plugin/types/`;
both are gitignored.
- Optional user config: `~/.claude/<name>.json`. Its `"enabled": false` is the
per-machine off switch (untracked). `"<name>@skills-dir": false` in
`enabledPlugins` also works but lands in the TRACKED settings.json and
dirties every machine's tree.
- A dev copy of the same name (`--plugin-dir`, hot-reload link in
`~/.claude/dev-mods/<session>/`) shadows the skills-dir copy for that
session: remove it before reading `/reload-plugins` as a test of the link.
- Tests: `make test suite=lib/tests/mods.test.sh` (manifest, link,
`claude plugin validate`, `claude plugin test`). `doctor.sh` has a Mods section.
## Transient planning artifacts
`docs/superpowers/specs/**` and `docs/superpowers/plans/**` are run-time
artifacts of a feature pipeline (subagent briefs, reviewer references).
They are committed DURING the run (the SDD worktree + reviewers read them
from disk — NOT gitignored), then AUTO-PURGED by `gitflow finish` on a
`feature`/`bugfix` branch, before the merge, so develop's tip stays clean
(BDR-065, `lib/gitflow.sh` `_gitflow_purge_transient`). The feature commits
stay reachable from develop, so `git show <sha>:docs/…` is still the archive.
Opt out with `GITFLOW_PURGE_TRANSIENT=0`. NOT in scope: `.claude/tasks/{contracts,plans}`
(durable, versioned, referenced by decisions.md). Durable knowledge goes to
`.claude/memory/` registries, never to these files. Derived scan/audit
outputs (`.audit/**`) are gitignored and never committed, even redacted
(LRN-124).
+1 -1
View File
@@ -208,7 +208,7 @@ a different package, ships its own conflicting `graphify` bin) — see
|---|---| |---|---|
| `/init-project` | Initialize a complete project from scratch (full orchestrator, 12+ steps) | | `/init-project` | Initialize a complete project from scratch (full orchestrator, 12+ steps) |
| `/ship-feature` | Ship a feature end-to-end with validation gates (full orchestrator) | | `/ship-feature` | Ship a feature end-to-end with validation gates (full orchestrator) |
| `/onboard` | Onboard an existing project: CLAUDE.md, settings, .claudeignore, archetype audits, report and a sequenced TODO backlog | | `/onboard` | Onboard an existing project: CLAUDE.md, settings, .claudeignore, path rules, archetype audits, report and a sequenced TODO backlog. `/onboard split` moves the path-bound sections of an existing CLAUDE.md into `.claude/rules/` (loaded on Read of a matching file) |
| `/feat` | Small feature implementation (1-5 files, lightweight) | | `/feat` | Small feature implementation (1-5 files, lightweight) |
| `/bugfix` | Structured bug fix with root cause investigation | | `/bugfix` | Structured bug fix with root cause investigation |
| `/hotfix` | Quick fix for superficial bugs (typos, CSS, config — max 2 files) | | `/hotfix` | Quick fix for superficial bugs (typos, CSS, config — max 2 files) |
+3 -2
View File
@@ -139,7 +139,7 @@ Tu veux...
| `/feat` | Petite feature (1-5 fichiers) | Léger, pas d'orchestration lourde | | `/feat` | Petite feature (1-5 fichiers) | Léger, pas d'orchestration lourde |
| `/bugfix` | Bug avec investigation root cause | Hypothèses, diagnostic, fix minimal | | `/bugfix` | Bug avec investigation root cause | Hypothèses, diagnostic, fix minimal |
| `/hotfix` | Bug superficiel (typo, CSS, config) | Max 2 fichiers, cause évidente | | `/hotfix` | Bug superficiel (typo, CSS, config) | Max 2 fichiers, cause évidente |
| `/onboard` | Projet existant non géré par ce config | Génère CLAUDE.md + settings | | `/onboard` | Projet existant non géré par ce config | Génère CLAUDE.md + settings ; `/onboard split` découpe un CLAUDE.md existant en règles `.claude/rules/` |
| `/plugin-check` | Avant de démarrer tout travail | Aussi embarqué en STEP 0 des orchestrateurs | | `/plugin-check` | Avant de démarrer tout travail | Aussi embarqué en STEP 0 des orchestrateurs |
| `/analyze` | Comprendre du code avant de le modifier | Read-only, aucune solution proposée | | `/analyze` | Comprendre du code avant de le modifier | Read-only, aucune solution proposée |
| `/analyze` + erreur | Diagnostiquer un test/build qui échoue | Mode DEBUG : hypothèses ordonnées | | `/analyze` + erreur | Diagnostiquer un test/build qui échoue | Mode DEBUG : hypothèses ordonnées |
@@ -286,7 +286,7 @@ cd mon-projet-existant/
| 0 | plugin-advisor — détection signaux + activation plugins | recommandations plugins | | 0 | plugin-advisor — détection signaux + activation plugins | recommandations plugins |
| 1 | Archetype detection (scan ~/.claude/lib/project-archetypes/*.md) | archétype SELECTED + implications auto | | 1 | Archetype detection (scan ~/.claude/lib/project-archetypes/*.md) | archétype SELECTED + implications auto |
| 1b | Gate monorepo (A/B/C si détecté) | mode choisi | | 1b | Gate monorepo (A/B/C si détecté) | mode choisi |
| 2 | Config baseline (onboarder agent) | CLAUDE.md, settings.json, .claudeignore, .claude/tasks/ + .claude/memory/ + .claude/audits/ | | 2 | Config baseline (onboarder agent) | CLAUDE.md, settings.json, .claudeignore, .claude/tasks/ + .claude/memory/ + .claude/audits/ + .claude/rules/ (docker, testing, ci si un glob matche) |
| 2.5| Lib d'animation (`motion`), proposée, opt-in | dépendance si acceptée | | 2.5| Lib d'animation (`motion`), proposée, opt-in | dépendance si acceptée |
| 2.6| Gitflow init (main + develop, hooks) | branches + .githooks/ | | 2.6| Gitflow init (main + develop, hooks) | branches + .githooks/ |
| 3 | Interview deep = business minimum (users, deadlines, équipe, légal, perfs) + adaptative par archétype | brief enrichi | | 3 | Interview deep = business minimum (users, deadlines, équipe, légal, perfs) + adaptative par archétype | brief enrichi |
@@ -311,6 +311,7 @@ cd mon-projet-existant/
``` ```
/onboard "Python FastAPI" # hint stack /onboard "Python FastAPI" # hint stack
/onboard force-archetype:wordpress # override detection /onboard force-archetype:wordpress # override detection
/onboard split # CLAUDE.md existant → règles .claude/rules/ (sections liées à un chemin)
``` ```
**Après /onboard :** **Après /onboard :**
+124 -1
View File
@@ -11,6 +11,9 @@ effort: medium
## ROLE ## ROLE
Generate the baseline claude-config files in a project directory. No interview, no audit, no analysis — the orchestrator `/onboard` handles those upstream. This agent only writes config files given a prepared brief. Generate the baseline claude-config files in a project directory. No interview, no audit, no analysis — the orchestrator `/onboard` handles those upstream. This agent only writes config files given a prepared brief.
Two modes. No `MODE:` line in the brief → the generator below (PHASES 1-6).
`MODE: split` → only § MODE: split at the end of this file runs.
--- ---
## INPUTS (passed by orchestrator) ## INPUTS (passed by orchestrator)
@@ -125,6 +128,24 @@ ls ${PROJECT_ROOT}/.claude/tasks/TODO.md ${PROJECT_ROOT}/.claude/memory/ 2>/dev/
**Do NOT overwrite existing content.** **Do NOT overwrite existing content.**
## PHASE 5b — PATH-SCOPED RULES (born split)
For each of `docker`, `testing`, `ci`:
```bash
bash ~/.claude/lib/project-rules.sh -C <PROJECT_ROOT> emit ~/.claude/templates/project-rules/<name>.md .claude/rules/<name>.md
```
- rc 0 → written with the globs that match this tree; its stub comments
are `<!-- TODO(/onboard STEP 3): … -->` placeholders the orchestrator's
STEP 3 fills (list them in OUTPUT beside the CLAUDE.md placeholders).
Fill now only what the BRIEF already settles (`docker` commands from
`build_cmd`, `testing` layout from `test_cmd`); never duplicate the
always-on Build/Test sections.
- rc 1 → no match, nothing written, skip silently.
- rc 2 → the file exists: keep it, never overwrite.
Then `bash ~/.claude/lib/project-rules.sh -C <PROJECT_ROOT> check` must print
`N rule(s) ok`. The `!.claude/rules/` negation comes from the gitflow socle
at /onboard STEP 2.6 (`gitflow init` reconciles it); PHASE 4 stays as is.
--- ---
## PHASE 6 — GSD v2 ROADMAP (optional, per orchestrator flag) ## PHASE 6 — GSD v2 ROADMAP (optional, per orchestrator flag)
@@ -156,6 +177,7 @@ FILES WRITTEN:
✅ .claude/memory/journal.md (created | unchanged) ✅ .claude/memory/journal.md (created | unchanged)
✅ .claude/memory/evals.md (created | unchanged) ✅ .claude/memory/evals.md (created | unchanged)
✅ .claude/audits/ (created | unchanged) ✅ .claude/audits/ (created | unchanged)
[✅ .claude/rules/<name>.md] (per skeleton that matched: docker | testing | ci)
[✅ ROADMAP.md] (if generate_roadmap) [✅ ROADMAP.md] (if generate_roadmap)
PLACEHOLDERS : <null enrichment keys left as TODO(/onboard STEP 3), or none> PLACEHOLDERS : <null enrichment keys left as TODO(/onboard STEP 3), or none>
``` ```
@@ -167,6 +189,107 @@ PLACEHOLDERS : <null enrichment keys left as TODO(/onboard STEP 3), or none>
- A command the permission rules refuse is reported in your final message with the rule that stopped it, never rerun through a wrapper script, alias, env file, `make` target or another shell (a brief that orders the refused form is wrong: report it, do not comply). - A command the permission rules refuse is reported in your final message with the rule that stopped it, never rerun through a wrapper script, alias, env file, `make` target or another shell (a brief that orders the refused form is wrong: report it, do not comply).
- NO interview (handled upstream). - NO interview (handled upstream).
- NO audit (handled downstream by orchestrator). - NO audit (handled downstream by orchestrator).
- NO destructive writes: never overwrite CLAUDE.md if it exists without asking (print path + STOP, let orchestrator decide). - NO destructive writes: never overwrite CLAUDE.md if it exists without asking (print path + STOP, let orchestrator decide). MODE: split edits it by design, row by row, on the approved TABLE.
- Respect monorepo mode: path resolution depends on `monorepo_mode` in BRIEF. - Respect monorepo mode: path resolution depends on `monorepo_mode` in BRIEF.
- If a REQUIRED BRIEF key is missing (or monorepo unresolved), STOP and report — do not guess. Null OPTIONAL keys are normal on first dispatch: placeholder, don't stop. - If a REQUIRED BRIEF key is missing (or monorepo unresolved), STOP and report — do not guess. Null OPTIONAL keys are normal on first dispatch: placeholder, don't stop.
---
## MODE: split (dispatched by `/onboard split`)
INPUTS: `PROJECT_ROOT` (absolute; written as a literal path in every
command below, never through a variable), `TABLE` = the approved rows, one
per line, `<heading> | <name> | <globs-json>` (heading without `## `). No
BRIEF; PHASES 1-6 do not run. `PR` below stands for
`bash ~/.claude/lib/project-rules.sh -C <PROJECT_ROOT>`.
S0 — PREFLIGHT (no write before every step passes):
1. `git -C <PROJECT_ROOT> status --porcelain` is empty, else STOP.
2. `PR check` is rc 0, else STOP with its culprit lines: a pre-existing
rule the oracle cannot parse (the one-line `paths: ["a", "b"]` form
only) is fixed by the user before any split.
3. Per row, by reading the row (never a shell test that embeds it):
`<name>` matches `[a-z0-9][a-z0-9-]*`; the heading has no `'`; every
glob is relative, with no `'`, no leading `/`, no `..`. A row that
fails → STOP with the row and the field.
4. Per row: `PR sections CLAUDE.md` lists `## <heading>` exactly once;
`<PROJECT_ROOT>/.claude/rules/<name>.md` does not exist; every glob of
`<globs-json>` passes `PR matches '<glob>'` (rc 0). Any failure → STOP
with the row and the reason.
5. gitignore, in this order:
a. `git -C <PROJECT_ROOT> check-ignore -q .claude/rules/probe.md`;
rc 1 → nothing to do, `GITIGNORE_TOUCHED` stays unset, go to S1.
b. rc 0 and `<PROJECT_ROOT>/.gitignore` does not exist → STOP: the
ignore comes from outside the repo (global excludes or
`.git/info/exclude`); the user decides.
c. Trailing-newline guard: `[ -n "$(tail -c1 <PROJECT_ROOT>/.gitignore)" ]
&& echo >> <PROJECT_ROOT>/.gitignore` (rc 1 when already
newline-terminated is fine).
d. Append the negation (portable, lands after any `.claude/*` line):
`printf '!.claude/rules/\n' >> <PROJECT_ROOT>/.gitignore`
e. Re-run `check-ignore`; still rc 0 → `git -C <PROJECT_ROOT> checkout
-- .gitignore`, then STOP: "ignore form cannot be negated (BDR-003:
use the `.claude/*` file form)".
f. Set `GITIGNORE_TOUCHED`: `.gitignore` enters the later `add`,
`checkout` and `commit` only then (a missing pathspec is a fatal
git error).
A STOP after 5.d reverts the gitignore line (5.e); nothing else was
written.
S1 — EXTRACT, per row (single quotes around the heading):
```bash
bash ~/.claude/lib/project-rules.sh -C <PROJECT_ROOT> extract CLAUDE.md '<heading>' .claude/rules/<name>.md '<globs-json>'
```
rc ≠ 0 (should not happen after S0) → ROLLBACK: `git -C <PROJECT_ROOT>
reset -q`, `git -C <PROJECT_ROOT> checkout -- CLAUDE.md` (plus
`.gitignore` when S0 appended to it), delete every
`.claude/rules/<name>.md` this run wrote (literal paths, one `rm` per
row), then STOP with the row and the lib's message.
S2 — POINTER. If CLAUDE.md has no `## Path-scoped rules` section, append:
```markdown
## Path-scoped rules
Project rules live in `.claude/rules/<name>.md` and load on Read of a file
matching their `paths:` (never at session start): <name>, <name>.
```
Else add the new names to its list (Edit tool, or `cat >> <PROJECT_ROOT>/CLAUDE.md`
with a heredoc; never Write the whole file: subtract-only). Then squeeze
the blank runs the extraction left, through a literal temp path:
`cat -s <PROJECT_ROOT>/CLAUDE.md > <PROJECT_ROOT>/CLAUDE.md.tmp && cat
<PROJECT_ROOT>/CLAUDE.md.tmp > <PROJECT_ROOT>/CLAUDE.md && rm
<PROJECT_ROOT>/CLAUDE.md.tmp`.
S3 — CHECK, COMMIT, VERIFY TRACKED.
```bash
bash ~/.claude/lib/project-rules.sh -C <PROJECT_ROOT> check
```
rc ≠ 0 → ROLLBACK as in S1, STOP with the culprit lines. rc 0 →
```bash
git -C <PROJECT_ROOT> add -- CLAUDE.md .claude/rules/<name>.md # one literal path per row, + .gitignore when GITIGNORE_TOUCHED
git -C <PROJECT_ROOT> commit -m "<message>"
```
Never `add` the directory: a
pre-existing rule that S0's negation made visible would ride along
unlisted.
`<message>` follows the project's commit convention (its CLAUDE.md commit
rules: allowed types and scopes); with none, `chore: split <k> CLAUDE.md
section(s) into .claude/rules/`. Commit rc ≠ 0 (a hook refused it, e.g.
the gitflow pre-commit on a protected branch, or gitleaks) → ROLLBACK as
in S1, STOP with the hook's output verbatim. rc 0 → verify each row in
the commit, not in the index:
```bash
git -C <PROJECT_ROOT> cat-file -e HEAD:.claude/rules/<name>.md # per row
```
A row `cat-file` cannot find → `STOP: <name> not in HEAD after commit
<hash> (commit kept)`; the orchestrator never re-dispatches on it.
OUTPUT:
```
SPLIT DONE: <k> rule(s) — <name>.md (<globs>), …
CLAUDE.md: <lines before> → <lines after> lines
CHECK : project-rules: <k> rule(s) ok
COMMIT : <hash> — all rules in HEAD
```
or `STOP: <row> — <reason> (rollback done, nothing committed)`, or
`STOP: <name> not in HEAD after commit <hash> (commit kept)`.
+19
View File
@@ -73,6 +73,25 @@ Empty structure only: imports + empty main/init. No logic.
`.dockerignore`: node_modules, .git, .env, dist/build/target, __pycache__. `.dockerignore`: node_modules, .git, .env, dist/build/target, __pycache__.
Add `COMPOSE_PROJECT_NAME=<slug>` to `.env.example`. Add `COMPOSE_PROJECT_NAME=<slug>` to `.env.example`.
## PHASE 3b — PATH-SCOPED RULES (born split)
After PHASE 3 wrote the files and BEFORE PHASE 4 installs dependencies
(installed packages must not match the globs). `<PROJECT_ROOT>` is the
project root PHASE 1 wrote `CLAUDE.md` into, as a literal absolute path
(`pwd` there; it is not an INPUT, the scaffold defines it). For each of
`docker`, `testing`, `ci`, one uniform loop:
```bash
bash ~/.claude/lib/project-rules.sh -C <PROJECT_ROOT> emit ~/.claude/templates/project-rules/<name>.md .claude/rules/<name>.md
```
rc 0 → fill its stubs from the DESIGN (image, compose services, test
layout, pipeline jobs), no placeholders left; rc 1 → nothing matched,
skipped (a plain scaffold yields `docker.md` when Docker is relevant, and
`testing.md` only when the stack scaffolds a test file). Then
`bash ~/.claude/lib/project-rules.sh -C <PROJECT_ROOT> check` prints
`N rule(s) ok`. The `.gitignore` negation `!.claude/rules/` comes from the
gitflow socle at STEP 5f (`gitflow init` reconciles it before the root
commit); do not add `.claude` lines to the stack `.gitignore` yourself.
--- ---
## PHASE 4 — INSTALL DEPS ## PHASE 4 — INSTALL DEPS
+1 -1
View File
@@ -73,7 +73,7 @@ check_symlink() {
check_symlink "CLAUDE.md" check_symlink "CLAUDE.md"
# check_symlink only asserts the canonical path lands inside $REPO — after a # check_symlink only asserts the canonical path lands inside $REPO — after a
# `git pull` without `link.sh`, ~/.claude/CLAUDE.md can still resolve inside # `git pull` without `link.sh`, ~/.claude/CLAUDE.md can still resolve inside
# $REPO but at the wrong file (the 29-line project CLAUDE.md instead of # $REPO but at the wrong file (the project CLAUDE.md instead of
# CLAUDE.global.md), passing green while the global doctrine is silently gone. # CLAUDE.global.md), passing green while the global doctrine is silently gone.
_claude_md_target=$(readlink "$HOME/.claude/CLAUDE.md" 2>/dev/null || true) _claude_md_target=$(readlink "$HOME/.claude/CLAUDE.md" 2>/dev/null || true)
if [ "$_claude_md_target" != "$REPO/CLAUDE.global.md" ]; then if [ "$_claude_md_target" != "$REPO/CLAUDE.global.md" ]; then
+19
View File
@@ -0,0 +1,19 @@
#!/usr/bin/env bash
# hooks/instructions-loaded.sh — InstructionsLoaded hook: one JSON line per
# instruction file the engine loads, into
# ~/.claude/logs/instructions-loaded.jsonl. The proof channel for
# path-scoped rules (BDR-125 phase 0): a rule that loaded shows
# `load_reason: path_glob_match`, the file that triggered it, and the
# session or sub-agent that loaded it. Never blocks, never prints to
# stdout (stdout reaches the model), exits 0 whatever happens. Rotates to
# <log>.1 above 5 MB. CLAUDE_INSTRUCTIONS_LOG overrides the path (tests).
log="${CLAUDE_INSTRUCTIONS_LOG:-$HOME/.claude/logs/instructions-loaded.jsonl}"
command -v jq >/dev/null 2>&1 || exit 0
mkdir -p "$(dirname "$log")" 2>/dev/null || exit 0
if [ -f "$log" ] && [ "$(wc -c < "$log")" -gt 5242880 ]; then
mv -f "$log" "$log.1" 2>/dev/null
fi
jq -c --arg ts "$(date -u +%FT%TZ)" '{ts: $ts, session_id, agent_id,
agent_type, cwd, file_path, memory_type, load_reason, globs,
trigger_file_path}' >> "$log" 2>/dev/null
exit 0
+1
View File
@@ -45,6 +45,7 @@ chk "develop exists" 'git rev-parse --verify -q refs/heads/develop >/dev/nul
chk "root commit on main" '[ -n "$(git rev-parse -q --verify main)" ]' chk "root commit on main" '[ -n "$(git rev-parse -q --verify main)" ]'
chk "gitignore created" '[ -f .gitignore ]' chk "gitignore created" '[ -f .gitignore ]'
chk "socle: !.claude/deploy/" 'grep -qxF "!.claude/deploy/" .gitignore' chk "socle: !.claude/deploy/" 'grep -qxF "!.claude/deploy/" .gitignore'
chk "socle: !.claude/rules/" 'grep -qxF "!.claude/rules/" .gitignore'
chk "socle: re-ignore PENDING" 'grep -qxF ".claude/deploy/PENDING.json" .gitignore' chk "socle: re-ignore PENDING" 'grep -qxF ".claude/deploy/PENDING.json" .gitignore'
chk "hook installed" '[ -x .githooks/pre-commit ] && [ "$(git config core.hooksPath)" = .githooks ]' chk "hook installed" '[ -x .githooks/pre-commit ] && [ "$(git config core.hooksPath)" = .githooks ]'
chk "tree CLEAN after init" '[ -z "$(git status --porcelain)" ]' chk "tree CLEAN after init" '[ -z "$(git status --porcelain)" ]'
+210
View File
@@ -0,0 +1,210 @@
#!/usr/bin/env bash
# lib/project-rules.sh — project-scope path rules (.claude/rules/<name>.md),
# BDR-125 phase 0. One deterministic oracle for the make-test suite, the
# /onboard split mode, the onboarder and the scaffolder. Every subcommand
# takes an optional leading `-C <dir>` (a dispatched agent's cwd is the
# session's, never the project's):
# check [rules-dir] every path rule parses and every glob matches ≥1
# path; rc 2 with the culprit named
# matches <glob> rc 0 + the first hits, rc 1 none
# sections <file> chars, line, heading per top-level ## section
# (a section ends at the next # or ## heading
# outside a fence)
# extract <file> <heading> <out> <globs-json> move one section to a rule
# emit <skeleton> <out> the rule with the matching globs only (rc 1
# when none matches, nothing written)
# Globs match the WORKING TREE (compgen -G with globstar and dotglob,
# no brace expansion: one glob per extension; a symlinked dir matches
# when the glob names it, globstar never descends into a symlink met
# under `**`;
# dotglob makes `*` match dotfiles, which the engine's matcher skips: a
# glob that only hits hidden paths passes here but never loads),
# dependency dirs excluded (unless the glob names one: `vendor/**` is a
# valid rule): the engine matches the path the model reads,
# tracked or not; a typo matches nothing either way. A frontmatter line
# `# static-check: skip` exempts a rule whose files only exist mid-run. A
# rule without frontmatter or without `paths:` is an always-on rule:
# reported, never failed. No `head` after a producer: an early reader
# gives the writer SIGPIPE (rc 141 under pipefail).
_RULES_DEPS='(^|/)(node_modules|\.venv|venv|vendor|target|dist|build|\.git)/'
_rules_frontmatter() { # <file> → frontmatter body on stdout, rc 1 if none
awk 'NR == 1 && $0 != "---" { exit 1 }
NR > 1 && $0 == "---" { found = 1; exit }
NR > 1 { print }
END { exit found ? 0 : 1 }' "$1"
}
# <frontmatter text> → one glob per line. rc 1: no paths: line (always-on);
# rc 2: a paths: value that is not a non-empty JSON array of strings.
_rules_globs() {
local line arr
line=$(printf '%s\n' "$1" | grep -E '^paths:') || return 1
arr=${line#paths:}
printf '%s' "$arr" \
| jq -e 'type == "array" and length > 0 and all(type == "string")' \
>/dev/null 2>&1 || return 2
printf '%s' "$arr" | jq -r '.[]'
}
_rules_hits() { # <glob> → matching paths outside dependency dirs, rc 1 none
case "$1" in # a glob that names a dependency dir is not filtered
node_modules/*|.venv/*|venv/*|vendor/*|target/*|dist/*|build/*|.git/*)
( shopt -s globstar dotglob; compgen -G "$1" ) 2>/dev/null; return ;;
esac
( shopt -s globstar dotglob; compgen -G "$1" ) 2>/dev/null \
| grep -Ev "$_RULES_DEPS"
}
_rules_matching() { # <globs, one per line> → JSON array of the matching ones
local g out=""
while IFS= read -r g; do
[ -n "$g" ] && _rules_hits "$g" >/dev/null && out="$out, \"$g\""
done <<< "$1"
[ -n "$out" ] || return 1
printf '[%s]\n' "${out#, }"
}
_rules_check_file() { # <rule.md> → rc 0 ok or always-on, rc 1 with culprits
local fm globs skip=0 g bad=0
fm=$(_rules_frontmatter "$1") \
|| { echo "$1: always-on (no frontmatter)"; return 0; }
globs=$(_rules_globs "$fm")
case $? in
1) echo "$1: always-on (no paths:)"; return 0 ;;
2) echo "$1: paths: must be one line:" \
"paths: [\"a\", \"b\"]"; return 1 ;;
esac
printf '%s\n' "$fm" | grep -qx '# static-check: skip' && skip=1
while IFS= read -r g; do
if [ "$skip" = 1 ]; then echo "$1: SKIP $g"; continue; fi
_rules_hits "$g" >/dev/null \
|| { echo "$1: glob matches nothing: $g"; bad=1; }
done <<< "$globs"
[ "$bad" = 0 ]
}
project_rules_check() { # [rules-dir] → rc 0 all ok, rc 2 with culprits named
local dir="${1:-.claude/rules}" f n=0 bad=0
[ -d "$dir" ] \
|| { echo "project-rules: 0 rule(s) ok ($dir absent)"; return 0; }
for f in "$dir"/*.md; do
[ -e "$f" ] || continue
n=$((n + 1))
_rules_check_file "$f" || bad=1
done
[ "$bad" = 0 ] || return 2
echo "project-rules: $n rule(s) ok"
}
project_rules_matches() { # <glob> → rc 0 + the first 3 hits, rc 1 none
# awk reads the pipe to its end: a `head` reader would SIGPIPE the
# producer on any glob with more than a pipe buffer of hits (rc 141).
_rules_hits "$1" | awk 'NR <= 3 { print } END { exit NR == 0 }' \
|| { echo "no match: $1" >&2; return 1; }
}
project_rules_sections() { # <file> → chars, line, heading per ## section
[ -f "$1" ] || { echo "project-rules: $1 not found" >&2; return 2; }
awk '
function flush() { if (h != "") printf "%d\t%d\t%s\n", c, l, h; h = "" }
/^```/ { fence = !fence }
/^# / && !fence { flush() }
/^## / && !fence { flush(); h = $0; l = NR; c = 0 }
h != "" { c += length($0) + 1 }
END { flush() }' "$1"
}
_rules_heading_count() { # <file> <heading> → fence-aware count of "## h"
awk -v h="## $2" '/^```/ { fence = !fence }
!fence && $0 == h { n++ }
END { print n + 0 }' "$1"
}
_rules_section_body() { # <file> <heading> → body, trailing ---/blank trimmed
awk -v h="## $2" '
/^```/ { fence = !fence }
!fence && $0 == h { on = 1; next }
!fence && on && (/^## / || /^# /) { exit }
on { buf[++n] = $0 }
END { while (n > 0 && (buf[n] == "" || buf[n] == "---")) n--
for (i = 1; i <= n; i++) print buf[i] }' "$1"
}
_rules_without_section() { # <file> <heading> → the file minus that section
awk -v h="## $2" '
/^```/ { fence = !fence }
!fence && $0 == h { skip = 1; next }
!fence && skip && (/^## / || /^# /) { skip = 0 }
!skip { print }' "$1"
}
_rules_globs_all_match() { # <globs-json> → rc 0 valid and every glob matches
local globs g
globs=$(_rules_globs "paths: $1") || {
echo "project-rules: globs must be a JSON array of strings: $1" >&2
return 1; }
while IFS= read -r g; do
_rules_hits "$g" >/dev/null \
|| { echo "project-rules: glob matches nothing: $g" >&2; return 1; }
done <<< "$globs"
}
project_rules_extract() { # <file> <heading> <out.md> <globs-json>
local src="$1" heading="$2" out="$3" globs="$4" tmp
[ "$(_rules_heading_count "$src" "$heading")" = 1 ] || {
echo "project-rules: heading must occur exactly once: ## $heading" >&2
return 2; }
[ -e "$out" ] && { echo "project-rules: $out exists" >&2; return 2; }
_rules_globs_all_match "$globs" || return 2
mkdir -p "$(dirname "$out")"
tmp=$(mktemp) || { echo "project-rules: no temp file" >&2; return 2; }
{ printf -- '---\npaths: %s\n---\n\n# %s\n' "$globs" "$heading"
_rules_section_body "$src" "$heading"; } > "$out"
if ! { _rules_without_section "$src" "$heading" > "$tmp" \
&& cat "$tmp" > "$src"; }; then
rm -f "$tmp" "$out"
echo "project-rules: $src not rewritten, $out removed" >&2
return 2
fi
rm -f "$tmp"
echo "project-rules: moved '## $heading' to $out"
}
project_rules_emit() { # <skeleton.md> <out.md> → the rule, matching globs only
local fm globs kept
fm=$(_rules_frontmatter "$1") \
|| { echo "project-rules: $1: no frontmatter" >&2; return 2; }
globs=$(_rules_globs "$fm") \
|| { echo "project-rules: $1: no valid paths: array" >&2; return 2; }
kept=$(_rules_matching "$globs") \
|| { echo "project-rules: $1: no glob matches, not emitted" >&2; return 1; }
[ -e "$2" ] && { echo "project-rules: $2 exists" >&2; return 2; }
mkdir -p "$(dirname "$2")"
{ printf -- '---\npaths: %s\n---\n' "$kept"
awk 'body { print } NR > 1 && $0 == "---" { body = 1 }' "$1"; } > "$2"
echo "project-rules: emitted $2 paths: $kept"
}
_project_rules_main() {
set -uo pipefail
if [ "${1:-}" = "-C" ]; then
cd "${2:?dir}" 2>/dev/null \
|| { echo "project-rules: no dir $2" >&2; return 2; }
shift 2
fi
case "${1:-}" in
check) project_rules_check "${2:-.claude/rules}" ;;
matches) project_rules_matches "${2:?glob}" ;;
sections) project_rules_sections "${2:?file}" ;;
extract) project_rules_extract "${2:?file}" "${3:?heading}" "${4:?out}" \
"${5:?globs-json}" ;;
emit) project_rules_emit "${2:?skeleton}" "${3:?out}" ;;
*) echo "usage: project-rules.sh [-C dir] check [rules-dir] | matches" \
"<glob> | sections <file> | extract <file> <heading> <out>" \
"<globs-json> | emit <skeleton> <out>" >&2; return 2 ;;
esac
}
if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then _project_rules_main "$@"; fi
+237
View File
@@ -0,0 +1,237 @@
#!/usr/bin/env bash
# lib/tests/project-rules.test.sh — lib/project-rules.sh (check / matches /
# sections / extract / emit) and hooks/instructions-loaded.sh. Flip-tests
# on fixtures first (LRN-096), then the real check on this repo's rules.
set -u
ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
pass=0; fail=0
check() { if [ "$2" = "$3" ]; then pass=$((pass+1)); else fail=$((fail+1));
printf 'FAIL %s: got[%s] want[%s]\n' "$1" "$2" "$3"; fi; }
PR="$ROOT/lib/project-rules.sh"
FIX=$(mktemp -d); trap 'rm -rf "$FIX"' EXIT
cd "$FIX" || exit 1
mkdir -p .claude/rules src node_modules/x
echo x > src/app.ts
echo n > node_modules/x/a.test.js
# T1 a good rule passes
printf -- '---\npaths: ["src/**"]\n---\n\n# Src\nbody\n' > .claude/rules/good.md
bash "$PR" check >/dev/null; check T1-good-rule-passes "$?" 0
# T2 an unmatched glob fails, culprit named (flip test)
printf -- '---\npaths: ["src/**", "nowhere/**"]\n---\n\n# Bad\n' > .claude/rules/bad.md
out=$(bash "$PR" check); rc=$?
check T2-unmatched-glob-fails "$rc" 2
check T2b-culprit-named \
"$(printf '%s\n' "$out" | grep -c 'bad.md: glob matches nothing: nowhere/\*\*')" 1
printf -- '---\npaths: ["src/app.tz"]\n---\n\n# Typo\n' > .claude/rules/bad.md
bash "$PR" check >/dev/null; check T2c-literal-typo-fails "$?" 2
printf -- '---\npaths: ["**/*.test.*"]\n---\n\n# Deps\n' > .claude/rules/bad.md
out=$(bash "$PR" check); rc=$?
check T2d-dep-dir-only-is-no-match "$rc" 2
check T2e-dep-dir-culprit \
"$(printf '%s\n' "$out" | grep -c 'bad.md: glob matches nothing: \*\*/\*.test.\*')" 1
rm .claude/rules/bad.md
# T3 no frontmatter / no paths: = always-on info; a malformed paths: fails
printf '# No front\nbody\n' > .claude/rules/nofm.md
out=$(bash "$PR" check); rc=$?
check T3-no-frontmatter-is-always-on "$rc" 0
check T3b-reported "$(printf '%s\n' "$out" | grep -c 'nofm.md: always-on (no frontmatter)')" 1
check T3c-counted "$(printf '%s\n' "$out" | grep -c '2 rule(s) ok')" 1
printf -- '---\ntitle: x\n---\n\n# No paths\n' > .claude/rules/nofm.md
out=$(bash "$PR" check); rc=$?
check T3d-no-paths-is-always-on "$rc" 0
check T3e-reported "$(printf '%s\n' "$out" | grep -c 'nofm.md: always-on (no paths:)')" 1
printf -- '---\npaths: src/**\n---\n\n# Malformed\n' > .claude/rules/nofm.md
out=$(bash "$PR" check); rc=$?
check T3f-malformed-paths-fails "$rc" 2
check T3g-named \
"$(printf '%s\n' "$out" | grep -c 'nofm.md: paths: must be one line')" 1
rm .claude/rules/nofm.md
# T4 the skip marker passes an unmatched glob, and only in its own file
printf -- '---\npaths: ["nowhere/**"]\n# static-check: skip\n---\n\n# T\n' \
> .claude/rules/skip.md
out=$(bash "$PR" check); rc=$?
check T4-skip-marker-passes "$rc" 0
check T4b-skip-printed "$(printf '%s\n' "$out" | grep -c 'skip.md: SKIP nowhere/\*\*')" 1
printf -- '---\npaths: ["nowhere2/**"]\n---\n\n# U\n' > .claude/rules/other.md
bash "$PR" check >/dev/null; check T4c-skip-is-per-file "$?" 2
rm .claude/rules/skip.md .claude/rules/other.md
# T5 an absent dir is not an error; -C runs from elsewhere
rm -rf .claude/rules
out=$(bash "$PR" check); check T5-absent-dir-ok "$?" 0
check T5b-zero-rules "$(printf '%s' "$out" | grep -c '0 rule(s) ok')" 1
mkdir -p .claude/rules
printf -- '---\npaths: ["src/**"]\n---\n\n# Src\n' > .claude/rules/good.md
out=$(cd / && bash "$PR" -C "$FIX" check); rc=$?
check T5c-dash-C-rc "$rc" 0
check T5d-dash-C-counted "$(printf '%s' "$out" | grep -c '1 rule(s) ok')" 1
bash "$PR" -C /nonexistent-dir check 2>/dev/null; check T5e-dash-C-bad-dir "$?" 2
# T5f matches: hits on stdout, rc 1 and stderr line when none
out=$(bash "$PR" matches 'src/**'); rc=$?
check T5f-matches-rc "$rc" 0
check T5g-matches-hit "$(printf '%s\n' "$out" | grep -c '^src/app.ts$')" 1
err=$(bash "$PR" matches 'nope/**' 2>&1 >/dev/null); rc=$?
check T5h-no-match-rc "$rc" 1
check T5i-no-match-stderr "$err" 'no match: nope/**'
bash "$PR" matches '**/*.test.*' >/dev/null 2>&1; check T5j-dep-only-no-match "$?" 1
# T5k a glob with more than a pipe buffer of hits is still a match (no
# SIGPIPE from an early reader); T5m braces are not expanded by compgen
mkdir -p many
seq -f 'many/file-%04.0f-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' 1 3000 \
| xargs touch
bash "$PR" matches 'many/**' >/dev/null; check T5k-many-hits-rc "$?" 0
check T5l-three-lines "$(bash "$PR" matches 'many/**' | wc -l | tr -d ' ')" 3
bash "$PR" matches 'src/**/*.{ts,tz}' >/dev/null 2>&1
check T5m-brace-glob-no-match "$?" 1
# T5n a glob that names a dependency dir is a match (vendored area rule)
mkdir -p vendor/lib && echo v > vendor/lib/a.js
bash "$PR" matches 'vendor/**' >/dev/null; check T5n-named-dep-dir-rc "$?" 0
bash "$PR" matches '**/a.js' >/dev/null 2>&1
check T5o-unnamed-dep-dir-still-filtered "$?" 1
# T6 sections lists headings with sizes, fence-aware
cat > CLAUDE.md <<'EOF'
# Proj
## Alpha
aaa
---
## Beta
```
## not a heading
```
bbb
## Gamma
g1
## Gamma
g2
EOF
out=$(bash "$PR" sections CLAUDE.md)
check T6-four-sections "$(printf '%s\n' "$out" | wc -l | tr -d ' ')" 4
check T6b-beta-line "$(printf '%s\n' "$out" | awk -F'\t' '$3=="## Beta"{print $2}')" 8
check T6c-alpha-chars "$(printf '%s\n' "$out" | awk -F'\t' '$3=="## Alpha"{print $1}')" 19
check T6d-fenced-not-listed "$(printf '%s\n' "$out" | grep -c 'not a heading')" 0
cp CLAUDE.md "$FIX/orig.md"
# T7 extract moves the section, writes the frontmatter, demotes the title
bash "$PR" extract CLAUDE.md 'Alpha' .claude/rules/alpha.md '["src/**"]' >/dev/null
check T7-extract-rc "$?" 0
check T7b-rule-frontmatter "$(sed -n '2p' .claude/rules/alpha.md)" 'paths: ["src/**"]'
check T7c-rule-title "$(sed -n '5p' .claude/rules/alpha.md)" '# Alpha'
check T7d-rule-body "$(sed -n '6p' .claude/rules/alpha.md)" 'aaa'
check T7e-trailing-sep-trimmed "$(tail -1 .claude/rules/alpha.md)" 'aaa'
check T7f-section-gone "$(grep -c '^## Alpha' CLAUDE.md)" 0
check T7g-beta-kept "$(grep -c '^## Beta' CLAUDE.md)" 1
check T7h-fenced-line-kept "$(grep -c '^## not a heading' CLAUDE.md)" 1
bash "$PR" check >/dev/null; check T7i-check-passes "$?" 0
# T7j subtract-only: one deletion hunk, removed = heading + body + separators
check T7j-one-hunk "$(diff "$FIX/orig.md" CLAUDE.md | grep -c '^[0-9]')" 1
check T7k-no-additions "$(diff "$FIX/orig.md" CLAUDE.md | grep -c '^> ')" 0
check T7l-removed-lines "$(diff "$FIX/orig.md" CLAUDE.md | grep '^< ' | cut -c3- | grep -vE '^(---)?$' | tr '\n' '|')" '## Alpha|aaa|'
# T8 extract refuses: missing heading, existing target, duplicate, fenced-only
bash "$PR" extract CLAUDE.md 'Alpha' .claude/rules/alpha2.md '["src/**"]' 2>/dev/null
check T8-missing-heading-rc "$?" 2
check T8b-nothing-written "$([ -e .claude/rules/alpha2.md ] && echo yes || echo no)" no
bash "$PR" extract CLAUDE.md 'Beta' .claude/rules/alpha.md '["src/**"]' 2>/dev/null
check T8c-existing-target-rc "$?" 2
check T8d-beta-still-there "$(grep -c '^## Beta' CLAUDE.md)" 1
bash "$PR" extract CLAUDE.md 'Gamma' .claude/rules/gamma.md '["src/**"]' 2>/dev/null
check T8e-duplicate-heading-rc "$?" 2
check T8e2-both-gammas-kept "$(grep -c '^## Gamma' CLAUDE.md)" 2
bash "$PR" extract CLAUDE.md 'not a heading' .claude/rules/nah.md '["src/**"]' 2>/dev/null
check T8f-fenced-only-rc "$?" 2
check T8g-nothing-written "$(cd .claude/rules && printf '%s ' *)" 'alpha.md good.md '
# T9 extract refuses malformed globs and a glob that matches nothing
bash "$PR" extract CLAUDE.md 'Beta' .claude/rules/beta.md 'src/**' 2>/dev/null
check T9-bad-globs-rc "$?" 2
bash "$PR" extract CLAUDE.md 'Beta' .claude/rules/beta.md '["nowhere/**"]' 2>/dev/null
check T9b-unmatched-glob-rc "$?" 2
check T9c-nothing-written "$([ -e .claude/rules/beta.md ] && echo yes || echo no)" no
check T9d-beta-still-there "$(grep -c '^## Beta' CLAUDE.md)" 1
# T9e a failed source rewrite is rc 2 and leaves no rule behind
TMPDIR=/nonexistent bash "$PR" extract CLAUDE.md 'Beta' .claude/rules/beta.md '["src/**"]' 2>/dev/null
check T9e-no-tmp-rc "$?" 2
check T9f-no-tmp-nothing-written "$([ -e .claude/rules/beta.md ] && echo yes || echo no)" no
check T9g-no-tmp-beta-still-there "$(grep -c '^## Beta' CLAUDE.md)" 1
chmod a-w CLAUDE.md
bash "$PR" extract CLAUDE.md 'Beta' .claude/rules/beta.md '["src/**"]' 2>/dev/null
check T9h-unwritable-src-rc "$?" 2
check T9i-unwritable-src-rule-removed "$([ -e .claude/rules/beta.md ] && echo yes || echo no)" no
chmod u+w CLAUDE.md
check T9j-unwritable-src-beta-still-there "$(grep -c '^## Beta' CLAUDE.md)" 1
# T9k a mid-file H1 ends the section (foreign CLAUDE.md with several parts)
mkdir -p "$FIX/h1/src" && cd "$FIX/h1" || exit 1
echo x > src/a.ts
printf '## A\naaa\n\n# Part Two\nintro\n\n## B\nbbb\n' > CLAUDE.md
check T9k-h1-ends-section "$(bash "$PR" sections CLAUDE.md | awk -F'\t' '$3=="## A"{print $1}')" 10
bash "$PR" extract CLAUDE.md 'A' .claude/rules/a.md '["src/**"]' >/dev/null
check T9l-h1-kept "$(grep -c '^# Part Two' CLAUDE.md)" 1
check T9m-h1-intro-kept "$(grep -c '^intro' CLAUDE.md)" 1
check T9n-rule-body-stops-at-h1 "$(tail -1 .claude/rules/a.md)" aaa
cd "$FIX" || exit 1
# T10 the hook appends one jq line, prints nothing, never fails
HOOK="$ROOT/hooks/instructions-loaded.sh"
LOG="$FIX/il.jsonl"
IN='{"hook_event_name":"InstructionsLoaded","session_id":"s1","agent_id":"a1","agent_type":"general-purpose","cwd":"/p","file_path":"/p/.claude/rules/x.md","memory_type":"Project","load_reason":"path_glob_match","globs":["src/**"],"trigger_file_path":"/p/src/a.ts"}'
out=$(printf '%s' "$IN" | CLAUDE_INSTRUCTIONS_LOG="$LOG" bash "$HOOK"); rc=$?
check T10-hook-rc "$rc" 0
check T10b-stdout-empty "$out" ""
check T10c-one-line "$(wc -l < "$LOG" | tr -d ' ')" 1
check T10d-reason-kept "$(jq -r '.load_reason' "$LOG")" path_glob_match
check T10e-ids-kept "$(jq -r '[.session_id, .agent_id, .globs[0]] | join(",")' "$LOG")" 's1,a1,src/**'
out=$(printf '%s' "$IN" | CLAUDE_INSTRUCTIONS_LOG=/proc/nowhere/il.jsonl bash "$HOOK"); rc=$?
check T10f-unwritable-log-rc0 "$rc" 0
check T10g-unwritable-log-stdout-empty "$out" ""
# "$BASH", not bash: a blank PATH applies to the command lookup too (rc 127); this proves the contract (rc 0, silent, nothing appended), not the jq guard
out=$(printf '%s' "$IN" \
| CLAUDE_INSTRUCTIONS_LOG="$LOG" PATH=/nonexistent "$BASH" "$HOOK"); rc=$?
check T10h-empty-path-rc0 "$rc" 0
check T10i-empty-path-stdout-empty "$out" ""
check T10j-empty-path-nothing-appended "$(wc -l < "$LOG" | tr -d ' ')" 1
head -c 5300000 /dev/zero | tr '\0' 'x' > "$LOG"
printf '%s' "$IN" | CLAUDE_INSTRUCTIONS_LOG="$LOG" bash "$HOOK"
check T10k-rotated "$([ -e "$LOG.1" ] && echo yes || echo no)" yes
check T10l-fresh-log-one-line "$(wc -l < "$LOG" | tr -d ' ')" 1
# T11 the real rules of this repo pass the check (4 rules, 1 skip-marked)
out=$(bash "$PR" -C "$ROOT" check); rc=$?
[ "$rc" -eq 0 ] || printf '%s\n' "$out"
check T11-repo-rules-pass "$rc" 0
check T11b-four-rules "$(printf '%s\n' "$out" | grep -c '4 rule(s) ok')" 1
check T11c-transient-skipped \
"$(printf '%s\n' "$out" | grep -c 'transient-artifacts.md: SKIP docs/superpowers/\*\*')" 1
# T12 skeletons: emit keeps the matching globs only, skips when none match
mkdir -p "$FIX/gen/tests" && cd "$FIX/gen" || exit 1
echo x > Dockerfile; echo y > tests/test_a.py
bash "$PR" emit "$ROOT/templates/project-rules/docker.md" .claude/rules/docker.md >/dev/null
check T12-docker-emitted "$?" 0
check T12b-docker-globs-pruned "$(sed -n '2p' .claude/rules/docker.md)" 'paths: ["Dockerfile*"]'
check T12c-docker-body-kept "$(grep -c '^# Docker' .claude/rules/docker.md)" 1
bash "$PR" emit "$ROOT/templates/project-rules/testing.md" .claude/rules/testing.md >/dev/null
check T12d-testing-emitted "$?" 0
check T12e-testing-globs-pruned "$(sed -n '2p' .claude/rules/testing.md)" 'paths: ["tests/**"]'
bash "$PR" emit "$ROOT/templates/project-rules/ci.md" .claude/rules/ci.md 2>/dev/null
check T12f-ci-not-emitted-rc "$?" 1
check T12g-ci-not-written "$([ -e .claude/rules/ci.md ] && echo yes || echo no)" no
bash "$PR" emit "$ROOT/templates/project-rules/docker.md" .claude/rules/docker.md 2>/dev/null
check T12h-existing-target-rc "$?" 2
bash "$PR" check >/dev/null; check T12i-emitted-rules-pass-check "$?" 0
cd "$FIX" || exit 1
echo "PASS=$pass FAIL=$fail"
[ "$fail" -eq 0 ]
+2 -1
View File
@@ -6,4 +6,5 @@ paths: ["rules/**"]
User-scope rules, deployed to `~/.claude/rules` by `link.sh`. User-scope rules, deployed to `~/.claude/rules` by `link.sh`.
Maintenance doctrine (what belongs here, lazy-load `paths:` semantics, Maintenance doctrine (what belongs here, lazy-load `paths:` semantics,
machine-owned files): see `CLAUDE.md` (project scope) at the repo root. machine-owned files): see `.claude/rules/rules-maintenance.md` in the
claude-config repo (project scope, loads on Read under `rules/`).
+11
View File
@@ -374,6 +374,17 @@
] ]
} }
], ],
"InstructionsLoaded": [
{
"hooks": [
{
"type": "command",
"command": "bash ~/.claude/hooks/instructions-loaded.sh",
"timeout": 5
}
]
}
],
"PreToolUse": [ "PreToolUse": [
{ {
"matcher": "Bash", "matcher": "Bash",
+110 -5
View File
@@ -1,8 +1,8 @@
--- ---
name: onboard name: onboard
effort: xhigh effort: xhigh
description: 'Use when bringing an existing repo into the claude-config framework — needs archetype detection, config install, full multi-axis audit (debt/SEO/GEO/UI-UX/perf/security/a11y/docs), and prioritized backlog. Multi-agent orchestrator. Do NOT use for repos created via /init-project. Triggers: "onboard", "onboard project", "audit existing repo", "setup existing project".' description: 'Use when bringing an existing repo into the claude-config framework — needs archetype detection, config install, full multi-axis audit (debt/SEO/GEO/UI-UX/perf/security/a11y/docs), and prioritized backlog. Multi-agent orchestrator. Default flow: do NOT use it for repos created via /init-project. Triggers: "onboard", "onboard project", "audit existing repo", "setup existing project". `split` mode (any repo): "onboard split", "split the project instructions", "découpe le fichier CLAUDE", "path-scoped rules".'
argument-hint: '[optional hints: "Python FastAPI" | "Next.js monorepo" | "force-archetype:wordpress"]' argument-hint: '[split | optional hints: "Python FastAPI" | "Next.js monorepo" | "force-archetype:wordpress"]'
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, Skill allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, Skill
--- ---
@@ -21,6 +21,13 @@ $ARGUMENTS
--- ---
## MODE DISPATCH
`$ARGUMENTS` whose first token is `split` → jump to § SPLIT MODE (end of
this file); STEP 0 to FINAL OUTPUT do not run. Anything else → the flow
below, unchanged.
---
## STEP 0 — PLUGIN CHECK + AUTO-ACTIVATE ## STEP 0 — PLUGIN CHECK + AUTO-ACTIVATE
Run `$HOME/.claude/lib/plugin-gate.md` with hint "onboarding existing project + $ARGUMENTS" (dispatch plugin-probe → checkpoint → dispatch plugin-advisor → gates in this loop, BDR-077). Run `$HOME/.claude/lib/plugin-gate.md` with hint "onboarding existing project + $ARGUMENTS" (dispatch plugin-probe → checkpoint → dispatch plugin-advisor → gates in this loop, BDR-077).
@@ -110,6 +117,7 @@ L'agent génère :
- `.claudeignore` - `.claudeignore`
- `.gitignore` (safety check) - `.gitignore` (safety check)
- `.claude/tasks/TODO.md`, `.claude/memory/{decisions,learnings,blockers,journal,evals}.md` - `.claude/tasks/TODO.md`, `.claude/memory/{decisions,learnings,blockers,journal,evals}.md`
- `.claude/rules/<name>.md` pour chaque squelette dont un glob matche (docker, testing, ci) — placeholders listés avec ceux du CLAUDE.md
- **Pas encore** `ROADMAP.md` (GSD multi-session : `gsd init` à la main, voir docs gsd-pi — cf. Next steps) - **Pas encore** `ROADMAP.md` (GSD multi-session : `gsd init` à la main, voir docs gsd-pi — cf. Next steps)
Si `CLAUDE.md` existe déjà : lire son contenu, ne PAS écraser — fusionner après STEP 3. Si `CLAUDE.md` existe déjà : lire son contenu, ne PAS écraser — fusionner après STEP 3.
@@ -198,7 +206,7 @@ Ne pas redemander ce qui est déjà dans :
Présenter toutes les questions en UN BLOC. Attendre les réponses. STOP. Présenter toutes les questions en UN BLOC. Attendre les réponses. STOP.
Après réponses : **mettre à jour le brouillon CLAUDE.md** avec les infos obtenues. Après réponses : **mettre à jour le brouillon CLAUDE.md** avec les infos obtenues, et les placeholders `<!-- TODO(/onboard STEP 3): … -->` des `.claude/rules/*.md` émis en PHASE 5b (Docker, tests, CI : leurs réponses vont dans la règle, pas dans CLAUDE.md).
--- ---
@@ -1034,11 +1042,11 @@ Pour démarrer : lire .claude/tasks/TODO.md, choisir une tâche P0, lancer le /s
--- ---
## RULES ## RULES
- NO skipping STEP 0, 1, 2 — ils sont obligatoires. - NO skipping STEP 0, 1, 2 — ils sont obligatoires (split mode runs its own steps, § SPLIT MODE).
- NO audit agressif : chaque subagent doit recevoir "AUDIT-ONLY, no file modifications". - NO audit agressif : chaque subagent doit recevoir "AUDIT-ONLY, no file modifications".
- STEP 1 doit proposer un override `force-archetype:<name>` si l'utilisateur sait déjà. - STEP 1 doit proposer un override `force-archetype:<name>` si l'utilisateur sait déjà.
- Monorepo : toujours demander le mode (A/B/C) avant STEP 2. - Monorepo : toujours demander le mode (A/B/C) avant STEP 2.
- Si `CLAUDE.md` existe : le lire, ne pas l'écraser sans fusion après STEP 3. - Si `CLAUDE.md` existe : le lire, ne pas l'écraser sans fusion après STEP 3 (default flow; split mode edits it on the approved table).
- STEP 3 : ne redemande jamais ce qui est déjà dans README ou manifests. - STEP 3 : ne redemande jamais ce qui est déjà dans README ou manifests.
- STEP 3.5 : si ctx7 absent + fast-libs, WARN mais ne bloque pas. - STEP 3.5 : si ctx7 absent + fast-libs, WARN mais ne bloque pas.
- STEP 4 : graphify proposé seulement si `graphify-gate.sh` imprime une ligne (≥ 200 fichiers code, pas de graphe — BDR-097) ; l'utilisateur décide, jamais de build sans oui explicite. - STEP 4 : graphify proposé seulement si `graphify-gate.sh` imprime une ligne (≥ 200 fichiers code, pas de graphe — BDR-097) ; l'utilisateur décide, jamais de build sans oui explicite.
@@ -1079,3 +1087,100 @@ NEXT STEPS :
3. GSD (multi-session) : `gsd init` à la main, voir docs gsd-pi 3. GSD (multi-session) : `gsd init` à la main, voir docs gsd-pi
4. .onboard-audit/ peut être supprimé (raw data consommée en synthèse) 4. .onboard-audit/ peut être supprimé (raw data consommée en synthèse)
``` ```
---
## SPLIT MODE — `/onboard split` (BDR-125 phase 0)
Move the path-bound sections of an existing project `CLAUDE.md` into
`.claude/rules/<name>.md` path rules (loaded on Read of a matching file),
so the always-on context of that project shrinks. Judgment here, writes by
the onboarder, `lib/project-rules.sh` as the only glob oracle. The MODEL
GATE above has run. `mcp__model-router__route(phase="plan")` first.
`<ROOT>` below is the project root as a literal absolute path.
S1 — PRECONDITIONS. `CLAUDE.md` at `<ROOT>`, else print `nothing to split —
run /onboard` and stop. `git -C <ROOT> status --porcelain` empty (whole
tree) and the current branch is `develop` (or `main` when no `develop`
exists), else stop and say why: the split branches off develop, and an
in-flight feature branch or dirty file would be classified on one version
and extracted on another. `.claude/rules/` already holding rules → `bash
~/.claude/lib/project-rules.sh -C <ROOT> check`; rc ≠ 0 → stop with the
culprit lines (the user fixes them first: the oracle reads the one-line
`paths: ["a", "b"]` form only); rc 0 → list them, continue (new rules add
to them).
S2 — BASELINE. `claude -p "/context"` from `<ROOT>` (refused → ask the user
to run `! claude -p "/context"`); note the `Memory files` total and the
project CLAUDE.md row.
S3 — BRANCH. `cd <ROOT> && bash ~/.claude/lib/gitflow.sh start chore
claude-md-split`. A project without gitflow (no `develop`):
`git -C <ROOT> switch -c chore/claude-md-split`, and say so. Everything
after this step reads the branched file.
S4 — CLASSIFY. `bash ~/.claude/lib/project-rules.sh -C <ROOT> sections
CLAUDE.md` lists every `##` section with its size. For each one decide:
- always-on: project overview, stack, build/test/lint commands, folder
structure, conventions that apply everywhere, exceptions to global rules,
workflow expectations, key dependencies, anything needed before a file is
read (how to run the project), even when it names a folder;
- path-scoped: one module or folder, Docker, migrations, CI, a tool's
gotchas, a vendored or machine-owned area. Propose `<name>` (kebab, the
section's subject) and globs (a folder → `dir/**`, a tool → its config
files; never a brace glob `*.{ts,tsx}`: one glob per extension, the
oracle does no brace expansion) and verify EVERY proposed glob with
`bash ~/.claude/lib/project-rules.sh -C <ROOT> matches '<glob>'` (rc 0)
before showing it. Row shape, checked before a row enters the TABLE: `<name>` matches
`[a-z0-9][a-z0-9-]*`; globs are relative, no `'`, no leading `/`, no
`..`, no `|`; the heading has no `'` and no `|` (the rows are
`|`-separated and the executor single-quotes both). A section that fails
is not split by this mode: say so, the user renames or re-globs first.
S5 — GATE (mandatory stop). Print the table, then end the turn:
```
SPLIT — <project> CLAUDE.md (<chars> chars, <n> sections) on chore/claude-md-split
| # | section | chars | verdict | rule file | paths |
| 1 | Stack | 420 | keep | | |
| 2 | Docker | 1,340 | move | docker.md | ["Dockerfile*", "docker-compose*"] |
...
Moves <k> sections, <m> chars (<p>% of the file). Approve, edit a row, or "keep everything".
```
"keep everything" ends the mode with no change (`bash
~/.claude/lib/gitflow.sh delete chore/claude-md-split`). An edited row's
globs are re-verified with `matches` before they enter the TABLE. The
approved rows are the TABLE handed to the onboarder, verbatim.
S6 — EXECUTE. `mcp__model-router__route(phase="orchestrate")` with the
dispatch: `Agent(subagent_type="onboarder")`, prompt = `MODE: split`,
`PROJECT_ROOT: <ROOT>`, `TABLE:` the approved rows, one per line as
`<heading> | <name> | <globs-json>` (LRN-126: every field crosses the
prompt). It pre-flights every row, then extracts, writes the pointer
section, secures the gitignore negation, runs `check`, commits (message
per the project's commit convention), and verifies every rule is in
`HEAD`. Two STOP shapes come back:
- `STOP: <row> — <reason> (rollback done, nothing committed)`: the tree is
back to the branch tip; fix the row, re-dispatch the WHOLE table.
- `STOP: <name> not in HEAD after commit <hash> (commit kept)`: never
re-dispatch (the headings are gone from CLAUDE.md); show the user the
hash and `git -C <ROOT> show --stat <hash>`, the user decides.
S7 — AFTER. `claude -p "/context"` again from `<ROOT>`; append to that
project's `.claude/memory/journal.md` under today's date: `CLAUDE.md
split: <k> sections → .claude/rules/ (<names>), always-on <before> →
<after>`. Tell the user the proof step: a fresh session in that project
that Reads one file per rule, then `jq -c 'select(.memory_type=="Project"
and (.file_path|contains("/.claude/rules/")))'
~/.claude/logs/instructions-loaded.jsonl | tail`. Never `finish`: the
merge is the user's signal.
FINAL OUTPUT:
```
SPLIT COMPLETE: <project>
RULES : <k> files under .claude/rules/ (<names>)
CLAUDE.md: <before chars> → <after chars>
CONTEXT : <before> → <after> (Memory files)
BRANCH : chore/claude-md-split (<hash>) — merge on your signal
PROOF : pending — fresh session + the jq filter above
```
+1
View File
@@ -18,6 +18,7 @@ Thumbs.db
!.claude/audits/ !.claude/audits/
!.claude/settings.json !.claude/settings.json
!.claude/deploy/ !.claude/deploy/
!.claude/rules/
# re-ignore transients inside the versioned subtrees (the PENDING.json trap) # re-ignore transients inside the versioned subtrees (the PENDING.json trap)
.claude/settings.local.json .claude/settings.local.json
.claude/agent-memory/ .claude/agent-memory/
+1
View File
@@ -2,6 +2,7 @@
# Generated by /init-project or /onboard. Single source of truth for Claude in this repo. # Generated by /init-project or /onboard. Single source of truth for Claude in this repo.
# Global rules: ~/.claude/CLAUDE.md — this file extends or overrides them. # Global rules: ~/.claude/CLAUDE.md — this file extends or overrides them.
# Path-scoped rules: .claude/rules/<name>.md (paths: frontmatter), loaded on Read of a matching file.
--- ---
+10
View File
@@ -0,0 +1,10 @@
---
paths: [".github/workflows/**", ".gitlab-ci.yml", ".circleci/**"]
---
# CI
<!-- Generated by /init-project or /onboard: loads on Read of a pipeline file. -->
<!-- TODO(/onboard STEP 3): jobs — lint, test, build, deploy; which run on PR vs main; required checks. -->
<!-- TODO(/onboard STEP 3): secrets — names only (never values), where they are set. -->
<!-- TODO(/onboard STEP 3): runtime versions pinned here must match the Stack section of CLAUDE.md. -->
+10
View File
@@ -0,0 +1,10 @@
---
paths: ["Dockerfile*", "docker-compose*", "compose*.y*ml", ".dockerignore"]
---
# Docker
<!-- Generated by /init-project or /onboard: loads on Read of a Docker file. -->
<!-- TODO(/onboard STEP 3): image — base image + version; multi-stage? what the final stage holds. -->
<!-- TODO(/onboard STEP 3): compose — services, volumes, ports, the env file it reads (.env, never a secret in the image). -->
<!-- TODO(/onboard STEP 3): commands — docker compose up --build / down -v, where they differ from the native run. -->
+10
View File
@@ -0,0 +1,10 @@
---
paths: ["tests/**", "test/**", "**/*.test.*", "**/*.spec.*", "**/conftest.py"]
---
# Testing conventions
<!-- Generated by /init-project or /onboard: loads on Read of a test file. -->
<!-- TODO(/onboard STEP 3): layout — where tests live, one file per module? naming (test_x.py / x.test.ts). -->
<!-- TODO(/onboard STEP 3): fixtures and factories — shared setup, what is mocked, what hits a real service. -->
<!-- TODO(/onboard STEP 3): rules — a bug fix ships its regression test; no sleep-based waits; coverage target if any. -->