chore(contract): citers-blind-spots plan r3 + contract
This commit is contained in:
1 parent
5bd0de4498
commit
ef7ebd9035
2 files changed
+130
No files matched your search
@@ -0,0 +1,21 @@
|
||||
# CONTRACT — citers-blind-spots
|
||||
|
||||
## REQUEST (verbatim — IMMUTABLE)
|
||||
Close the doctrine-citers census blind spots (TODO phase 1): lib/tests/doctrine-citers.test.sh (1) `_citers_extract_files` regex `(rules|lib)/[a-z0-9-]+\.md` misses nested `lib/<dir>/x.md § Y` (e.g. lib/project-archetypes/*.md); (2) the real-census FILES list scans `skills agents lib rules hooks` only, not `templates/` nor `.claude/rules/`; (3) a citation of `.claude/rules/<f>.md § X` is read as `rules/<f>.md` (header comment admits it). Measured 2026-10-31: 0 real citations in these spots today, so the fix is preventive; each extension needs a flip-test fixture proving it bites.
|
||||
|
||||
## CLARIFICATIONS
|
||||
- Plan r2: `.claude/tasks/plans/2026-10-31-citers-blind-spots-0100.md`. T3 keeps its old scan roots; a bare `.claude/rules/` resolves by citer (this repo's .claude/rules → itself; skills/agents/templates → templates/project-rules). `~/.claude/…` and `$HOME/.claude/…` prefixes map to this repo's tree; a bare `.claude/rules/` is a project path.
|
||||
|
||||
## ACCEPTANCE CRITERIA
|
||||
1. The citers suite is green and holds the new checks T8a-T8h (plan r2); existing T1-T7c unchanged and green.
|
||||
CHECK: cd /home/bchanot/Documents/claude && out=$(make test suite=lib/tests/doctrine-citers.test.sh 2>&1) && printf '%s\n' "$out" | grep -q 'FAIL=0' && for n in T8a-nested-lib-resolves T8b-nested-lib-dangling T8c-project-rules-resolve T8d-project-rules-not-user-rules T8e-home-prefix-maps-to-repo T8f-scan-lists T8g-left-boundary T8h-template-rules-path; do grep -q "$n" lib/tests/doctrine-citers.test.sh || exit 1; done && echo CITERS-OK
|
||||
EXPECT: CITERS-OK
|
||||
EVIDENCE: MET exit=0 marker-found :: CITERS-OK
|
||||
2. The new checks bite: with the extraction, mapping and scan lists reverted to develop's versions (fixtures kept), T8a/T8b/T8c/T8d/T8f/T8g/T8h fail (the executor reports which); T8e fails against the r3 ERE with the home-prefix alternative removed (its own negative control). Judged by the verifier (the executor reports the negative control).
|
||||
3. Shellcheck clean, no added line over 80 columns, BSD-portable ERE (no grep -P).
|
||||
CHECK: cd /home/bchanot/Documents/claude && shellcheck lib/tests/doctrine-citers.test.sh && [ "$(git diff develop -- lib/tests/doctrine-citers.test.sh | grep '^+' | grep -v '^+++' | awk 'length($0) > 81' | wc -l)" = 0 ] && ! git diff develop -- lib/tests/doctrine-citers.test.sh | grep '^+' | grep -q 'grep -P' && echo LINT-OK
|
||||
EXPECT: LINT-OK
|
||||
EVIDENCE: MET exit=0 marker-found :: LINT-OK
|
||||
|
||||
## FILE SCOPE
|
||||
- lib/tests/doctrine-citers.test.sh
|
||||
@@ -0,0 +1,109 @@
|
||||
# /feat citers-blind-spots — PLAN r2
|
||||
|
||||
r2 2026-10-31 after 3 lenses: simplicity SOLID (2 MINOR), correctness CONCERNS(3),
|
||||
robustness CONCERNS(2). No BLOCKER. Changes named in § R2 CHANGES.
|
||||
|
||||
FEAT: doctrine-citers census blind spots — rule 7, 1 file
|
||||
(lib/tests/doctrine-citers.test.sh), one hoisted path ERE + citer-aware target
|
||||
mapping + a second scan list for T6 + flip-tests.
|
||||
|
||||
## Facts (2026-10-31, measured by the lenses)
|
||||
- develop's ERE `(rules|lib)/[a-z0-9-]+\.md` emits no row for a nested
|
||||
`lib/sub/x.md § Y` (blind, and a missing row reads as "resolves").
|
||||
- No left boundary: `templates/project-rules/ci.md § X` is read as
|
||||
`rules/ci.md`; `foo-rules/x.md` matches from `rules/`.
|
||||
- Real census FILES (`find skills agents lib rules hooks`) feeds BOTH T3
|
||||
(`CLAUDE.md "X"` vs CLAUDE.global.md) and T6 (file citations).
|
||||
`templates/` (12 .md) and `.claude/rules/` (4 .md) are never scanned. In
|
||||
those two trees `CLAUDE.md` means a PROJECT CLAUDE.md (templates/project-
|
||||
CLAUDE.md, templates/project-rules/ci.md:10), so T3 must not see them.
|
||||
- Bare `.claude/rules/<f>.md` has two meanings: inside this repo's own
|
||||
`.claude/rules/*` it is this repo; in skills/agents/templates it names the
|
||||
TARGET project's copy, emitted from `templates/project-rules/<f>.md`
|
||||
(agents/onboarder.md:135, agents/scaffolder.md:85).
|
||||
- 5 live home-prefixed citations (agents/interviewer.md:26, agents/commit-
|
||||
changer.md:220, lib/architecture-defaults.md:49, hooks/design-toolchain-
|
||||
reminder.sh:78, CLAUDE.global.md:261) resolve today through the suffix and
|
||||
must keep resolving against this repo (`~/.claude/{rules,lib}` link here).
|
||||
- 0 real citations in any blind spot today: preventive.
|
||||
|
||||
## Plan
|
||||
- [ ] One path ERE, hoisted into a variable used by both grep branches of
|
||||
`_citers_extract_files` (lines ≤ 80 cols, may span two assignments):
|
||||
left boundary `(^|[^A-Za-z0-9_-])` (captured, dropped by sed), then
|
||||
`((~|\$[{]?HOME[}]?)/\.claude/|\.claude/)?(templates/project-)?`
|
||||
`(rules|lib)/([a-z0-9-]+/)*[a-z0-9-]+\.md`.
|
||||
ONE sed over the `{ branch1; branch2; }` output strips an OPTIONAL
|
||||
boundary char of class `[^A-Za-z0-9_~$.-]` (absent at column 1: never eat
|
||||
the path's own first char) and a home prefix (`~/.claude/`, `$HOME/.claude/`, `${HOME}/.claude/`)
|
||||
→ repo-relative target. A bare `.claude/` stays in the target.
|
||||
- [ ] `citers_check_files`: citer-aware mapping of a bare `.claude/rules/<f>`
|
||||
target: citer path matches `.claude/rules/*` (or `*/.claude/rules/*`) →
|
||||
or `rules/*` (rules/README.md cites this repo's own .claude/rules) → keep
|
||||
`.claude/rules/<f>.md` (resolves against `$root/.claude/rules`); a citer
|
||||
under skills/ agents/ templates/ lib/ hooks/ or CLAUDE.global.md →
|
||||
`templates/project-rules/<f>.md`. A bare `.claude/lib/`
|
||||
stays as is (resolves against `$root/.claude/lib`, absent → DANGLING).
|
||||
- [ ] Scan lists: `FILES` (T3) unchanged roots `skills agents lib rules hooks`;
|
||||
new `FILES_ALL` = FILES roots + `templates` + `.claude/rules` (same name
|
||||
filter and excludes, find roots on a continuation line) feeds T6.
|
||||
- [ ] Header comment: lines 2-3 (scope list), 11-13, 59-63 (drop "would be
|
||||
read as rules/<f>.md"): nested dirs, home prefixes, the citer-aware
|
||||
`.claude/rules/` rule, `templates/project-rules/`, T3 vs T6 lists; an
|
||||
absolute `/home/<u>/…` path is unsupported (resolved as a bare
|
||||
`.claude/…` or suffix).
|
||||
- [ ] Fixtures (in the `$FIX` block, before the real census), check names:
|
||||
T8a-nested-lib-resolves: `_citers_extract_files` on `lib/sub/x.md § Alpha`
|
||||
emits exactly one `:lib/sub/x.md:Alpha` row AND citers_check_files rc 0
|
||||
with `$FIX/lib/sub/x.md` holding `## Alpha`.
|
||||
T8b-nested-lib-dangling: `lib/sub/x.md § Beta` → rc 1, culprit named.
|
||||
T8c-project-rules-resolve: a citer at `$FIX/.claude/rules/c.md` citing
|
||||
`.claude/rules/p.md § Gamma`, `$FIX/.claude/rules/p.md` holds `## Gamma`,
|
||||
no `$FIX/rules/p.md` → rc 0.
|
||||
T8d-project-rules-not-user-rules: a skill-side citer (`$FIX/s.md`) citing
|
||||
`.claude/rules/q.md § Delta`: rc 0 when `$FIX/templates/project-rules/
|
||||
q.md` holds `## Delta`; rc 1 when only `$FIX/rules/q.md` and
|
||||
`$FIX/.claude/rules/q.md` hold it.
|
||||
T8e-home-prefix-maps-to-repo: `~/.claude/rules/api.md § Versioning`,
|
||||
`${HOME}/.claude/lib/cc.md § WRITE`, and quoted
|
||||
`$HOME/.claude/lib/cc.md § "WRITE (before the commit)"` → rc 0
|
||||
(`# shellcheck disable=SC2016` on the single-quoted printf). Includes
|
||||
column-1 lines (`~/.claude/…`, `$HOME/.claude/…`). T8e is a guard of
|
||||
the new code, NOT a flip-test vs develop (develop resolves these by
|
||||
suffix): its negative control = the r3 ERE without the home
|
||||
alternative → the targets go bare `.claude/…` → DANGLING.
|
||||
T8c also carries a column-1 `.claude/rules/p.md § Gamma` line.
|
||||
T8g-left-boundary: `foo-rules/api.md § Versioning` → no row extracted.
|
||||
T8h-template-rules-path: `templates/project-rules/t.md § Eps` resolves
|
||||
against `$FIX/templates/project-rules/t.md` → rc 0; with a wrong label
|
||||
→ rc 1.
|
||||
T8f-scan-lists (placed right after the mapfiles): FILES_ALL holds ≥1
|
||||
`templates/` and ≥1 `.claude/rules/` path; FILES holds none.
|
||||
- [ ] T3 runs on FILES, T6 on FILES_ALL + CLAUDE.global.md; T4-T7c unchanged.
|
||||
|
||||
## Edge cases
|
||||
- grep -o is leftmost: a home or `templates/project-` prefix is captured
|
||||
whole when present.
|
||||
- `$HOME` / `${HOME}` are literal text in the scanned sources.
|
||||
- BSD-safe ERE, `/usr/bin/grep` pinned, no grep -P, no lookbehind.
|
||||
|
||||
## R2 CHANGES
|
||||
- ERE hoisted once, nested prefix, left boundary, `${HOME}`, `templates/
|
||||
project-` (simplicity 1, correctness 4/8, robustness 3/4).
|
||||
- Citer-aware `.claude/rules/` mapping (correctness 2, robustness 1;
|
||||
simplicity 2 documents it).
|
||||
- T3 keeps the old roots, T6 gets FILES_ALL (correctness 3, robustness 2).
|
||||
- T8a asserts the extracted row (correctness 1); T8e quoted + `${HOME}`
|
||||
(robustness 5); T8g, T8h added; T8f after mapfile (correctness 6); header
|
||||
lines 2-3 (correctness 7); live count 5 (correctness 5).
|
||||
|
||||
## R3 CHANGES (confirmation correctness CONCERNS(1), folded, no 3rd pass)
|
||||
- T8e reclassified: guard of the new code, own negative control (C1).
|
||||
- Boundary strip optional and excludes `~ $ .`; column-1 fixtures (C2).
|
||||
- Citers under rules/ map bare `.claude/rules/` to this repo (C3).
|
||||
- `\$[{]?HOME[}]?` instead of `\$\{?HOME\}?` (C4).
|
||||
|
||||
## Disposition
|
||||
Honors BDR-100 (the census is the mechanism) and LRN-096 (each extension has
|
||||
a flip-test that fails on develop's extractor: T8a row assert, T8b, T8c, T8d,
|
||||
T8g, T8h, T8f; T8e guards the new home mapping with its own negative control).
|
||||
Reference in new issue
Block a user