Merge chore/code-clean into develop

This commit is contained in:
bchanot committed 2026-10-12 22:56:20 +02:00
commit 95f87cf4e3
21 files changed
+903 -326

No files matched your search

+4
View File
@@ -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).
+172
View File
@@ -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=<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.
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.
+8
View File
@@ -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]].
+7
View File
@@ -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]].
+4
View File
@@ -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.
+12
View File
@@ -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]].
+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.
+1 -1
View File
@@ -28,7 +28,7 @@ seo-connect: ## Connect a Google account for /seo FULL (creates venv, OAuth cons
@bash -c 'read -r -p "Label for this account (e.g. client-a): " label; \
bash lib/seo-data/connect.sh --label "$$label"'
SUITES = lib/tests/*.test.sh lib/seo-data/*.test.sh lib/gitflow-test.sh lib/tests/run-*.sh
SUITES = lib/tests/*.test.sh lib/seo-data/*.test.sh lib/gitflow-test.sh lib/tests/run-*.sh skills/prune-memory/tests/run-deterministic.sh
test: ## Run deterministic tests hermetically (one: make test suite=lib/tests/x.test.sh)
@# Hermetic git: the machine's global core.hooksPath (BDR-095) must not
@# fire inside the throwaway repos the suites build. The export lives
+15 -1
View File
@@ -48,7 +48,21 @@ lc="$(printf '%s' "$prompt" | tr '[:upper:]' '[:lower:]')"
# French prose ("changement ux vu…"; 2 logged FPs, both FR). \bui\b KEPT
# (zero logged FP, one logged true positive). NB: the log records only the
# FIRST match per fire (head -1), so per-token FP rates aren't derivable.
pattern='redesign|refonte|refont|ui/ux|ux/ui|\bui\b|ui kit|design system|design-system|front-?end design|\bnavbar\b|\bsidebar\b|\bmodal\b|\bbouton\b|\bbutton\b|formulaire|\bhero\b|\bheader\b|\bfooter\b|dropdown|tooltip|\bbadge\b|\bchart\b|graphique|accordion|carousel|\bslider\b|landing|\bdashboard\b|homepage|home page|\baccueil\b|\bécran\b|\becran\b|portfolio|maquette|mockup|wireframe|prototype|\bjoli\b|\bjolie\b|\bbeau\b|\bbelle\b|esth[eé]tique|aesthetic|\bvisuel\b|\bvisual\b|embellir|fignol|peaufin|polish|styliser|styling|stylesheet|\bskin\b|charte graphique|\bbrand\b|branding|\blogo\b|favicon|ic[oô]ne|\bicon\b|\bcss\b|tailwind|shadcn|couleur|gradient|d[eé]grad[eé]|\bombre\b|spacing|espacement|\bmarge\b|\bpadding\b|\bmargin\b|\bradius\b|arrondi|\bhover\b|dark mode|light mode|typograph|\bfont\b|\bfonts\b|font pairing|\bpolice\b|animation|\bmotion\b|micro-interaction|keyframe|glassmorph|neumorph|claymorph|skeuomorph|brutalis|bento|minimalis|responsive|figma'
pattern='redesign|refonte|refont|ui/ux|ux/ui|\bui\b|ui kit|design system'
pattern+='|design-system|front-?end design|\bnavbar\b|\bsidebar\b|\bmodal\b'
pattern+='|\bbouton\b|\bbutton\b|formulaire|\bhero\b|\bheader\b|\bfooter\b'
pattern+='|dropdown|tooltip|\bbadge\b|\bchart\b|graphique|accordion|carousel'
pattern+='|\bslider\b|landing|\bdashboard\b|homepage|home page|\baccueil\b'
pattern+='|\bécran\b|\becran\b|portfolio|maquette|mockup|wireframe|prototype'
pattern+='|\bjoli\b|\bjolie\b|\bbeau\b|\bbelle\b|esth[eé]tique|aesthetic'
pattern+='|\bvisuel\b|\bvisual\b|embellir|fignol|peaufin|polish|styliser'
pattern+='|styling|stylesheet|\bskin\b|charte graphique|\bbrand\b|branding'
pattern+='|\blogo\b|favicon|ic[oô]ne|\bicon\b|\bcss\b|tailwind|shadcn|couleur'
pattern+='|gradient|d[eé]grad[eé]|\bombre\b|spacing|espacement|\bmarge\b'
pattern+='|\bpadding\b|\bmargin\b|\bradius\b|arrondi|\bhover\b|dark mode'
pattern+='|light mode|typograph|\bfont\b|\bfonts\b|font pairing|\bpolice\b'
pattern+='|animation|\bmotion\b|micro-interaction|keyframe|glassmorph|neumorph'
pattern+='|claymorph|skeuomorph|brutalis|bento|minimalis|responsive|figma'
if printf '%s' "$lc" | grep -Eq "$pattern"; then
# Counter: log the fire (time, matched token, excerpt) — best-effort, never blocks.
+15 -14
View File
@@ -35,6 +35,19 @@ _out_of_scope() { # 0 = forbidden, 1 = in scope
_scope_violations() { local p; for p in "$@"; do _out_of_scope "$p" && printf '%s\n' "$p"; done; }
# Exits 4 with the REFUSED text (parsed by the calling skill) when any
# passed path is outside the allowlist; returns normally otherwise.
_refuse_outside_allowlist() {
local violations
mapfile -t violations < <(_scope_violations "$@")
if [ "${#violations[@]}" -gt 0 ]; then
{ echo "deploy-commit: REFUSED — path(s) outside .claude/deploy/ allowlist:";
printf ' - %s\n' "${violations[@]}";
echo "deploy-commit: NOTHING committed. Caller must pass only .claude/deploy/ files."; } >&2
exit 4
fi
}
_ignored() { git check-ignore -q "$1"; } # rc 0 = ignored
_changed_only() { # echo passed files that actually have changes
@@ -48,24 +61,12 @@ _in_git_repo || { echo "deploy-commit: not a git repo" >&2; exit 2; }
case "$cmd" in
pending)
[ "$#" -gt 0 ] || { echo "deploy-commit: pending needs file args" >&2; exit 2; }
mapfile -t violations < <(_scope_violations "$@")
if [ "${#violations[@]}" -gt 0 ]; then
{ echo "deploy-commit: REFUSED — path(s) outside .claude/deploy/ allowlist:";
printf ' - %s\n' "${violations[@]}";
echo "deploy-commit: NOTHING committed. Caller must pass only .claude/deploy/ files."; } >&2
exit 4
fi
_refuse_outside_allowlist "$@"
[ -n "$(_changed_only "$@")" ] && exit 0 || exit 1 ;;
commit)
msg="${1:-}"; shift || true
[ -n "$msg" ] && [ "$#" -gt 0 ] || { echo "deploy-commit: commit needs <msg> <file>..." >&2; exit 2; }
mapfile -t violations < <(_scope_violations "$@")
if [ "${#violations[@]}" -gt 0 ]; then
{ echo "deploy-commit: REFUSED — path(s) outside .claude/deploy/ allowlist:";
printf ' - %s\n' "${violations[@]}";
echo "deploy-commit: NOTHING committed. Caller must pass only .claude/deploy/ files."; } >&2
exit 4
fi
_refuse_outside_allowlist "$@"
mapfile -t ignored_paths < <(for p in "$@"; do _ignored "$p" && printf '%s\n' "$p"; done)
if [ "${#ignored_paths[@]}" -gt 0 ]; then
{ echo "deploy-commit: REFUSED — path(s) are git-ignored and will NOT persist; \`.claude/deploy/\` must be committable in this project:";
+1 -1
View File
@@ -1,7 +1,7 @@
#!/usr/bin/env bash
# ============================================================
# lib/detect-plugins.sh — Single source of truth for plugin detection
# Sourced by: session-start.sh, doctor.sh, install-plugins.sh
# Sourced by: session-start.sh, doctor.sh, install-plugins.sh, update-all.sh
#
# Each function returns 0 (detected) or 1 (not detected).
# No output — callers handle messaging.
+50
View File
@@ -19,6 +19,12 @@
# house permissions.deny is stricter (BDR-095)
# design-shotgun mockups need OPENAI_API_KEY, absent
#
# Also hosts the gstack helpers the two scripts share (gstack_skills and
# the park/unpark moves below). They live in this file because it is the
# only one the fixture suites copy next to profile.sh / toggle-external.sh:
# a new sourced file would be missing there. Each takes its directories as
# arguments (no reliance on the caller's globals).
#
# No `set -euo pipefail` here (sourced lib, mirrors lib/detect-plugins.sh).
# ============================================================
@@ -33,3 +39,47 @@ gstack_is_removed() {
done
return 1
}
# gstack_skills <gstack_src> — prints the directory basenames under
# <gstack_src>/*/ that hold a SKILL.md; nothing when the dir is absent.
# Source of truth for "which skills belong to gstack".
gstack_skills() {
local src="$1" d
[ -d "$src" ] || return 0
for d in "$src"/*/; do
[ -f "${d}SKILL.md" ] || continue
basename "$d"
done
}
# gstack_parked_names <disabled_dir> — prints <name> for every
# <disabled_dir>/gstack__<name> entry (a dangling symlink is skipped).
gstack_parked_names() {
local entry
[ -d "$1" ] || return 0
for entry in "$1"/gstack__*; do
[ -e "$entry" ] || continue
basename "$entry" | sed 's/^gstack__//'
done
}
# gstack_park <skills_dir> <disabled_dir> <name> — moves skills/<name> to
# skills-disabled/gstack__<name>. A stale destination is clobbered first:
# gstack ./setup creates skills/<name>/ as directories, so mv onto an
# existing dir would nest it (gstack__<name>/<name>/) instead of renaming.
# Content is symlinks to the submodule, `gstack ./setup` regenerates it.
# Call as a plain statement (never `|| …`, `if`, `!`): errexit must stay on.
gstack_park() {
local skills_dir="$1" disabled_dir="$2" name="$3"
rm -rf "$disabled_dir/gstack__$name"
mv "$skills_dir/$name" "$disabled_dir/gstack__$name"
}
# gstack_unpark <skills_dir> <disabled_dir> <name> — moves
# skills-disabled/gstack__<name> back to skills/<name>, replacing whatever
# sits there. Same plain-statement rule as gstack_park.
gstack_unpark() {
local skills_dir="$1" disabled_dir="$2" name="$3"
rm -rf "${skills_dir:?}/${name:?}"
mv "$disabled_dir/gstack__$name" "$skills_dir/$name"
}
+130 -116
View File
@@ -58,7 +58,9 @@ ACTIVE_CACHE="$REPO/.active-profile" # statusline reads this — keep fast (sin
DEFAULT_PROFILE="full" # profile in force when none is selected (cache absent, empty, or legacy "none")
# GSTACK_REMOVED + gstack_is_removed() — single source, honored by every
# "bring gstack back" path below (enable_all_gstack, enable_skill).
# "bring gstack back" path below (enable_all_gstack, enable_skill) — plus the
# gstack helpers shared with toggle-external.sh (gstack_skills, gstack_park,
# gstack_unpark, gstack_parked_names).
# shellcheck source=lib/gstack-removed.sh disable=SC1091
source "$(dirname "${BASH_SOURCE[0]}")/gstack-removed.sh"
@@ -181,16 +183,6 @@ read_profile() {
done < "$file"
}
# All skills bundled in skills-external/gstack/
gstack_skills() {
local src="$REPO/skills-external/gstack"
[ -d "$src" ] || return 0
for d in "$src"/*/; do
[ -f "${d}SKILL.md" ] || continue
basename "$d"
done
}
# Profile description (line starting with "# DESC: …")
profile_desc() {
local file="$1"
@@ -318,73 +310,84 @@ profile_match() {
# ── Enable / disable ──────────────────────────────────────
# Enables a gstack skill: unpark it, or link it from the submodule.
enable_gstack_skill() {
local skill="$1"
if gstack_is_removed "$skill"; then
warn "refusing to enable removed skill: $skill (lib/gstack-removed.sh \
— a profile census failure, not a crash)"
return 0
elif [ -e "$DISABLED_DIR/gstack__$skill" ]; then
gstack_unpark "$SKILLS_DIR" "$DISABLED_DIR" "$skill"
ok "enabled: $skill"
elif [ -e "$DISABLED_DIR/$skill" ]; then
rm -rf "${SKILLS_DIR:?}/${skill:?}"
mv "$DISABLED_DIR/$skill" "$SKILLS_DIR/$skill"
ok "enabled: $skill"
elif [ -e "$SKILLS_DIR/$skill" ]; then
: # already enabled — silent
elif [ -d "$GSTACK_SRC/$skill" ]; then
# gstack is OFF by default: its skills live only in the submodule,
# never pre-symlinked into skills/. A profile that lists this gstack
# skill activates it on demand by symlinking the submodule skill dir
# in. disable_gstack_not_in() parks it again when an unrelated profile
# is set. The gstack/bin + browse/dist infra it relies on is created
# by link.sh, independent of this.
ln -sf "$GSTACK_SRC/$skill" "$SKILLS_DIR/$skill"
ok "enabled: $skill (gstack on-demand)"
elif [ ! -d "$GSTACK_SRC" ]; then
warn "missing: $skill — gstack submodule absent, run: git submodule update --init"
else
warn "missing: $skill — not found in gstack submodule ($GSTACK_SRC)"
fi
}
# Enables an external|personal skill: unpark it, or recreate the symlink.
enable_linked_skill() {
local skill="$1" type="$2"
if [ -e "$DISABLED_DIR/$skill" ]; then
rm -rf "${SKILLS_DIR:?}/${skill:?}"
mv "$DISABLED_DIR/$skill" "$SKILLS_DIR/$skill"
ok "enabled: $skill ($type)"
elif [ -e "$SKILLS_DIR/$skill" ]; then
:
elif [ "$type" = external ] && [ -d "$REPO/skills-external/$skill" ]; then
# Symlink never created (or hand-removed): recreate it from the
# vendored pack — mirrors toggle-external.sh's from-source path.
ln -sf "$REPO/skills-external/$skill" "$SKILLS_DIR/$skill"
ok "enabled: $skill (external, symlink created)"
else
warn "missing: $skill ($type)"
fi
}
# Enables a plugin@<marketplace> skill through the claude CLI.
enable_plugin_skill() {
local skill="$1" type="$2"
# type holds the marketplace: plugin@<marketplace>
local marketplace="${type#plugin@}"
if [ "$(skill_status "$skill" "$type")" = "enabled" ]; then
: # already on
elif command -v "$CLAUDE_BIN" >/dev/null 2>&1; then
# CLI call stays inside the condition: a failing CLI must not abort
if grep -qiE "enabled|already" \
<<<"$("$CLAUDE_BIN" plugin enable \
"${skill}@${marketplace}" 2>&1)"; then
ok "enabled plugin: ${skill}@${marketplace}"
else
warn "could not enable plugin: ${skill}@${marketplace}"
fi
else
info "claude CLI not in PATH — manual: claude plugin enable ${skill}@${marketplace}"
fi
}
enable_skill() {
local skill="$1" type="$2"
case "$type" in
gstack)
if gstack_is_removed "$skill"; then
warn "refusing to enable removed skill: $skill (lib/gstack-removed.sh \
— a profile census failure, not a crash)"
return 0
elif [ -e "$DISABLED_DIR/gstack__$skill" ]; then
rm -rf "${SKILLS_DIR:?}/${skill:?}"
mv "$DISABLED_DIR/gstack__$skill" "$SKILLS_DIR/$skill"
ok "enabled: $skill"
elif [ -e "$DISABLED_DIR/$skill" ]; then
rm -rf "${SKILLS_DIR:?}/${skill:?}"
mv "$DISABLED_DIR/$skill" "$SKILLS_DIR/$skill"
ok "enabled: $skill"
elif [ -e "$SKILLS_DIR/$skill" ]; then
: # already enabled — silent
elif [ -d "$GSTACK_SRC/$skill" ]; then
# gstack is OFF by default: its skills live only in the submodule,
# never pre-symlinked into skills/. A profile that lists this gstack
# skill activates it on demand by symlinking the submodule skill dir
# in. disable_gstack_not_in() parks it again when an unrelated profile
# is set. The gstack/bin + browse/dist infra it relies on is created
# by link.sh, independent of this.
ln -sf "$GSTACK_SRC/$skill" "$SKILLS_DIR/$skill"
ok "enabled: $skill (gstack on-demand)"
elif [ ! -d "$GSTACK_SRC" ]; then
warn "missing: $skill — gstack submodule absent, run: git submodule update --init"
else
warn "missing: $skill — not found in gstack submodule ($GSTACK_SRC)"
fi
;;
external|personal)
if [ -e "$DISABLED_DIR/$skill" ]; then
rm -rf "${SKILLS_DIR:?}/${skill:?}"
mv "$DISABLED_DIR/$skill" "$SKILLS_DIR/$skill"
ok "enabled: $skill ($type)"
elif [ -e "$SKILLS_DIR/$skill" ]; then
:
elif [ "$type" = external ] && [ -d "$REPO/skills-external/$skill" ]; then
# Symlink never created (or hand-removed): recreate it from the
# vendored pack — mirrors toggle-external.sh's from-source path.
ln -sf "$REPO/skills-external/$skill" "$SKILLS_DIR/$skill"
ok "enabled: $skill (external, symlink created)"
else
warn "missing: $skill ($type)"
fi
;;
plugin@*)
# type holds the marketplace: plugin@<marketplace>
local marketplace="${type#plugin@}"
if [ "$(skill_status "$skill" "$type")" = "enabled" ]; then
: # already on
elif command -v "$CLAUDE_BIN" >/dev/null 2>&1; then
# CLI call stays inside the condition: a failing CLI must not abort
if grep -qiE "enabled|already" \
<<<"$("$CLAUDE_BIN" plugin enable \
"${skill}@${marketplace}" 2>&1)"; then
ok "enabled plugin: ${skill}@${marketplace}"
else
warn "could not enable plugin: ${skill}@${marketplace}"
fi
else
info "claude CLI not in PATH — manual: claude plugin enable ${skill}@${marketplace}"
fi
;;
gstack) enable_gstack_skill "$skill" ;;
external|personal) enable_linked_skill "$skill" "$type" ;;
plugin@*) enable_plugin_skill "$skill" "$type" ;;
plugin)
# No marketplace specified — purely advisory.
if [ "$(skill_status "$skill" plugin)" = "enabled" ]; then
@@ -419,8 +422,7 @@ disable_skill() {
gstack)
if [ -e "$SKILLS_DIR/$skill" ]; then
mkdir -p "$DISABLED_DIR"
rm -rf "$DISABLED_DIR/gstack__$skill"
mv "$SKILLS_DIR/$skill" "$DISABLED_DIR/gstack__$skill"
gstack_park "$SKILLS_DIR" "$DISABLED_DIR" "$skill"
ok "disabled: $skill"
fi
;;
@@ -477,20 +479,17 @@ disable_skill() {
# stdout so the caller can report it accurately; per-skill confirmations
# go to stderr so that count is the only thing captured with `$(...)`.
enable_all_gstack() {
local entry name restored=0
local name restored=0
[ -d "$DISABLED_DIR" ] || { echo 0; return 0; }
for entry in "$DISABLED_DIR"/gstack__*; do
[ -e "$entry" ] || continue
name="$(basename "$entry" | sed 's/^gstack__//')"
while IFS= read -r name; do
if gstack_is_removed "$name"; then
info "skipped (removed by policy, lib/gstack-removed.sh): $name" >&2
continue
fi
rm -rf "${SKILLS_DIR:?}/${name:?}"
mv "$entry" "$SKILLS_DIR/$name"
gstack_unpark "$SKILLS_DIR" "$DISABLED_DIR" "$name"
ok "re-enabled: $name" >&2
restored=$((restored + 1))
done
done < <(gstack_parked_names "$DISABLED_DIR")
echo "$restored"
}
@@ -504,7 +503,7 @@ disable_gstack_not_in() {
while read -r name; do
[ -n "$name" ] || continue
grep -qx "$name" "$keep_file" || disable_skill "$name" gstack
done < <(gstack_skills | sort -u)
done < <(gstack_skills "$GSTACK_SRC" | sort -u)
rm -f "$keep_file"
}
@@ -572,29 +571,58 @@ cmd_list() {
done
}
# Snapshot of a profile's entries, claude-free: "<cat><TAB><name>" lines,
# canonical name. A plugin's marketplace (plugin@<mp>) collapses to the
# category "plugin".
_show_entries() {
local skill type cat
while IFS=$'\t' read -r skill type; do
case "$type" in plugin@*|plugin) cat=plugin ;; *) cat="$type" ;; esac
printf '%s\t%s\n' "$cat" "$skill"
done < <(read_profile "$1")
}
# --plain: parsable contract for the design gate. One "<type><TAB><name>"
# per line, grouped by type, NO status, NO claude calls.
_show_plain() {
local entries=() cat e line
while IFS= read -r line; do entries+=("$line"); done < <(_show_entries "$1")
for cat in gstack external personal plugin mcp cli; do
for e in "${entries[@]}"; do
[ "${e%%$'\t'*}" = "$cat" ] && printf '%s\t%s\n' "$cat" "${e#*$'\t'}"
done
done
return 0
}
# Grouped by type, fixed order; empty groups skipped. Canonical name +
# runtime status (existing skill_status — degrades to disabled if no claude).
_show_grouped() {
local entries=() cat e line names skill status
while IFS= read -r line; do entries+=("$line"); done < <(_show_entries "$1")
for cat in gstack external personal plugin mcp cli; do
names=()
for e in "${entries[@]}"; do
[ "${e%%$'\t'*}" = "$cat" ] && names+=("${e#*$'\t'}")
done
[ "${#names[@]}" -eq 0 ] && continue
printf '%s (%d):\n' "$cat" "${#names[@]}"
for skill in "${names[@]}"; do
status="$(skill_status "$skill" "$cat")"
printf ' %-24s %s\n' "$skill" "$status"
done
done
return 0
}
cmd_show() {
local prof="$1" plain=0
[ "${2:-}" = "--plain" ] && plain=1
local file="$PROFILES_DIR/$prof.profile"
[ -f "$file" ] || { err "Profile not found: $prof"; return 1; }
# Snapshot entries once (claude-free): "<cat><TAB><name>", canonical name.
# A plugin's marketplace (plugin@<mp>) collapses to category "plugin".
local entries=() skill type cat
while IFS=$'\t' read -r skill type; do
case "$type" in plugin@*|plugin) cat=plugin ;; *) cat="$type" ;; esac
entries+=("$cat"$'\t'"$skill")
done < <(read_profile "$prof")
# --plain: parsable contract for the design gate. One "<type><TAB><name>"
# per line, grouped by type, NO status, NO claude calls.
if [ "$plain" -eq 1 ]; then
local e
for cat in gstack external personal plugin mcp cli; do
for e in "${entries[@]}"; do
[ "${e%%$'\t'*}" = "$cat" ] && printf '%s\t%s\n' "$cat" "${e#*$'\t'}"
done
done
_show_plain "$prof"
return 0
fi
@@ -611,21 +639,7 @@ cmd_show() {
fi
echo ""
# Grouped by type, fixed order; empty groups skipped. Canonical name +
# runtime status (existing skill_status — degrades to disabled if no claude).
local e names status
for cat in gstack external personal plugin mcp cli; do
names=()
for e in "${entries[@]}"; do
[ "${e%%$'\t'*}" = "$cat" ] && names+=("${e#*$'\t'}")
done
[ "${#names[@]}" -eq 0 ] && continue
printf '%s (%d):\n' "$cat" "${#names[@]}"
for skill in "${names[@]}"; do
status="$(skill_status "$skill" "$cat")"
printf ' %-24s %s\n' "$skill" "$status"
done
done
_show_grouped "$prof"
}
cmd_apply() {
+44 -37
View File
@@ -214,45 +214,52 @@ def inspect(store_path, account, property, url):
"last_crawl": isr.get("lastCrawlTime"),
"rich_results": _norm_rich(ir)}
def _build_parser():
p = argparse.ArgumentParser()
sub = p.add_subparsers(dest="cmd", required=True)
pc = sub.add_parser("crux")
pc.add_argument("--url", required=True)
pc.add_argument("--strategy", default="mobile", choices=["mobile", "desktop"])
pc.add_argument("--store", default=None) # accepted+ignored: uniform fetch.sh dispatch
pq = sub.add_parser("queries")
pq.add_argument("--store", required=True)
pq.add_argument("--account", required=True)
pq.add_argument("--property", required=True)
pq.add_argument("--days", type=int, default=90)
pq.add_argument("--dim", default="query",
help="one dimension, or a comma-separated list (query,page)")
pq.add_argument("--rows", type=int, default=100)
pn = sub.add_parser("cannibal")
pn.add_argument("--store", required=True)
pn.add_argument("--account", required=True)
pn.add_argument("--property", required=True)
pn.add_argument("--days", type=int, default=90)
pn.add_argument("--rows", type=int, default=1000)
pi = sub.add_parser("inspect")
pi.add_argument("--store", required=True)
pi.add_argument("--account", required=True)
pi.add_argument("--property", required=True)
pi.add_argument("--url", required=True)
return p
def _dispatch(args):
if args.cmd == "crux":
print(json.dumps(crux(args.url, args.strategy), indent=2))
elif args.cmd == "queries":
print(json.dumps(queries(args.store, args.account, args.property,
args.days, args.dim, args.rows), indent=2))
elif args.cmd == "cannibal":
print(json.dumps(cannibal(args.store, args.account, args.property,
args.days, args.rows), indent=2))
elif args.cmd == "inspect":
print(json.dumps(inspect(args.store, args.account, args.property,
args.url), indent=2))
def _cli():
try:
p = argparse.ArgumentParser()
sub = p.add_subparsers(dest="cmd", required=True)
pc = sub.add_parser("crux")
pc.add_argument("--url", required=True)
pc.add_argument("--strategy", default="mobile", choices=["mobile", "desktop"])
pc.add_argument("--store", default=None) # accepted+ignored: uniform fetch.sh dispatch
pq = sub.add_parser("queries")
pq.add_argument("--store", required=True)
pq.add_argument("--account", required=True)
pq.add_argument("--property", required=True)
pq.add_argument("--days", type=int, default=90)
pq.add_argument("--dim", default="query",
help="one dimension, or a comma-separated list (query,page)")
pq.add_argument("--rows", type=int, default=100)
pn = sub.add_parser("cannibal")
pn.add_argument("--store", required=True)
pn.add_argument("--account", required=True)
pn.add_argument("--property", required=True)
pn.add_argument("--days", type=int, default=90)
pn.add_argument("--rows", type=int, default=1000)
pi = sub.add_parser("inspect")
pi.add_argument("--store", required=True)
pi.add_argument("--account", required=True)
pi.add_argument("--property", required=True)
pi.add_argument("--url", required=True)
args = p.parse_args()
if args.cmd == "crux":
print(json.dumps(crux(args.url, args.strategy), indent=2))
elif args.cmd == "queries":
print(json.dumps(queries(args.store, args.account, args.property,
args.days, args.dim, args.rows), indent=2))
elif args.cmd == "cannibal":
print(json.dumps(cannibal(args.store, args.account, args.property,
args.days, args.rows), indent=2))
elif args.cmd == "inspect":
print(json.dumps(inspect(args.store, args.account, args.property,
args.url), indent=2))
_dispatch(_build_parser().parse_args())
except SystemExit as e: # argparse usage error
if e.code not in (0, None):
print(json.dumps({"status": "error", "reason": "bad_usage"}))
-1
View File
@@ -27,7 +27,6 @@ separate process and cannot be pinned from here. Their surface is smaller
(a fixed set against an operator-typed/confirmed $DOMAIN). Closing them needs
`curl --resolve` and is a separate change.
"""
import gzip
import http.client
import ipaddress
import socket
+1
View File
@@ -1,5 +1,6 @@
#!/usr/bin/env bash
# Deterministic tests for the seo-data engine (no network, no venv).
# shellcheck disable=SC2015 # A && ok || no is deliberate (ok/no never fail)
set -u
REPO="$(cd "$(dirname "$0")/../.." && pwd)"
SD="$REPO/lib/seo-data"
+1
View File
@@ -2,6 +2,7 @@
# lib/tests/push-guard.test.sh
# hooks/push-guard.sh (BDR-111): denies `git push` in manual push mode,
# silent otherwise. Also locks the settings.json wiring and the banner line.
# shellcheck disable=SC2016 # single-quoted forms are the commands under test
set -u
export GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null
ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+1 -1
View File
@@ -11,7 +11,7 @@ set -uo pipefail
GREP=/usr/bin/grep # LRN-074: pin grep
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO="$(cd "$HERE/../.." && pwd)"
cd "$REPO"
cd "$REPO" || exit 1
pass=0; fail=0; skip=0
ok() { echo "GREEN ✓ $*"; pass=$((pass+1)); }
+1
View File
@@ -1,5 +1,6 @@
#!/usr/bin/env bash
# lib/tests/url-guard.test.sh
# shellcheck disable=SC2016 # single-quoted forms are the commands under test
set -u
G="$(cd "$(dirname "$0")/../.." && pwd)/lib/url-guard.sh"
pass=0; fail=0
+170 -154
View File
@@ -42,10 +42,13 @@ set -euo pipefail
REPO="${TOGGLE_EXTERNAL_REPO_OVERRIDE:-$(cd -P "$(dirname "$0")/.." && pwd)}"
SKILLS_DIR="$REPO/skills"
DISABLED_DIR="$REPO/skills-disabled"
GSTACK_SRC="$REPO/skills-external/gstack" # gstack submodule: its skills
# GSTACK_REMOVED + gstack_is_removed() — single source, honored by the
# `enable gstack` loop below. Resolved from $0 like REPO above, not from
# $REPO/lib — gstack-removed.sh sits next to this file wherever it runs.
# `enable gstack` loop below — plus the gstack helpers shared with
# profile.sh (gstack_skills, gstack_park, gstack_unpark, gstack_parked_names).
# Resolved from $0 like REPO above, not from $REPO/lib — gstack-removed.sh
# sits next to this file wherever it runs.
# shellcheck source=lib/gstack-removed.sh disable=SC1091
source "$(dirname "$0")/gstack-removed.sh"
@@ -54,14 +57,40 @@ ok() { echo -e "${GREEN}✓${NC} $1"; }
warn() { echo -e "${YELLOW}⚠${NC} $1"; }
err() { echo -e "${RED}✗${NC} $1"; }
# All non-plugin tools this script can toggle.
# All non-plugin tools this script can toggle, in `list` order. The one
# roster: tool_kind() derives every tool's kind from it.
MANAGED_TOOLS=(gstack emil-design-eng darwin-skill 21st higgsfield
higgsfield-websites
observability-and-instrumentation deprecation-and-migration ci-cd-and-automation
observability-and-instrumentation deprecation-and-migration
ci-cd-and-automation
scroll-world-storytelling build-threejs-scroll-worlds
scroll-scrubbed-visual-sequence scroll-scrubbed-word-reveal
scroll-progress-timeline)
# Prints the kind of a tool: gstack | pack (21st, higgsfield) | single (one
# symlink: every other MANAGED_TOOLS entry) | unknown. Exact-match loop, so
# a name with spaces or glob characters can never match a roster entry.
tool_kind() {
local tool="$1" managed
case "$tool" in
gstack) echo gstack; return ;;
21st|higgsfield) echo pack; return ;;
esac
for managed in "${MANAGED_TOOLS[@]}"; do
[ "$managed" = "$tool" ] && { echo single; return; }
done
echo unknown
}
# Prints where a single-symlink tool is linked from: ~/.agents/skills for
# darwin-skill, skills-external/ for the others.
tool_source() {
case "$1" in
darwin-skill) echo "$HOME/.agents/skills/$1" ;;
*) echo "$REPO/skills-external/$1" ;;
esac
}
# Prints the skill names that belong to the "21st" pack. Source of truth:
# skills-external/21st-* — the `21st skills install` run in install-plugins.sh
# owns that list, so adding a skill upstream needs no edit here.
@@ -117,8 +146,8 @@ pack_skills() {
# tool exists (`timeout`, or `gtimeout` from Homebrew coreutils on macOS):
# a closed-source binary must never hang a toggle, and what it prints (a
# token) must never reach the terminal. Twin of _higgsfield_probe in
# lib/higgsfield-skills.sh, kept here because this script takes no extra
# `source` (the fixture suites copy it alone).
# lib/higgsfield-skills.sh, kept here so the only file sourced beside this
# script stays gstack-removed.sh (the fixture suites copy just those two).
bounded() {
local tool
for tool in timeout gtimeout; do
@@ -158,41 +187,22 @@ pack_hints() {
esac
}
# Prints the names (directory basenames) that belong to "gstack".
# Source of truth: skills-external/gstack/*/SKILL.md. The repo's
# skills/<name> symlinks are generated from these by gstack ./setup.
gstack_skills() {
local gstack_src="$REPO/skills-external/gstack"
[ -d "$gstack_src" ] || return 0
for d in "$gstack_src"/*/; do
[ -f "${d}SKILL.md" ] || continue
basename "$d"
done
}
# Prints "enabled" / "disabled" / "missing" for a tool.
status_tool() {
local tool="$1"
case "$tool" in
local tool="$1" installed=0 name
case "$(tool_kind "$tool")" in
gstack)
[ -d "$REPO/skills-external/gstack" ] || { echo "missing"; return; }
[ -d "$GSTACK_SRC" ] || { echo "missing"; return; }
while read -r name; do
[ -e "$SKILLS_DIR/$name" ] && { echo "enabled"; return; }
done < <(gstack_skills)
done < <(gstack_skills "$GSTACK_SRC")
echo "disabled"
;;
emil-design-eng|observability-and-instrumentation|deprecation-and-migration|ci-cd-and-automation| \
scroll-world-storytelling|build-threejs-scroll-worlds|scroll-scrubbed-visual-sequence| \
scroll-scrubbed-word-reveal|scroll-progress-timeline|higgsfield-websites)
[ -d "$REPO/skills-external/$tool" ] || { echo "missing"; return; }
single)
[ -d "$(tool_source "$tool")" ] || { echo "missing"; return; }
[ -e "$SKILLS_DIR/$tool" ] && echo "enabled" || echo "disabled"
;;
darwin-skill)
[ -d "$HOME/.agents/skills/$tool" ] || { echo "missing"; return; }
[ -e "$SKILLS_DIR/$tool" ] && echo "enabled" || echo "disabled"
;;
21st|higgsfield)
local installed=0
pack)
while read -r name; do
installed=1
[ -e "$SKILLS_DIR/$name" ] && { echo "enabled"; return; }
@@ -204,141 +214,145 @@ status_tool() {
esac
}
# Parks every live gstack skill (twin of profile.sh's disable_skill gstack
# arm, kept separate: the messages differ).
disable_gstack() {
local moved=0 name
while read -r name; do
[ -e "$SKILLS_DIR/$name" ] || continue
gstack_park "$SKILLS_DIR" "$DISABLED_DIR" "$name"
moved=$((moved + 1))
done < <(gstack_skills "$GSTACK_SRC")
ok "gstack disabled ($moved symlinks moved)"
}
# Parks one single-symlink external tool.
disable_external_single() {
local tool="$1"
if [ -e "$SKILLS_DIR/$tool" ]; then
rm -rf "${DISABLED_DIR:?}/${tool:?}"
mv "$SKILLS_DIR/$tool" "$DISABLED_DIR/$tool"
ok "$tool disabled"
else
warn "$tool already disabled"
fi
}
# Parks every live skill of a pack (21st, higgsfield). Parked under the
# plain skill name — same convention as the other externals, so profile.sh's
# park/restore path stays interoperable.
disable_pack() {
local tool="$1" parked=0 name
while read -r name; do
[ -e "$SKILLS_DIR/$name" ] || continue
rm -rf "${DISABLED_DIR:?}/${name:?}"
mv "$SKILLS_DIR/$name" "$DISABLED_DIR/$name"
parked=$((parked + 1))
done < <(pack_skills "$tool")
if [ "$parked" -gt 0 ]; then
ok "$tool disabled ($parked skills parked)"
else
warn "$tool already disabled"
fi
}
disable_tool() {
local tool="$1"
mkdir -p "$DISABLED_DIR"
case "$tool" in
gstack)
local moved=0
while read -r name; do
[ -e "$SKILLS_DIR/$name" ] || continue
# Clobber any stale destination. gstack ./setup now creates
# skills/<name>/ as directories, so mv onto an existing dir
# would nest it (gstack__<name>/<name>/) instead of renaming.
# Content is symlinks to the submodule — `gstack ./setup` regenerates.
rm -rf "$DISABLED_DIR/gstack__$name"
mv "$SKILLS_DIR/$name" "$DISABLED_DIR/gstack__$name"
moved=$((moved + 1))
done < <(gstack_skills)
ok "gstack disabled ($moved symlinks moved)"
;;
emil-design-eng|darwin-skill|observability-and-instrumentation|deprecation-and-migration| \
ci-cd-and-automation|scroll-world-storytelling|build-threejs-scroll-worlds| \
scroll-scrubbed-visual-sequence|scroll-scrubbed-word-reveal|scroll-progress-timeline| \
higgsfield-websites)
if [ -e "$SKILLS_DIR/$tool" ]; then
rm -rf "${DISABLED_DIR:?}/${tool:?}"
mv "$SKILLS_DIR/$tool" "$DISABLED_DIR/$tool"
ok "$tool disabled"
else
warn "$tool already disabled"
fi
;;
21st|higgsfield)
# Parked under the plain skill name — same convention as the other
# externals, so profile.sh's park/restore path stays interoperable.
local parked=0
while read -r name; do
[ -e "$SKILLS_DIR/$name" ] || continue
rm -rf "${DISABLED_DIR:?}/${name:?}"
mv "$SKILLS_DIR/$name" "$DISABLED_DIR/$name"
parked=$((parked + 1))
done < <(pack_skills "$tool")
if [ "$parked" -gt 0 ]; then
ok "$tool disabled ($parked skills parked)"
else
warn "$tool already disabled"
fi
;;
case "$(tool_kind "$tool")" in
gstack) disable_gstack ;;
single) disable_external_single "$tool" ;;
pack) disable_pack "$tool" ;;
*) err "Unknown tool: $tool"; return 1 ;;
esac
}
# Re-links the gstack skills parked as gstack__<name>, honoring the
# policy denylist (lib/gstack-removed.sh).
enable_gstack() {
local moved=0 skipped=0 name
while IFS= read -r name; do
if gstack_is_removed "$name"; then
warn "skipped (removed by policy, lib/gstack-removed.sh): $name"
skipped=$((skipped + 1))
continue
fi
gstack_unpark "$SKILLS_DIR" "$DISABLED_DIR" "$name"
moved=$((moved + 1))
done < <(gstack_parked_names "$DISABLED_DIR")
if [ "$moved" -eq 0 ] && [ "$skipped" -ge 1 ]; then
warn "only policy-removed skills remain parked (lib/gstack-removed.sh)"
elif [ "$moved" -eq 0 ]; then
warn "gstack was not disabled — re-run gstack setup to (re)create symlinks"
else
ok "gstack enabled ($moved symlinks restored)"
fi
}
# Enables one single-symlink external tool: restore from the parking dir,
# else link its source (see tool_source).
enable_external_single() {
local tool="$1" src
src="$(tool_source "$tool")"
if [ -e "$DISABLED_DIR/$tool" ]; then
rm -rf "${SKILLS_DIR:?}/${tool:?}"
mv "$DISABLED_DIR/$tool" "$SKILLS_DIR/$tool"
ok "$tool enabled"
elif [ -e "$SKILLS_DIR/$tool" ]; then
warn "$tool already enabled"
elif [ -d "$src" ]; then
ln -sf "$src" "$SKILLS_DIR/$tool"
ok "$tool enabled (symlink created → $src)"
else
err "$tool not installed at $src — run: make plugin"
return 1
fi
if [ "$tool" = "higgsfield-websites" ]; then pack_hints higgsfield; fi
}
# Enables a multi-skill pack (21st, higgsfield): restore parked skills,
# link the missing ones, then print the CLI hints.
enable_pack() {
local tool="$1" restored=0 linked=0
while read -r name; do
if [ -e "$DISABLED_DIR/$name" ]; then
rm -rf "${SKILLS_DIR:?}/${name:?}"
mv "$DISABLED_DIR/$name" "$SKILLS_DIR/$name"
restored=$((restored + 1))
elif [ -e "$SKILLS_DIR/$name" ]; then
: # already enabled
else
ln -sf "$REPO/skills-external/$name" "$SKILLS_DIR/$name"
linked=$((linked + 1))
fi
done < <(pack_skills "$tool")
if [ "$((restored + linked))" -eq 0 ]; then
if [ "$(status_tool "$tool")" = "missing" ]; then
err "$tool pack not installed in $REPO/skills-external — run: make plugin"
return 1
fi
warn "$tool already enabled"
# Enabled is the steady state, and Claude re-runs this on every
# media ask: the hints (upstream drift, CLI, session) show here too.
if [ "$tool" = "higgsfield" ]; then pack_hints higgsfield; fi
return 0
fi
ok "$tool enabled ($((restored + linked)) skills: $restored restored, $linked linked)"
pack_hints "$tool"
}
enable_tool() {
local tool="$1"
case "$tool" in
gstack)
local moved=0 skipped=0
if [ -d "$DISABLED_DIR" ]; then
for entry in "$DISABLED_DIR"/gstack__*; do
[ -e "$entry" ] || continue
local name
name="$(basename "$entry" | sed 's/^gstack__//')"
if gstack_is_removed "$name"; then
warn "skipped (removed by policy, lib/gstack-removed.sh): $name"
skipped=$((skipped + 1))
continue
fi
rm -rf "${SKILLS_DIR:?}/${name:?}"
mv "$entry" "$SKILLS_DIR/$name"
moved=$((moved + 1))
done
fi
if [ "$moved" -eq 0 ] && [ "$skipped" -ge 1 ]; then
warn "only policy-removed skills remain parked (lib/gstack-removed.sh)"
elif [ "$moved" -eq 0 ]; then
warn "gstack was not disabled — re-run gstack setup to (re)create symlinks"
else
ok "gstack enabled ($moved symlinks restored)"
fi
;;
emil-design-eng|darwin-skill|observability-and-instrumentation|deprecation-and-migration| \
ci-cd-and-automation|scroll-world-storytelling|build-threejs-scroll-worlds| \
scroll-scrubbed-visual-sequence|scroll-scrubbed-word-reveal|scroll-progress-timeline| \
higgsfield-websites)
local src
case "$tool" in
darwin-skill) src="$HOME/.agents/skills/$tool" ;;
*) src="$REPO/skills-external/$tool" ;;
esac
if [ -e "$DISABLED_DIR/$tool" ]; then
rm -rf "${SKILLS_DIR:?}/${tool:?}"
mv "$DISABLED_DIR/$tool" "$SKILLS_DIR/$tool"
ok "$tool enabled"
elif [ -e "$SKILLS_DIR/$tool" ]; then
warn "$tool already enabled"
elif [ -d "$src" ]; then
ln -sf "$src" "$SKILLS_DIR/$tool"
ok "$tool enabled (symlink created → $src)"
else
err "$tool not installed at $src — run: make plugin"
return 1
fi
if [ "$tool" = "higgsfield-websites" ]; then pack_hints higgsfield; fi
;;
21st|higgsfield)
local restored=0 linked=0
while read -r name; do
if [ -e "$DISABLED_DIR/$name" ]; then
rm -rf "${SKILLS_DIR:?}/${name:?}"
mv "$DISABLED_DIR/$name" "$SKILLS_DIR/$name"
restored=$((restored + 1))
elif [ -e "$SKILLS_DIR/$name" ]; then
: # already enabled
else
ln -sf "$REPO/skills-external/$name" "$SKILLS_DIR/$name"
linked=$((linked + 1))
fi
done < <(pack_skills "$tool")
if [ "$((restored + linked))" -eq 0 ]; then
if [ "$(status_tool "$tool")" = "missing" ]; then
err "$tool pack not installed in $REPO/skills-external — run: make plugin"
return 1
fi
warn "$tool already enabled"
# Enabled is the steady state, and Claude re-runs this on every
# media ask: the hints (upstream drift, CLI, session) show here too.
if [ "$tool" = "higgsfield" ]; then pack_hints higgsfield; fi
return 0
fi
ok "$tool enabled ($((restored + linked)) skills: $restored restored, $linked linked)"
pack_hints "$tool"
;;
case "$(tool_kind "$tool")" in
gstack) enable_gstack ;;
single) enable_external_single "$tool" ;;
pack) enable_pack "$tool" ;;
*) err "Unknown tool: $tool"; return 1 ;;
esac
}
list_all() {
local t
printf "%-20s %s\n" "TOOL" "STATUS"
printf "%-20s %s\n" "----" "------"
for t in "${MANAGED_TOOLS[@]}"; do
@@ -347,7 +361,9 @@ list_all() {
}
usage() {
sed -n '3,26p' "$0" | sed 's/^# \?//'
# Header comment = lines 3 .. closing banner (dropped); no numeric range,
# so a longer tool list can no longer fall out of --help.
sed -n '3,/^# ====/p' "$0" | sed '$d' | sed 's/^# \?//'
exit "${1:-0}"
}