chore(memory): code-clean run, LRN-213/214/215, EVAL-046, BDR-117, journal, TODO, plan + audits

This commit is contained in:
bchanot committed 2026-10-12 22:51:53 +02:00
1 parent 84446612ae
commit 8693fff1d8
8 files changed
+473

No files matched your search

+6
View File
@@ -1,5 +1,11 @@
# TODO
## 2026-10-12 — code-clean whole repo (chore/code-clean)
- [x] audit r1→r3 (3 lenses + confirmation), user approved all 14 non-deferred items, code-cleaner DONE, make test 47 green — plan `.claude/tasks/plans/2026-10-12-code-clean-0103.md`, scope `.claude/audits/CODE-CLEAN-SCOPE.md`
- [x] fix BUGS-FOUND: toggle-external.sh usage() prints header 3-26, list ends at 32
- [x] C4/C5 deferred dedupes via /refactor (tool_kind/tool_source + shared gstack_* in lib/gstack-removed.sh; 496-run golden identical) (tool list ×4, profile/toggle-external twins)
- deferred: C1 gitflow-test.sh move (blocked: T19 drift lock), B13-B17 (no change by design)
## 2026-10-08 — model-router mod: one mod routes model + effort per request (feature/model-router-mod)
Plan `.claude/tasks/plans/2026-10-08-model-router-mod.md`. Decisions 2026-10-08: main-loop
model switch spike-first then flag off; load via `CLAUDE_CODE_PLUGIN_DIRS` + link.sh;
@@ -0,0 +1,260 @@
# CODE-CLEAN AUDIT — whole repository (claude-config), 2026-10-12 — r3
r2 = r1 after the 3-lens challenge (correctness FATAL(6), robustness FATAL(5),
simplicity CONCERNS(5)). r3 = r2 after the confirmation pass (correctness
CONCERNS(2): B18 half void, C3 without a stderr oracle; 5 MINOR). Every
BLOCKER/MAJOR is closed by a named change below or tagged
[deferred 2026-10-12] for the human gate.
Proposed cleanup scope (KIND = proposals). Iron law: zero behavior change —
identical observable output before and after every item; the items that DO
carry a delta are tagged `delta:` explicitly (B3, C2).
Scanned: 98 shell files (~16.5K lines, incl. the 4 git hooks × 2 copies),
13 Python files (~2.3K lines), 2 TypeScript files (8.6K lines, the
model-router mod), Makefile. Markdown/JSON are out of scope.
Norms source: CLAUDE.global.md limits (25 logic lines/function, 80 chars/line,
5 params, 5 locals; comments and error-handling boilerplate NOT counted) +
project CLAUDE.md Health Stack (`shellcheck *.sh hooks/*.sh lib/*.sh` — a
non-recursive glob: lib/tests/ and lib/seo-data/ are outside it, exit 0
today). No .editorconfig / .shellcheckrc / pyproject / tsconfig tracked.
Tools: shellcheck (37 notes in 4 files, 0 errors); AST scan for Python;
regex scan for TypeScript; logic-line counter for shell, re-run in r2 WITH
the error-handling exclusion (err/warn/info/ok lines, `>&2` diagnostics,
`return N`, except/raise/sys.exit, degraded returns); word-boundary
reference census for every function and script; `diff` for duplicate blocks.
Baseline: `make test` all 46 suites green, exit 0 (2026-10-12 00:5x).
Format: `file:line — description — severity — proposed fix`
═══ DEAD CODE ═══
A1. lib/seo-data/safe_fetch.py:30 — `import gzip` unused (gzip appears only in
comments at :137 and :153) — warn — delete the import line. The `gzip`
token in the stdlib-only ALLOWLIST at lib/seo-data/seo-data.test.sh:143
stays: it is a list of permitted stdlib names, not a usage assertion.
Checked and NOT listed:
- lib/detect-plugins.sh:28 `detect_gstack`, :41 `detect_plugin_dev`: zero
literal callers but CALLED by constructed name at hooks/session-start.sh:80
(`"detect_$plugin"`). Live. Do not delete.
- No commented-out code; no TODO/FIXME/XXX/HACK in executable code (the two
`shortcut:` markers, lib/floor-guard.sh:106 and register.ts:3423, are
by-design, dated 2026-09-28 / 2026-10-09).
- TypeScript: 0 symbols with ≤1 reference; only export is `register`.
- Python: 0 dead locals, 0 unused functions.
- Every lib/*.sh, lib/*.py, hooks/*.sh has ≥1 non-test caller.
═══ STYLE VIOLATIONS ═══
B1. lib/seo-data/seo-data.test.sh (27 sites, SC2015 `[ … ] && ok … || no …`;
`ok`/`no` never fail) — warn, outside the Health Stack glob — insert on
line 3, BEFORE `set -u` (a directive after the first command scopes to the
next command only; r1 had it wrong):
`# shellcheck disable=SC2015 # A && ok || no is deliberate (ok/no never fail)`
— the convention of lib/tests/effort-routing.test.sh:8/:9. Prove:
`shellcheck lib/seo-data/seo-data.test.sh` exits 0. Zero behavior change.
B2. lib/tests/url-guard.test.sh:21,22,33,34,60,61 and
lib/tests/push-guard.test.sh:108-110 (SC2016: single-quoted `$(…)` /
backticks are the commands under test) — warn, outside the Health Stack
glob — file-level `# shellcheck disable=SC2016 # single-quoted forms are
the commands under test` placed BEFORE the first command (url-guard line
3, push-guard line 5), as lib/tests/guard-bash.test.sh:5. Prove: shellcheck
exits 0 on both.
B3. lib/tests/run-review-guards.sh:14 — `cd "$REPO"` unguarded (SC2164);
under `set -uo pipefail` a failed cd runs every guard in the wrong
directory — warn — `cd "$REPO" || exit 1`. delta: cd-failure path only
(silent wrong-dir run → loud exit 1).
B4. hooks/design-toolchain-reminder.sh:51 — one 972-char regex literal — warn
— split into `pattern='…'` + `pattern+='|…'` lines ≤80 chars, IN THE
CURRENT ALTERNATIVE ORDER (no regrouping: the sha256 must match). This
hook runs live on every UserPromptSubmit of every session (settings.json
wires ~/.claude/hooks → repo hooks/); a syntax error = exit 2 = every
prompt blocked. Procedure: build on a scratch copy, `bash -n`, then
`printf '%s' "$pattern" | sha256sum` old vs new must match, then the
suite lib/tests/design-toolchain-reminder.test.sh run on the copy — the
suite hardcodes `$H=<root>/hooks/design-toolchain-reminder.sh` (:4), so
build a mirror tree `$T/hooks/<copy>` + `$T/lib/tests/<suite copy>` and
run the suite from there, never edit the suite — then land it in ONE
write. Zero behavior change.
B5. lib/toggle-external.sh:257 — `enable_tool()` 49 logic lines after the
error-handling exclusion (max 25) — warn — split by case arm:
`enable_gstack`, `enable_external_single` (the 11-name arm, darwin-skill
src branch included), `enable_pack` (21st|higgsfield); `enable_tool`
keeps only the dispatch `case`. Every `ok`/`warn`/`err` string and return
code unchanged. Lines 1-32 of the file untouched (usage() prints 3-26).
Coverage: `enable gstack` by lib/tests/gstack-removed.test.sh:43,55; the
darwin-skill branch has NO suite → golden capture mandatory (see
EXECUTOR CONSTRAINTS).
B7. lib/profile.sh:321 — `enable_skill()` 41 logic lines — warn — extract the
three large arms: `enable_gstack_skill`, `enable_linked_skill`
(external|personal; NOT "managed", a term of art for the MANAGED_*
allowlists), `enable_plugin_skill` (plugin@*); the plugin / mcp / cli
arms stay inline. Twin of toggle-external's arms (see C5), kept separate:
merging changes messages. Golden capture mandatory: the profile suites
discard output (`>/dev/null 2>&1`).
B9. lib/profile.sh:575 — `cmd_show()` 32 logic lines AND 14 distinct locals
(max 5; outcome: logic lines ≤25 per function, locals reduced, NOT to
≤5 — whichever helper keeps the header still holds prof/file/desc/
skills/pl/m/c/total) — warn — extract `_show_plain "$prof"` (the `--plain` branch) and
`_show_grouped "$prof"`; each helper takes `$prof` and iterates
`read_profile` itself. NO `local -n` (zero namerefs in the repo, bash
≥4.3 only). `_show_plain` MUST end with an explicit `return 0`: profile.sh
runs `set -euo pipefail` and the loop's last `[ … ] && printf` returns 1
whenever the last entry is not `cli` (dev/qa/seo today) — without it the
helper's rc 1 kills the script after printing (reproduced), and
lib/design-tool-gate.sh:202 turns that into `exit 2`. No suite runs the
real cmd_show (design-tool-gate.test.sh fakes profile.sh) → characterization
oracle: stdout + rc of `bash lib/profile.sh show <p>` and `show <p>
--plain` for EVERY lib/profiles/*.profile, captured before and after,
byte-identical. Grouped mode calls `claude plugin list` / `claude mcp
list` live via skill_status (:270-297): run both captures with the same
fixed `CLAUDE_BIN` stub so session state cannot drift between them.
minimal.profile (0 entries) covers the `Total: 0` branch.
B11. lib/seo-data/google_seo.py:217 — `_cli()` 40 logic lines — warn —
extract `_build_parser()` (the four sub-parsers; name already used by
content_quality.py and schema_gen.py) and `_dispatch(args)`; the
try/except envelope (bad_usage / degraded) stays in `_cli`. The
`bad_usage` path has no test → golden capture of stdout + rc for one
bad invocation and each of the 4 verbs in mock mode.
B13. Borderline (26–29 logic lines after the exclusion) — info — leave; a
split for 1–4 lines is churn: lib/toggle-external.sh:207 disable_tool
(28), lib/profile.sh:416 disable_skill (27), lib/seo-data/sitemap.py:133
sitemap (29, 6-8 lines are except→degraded returns), doctor.sh:340
inspect_automode (28), lib/design-tool-gate.sh:160 tool_active (27),
lib/profile.sh:252 skill_status (27), lib/profile.sh:671 cmd_gstack (27),
skills/client-handover/scripts/handover-to-pdf.sh:154 tag_bare_url_links
(27), lib/seo-data/tokenstore.py:85 _cli (26), register.ts:3314
registerSpawn (26), :3344 registerTurns (26). (r1's B6/B8/B12 land here.)
Dropped as a false positive: r1 B10 lib/doc-commit.sh:77 commit_docs —
18 logic lines once its four fail-closed blocks (rc 3/3/4/5) are
excluded; a split would scatter the BDR-022 guard that IS the file and
break the shape match with its twin commit_memory (memory-commit.sh:51).
B14. Over the limit but not logic — info — leave: hooks/push-guard.sh:99
simple_cmds (one awk program); lib/doctor-vendored.sh:80 and
lib/vendor-skills.sh:91 (embedded Python heredocs); lib/profile.sh:755
usage (help text); lib/tests/profile-census.test.sh:41 census_check
(embedded Python); register.ts:896 newState (one 43-field literal), :560
mergeConfig (one return literal), :1607 handleCommand (flat switch);
register.test.ts:59/:130/:3610 (fixtures).
B15. Params > 5: lib/seo-data/schema_gen.py:20 reservation (9), :85
discussion (8), :111 profile (8); google_seo.py:101 queries (6) — info —
keyword-only, mirror the CLI flags one-to-one, one caller each. Leave.
B16. Locals > 5 (norm listed, r1 had no section) — info — leave; census from
the correctness lens, verified only for cmd_show (14, reduced not
closed by B9):
lib/vendor-skills.sh vendor_pinned_skills (~11), lib/gstack-playwright.sh
gstack_browsers_report (~9), _vendor_install_skill / profile.sh
count_profile / cmd_list (~8 each), google_seo.py _cli (8, reduced by
B11). Not proposed: each is a sequential CLI/report body; splitting for
the count alone is churn.
B17. Lines > 80 chars: 1273 in 78 shell files, 46 in Python (6 of them
docstrings), 5 in TypeScript — info — ALL DEFERRED to "enforce on new
code" (r1 proposed the Python/TS subset; dropped: no formatter tracked so
it would not hold, 5 of google_seo's lines sit inside B11's `_cli`, and
the register.ts lines are in a live-loaded mod with a `make test` gate
that SKIPs when `claude plugin test` is absent). Lines MOVED by B5, B7,
B9, B11, C3 keep their current length (toggle-external.sh:280, 285-287,
325, 334; deploy-commit.sh:53, :55; profile.sh:349, 385, 393, 402 are
>80 today): rewrapping a message string can change output. B17 applies
only to lines newly written in this run (function headers, calls).
B18. lib/profile.sh:188 (gstack_skills) and lib/toggle-external.sh:167
(gstack_skills) — `for d in` loops with no `local d`: `d` leaks as a
global (norm: no global state); no reader of `$d` outside those loops,
and every caller reads the function through `< <(gstack_skills …)`
(profile.sh:507, toggle-external.sh:181, :222), so the leak never
reaches a caller — warn — add `local d` in each. r2 also listed
toggle-external.sh:70 and :98: FALSE, both already declare `local d`
(:69, :97); dropped. Same class, same fix, added in r3:
toggle-external.sh:263 `for entry in` (inside the gstack arm B5 moves
into enable_gstack — declare `local entry` there) and :344 `for t in`
(cmd_status → `local t`). Zero behavior change.
B19. lib/toggle-external.sh:119-121 — comment says "this script takes no extra
`source`" but :50 sources lib/gstack-removed.sh and both fixture suites
copy it alongside (higgsfield.test.sh:180,
toggle-external-repo-resolution.test.sh:20) — info — reword the comment.
B20. lib/detect-plugins.sh:4 — header "Sourced by:" omits update-all.sh:19 —
info — add it.
═══ STRUCTURAL ISSUES ═══
C1. [deferred 2026-10-12] lib/gitflow-test.sh — only suite outside lib/tests/
and only `-test.sh` name (38 siblings are lib/tests/*.test.sh). r1
proposed a move; BOTH challengers (correctness, robustness) BLOCKED it:
the file resolves 22 paths from `$HERE` (15× `$HERE/gitflow.sh`, 7×
`$HERE/../`), and :434/:442 guard T19a-e with `[ -d "$HERE/../.githooks" ]`
— after a move those fall to lib/.githooks (absent) and print
`ok "T19 skipped"`, silently voiding the ONLY drift lock on post-commit /
post-merge / reference-transaction. Plus: 14 `CHECK:` lines in 7 durable
contracts run the old path, .gitleaks.toml:56,59 cite it, lib/tests/ is
outside the Health Stack glob, and the `== lib/gitflow-test.sh` line /
suite order of `make test` change. Cosmetic payoff. Deferred: not in this
run unless the human explicitly asks; the safe form would be
`HERE="$(cd "$(dirname "$0")/.." && pwd)"` plus every citer, with a
`grep -c 'ok T19'` before/after proof.
C2. skills/prune-memory/tests/run-deterministic.sh — hermetic deterministic
suite (mktemp sandbox, 5 oracles, ALL GREEN today) absent from Makefile
SUITES — info, delta: `make test` gains one suite block and one new way
to go red — add the LITERAL tracked path
`skills/prune-memory/tests/run-deterministic.sh` to Makefile:31 (NOT a
`skills/*/…` glob: skills/ holds symlinks to vendored and out-of-repo
trees, a glob would execute unreviewed third-party tests and make the
suite set machine-dependent). Caveat for the human: the suite executes
bash blocks extracted from prune-memory SKILL.md headings, so wiring it
locks that doc's headings under `make test`.
C3. lib/deploy-commit.sh:51-57 and :62-68 — verbatim identical 7-line
REFUSED block (`diff` empty) in the `pending` and `commit` arms — warn —
hoist into `_refuse_outside_allowlist "$@"` (`local violations;
mapfile -t violations …` + the `{ … } >&2; exit 4` block). Define it
with the other `_` helpers ABOVE line 46 (the script runs `set -uo
pipefail` without -e: a helper defined after `esac` would give rc 127
and the arm would carry on to `git add` out-of-scope paths); call it as
a plain statement so `exit 4` ends the script exactly as today, and
keep the post-`shift` `"$@"` (:60). stderr text byte-identical — but
lib/tests/deploy-commit.test.sh runs every rc-4 case with `>/dev/null
2>&1` (:19, :22, :26, :46) and checks rc + commit count only, and the
calling skill parses the REFUSED text (deploy-commit.sh:13-15) → golden
capture of stdout + stderr + rc, before and after, in a mkrepo-style
sandbox for `pending src.txt`, `commit x src.txt` and one mixed
in-scope + out-of-scope call.
C4. [done 2026-10-12 via /refactor, refactorer on chore/code-clean — was deferred] lib/toggle-external.sh — the same 10/11-name tool
list repeated at :58-63, :184-186, :225-228, :285-288 (+ header :20-32):
adding a tool takes 5 edits — info — resolve the kind once from a single
array (membership idiom already at :101). Not in this run: it reshapes
the case arms B5 splits and the status_tool arm order; a follow-up
/refactor after B5 lands.
C5. [done 2026-10-12 via /refactor, refactorer on chore/code-clean — was deferred] Twin implementations across lib/profile.sh and
lib/toggle-external.sh: `gstack_skills` (:184 / :164, same loop),
enable_all_gstack (:479) vs the enable gstack arm (:261), the external
from-source path (:363 says "mirrors toggle-external.sh") — info —
merging changes messages, not zero-behavior; logged for a design pass.
B5/B7 name their helpers so the twin relation stays visible.
BUG TO LOG (executor appends to .claude/audits/BUGS-FOUND.md, never fixes):
- lib/toggle-external.sh:350 usage() prints header lines 3-26 only; the
managed-tool list continues to :32, so `--help` omits 8 of 14 tools.
Checked, not an issue: githooks/ and .githooks/ byte-identical (by design);
lib/seo-data/seo-data.test.sh co-located with its engine; .claude/tasks/
contracts/*.{sh,py} durable oracles, out of scope; profile.sh's unprefixed
CLI-style function names, per-file convention.
EXECUTOR CONSTRAINTS (apply to every approved item):
- Golden capture BEFORE any edit, diff AFTER: stdout, stderr, rc (and the
fixture tree where a mv/rm arm is moved) for every moved arm and CLI verb
— the suites that "cover" B5/B7/B9/B11/C3 discard output or fake the
script.
- Hook-safe landing for B4 (scratch copy → bash -n → sha256 → suite → one
write). No edit to register.ts in this run.
- No `local -n`, no new bash ≥4 construct, no new dependency.
- Return codes: toggle-external.sh:40 and profile.sh:49 run `set -euo
pipefail`. Call every extracted helper (B5, B7, B9) as a PLAIN statement
— never `helper || …`, `helper && …`, `if helper`, `! helper`: those
switch errexit OFF inside the helper, so a failed `mv`
(toggle-external.sh:273, profile.sh:330) that aborts with rc 1 today would
instead continue and print `ok …` with rc 0, a path no golden capture
exercises. A plain call keeps `return 1` (toggle-external.sh:305, :326)
→ errexit in the caller → exit 1 through main (:359), as today. C3 uses
`exit`, not `return`, and is covered by its own placement rule.
- `make test` full run after; shellcheck on every touched file.
TOTALS: 0 blocking, 11 warn (A1, B1, B2, B3, B4, B5, B7, B9, B11, B18, C3),
8 info (B13–B17, B19, B20, C2 — of which B13–B17 propose no change),
3 deferred for the human (C1, C4, C5), 1 bug to log.