From 9e116a48d7220335947b15dc553e00f6c84106c1 Mon Sep 17 00:00:00 2001 From: bchanot Date: Tue, 27 Oct 2026 13:24:19 +0100 Subject: [PATCH] chore: purge transient planning artifacts (BDR-065) --- .../plans/2026-10-26-claude-md-split.md | 1238 ----------------- .../2026-10-26-claude-md-split-design.md | 191 --- 2 files changed, 1429 deletions(-) delete mode 100644 docs/superpowers/plans/2026-10-26-claude-md-split.md delete mode 100644 docs/superpowers/specs/2026-10-26-claude-md-split-design.md diff --git a/docs/superpowers/plans/2026-10-26-claude-md-split.md b/docs/superpowers/plans/2026-10-26-claude-md-split.md deleted file mode 100644 index 8a13c93..0000000 --- a/docs/superpowers/plans/2026-10-26-claude-md-split.md +++ /dev/null @@ -1,1238 +0,0 @@ -# Phase 0 — split project CLAUDE.md into `.claude/rules/` — Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Move the four path-bound sections of this repo's project CLAUDE.md into `.claude/rules/.md` path rules, prove they load, and give every project the same lever (`/onboard split`, generators born split). - -**Architecture:** One bash lib (`lib/project-rules.sh`: `check`, `matches`, `sections`, `extract`, `emit`, all behind an optional `-C `) is the deterministic oracle for every consumer: the `make test` suite, this repo's own split, the onboarder in `MODE: split`, and the two generators. Judgment (which section is path-scoped, which globs) stays in the `/onboard split` main loop; writes are executed by the sonnet onboarder against an explicit project root. A permanent `InstructionsLoaded` hook logs every loaded instruction file (with session and agent ids) so a path-rule load is a grep, not a guess. - -**Tech Stack:** bash 5 (`compgen -G` with globstar/dotglob), awk, jq, shellcheck; markdown skills/agents; Claude Code path-scoped rules (`paths:` frontmatter) and the `InstructionsLoaded` classic hook. - -**Spec:** `docs/superpowers/specs/2026-10-26-claude-md-split-design.md` -**Contract:** `.claude/tasks/contracts/2026-10-26-claude-md-split-0042.md` -**Branch:** `feature/claude-md-split`, already started off develop (spec 2c8e4a2, plan r1 420448a). **Implement in place on this checkout, no worktree**: `~/.claude/{lib,agents,skills,hooks,settings.json}` are symlinks into this repo, and Tasks 6, 8 and 11 exercise the live links. - -Spec deltas, decided while planning (r2 after the three-lens challenge, r3 after the correctness confirmation): a `matches ` subcommand (the split mode's only glob oracle, so the skill never consults `git ls-files`); `emit ` (writes a skeleton with the matching globs only); `-C ` on every subcommand (a dispatched agent's cwd is the session's, never the project's); `extract` refuses a glob that matches nothing and a heading that does not occur exactly once; the hook also logs `session_id`, `agent_id`, `agent_type`, `globs` and rotates above 5 MB; the graphify rule drops `.graphify_version` (it lives under `skills/graphify/`, already covered); the onboarder's default-mode PHASE 4 is untouched (the gitignore socle reaches onboarded projects through STEP 2.6 `gitflow init`). r3: `matches` reads its whole pipe through awk (a `head` reader gives the writer SIGPIPE, rc 141 under `pipefail`, so any glob with more than a pipe buffer of hits read as "no match"); the no-jq hook test runs `"$BASH"` (a temporary `PATH=/nonexistent` makes `bash` itself unfindable, rc 127); the Task 8 dry run branches the scratch first (the global pre-commit hook blocks a CLAUDE.md commit on `develop`); the onboarder checks the commit rc, rolls back on failure and verifies `HEAD:` with `cat-file`; globs carry no braces (`compgen -G` does not expand them). - -Baseline, taken 2026-10-26 before any edit (`claude -p "/context"` at the repo root, CLAUDE.md unchanged): total 32.2k; Memory files 11.6k, of which project CLAUDE.md 2.1k; Skills 10k; Custom agents 2.6k; System prompt 4.4k; MCP instructions 2.2k. - -## Global Constraints - -- Our code (strict): max 25 logic lines per function, 80 chars per line, 5 params, 5 locals; `shellcheck *.sh hooks/*.sh lib/*.sh` clean; no `sed -i '` in any file (portability census scans `*.sh`; agent text follows the same rule). -- Subtract-only: section text moves verbatim; nothing deleted from CLAUDE.global.md / rules/; registries (`.claude/memory/*`) are never edited by a task (STEP 7 capitalize owns them). CLAUDE.md keeps its lines 1-3 HTML comment. -- Never write into `rules/` (user scope, every project) except the pointer fix in `rules/README.md`. -- `.gitignore` negations only work with the `.claude/*` file form (BDR-003); the negation line must come AFTER `.claude/*`. -- Hooks never print to stdout (stdout reaches the model) and never block. -- The doctrine-citers census (`lib/tests/doctrine-citers.test.sh`) flags any `CLAUDE.md` followed within 12 chars by a double quote in skills/agents/lib/rules/hooks: new text never writes `CLAUDE.md "…"`; headings in command templates are single-quoted. -- Commit on the feature branch only, one commit per task, message under 50 words, no attribution lines. -- Frontmatter shape is exactly `paths: ["glob", "glob"]` on one line (as `rules/a11y.md`). No brace glob (`*.{ts,tsx}`): `compgen -G` does no brace expansion, so one glob per extension. -- A pipeline whose reader may stop early (`head`, `grep -q`) gives the writer SIGPIPE; under `set -o pipefail` that is rc 141 on the whole pipeline. The lib never puts `head` after a producer: awk reads the pipe to its end. -- A temporary assignment `PATH=/nonexistent cmd` applies to the lookup of `cmd` itself: write `"$BASH"`, never `bash`, when the test blanks PATH. -- Commands with a shell variable in a path are denied by the permission rules in this repo: write literal paths in every Bash step; agent templates say `` and the executor substitutes the literal. -- Deferred, for the human gate: the pre-commit `.claude/**` exemption lets a rules-only commit land directly on develop/main `[deferred 2026-10-26]` (phase 2, guards, narrows it; split mode always branches first). - -## Review Focus - -1. A heading inside a fenced code block, or a duplicated heading, must never be moved: `sections` ignores fenced lines, `extract` refuses unless the fence-aware count is exactly 1 (T6, T8e, T8f in Task 1). -2. A literal glob (no `*?[`) that names a missing file must fail `check` and be pruned by `emit`: bash never expands a plain word, so the matcher uses `compgen -G` (T2c, T12b, T12f in Tasks 1 and 9). -3. A glob that matches only under `node_modules/`, `.venv/`, `vendor/`, `target/`, `dist/`, `build/` or `.git/` counts as no match (T2d in Task 1). -4. A dispatched onboarder must act on the project root it was given, never on the session cwd: every lib call carries `-C `, every git call `-C` (Task 8 asserts the scratch repo got the commit on its chore branch and this repo's status is unchanged). -6. A glob with thousands of hits (a real repo's `src/**`) must still be a match: `matches` reads the whole pipe (T5k, T5l in Task 1). -5. The hook must exit 0 and print nothing when `jq` is absent or the log dir is unwritable (T10f-T10h in Task 2). - ---- - -### Task 1: `lib/project-rules.sh` + its suite (check / matches / sections / extract) - -**Files:** -- Create: `lib/project-rules.sh` -- Create: `lib/tests/project-rules.test.sh` - -**Interfaces:** -- Produces: `bash lib/project-rules.sh [-C ] check [rules-dir]` (rc 0 + `project-rules: N rule(s) ok`; rc 2 + `: ` lines; `: SKIP ` for a skip-marked file; `: always-on (no frontmatter)` / `(no paths:)` as info); `matches ` (rc 0 + up to 3 hits, rc 1 + `no match: ` on stderr); `sections ` (`\t\t## ` per top-level section, fence-aware); `extract '' ''` (rc 0 moved; rc 2 heading count ≠ 1 / target exists / malformed globs / a glob matches nothing, nothing written). Task 9 adds `emit`. - -- [ ] **Step 1: Write the failing suite (T1-T9)** - -Create `lib/tests/project-rules.test.sh` (4-backtick fence: the heredoc inside holds a ``` line): - -````bash -#!/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: is not a JSON array of strings')" 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 - -# 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 - -# 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 - -# 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 - -echo "PASS=$pass FAIL=$fail" -[ "$fail" -eq 0 ] -```` - -(T6c: the Alpha section spans `## Alpha`, `aaa`, blank, `---`, blank; each line counts its length plus one newline: 9+4+1+4+1 = 19.) - -- [ ] **Step 2: Run the suite, verify it fails** - -Run: `bash lib/tests/project-rules.test.sh` -Expected: many `FAIL …` lines (the lib does not exist), last line `PASS=… FAIL=…` with FAIL above 40 (a few negative checks such as T6d, T8b, T9c pass with no lib), exit 1. - -- [ ] **Step 3: Write the lib** - -Create `lib/project-rules.sh`: - -```bash -#!/usr/bin/env bash -# lib/project-rules.sh — project-scope path rules (.claude/rules/.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 ` (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 rc 0 + the first hits, rc 1 none -# sections chars, line, heading per top-level ## section -# extract move one section to a rule -# emit 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, -# through symlinks, no brace expansion: one glob per extension), -# dependency dirs excluded: 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() { # → 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" -} - -# → 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() { # → matching paths outside dependency dirs, rc 1 none - ( shopt -s globstar dotglob; compgen -G "$1" ) 2>/dev/null \ - | grep -Ev "$_RULES_DEPS" -} - -_rules_matching() { # → 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() { # → 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: is not a JSON array of strings"; 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() { # → 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() { # → chars, line, heading per ## section - [ -f "$1" ] || { echo "project-rules: $1 not found" >&2; return 2; } - awk ' - /^```/ { fence = !fence } - /^## / && !fence { if (h != "") printf "%d\t%d\t%s\n", c, l, h - h = $0; l = NR; c = 0 } - h != "" { c += length($0) + 1 } - END { if (h != "") printf "%d\t%d\t%s\n", c, l, h }' "$1" -} - -_rules_heading_count() { # → fence-aware count of "## h" - awk -v h="## $2" '/^```/ { fence = !fence } - !fence && $0 == h { n++ } - END { print n + 0 }' "$1" -} - -_rules_section_body() { # → 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() { # → 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() { # → 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() { # - 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")" - { printf -- '---\npaths: %s\n---\n\n# %s\n' "$globs" "$heading" - _rules_section_body "$src" "$heading"; } > "$out" - tmp=$(mktemp) - _rules_without_section "$src" "$heading" > "$tmp" && cat "$tmp" > "$src" - rm -f "$tmp" - echo "project-rules: moved '## $heading' to $out" -} - -project_rules_emit() { # → 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" \ - " | sections | extract " \ - " | emit " >&2; return 2 ;; - esac -} - -if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then _project_rules_main "$@"; fi -``` - -- [ ] **Step 4: Run the suite, verify T1-T9 pass** - -Run: `bash lib/tests/project-rules.test.sh` -Expected: `PASS=… FAIL=0`, exit 0. - -- [ ] **Step 5: shellcheck, 80 columns, census, make test on the new suite** - -Run: `shellcheck lib/project-rules.sh lib/tests/project-rules.test.sh; awk 'length > 80 {print FILENAME": "FNR": "length}' lib/project-rules.sh; make test suite=lib/tests/project-rules.test.sh | tail -1; make test suite=lib/tests/doctrine-citers.test.sh | tail -1; make test suite=lib/tests/portability-census.test.sh | tail -1` -Expected: no shellcheck output, no awk output, `all suites green` three times. - -- [ ] **Step 6: Commit** - -```bash -git add lib/project-rules.sh lib/tests/project-rules.test.sh -git commit -m "feat(rules): lib/project-rules.sh check/matches/sections/extract + suite" -``` - ---- - -### Task 2: InstructionsLoaded proof hook - -**Files:** -- Create: `hooks/instructions-loaded.sh` -- Modify: `settings.json` (hooks block, after the `"SessionStart": [ … ],` block, before `"PreToolUse": [`) -- Modify: `lib/tests/project-rules.test.sh` (append T10 before the tally) - -**Interfaces:** -- Produces: one JSON line per loaded instruction file in `~/.claude/logs/instructions-loaded.jsonl` (`ts, session_id, agent_id, agent_type, cwd, file_path, memory_type, load_reason, globs, trigger_file_path`); `CLAUDE_INSTRUCTIONS_LOG=` overrides the log path (tests); the log rotates to `.1` above 5 MB. - -- [ ] **Step 1: Append the failing hook tests (T10) to the suite** - -Insert before the `echo "PASS=$pass FAIL=$fail"` line of `lib/tests/project-rules.test.sh`: - -```bash -# 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: the blank PATH applies to the command lookup too (rc 127) -out=$(printf '%s' "$IN" \ - | CLAUDE_INSTRUCTIONS_LOG="$LOG" PATH=/nonexistent "$BASH" "$HOOK"); rc=$? -check T10h-no-jq-rc0 "$rc" 0 -check T10i-no-jq-stdout-empty "$out" "" -check T10j-no-jq-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 -``` - -- [ ] **Step 2: Run the suite, verify T10 fails** - -Run: `bash lib/tests/project-rules.test.sh | tail -3` -Expected: `FAIL T10-hook-rc` (hook missing), exit 1. - -- [ ] **Step 3: Write the hook** - -Create `hooks/instructions-loaded.sh`: - -```bash -#!/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 -# .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 -``` - -- [ ] **Step 4: Register it in `settings.json`** - -In `settings.json`, after the `"SessionStart": [ … ],` block (the `],` that closes it, just before `"PreToolUse": [`), insert: - -```json - "InstructionsLoaded": [ - { - "hooks": [ - { - "type": "command", - "command": "bash ~/.claude/hooks/instructions-loaded.sh", - "timeout": 5 - } - ] - } - ], -``` - -Verify: `jq -r '.hooks.InstructionsLoaded[0].hooks[0].command' settings.json` prints `bash ~/.claude/hooks/instructions-loaded.sh`. - -- [ ] **Step 5: Run the suite, verify T10 passes** - -Run: `bash lib/tests/project-rules.test.sh | tail -1 && shellcheck hooks/instructions-loaded.sh && make test suite=lib/tests/curated-config-guard.test.sh | tail -1` -Expected: `FAIL=0`, no shellcheck output, `all suites green`. - -- [ ] **Step 6: Commit** - -```bash -git add hooks/instructions-loaded.sh settings.json lib/tests/project-rules.test.sh -git commit -m "feat(hooks): InstructionsLoaded logger, the proof channel for path rules" -``` - ---- - -### Task 3: gitignore negation, here and in the socle - -**Files:** -- Modify: `.gitignore:122-126` -- Modify: `templates/gitignore/standard.gitignore` (the `.claude/*` block) -- Modify: `lib/gitflow-test.sh:47` (one more socle assertion) - -- [ ] **Step 1: Add the failing socle assertion** - -In `lib/gitflow-test.sh`, after line 47 (`chk "socle: !.claude/deploy/" …`), add: - -```bash -chk "socle: !.claude/rules/" 'grep -qxF "!.claude/rules/" .gitignore' -``` - -- [ ] **Step 2: Run gitflow-test, verify the new assertion fails** - -Run: `make test suite=lib/gitflow-test.sh 2>&1 | grep -E 'rules|suite'` -Expected: `FAIL socle: !.claude/rules/ …` and `1 suite(s) red`. - -- [ ] **Step 3: Patch the socle and this repo's `.gitignore`** - -`templates/gitignore/standard.gitignore`: after the line `!.claude/deploy/` add the line `!.claude/rules/` (it stays after `.claude/*`; reconcile appends missing lines at the end of a project's file, which is after any existing `.claude/*`). - -`.gitignore`: add `!.claude/rules/` directly after `!.claude/settings.json` (line 126), so the block reads: - -``` -.claude/* -!.claude/tasks/ -!.claude/memory/ -!.claude/audits/ -!.claude/settings.json -!.claude/rules/ -``` - -- [ ] **Step 4: Verify** - -Run: `make test suite=lib/gitflow-test.sh 2>&1 | tail -1; git check-ignore -q .claude/rules/probe.md; echo "ignored-rc=$?"` -Expected: `all suites green`; `ignored-rc=1` (not ignored; `git check-ignore` needs no existing file). - -- [ ] **Step 5: Commit** - -```bash -git add .gitignore templates/gitignore/standard.gitignore lib/gitflow-test.sh -git commit -m "chore(gitignore): un-ignore .claude/rules/ here and in the gitflow socle" -``` - ---- - -### Task 4: split this repo's CLAUDE.md (dogfood `extract`) - -**Files:** -- Modify: `CLAUDE.md` (four sections leave, a pointer section arrives; lines 1-3 comment stays) -- Create: `.claude/rules/rules-maintenance.md`, `.claude/rules/graphify-vendored.md`, `.claude/rules/mods.md`, `.claude/rules/transient-artifacts.md` -- Modify: `lib/tests/project-rules.test.sh` (append T11 before the tally) - -**Interfaces:** -- Consumes: `lib/project-rules.sh extract` / `check` (Task 1). - -- [ ] **Step 1: Append the failing real-repo test (T11)** - -Insert before the `echo "PASS=$pass FAIL=$fail"` line of `lib/tests/project-rules.test.sh`: - -```bash -# 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 -``` - -Run: `bash lib/tests/project-rules.test.sh | tail -4` -Expected: `FAIL T11b-four-rules: got[0] want[1]` (0 rules yet). - -- [ ] **Step 2: Move the four sections with `extract`** - -From the repo root, in this order (headings are exact, copied from CLAUDE.md; the transient rule is extracted with the one glob that matches mid-run, `docs/superpowers/**`, since `.audit/` does not exist at rest): - -```bash -bash lib/project-rules.sh extract CLAUDE.md 'rules/ maintenance' .claude/rules/rules-maintenance.md '["rules/**", "CLAUDE.global.md"]' -bash lib/project-rules.sh extract CLAUDE.md 'Machine-owned: the vendored graphify skill' .claude/rules/graphify-vendored.md '["skills/graphify/**", "install-plugins.sh"]' -bash lib/project-rules.sh extract CLAUDE.md 'mods/ — function-hooks plugins (Claude Code mods)' .claude/rules/mods.md '["mods/**", "skills/model-router/**", "lib/tests/mods.test.sh"]' -bash lib/project-rules.sh extract CLAUDE.md 'Transient planning artifacts' .claude/rules/transient-artifacts.md '["docs/superpowers/**"]' -``` - -Expected: four `project-rules: moved '## …' to .claude/rules/….md` lines. `git diff --stat CLAUDE.md` shows about 90 deletions and no insertion. - -- [ ] **Step 3: Transient rule: second glob + skip marker** - -Edit `.claude/rules/transient-artifacts.md` so its frontmatter reads exactly: - -``` ---- -paths: ["docs/superpowers/**", ".audit/**"] -# static-check: skip ---- -``` - -- [ ] **Step 4: The pointer section in CLAUDE.md** - -Append to CLAUDE.md: - -```markdown - -## Path-scoped rules -Project rules live in `.claude/rules/.md` and load on Read of a file -matching their `paths:` (never at session start): rules-maintenance, -graphify-vendored, mods, transient-artifacts. Check: `bash -lib/project-rules.sh check` (runs in `make test`). -``` - -The whole file must then read (lines 1-3 are the existing comment, untouched): - -```markdown - - -# claude-config — project instructions - -## Health Stack -- shell: `shellcheck *.sh hooks/*.sh lib/*.sh` - -## Path-scoped rules -Project rules live in `.claude/rules/.md` and load on Read of a file -matching their `paths:` (never at session start): rules-maintenance, -graphify-vendored, mods, transient-artifacts. Check: `bash -lib/project-rules.sh check` (runs in `make test`). -``` - -(Remove any run of more than one blank line left by the extraction.) - -- [ ] **Step 5: Verify** - -Run: `bash lib/project-rules.sh check; bash lib/tests/project-rules.test.sh | tail -1; git status --short --untracked-files=all .claude/rules CLAUDE.md; git diff HEAD --stat -- CLAUDE.md; wc -c .claude/rules/*.md` -Expected: `transient-artifacts.md: SKIP docs/superpowers/**`, `… SKIP .audit/**`, `project-rules: 4 rule(s) ok`; `FAIL=0`; four `??` entries under `.claude/rules/` (`--untracked-files=all`, else git collapses the new dir into one line) plus ` M CLAUDE.md`; the four rule files sum to roughly the 4,960 chars the sections held (T7 proves `extract` is verbatim; the sizes are the sanity check). - -- [ ] **Step 6: Commit** - -```bash -git add CLAUDE.md .claude/rules lib/tests/project-rules.test.sh -git commit -m "refactor(claude-md): four sections become .claude/rules path rules (phase 0)" -``` - ---- - -### Task 5: citers of the moved sections - -**Files:** -- Modify: `rules/README.md:8-9` -- Modify: `doctor.sh:76` - -- [ ] **Step 1: Repoint `rules/README.md`** - -Replace lines 8-9: - -``` -Maintenance doctrine (what belongs here, lazy-load `paths:` semantics, -machine-owned files): see `CLAUDE.md` (project scope) at the repo root. -``` - -with: - -``` -Maintenance doctrine (what belongs here, lazy-load `paths:` semantics, -machine-owned files): see `.claude/rules/rules-maintenance.md` in the -claude-config repo (project scope, loads on Read under `rules/`). -``` - -Line 7 (`User-scope rules, deployed to …`) stays. - -- [ ] **Step 2: Fix the stale doctor comment** - -`doctor.sh:76`: replace `(the 29-line project CLAUDE.md instead of` with `(the project CLAUDE.md instead of`. - -- [ ] **Step 3: Census grep** - -Run: -```bash -grep -rnE 'CLAUDE\.md`? \(project scope\)|29-line project CLAUDE\.md|Machine-owned: the vendored|§ ?Transient planning|"rules/ maintenance"|"mods/ — function-hooks"' rules/ doctor.sh skills/ agents/ lib/ hooks/ README.md ARCHITECTURE.md --include='*.md' --include='*.sh' | grep -v 'skills-external\|skills/graphify/\|lib/tests/project-rules' -``` -Expected: no output. (The optional backtick matches the README's `` `CLAUDE.md` (project scope) `` form: on today's tree, before Step 1, this grep returns rules/README.md:9 and doctor.sh:76; after Steps 1-2 nothing.) (`lib/gitflow.sh:21` mentions transient planning artifacts in a comment about the purge, not as a citation: leave it. `install-plugins.sh` GUARDED_CONFIGS keeps `CLAUDE.md`: leave it. `ARCHITECTURE.md` is the doc pipeline's, STEP 8.) - -- [ ] **Step 4: make test + commit** - -Run: `make test suite=lib/tests/doctrine-citers.test.sh | tail -1` -Expected: `all suites green`. - -```bash -git add rules/README.md doctor.sh -git commit -m "chore(citers): rules/README and doctor point at .claude/rules after the split" -``` - ---- - -### Task 6: `/onboard split` RED pressure test (orchestrator dispatch, no code) - -**Files:** none modified. Scratch: `/tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/split-red/` (a git repo on branch `develop` holding `CLAUDE.md` = `git show develop:CLAUDE.md`, plus `rules/x.md`, `mods/m/plugin.json`, `.gitignore` with `.claude/*`). - -- [ ] **Step 1: Assert in-place links, build the scratch repo** - -Run (one line, literal paths): `readlink -f ~/.claude/lib ~/.claude/skills ~/.claude/agents ~/.claude/hooks ~/.claude/settings.json` → every line under `/home/bchanot/Documents/claude/`. - -```bash -mkdir -p /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/split-red/rules /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/split-red/mods/m && git show develop:CLAUDE.md > /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/split-red/CLAUDE.md && echo r > /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/split-red/rules/x.md && echo '{}' > /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/split-red/mods/m/plugin.json && printf '.claude/*\n!.claude/memory/\n' > /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/split-red/.gitignore && git -C /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/split-red init -q -b develop && git -C /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/split-red add -A && git -C /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/split-red commit -qm init -``` - -- [ ] **Step 2: Dispatch the RED probe (sonnet)** - -`Agent(subagent_type="general-purpose", model="sonnet", effort="medium")` with: "Probe of a skill's text, not a real run. Read `/home/bchanot/.claude/skills/onboard/SKILL.md` as if you had been invoked as `/onboard split` in the project ``. Treat the MODEL GATE as passed and never call `mcp__model-router__route`; do not dispatch agents, do not run `claude`, do not write outside the scratch. Follow the skill's text for what it tells you to do first, up to the first point where it would stop for the user or dispatch an agent, then stop. Report: the steps you ran in order, whether any step had you classify the CLAUDE.md sections into path-scoped rules, and what you would have shown the user." - -Expected (RED): the report names the plugin check / archetype detection; no classification table, no `.claude/rules/` written. Record one line for the Task 7 commit message ("RED: current skill runs archetype detection on `split`"). - -If the probe DOES produce a split with the current skill: stop, the mode is unnecessary as designed; re-plan. - ---- - -### Task 7: `/onboard split` mode + onboarder `MODE: split` - -**Files:** -- Modify: `skills/onboard/SKILL.md` (frontmatter lines 4-5, after `## REQUEST` ~line 20, STEP 3 draft-update line ~201, RULES lines ~1037 and ~1041, append § SPLIT MODE after FINAL OUTPUT) -- Modify: `agents/onboarder.md` (after `## ROLE`; RULES line 170; a new section at the end) - -**Interfaces:** -- Consumes: `project-rules.sh -C sections|matches|extract|check` (Task 1). -- Produces: the onboarder `MODE: split` contract: INPUTS `PROJECT_ROOT`, `TABLE` rows ` | | `; OUTPUT rules written, check result, commit hash, or `STOP: — ` with the rollback done. - -- [ ] **Step 1: Skill frontmatter** - -Line 4 `description:` — replace `Do NOT use for repos created via /init-project.` with `Default flow: do NOT use it for repos created via /init-project.` and append inside the quoted string, before the closing `'`: ` `split` mode (any repo): "onboard split", "split the project instructions", "découpe le fichier CLAUDE", "path-scoped rules".` -Line 5: `argument-hint: '[split | optional hints: "Python FastAPI" | "Next.js monorepo" | "force-archetype:wordpress"]'` - -- [ ] **Step 2: MODE DISPATCH after `## REQUEST`** - -After the `$ARGUMENTS` line of `## REQUEST` and its `---`, insert: - -```markdown -## 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 3: STEP 3 draft update and the RULES lines** - -STEP 3 (~line 201): replace `Après réponses : **mettre à jour le brouillon CLAUDE.md** avec les infos obtenues.` with `Après réponses : **mettre à jour le brouillon CLAUDE.md** avec les infos obtenues, et les placeholders `` des `.claude/rules/*.md` émis en PHASE 5b (Docker, tests, CI : leurs réponses vont dans la règle, pas dans CLAUDE.md).` - -RULES: replace `- NO skipping STEP 0, 1, 2 — ils sont obligatoires.` with `- NO skipping STEP 0, 1, 2 — ils sont obligatoires (split mode runs its own steps, § SPLIT MODE).` and replace `- Si `CLAUDE.md` existe : le lire, ne pas l'écraser sans fusion après STEP 3.` with `- 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 4: § SPLIT MODE appended at the end of the skill** (4-backtick fence, inner ``` blocks are part of the text) - -````markdown - ---- - -## SPLIT MODE — `/onboard split` (BDR-125 phase 0) - -Move the path-bound sections of an existing project `CLAUDE.md` into -`.claude/rules/.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. -`` below is the project root as a literal absolute path. - -S1 — PRECONDITIONS. `CLAUDE.md` at ``, else print `nothing to split — -run /onboard` and stop. `git -C 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 → list -them, continue (new rules add to them). - -S2 — BASELINE. `claude -p "/context"` from `` (refused → ask the user -to run `! claude -p "/context"`); note the `Memory files` total and the -project CLAUDE.md row. - -S3 — BRANCH. `cd && bash ~/.claude/lib/gitflow.sh start chore -claude-md-split`. A project without gitflow (no `develop`): -`git -C 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 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 `` (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 matches ''` (rc 0) - before showing it. A heading containing `'` or `|` is not split by this - mode (say so; the user renames it first). - -S5 — GATE (mandatory stop). Print the table, then end the turn: - -``` -SPLIT — CLAUDE.md ( chars, 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 sections, chars (

