diff --git a/docs/superpowers/plans/2026-10-26-claude-md-split.md b/docs/superpowers/plans/2026-10-26-claude-md-split.md index ea8b280..10d7d4d 100644 --- a/docs/superpowers/plans/2026-10-26-claude-md-split.md +++ b/docs/superpowers/plans/2026-10-26-claude-md-split.md @@ -4,45 +4,49 @@ **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`, `sections`, `extract`, `emit`) 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. A permanent `InstructionsLoaded` hook logs every loaded instruction file so a path-rule load is a grep, not a guess. +**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 (globstar), awk, jq, shellcheck; markdown skills/agents; Claude Code path-scoped rules (`paths:` frontmatter) and the `InstructionsLoaded` classic hook. +**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 committed 2c8e4a2). +**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 delta, decided while planning: a fourth subcommand `emit ` (the spec's "emit only skeletons whose globs match" needs a per-glob prune the sonnet generators cannot do by hand; `emit` writes the rule with the matching globs only, so the strict "each glob matches" check still holds). +Spec deltas, decided while planning (r2, after the three-lens challenge): 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`). + +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. -- 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). -- Never write into `rules/` (user scope, every project) except the one pointer fix in `rules/README.md`. +- 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`). -- Commands with a shell variable in the path are denied by the permission rules in this repo: write literal paths in every Bash step. +- 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 in CLAUDE.md (` ```\n## x\n``` `) must not be read as a section by `sections`/`extract` (test T6 in Task 1). -2. `extract` on a heading that is absent, or onto a rule file that already exists, must write nothing and exit 2 (test T8 in Task 1). -3. A glob with a typo (`skils/**`) must fail `check` with the culprit named, and the skip marker must only silence globs of its own file (tests T2, T4 in Task 1). -4. `emit` on a project where only some globs of a skeleton match must keep exactly the matching ones; none matching → nothing written, rc 1 (test T12 in Task 7). -5. The hook must exit 0 and print nothing when `jq` is absent or the log dir is unwritable, so a broken log never reaches the model (test T10f in Task 2). +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 and this repo stayed clean). +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 / sections / extract) +### 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 check [dir]` (rc 0 + `project-rules: N rule(s) ok`; rc 2 + `: ` lines; `: SKIP ` lines for a skip-marked file); `sections ` (`\t\t## ` per top-level section); `extract "" ''` (rc 0 moved; rc 2 heading absent / target exists / malformed globs, nothing written). Functions are sourceable (`source lib/project-rules.sh`; main guarded by `BASH_SOURCE`). +- 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)** @@ -50,9 +54,9 @@ Create `lib/tests/project-rules.test.sh`: ```bash #!/usr/bin/env bash -# lib/tests/project-rules.test.sh — lib/project-rules.sh (check / sections / -# extract / emit) and hooks/instructions-loaded.sh. Flip-tests on fixtures -# first (LRN-096), then the real check on this repo's .claude/rules. +# 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 @@ -61,8 +65,9 @@ check() { if [ "$2" = "$3" ]; then pass=$((pass+1)); else fail=$((fail+1)); PR="$ROOT/lib/project-rules.sh" FIX=$(mktemp -d); trap 'rm -rf "$FIX"' EXIT cd "$FIX" || exit 1 -mkdir -p .claude/rules src +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 @@ -74,13 +79,30 @@ 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 missing frontmatter fails +# 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-missing-frontmatter-fails "$rc" 2 -check T3b-named "$(printf '%s\n' "$out" | grep -c 'nofm.md: no frontmatter')" 1 +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 @@ -93,11 +115,25 @@ 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 +# 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 # T6 sections lists headings with sizes, fence-aware cat > CLAUDE.md <<'EOF' @@ -113,14 +149,21 @@ aaa ## not a heading ``` bbb + +## Gamma +g1 + +## Gamma +g2 EOF out=$(bash "$PR" sections CLAUDE.md) -check T6-two-sections "$(printf '%s\n' "$out" | wc -l | tr -d ' ')" 2 +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 +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' @@ -131,18 +174,27 @@ 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 a missing heading and an existing target, writes nothing -bash "$PR" extract CLAUDE.md "Alpha" .claude/rules/alpha2.md '["src/**"]' 2>/dev/null +# 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 "$(ls .claude/rules | wc -l | tr -d ' ')" 1 -bash "$PR" extract CLAUDE.md "Beta" .claude/rules/alpha.md '["src/**"]' 2>/dev/null +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 "$(ls .claude/rules | tr '\n' ' ')" 'alpha.md good.md ' -# T9 extract refuses a malformed globs argument -bash "$PR" extract CLAUDE.md "Beta" .claude/rules/beta.md 'src/**' 2>/dev/null +# 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 -check T9b-nothing-written "$(ls .claude/rules/beta.md 2>/dev/null | wc -l | tr -d ' ')" 0 +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 ] @@ -163,17 +215,24 @@ Create `lib/project-rules.sh`: #!/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: -# check [dir] frontmatter parses, every glob matches ≥1 path (rc 2) -# sections "\t\t## " per top-level section +# /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 write the rule with the globs that match (rc 1 +# emit the rule with the matching globs only (rc 1 # when none matches, nothing written) -# Globs match the WORKING TREE (globstar, dotglob, through symlinks): 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 (docs/superpowers/**). -set -uo pipefail +# Globs match the WORKING TREE (compgen -G with globstar and dotglob, +# through symlinks), 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. + +_RULES_DEP_DIRS='(^|/)(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 } @@ -182,44 +241,50 @@ _rules_frontmatter() { # → frontmatter body on stdout, rc 1 if none END { exit found ? 0 : 1 }' "$1" } -_rules_globs() { # → one glob per line, rc 1 if no paths: - local line - line=$(printf '%s\n' "$1" | grep -E '^paths: *\[.*\] *$') || return 1 - printf '%s\n' "$line" | grep -oE '"[^"]+"' | tr -d '"' +# → 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_glob_matches() { # → rc 0 when ≥1 path exists in the tree - local -a hits - shopt -s globstar dotglob nullglob - # shellcheck disable=SC2206 # the glob MUST expand: that is the test - hits=( $1 ) - shopt -u globstar dotglob nullglob - [ "${#hits[@]}" -gt 0 ] +_rules_hits() { # → matching paths outside dependency dirs, rc 1 none + ( shopt -s globstar dotglob; compgen -G "$1" ) 2>/dev/null \ + | grep -Ev "$_RULES_DEP_DIRS" } _rules_matching() { # → JSON array of the matching ones local g out="" while IFS= read -r g; do - [ -n "$g" ] && _rules_glob_matches "$g" && out="$out, \"$g\"" + [ -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, rc 1 with the culprit lines +_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: no frontmatter"; return 1; } - globs=$(_rules_globs "$fm") || { echo "$1: no paths: array"; return 1; } + 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 - [ -n "$g" ] || continue if [ "$skip" = 1 ]; then echo "$1: SKIP $g"; continue; fi - _rules_glob_matches "$g" || { echo "$1: glob matches nothing: $g"; bad=1; } + _rules_hits "$g" >/dev/null || { echo "$1: glob matches nothing: $g"; bad=1; } done <<< "$globs" [ "$bad" = 0 ] } -project_rules_check() { # [dir] → rc 0 all ok, rc 2 with culprits named +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 @@ -231,7 +296,12 @@ project_rules_check() { # [dir] → rc 0 all ok, rc 2 with culprits named echo "project-rules: $n rule(s) ok" } -project_rules_sections() { # → "\t\t## " +project_rules_matches() { # → rc 0 + the first 3 hits, rc 1 none + _rules_hits "$1" | head -3 + [ "${PIPESTATUS[0]}" -eq 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 } @@ -241,6 +311,12 @@ project_rules_sections() { # → "\t\t## " 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 } @@ -259,20 +335,31 @@ _rules_without_section() { # → the file minus that section !skip { print }' "$1" } -project_rules_extract() { # +_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 - grep -qxF -- "## $heading" "$src" \ - || { echo "project-rules: heading not found: ## $heading" >&2; return 2; } + [ "$(_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 "paths: $globs" >/dev/null \ - || { echo "project-rules: globs must be a JSON array: $globs" >&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" + echo "project-rules: moved '## $heading' to $out" } project_rules_emit() { # → the rule, matching globs only @@ -280,7 +367,7 @@ project_rules_emit() { # → the rule, matching globs on fm=$(_rules_frontmatter "$1") \ || { echo "project-rules: $1: no frontmatter" >&2; return 2; } globs=$(_rules_globs "$fm") \ - || { echo "project-rules: $1: no paths: array" >&2; return 2; } + || { 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; } @@ -291,15 +378,21 @@ project_rules_emit() { # → the rule, matching globs on } _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}" ;; - sections) project_rules_sections "${2:?CLAUDE.md path}" ;; + 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 check [dir] | sections " \ - "| extract " \ - "| emit " >&2; return 2 ;; + *) echo "usage: project-rules.sh [-C dir] check [rules-dir] | matches" \ + " | sections | extract " \ + " | emit " >&2; return 2 ;; esac } @@ -309,18 +402,18 @@ 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=33 FAIL=0`, exit 0 (count may differ by one or two; the invariant is `FAIL=0`). +Expected: `PASS=… FAIL=0`, exit 0. -- [ ] **Step 5: shellcheck + make test on the new suite** +- [ ] **Step 5: shellcheck, 80 columns, census, make test on the new suite** -Run: `shellcheck lib/project-rules.sh lib/tests/project-rules.test.sh && make test suite=lib/tests/project-rules.test.sh` -Expected: no shellcheck output; `all suites green`. +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/sections/extract/emit + suite" +git commit -m "feat(rules): lib/project-rules.sh check/matches/sections/extract + suite" ``` --- @@ -329,11 +422,11 @@ git commit -m "feat(rules): lib/project-rules.sh check/sections/extract/emit + s **Files:** - Create: `hooks/instructions-loaded.sh` -- Modify: `settings.json` (hooks block, after `"SessionStart": [...]`, line ~374) +- 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, cwd, file_path, memory_type, load_reason, trigger_file_path`); `CLAUDE_INSTRUCTIONS_LOG=` overrides the log path (tests). +- 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** @@ -343,21 +436,29 @@ Insert before the `echo "PASS=$pass FAIL=$fail"` line of `lib/tests/project-rule # 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","cwd":"/p","file_path":"/p/.claude/rules/x.md","memory_type":"Project","load_reason":"path_glob_match","trigger_file_path":"/p/src/a.ts"}' +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-trigger-kept "$(jq -r '.trigger_file_path' "$LOG")" /p/src/a.ts +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-still-rc0 "$rc" 0 +check T10f-unwritable-log-rc0 "$rc" 0 check T10g-unwritable-log-stdout-empty "$out" "" +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` +Run: `bash lib/tests/project-rules.test.sh | tail -3` Expected: `FAIL T10-hook-rc` (hook missing), exit 1. - [ ] **Step 3: Write the hook** @@ -370,21 +471,25 @@ Create `hooks/instructions-loaded.sh`: # 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` with the file that triggered it. -# Never blocks, never prints to stdout (stdout reaches the model), exits 0 -# whatever happens. CLAUDE_INSTRUCTIONS_LOG overrides the path (tests). +# `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 -jq -c --arg ts "$(date -u +%FT%TZ)" \ - '{ts: $ts, cwd, file_path, memory_type, load_reason, trigger_file_path}' \ - >> "$log" 2>/dev/null +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: +In `settings.json`, after the `"SessionStart": [ … ],` block (the `],` that closes it, just before `"PreToolUse": [`), insert: ```json "InstructionsLoaded": [ @@ -400,12 +505,12 @@ In `settings.json`, after the `"SessionStart": [ ... ],` block (the `],` that cl ], ``` -Verify: `jq '.hooks.InstructionsLoaded[0].hooks[0].command' settings.json` prints `"bash ~/.claude/hooks/instructions-loaded.sh"`. +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 && shellcheck hooks/instructions-loaded.sh` -Expected: `FAIL=0`, no shellcheck output. +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** @@ -438,9 +543,9 @@ 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 must stay after `.claude/*`; reconcile appends missing lines at the end of a project's file, which is after any existing `.claude/*`). +`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`: after line 122 `.claude/*` and its negations, add `!.claude/rules/` directly after `!.claude/settings.json` (line 126): +`.gitignore`: add `!.claude/rules/` directly after `!.claude/settings.json` (line 126), so the block reads: ``` .claude/* @@ -453,8 +558,8 @@ Expected: `FAIL socle: !.claude/rules/ …` and `1 suite(s) red`. - [ ] **Step 4: Verify** -Run: `make test suite=lib/gitflow-test.sh 2>&1 | tail -2 && mkdir -p .claude/rules && touch .claude/rules/.probe && git check-ignore -v .claude/rules/.probe; echo "rc=$?"; rm .claude/rules/.probe` -Expected: `all suites green`; `git check-ignore` prints nothing and `rc=1` (not ignored). +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** @@ -468,7 +573,7 @@ git commit -m "chore(gitignore): un-ignore .claude/rules/ here and in the gitflo ### Task 4: split this repo's CLAUDE.md (dogfood `extract`) **Files:** -- Modify: `CLAUDE.md` (four sections leave, a pointer section arrives) +- 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) @@ -481,7 +586,7 @@ Insert before the `echo "PASS=$pass FAIL=$fail"` line of `lib/tests/project-rule ```bash # T11 the real rules of this repo pass the check (4 rules, 1 skip-marked) -out=$(cd "$ROOT" && bash "$PR" check); rc=$? +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 @@ -494,33 +599,31 @@ 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): +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", ".graphify_version"]' -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/**", ".audit/**"]' +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. +Expected: four `project-rules: moved '## …' to .claude/rules/….md` lines. `git diff --stat CLAUDE.md` shows about 90 deletions and no insertion. -- [ ] **Step 3: Skip marker on the transient rule** +- [ ] **Step 3: Transient rule: second glob + skip marker** -Edit `.claude/rules/transient-artifacts.md`: between the `paths:` line and the closing `---`, insert the line `# static-check: skip`. The file starts: +Edit `.claude/rules/transient-artifacts.md` so its frontmatter reads exactly: ``` --- paths: ["docs/superpowers/**", ".audit/**"] # static-check: skip --- - -# Transient planning artifacts ``` - [ ] **Step 4: The pointer section in CLAUDE.md** -CLAUDE.md now holds only the title and `## Health Stack`. Append: +Append to CLAUDE.md: ```markdown @@ -531,9 +634,13 @@ graphify-vendored, mods, transient-artifacts. Check: `bash lib/project-rules.sh check` (runs in `make test`). ``` -The whole file must then read: +The whole file must then read (lines 1-3 are the existing comment, untouched): ```markdown + + # claude-config — project instructions ## Health Stack @@ -548,18 +655,10 @@ 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 verbatim move and the check** +- [ ] **Step 5: Verify** -Run: -```bash -git show HEAD:CLAUDE.md | sed -n '/^## rules\/ maintenance$/,/^## Machine-owned/p' | sed '1d;$d' | sed -e :a -e '/^\n*$/{$d;N;ba' -e '}' > /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/old-rules.txt -sed -n '6,$p' .claude/rules/rules-maintenance.md | sed -e :a -e '/^\n*$/{$d;N;ba' -e '}' > /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/new-rules.txt -diff /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/old-rules.txt /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/new-rules.txt && echo VERBATIM -bash lib/project-rules.sh check -bash lib/tests/project-rules.test.sh | tail -1 -git status --short .claude/rules -``` -Expected: `VERBATIM`; `transient-artifacts.md: SKIP docs/superpowers/**`, `… SKIP .audit/**`, `project-rules: 4 rule(s) ok`; `PASS=… FAIL=0`; four `??`/`A` entries under `.claude/rules/` (tracked thanks to Task 3). +Run: `bash lib/project-rules.sh check; bash lib/tests/project-rules.test.sh | tail -1; git status --short .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/` 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** @@ -573,12 +672,12 @@ git commit -m "refactor(claude-md): four sections become .claude/rules path rule ### Task 5: citers of the moved sections **Files:** -- Modify: `rules/README.md:7-9` +- Modify: `rules/README.md:8-9` - Modify: `doctor.sh:76` - [ ] **Step 1: Repoint `rules/README.md`** -Replace lines 7-9: +Replace lines 8-9: ``` Maintenance doctrine (what belongs here, lazy-load `paths:` semantics, @@ -593,6 +692,8 @@ 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`. @@ -603,11 +704,11 @@ 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. (`lib/gitflow.sh:21` says "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.) +Expected: no output. (`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 -2` +Run: `make test suite=lib/tests/doctrine-citers.test.sh | tail -1` Expected: `all suites green`. ```bash @@ -619,22 +720,21 @@ git commit -m "chore(citers): rules/README and doctor point at .claude/rules aft ### 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 holding `CLAUDE.md` = `git show develop:CLAUDE.md`, plus `rules/x.md`, `mods/m/plugin.json`, `.gitignore` with `.claude/*`). +**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: Build the scratch repo** +- [ ] **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 -S=/tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/split-red -mkdir -p "$S/rules" "$S/mods/m" "$S/.claude" && git show develop:CLAUDE.md > "$S/CLAUDE.md" && echo r > "$S/rules/x.md" && echo '{}' > "$S/mods/m/plugin.json" && printf '.claude/*\n!.claude/memory/\n' > "$S/.gitignore" && git -C "$S" init -q && git -C "$S" add -A && git -C "$S" commit -qm init +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 ``` -(The denied-variable rule: run it as ONE line with the literal path substituted for `$S`.) - - [ ] **Step 2: Dispatch the RED probe (sonnet)** -`Agent(subagent_type="general-purpose", model="sonnet", effort="medium")` with: "You are executing the skill at `/home/bchanot/.claude/skills/onboard/SKILL.md` with `$ARGUMENTS` = `split`, working directory ``. Read the skill, then do exactly what it tells you for its first three steps, in the scratch directory only; do not dispatch agents, do not run `claude`, do not write outside the scratch. Stop after the third step and report: which steps you ran, whether any step asked you to classify CLAUDE.md sections into path-scoped rules, and what you would have produced." +`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 MODEL GATE / plugin check / archetype detection; no classification table, no `.claude/rules/` written. Record one line in the plan's commit message of Task 7 ("RED: current skill runs archetype detection on `split`"). +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. @@ -643,16 +743,16 @@ If the probe DOES produce a split with the current skill: stop, the mode is unne ### Task 7: `/onboard split` mode + onboarder `MODE: split` **Files:** -- Modify: `skills/onboard/SKILL.md` (frontmatter lines 4-5, after `## REQUEST` ~line 20, RULES line ~1037, append § SPLIT MODE after FINAL OUTPUT) -- Modify: `agents/onboarder.md` (after `## INPUTS`, before `## PHASE 1`; and a new section after PHASE 6) +- 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 sections|extract|check` (Task 1). -- Produces: the onboarder `MODE: split` contract: INPUTS `PROJECT_ROOT`, `TABLE` rows ` | | `; OUTPUT rules written, check result, commit hash. +- 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:` — append inside the quoted string, before the closing `'`: ` `split` mode: "split CLAUDE.md", "découpe le CLAUDE.md", "path-scoped rules", "move sections to .claude/rules".` +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`** @@ -668,9 +768,11 @@ below, unchanged. --- ``` -- [ ] **Step 3: RULES line** +- [ ] **Step 3: STEP 3 draft update and the RULES lines** -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).` +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** @@ -683,63 +785,75 @@ Replace `- NO skipping STEP 0, 1, 2 — ils sont obligatoires.` with `- NO skipp 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 oracle. The MODEL GATE above -has run. `mcp__model-router__route(phase="plan")` first. +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 the project root, else print -`nothing to split — run /onboard` and stop. `git status --porcelain -CLAUDE.md` empty, else stop (an in-flight edit would be lost). `.claude/rules/` -already holding rules → list them, continue (new rules add to them). +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. Run `claude -p "/context"` at the root (refused → ask the -user to run `! claude -p "/context"`); note the `Memory files` total and the +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 — CLASSIFY. `bash ~/.claude/lib/project-rules.sh sections CLAUDE.md` -lists every `##` section with its size. For each one decide: +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; + 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 from `git ls-files` (a folder → `dir/**`, - a tool → its config files), and verify every proposed glob with - `git ls-files ''` (≥1 line) before showing it. - Sections that are needed before any file is read (how to run the project) - stay always-on even when they name a folder. + section's subject) and globs (a folder → `dir/**`, a tool → its config + files) 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). -S4 — GATE (mandatory stop). Print the table, then end the turn: +S5 — GATE (mandatory stop). Print the table, then end the turn: ``` -SPLIT — CLAUDE.md ( chars, sections) +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. The approved rows are the -TABLE handed to the onboarder, verbatim. - -S5 — BRANCH. `bash ~/.claude/lib/gitflow.sh start chore claude-md-split`. -A project without gitflow (no `develop`): `git switch -c chore/claude-md-split` -and say so. +"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 +`PROJECT_ROOT: `, `TABLE:` the approved rows, one per line as ` | | ` (LRN-126: every field crosses the -prompt). It extracts each row, writes the pointer section, adds the -gitignore negation, runs `check`, commits. A STOP report (heading absent, -target exists, check red) comes back here: fix the row, re-dispatch; rows -already moved stay moved. +prompt). It pre-flights every row, then extracts, writes the pointer +section, secures the gitignore negation, runs `check`, commits, and +verifies the rules are tracked. A `STOP:` report comes back here with the +rollback already done (nothing committed): fix the row, re-dispatch the +WHOLE table (nothing was moved). A `STOP:` after a commit cannot happen +(the commit is the last step). -S7 — AFTER. `claude -p "/context"` again; 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 `grep path_glob_match ~/.claude/logs/instructions-loaded.jsonl | -tail`. Never `finish`: the merge is the user's signal. +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: ``` @@ -748,19 +862,21 @@ RULES : files under .claude/rules/ () CLAUDE.md: → CONTEXT : → (Memory files) BRANCH : chore/claude-md-split () — merge on your signal -PROOF : pending — fresh session + grep path_glob_match +PROOF : pending — fresh session + the jq filter above ``` ``` -- [ ] **Step 5: Onboarder: mode header + `MODE: split` section** +- [ ] **Step 5: Onboarder: mode header, RULES exemption, `MODE: split` section** -In `agents/onboarder.md`, insert right after `## ROLE`'s paragraph (before the `---` that precedes `## INPUTS`): +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: ```markdown @@ -769,16 +885,34 @@ Append at the end of the file: ## MODE: split (dispatched by `/onboard split`) -INPUTS: `PROJECT_ROOT` (absolute), `TABLE` = the approved rows, one per -line, ` | | ` (heading without `## `). No -BRIEF; PHASES 1-6 do not run. +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 `. -S1 — EXTRACT. From `${PROJECT_ROOT}`, per row: +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`. +- 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 extract CLAUDE.md "" .claude/rules/.md '' +bash ~/.claude/lib/project-rules.sh -C extract CLAUDE.md '' .claude/rules/.md '' ``` -rc 2 (heading absent, target exists, malformed globs) → STOP and report -the row; rows already moved stay (the orchestrator re-dispatches the rest). +rc ≠ 0 (should not happen after S0) → ROLLBACK: `git -C +checkout -- CLAUDE.md .gitignore`, delete every `.claude/rules/.md` +this run wrote, then STOP with the row and the lib's message. S2 — POINTER. If CLAUDE.md has no `## Path-scoped rules` section, append: ```markdown @@ -790,61 +924,60 @@ 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 — GITIGNORE. When `.gitignore` has the exact line `.claude/*` and no -`!.claude/rules/` line: +S3 — CHECK, COMMIT, VERIFY TRACKED. ```bash -sed -i '\|^\.claude/\*$|a !.claude/rules/' .gitignore +bash ~/.claude/lib/project-rules.sh -C check ``` -(No `.claude/*` line → the rules are not ignored, nothing to add.) - -S4 — CHECK + COMMIT. +rc ≠ 0 → ROLLBACK as in S1, STOP with the culprit lines. rc 0 → ```bash -bash ~/.claude/lib/project-rules.sh check -``` -rc ≠ 0 → STOP, report the culprit lines, do not commit. rc 0 → -```bash -git add CLAUDE.md .claude/rules .gitignore -git commit -m "chore(claude-md): split section(s) into .claude/rules/" +git -C add CLAUDE.md .claude/rules .gitignore +git -C commit -m "chore(claude-md): split section(s) into .claude/rules/" +git -C ls-files --error-unmatch .claude/rules/.md # per row ``` +A rule `ls-files` cannot find → report it as `STOP: not tracked +after commit` (the commit stays; the orchestrator decides). OUTPUT: ``` SPLIT DONE: rule(s) — .md (), … CLAUDE.md: → lines CHECK : project-rules: rule(s) ok -COMMIT : +COMMIT : — all rules tracked ``` -or `STOP: — `. +or `STOP: — (rollback done, nothing committed)`. ``` - [ ] **Step 6: Locks still hold** -Run: `make test suite=lib/tests/model-routing.test.sh && make test suite=lib/tests/effort-routing.test.sh && make test suite=lib/tests/loops-heavy.test.sh && make test suite=lib/tests/plan-challenger.test.sh && make test suite=lib/tests/security-auditor.test.sh && make test suite=lib/tests/doctrine-citers.test.sh` -Expected: `all suites green` six times. +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 — classify CLAUDE.md sections, onboarder MODE: split executes (RED: current skill ran archetype detection on 'split')" +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: Reset the scratch repo** +- [ ] **Step 1: Fresh scratch repo `split-green/`** -`git -C /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/split-red checkout -- . && git -C /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/split-red clean -fdq` +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, same prompt as Task 6 Step 2)** +- [ ] **Step 2: Dispatch the GREEN probe (sonnet, its own prompt)** -Expected (GREEN): the report says it jumped to § SPLIT MODE, ran S1-S3, and produced the classification table (at least `rules/ maintenance` → move with `rules/**`, `Health Stack` → keep), then stopped at the S4 gate without writing. A probe that writes files or skips the gate = not green: fix the skill text, re-run. +`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." -- [ ] **Step 3: Executor dry run (sonnet onboarder, MODE: split) on the scratch** +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. -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)`, a commit in the scratch repo, `.gitignore` there gained `!.claude/rules/`, and `bash lib/project-rules.sh check` run from the scratch root prints `2 rule(s) ok`. +- [ ] **Step 3: Executor dry run (onboarder, MODE: split) on the scratch** + +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 tracked`; `git -C log --oneline -1` shows the split commit; `.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` empty here and `git log --oneline -1` unchanged. - [ ] **Step 4: Record** @@ -852,13 +985,13 @@ No commit. The orchestrator notes RED/GREEN outcomes for STEP 7 capitalize (EVAL --- -### Task 9: generators born split (skeletons, `emit`, onboarder PHASE 1b + PHASE 4, scaffolder PHASE 1b) +### 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:3-4` (header comment) -- Modify: `agents/onboarder.md` (new PHASE 1b after PHASE 1; PHASE 4 gains the negation) -- Modify: `agents/scaffolder.md` (new PHASE 1b after PHASE 1) +- 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:** @@ -881,7 +1014,7 @@ 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 "$(ls .claude/rules/ci.md 2>/dev/null | wc -l | tr -d ' ')" 0 +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 @@ -902,9 +1035,9 @@ paths: ["Dockerfile*", "docker-compose*", "compose*.y*ml", ".dockerignore"] # Docker - - - + + + ``` `templates/project-rules/testing.md`: @@ -916,9 +1049,9 @@ paths: ["tests/**", "test/**", "**/*.test.*", "**/*.spec.*", "**/conftest.py"] # Testing conventions - - - + + + ``` `templates/project-rules/ci.md`: @@ -930,81 +1063,66 @@ 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 1b + PHASE 4 negation** +- [ ] **Step 3: Onboarder PHASE 5b** -In `agents/onboarder.md`, after the PHASE 1 block (after `For Option C (monorepo sequential): path = ${package_root}/CLAUDE.md.` and before its `---`), add: +In `agents/onboarder.md`, after the PHASE 5 block (after `**Do NOT overwrite existing content.**` and before the `---` that precedes PHASE 6), add: ```markdown -## PHASE 1b — PATH-SCOPED RULES (born split) +## PHASE 5b — PATH-SCOPED RULES (born split) -From `${PROJECT_ROOT}`, for each of `docker`, `testing`, `ci`: +For each of `docker`, `testing`, `ci`: ```bash -bash ~/.claude/lib/project-rules.sh emit ~/.claude/templates/project-rules/.md .claude/rules/.md +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. Fill its stub comments - from the BRIEF where known (`docker` from `build_cmd`, `testing` from - `test_cmd` and `conventions`); unknown → keep the stubs. +- 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 check` must print `N rule(s) ok`; -list the emitted rules in OUTPUT. +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. ``` -In PHASE 4, replace the three bullets with: +- [ ] **Step 4: Scaffolder PHASE 3b** -```markdown -- **`.gitignore` exists AND contains `settings.local.json`** → nothing to do for it. -- **`.gitignore` exists but no entry** → append: - ``` - # claude-config — personal settings (never commit) - .claude/settings.local.json - ``` -- **`.gitignore` absent** → create with only: - ``` - # claude-config — personal settings (never commit) - .claude/settings.local.json - ``` -- Then, whatever the case: when `.gitignore` has the exact line `.claude/*` - and no `!.claude/rules/` line, add the negation right after it (PHASE 1b - rules would be ignored otherwise, LRN-066): - ```bash - sed -i '\|^\.claude/\*$|a !.claude/rules/' .gitignore - ``` -``` - -- [ ] **Step 4: Scaffolder PHASE 1b** - -In `agents/scaffolder.md`, after PHASE 1 (`Write to CLAUDE.md at project root.`), before its `---`, add: +In `agents/scaffolder.md`, after the PHASE 3 block (its last stack line, before the `---` that precedes `## PHASE 4`), add: ```markdown -## PHASE 1b — PATH-SCOPED RULES (born split) +## PHASE 3b — PATH-SCOPED RULES (born split) -Runs AFTER PHASE 3 has written the files (the globs match the scaffolded -tree). For each of `docker` (only when DOCKER_RELEVANT), `testing`, `ci`: +After PHASE 3 wrote the files and BEFORE PHASE 4 installs dependencies +(installed packages must not match the globs). For each of `docker`, +`testing`, `ci`, one uniform loop: ```bash -bash ~/.claude/lib/project-rules.sh emit ~/.claude/templates/project-rules/.md .claude/rules/.md +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); rc 1 → nothing matched, skipped. Then -`bash ~/.claude/lib/project-rules.sh 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. +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 && cd /tmp && mkdir -p /tmp/claude-1000/-home-bchanot-Documents-claude/ea0efe5f-67aa-4f89-9e2a-ba0ac8695999/scratchpad/gen-all/.github/workflows && 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 && mkdir -p tests test .circleci && touch 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` -Expected: `PASS=… FAIL=0`; `project-rules: 3 rule(s) ok` (every skeleton glob is syntactically sound). +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** @@ -1025,10 +1143,11 @@ git commit -m "feat(generators): onboarder and scaffolder emit docker/testing/ci 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/sections/extract/emit + suite, `hooks/instructions-loaded.sh` (log `~/.claude/logs/instructions-loaded.jsonl`), `!.claude/rules/` here + socle, `/onboard split` + onboarder `MODE: split`, generators emit docker/testing/ci from `templates/project-rules/`. Baseline `/context` 32.2k (project CLAUDE.md 2.1k). - - [ ] Proof, this repo: `/context` after the merge; one fresh session Reading one file per rule → 4 `path_glob_match` lines in the log, pasted in the journal. +- [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 0b, per-repo pass** (after phase 0 merges; via `/onboard split`, one `chore/claude-md-split` per repo, approval per repo, never an automatic merge; `/context` before/after in that repo's journal; faunosteo first and measure whether path rules load inside sub-agents before moving anything a sub-agent needs). Order by size: faunosteo 52,322 chars (on feature/v1-1-clients-animals: wait for it or branch off develop and rebase), 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). + - [ ] 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** @@ -1050,18 +1169,25 @@ git commit -m "chore(todo): phase 0 done in-repo, per-repo pass queued as phase - [ ] **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 2.1k (about 150 tokens); Memory files total about 1.9k lower than the 11.6k baseline. Record both numbers for the journal. +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: Logged loads** +- [ ] **Step 2: Main-session loads** -The hook needs a session started AFTER Task 2 landed in `settings.json`. Run a headless session that reads one file per rule: `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 `grep path_glob_match ~/.claude/logs/instructions-loaded.jsonl | tail -4 | jq -c '{file_path, trigger_file_path}'`. -Expected: four lines, 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 a transcript check (`/context` in the same session listing the rule under Memory files), and the finding goes to STEP 7 as a BLK. +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** + +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 +`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 → 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 + suite → Task 1, 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. +- 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 1b (both agents); 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 T5b, T11b and the agents quote. -- Review Focus: 1 → T6/T7h, 2 → T8, 3 → T2/T4c, 4 → T12, 5 → T10f/T10g. All pinned. +- 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. +- Review Focus: 1 → T6d/T8e/T8f, 2 → T2c/T12b/T12f, 3 → T2d/T5j, 4 → Task 8 Step 3 assertions, 5 → T10f-T10j. All pinned.