forked from bchanot/claude
chore(memory): LRN-234 — feat rules-h3-extract, contract + plan + TODO follow-ups
This commit is contained in:
1 parent
c446caeae6
commit
f85e9a722c
5 files changed
+349
-1
No files matched your search
@@ -0,0 +1,303 @@
|
||||
# PLAN r3 — rules-h3-extract (feat, 2026-10-27)
|
||||
Contract: `.claude/tasks/contracts/2026-10-27-rules-h3-extract-1326.md`.
|
||||
Base develop 925dafa. Our code (strict): `lib/project-rules.sh` 80 cols,
|
||||
≤ 25 logic lines and ≤ 5 locals per function, shellcheck clean, mawk-safe
|
||||
awk (no `{n,m}` intervals), no `sed -i`. r2 folds the 3-lens challenge
|
||||
(S5 cell, separator loss, `#1 title` regression, arity, AC5 gate items,
|
||||
parent-with-children test); r3 folds the confirmation pass (T13r locale
|
||||
collation, re-emission gated on level 3, level-refusal flip, `####`+ arm,
|
||||
S0.3 wording, S5 anchor, 4-backtick fence). Edits anchor on TEXT, never
|
||||
on line numbers.
|
||||
|
||||
## Approach
|
||||
- The heading argument carries its level: bare `<title>` = `## <title>`
|
||||
(unchanged, including a title that starts with `#` such as `#1 priority`);
|
||||
`### <title>` = a level-3 section; `## <title>` is accepted as the explicit
|
||||
level-2 form. `# x` (H1) or `####`-and-deeper → rc 2 `heading level must
|
||||
be ## or ###`. One helper
|
||||
`_rules_heading_line` normalises the argument to the exact heading LINE;
|
||||
every awk helper takes that line and derives the level inside awk as
|
||||
`lvl = index(h, " ") - 1`.
|
||||
- A section of level L ends at the next heading of level ≤ L outside a
|
||||
fence: awk test `match($0, /^#+ /) && RLENGTH - 1 <= lvl`.
|
||||
- Separator rule, level 3 ONLY: when a `###` section is removed and its end
|
||||
is a heading of a LOWER level (`#`/`##`), the trailing run of blank/`---`
|
||||
lines it carried is re-emitted in the source (it was the parent's closing
|
||||
separator); when the end is a same-level heading, the run goes with the
|
||||
section. A `##` section keeps today's behaviour exactly (its run always
|
||||
travels with it, an H1 end included): the awk condition is
|
||||
`lvl == 3 && RLENGTH - 1 < lvl`. The rule body trims the run either way.
|
||||
- `sections [--depth 2|3] <file>`: depth 2 is today's output byte for byte;
|
||||
depth 3 also lists each `###` subsection (its own chars, its line, the
|
||||
`### <title>` heading). A `##` parent's chars keep counting through its
|
||||
children (same number as depth 2). Exactly one positional argument after
|
||||
the optional flag, else rc 2 (a flag after the file is an error, not a
|
||||
silent depth 2). Lines come out in file order: awk prints at close, so the
|
||||
output is piped through `sort -t "$(printf '\t')" -k2,2n`.
|
||||
- Rule title line: `# <title without its prefix>`.
|
||||
|
||||
## Files
|
||||
### 1. `lib/project-rules.sh`
|
||||
Header: replace the block that starts at the line beginning
|
||||
`# sections <file>` and ends at the line before `# emit <skeleton>` with:
|
||||
```
|
||||
# sections [--depth 2|3] <file> chars, line, heading per ## section
|
||||
# (--depth 3 adds the ### subsections; a section
|
||||
# ends at the next heading of level ≤ its own)
|
||||
# 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 ---)
|
||||
```
|
||||
Every header line ≤ 80 chars.
|
||||
|
||||
Replace `_rules_heading_count`, `_rules_section_body` and
|
||||
`_rules_without_section` (they now take the heading LINE), and add
|
||||
`_rules_heading_line` before them:
|
||||
|
||||
```bash
|
||||
_rules_heading_line() { # <heading arg> → "## t" | "### t" on stdout, rc 2
|
||||
case "$1" in
|
||||
'## '*|'### '*) printf '%s\n' "$1" ;;
|
||||
'# '*|'####'*)
|
||||
echo "project-rules: heading level must be ## or ###: $1" >&2
|
||||
return 2 ;;
|
||||
*) printf '## %s\n' "$1" ;;
|
||||
esac
|
||||
}
|
||||
|
||||
_rules_heading_count() { # <file> <heading line> → fence-aware count
|
||||
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 && $0 == h { on = 1; next }
|
||||
!fence && on && match($0, /^#+ /) && RLENGTH - 1 <= lvl { exit }
|
||||
on { buf[++n] = $0 }
|
||||
END { while (n > 0 && (buf[n] == "" || buf[n] == "---")) n--
|
||||
for (i = 1; i <= n; i++) print buf[i] }' "$1"
|
||||
}
|
||||
|
||||
_rules_without_section() { # <file> <heading line> → the file minus it
|
||||
# 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 && $0 == h { skip = 1; n = 0; next }
|
||||
!fence && skip && match($0, /^#+ /) && RLENGTH - 1 <= lvl {
|
||||
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"
|
||||
}
|
||||
```
|
||||
(`'####'*` without a trailing space catches every level ≥ 4.)
|
||||
|
||||
`project_rules_sections` becomes:
|
||||
```bash
|
||||
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; }
|
||||
awk -v depth="$depth" '
|
||||
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 { flush3(); flush2() }
|
||||
/^## / && !fence { flush3(); flush2(); h2 = $0; l2 = NR; c2 = 0 }
|
||||
/^### / && !fence && depth == 3 { flush3(); h3 = $0; l3 = NR; c3 = 0 }
|
||||
h2 != "" { c2 += length($0) + 1 }
|
||||
h3 != "" { c3 += length($0) + 1 }
|
||||
END { flush3(); flush2() }' "$1" | sort -t "$(printf '\t')" -k2,2n
|
||||
}
|
||||
```
|
||||
(`shift 2` with a lone `--depth` and `set -u`: `${2:-}` is empty, the case
|
||||
refuses it before the shift matters; if shellcheck or bash complains about
|
||||
`shift 2` on one argument, guard with `[ $# -ge 2 ] &&`.)
|
||||
|
||||
`project_rules_extract` becomes (locals: src out globs hline tmp):
|
||||
```bash
|
||||
project_rules_extract() { # <file> <heading> <out.md> <globs-json>
|
||||
local src="$1" out="$3" globs="$4" hline tmp
|
||||
hline=$(_rules_heading_line "$2") || return 2
|
||||
[ "$(_rules_heading_count "$src" "$hline")" = 1 ] || {
|
||||
echo "project-rules: heading must occur exactly once: $hline" >&2
|
||||
return 2; }
|
||||
[ -e "$out" ] && { echo "project-rules: $out exists" >&2; return 2; }
|
||||
_rules_globs_all_match "$globs" || return 2
|
||||
mkdir -p "$(dirname "$out")"
|
||||
tmp=$(mktemp) || { echo "project-rules: no temp file" >&2; return 2; }
|
||||
{ printf -- '---\npaths: %s\n---\n\n# %s\n' "$globs" "${hline#* }"
|
||||
_rules_section_body "$src" "$hline"; } > "$out"
|
||||
if ! { _rules_without_section "$src" "$hline" > "$tmp" \
|
||||
&& cat "$tmp" > "$src"; }; then
|
||||
rm -f "$tmp" "$out"
|
||||
echo "project-rules: $src not rewritten, $out removed" >&2
|
||||
return 2
|
||||
fi
|
||||
rm -f "$tmp"
|
||||
echo "project-rules: moved '$hline' to $out"
|
||||
}
|
||||
```
|
||||
Main dispatch: `sections) project_rules_sections "${@:2}" ;;`. The usage
|
||||
`*)` arm becomes:
|
||||
```bash
|
||||
*) echo "usage: project-rules.sh [-C dir] check [rules-dir] | matches" \
|
||||
"<glob> | sections [--depth 2|3] <file> | extract <file>" \
|
||||
"<heading> <out> <globs-json> | emit <skeleton> <out>" >&2
|
||||
return 2 ;;
|
||||
```
|
||||
|
||||
### 2. `lib/tests/project-rules.test.sh`
|
||||
No existing expectation changes (the "moved" message now prints the heading
|
||||
line; no test greps it). Insert the block AFTER the T12 block's closing
|
||||
`cd "$FIX" || exit 1` and BEFORE the `echo "PASS=$pass FAIL=$fail"` line:
|
||||
|
||||
````bash
|
||||
# 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"
|
||||
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'
|
||||
# shellcheck disable=SC2016
|
||||
check T13i-removed-lines "$(diff "$FIX/orig3.md" CLAUDE.md | grep '^< ' | cut -c3- | grep -vE '^(---)?$' | tr '\n' '|')" '### Sub|s1|```|### fenced|```|#### 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
|
||||
````
|
||||
(T13r counts files instead of listing them: glob order follows
|
||||
LC_COLLATE, and `make test` does not pin the locale.)
|
||||
Hand counts (each line `length + 1`, the heading line counted in its own
|
||||
section): `### Sub` = `### Sub`(8) `s1`(3) "```"(4) `### fenced`(11)
|
||||
"```"(4) `#### deep`(10) `s2`(3) ``(1) = 44, at file line 6. `### Sub2` =
|
||||
9+3+1+4+1 = 18. `## P` = `## P`(5) `intro`(6) ``(1) + 44 + 18 = 74.
|
||||
`## Q` = 5+2 = 7. The rule file: lines 1-3 frontmatter, 4 blank, 5
|
||||
`# Sub`, 6-11 the body. T13l: the diff of the Sub2 extract deletes exactly
|
||||
`### Sub2` and `s3` (the blank, `---`, blank run is re-emitted), so the
|
||||
`<` lines are those two. Expected tally: 93 + 23 = 116.
|
||||
|
||||
### 3. `skills/onboard/SKILL.md` § SPLIT MODE S4 and S5
|
||||
S4: the first sentence `` `bash ~/.claude/lib/project-rules.sh -C <ROOT> sections
|
||||
CLAUDE.md` lists every `##` section with its size.`` becomes
|
||||
`` `bash ~/.claude/lib/project-rules.sh -C <ROOT> sections --depth 3
|
||||
CLAUDE.md` lists every `##` section with its size and, under it, its
|
||||
`###` subsections with theirs (the parent's size includes them).`` and this
|
||||
text is added right after that sentence:
|
||||
`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).`
|
||||
S5: after the Docker example row add the row
|
||||
`| 3 | ### Supabase | 2,210 | move | supabase.md | ["supabase/**"] |`
|
||||
and, AFTER the gate template's closing ``` fence and BEFORE the paragraph
|
||||
that starts `"keep everything" ends the mode`, add the sentence `A `###`
|
||||
row's section cell is the exact heading argument, prefix included, nothing
|
||||
else (no parent breadcrumb: the cell crosses to the onboarder verbatim).`
|
||||
|
||||
### 4. `agents/onboarder.md` § MODE: split
|
||||
INPUTS: `(heading without `## `)` becomes `(heading without `## `; a
|
||||
subsection row starts with `### ` and is passed to `extract` as written)`.
|
||||
S0 step 3: after `the heading has no `'`;` add `a heading whose leading `#`
|
||||
run is followed by a space starts with `### `; any other leading `#` is a
|
||||
bare `##` title (`#1 priority`);`
|
||||
S0 step 4: `` `PR sections CLAUDE.md` lists `## <heading>` exactly once`` becomes
|
||||
`` `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``.
|
||||
S1 first line: `(single quotes around the heading):` becomes `(single quotes
|
||||
around the heading, passed as the row wrote it: bare, or with its `### `
|
||||
prefix):`.
|
||||
|
||||
## Edge cases
|
||||
- `### ` inside a fence: never a heading (fence-aware, T13i).
|
||||
- `####` under a `###`: body of the `###` (T13i/T13j), not extractable (T13p).
|
||||
- Same `###` title under two parents: count 2 → rc 2, user renames (the
|
||||
existing "exactly once" rule, now across levels).
|
||||
- Last `###` of a parent: the parent's trailing `---` stays in the source
|
||||
(T13l/T13m); a same-level end takes the run with the section, as `##`.
|
||||
- `sections --depth 3` on a file with no `###`: identical to depth 2.
|
||||
- A bare title starting with `#` (`#1 priority`): still `##` (T13u).
|
||||
- `sort` on an empty awk output: prints nothing, rc 0.
|
||||
|
||||
## Tests
|
||||
- `bash lib/tests/project-rules.test.sh | tail -1` → `FAIL=0` (114).
|
||||
- `shellcheck lib/project-rules.sh lib/tests/project-rules.test.sh` clean.
|
||||
- `awk 'length > 80' lib/project-rules.sh` empty.
|
||||
- `make test` all GREEN (citers census sees the skill/agent edits).
|
||||
- `bash lib/project-rules.sh check` → 4 rule(s) ok; `sections CLAUDE.md` → 2 lines.
|
||||
|
||||
## Disposition
|
||||
- honors BDR-128 by keeping one oracle, inline `paths:`, subtract-only
|
||||
extract, the `##` contract unchanged (depth-2 output byte-identical).
|
||||
- honors LRN-233 by keeping the awk-reads-the-pipe shape, the checked
|
||||
`mktemp` + `if !` rewrite, no `{n,m}` awk intervals.
|
||||
- honors LRN-096 by flip tests (T13e/f refusals, T13p2/q2 the level arm's
|
||||
message, T13i/l/n conservation).
|
||||
- BDR-003 unaffected.
|
||||
Reference in new issue
Block a user