% 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: `, `TABLE:` the approved rows, one per line as -` | | ` (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: — (rollback done, nothing committed)`: the tree is - back to the branch tip; fix the row, re-dispatch the WHOLE table. -- `STOP: not in HEAD after commit (commit kept)`: never - re-dispatch (the headings are gone from CLAUDE.md); show the user the - hash and `git -C show --stat `, the user decides. - -S7 — AFTER. `claude -p "/context"` again from ``; append to that -project's `.claude/memory/journal.md` under today's date: `CLAUDE.md -split: sections → .claude/rules/ (), always-on → -`. 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: -RULES : files under .claude/rules/ () -CLAUDE.md: → -CONTEXT : → (Memory files) -BRANCH : chore/claude-md-split () — merge on your signal -PROOF : pending — fresh session + the jq filter above -``` -```` - -- [ ] **Step 5: Onboarder: mode header, RULES exemption, `MODE: split` section** - -In `agents/onboarder.md`, insert right after the `## ROLE` paragraph (before the `---` that precedes `## INPUTS`): - -```markdown -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. -``` - -RULES line 170: replace `- NO destructive writes: never overwrite CLAUDE.md if it exists without asking (print path + STOP, let orchestrator decide).` with `- 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.` - -Append at the end of the file (4-backtick fence, inner ``` blocks are part of the text): - -````markdown - ---- - -## 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 without `## `). No -BRIEF; PHASES 1-6 do not run. `PR` below stands for -`bash ~/.claude/lib/project-rules.sh -C `. - -S0 — PREFLIGHT (no write before every row passes): -- `git -C status --porcelain` is empty, else STOP. -- gitignore: `git -C check-ignore -q .claude/rules/probe.md` - rc 0 means the rules would be ignored → append the negation (portable, - lands after any `.claude/*` line): - `printf '!.claude/rules/\n' >> /.gitignore` - then re-run `check-ignore`; still rc 0 → STOP: "ignore form cannot be - negated (BDR-003: use the `.claude/*` file form)", and `git -C - checkout -- .gitignore`. Remember whether this step - appended (`GITIGNORE_TOUCHED`): `.gitignore` enters the later `add`, - `checkout` and `commit` only then (a repo with no `.gitignore` is rc 1 - here and never names it: a missing pathspec is a fatal git error). -- per row: `PR sections CLAUDE.md` lists `## ` exactly once; - `/.claude/rules/.md` does not exist; every glob of - `` passes `PR matches ''` (rc 0). Any failure → STOP - with the row and the reason (nothing written yet besides the gitignore - line, which the STOP reverts). - -S1 — EXTRACT, per row (single quotes around the heading): -```bash -bash ~/.claude/lib/project-rules.sh -C extract CLAUDE.md '' .claude/rules/.md '' -``` -rc ≠ 0 (should not happen after S0) → ROLLBACK: `git -C -reset -q`, `git -C checkout -- CLAUDE.md` (plus -`.gitignore` when S0 appended to it), delete every -`.claude/rules/.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/.md` and load on Read of a file -matching their `paths:` (never at session start): , . -``` -Else add the new names to its list. Collapse runs of blank lines left by -the extraction (never more than one). - -S3 — CHECK, COMMIT, VERIFY TRACKED. -```bash -bash ~/.claude/lib/project-rules.sh -C check -``` -rc ≠ 0 → ROLLBACK as in S1, STOP with the culprit lines. rc 0 → -```bash -git -C add CLAUDE.md .claude/rules # + .gitignore when S0 appended -git -C commit -m "" -``` -`` follows the project's commit convention (its CLAUDE.md commit -rules: allowed types and scopes); with none, `chore: split 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 cat-file -e HEAD:.claude/rules/.md # per row -``` -A row `cat-file` cannot find → `STOP: not in HEAD after commit - (commit kept)`; the orchestrator never re-dispatches on it. - -OUTPUT: -``` -SPLIT DONE: rule(s) — .md (), … -CLAUDE.md: → lines -CHECK : project-rules: rule(s) ok -COMMIT : — all rules in HEAD -``` -or `STOP: — (rollback done, nothing committed)`, or -`STOP: not in HEAD after commit (commit kept)`. -```` - -- [ ] **Step 6: Locks still hold** - -Run: `for s in model-routing effort-routing loops-heavy plan-challenger security-auditor doctrine-citers portability-census; do make test suite=lib/tests/$s.test.sh | tail -1; done` -(If the loop form is refused by the permission rules, run the seven `make test suite=…` commands one by one.) -Expected: `all suites green` seven times. - -- [ ] **Step 7: Commit** - -```bash -git add skills/onboard/SKILL.md agents/onboarder.md -git commit -m "feat(onboard): split mode classifies CLAUDE.md sections, onboarder MODE: split executes (RED: current skill ran archetype detection on split)" -``` - ---- - -### Task 8: `/onboard split` GREEN pressure test (orchestrator dispatch, no code) - -- [ ] **Step 1: Fresh scratch repo `split-green/`** - -Same one-liner as Task 6 Step 1 with `split-red` replaced by `split-green` everywhere (no `git clean`: a fresh directory). - -- [ ] **Step 2: Dispatch the GREEN probe (sonnet, its own prompt)** - -`Agent(subagent_type="general-purpose", model="sonnet", effort="medium")` with: "Probe of a skill's text, not a real run. Read `/home/bchanot/.claude/skills/onboard/SKILL.md` as if you had been invoked as `/onboard split` in the project `` (a git repo on `develop`, clean). Treat the MODEL GATE as passed and never call `mcp__model-router__route`; treat S2 (the `claude -p` baseline) as done with the value 2.1k; do not dispatch agents; do not write anything, not even the branch (report the command you would run instead). Follow the skill's text up to the mandatory stop, then stop. Report: the steps you ran in order, the classification table you would print, and the exact `matches` commands you ran." - -Expected (GREEN): the report says it took MODE DISPATCH → § SPLIT MODE, ran S1, S3 (reported, not run), S4 with `matches` calls, and printed the S5 table (at least `rules/ maintenance` → move with `rules/**` and `Health Stack` → keep), then stopped. A probe that writes files, skips the gate, or runs archetype detection = not green: fix the skill text, re-run. - -- [ ] **Step 3: Executor dry run (onboarder, MODE: split) on the scratch** - -Before the dispatch, mirror the skill's S3 (the scratch is on `develop`, and the global `core.hooksPath` pre-commit blocks any commit there that stages a path outside `.claude/`): `git -C /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/split-green switch -c chore/claude-md-split`, and snapshot this repo: `git status --porcelain > /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/status-before.txt; git rev-parse HEAD`. - -Dispatch `Agent(subagent_type="onboarder")` with `MODE: split`, `PROJECT_ROOT: `, `TABLE:` two rows: `rules/ maintenance | rules-maintenance | ["rules/**"]` and `mods/ — function-hooks plugins (Claude Code mods) | mods | ["mods/**"]`. -Expected: `SPLIT DONE: 2 rule(s)` with `all rules in HEAD`; `git -C log --oneline -1 --decorate` shows the split commit on `chore/claude-md-split` (the post-commit push hook warns about the missing origin, never blocks); `.gitignore` there ends with `!.claude/rules/`; `bash lib/project-rules.sh -C check` prints `2 rule(s) ok`; and THIS repo is untouched: `git status --porcelain | diff - /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/status-before.txt` empty (the untracked contract file is in both) and `git rev-parse HEAD` unchanged. - -- [ ] **Step 4: Record** - -No commit. The orchestrator notes RED/GREEN outcomes for STEP 7 capitalize (EVAL entry). - ---- - -### Task 9: generators born split (skeletons, `emit`, onboarder PHASE 5b, scaffolder PHASE 3b) - -**Files:** -- Create: `templates/project-rules/docker.md`, `templates/project-rules/testing.md`, `templates/project-rules/ci.md` -- Modify: `templates/project-CLAUDE.md:4` (header comment) -- Modify: `agents/onboarder.md` (new PHASE 5b after PHASE 5) -- Modify: `agents/scaffolder.md` (new PHASE 3b between PHASE 3 and PHASE 4) -- Modify: `lib/tests/project-rules.test.sh` (append T12 before the tally) - -**Interfaces:** -- Consumes: `project-rules.sh emit ` (Task 1): rc 0 written with matching globs only, rc 1 none matched (nothing written), rc 2 malformed / target exists. - -- [ ] **Step 1: Append the failing skeleton tests (T12)** - -Insert before the tally line of the suite: - -```bash -# 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 -``` - -Run: `bash lib/tests/project-rules.test.sh | tail -3` -Expected: `FAIL T12-docker-emitted` (skeleton missing). - -- [ ] **Step 2: The three skeletons** - -`templates/project-rules/docker.md`: -```markdown ---- -paths: ["Dockerfile*", "docker-compose*", "compose*.y*ml", ".dockerignore"] ---- - -# Docker - - - - - -``` - -`templates/project-rules/testing.md`: -```markdown ---- -paths: ["tests/**", "test/**", "**/*.test.*", "**/*.spec.*", "**/conftest.py"] ---- - -# Testing conventions - - - - - -``` - -`templates/project-rules/ci.md`: -```markdown ---- -paths: [".github/workflows/**", ".gitlab-ci.yml", ".circleci/**"] ---- - -# CI - - - - - -``` - -`templates/project-CLAUDE.md` line 4: after `# Global rules: ~/.claude/CLAUDE.md — this file extends or overrides them.` add the line `# Path-scoped rules: .claude/rules/.md (paths: frontmatter), loaded on Read of a matching file.` - -- [ ] **Step 3: Onboarder PHASE 5b** - -In `agents/onboarder.md`, after the PHASE 5 block (after `**Do NOT overwrite existing content.**` and before the `---` that precedes PHASE 6), add (4-backtick fence, the inner ```bash block is part of the text): - -````markdown - -## PHASE 5b — PATH-SCOPED RULES (born split) - -For each of `docker`, `testing`, `ci`: -```bash -bash ~/.claude/lib/project-rules.sh -C emit ~/.claude/templates/project-rules/.md .claude/rules/.md -``` -- rc 0 → written with the globs that match this tree; its stub comments - are `` 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 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. -```` - -- [ ] **Step 4: Scaffolder PHASE 3b** - -In `agents/scaffolder.md`, after the PHASE 3 block (its last stack line, before the `---` that precedes `## PHASE 4`), add (4-backtick fence, the inner ```bash block is part of the text): - -````markdown - -## 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). `` 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 emit ~/.claude/templates/project-rules/.md .claude/rules/.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 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. -```` - -- [ ] **Step 5: Verify** - -Run: `bash lib/tests/project-rules.test.sh | tail -1; mkdir -p /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/gen-all/.github/workflows /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/gen-all/tests /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/gen-all/test /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/gen-all/.circleci && cd /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/gen-all && touch Dockerfile docker-compose.yml compose.yaml .dockerignore .gitlab-ci.yml tests/a test/b a.test.ts b.spec.ts conftest.py .github/workflows/ci.yml .circleci/config.yml && bash /home/bchanot/Documents/claude/lib/project-rules.sh check /home/bchanot/Documents/claude/templates/project-rules; make -C /home/bchanot/Documents/claude test suite=lib/tests/doctrine-citers.test.sh | tail -1` -Expected: `FAIL=0`; `project-rules: 3 rule(s) ok` (every skeleton glob is syntactically sound); `all suites green`. - -- [ ] **Step 6: Commit** - -```bash -git add templates/project-rules templates/project-CLAUDE.md agents/onboarder.md agents/scaffolder.md lib/tests/project-rules.test.sh -git commit -m "feat(generators): onboarder and scaffolder emit docker/testing/ci path rules from templates/project-rules" -``` - ---- - -### Task 10: TODO.md phase 0 bookkeeping + full suite - -**Files:** -- Modify: `.claude/tasks/TODO.md:20-30` (the phase 0 item) - -- [ ] **Step 1: Update the phase 0 item** - -Replace the `- [ ] **Phase 0, no mod: split project CLAUDE.md**` block (lines 20-30) with: - -```markdown -- [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

