From 8693fff1d827a2ef53b3e0893700e6c493f57983 Mon Sep 17 00:00:00 2001 From: bchanot Date: Mon, 12 Oct 2026 22:51:53 +0200 Subject: [PATCH] chore(memory): code-clean run, LRN-213/214/215, EVAL-046, BDR-117, journal, TODO, plan + audits --- .claude/audits/BUGS-FOUND.md | 4 + .claude/audits/CODE-CLEAN-SCOPE.md | 172 ++++++++++++ .claude/memory/decisions.md | 8 + .claude/memory/evals.md | 7 + .claude/memory/journal.md | 4 + .claude/memory/learnings.md | 12 + .claude/tasks/TODO.md | 6 + .../tasks/plans/2026-10-12-code-clean-0103.md | 260 ++++++++++++++++++ 8 files changed, 473 insertions(+) create mode 100644 .claude/audits/BUGS-FOUND.md create mode 100644 .claude/audits/CODE-CLEAN-SCOPE.md create mode 100644 .claude/tasks/plans/2026-10-12-code-clean-0103.md diff --git a/.claude/audits/BUGS-FOUND.md b/.claude/audits/BUGS-FOUND.md new file mode 100644 index 0000000..fd9baf7 --- /dev/null +++ b/.claude/audits/BUGS-FOUND.md @@ -0,0 +1,4 @@ +# BUGS-FOUND + +- lib/toggle-external.sh:350 (pre-cleanup numbering; `usage()`, now near :370) — usage() prints header lines 3-26 only (`sed -n '3,26p'`); the managed-tool list continues to line 32, so `--help` omits 8 of the 14 tools. Severity: low (help text only). Discovered while: code-clean run 2026-10-12 (B5 audit). Not fixed (cleanup and bugfix are separate concerns). + FIXED 2026-10-12 (inline on chore/code-clean, no /bugfix pipeline): usage() now prints lines 3 .. closing banner (`sed -n '3,/^# ====/p' | sed '$d'`), no numeric range; --help shows all 14 tools (36 lines). diff --git a/.claude/audits/CODE-CLEAN-SCOPE.md b/.claude/audits/CODE-CLEAN-SCOPE.md new file mode 100644 index 0000000..8c23548 --- /dev/null +++ b/.claude/audits/CODE-CLEAN-SCOPE.md @@ -0,0 +1,172 @@ +# CODE-CLEAN SCOPE — approved 2026-10-12 — branch chore/code-clean + +Source plan: .claude/tasks/plans/2026-10-12-code-clean-0103.md (r3). +APPROVED: all non-deferred items = A1, B1, B2, B3, B4, B5, B7, B9, B11, B18, B19, B20, C2, C3. +NOT approved / untouched: B13-B17 (no change proposed), C1, C4, C5 (deferred). +Iron law: zero behavior change. No commit. Never switch branch. +Format below: file:line — item — severity — proposed fix (verbatim from the plan). + +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. + +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=/hooks/design-toolchain-reminder.sh` (:4), so + build a mirror tree `$T/hooks/` + `$T/lib/tests/` 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

` and `show

