feat(rules): extract accepts a ### heading, sections --depth 3 lists subsections, split mode names the ### row

A ### section ends at the next heading of level <= 3 outside a fence; a last ### gives its parent's trailing --- back. Bare headings stay ##.
This commit is contained in:
bchanot committed 2026-10-27 14:38:57 +01:00
1 parent 925dafa4bc
commit ab5049e5b1
4 files changed
+153 -39

No files matched your search

+10 -4
View File
@@ -199,7 +199,8 @@ PLACEHOLDERS : <null enrichment keys left as TODO(/onboard STEP 3), or none>
INPUTS: `PROJECT_ROOT` (absolute; written as a literal path in every INPUTS: `PROJECT_ROOT` (absolute; written as a literal path in every
command below, never through a variable), `TABLE` = the approved rows, one command below, never through a variable), `TABLE` = the approved rows, one
per line, `<heading> | <name> | <globs-json>` (heading without `## `). No per line, `<heading> | <name> | <globs-json>` (heading without `## `; a
subsection row starts with `### ` and is passed to `extract` as written). No
BRIEF; PHASES 1-6 do not run. `PR` below stands for BRIEF; PHASES 1-6 do not run. `PR` below stands for
`bash ~/.claude/lib/project-rules.sh -C <PROJECT_ROOT>`. `bash ~/.claude/lib/project-rules.sh -C <PROJECT_ROOT>`.
@@ -209,10 +210,14 @@ S0 — PREFLIGHT (no write before every step passes):
rule the oracle cannot parse (the one-line `paths: ["a", "b"]` form rule the oracle cannot parse (the one-line `paths: ["a", "b"]` form
only) is fixed by the user before any split. only) is fixed by the user before any split.
3. Per row, by reading the row (never a shell test that embeds it): 3. Per row, by reading the row (never a shell test that embeds it):
`<name>` matches `[a-z0-9][a-z0-9-]*`; the heading has no `'`; every `<name>` matches `[a-z0-9][a-z0-9-]*`; the heading has no `'`; a heading
whose leading `#` run is followed by a space starts with `### `; any other
leading `#` is a bare `##` title (`#1 priority`); every
glob is relative, with no `'`, no leading `/`, no `..`. A row that glob is relative, with no `'`, no leading `/`, no `..`. A row that
fails → STOP with the row and the field. fails → STOP with the row and the field.
4. Per row: `PR sections CLAUDE.md` lists `## <heading>` exactly once; 4. Per row: `PR sections --depth 3 CLAUDE.md` lists the row's heading exactly
once (`## <heading>` for a bare row; a `### ` row's heading as written);
a `### ` row whose parent `##` is also a row → STOP with both rows;
`<PROJECT_ROOT>/.claude/rules/<name>.md` does not exist; every glob of `<PROJECT_ROOT>/.claude/rules/<name>.md` does not exist; every glob of
`<globs-json>` passes `PR matches '<glob>'` (rc 0). Any failure → STOP `<globs-json>` passes `PR matches '<glob>'` (rc 0). Any failure → STOP
with the row and the reason. with the row and the reason.
@@ -236,7 +241,8 @@ S0 — PREFLIGHT (no write before every step passes):
A STOP after 5.d reverts the gitignore line (5.e); nothing else was A STOP after 5.d reverts the gitignore line (5.e); nothing else was
written. written.
S1 — EXTRACT, per row (single quotes around the heading): S1 — EXTRACT, per row (single quotes around the heading, passed as the row
wrote it: bare, or with its `### ` prefix):
```bash ```bash
bash ~/.claude/lib/project-rules.sh -C <PROJECT_ROOT> extract CLAUDE.md '<heading>' .claude/rules/<name>.md '<globs-json>' bash ~/.claude/lib/project-rules.sh -C <PROJECT_ROOT> extract CLAUDE.md '<heading>' .claude/rules/<name>.md '<globs-json>'
``` ```
+66 -33
View File
@@ -7,10 +7,12 @@
# check [rules-dir] every path rule parses and every glob matches ≥1 # check [rules-dir] every path rule parses and every glob matches ≥1
# path; rc 2 with the culprit named # path; rc 2 with the culprit named
# matches <glob> rc 0 + the first hits, rc 1 none # matches <glob> rc 0 + the first hits, rc 1 none
# sections <file> chars, line, heading per top-level ## section # sections [--depth 2|3] <file> chars, line, heading per ## section
# (a section ends at the next # or ## heading # (--depth 3 adds the ### subsections; a section
# outside a fence) # ends at the next heading of level ≤ its own)
# extract <file> <heading> <out> <globs-json> move one section to a rule # extract <file> <heading> <out> <globs-json> move one section to a
# rule (bare heading = ##; "### title" = a subsection;
# a ### moved last keeps its parent's trailing ---)
# emit <skeleton> <out> the rule with the matching globs only (rc 1 # emit <skeleton> <out> the rule with the matching globs only (rc 1
# when none matches, nothing written) # when none matches, nothing written)
# Globs match the WORKING TREE (compgen -G with globstar and dotglob, # Globs match the WORKING TREE (compgen -G with globstar and dotglob,
@@ -105,39 +107,68 @@ project_rules_matches() { # <glob> → rc 0 + the first 3 hits, rc 1 none
|| { echo "no match: $1" >&2; return 1; } || { echo "no match: $1" >&2; return 1; }
} }
project_rules_sections() { # <file> → chars, line, heading per ## section project_rules_sections() { # [--depth 2|3] <file> → chars, line, heading
local depth=2
if [ "${1:-}" = "--depth" ]; then depth="${2:-}"; shift 2; fi
case "$depth" in 2|3) ;; *)
echo "project-rules: --depth takes 2 or 3" >&2; return 2 ;; esac
[ $# -eq 1 ] \
|| { echo "project-rules: sections [--depth 2|3] <file>" >&2; return 2; }
[ -f "$1" ] || { echo "project-rules: $1 not found" >&2; return 2; } [ -f "$1" ] || { echo "project-rules: $1 not found" >&2; return 2; }
awk ' awk -v depth="$depth" '
function flush() { if (h != "") printf "%d\t%d\t%s\n", c, l, h; h = "" } function flush2() {
if (h2 != "") printf "%d\t%d\t%s\n", c2, l2, h2; h2 = "" }
function flush3() {
if (h3 != "") printf "%d\t%d\t%s\n", c3, l3, h3; h3 = "" }
/^```/ { fence = !fence } /^```/ { fence = !fence }
/^# / && !fence { flush() } /^# / && !fence { flush3(); flush2() }
/^## / && !fence { flush(); h = $0; l = NR; c = 0 } /^## / && !fence { flush3(); flush2(); h2 = $0; l2 = NR; c2 = 0 }
h != "" { c += length($0) + 1 } /^### / && !fence && depth == 3 { flush3(); h3 = $0; l3 = NR; c3 = 0 }
END { flush() }' "$1" h2 != "" { c2 += length($0) + 1 }
h3 != "" { c3 += length($0) + 1 }
END { flush3(); flush2() }' "$1" | sort -t "$(printf '\t')" -k2,2n
} }
_rules_heading_count() { # <file> <heading> → fence-aware count of "## h" _rules_heading_line() { # <heading arg> → "## t" | "### t" on stdout, rc 2
awk -v h="## $2" '/^```/ { fence = !fence } case "$1" in
!fence && $0 == h { n++ } '## '*|'### '*) printf '%s\n' "$1" ;;
END { print n + 0 }' "$1" '# '*|'####'*)
echo "project-rules: heading level must be ## or ###: $1" >&2
return 2 ;;
*) printf '## %s\n' "$1" ;;
esac
} }
_rules_section_body() { # <file> <heading> → body, trailing ---/blank trimmed _rules_heading_count() { # <file> <heading line> → fence-aware count
awk -v h="## $2" ' awk -v h="$2" '/^```/ { fence = !fence }
!fence && $0 == h { n++ }
END { print n + 0 }' "$1"
}
_rules_section_body() { # <file> <heading line> → body, ---/blank trimmed
awk -v h="$2" '
BEGIN { lvl = index(h, " ") - 1 }
/^```/ { fence = !fence } /^```/ { fence = !fence }
!fence && $0 == h { on = 1; next } !fence && $0 == h { on = 1; next }
!fence && on && (/^## / || /^# /) { exit } !fence && on && match($0, /^#+ /) && RLENGTH - 1 <= lvl { exit }
on { buf[++n] = $0 } on { buf[++n] = $0 }
END { while (n > 0 && (buf[n] == "" || buf[n] == "---")) n-- END { while (n > 0 && (buf[n] == "" || buf[n] == "---")) n--
for (i = 1; i <= n; i++) print buf[i] }' "$1" for (i = 1; i <= n; i++) print buf[i] }' "$1"
} }
_rules_without_section() { # <file> <heading> → the file minus that section _rules_without_section() { # <file> <heading line> → the file minus it
awk -v h="## $2" ' # a ### ended by a lower-level heading gives its trailing ---/blank run
# back to the source (the parent's closing separator); a ## keeps today's
# behaviour, its run travels with it
awk -v h="$2" '
BEGIN { lvl = index(h, " ") - 1 }
/^```/ { fence = !fence } /^```/ { fence = !fence }
!fence && $0 == h { skip = 1; next } !fence && $0 == h { skip = 1; n = 0; next }
!fence && skip && (/^## / || /^# /) { skip = 0 } !fence && skip && match($0, /^#+ /) && RLENGTH - 1 <= lvl {
!skip { print }' "$1" if (lvl == 3 && RLENGTH - 1 < lvl) for (i = 1; i <= n; i++) print buf[i]
skip = 0 }
skip { if ($0 == "" || $0 == "---") buf[++n] = $0; else n = 0; next }
{ print }' "$1"
} }
_rules_globs_all_match() { # <globs-json> → rc 0 valid and every glob matches _rules_globs_all_match() { # <globs-json> → rc 0 valid and every glob matches
@@ -152,24 +183,25 @@ _rules_globs_all_match() { # <globs-json> → rc 0 valid and every glob matches
} }
project_rules_extract() { # <file> <heading> <out.md> <globs-json> project_rules_extract() { # <file> <heading> <out.md> <globs-json>
local src="$1" heading="$2" out="$3" globs="$4" tmp local src="$1" out="$3" globs="$4" hline tmp
[ "$(_rules_heading_count "$src" "$heading")" = 1 ] || { hline=$(_rules_heading_line "$2") || return 2
echo "project-rules: heading must occur exactly once: ## $heading" >&2 [ "$(_rules_heading_count "$src" "$hline")" = 1 ] || {
echo "project-rules: heading must occur exactly once: $hline" >&2
return 2; } return 2; }
[ -e "$out" ] && { echo "project-rules: $out exists" >&2; return 2; } [ -e "$out" ] && { echo "project-rules: $out exists" >&2; return 2; }
_rules_globs_all_match "$globs" || return 2 _rules_globs_all_match "$globs" || return 2
mkdir -p "$(dirname "$out")" mkdir -p "$(dirname "$out")"
tmp=$(mktemp) || { echo "project-rules: no temp file" >&2; return 2; } tmp=$(mktemp) || { echo "project-rules: no temp file" >&2; return 2; }
{ printf -- '---\npaths: %s\n---\n\n# %s\n' "$globs" "$heading" { printf -- '---\npaths: %s\n---\n\n# %s\n' "$globs" "${hline#* }"
_rules_section_body "$src" "$heading"; } > "$out" _rules_section_body "$src" "$hline"; } > "$out"
if ! { _rules_without_section "$src" "$heading" > "$tmp" \ if ! { _rules_without_section "$src" "$hline" > "$tmp" \
&& cat "$tmp" > "$src"; }; then && cat "$tmp" > "$src"; }; then
rm -f "$tmp" "$out" rm -f "$tmp" "$out"
echo "project-rules: $src not rewritten, $out removed" >&2 echo "project-rules: $src not rewritten, $out removed" >&2
return 2 return 2
fi fi
rm -f "$tmp" rm -f "$tmp"
echo "project-rules: moved '## $heading' to $out" echo "project-rules: moved '$hline' to $out"
} }
project_rules_emit() { # <skeleton.md> <out.md> → the rule, matching globs only project_rules_emit() { # <skeleton.md> <out.md> → the rule, matching globs only
@@ -197,13 +229,14 @@ _project_rules_main() {
case "${1:-}" in case "${1:-}" in
check) project_rules_check "${2:-.claude/rules}" ;; check) project_rules_check "${2:-.claude/rules}" ;;
matches) project_rules_matches "${2:?glob}" ;; matches) project_rules_matches "${2:?glob}" ;;
sections) project_rules_sections "${2:?file}" ;; sections) project_rules_sections "${@:2}" ;;
extract) project_rules_extract "${2:?file}" "${3:?heading}" "${4:?out}" \ extract) project_rules_extract "${2:?file}" "${3:?heading}" "${4:?out}" \
"${5:?globs-json}" ;; "${5:?globs-json}" ;;
emit) project_rules_emit "${2:?skeleton}" "${3:?out}" ;; emit) project_rules_emit "${2:?skeleton}" "${3:?out}" ;;
*) echo "usage: project-rules.sh [-C dir] check [rules-dir] | matches" \ *) echo "usage: project-rules.sh [-C dir] check [rules-dir] | matches" \
"<glob> | sections <file> | extract <file> <heading> <out>" \ "<glob> | sections [--depth 2|3] <file> | extract <file>" \
"<globs-json> | emit <skeleton> <out>" >&2; return 2 ;; "<heading> <out> <globs-json> | emit <skeleton> <out>" >&2
return 2 ;;
esac esac
} }
+63
View File
@@ -233,5 +233,68 @@ check T12h-existing-target-rc "$?" 2
bash "$PR" check >/dev/null; check T12i-emitted-rules-pass-check "$?" 0 bash "$PR" check >/dev/null; check T12i-emitted-rules-pass-check "$?" 0
cd "$FIX" || exit 1 cd "$FIX" || exit 1
# T13 ### subsections: hidden at depth 2, listed at depth 3, extractable,
# a ### moved last gives its parent's --- back, a ## parent takes its ###
mkdir -p "$FIX/d3/src" && cd "$FIX/d3" || exit 1
echo x > src/a.ts
cat > CLAUDE.md <<'EOF'
# Top
## P
intro
### Sub
s1
```
### fenced
```
#### deep
s2
### Sub2
s3
---
## Q
q
EOF
cp CLAUDE.md "$FIX/orig3.md"
fence=$(printf '\140\140\140')
check T13-depth2-unchanged "$(bash "$PR" sections CLAUDE.md | cut -f1,3 | tr '\t\n' ' |')" '74 ## P|7 ## Q|'
out=$(bash "$PR" sections --depth 3 CLAUDE.md)
check T13b-depth3-file-order "$(printf '%s\n' "$out" | cut -f3 | tr '\n' '|')" '## P|### Sub|### Sub2|## Q|'
check T13c-sub-chars-and-line "$(printf '%s\n' "$out" | awk -F'\t' '$3=="### Sub"{print $1 "," $2}')" '44,6'
check T13d-parent-same-as-depth2 "$(printf '%s\n' "$out" | awk -F'\t' '$3=="## P"{print $1}')" 74
bash "$PR" sections --depth 4 CLAUDE.md 2>/dev/null; check T13e-bad-depth-rc "$?" 2
bash "$PR" sections CLAUDE.md --depth 3 2>/dev/null; check T13f-flag-after-file-rc "$?" 2
bash "$PR" extract CLAUDE.md '### Sub' .claude/rules/sub.md '["src/**"]' >/dev/null
check T13g-extract-sub-rc "$?" 0
check T13h-rule-title "$(sed -n '5p' .claude/rules/sub.md)" '# Sub'
check T13i-removed-lines "$(diff "$FIX/orig3.md" CLAUDE.md | grep '^< ' | cut -c3- | grep -vE '^(---)?$' | tr '\n' '|')" "### Sub|s1|$fence|### fenced|$fence|#### deep|s2|"
check T13j-rule-ends-before-sub2 "$(tail -1 .claude/rules/sub.md)" 's2'
cp CLAUDE.md "$FIX/mid3.md"
bash "$PR" extract CLAUDE.md '### Sub2' .claude/rules/sub2.md '["src/**"]' >/dev/null
check T13k-last-child-rc "$?" 0
check T13l-last-child-removed-lines "$(diff "$FIX/mid3.md" CLAUDE.md | grep '^< ' | cut -c3- | tr '\n' '|')" '### Sub2|s3|'
check T13m-parent-separator-kept "$(grep -c '^---$' CLAUDE.md)" 1
check T13n-no-additions "$(diff "$FIX/mid3.md" CLAUDE.md | grep -c '^> ')" 0
check T13o-q-kept "$(grep -c '^## Q' CLAUDE.md)" 1
bash "$PR" extract CLAUDE.md '#### deep' .claude/rules/deep.md '["src/**"]' 2>/dev/null
check T13p-level4-rc "$?" 2
check T13p2-level4-msg "$(bash "$PR" extract CLAUDE.md '#### deep' .claude/rules/deep.md '["src/**"]' 2>&1 >/dev/null | grep -c 'heading level must be ## or ###')" 1
bash "$PR" extract CLAUDE.md '# Top' .claude/rules/top.md '["src/**"]' 2>/dev/null
check T13q-level1-rc "$?" 2
check T13q2-level1-msg "$(bash "$PR" extract CLAUDE.md '# Top' .claude/rules/top.md '["src/**"]' 2>&1 >/dev/null | grep -c 'heading level must be ## or ###')" 1
check T13r-nothing-else-written "$(cd .claude/rules && printf '%s\n' * | wc -l | tr -d ' ')" 2
cp "$FIX/orig3.md" CLAUDE.md
bash "$PR" extract CLAUDE.md 'P' .claude/rules/p.md '["src/**"]' >/dev/null
check T13s-parent-takes-children "$(grep -c '^### Sub' .claude/rules/p.md)" 2
check T13t-parent-extract-q-kept "$(grep -c '^## Q' CLAUDE.md)" 1
printf '## #1 priority\nbody\n' > hash.md
bash "$PR" extract hash.md '#1 priority' .claude/rules/hash.md '["src/**"]' >/dev/null
check T13u-bare-title-starting-with-hash "$?" 0
cd "$FIX" || exit 1
echo "PASS=$pass FAIL=$fail" echo "PASS=$pass FAIL=$fail"
[ "$fail" -eq 0 ] [ "$fail" -eq 0 ]
+14 -2
View File
@@ -1119,8 +1119,16 @@ claude-md-split`. A project without gitflow (no `develop`):
`git -C <ROOT> switch -c chore/claude-md-split`, and say so. Everything `git -C <ROOT> switch -c chore/claude-md-split`, and say so. Everything
after this step reads the branched file. after this step reads the branched file.
S4 — CLASSIFY. `bash ~/.claude/lib/project-rules.sh -C <ROOT> sections S4 — CLASSIFY. `bash ~/.claude/lib/project-rules.sh -C <ROOT> sections --depth 3
CLAUDE.md` lists every `##` section with its size. For each one decide: CLAUDE.md` lists every `##` section with its size and, under it, its
`###` subsections with theirs (the parent's size includes them).
An always-on parent (conventions, overview) whose subsections are
path-bound (one module, one tool) keeps its intro and the subsections move,
one row each, heading written `### <title>` in the TABLE (the prefix marks
the level; a bare heading means `##`). A `###` title must be unique across
the whole file, like a `##` one, and a `###` row's parent is never itself a
move row (the parent would carry the child away first; say so, the user
picks one). For each one decide:
- always-on: project overview, stack, build/test/lint commands, folder - always-on: project overview, stack, build/test/lint commands, folder
structure, conventions that apply everywhere, exceptions to global rules, structure, conventions that apply everywhere, exceptions to global rules,
workflow expectations, key dependencies, anything needed before a file is workflow expectations, key dependencies, anything needed before a file is
@@ -1144,9 +1152,13 @@ SPLIT — <project> CLAUDE.md (<chars> chars, <n> sections) on chore/claude-md-s
| # | section | chars | verdict | rule file | paths | | # | section | chars | verdict | rule file | paths |
| 1 | Stack | 420 | keep | | | | 1 | Stack | 420 | keep | | |
| 2 | Docker | 1,340 | move | docker.md | ["Dockerfile*", "docker-compose*"] | | 2 | Docker | 1,340 | move | docker.md | ["Dockerfile*", "docker-compose*"] |
| 3 | ### Supabase | 2,210 | move | supabase.md | ["supabase/**"] |
... ...
Moves <k> sections, <m> chars (<p>% of the file). Approve, edit a row, or "keep everything". Moves <k> sections, <m> chars (<p>% of the file). Approve, edit a row, or "keep everything".
``` ```
A `###` row's section cell is the exact heading argument, prefix included,
nothing else (no parent breadcrumb: the cell crosses to the onboarder
verbatim).
"keep everything" ends the mode with no change (`bash "keep everything" ends the mode with no change (`bash
~/.claude/lib/gitflow.sh delete chore/claude-md-split`). An edited row's ~/.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 globs are re-verified with `matches` before they enter the TABLE. The