`) + 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. - - [ ] 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. - - [ ] User step: `claude mcp remove -s user higgsfield` (user-scope MCP, no toggle ownership, no doctor check; phase 5 `.mcp.json` owns it). - - [ ] Phase 2 folds: narrow the pre-commit `.claude/**` exemption so a rules-only commit cannot land on develop/main (deferred 2026-10-26). -- [ ] **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. -``` - -- [ ] **Step 2: Full suite + shellcheck** - -Run: `make test 2>&1 | tail -3 && shellcheck ./*.sh hooks/*.sh lib/*.sh && echo SHELLCHECK-OK` -Expected: `all suites green`, `SHELLCHECK-OK`. - -- [ ] **Step 3: Commit** - -```bash -git add .claude/tasks/TODO.md -git commit -m "chore(todo): phase 0 done in-repo, per-repo pass queued as phase 0b" -``` - ---- - -### Task 11: proof on this branch (orchestrator, no code) - -- [ ] **Step 1: `/context` after** - -Run from the repo root: `claude -p "/context" 2>/dev/null | grep -E 'Memory files|Documents/claude/CLAUDE.md'` -Expected: the project CLAUDE.md row well under the 2.1k baseline (about 200 tokens); Memory files total about 1.9k lower than 11.6k. Record both for the journal. - -- [ ] **Step 2: Main-session loads** - -The hook needs a session started AFTER Task 2 landed in `settings.json`. Note the start time, then run a headless session that reads one file per rule: `date -u +%FT%TZ; claude -p "Read rules/a11y.md, install-plugins.sh, mods/model-router/.claude-plugin/plugin.json and docs/superpowers/specs/2026-10-26-claude-md-split-design.md, then answer with the single word done." 2>/dev/null | tail -1`, then -`jq -c 'select(.memory_type=="Project" and (.file_path|contains("/.claude/rules/")) and .ts >= "") | {file_path, trigger_file_path, load_reason}' ~/.claude/logs/instructions-loaded.jsonl`. -Expected: exactly four lines with `load_reason: path_glob_match`, one per `.claude/rules/*.md`. Zero lines → the event does not fire as a classic hook on this CLI: report it, the proof falls back to `/context` inside the same `-p` session listing the rule under Memory files, and the finding goes to STEP 7 as a BLK. - -- [ ] **Step 3: Sub-agent loads** - -Note the time, then dispatch `Agent(subagent_type="general-purpose", model="sonnet", effort="low")`: "Read `rules/a11y.md` and `install-plugins.sh` in /home/bchanot/Documents/claude, then reply with the single word done." Then two filters: -1. Control, does the hook see sub-agent loads at all: `jq -c 'select(.agent_id != null and .ts >= "") | {agent_type, memory_type, file_path}' ~/.claude/logs/instructions-loaded.jsonl` (`agent_id` is optional in the hook input, "present only when the hook fires from within a subagent"). Zero lines → the event does not fire, or carries no `agent_id`, inside sub-agents: the sub-agent question is UNANSWERED (not "no"), record that, and the per-repo pass keeps sub-agent-needed sections always-on until a later probe answers it. -2. With at least one control line: `jq -c 'select(.agent_id != null and (.file_path|contains("/.claude/rules/")) and .ts >= "") | {agent_type, file_path, load_reason}' ~/.claude/logs/instructions-loaded.jsonl`. -Expected: two lines (rules-maintenance, graphify-vendored) with an `agent_id` → path rules load inside sub-agents. Zero lines with a non-empty control → they do not: record it (journal + STEP 7 LRN), and the per-repo pass keeps sub-agent-needed sections always-on; whether this repo's two hazards (graphify untrack-then-merge, mods `[ -L ]` guard) return as always-on one-liners is the user's call at the next gate. - ---- - -## Self-review - -- Spec coverage: §1 rules → Task 4; `.gitignore` + socle → Task 3; §2 check/sections/extract (+ matches, emit, -C) + suite → Task 1 (emit Task 9), hook + settings → Task 2, proof → Task 11; §3 skill + onboarder split + RED/GREEN → Tasks 6-8; §4 skeletons + generators + template header → Task 9; §5 citers → Task 5 (ARCHITECTURE.md is STEP 8's), TODO → Task 10, higgsfield user step → Task 10 TODO line + STEP 7 journal; §6 testing → every task's verify step + Task 10 Step 2; §7 pre-commit exemption → deferred, Task 10 TODO line. -- Placeholder scan: none. Every code step carries its content. -- Type consistency: `extract` arg order ` ` is the same in the lib, the suite, Task 4 and the onboarder S1; `emit ` the same in the lib, T12, PHASE 5b and PHASE 3b; `-C ` precedes the subcommand everywhere; the skip marker string `# static-check: skip` is identical in the lib grep, T4 and Task 4 Step 3; the `check` success line `project-rules: N rule(s) ok` is what T3c, T5b, T5d, T11b and the agents quote; the `matches` stderr line `no match: ` is what T5i expects; the onboarder's success line `all rules in HEAD` is what Task 8 Step 3 expects; the two STOP shapes in onboarder S3 are the two the skill's S6 handles. -- Review Focus: 1 → T6d/T8e/T8f, 2 → T2c/T12b/T12f, 3 → T2d/T5j, 4 → Task 8 Step 3 assertions, 5 → T10f-T10j, 6 → T5k/T5l. All pinned. -- r3 lint pass on the plan's own code: every line of the lib block is 80 columns or fewer (the four over-long r2 lines are wrapped, `_RULES_DEPS` renamed); the suite has no `ls` pipe (T8g uses `printf '%s ' *`); the lib has no `head` after a producer. diff --git a/docs/superpowers/specs/2026-10-26-claude-md-split-design.md b/docs/superpowers/specs/2026-10-26-claude-md-split-design.md deleted file mode 100644 index 39e9fd1..0000000 --- a/docs/superpowers/specs/2026-10-26-claude-md-split-design.md +++ /dev/null @@ -1,191 +0,0 @@ -# Phase 0 — split project CLAUDE.md into `.claude/rules/` (design) - -Date: 2026-10-26 · flow: /ship-feature · branch: feature/claude-md-split -Contract: `.claude/tasks/contracts/2026-10-26-claude-md-split-0042.md` -Parent: BDR-125 (context mod queue), TODO.md "Phase 0, no mod". - -## Intent - -The project CLAUDE.md of this repo (5,285 chars) loads in every session of -this repo; four of its five sections only matter when a matching file is -being read. Move those four into project-scope path rules -(`.claude/rules/.md` with `paths:` frontmatter), prove they load, and -give the other projects the same lever through a `/onboard split` mode and -generators that emit path rules from day one. No mod, subtract-only. - -Decided with the user (2026-10-26): this run covers this repo, the mode and -the generators; the per-repo pass over the six other repos runs after the -merge through the shipped `/onboard split`, one `chore/claude-md-split` -branch per repo, user approval per repo, never an automatic merge. The -InstructionsLoaded proof hook is permanent. The transient-artifacts rule -carries a `# static-check: skip` marker. The gitignore socle gains -`!.claude/rules/`. Generator skeleton set: docker, testing, ci. - -## 1. This repo's rules - -| Rule file | `paths:` | Source section (CLAUDE.md, verbatim) | -|---|---|---| -| `.claude/rules/rules-maintenance.md` | `rules/**`, `CLAUDE.global.md` | `## rules/ maintenance` | -| `.claude/rules/graphify-vendored.md` | `skills/graphify/**`, `install-plugins.sh`, `.graphify_version` | `## Machine-owned: the vendored graphify skill` | -| `.claude/rules/mods.md` | `mods/**`, `skills/model-router/**`, `lib/tests/mods.test.sh` | `## mods/ — function-hooks plugins (Claude Code mods)` | -| `.claude/rules/transient-artifacts.md` | `docs/superpowers/**`, `.audit/**` (+ `# static-check: skip`) | `## Transient planning artifacts` | - -Frontmatter shape = `rules/a11y.md`: `paths: ["glob", ...]` on one line. -The skip marker is a YAML comment line inside the frontmatter, invisible to -the engine. Body text moves verbatim; the title line becomes `#
`. CLAUDE.md keeps its header, `## Health Stack`, and a two-line -pointer: path-scoped rules live in `.claude/rules/` and load on Read of a -matching file; the four names listed. - -`.gitignore`: `!.claude/rules/` right after `.claude/*` (line 122). -`templates/gitignore/standard.gitignore`: same line after `.claude/*` -(order matters: a negation must follow the ignore it carves; reconcile -appends missing lines at the end, which is after any existing `.claude/*`). -`lib/gitflow-test.sh`: one `chk "socle: !.claude/rules/"` beside the -`!.claude/deploy/` assertion. - -## 2. Static check and proof hook - -`lib/project-rules.sh` (our code, strict limits, shellcheck): -- `check [dir]` (default `.claude/rules`): for each `*.md`: frontmatter - delimited by `---` present; a `paths:` line whose value is a JSON-style - array of double-quoted globs; each glob matches ≥1 path in the working - tree (`shopt -s globstar dotglob nullglob`, so the symlinked - `skills/model-router/**` and the gitignored `skills/graphify/SKILL.md` - count, and a typo matches nothing). A frontmatter line - `# static-check: skip` exempts that file's globs (printed as SKIP). Exit 0 - and `project-rules: N rule(s) ok` on success; exit 2 and one - `: ` line per failure. An empty or absent dir is exit 0 - with `0 rule(s)` (a project without rules is not an error). -- `sections `: prints `\t\t## ` per - top-level section, for the split-mode classification table. -- `extract "" `: writes - `` with the frontmatter and the section body (title demoted to - `#`), removes the section from CLAUDE.md. Deterministic, idempotent - failure (heading absent → exit 2, nothing written). Used by the onboarder - in MODE: split and by the per-repo pass. - -`lib/tests/project-rules.test.sh` (picked up by `make test` via the -`lib/tests/*.test.sh` glob): fixtures in `mktemp -d`: a good rule passes; -an unmatched glob fails with the culprit; a missing frontmatter fails; the -skip marker passes an unmatched glob; `sections` lists sizes; `extract` -round-trips (rule written, section gone, second call exit 2); then the real -check on this repo's `.claude/rules` (exit 0). PASS/FAIL tally like -`doctrine-citers.test.sh`. - -`hooks/instructions-loaded.sh`: reads the hook JSON on stdin, appends one -`jq -c` line `{ts, cwd, file_path, memory_type, load_reason, -trigger_file_path}` to `~/.claude/logs/instructions-loaded.jsonl` -(`mkdir -p`), always exits 0, never prints to stdout (a stdout line would -reach the model). Registered in `settings.json` under `"InstructionsLoaded"` -beside the other classic hooks. No hooks suite exists: the hook test lives -in `lib/tests/project-rules.test.sh` (fixture JSON on stdin, `HOME` pointed -at a temp dir, the appended line asserted, stdout asserted empty). - -Proof for this repo (recorded in the journal): `claude -p "/context"` on -develop BEFORE any edit (baseline, same measure as 2026-10-23), the same on -the branch after the split, one fresh interactive session that Reads one -matching file per rule, then `grep path_glob_match -~/.claude/logs/instructions-loaded.jsonl | tail -4` pasted. - -## 3. `/onboard split` - -`skills/onboard/SKILL.md`: right after the MODEL GATE, a MODE DISPATCH -paragraph: `$ARGUMENTS` starting with the token `split` → § SPLIT MODE; -anything else → the existing flow unchanged. The description gains the -trigger ("split CLAUDE.md", "découpe le CLAUDE.md"), the argument-hint gains -`split`, RULES line "NO skipping STEP 0, 1, 2" gains "(split mode runs its -own steps, § SPLIT MODE)". Routing rows, test locks (`model-routing`, -`effort-routing`, `loops-heavy`, `plan-challenger`, `security-auditor`) and -`routing.json:67` keep their anchors. - -§ SPLIT MODE (steps): -1. Precondition: `CLAUDE.md` at the project root, else print "nothing to - split, run /onboard" and stop. `git status --porcelain` clean on the - CLAUDE.md path, else stop (an in-flight edit would be lost). -2. Baseline: `claude -p "/context"` at the root; refused → the user runs - `! claude -p "/context"`; the always-on total is noted. -3. `bash ~/.claude/lib/project-rules.sh sections CLAUDE.md`; classify each - `##` section: always-on (overview, stack, build/test/lint commands, - conventions, workflow expectations, exceptions) or path-scoped (one - module, one folder, Docker, migrations, CI, a tool's gotchas); propose a - file name and globs from `git ls-files` for each path-scoped one, and - verify every proposed glob matches ≥1 tracked path before showing it. -4. Gate (prose table, per project): section · chars · keep / move → - `.md` · globs. The user edits or approves; "keep everything" is a - valid answer that ends the mode. -5. `bash ~/.claude/lib/gitflow.sh start chore claude-md-split` (a project - without gitflow: a plain branch, said so). -6. Dispatch `Agent(subagent_type="onboarder")` with `MODE: split`, the - project root, and the approved table verbatim (LRN-126: every field - crosses the prompt). It runs `extract` per row, writes the pointer lines - into CLAUDE.md, adds `!.claude/rules/` after `.claude/*` when that line - is present and the negation absent, runs `check`, commits - `chore(claude-md): split N sections into .claude/rules/`, reports. -7. After: `claude -p "/context"` again, the delta and the rule list go to - that project's `.claude/memory/journal.md`; the InstructionsLoaded proof - is the user's next session there (one Read per rule, grep the log). - Never `finish`: merge on the user's signal. - -Skill edit through /writing-skills: RED first (a sonnet subagent given the -CURRENT skill and a scratch repo holding a copy of this repo's pre-split -CLAUDE.md, asked to "/onboard split": it has no mode and runs or asks for -the full onboard), then the edit, then GREEN on the same scratch (the -subagent produces the classification table and stops at the gate). - -`agents/onboarder.md`: a `MODE:` header: absent → today's PHASES 1-5 -(generate config); `MODE: split` → the split executor above (PHASES -S1-S4: extract rows, pointer lines, gitignore negation, check + commit). -Stays sonnet, effort medium (BDR-077). - -## 4. Generators born split - -`templates/project-rules/` skeletons, each with `paths:` and 3-6 lines of -section stubs (HTML comments like the CLAUDE.md template): -- `docker.md`: `["Dockerfile*", "docker-compose*", "compose*.y*ml", ".dockerignore"]` -- `testing.md`: `["tests/**", "test/**", "**/*.test.*", "**/*.spec.*", "**/conftest.py"]` -- `ci.md`: `[".github/workflows/**", ".gitlab-ci.yml", ".circleci/**"]` - -onboarder (default mode) PHASE 1b and scaffolder PHASE 1b: for each -skeleton, emit `.claude/rules/.md` when ≥1 of its globs matches a -path in the project tree (onboarder: the real tree; scaffolder: the tree it -just scaffolded, so a Docker-relevant project gets `docker.md`), filled from -the BRIEF where known, else the template stubs. Then run `project-rules.sh -check` and report the emitted list. The onboarder's PHASE 4 gitignore check -also appends `!.claude/rules/` after an existing `.claude/*` line -(the socle covers gitflow-init projects; this covers the rest). The -scaffolder's `.gitignore` is reconciled by STEP 5f `gitflow init` before -the root commit, so the socle line lands first (LRN-066, BLK-010). -`templates/project-CLAUDE.md` keeps every section (commands stay always-on); -its header comment gains one line naming `.claude/rules/`. - -## 5. Cleanup and citers - -- `rules/README.md:9` → "see `.claude/rules/rules-maintenance.md` in the - claude-config repo". -- `doctor.sh:76` comment: "the project CLAUDE.md" (drop "29-line"). -- `ARCHITECTURE.md` tree gains `.claude/rules/` (doc pipeline, STEP 8). -- `install-plugins.sh` GUARDED_CONFIGS unchanged: `graphify claude install` - still rewrites CLAUDE.md and the trap still reverts it. -- `.claude/tasks/TODO.md`: phase 0 item updated (done parts, per-repo pass - queued as its own item with the repo order). -- Registries append-only: BDR-065 and LRN-154 keep their old location text. -- Manual step (user): `claude mcp remove -s user higgsfield`; journal line. - -## 6. Testing and proof - -- `make test` green (new suite + gitflow-test socle assertion + hook test). -- `shellcheck *.sh hooks/*.sh lib/*.sh` clean. -- `project-rules.sh check` exit 0 on this repo. -- `/context` before/after at the repo root; the four `path_glob_match` - log lines from one real session. -- RED → GREEN pressure test transcript summary for `/onboard split`. - -## 7. Out of scope, risks kept - -- The per-repo pass (six repos) and whether path rules load inside - sub-agents: measured on faunosteo first, during that pass. -- A `paths:` rule loads on Read, not on Write of a new file: generator - rules load once the scaffolded file is edited (Edit needs a Read). -- The pre-commit `.claude/**` exemption lets a rules-only commit land on - develop; split mode always branches first.