+ --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. + +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. + +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. + +B17 POLICY (no change proposed; applies to how the items above are written): +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). + +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. + +BUG TO LOG (executor appends to .claude/audits/BUGS-FOUND.md, never fixes): + +BASELINE: make test = 46 suites green before this run (scratchpad make-test-baseline.txt); shellcheck *.sh hooks/*.sh lib/*.sh exit 0. diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index b62e75c..d4299fe 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -134,6 +134,7 @@ rules: | BDR-110 | 2026-10-06 | Shell portability doctrine: native userland on macOS AND Linux, no Homebrew GNU tools on PATH; `lib/tests/portability-census.test.sh` locks deterministic GNU-only idioms | accepted | | BDR-115 | 2026-10-08 | model-router mod: pin = entry default, sub-tasks route finer; one writer per axis; full ids from the mod table; built-ins-only agents table until frontmatter pins go; state in closure | accepted | | BDR-116 | 2026-10-11 | model-router first-use confirmation: tracked routing.json = source of phases + rows + decisions; engine dialog at first use; project exceptions in user scope keyed by normalized remote; model never writes; census tolerates a decided row | accepted | +| BDR-117 | 2026-10-12 | shared gstack helpers live in lib/gstack-removed.sh, not in a new lib | accepted | --- @@ -1419,3 +1420,10 @@ Branch feature/user-writing-web-rules, UNMERGED (human gate). - **Alternatives rejected**: first-use dialog on classified phases (the TODO line said so; a dialog per plain prompt is noise and the phase is already confirmed through T3); writing the guess into routing.json; classifying mid-turn or sub-agent prompts; unbounded await (robustness BLOCKER r1: the classify call sat on the critical path with no clock race); `classify` as a tracked-file writer (session toggle + config key instead). - **Gates**: plan r1 → r3 (simplicity CONCERNS(4), robustness FATAL(6) BLOCKER unbounded await, correctness CONCERNS(4); confirmation robustness CONCERNS(4)); feater DONE (423) + 1 round (trim, argumentHint, repeated undefined: 428, each mutation-proven); GATE 0 MET; verifier ECARTS(2) coverage → CONFORME on #2; security PASS (0 findings; LOW accepted: pasted text can steer one turn's effort up, README says so). Abort paths judged by reading (`[gated]` clarification). Residual: `smallModelBusy` checks `cfg.models.haiku` while classify uses the engine's default small model (mismatch only when the two differ). Live AC9 open. - **Refs**: contract `.claude/tasks/contracts/2026-10-11-model-router-w4b-classifier-1858.md`, plan r3 same slug. Links [[EVAL-045]], [[LRN-210]]. + +## BDR-117 — shared gstack helpers live in lib/gstack-removed.sh, not in a new lib [accepted] (2026-10-12) +- **Decision**: C5 /refactor 2026-10-12. profile.sh + toggle-external.sh duplicated gstack_skills + park/unpark moves. Host gstack_skills/gstack_parked_names/gstack_park/gstack_unpark in lib/gstack-removed.sh; each takes dirs as args, no caller globals; plain-statement call only (errexit, [[LRN-215]]). +- **Why**: only sourced file 5 fixture suites copy next to both scripts; new lib = every fixture breaks. +- **Alternatives rejected**: new lib/gstack-helpers.sh + patch 5 fixtures (wider diff, fixture drift risk); keep twins (3 copies drifted once already). +- **Cost**: file name says denylist, now hosts helpers; header comment states it. +- **Refs**: commit 8444661. Links [[LRN-215]], [[EVAL-046]]. diff --git a/.claude/memory/evals.md b/.claude/memory/evals.md index 18f7b5e..30f038a 100644 --- a/.claude/memory/evals.md +++ b/.claude/memory/evals.md @@ -418,3 +418,10 @@ Dogfood: 3 blind lenses attacked the v1 plan for the plan-challenge feature itse - **Method**: simplicity CONCERNS(4), robustness FATAL(6) (BLOCKER: the classify await sat unbounded on the prompt's critical path → `$.clock.sleep` race, abort not counted, post-await re-check), correctness CONCERNS(4) → r2; confirmation robustness CONCERNS(4) → r3. Feater DONE (423, 5 mutation proofs); GATE 0 MET; verifier #1 ECARTS(2) (no test on `trim`, none on the argumentHint) → feater (+5 tests, each failing under its mutation; first trim tests passed without the trim because the length guard caught them, lengthened) → verifier #2 CONFORME 8/8, criterion 9 gated. Security PASS, 0 findings, 1 LOW accepted. - **Anomaly**: none on the loop. Verifier observations worth keeping: the sub-agent test proves only spawn+step never calls classify (`prompt.submit` has no agent form in the API types); the 3-s tests pin the upper bound only; the post-await re-check is tested through the route-landing case alone. Security note: `smallModelBusy` guards `cfg.models.haiku`, classify uses the engine small model. - **Action**: keep the W4-B contract shape as the template (one clause per criterion, kit-untestable paths listed in CLARIFICATIONS before the first verifier); the live AC9 check is the real oracle for label quality (drop `bookkeeping` if it misfires). Links [[EVAL-044]], [[BDR-116]], [[LRN-210]], [[LRN-212]]. + +## EVAL-046 — code-clean: 3 lenses + 1 confirmation turned a half-wrong r1 into a byte-identical 14-item cleanup +- **Date**: 2026-10-12 +- **Output checked**: plan `.claude/tasks/plans/2026-10-12-code-clean-0103.md` r1 → r3; code-cleaner diff on chore/code-clean (13 files, +299/−230). +- **Method**: correctness FATAL(6), robustness FATAL(5), simplicity CONCERNS(5), confirmation CONCERNS(2). Independent re-check of the executor: `make test` 47 green, shellcheck 0, hook `$pattern` sha256 identical old/new, old vs new google_seo.py no-arg run byte-identical (stdout, stderr, rc). +- **Anomaly**: r1 wrong on 5 points (directive placement, logic-line counter ignored the error-handling exclusion → 1 false positive + 3 reclassified, B18 half false: 2 of 4 sites already `local`, C1 move would silently void T19, `|| return $?` rule inverted). Executor denied once (`rm -rf` on a variable path), used a fresh dir, reported it. Scope file's BUG TO LOG block came out empty (regex cut at the heading) — executor fell back to the plan. Two golden gaps left open by executor (gstack-absent warning, pack_hints with stubbed CLI). +- **Action**: keep the confirmation pass after a material rewrite (it caught 2 MAJOR the first round missed). Scope writer: assert every section non-empty before dispatch. Links [[LRN-213]], [[LRN-214]], [[LRN-215]]. diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index 91bff09..bfcb1d9 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -602,3 +602,7 @@ rules: - model-router W4-A landed 68d7ea6 on feature/model-router-w4 (+ data commit). User: fewer logs (one line per real change with a cause), residuals, then the classifier. Plan r1→r3: three lenses (BLOCKER: an agent's model move is decided at spawn; `trace` level rejected as unrequested surface; reuse lastPlan/Loop; cause from the decision), confirmation CONCERNS(5) (hand-off line per dispatch deduped per type+target). Feater DONE (341 tests) + 4 rounds; verifier ECARTS(3) real (dedupe on text, double host prefix) then coverage ×2 → cap → user accepted; security PASS + 2 MEDIUM (raw skill names) fixed. Live: the terminal logs changed as soon as the feater saved; user Kept plan-challenger (judge) and the judge phase. Next: W4-B classifier; push-guard hotfix queued. - model-router W4-B prompt classifier landed e54a2b5 on feature/model-router-w4. Plain composer prompt with no route in force → `$.model.classify` (5 labels, head 500 + tail 1500) → turn effort only, 3-s clock race, 3 failures pause, `/route classify on|off`. Plan r1→r3 (robustness BLOCKER: unbounded await), feater DONE + 1 round (trim, argumentHint), verifier ECARTS(2) → CONFORME, security PASS 0 findings. No live routing.json change this wave. Branch carries W4-A + W4-B (5 commits), unmerged, unpushed: merge on signal, user publishes. Live AC9 (plain prompts labelled) open. - Residual sweep (user: "corrige le push-guard, et aussi corrige les residus"). bugfix/push-guard-argv fe7d5cd: text regex = prefilter, awk tokenizer splits simple commands (quotes, heredocs, separators), push = git argv[0] + push/send-pack subcommand; wrappers/assignments/subtree/no-awk keep text verdict; `"git" push` miss closed; suite 98→124. bugfix/model-router-residuals a3fbb9a + 85ef5e1 (data: analyzer judge Keep, stale changed entry purged): kill switch fail closed (broken override first load, non-boolean enabled), reload answer honest, NESTED_QUANT, stat.kind, errWord, keyWord + KEY_NAME aliases, BAD_KEYS, offers cap, default chain withEveryAlias, canonical `-` boundary, tryLog/safely on step path, route-tool text; mods probe usage line, doctor timeout, update-all skips @skills-dir. Kit 431/431, full make test green (design-tool-gate green too). Both branches pushed, UNMERGED (human signal). Stale remote-tracking refs pruned (server had already dropped them). Done without /bugfix pipeline (no challengers/verifier/security gate): stated to user. Live checks left to user. + +## 2026-10-12 +- /code-clean whole repo on chore/code-clean (gitflow start, pushed). Plan r1→r3: 3 lenses + confirmation, C1 (gitflow-test.sh move) deferred ×2 lenses, B18 half false, C3 needed stderr oracle, errexit rule inverted. User approved all 14 non-deferred items. code-cleaner DONE: A1 import, B1-B4 lint/hook regex (sha identical), B5/B7/B9/B11 splits, B18-B20, C2 suite wired, C3 hoist. make test 47 green, shellcheck 0, verified independently. 1 bug logged (usage() 3-26 truncation). No commit. LRN-213/214/215, EVAL-046. Next (user: "capitalize all then correct bugs with what has been skipped"): usage() fix inline, C4/C5 via /refactor; C1 + B13-B17 left (blocked / no-change by design). +- Follow-up (same branch, no commit): usage() bug fixed inline (`sed -n '3,/^# ====/p' | sed '$d'`, --help 36 lines, 14 tools). /refactor → refactorer: C4 `tool_kind`/`tool_source` single roster (exact-match loop, not the `*" $x "*` idiom: multi-word arg stayed unknown), `disable_*` split mirrors `enable_*`; C5 shared `gstack_skills/parked_names/park/unpark` in lib/gstack-removed.sh (already copied by all 5 fixtures; new sourced lib would break them). 496-run golden capture identical except `${name:?}` diagnostic line ref for an empty `gstack__` dir. Verified: make test 47 green, shellcheck 0. Left: C1 (T19 lock), B13-B17 (no change), `name` leak in enable_pack. Commit split suggested: cleanup / usage fix / C4-C5. diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md index 78c4e5c..92b8c1a 100644 --- a/.claude/memory/learnings.md +++ b/.claude/memory/learnings.md @@ -1789,3 +1789,15 @@ Rule: when editing a doctrine file under structure locks, grep the test's lock s - **Context**: W3-A, 2026-10-10. Mid-run, `routing.json` gained decisions nobody expected (verifier → judge, feater → judge). First read: a kit test wrote the real file. Truth (feater, transcript timestamps = file mtimes to the second): the engine had reloaded `register.ts` from the working tree through the `skills/model-router` link, the live mod opened the T2 dialog on MY verifier/feater spawns, the user answered them in the terminal. The kit cannot write: an unmocked `fs.write` is refused ("no implementation"), a throwing mock lands on the same refusal; the real file's sha was stable across 10+ suite runs. - **Apply**: while a mod is under development in this repo, its working-tree code is LIVE in every session (no `/reload-plugins` needed): expect its side effects (dialogs, writes) during the gates; tell the user what dialogs will pop and what to answer; reset the data file deliberately at the gate. Blame the kit last: check mtimes against the transcript before assuming a test leak. Live answers = criterion evidence (record them `[gated]`). Links [[BDR-116]], [[LRN-206]], [[LRN-211]]. + +## LRN-213 — grep-based dead-function census misses constructed-name callers +- **Context**: code-clean 2026-10-12. `detect_gstack` / `detect_plugin_dev` (lib/detect-plugins.sh) had zero literal callers → flagged dead. Real caller: hooks/session-start.sh:80 `if "detect_$plugin"` over a name list. Deleting them = silent hook break on every session start. +- **Apply**: before calling a function dead, grep its PREFIX in a quoted-expansion form (`"prefix_$`, `prefix_${`, `eval`, `declare -f`) and any name-list loop. Constructed dispatch = exclude + note in the plan so challengers do not re-raise. Links [[LRN-214]]. + +## LRN-214 — shellcheck directive after the first command scopes to that command only; file-wide disable goes BEFORE `set -u` +- **Context**: code-clean r1 placed `# shellcheck disable=SC2015` after `set -u` in seo-data.test.sh → two lenses proved via stdin that 26 of 27 sites stay red. Precedent in repo: lib/tests/effort-routing.test.sh:8 (before any command) silences file-wide. +- **Apply**: file-level directive = between the shebang and the first command. Prove with `shellcheck` exit 0 on the edited file, not by reading. Links [[LRN-213]], [[LRN-215]]. + +## LRN-215 — helper extracted from a `set -e` function must be called as a plain statement; `helper || …` / `if helper` switches errexit OFF inside it +- **Context**: code-clean B5/B7/B9 split enable_tool / enable_skill / cmd_show out of `set -euo pipefail` scripts. r2 executor rule said `|| return $?`; confirmation lens: that form disables errexit inside the helper, so a failed `mv` (toggle-external.sh:273) would print `ok …` rc 0 instead of aborting — a path no golden capture sees. Plain call keeps `return 1` → errexit in caller → exit 1 as today. +- **Apply**: split rule for -e scripts: plain calls only, never `||`, `&&`, `if`, `!` around an extracted helper. Golden capture (stdout + stderr + rc + fixture tree) before/after for every moved arm when the suite discards output. Links [[LRN-214]], [[EVAL-046]]. diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index b49a130..3277004 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -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; diff --git a/.claude/tasks/plans/2026-10-12-code-clean-0103.md b/.claude/tasks/plans/2026-10-12-code-clean-0103.md new file mode 100644 index 0000000..853ba7d --- /dev/null +++ b/.claude/tasks/plans/2026-10-12-code-clean-0103.md @@ -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=/hooks/design-toolchain-reminder.sh` (:4), so + build a mirror tree `$T/hooks/` + `$T/lib/tests/` 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

` and `show

+ --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.