diff --git a/CLAUDE.global.md b/CLAUDE.global.md index 1a25f5b..52cc81c 100644 --- a/CLAUDE.global.md +++ b/CLAUDE.global.md @@ -84,9 +84,10 @@ code" wins. Repo-specific instructions override both. calls the advisor tool when it is listed (settings `advisorModel`, Fable, set by /advisor), at least at the points of `~/.claude/lib/effort-shift.md` § Advisor; dispatched plan-challenger, - verifier, security-auditor and `analyzer` at most once, before their - verdict or report; other sub-agents do not. Fable is never routed or - pinned: the router tops out at opus (BDR-150). + verifier, security-auditor, `analyzer` and an opus code review at most + once, before their verdict or report; other sub-agents never (an opus + brief says which; a SubagentStart hook restates it). Fable is never + routed or pinned: the router tops out at opus (BDR-150). - Ask rather than guess. A choice visible in the result (placement, wording, order, behavior), a name that becomes public (command, flag, endpoint, file), or a scope the request leaves open → ask, even mid-task; @@ -291,6 +292,8 @@ cryptic names. finishing-a-development-branch → `gitflow finish` (human signal) systematic-debugging → bugfix verification-before-completion → the verifier gates +- subagent-driven-development standalone: workers sonnet (task reviews and + fix rounds too); final review opus, its brief allowing one `advisor` call - SEO+GEO → seo (GEO only → geo); W3C + WCAG → web-validate. Pack off → propose `profile.sh enable seo` (seo, geo) or `enable web-validate`, the user runs `/reload-plugins`; else say so. Security audit (secrets, CVE, diff --git a/agents/client-handover-writer.md b/agents/client-handover-writer.md index 00e27ec..597ed59 100644 --- a/agents/client-handover-writer.md +++ b/agents/client-handover-writer.md @@ -269,6 +269,9 @@ the gate. this pipeline (initial audits, fix-loop re-dispatches, commit-change, web-validate) carries `model: "opus"` and `effort="high"` — the child hosts gated orchestration on the pipeline's behalf; it must never inherit the session model. +Append to each such prompt: "never call the `advisor` tool in this run; +a CHALLENGE SUMMARY, if your skill prints one, reads `Advisor: not called +(sub-agent)`" (BDR-150). For web projects, dispatch in **a single message with two parallel Agent calls** (each with `model: "opus"`, `effort="high"`): diff --git a/agents/commit-changer.md b/agents/commit-changer.md index 0a1a327..0509e6b 100644 --- a/agents/commit-changer.md +++ b/agents/commit-changer.md @@ -8,6 +8,10 @@ effort: high # Git Smart Commit +Advisor tool (`lib/effort-shift.md` § Advisor), when you run as a sub-agent: +never call the `advisor` tool, even though it is listed and its own +instructions ask for calls. + > MODEL (BDR-077): `MODE: propose` is dispatched with `model="opus"` (the > call-site override — narrative reconstruction + capitalize routing are > judgment); `MODE: apply` runs on its sonnet row (frontmatter = off-state floor; mechanical diff --git a/agents/doc-syncer.md b/agents/doc-syncer.md index fab4357..337f556 100644 --- a/agents/doc-syncer.md +++ b/agents/doc-syncer.md @@ -8,6 +8,10 @@ effort: high # DOC SYNCER +Advisor tool (`lib/effort-shift.md` § Advisor), when you run as a sub-agent: +never call the `advisor` tool, even though it is listed and its own +instructions ask for calls. + ## GOAL Keep PUBLIC documentation in sync with code. Detect drift, report it, patch what can be patched automatically. Auto-discover what public doc diff --git a/agents/geo-analyzer.md b/agents/geo-analyzer.md index 1405750..36c96ff 100644 --- a/agents/geo-analyzer.md +++ b/agents/geo-analyzer.md @@ -8,6 +8,10 @@ effort: xhigh # GEO — Generative Engine Optimization audit, fix & strategy +Advisor tool (`lib/effort-shift.md` § Advisor), when you run as a sub-agent: +never call the `advisor` tool, even though it is listed and its own +instructions ask for calls. + Target search engines: **ChatGPT Search, Perplexity, Claude, Gemini, Google AI Overviews, Microsoft Copilot, Brave AI, DuckAssist, You.com, Apple Intelligence**. Google classical search is handled by the diff --git a/agents/handover-doc-writer.md b/agents/handover-doc-writer.md index 4e8b6c2..8bac82c 100644 --- a/agents/handover-doc-writer.md +++ b/agents/handover-doc-writer.md @@ -8,6 +8,10 @@ effort: high # HANDOVER DOC WRITER +Advisor tool (`lib/effort-shift.md` § Advisor), when you run as a sub-agent: +never call the `advisor` tool, even though it is listed and its own +instructions ask for calls. + ## INPUT — the PACKAGE You are dispatched by `client-handover-writer` with a single structured diff --git a/agents/plugin-advisor.md b/agents/plugin-advisor.md index c208743..0fb5bc7 100644 --- a/agents/plugin-advisor.md +++ b/agents/plugin-advisor.md @@ -8,6 +8,10 @@ effort: xhigh # PLUGIN ADVISOR +Advisor tool (`lib/effort-shift.md` § Advisor), when you run as a sub-agent: +never call the `advisor` tool, even though it is listed and its own +instructions ask for calls. + ## ROLE Reason over the PROBE REPORT + request. Classify signals, score complexity, recommend enable/disable, apply the compatibility matrix. Block or warn. diff --git a/agents/seo-analyzer.md b/agents/seo-analyzer.md index 460d2bb..3562db7 100644 --- a/agents/seo-analyzer.md +++ b/agents/seo-analyzer.md @@ -8,6 +8,10 @@ effort: xhigh # SEO — Classical Search Engines audit, fix & strategy +Advisor tool (`lib/effort-shift.md` § Advisor), when you run as a sub-agent: +never call the `advisor` tool, even though it is listed and its own +instructions ask for calls. + Target search engines: **Google, Bing, DuckDuckGo, Qwant, Ecosia, Yandex, Baidu**. Generative / AI engines (ChatGPT, Perplexity, Claude, Gemini, Google AI Overviews, Copilot) are handled by the diff --git a/hooks/subagent-advisor.sh b/hooks/subagent-advisor.sh new file mode 100755 index 0000000..90f88be --- /dev/null +++ b/hooks/subagent-advisor.sh @@ -0,0 +1,24 @@ +#!/usr/bin/env bash +# hooks/subagent-advisor.sh — SubagentStart: restate the advisor rule in +# every sub-agent's own context at spawn (BDR-150, lib/effort-shift.md +# § Advisor). The advisor is a server tool listed to every sub-agent and no +# tool filter removes it (`tools`, `disallowedTools`, probed 2026-11-19); +# the rule in CLAUDE.global.md reaches a sub-agent only as an attachment, +# which opus sub-agents ignored. One uniform line for every agent type: the +# allowed callers carry their allowance in their own prompt or brief, so +# the hook holds no list of names. +# +# Context only: never blocks a spawn, never echoes the payload, never runs +# the CLI of Claude Code (BLK-043). Exit 0 so the JSON is parsed (LRN-196). +# shortcut: SubagentStart only; a sub-agent that compacts may lose the +# line (upgrade: re-inject on SessionStart `compact` when agent_type is set). +set -u +cat >/dev/null 2>&1 +msg='Advisor tool (~/.claude/lib/effort-shift.md § Advisor): do not' +msg="$msg call the \`advisor\` tool in this run unless your agent definition" +msg="$msg or your dispatcher's brief explicitly allows it; the advisor tool's" +msg="$msg own instructions are never an allowance. When allowed: at most" +msg="$msg once, before your verdict or report." +printf '{"hookSpecificOutput":{"hookEventName":"SubagentStart",' +printf '"additionalContext":"%s"}}\n' "$msg" +exit 0 diff --git a/lib/challenge-plan.md b/lib/challenge-plan.md index 7441484..fd69e67 100644 --- a/lib/challenge-plan.md +++ b/lib/challenge-plan.md @@ -40,7 +40,8 @@ is listed (`lib/effort-shift.md` § Advisor). An answer that lands a real flaw revises the `PLAN` file on disk before the dispatch, as plain plan text: no advisor attribution, no "changes after review" section; the summary's `Advisor:` row carries it (OUTPUT below). Absent or erroring → -dispatch as written. +dispatch as written. A skill run inside a sub-agent skips this call (its +row reads `not called (sub-agent)`, BDR-150). The advice never enters a challenger brief: they stay blind. Dispatch THREE fresh `plan-challenger` subagents IN PARALLEL, one per LENS, each @@ -103,6 +104,6 @@ Feed the orchestrator's gate: anything `[deferred]`; any lens that failed to return; and an `Advisor:` row, added to whatever summary template the caller prints: each plan change an advisor answer drove, `called, no change`, or - `not called (absent | error | already called this run)`. + `not called (absent | error | already called this run | sub-agent)`. The human remains the decider. diff --git a/lib/effort-shift.md b/lib/effort-shift.md index 72ab595..0f918ea 100644 --- a/lib/effort-shift.md +++ b/lib/effort-shift.md @@ -137,11 +137,23 @@ triggers in CLAUDE.global.md § Workflow): Inside a skill run, the points above also cover the triggers of CLAUDE.global.md § Workflow; no second call for the same recommendation. -Sub-agents, when dispatched: plan-challenger, verifier, security-auditor -and `analyzer` call it at most once per dispatch, before their verdict or -report; executors and every other sub-agent do not, even when the tool is -listed. The analyzer file loaded inline by the main loop follows the -main-loop points. +Sub-agents, when dispatched: plan-challenger, verifier, security-auditor, +`analyzer` and an opus code review (ship-feature STEP 6, init-project +STEP 10, a standalone subagent-driven-development final review) call it +at most once per dispatch, before their verdict or report; executors and +every other sub-agent never call it, even when the tool is listed. The +rule rides each sub-agent's own text: the allowed agents' prompts, a +`never call` line in the opus-served agents and in the opus briefs we +write (a brief sending a general-purpose agent to opus says which rule +applies; a code review's says it may call once), and, for every spawn +including built-ins such as `Plan`, the SubagentStart hook +hooks/subagent-advisor.sh. A skill run by a sub-agent reads +`not called (sub-agent)` in its `Advisor:` row. +subagent-driven-development, whoever runs it, dispatches every worker +(implementers, task reviewers, re-reviews, fix rounds) on sonnet +(BDR-066), as ship-feature and init-project pin it; run standalone, its +final whole-branch review runs on opus as a code review. The analyzer +file loaded inline by the main loop follows the main-loop points. Advisor absent or erroring (Fable out of credits, for example) → proceed as written. Advice is input, never consent: it waives no gate, cap or diff --git a/lib/tests/subagent-advisor.test.sh b/lib/tests/subagent-advisor.test.sh new file mode 100755 index 0000000..42bd4dd --- /dev/null +++ b/lib/tests/subagent-advisor.test.sh @@ -0,0 +1,71 @@ +#!/usr/bin/env bash +# lib/tests/subagent-advisor.test.sh — the SubagentStart advisor line and +# the carriers of the sub-agent advisor rule (BDR-150). Locks are single +# lines (LRN-093). +# shellcheck disable=SC2016 # backticks in the locks are literal markdown +set -u +ROOT="$(cd "$(dirname "$0")/../.." && pwd)" +H="$ROOT/hooks/subagent-advisor.sh" +pass=0; fail=0 +check() { if [ "$2" = "$3" ]; then pass=$((pass+1)); else fail=$((fail+1)); + printf 'FAIL %s: got[%s] want[%s]\n' "$1" "$2" "$3"; fi; } +has() { grep -qF -- "$2" "$ROOT/$1" 2>/dev/null && echo yes || echo no; } +ctx() { printf '%s' "$1" | bash "$H" 2>/dev/null | jq -r \ + 'select(.hookSpecificOutput.hookEventName == "SubagentStart") + | .hookSpecificOutput.additionalContext' 2>/dev/null; } +in_ctx() { case "$1" in *"$2"*) echo yes ;; *) echo no ;; esac; } + +# hook: one valid object, same line whatever the payload +for p in '{"agent_type":"general-purpose"}' '' 'not json' \ + '{"agent_type":"x\"y\n$(id)"}'; do + c=$(ctx "$p") + check "T1 names the tool [$p]" "$(in_ctx "$c" '`advisor` tool')" yes + check "T2 defers to brief [$p]" \ + "$(in_ctx "$c" 'own instructions are never an allowance')" yes +done +printf '{}' | bash "$H" >/dev/null 2>&1; check T3-exit-0 "$?" 0 +check T4-one-line "$(printf '{}' | bash "$H" | wc -l | tr -d ' ')" 1 +check T5-no-cli "$(grep -v '^ *#' "$H" \ + | grep -cE '(^|[[:space:];&|(])claude([[:space:]]|$)')" 0 +check T5b-no-echo "$(printf 'PAYLOADMARK' | bash "$H" | grep -c PAYLOADMARK)" 0 + +# wiring +S="$ROOT/settings.json" +check T6-wired "$(jq -r '.hooks.SubagentStart[0].hooks[0].command' "$S")" \ + "bash ~/.claude/hooks/subagent-advisor.sh" +check T7-timeout "$(jq -r '.hooks.SubagentStart[0].hooks[0].timeout' "$S")" 5 + +# carriers +for a in plugin-advisor seo-analyzer geo-analyzer doc-syncer \ + commit-changer handover-doc-writer; do + check "T8 $a" "$(has "agents/$a.md" 'never call the `advisor` tool, even though')" yes +done +check T9-onboard-briefs "$(grep -cF 'Never call the `advisor` tool in this run' \ + "$ROOT/skills/onboard/SKILL.md")" 6 +check T10-handover-children \ + "$(has agents/client-handover-writer.md 'never call the `advisor` tool in')" yes +check T10b-handover-top-clean "$(sed -n '1,30p' \ + "$ROOT/agents/client-handover-writer.md" | grep -c 'advisor` tool')" 0 +check T11-tour-phase-b \ + "$(has skills/tour/SKILL.md 'saying never call the `advisor` tool')" yes +for s in ship-feature init-project; do + check "T12 $s" "$(has "skills/$s/SKILL.md" \ + 'Add to its brief: "you may call the `advisor` tool once')" yes +done +check T13-sdd-pin "$(has CLAUDE.global.md \ + 'subagent-driven-development standalone: workers sonnet')" yes +check T14-global-set "$(has CLAUDE.global.md \ + 'and an opus code review at most')" yes +check T15-effort-hook "$(has lib/effort-shift.md \ + 'hooks/subagent-advisor.sh. A skill run by a sub-agent reads')" yes +check T16-effort-sdd "$(has lib/effort-shift.md \ + 'subagent-driven-development, whoever runs it')" yes +check T17-row-reason "$(has lib/challenge-plan.md \ + 'already called this run | sub-agent)')" yes +check T19-advisor-first-skip "$(has lib/challenge-plan.md \ + 'A skill run inside a sub-agent skips this call')" yes +check T18-no-old-row "$(cd "$ROOT" && git grep -c 'already called this run)' \ + -- skills lib ':!lib/tests' | wc -l | tr -d ' ')" 0 + +echo "subagent-advisor: $pass pass, $fail fail" +[ "$fail" -eq 0 ] diff --git a/settings.json b/settings.json index 5055aa0..dd82331 100644 --- a/settings.json +++ b/settings.json @@ -572,6 +572,17 @@ ] } ], + "SubagentStart": [ + { + "hooks": [ + { + "type": "command", + "command": "bash ~/.claude/hooks/subagent-advisor.sh", + "timeout": 5 + } + ] + } + ], "PostToolUse": [ { "matcher": "Edit|Write", diff --git a/skills/audit-delta/SKILL.md b/skills/audit-delta/SKILL.md index e454970..38e120d 100644 --- a/skills/audit-delta/SKILL.md +++ b/skills/audit-delta/SKILL.md @@ -192,7 +192,7 @@ CHALLENGE SUMMARY (3b-bis — 3 lenses): BLOCKERs addressed : — Deferred (human-ack): Lenses returned : correctness / robustness / simplicity (NAME any that failed to return) - Advisor : + Advisor : ``` - "Fix what you find" said **in the invocation** does NOT skip this gate: diff --git a/skills/code-clean/SKILL.md b/skills/code-clean/SKILL.md index 94b3f4d..0cb7b5c 100644 --- a/skills/code-clean/SKILL.md +++ b/skills/code-clean/SKILL.md @@ -144,7 +144,7 @@ CHALLENGE SUMMARY (STEP 3b — 3 lenses): BLOCKERs addressed : — Deferred (human-ack): Lenses returned : correctness / robustness / simplicity (NAME any that failed to return) - Advisor : + Advisor : AskUserQuestion: Approve which items for execution? (all / / clarify ) diff --git a/skills/harden/SKILL.md b/skills/harden/SKILL.md index db3c75b..d218044 100644 --- a/skills/harden/SKILL.md +++ b/skills/harden/SKILL.md @@ -557,7 +557,7 @@ If MODE=fix and `.claude/audits/HARDEN.md` ends with `READY TO APPLY — awaitin BLOCKERs addressed : — Deferred (human-ack): Lenses returned : correctness / robustness / simplicity (NAME any that failed to return) - Advisor : + Advisor : Options : A) Apply all diff --git a/skills/init-project/SKILL.md b/skills/init-project/SKILL.md index d31f6f0..40066ab 100644 --- a/skills/init-project/SKILL.md +++ b/skills/init-project/SKILL.md @@ -213,7 +213,7 @@ CHALLENGE SUMMARY (STEP 6b — 3 lenses): BLOCKERs addressed : — Deferred (human-ack): Lenses returned : correctness / robustness / simplicity (NAME any that failed to return) - Advisor : + Advisor : Approve and start? (yes / request changes) ``` Changes → back to STEP 6. Approved → continue. @@ -275,8 +275,9 @@ first ran → the main loop calls the advisor per `lib/verify-secure-loop.md` ## STEP 10 — CODE REVIEW Invoke `requesting-code-review` (vendored superpowers skill). **Model routing (BDR-077):** the review subagent it dispatches MUST carry `model: "opus"` and `effort="xhigh"` in the Agent call — -craft review is dispatched judgment, never inherited from the session. Fix -all CRITICAL before proceeding. +craft review is dispatched judgment, never inherited from the session. +Add to its brief: "you may call the `advisor` tool once, before your +verdict" (code review, BDR-150). Fix all CRITICAL before proceeding. ## STEP 10b — CAPITALIZE FOUNDING DECISIONS (memory registries) A greenfield's founding architecture decisions are the highest-value BDRs — the diff --git a/skills/onboard/SKILL.md b/skills/onboard/SKILL.md index 0fcbecc..d544720 100644 --- a/skills/onboard/SKILL.md +++ b/skills/onboard/SKILL.md @@ -403,6 +403,7 @@ Agent( effort="xhigh", description="Onboard — code-clean audit only (read-only, opus)", prompt=""" + Never call the `advisor` tool in this run (sub-agent, BDR-150). AUDIT-ONLY mode — NO fixes, NO refactoring, NO file modifications. Target: . ARCHETYPE: . Produce a report covering: @@ -441,6 +442,7 @@ bash $HOME/.claude/lib/profile.sh -C "$PWD" current --plain 2>/dev/null | grep - effort="xhigh", description="Onboard — security audit fallback (archetype-adaptive)", prompt=""" + Never call the `advisor` tool in this run (sub-agent, BDR-150). READ-ONLY security audit. No file modifications. Target: . ARCHETYPE: . Category: . Stack: . @@ -690,6 +692,7 @@ Agent( effort="xhigh", description="Onboard — static design review fallback", prompt=""" + Never call the `advisor` tool in this run (sub-agent, BDR-150). AUDIT-ONLY mode — NO edits. Static design review du code UI. Target: . Archetype: . Context: ui-ux-pro-max plugin state = . @@ -735,6 +738,7 @@ Agent( effort="xhigh", description="Onboard — static perf audit", prompt=""" + Never call the `advisor` tool in this run (sub-agent, BDR-150). AUDIT-ONLY mode — NO edits. Target: . Archetype: . Static perf audit (pas de browser) : @@ -779,6 +783,7 @@ Agent( effort="xhigh", description="Onboard — static a11y audit", prompt=""" + Never call the `advisor` tool in this run (sub-agent, BDR-150). AUDIT-ONLY mode — NO edits. Target: . Archetype: . Static a11y audit (WCAG 2.1 AA + RGAA 4.1 France) : @@ -826,6 +831,7 @@ Agent( effort="xhigh", description="Onboard — synthèse vers .claude/audits/", prompt=""" + Never call the `advisor` tool in this run (sub-agent, BDR-150). Lire tous les fichiers de /.onboard-audit/ : - analyze.md, code-clean.md, cso.md, doc.md (toujours) - seo.md, geo.md, design.md, perf.md, a11y.md (si présents) @@ -961,7 +967,7 @@ CHALLENGE SUMMARY (STEP 7b — 3 lenses): BLOCKERs addressed : — Deferred (human-ack): Lenses returned : correctness / robustness / simplicity (NAME any that failed to return) - Advisor : + Advisor : Prochaine étape : générer .claude/tasks/TODO.md depuis .claude/audits/AUDIT_PROPOSALS.md approuvé. diff --git a/skills/pack-seo/skills/geo/SKILL.md b/skills/pack-seo/skills/geo/SKILL.md index c19cd31..a954054 100644 --- a/skills/pack-seo/skills/geo/SKILL.md +++ b/skills/pack-seo/skills/geo/SKILL.md @@ -138,7 +138,7 @@ CHALLENGE SUMMARY (STEP 1b — 3 lenses): BLOCKERs addressed : — Deferred (human-ack): Lenses returned : correctness / robustness / simplicity (NAME any that failed to return) - Advisor : + Advisor : Approve all / select (ids) / skip all? ``` diff --git a/skills/pack-seo/skills/seo/SKILL.md b/skills/pack-seo/skills/seo/SKILL.md index 72d185c..04e425d 100644 --- a/skills/pack-seo/skills/seo/SKILL.md +++ b/skills/pack-seo/skills/seo/SKILL.md @@ -583,7 +583,7 @@ CHALLENGE SUMMARY (STEP 1b — 3 lenses): BLOCKERs addressed : — Deferred (human-ack): Lenses returned : correctness / robustness / simplicity (NAME any that failed to return) - Advisor : + Advisor : Approve all / select (ids) / skip all? ``` diff --git a/skills/pack-web-validate/skills/web-validate/SKILL.md b/skills/pack-web-validate/skills/web-validate/SKILL.md index e9fed22..0715ca4 100644 --- a/skills/pack-web-validate/skills/web-validate/SKILL.md +++ b/skills/pack-web-validate/skills/web-validate/SKILL.md @@ -296,7 +296,7 @@ CHALLENGE SUMMARY (STEP 2b — 3 lenses) : BLOCKERs addressed : — Deferred (human-ack): Lenses returned : correctness / robustness / simplicity (NAME any that failed to return) - Advisor : + Advisor : Options : A) Apply all diff --git a/skills/ship-feature/SKILL.md b/skills/ship-feature/SKILL.md index c791b27..81ae90a 100644 --- a/skills/ship-feature/SKILL.md +++ b/skills/ship-feature/SKILL.md @@ -163,7 +163,7 @@ CHALLENGE SUMMARY (STEP 2b — 3 lenses): BLOCKERs addressed : — Deferred (human-ack): Lenses returned : correctness / robustness / simplicity (NAME any that failed to return) - Advisor : + Advisor : Approve and execute? (yes / request changes) ``` This block EXPOSES each in-force item with the plan's CLAIMED disposition, for human @@ -257,8 +257,9 @@ first ran → the main loop calls the advisor per `lib/verify-secure-loop.md` ## STEP 6 — CODE REVIEW Invoke `requesting-code-review` (vendored superpowers skill). **Model routing (BDR-077):** the review subagent it dispatches MUST carry `model: "opus"` and `effort="xhigh"` in the Agent call — -craft review is dispatched judgment, never inherited from the session. Fix -all CRITICAL before proceeding. +craft review is dispatched judgment, never inherited from the session. +Add to its brief: "you may call the `advisor` tool once, before your +verdict" (code review, BDR-150). Fix all CRITICAL before proceeding. ## STEP 7 — CAPITALIZE (memory registries) Call memory_pending first, per /capitalize STEP 1 "Captured first". diff --git a/skills/tour/SKILL.md b/skills/tour/SKILL.md index c8e02e6..7931d02 100644 --- a/skills/tour/SKILL.md +++ b/skills/tour/SKILL.md @@ -174,7 +174,8 @@ honestly in the summary. Never loop past 3. ### Phase B — CLEAN 1. Dispatch a read-only cleanup audit (analyzer — opus row, BDR-076 — - or general-purpose with `model="opus"`, `effort="xhigh"`; NOT the sonnet code-cleaner, + or general-purpose with `model="opus"`, `effort="xhigh"`, its brief + saying never call the `advisor` tool; NOT the sonnet code-cleaner, which is now a fix executor): dead code, unused imports/exports, commented-out blocks, stale flags, norm violations. Findings as `id | file:line | finding | proposed fix`.