diff --git a/.claude/audits/BUGS-FOUND.md b/.claude/audits/BUGS-FOUND.md index 92da552..d16b54c 100644 --- a/.claude/audits/BUGS-FOUND.md +++ b/.claude/audits/BUGS-FOUND.md @@ -106,6 +106,7 @@ - lib/model-gate.md `fixed at spawn` row: inside a sub-agent the gate proceeds whatever model the child really runs on (the route answer names no id); fix direction: print the spawn id from `agentModels` in `routedText` ("fixed at spawn: ") and keep the id check. The repo-wide fable census (lib/tests/model-routing.test.sh) uses `git grep` (tracked files only) and the regex `model ?[:=] ?"fable"` (misses single quotes and unquoted frontmatter); skills/tour runner inherits the session model by design (BDR-084), so a hand-picked Fable session runs it on Fable. Severity: low. Discovered while: /feat fable-pins-to-opus security gate and verifier. Not fixed. - CLAUDE.global.md § Workflow + lib/effort-shift.md § Advisor: "sub-agents do not" call the advisor is prose only; sub-agents get the advisor tool listed and the harness prompt tells them to call it (seen live in this run's challengers and gates), each call forwarding that agent's whole transcript to Fable outside the router's caps (cost, BLK-030 credits). Fix direction: a mechanical scope (advisorModel for the main session only, if the CLI allows it), else accept. Severity: low. Discovered while: /feat advisor-doctrine plan challenge and security gate. Not fixed. SUPERSEDED 2026-11-17 (6ef3069, /feat advisor-call-points): plan-challenger, verifier, security-auditor now may call it at most once before the verdict; other sub-agents do not. Residual kept: still prose only, and the harness prompt asks sub-agents for "at least once before … and once before declaring done" (a verifier made 2 calls on 2026-11-16), against "at most one call". Severity: low. + FIX SHIPPED, UNVERIFIED 2026-11-20 (7979b9b 6be0669 b71db28, /ship-feature advisor-subagent-scope): no tool filter removes the advisor (probed), so the rule rides each sub-agent's own text (allowed agents "one call allowed", never-call lines in opus agents and briefs, opus code review one call) + SubagentStart hook hooks/subagent-advisor.sh + standalone SDD workers on sonnet. FIXED once the dated TODO behavioural check passes. - agents/security-auditor.md:166 (advisor bullet) — "overrides the STEP 2 mapping for that finding only" has no direction: read alone, an advisor "raise" into a lower STEP 3 class could take a semgrep HIGH out of BLOCK(n); only the closing "never removes, lowers or waives" stops it. Fix direction: "overrides it upward only". Severity: low. Discovered while: /feat advisor-call-points security gate r5 (advisor-sourced LOW). Not fixed. FIXED 2026-11-17 (24354d9, /ship-feature advisor-points-b2): a raise applies only when its class's severity is higher than the finding's own; a raise that does not apply, or matches no class, changes nothing (no tag, no PROOF count); "Advice never removes, lowers or waives" kept. - agents/verifier.md + agents/security-auditor.md advisor bullets — not scoped to dispatch (analyzer's is, 58a5273); lib/verify-secure-loop.md:54,:96 still allow "or load agents/.md" inline, where the gate's own call would be a main-loop call and void the stuck-call unit "no main-loop advisor call since GATE 0 first ran". No skill takes the inline path today. Fix direction: "when dispatched" in both bullets. Severity: low. Discovered while: /feat advisor-points-b1 re-challenge. Not fixed. diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index 5309617..ad4a9b7 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -1613,3 +1613,4 @@ Supersedes [[BDR-030]]. - **Status (2026-11-17)**: accepted, amended 58a5273: plan point in lib/challenge-plan.md (on written plan before challengers, once per skill run, Advisor: row in CHALLENGE SUMMARY, no attribution in plan); stuck lines inline in verify-secure-loop (main-loop calls only since GATE 0); dispatched analyzer joins; trigger before recommending doctrine/architecture/public-interface change - **Status (2026-11-17)**: accepted, amended 6022b9d: B2 stuck trigger in 6 gate skills (points to verify-secure-loop); end-of-run call before done/merge in feat, bugfix, ship-feature, init-project, a11y, guardrails, audit-delta+tour (fix applied only), release-candidate STEP 4; own budget; gate flows print diff stat, fix back through gates; verifier/security-auditor/plan-challenger advise only when dispatched; auditor raise upward only; plan-challenger protocol mirror. Commits f48343e 24354d9 6022b9d - **Status (2026-11-18)**: accepted, amended 51f343f: B3: challenge route rides first lib/challenge-plan.md call; summary Advisor row in 12 callers; feat/bugfix skip end call when GATE 0 MET + verifier CONFORME + security PASS (not DEGRADED, TOOL line) first attempt, ADVISOR field shows skip; item 3 reuse clause names later code commits +- **Status (2026-11-20)**: accepted, amended 7979b9b..b71db28: allowed set + opus code review (ship-feature STEP 6, init-project STEP 10, standalone SDD final) one call via brief; never-call lines in opus agents/briefs; SubagentStart hook hooks/subagent-advisor.sh backstop; standalone SDD workers sonnet; Advisor row reason sub-agent diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index 1a621c2..97dc74b 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -786,3 +786,6 @@ rules: - /bugfix degraded-tool-line 9814720: 3 security readers read DEGRADED off TOOL line (BLK-051), BUGS-FOUND:134 FIXED, TODO:13 done, 2 pre-existing minors logged; CHANGELOG Fixed entry. - /feat x2 merge-reuse (af846d6, 87566e2, feature/advisor-merge-reuse): 6 gate-flow end lines restate effort-shift item 3 merge-reuse clause, loops-light 97; TODO:14 done, 3 follow-ups logged; run 1 GATE 0 ERROR = contract without EVIDENCE: pending (LRN-173 again). - Run C /feat advisor-usage (c6f2dad + retention fix, feature/advisor-usage): FEEDBACK.md advisor usage table per caller/model, reconciled vs probe (156 calls, 21.7M); found general-purpose sub-agent advisor leak (30 calls, 7.1M) → TODO; LRN-301 (call = served iteration), LRN-302 (scratch develop ref); mods.test.sh timeout under load → BUGS-FOUND. + +## 2026-11-20 +- /ship-feature advisor-subagent-scope (7979b9b 6be0669 b71db28): leak root cause = advisor server tool on every sub-agent, no filter, opus ignores CLAUDE.md attachment; rule moved into agent defs/briefs + SubagentStart hook + SDD sonnet pin; LRN-303; behavioural proof pending next usage table. diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md index 58ad83b..26224a5 100644 --- a/.claude/memory/learnings.md +++ b/.claude/memory/learnings.md @@ -2174,3 +2174,9 @@ Rule: when editing a doctrine file under structure locks, grep the test's lock s - **Context**: 2026-11-19 merge-reuse run 2 simulation (LRN-296 method): criterion 3 SKIP-INTACT failed only on scratch clone; fixed by creating ref. - **Apply**: every LRN-296 scratch simulation from a non-develop branch: create local develop ref first, else false red. - **Reference**: LRN-296, .claude/tasks/contracts/2026-11-19-merge-reuse-feat-bugfix-1450.md + +## LRN-303 — Server tool scope per sub-agent: no filter removes advisor; rule must ride agent definition or brief, hook is backstop (2026-11-20) +- **Pattern**: server-side advisor tool attached to every sub-agent (sonnet too); no tool filter removes it: `tools` allowlist, agent `disallowedTools: ["advisor"]`, `--disallowedTools advisor` all probed 2026-11-19, still listed. Opus sub-agents ignored CLAUDE.global rule delivered as `instructions` attachment (18/25 called); agents carrying rule in own definition (system prompt) obeyed (≤1 call per dispatch, 89 dispatches). Sonnet never called (0/~450). SubagentStart `additionalContext` reaches sub-agent before first turn (nonce probe) = attachment channel too. +- **Context**: 2026-11-19/20 advisor leak (Run C table: general-purpose 30 calls 7.1M tok, 29 from standalone SDD on opus in another repo). Fix 7979b9b..b71db28: rule in each agent definition/brief, SDD workers sonnet, hook backstop. +- **Apply**: to scope any harness-listed server tool per sub-agent: put rule in agent definition or dispatcher brief, not CLAUDE.md; word allowance as explicit permission ("one call allowed"); hook = backstop only; behavioural proof = transcript tally, not delivery. +- **Reference**: hooks/subagent-advisor.sh, lib/effort-shift.md § Advisor, LRN-294, LRN-295, LRN-301, BDR-150 diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index 77ba290..1e1b44a 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -16,7 +16,12 @@ Done history before 2026-10-08 removed 2026-10-23 (git keeps it: `git log -p -- - [ ] item 3 "names any code commit made after it" has no anchor: ADVISOR field records no HEAD SHA, commits made outside the session are invisible; candidate: record the short SHA with the answer (visible format change, user decision) (merge-reuse robustness challenger, low) - [ ] end-of-run sites restate the call but not "one end-of-run call per skill run": a fix that goes back through the gates re-enters the end step and may call again (merge-reuse robustness challenger, low) - [x] DONE c6f2dad + 63f5fa4, merged 6e45536 (docs 7d09837, audits 77aac4b, memory 3ffd81f) (/feat feature/advisor-usage; user 2026-11-19: FEEDBACK.md section, per agentType, all projects no repo, since last run, retention + drift lines). Was: Run C /feat: advisor usage section in /memory-feedback (main loop vs sub-agents, model served, input tokens; dedupe usage rows by message.id, model from the `advisor_message` iteration) -- [ ] Advisor doctrine leak: general-purpose sub-agents called the advisor 30× (7.1M input tok, the largest line of the first advisor usage table; 16 on 2026-11-18/19, after 6ef3069 2026-11-17 12:59 limited sub-agents to plan-challenger/verifier/security-auditor/analyzer), doc-syncer 4× (2026-11-16/17). Likely SDD implementers/reviewers dispatched as general-purpose: find why the "executors and every other sub-agent do not" rule does not reach them (brief, agent prompt or tool listing) (Run C first table, medium) +- [x] FIX SHIPPED 7979b9b 6be0669 b71db28 (/ship-feature feature/advisor-subagent-scope; behavioural proof pending, next line). Was: Advisor doctrine leak: general-purpose sub-agents called the advisor 30× (7.1M input tok, the largest line of the first advisor usage table; 16 on 2026-11-18/19, after 6ef3069 2026-11-17 12:59 limited sub-agents to plan-challenger/verifier/security-auditor/analyzer), doc-syncer 4× (2026-11-16/17). Likely SDD implementers/reviewers dispatched as general-purpose: find why the "executors and every other sub-agent do not" rule does not reach them (brief, agent prompt or tool listing) (Run C first table, medium) +- [ ] 2026-11-27 or later, after a fresh session: advisor leak behavioural check. Run /memory-feedback (advisor usage table) plus a per-dispatch transcript tally since 7979b9b. Tripwires: every typed non-allowed type 0 calls; sonnet stays 0; general-purpose at most 1 call per dispatch and only in code-review dispatches; allowed four keep about 1 per dispatch (a drop to 0 = the "one call allowed" line not read); standalone SDD workers served sonnet. Revert path: drop the SubagentStart entry from settings.json. Then mark BUGS-FOUND :107 FIXED or reopen (advisor-subagent-scope, medium) +- [ ] lib/memory-feedback/advisor.ts: split general-purpose callers per dispatch (calls per dispatch, code-review vs other from a fixed description marker), so the advisor usage table can read the general-purpose tripwire without a hand tally (advisor-subagent-scope robustness challenger, low) +- [ ] census test: every agents/*.md served on opus (frontmatter or a model="opus" dispatch) carries either the never-call line or an allowance; every model="opus" general-purpose brief in skills/agents names its advisor rule (STEP 6 review minor 3, low) +- [ ] hooks/subagent-advisor.sh shortcut: SubagentStart only, a sub-agent that compacts may lose the line; re-inject on SessionStart `compact` when agent_type is set (hook header shortcut, low) +- [ ] advisor-scope review minors: lib/model-gate.md Dispatch tiers names the advisor line for opus built-ins; feat/bugfix ADVISOR fields gain `not called (sub-agent)`; client-handover-writer quoted child templates carry the line literally, not only the routing paragraph (STEP 6 review minors 1, 6, 8, low) - [ ] lib/tests/mods.test.sh model-router plugin test runs ~121 s alone vs CLI_TIMEOUT=120 (load avg 26-31 on 2026-11-19): flaky red in make test, probable cause of run 1 feater's unexplained red; raise the bound or speed the test (Run C GATE 0, low) - [x] Stale citers after A: README/USAGE/CHANGELOG patched, BUGS-FOUND residual superseded + LOW logged, BDR-150 status, LRN-295 (LRN-294 kept: its lesson holds) diff --git a/.claude/tasks/contracts/2026-11-19-advisor-subagent-scope-2035.md b/.claude/tasks/contracts/2026-11-19-advisor-subagent-scope-2035.md new file mode 100644 index 0000000..a7cc88c --- /dev/null +++ b/.claude/tasks/contracts/2026-11-19-advisor-subagent-scope-2035.md @@ -0,0 +1,57 @@ +# CONTRACT — advisor-subagent-scope +- date: 2026-11-19 | flow: ship-feature | branch: feature/advisor-subagent-scope +- status: active + +## REQUEST (verbatim — IMMUTABLE) +corrige la fuite advisor des sous-agents et fais les todos, et si il y en a d'autre ensuite fais les, tant que des todos apparaissent fais les sauf si tu vois que ca se repete + +Scope of this run (main loop): the advisor sub-agent leak (TODO advisor-leak), escalated from /bugfix (>5 files). Diagnosis and probes: .claude/tasks/plans/2026-11-19-subagent-advisor-hook-1905.md. + +## CLARIFICATIONS +Q: fix layers / A: "Both": SDD sonnet pin + never-call lines in opus-served agent prompts and opus briefs + a SubagentStart hook backstop [gated 2026-11-19] +Q: opus judgment reviewers / A: "Allow code reviews once": the opus code review (ship-feature STEP 6, init-project STEP 10, standalone SDD final review) may call the advisor at most once before its verdict; other judgment children never [gated 2026-11-19] +Q: merges in the TODO loop / A: gitflow finish per item once gates are clean [gated 2026-11-19] +Q: design / A: approved: carriers = CLAUDE.global.md § Skill routing (SDD pin) + § Workflow (allowed set, brief rule, hook) + lib/effort-shift.md § Advisor detail; six agent prompts (plugin-advisor, seo-analyzer, geo-analyzer, doc-syncer, commit-changer, handover-doc-writer); onboard's six opus briefs; client-handover-writer routing paragraph (not its top prompt: inline-loaded by the main loop); tour Phase B; ship-feature STEP 6 + init-project STEP 10 allowance; silent SubagentStart hook, timeout 5; vendored skills-external files NOT edited (update-all.sh overwrites them, BDR-106, BLK-024) [gated 2026-11-19] +Q: Advisor row of a skill run by a sub-agent / A: add `sub-agent` to the `not called (...)` reasons in lib/challenge-plan.md OUTPUT and the 9 caller template rows [gated 2026-11-19] +Q: plugin profile SET dev / A: no, keep full [gated 2026-11-19] + +Q: 3-lens challenge fixes (hook line: agent definition or dispatcher's brief, the tool's own instructions never an allowance, ~/.claude path; all SDD workers sonnet incl. fix rounds, no opus carve-out; imperative code-review brief line; agent lines scoped "when you run as a sub-agent"; atomic applier; tripwire redefined for general-purpose) / A: main loop, internal; no gated choice reopened [2026-11-19] + +Q: STEP 3 validation gate, plan docs/superpowers/plans/2026-11-19-advisor-subagent-scope.md (1 task, 33-check suite) / A: yes, execute [gated 2026-11-20] + +Q: GATE 1 round 1 ECARTS(4): plan artifacts outside FILE SCOPE + SC2016 shellcheck disable (FLOOR) / A: main loop: the docs/superpowers plan + apply.py are transient run artifacts committed during the run and purged by gitflow finish (BDR-065), added to FILE SCOPE; the disable is removed (double quotes with escaped backticks, as loops-light), no suppression authorized [2026-11-20] + +Q: STEP 6 opus review (With fixes: 2 Important) / A: main loop: fixed as plan section "Review fix round 1" (allowed agents' lines reworded "one call allowed" and locked T20; CLAUDE.global parenthetical clarified; hook prohibition locked T2c; plan-challenger mirror; effort-shift "other opus-served agents"; agent lines cite ~/.claude path; test lines ≤ 80); suite 38 checks; other minors to TODO [2026-11-20] + +Q: add agents/{plan-challenger,verifier,security-auditor,analyzer}.md to FILE SCOPE (review fix: "one call allowed", locked T20) / A: yes [gated 2026-11-20] + +## ACCEPTANCE CRITERIA +1. The new suite lib/tests/subagent-advisor.test.sh (hook output + wiring + carrier locks) is green. + CHECK: cd /home/bchanot/Documents/claude && bash lib/tests/subagent-advisor.test.sh 2>&1 | tail -1 | grep -qE '^subagent-advisor: [0-9]+ pass, 0 fail$' && echo SA-GREEN + EXPECT: SA-GREEN + EVIDENCE: MET exit=0 marker-found :: SA-GREEN +2. The hook emits one valid SubagentStart JSON object naming the advisor tool, whatever its stdin, and exits 0. + CHECK: cd /home/bchanot/Documents/claude && for i in '{"agent_type":"general-purpose"}' '' 'not json'; do o=$(printf '%s' "$i" | bash hooks/subagent-advisor.sh); [ $? -eq 0 ] || exit 1; printf '%s' "$o" | jq -e '.hookSpecificOutput.hookEventName == "SubagentStart" and (.hookSpecificOutput.additionalContext | test("advisor"))' >/dev/null || exit 1; done && echo HOOK-OK + EXPECT: HOOK-OK + EVIDENCE: MET exit=0 marker-found :: HOOK-OK +3. settings.json wires SubagentStart to the hook with timeout 5. + CHECK: cd /home/bchanot/Documents/claude && jq -e '.hooks.SubagentStart[0].hooks[0] | .command == "bash ~/.claude/hooks/subagent-advisor.sh" and .timeout == 5' settings.json >/dev/null && echo WIRED + EXPECT: WIRED + EVIDENCE: MET exit=0 marker-found :: WIRED +4. The 9 caller template rows and lib/challenge-plan.md carry the `sub-agent` reason; no row keeps the old closing. + CHECK: cd /home/bchanot/Documents/claude && n=$(grep -l 'already called this run | sub-agent)' skills/init-project/SKILL.md skills/code-clean/SKILL.md skills/onboard/SKILL.md skills/audit-delta/SKILL.md skills/ship-feature/SKILL.md skills/harden/SKILL.md skills/pack-seo/skills/seo/SKILL.md skills/pack-seo/skills/geo/SKILL.md skills/pack-web-validate/skills/web-validate/SKILL.md lib/challenge-plan.md | wc -l); [ "$n" -eq 10 ] && ! git grep -q 'already called this run)' -- skills lib ':!lib/tests' && echo ROWS-10 + EXPECT: ROWS-10 + EVIDENCE: MET exit=0 marker-found :: ROWS-10 +5. CLAUDE.global.md stays within its 320-line density budget. + CHECK: cd /home/bchanot/Documents/claude && [ "$(wc -l < CLAUDE.global.md)" -le 320 ] && echo BUDGET-OK + EXPECT: BUDGET-OK + EVIDENCE: MET exit=0 marker-found :: BUDGET-OK +6. Full make test green. + CHECK: cd /home/bchanot/Documents/claude && PATH=$HOME/.bun/bin:$PATH make test &1 | tail -1 + EXPECT: all suites green + EVIDENCE: MET exit=0 marker-found :: all suites green +7. Live delivery: a headless run with a scratch settings file wiring the real hooks/subagent-advisor.sh shows a sub-agent quoting the injected rule (manual, recorded by the main loop; this session may not reload settings). Behavioural proof is NOT claimed here: it is the next /memory-feedback advisor usage table plus a per-dispatch transcript check (dated TODO; tripwires: every typed non-allowed type → 0 calls, sonnet stays 0, general-purpose at most 1 call per dispatch and only in code-review dispatches, checked by hand until advisor.ts splits general-purpose by dispatch; revert = drop the settings entry). +8. No vendored skills-external file edited; no wording changed outside the plan's blocks; new prose lines ≤ 80 columns (manual). + +## FILE SCOPE +hooks/subagent-advisor.sh (new), lib/tests/subagent-advisor.test.sh (new), settings.json, CLAUDE.global.md, lib/effort-shift.md, lib/challenge-plan.md, agents/{plugin-advisor,seo-analyzer,geo-analyzer,doc-syncer,commit-changer,handover-doc-writer,client-handover-writer}.md, skills/onboard/SKILL.md, skills/tour/SKILL.md, skills/ship-feature/SKILL.md, skills/init-project/SKILL.md, skills/{code-clean,audit-delta,harden}/SKILL.md, skills/pack-seo/skills/{seo,geo}/SKILL.md, skills/pack-web-validate/skills/web-validate/SKILL.md, docs/superpowers/plans/2026-11-19-advisor-subagent-scope.md + docs/superpowers/plans/2026-11-19-advisor-subagent-scope/apply.py (transient, BDR-065), agents/{plan-challenger,verifier,security-auditor,analyzer}.md (review fix round 1, gated) diff --git a/.claude/tasks/plans/2026-11-19-subagent-advisor-hook-1905.md b/.claude/tasks/plans/2026-11-19-subagent-advisor-hook-1905.md new file mode 100644 index 0000000..f569cdd --- /dev/null +++ b/.claude/tasks/plans/2026-11-19-subagent-advisor-hook-1905.md @@ -0,0 +1,93 @@ +# Bugfix plan: sub-agents call the advisor against the doctrine (TODO advisor leak) + +## DIAGNOSIS +BUG: sub-agents outside the allowed four call the advisor. First advisor usage table +(2026-11-19): general-purpose 30 calls / 7.1M input tokens (29 in faunosteo's U2 SDD run, 1 the +B3 STEP 6 code review), doc-syncer 4 (opus audit). 16 general-purpose calls came after 6ef3069 +(2026-11-17 12:59) restricted sub-agent calls to plan-challenger, verifier, security-auditor and +analyzer. +ROOT CAUSE: the advisor is a server tool the harness attaches to every sub-agent, whatever its +model, with its own system prompt telling it to call "before substantive work … and before +declaring done". The restriction lives only in CLAUDE.global.md § Workflow and +lib/effort-shift.md § Advisor (:140-143), text a dispatched agent does not hold in its own +prompt; the four allowed agents carry an in-prompt "at most once" line and comply. No tool +filter exists: probed 2026-11-19, the advisor stays listed under a `tools:` allowlist +(plan-challenger), under `--disallowedTools advisor` (headless main) and under an agent's +`disallowedTools: ["advisor"]` (headless sub-agent). Sonnet sub-agents also list it (probe) and +simply never used it (0 calls in ~400 dispatches); opus sub-agents act on the tool's prompt. +EVIDENCE: transcript tally per agentType × model (all 1105 transcripts): every call comes from +an opus-served agent; leakers' meta: general-purpose `model: opus` (faunosteo SDD standalone, +41 opus dispatches; ship-feature's sonnet pin did not apply), doc-syncer `model=opus` audits; +three live probes (opus gp, sonnet gp, headless with/without disallowedTools) all list advisor. +Delivery and compliance proven before planning (2026-11-19): a headless `claude -p --settings +` run with a SubagentStart hook injecting a random nonce → the sub-agent returned the +exact nonce (additionalContext reaches the sub-agent before its first turn). In-context rules are +obeyed: since 6ef3069 the four allowed types made at most 1 call per dispatch (plan-challenger +43×1, verifier 22×1 + 3×0, security-auditor 21×1 + 1×0, analyzer 3×1); each carries its line in +its own prompt (agents/analyzer.md:46 and the other three). +PRIOR: LRN-294 (check what tools sub-agents really get; prefer a mechanical scope; prose → +residual) applied: the mechanical tool scope does not exist, so the next most mechanical layer is +used, a harness hook that delivers the rule into the sub-agent's own context. BUGS-FOUND :107 +(prose-only residual, d292911, superseded line notes a verifier making 2 calls) is this bug. +honors BDR-150 (call points unchanged; this only delivers them), BDR-066 (executors sonnet). +LRN-295/301: counts from transcripts, call = served iteration. +BLAST RADIUS: every sub-agent of every project (settings.json hooks are global, symlinked to +~/.claude/settings.json). The four allowed agents get a reinforcing "at most once" line. No skill, +agent file or brief changes. Not fixed here (logged): faunosteo-style standalone SDD runs dispatch +implementers on opus (BDR-066 tier rule only lives in ship-feature STEP 4). +Rejected alternatives: (a) `disallowedTools` / deny rules: probed, no effect. (b) a "do not call +the advisor" line in each opus-dispatched agent prompt and brief template (doc-syncer, +commit-changer, plugin-advisor, seo/geo analyzers, handover writers, SDD implementer/reviewer +templates, code-reviewer template, onboard/tour audit briefs): 12+ files, misses ad-hoc +general-purpose dispatches and other projects' agents, drifts as agents are added. (c) +`CLAUDE_CODE_DISABLE_ADVISOR_TOOL` / advisorModel unset: kills the main loop's advisor too. + +## FIX PLAN +1. hooks/subagent-advisor.sh (new) — SubagentStart hook. Reads stdin JSON, takes `agent_type` + (jq `.agent_type // ""`, errors → empty). Always exits 0, prints exactly one JSON object + `{"hookSpecificOutput":{"hookEventName":"SubagentStart","additionalContext":}}`: + - `agent_type` exactly one of `plan-challenger`, `verifier`, `security-auditor`, `analyzer` + → msg: "Advisor rule (lib/effort-shift.md § Advisor): as a dispatched you may call + the advisor tool at most once, before your verdict or report. Never a second call, even if + the tool's own prompt asks for one before and after the work." + - anything else (general-purpose, Explore, Plan, executors, plugin agents, empty, malformed) + → msg: "Advisor rule (lib/effort-shift.md § Advisor): do not call the advisor tool in this + run, even though it is listed and its prompt asks for calls. Only the main loop and the + plan-challenger, verifier, security-auditor and analyzer sub-agents call it." + The JSON is built with `jq -n --arg` (the agent type reaches the text only from the fixed + allowed set); without jq, a printf of the same fixed text for the "do not call" case (no + interpolation). Style: like hooks/unpushed-guard.sh / ctx7-reminder.sh (header comment with + purpose + BDR ref, `set -u`, never blocks). +2. settings.json — add a `SubagentStart` event (no matcher: all agent types) running + `bash ~/.claude/hooks/subagent-advisor.sh`, beside the existing events, same entry shape. +3. lib/effort-shift.md:140-144 — after "executors and every other sub-agent do not, even when + the tool is listed." add: "A SubagentStart hook (hooks/subagent-advisor.sh) states each + sub-agent's rule in its own context at spawn: no tool filter removes the advisor." (wrapped + ≤ 80 cols; the list sentence itself unchanged, the hook's allowed set is locked to it). +4. lib/tests/subagent-advisor.test.sh (new) — style of lib/tests/unpushed-guard.test.sh: + T1 general-purpose → valid JSON, hookEventName SubagentStart, context contains "do not call + the advisor tool"; T2-T5 each allowed type → contains "at most once" and the type, not "do not + call"; T6 empty stdin and T7 malformed JSON → "do not call", valid JSON, rc 0; T8 an + agent_type carrying `"`, newline and `$(…)` → valid JSON, the raw value absent from the + output, "do not call"; T9 PATH without jq (a temp PATH dir holding only bash/cat/printf links, + or `env PATH=` minimal) → valid JSON (checked with python3), "do not call"; T10 settings.json + wires `SubagentStart` to `hooks/subagent-advisor.sh` (jq query); T11 consistency: each of the + four allowed names appears in lib/effort-shift.md's "Sub-agents, when dispatched" sentence and + in the hook, and the effort-shift sentence names the hook. Lines ≤ 80 cols where the file + style allows. + +Bookkeeping (main loop): BUGS-FOUND :107 residual → FIXED line; TODO advisor-leak line done; +new TODO: standalone SDD opus dispatches (BDR-066 pin only in ship-feature STEP 4). + +Skill-runner children (onboard, tour, client-handover dispatch opus children that run whole +skills whose text has main-loop advisor points): the hook tells them not to call; proposed rule +(user decision at the STEP 3 gate): the parent main loop owns the call points, a child's own +`Advisor:` row / ADVISOR field reads `not called (sub-agent)`. +Proof of "fixed": the contract proves delivery (headless nonce through the real hook script and a +scratch settings file, since this session may not reload settings) and the hook's output per +type; the behavioural proof is the next /memory-feedback advisor usage table showing no calls +from other agent types after the hook commit (dated follow-up in TODO). + +RISK: low-medium — a new global hook on every sub-agent spawn (cost ~10 ms, a few dozen context +tokens per sub-agent); a hook failure injects nothing (never blocks a spawn). Live check after +commit: a probe sub-agent reports the injected line. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index ca13591..09be995 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -20,7 +20,7 @@ claude-config/ ├── update-all.sh # One-command update for all components ├── Makefile # Unified entry point: make install / doctor / update / test (make help) ├── plugins.lock.json # Version pinning for non-marketplace dependencies and vendored skills -├── hooks/ # Claude Code hooks: session start, statusline, RTK rewrite, ctx7 reminder, attention notify, unpushed-work guard, manual-mode push guard, system-dir extraction guard, instruction-load log, memory digest and memory feedback reminder at session start, code-limits line-width signal +├── hooks/ # Claude Code hooks: session start, statusline, RTK rewrite, ctx7 reminder, attention notify, unpushed-work guard, manual-mode push guard, system-dir extraction guard, instruction-load log, memory digest and memory feedback reminder at session start, code-limits line-width signal, sub-agent advisor rule at spawn ├── githooks/ # Generated git hooks (pre-commit, post-commit, post-merge, reference-transaction), git's global core.hooksPath ├── .githooks/ # This repo's own copy of the same hooks ├── .claude/rules/ # This repo's project path rules (paths: frontmatter), loaded on Read of a matching file diff --git a/CHANGELOG.md b/CHANGELOG.md index 561f96a..9c057d0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -45,6 +45,7 @@ The BDR-125 context queue is delivered: phases 0, 0b, 4a, 1, 5, 2 and 4b-4d ship - `settings.json`: the `autoMode.hard_deny` entry "Disarming the guardrails" now names turning a mod off as disarming: `"enabled": false` in `~/.claude/.json`, a mod's `enabledPlugins` entry set to false, or `profile.sh disable` of a mod. These switches turn off the model-router write guard and the memory mod; the user still sets them by hand. - `lib/gates.sh` (GATE 0 floor): an unindented line under `## ACCEPTANCE CRITERIA` that starts with a digit but is not `N. text` (`1b.`, `1.1`, `2)`) is now a parse error, `malformed criterion label at line N`, and a second `CHECK:`, `EXPECT:` or `EVIDENCE:` on one criterion is one too, `second CHECK: at line N in criterion M`. Either gives `VERDICT: ERROR(n)` (rc 2) and no CHECK runs. An oracle under a label the parser missed used to overwrite the previous criterion's, so a failing criterion could read MET. A label that is not digit-led (indented, bullet) is caught only when the criterion before it already has that attribute; after a manual criterion its oracle is still absorbed. With no criterion parsed, the `no numbered criteria` error now ends with the first parse error. Test: `lib/tests/gates.test.sh`. - Security gate readers (`lib/verify-secure-loop.md`, `agents/security-auditor.md` ORCHESTRATOR PROTOCOL, `skills/hotfix/SKILL.md` STEP 4) no longer read `DEGRADED` as a value of the `SECURITY — VERDICT:` line. The auditor prints `VERDICT: PASS` on a scan without semgrep and reports DEGRADED on its `TOOL:` line, so the old `DEGRADED` branch never fired: a degraded scan read as a clean PASS, the checklist result and the `make plugin` hint were never surfaced, and hotfix's `SECURITY: DEGRADED (checklist only)` summary could not be reached. The `PASS` branch now reads the `TOOL:` line first, and a PASS with no `TOOL:` line is a structural failure (one fresh retry, then escalation). `lib/effort-shift.md` § Advisor names the `TOOL:` line in the feat/bugfix skip condition. The auditor's output format is unchanged. Test: `lib/tests/loops-light.test.sh` (DEGRADED on the TOOL line). +- **Advisor in sub-agents**: opus sub-agents, general-purpose ones included, called the `advisor` tool on their own: 30 calls, 7.1M input tokens. The tool is listed to every sub-agent, its own instructions ask for calls, and the rule in `CLAUDE.global.md` reached them only as an attachment. A new SubagentStart hook, `hooks/subagent-advisor.sh` (`settings.json`, timeout 5 s), tells every sub-agent at spawn not to call it unless its agent definition or its dispatcher's brief allows it, then at most once. The allowed set is 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), whose brief allows one call. plugin-advisor, seo-analyzer, geo-analyzer, doc-syncer, commit-changer and handover-doc-writer, and the opus briefs of `/onboard`, client-handover-writer and `/tour` Phase B, carry a never-call line. A standalone subagent-driven-development run dispatches every worker on sonnet, task reviews and fix rounds included. `Advisor:` rows gain `not called (sub-agent)`. Test: `lib/tests/subagent-advisor.test.sh`. ## [3.0.0] — 2026-11-12 diff --git a/CLAUDE.global.md b/CLAUDE.global.md index 1a25f5b..778434e 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 (each opus + brief you write states its rule; 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/README.md b/README.md index 5fcad3f..5384554 100644 --- a/README.md +++ b/README.md @@ -85,10 +85,13 @@ security PASS, not DEGRADED, each on its first attempt, their summary's `ADVISOR` field then reading `skipped (gates clean on first pass)`; `/audit-delta` and `/tour` when the run applied no fix), and before recommending a change to the doctrine, the architecture or a public interface. -plan-challenger, verifier, security-auditor and `analyzer` may call it once -when dispatched as a sub-agent, before their verdict or report: advice can -add a finding or raise its severity, never drop, lower or clear one. Other -sub-agents do not, even when the tool is listed. An absent or +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) may call it once when dispatched +as a sub-agent, before their verdict or report: advice can add a finding or +raise its severity, never drop, lower or clear one. Other sub-agents never +call it, even when the tool is listed; the SubagentStart hook +`hooks/subagent-advisor.sh` restates the rule in every sub-agent at spawn. An absent or failing advisor changes nothing, and its advice waives no gate, cap or guard (`lib/effort-shift.md` § Advisor). The main loop writes no code outside a skill run (the router's guard redirects it to a skill); the fresh diff --git a/USAGE.md b/USAGE.md index d25515e..377ff89 100644 --- a/USAGE.md +++ b/USAGE.md @@ -200,7 +200,7 @@ l'outil `mcp__model-router__route` (`lib/effort-shift.md`). Les skills externes vendorés (pile design, superpowers, agent-skills, skills scroll MengTo, 21st) ont aussi leur ligne. -Taper un skill qui a une ligne route la boucle principale dessus. Une ligne du tier best (plan, reflect, orchestrate, escalate ; `audit` est une ligne d'agent, jamais tapée) tient d'un tour à l'autre pendant tout le run, jusqu'à `/route clear`, `/route off`, un `/model` tapé ou choisi dans le sélecteur, ou un skill d'un autre tier tapé. Un `/model ` tapé, ou un choix dans le sélecteur `/model`, avec un modèle de la table demande sa portée (Échap ne change rien). Le changement du sélecteur est d'abord retenu (le moteur affiche qu'un hook l'a bloqué), puis la question vient ; un choix fait pendant qu'un autre dialogue est ouvert est refusé (`answer the open dialog first`) : This project écrit l'id complet dans `model` du `.claude/settings.local.json` du projet (créé s'il manque, à garder dans le `.gitignore`) et pose une route de modèle tenue ; This conversation pose la route seule, sans rien écrire ; Everywhere lance le `/model` natif (`settings.json` utilisateur, tous les projets). Default dans le sélecteur, sans argument, avec un nom inconnu, en headless (`-p`) ou mod coupé, le `/model` natif passe sans question. Un modèle choisi dans ce dialogue change toujours : ni plafond de relecture à froid, ni `mainUpgrade` ni `mainModelSwitch`. S'il est en panne, la boucle principale reste où elle est jusqu'à son retour. Un changement natif (ligne Model de `/config` comprise) ou `/clear` l'abandonne ; un `/route model=` tapé garde les plafonds. La ligne Model de `/config` écrit toujours le `settings.json` utilisateur, et un dialogue jamais répondu n'a pas de délai. Pour relancer un tour bloqué : `ultrathink` dans le prompt (plancher d'effort du tour) ou `/route effort=max` (tient jusqu'à `/route clear`). Le `/effort` intégré n'a pas d'effet dans un run : les lignes et les routes passent devant. Les règles de mots-clés du prompt (`plan`, `design`, `architecture`… prennent l'effort de plan ; `pourquoi`, `review`, `audit`… celui de reflect), `ultrathink` et un lancement d'agent par la boucle principale (route `orchestrate` dérivée, tenue jusqu'à la fin de ses agents en arrière-plan) ne fixent que le niveau d'effort du tour, jamais le modèle : ils ne font jamais monter la boucle principale au-dessus du modèle de la session, et un run best tenu garde son modèle. Fable n'arrive sur la boucle principale que par un choix à la main (`/model`, sélecteur), un `/route model=fable` tapé, une phase qui nomme `model: fable` ou une config machine qui le place dans un tier : aucun tier ni aucune phase livrés ne le contiennent. Fable sert de conseiller (outil advisor, `advisorModel` dans settings.json, réglé par `/advisor`) : la boucle principale l'appelle au moins sur le plan écrit, avant que les challengers du plan le voient (`lib/challenge-plan.md`, une fois par run de skill ; la ligne `Advisor:` du CHALLENGE SUMMARY dit ce qu'il a changé), une fois par run verify-secure à la première boucle de porte qui échoue deux fois (le conseil reste dans la boucle principale, jamais dans le brief d'un exécutant ; un STOP au plafond ou en escalade le reprend), avant de proposer un merge ou de déclarer finie une longue tâche (deux exceptions : `/feat` et `/bugfix` le sautent quand GATE 0 a dit MET, le verifier CONFORME et la sécurité PASS, pas DEGRADED, chacun au premier essai, et leur champ `ADVISOR` affiche alors `skipped (gates clean on first pass)` ; `/audit-delta` et `/tour` le sautent quand le run n'a appliqué aucun fix), et avant de recommander un changement de la doctrine, de l'architecture ou d'une interface publique ; plan-challenger, verifier, security-auditor et `analyzer` peuvent l'appeler une fois, seulement quand ils sont lancés comme sous-agents, avant leur verdict ou leur rapport : un conseil peut ajouter un constat ou relever sa sévérité, jamais le retirer, l'abaisser ni l'effacer ; les autres sous-agents ne l'appellent pas, même quand l'outil est listé. Conseiller absent ou en erreur : on continue ; un conseil ne lève aucune porte, aucun plafond ni aucune garde. Un prompt tapé sans règle, skill ni route en cours passe par un classifieur (un appel au petit modèle, 3 secondes au plus) : le tour prend la route de la phase devinée : son niveau d'effort, et son modèle, jamais au-dessus de celui de la session. Une devinette `coding` ou `bookkeeping` fait descendre la boucle principale vers un modèle moins cher quand `mainModelSwitch` est actif (par défaut) et que la relecture à froid tient sous `downgradeMaxTokens` (120000 tokens par défaut). Cette relecture compte aussi le prompt qui vient d'être envoyé (un token pour 3 caractères), et un document joint bloque la descente pour cette étape. Le cache compte comme chaud pendant le TTL du moteur (`cache_ttl`, 5 ou 60 minutes), 60 minutes par défaut. `/route classify off` ou `"classify": false` dans la config machine le coupe, et un `/effort` tapé entre deux tours annule la devinette pour ce tour seulement. Avant d'envoyer la boucle principale sur un modèle, celui vers lequel elle se déplace comme celui qu'elle garde (le modèle de la session compris), le mod l'essaie une fois (un appel minimal, 8 secondes au plus) : sans réponse, ce modèle est marqué en panne (raison `probe`) et la décision est reprise une fois ; `"probe": false` dans la config machine coupe cet essai, et `/route show` affiche `probe:`. Quand un modèle inférieur remplace la tête de son tier en panne (Sonnet pour Opus sur une phase best ; Opus pour Fable si une config machine met fable en tête de best), le niveau propre de la phase monte d'un cran (reflect xhigh, plan max, orchestrate high) ; un niveau demandé explicitement ou un plancher ne bouge jamais. Les sous-agents reçoivent le modèle de leur ligne au lancement (dans leur tier, jamais en dessous de leur frontmatter) et son niveau à chaque étape ; un `model` ou `effort` explicite sur l'appel gagne. Explore tourne en sonnet/medium, Plan en opus/xhigh. Un agent intégré `general-purpose` lancé par la boucle principale sans `model`, pendant que celle-ci tourne sous le modèle de la session (descente, ou repli quand un modèle est en panne), part sur le modèle de la session au lieu d'hériter du modèle inférieur ; les autres types d'agents ne sont jamais épinglés ainsi. `/route show` affiche la route en cours, slot de run compris (`main: run `), et le switch avec son plafond et ce TTL (`switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`). Première utilisation : la première fois qu'un skill avec ligne est tapé, qu'un agent avec ligne est lancé ou qu'une phase est déclarée sur la boucle principale via l'outil `route`, le mod demande une fois si la route convient. La question donne le contexte : la description du skill (première phrase du frontmatter de son `SKILL.md`) ou celle de l'agent, la phase avec sa ligne `about` (champ de la phase dans `routing.json`), puis le modèle et le niveau réels de l'étape suivante ; une phase déclarée dit aussi qui l'utilise. Pour une ligne : Later, Keep ou Change ; pour une phase déclarée : Later ou Keep. Change demande le modèle (opus, sonnet, haiku, chacun avec son tier ; fable n'est pas proposé), puis le niveau parmi ceux des phases de ce modèle (opus : medium, high, xhigh ou max ; sonnet : low, medium, high ou xhigh ; haiku n'en a qu'un, la question est sautée), puis Everywhere ou This project only (exception rangée sous le remote origin du dépôt réduit à `host/path`, jamais d'identifiants). Une ligne reste un nom de phase : le couple modèle et niveau désigne une phase existante, et la même phase qu'avant vaut Keep. Un couple qu'aucune phase n'offre s'ajoute à la main comme nouvelle phase dans `routing.json`. Après un changement sur un skill, un toast donne le modèle et le niveau réels, et rappelle `/route switch on` quand le switch est coupé, ou nomme le plafond quand la relecture à froid bloque la descente. La réponse est écrite dans `routing.json` ; Later, un texte libre (Other) ou un dialogue fermé redemande à une session suivante. Un seul dialogue à la fois, jamais en headless (`-p`) ni dans un sous-agent, et le modèle n'écrit jamais ce fichier. Chaque réponse laisse le repo de config modifié : commite-le depuis ce repo. `/route pending` liste ce qui reste à confirmer, `/route ask off|on` coupe ou rallume le dialogue, `/route forget ` efface une décision (une ligne changée revient à la phase livrée ; `all` et `projects` demandent d'abord). Si une config machine met fable en tête du tier best (aucun tier livré ne le fait), avant qu'une route envoie la boucle principale, ou un agent à ligne, sur Fable depuis un autre modèle, le mod pose une question une seule fois par portée (origine, phase et sa ligne `about`, modèle et niveau) : `Fable`, `Opus instead (big tier)` (Opus à la place : le tier big, niveau de la phase inchangé, le label reste vrai : l'option disparaît si Opus est en panne) ou `Stop asking this session` (ne plus demander cette session : rien n'est écrit, `/clear` la réarme). Un skill chargé par le modèle compte comme une ligne de skill ; un agent n'a qu'une réponse par type et par session ; jamais en headless (`-p`) ni dans un sous-agent ; un dialogue fermé lance Fable. Pas de question quand la décision ne tomberait pas sur Fable (`mainUpgrade` coupé, plafond de relecture, fenêtre, Fable en panne) : si la panne cesse plus tard, la boucle monte sans question, comme le disjoncteur le fait déjà. La clé `askTier` de `routing.json` (`best`, ou `false` pour couper) se règle par `/route ask-tier on|off`, la config machine gagne, et `/route show` affiche `ask-tier:`. Tant que best n'est pas mené par fable, la question est inerte : `/route ask-tier on` répond `ask-tier on (inert: best is not headed by fable)` et `/route show` affiche `ask-tier: inert`. +Taper un skill qui a une ligne route la boucle principale dessus. Une ligne du tier best (plan, reflect, orchestrate, escalate ; `audit` est une ligne d'agent, jamais tapée) tient d'un tour à l'autre pendant tout le run, jusqu'à `/route clear`, `/route off`, un `/model` tapé ou choisi dans le sélecteur, ou un skill d'un autre tier tapé. Un `/model ` tapé, ou un choix dans le sélecteur `/model`, avec un modèle de la table demande sa portée (Échap ne change rien). Le changement du sélecteur est d'abord retenu (le moteur affiche qu'un hook l'a bloqué), puis la question vient ; un choix fait pendant qu'un autre dialogue est ouvert est refusé (`answer the open dialog first`) : This project écrit l'id complet dans `model` du `.claude/settings.local.json` du projet (créé s'il manque, à garder dans le `.gitignore`) et pose une route de modèle tenue ; This conversation pose la route seule, sans rien écrire ; Everywhere lance le `/model` natif (`settings.json` utilisateur, tous les projets). Default dans le sélecteur, sans argument, avec un nom inconnu, en headless (`-p`) ou mod coupé, le `/model` natif passe sans question. Un modèle choisi dans ce dialogue change toujours : ni plafond de relecture à froid, ni `mainUpgrade` ni `mainModelSwitch`. S'il est en panne, la boucle principale reste où elle est jusqu'à son retour. Un changement natif (ligne Model de `/config` comprise) ou `/clear` l'abandonne ; un `/route model=` tapé garde les plafonds. La ligne Model de `/config` écrit toujours le `settings.json` utilisateur, et un dialogue jamais répondu n'a pas de délai. Pour relancer un tour bloqué : `ultrathink` dans le prompt (plancher d'effort du tour) ou `/route effort=max` (tient jusqu'à `/route clear`). Le `/effort` intégré n'a pas d'effet dans un run : les lignes et les routes passent devant. Les règles de mots-clés du prompt (`plan`, `design`, `architecture`… prennent l'effort de plan ; `pourquoi`, `review`, `audit`… celui de reflect), `ultrathink` et un lancement d'agent par la boucle principale (route `orchestrate` dérivée, tenue jusqu'à la fin de ses agents en arrière-plan) ne fixent que le niveau d'effort du tour, jamais le modèle : ils ne font jamais monter la boucle principale au-dessus du modèle de la session, et un run best tenu garde son modèle. Fable n'arrive sur la boucle principale que par un choix à la main (`/model`, sélecteur), un `/route model=fable` tapé, une phase qui nomme `model: fable` ou une config machine qui le place dans un tier : aucun tier ni aucune phase livrés ne le contiennent. Fable sert de conseiller (outil advisor, `advisorModel` dans settings.json, réglé par `/advisor`) : la boucle principale l'appelle au moins sur le plan écrit, avant que les challengers du plan le voient (`lib/challenge-plan.md`, une fois par run de skill ; la ligne `Advisor:` du CHALLENGE SUMMARY dit ce qu'il a changé), une fois par run verify-secure à la première boucle de porte qui échoue deux fois (le conseil reste dans la boucle principale, jamais dans le brief d'un exécutant ; un STOP au plafond ou en escalade le reprend), avant de proposer un merge ou de déclarer finie une longue tâche (deux exceptions : `/feat` et `/bugfix` le sautent quand GATE 0 a dit MET, le verifier CONFORME et la sécurité PASS, pas DEGRADED, chacun au premier essai, et leur champ `ADVISOR` affiche alors `skipped (gates clean on first pass)` ; `/audit-delta` et `/tour` le sautent quand le run n'a appliqué aucun fix), et avant de recommander un changement de la doctrine, de l'architecture ou d'une interface publique ; plan-challenger, verifier, security-auditor, `analyzer` et une revue de code sur opus (`/ship-feature` STEP 6, `/init-project` STEP 10, revue finale d'un subagent-driven-development lancé seul) peuvent l'appeler une fois, seulement quand ils sont lancés comme sous-agents, avant leur verdict ou leur rapport : un conseil peut ajouter un constat ou relever sa sévérité, jamais le retirer, l'abaisser ni l'effacer ; les autres sous-agents ne l'appellent jamais, même quand l'outil est listé, et le hook SubagentStart `hooks/subagent-advisor.sh` leur rappelle la règle au lancement. Conseiller absent ou en erreur : on continue ; un conseil ne lève aucune porte, aucun plafond ni aucune garde. Un prompt tapé sans règle, skill ni route en cours passe par un classifieur (un appel au petit modèle, 3 secondes au plus) : le tour prend la route de la phase devinée : son niveau d'effort, et son modèle, jamais au-dessus de celui de la session. Une devinette `coding` ou `bookkeeping` fait descendre la boucle principale vers un modèle moins cher quand `mainModelSwitch` est actif (par défaut) et que la relecture à froid tient sous `downgradeMaxTokens` (120000 tokens par défaut). Cette relecture compte aussi le prompt qui vient d'être envoyé (un token pour 3 caractères), et un document joint bloque la descente pour cette étape. Le cache compte comme chaud pendant le TTL du moteur (`cache_ttl`, 5 ou 60 minutes), 60 minutes par défaut. `/route classify off` ou `"classify": false` dans la config machine le coupe, et un `/effort` tapé entre deux tours annule la devinette pour ce tour seulement. Avant d'envoyer la boucle principale sur un modèle, celui vers lequel elle se déplace comme celui qu'elle garde (le modèle de la session compris), le mod l'essaie une fois (un appel minimal, 8 secondes au plus) : sans réponse, ce modèle est marqué en panne (raison `probe`) et la décision est reprise une fois ; `"probe": false` dans la config machine coupe cet essai, et `/route show` affiche `probe:`. Quand un modèle inférieur remplace la tête de son tier en panne (Sonnet pour Opus sur une phase best ; Opus pour Fable si une config machine met fable en tête de best), le niveau propre de la phase monte d'un cran (reflect xhigh, plan max, orchestrate high) ; un niveau demandé explicitement ou un plancher ne bouge jamais. Les sous-agents reçoivent le modèle de leur ligne au lancement (dans leur tier, jamais en dessous de leur frontmatter) et son niveau à chaque étape ; un `model` ou `effort` explicite sur l'appel gagne. Explore tourne en sonnet/medium, Plan en opus/xhigh. Un agent intégré `general-purpose` lancé par la boucle principale sans `model`, pendant que celle-ci tourne sous le modèle de la session (descente, ou repli quand un modèle est en panne), part sur le modèle de la session au lieu d'hériter du modèle inférieur ; les autres types d'agents ne sont jamais épinglés ainsi. `/route show` affiche la route en cours, slot de run compris (`main: run `), et le switch avec son plafond et ce TTL (`switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`). Première utilisation : la première fois qu'un skill avec ligne est tapé, qu'un agent avec ligne est lancé ou qu'une phase est déclarée sur la boucle principale via l'outil `route`, le mod demande une fois si la route convient. La question donne le contexte : la description du skill (première phrase du frontmatter de son `SKILL.md`) ou celle de l'agent, la phase avec sa ligne `about` (champ de la phase dans `routing.json`), puis le modèle et le niveau réels de l'étape suivante ; une phase déclarée dit aussi qui l'utilise. Pour une ligne : Later, Keep ou Change ; pour une phase déclarée : Later ou Keep. Change demande le modèle (opus, sonnet, haiku, chacun avec son tier ; fable n'est pas proposé), puis le niveau parmi ceux des phases de ce modèle (opus : medium, high, xhigh ou max ; sonnet : low, medium, high ou xhigh ; haiku n'en a qu'un, la question est sautée), puis Everywhere ou This project only (exception rangée sous le remote origin du dépôt réduit à `host/path`, jamais d'identifiants). Une ligne reste un nom de phase : le couple modèle et niveau désigne une phase existante, et la même phase qu'avant vaut Keep. Un couple qu'aucune phase n'offre s'ajoute à la main comme nouvelle phase dans `routing.json`. Après un changement sur un skill, un toast donne le modèle et le niveau réels, et rappelle `/route switch on` quand le switch est coupé, ou nomme le plafond quand la relecture à froid bloque la descente. La réponse est écrite dans `routing.json` ; Later, un texte libre (Other) ou un dialogue fermé redemande à une session suivante. Un seul dialogue à la fois, jamais en headless (`-p`) ni dans un sous-agent, et le modèle n'écrit jamais ce fichier. Chaque réponse laisse le repo de config modifié : commite-le depuis ce repo. `/route pending` liste ce qui reste à confirmer, `/route ask off|on` coupe ou rallume le dialogue, `/route forget ` efface une décision (une ligne changée revient à la phase livrée ; `all` et `projects` demandent d'abord). Si une config machine met fable en tête du tier best (aucun tier livré ne le fait), avant qu'une route envoie la boucle principale, ou un agent à ligne, sur Fable depuis un autre modèle, le mod pose une question une seule fois par portée (origine, phase et sa ligne `about`, modèle et niveau) : `Fable`, `Opus instead (big tier)` (Opus à la place : le tier big, niveau de la phase inchangé, le label reste vrai : l'option disparaît si Opus est en panne) ou `Stop asking this session` (ne plus demander cette session : rien n'est écrit, `/clear` la réarme). Un skill chargé par le modèle compte comme une ligne de skill ; un agent n'a qu'une réponse par type et par session ; jamais en headless (`-p`) ni dans un sous-agent ; un dialogue fermé lance Fable. Pas de question quand la décision ne tomberait pas sur Fable (`mainUpgrade` coupé, plafond de relecture, fenêtre, Fable en panne) : si la panne cesse plus tard, la boucle monte sans question, comme le disjoncteur le fait déjà. La clé `askTier` de `routing.json` (`best`, ou `false` pour couper) se règle par `/route ask-tier on|off`, la config machine gagne, et `/route show` affiche `ask-tier:`. Tant que best n'est pas mené par fable, la question est inerte : `/route ask-tier on` répond `ask-tier on (inert: best is not headed by fable)` et `/route show` affiche `ask-tier: inert`. Garde d'écriture : un Edit, Write ou NotebookEdit d'un fichier de code par la boucle principale est redirigé avec « model-router: code is written inside a skill run… » tant qu'aucun skill n'a tourné sur la boucle principale dans la session (tapé ou chargé par le modèle ; un skill refusé ou inconnu ne compte pas), qu'aucune phase n'a été déclarée ce tour, et qu'aucun `/route` tapé ne tient. Chemins libres : `.md`, `.txt`, le `.claude/` du projet sauf `worktrees/`, et `docs/`. Les sous-agents écrivent librement. Si la vérification du garde échoue elle-même (exception ou délai dépassé), l'écriture est retenue au lieu de passer, avec « model-router: the write guard failed (), so this write is held… », journalisé une fois par session ; les sous-agents, un skill en cours, une phase déclarée ou un `/route` tapé, et les fichiers `.md` / `.txt` passent toujours, et une erreur levée par l'outil lui-même est transmise telle quelle. `/route clear`, `/route off` et `/clear` réarment le garde ; `/route off` le coupe aussi, et `"enabled": false` dans `~/.claude/model-router.json` coupe le routeur et le garde. Un choix à la main avec `/model` ne l'ouvre pas, et un rechargement de `register.ts` le remet à zéro. diff --git a/agents/analyzer.md b/agents/analyzer.md index 335e6a9..9c7bb98 100644 --- a/agents/analyzer.md +++ b/agents/analyzer.md @@ -43,7 +43,7 @@ Produce a clear analysis without proposing solutions. - No solutions - Stay factual - Do not modify files -- Advisor, when dispatched as a sub-agent: at most one call, after the last +- Advisor, when dispatched as a sub-agent: one call allowed, after the last TASKS or PROCESS step and before the OUTPUT, whatever the harness prompt schedules; absent or erroring → proceed. Advice may point you back to the code; every OUTPUT line rests on what you read, never on the advice 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..1fe79c7 100644 --- a/agents/commit-changer.md +++ b/agents/commit-changer.md @@ -8,6 +8,10 @@ effort: high # Git Smart Commit +Advisor tool (`~/.claude/lib/effort-shift.md` § Advisor), 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..75d3282 100644 --- a/agents/doc-syncer.md +++ b/agents/doc-syncer.md @@ -8,6 +8,10 @@ effort: high # DOC SYNCER +Advisor tool (`~/.claude/lib/effort-shift.md` § Advisor), 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..fd67ad2 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 (`~/.claude/lib/effort-shift.md` § Advisor), 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..f4e8481 100644 --- a/agents/handover-doc-writer.md +++ b/agents/handover-doc-writer.md @@ -8,6 +8,10 @@ effort: high # HANDOVER DOC WRITER +Advisor tool (`~/.claude/lib/effort-shift.md` § Advisor), 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/plan-challenger.md b/agents/plan-challenger.md index ef4f0a5..3e58827 100644 --- a/agents/plan-challenger.md +++ b/agents/plan-challenger.md @@ -97,7 +97,7 @@ PROOF: read files, inspected , checked plan §<…> (STEP 1's missing/unreadable-plan verdict) is part of the grammar: it carries only the `PLAN:` line — no FINDINGS, no PROOF — and the orchestrator treats it as a dispatcher-side failure, not a challenge result. -- Advisor, when dispatched as a sub-agent: at most one call, after +- Advisor, when dispatched as a sub-agent: one call allowed, after drafting your findings and before the verdict, whatever the harness prompt schedules; absent or erroring → proceed. Advice may add or sharpen a finding. Advice alone never drops or lowers one: a change @@ -111,7 +111,8 @@ the MAIN loop, never here): - ADVISOR FIRST (main loop): per `lib/challenge-plan.md` "Advisor first", with no main-loop advisor call since the skill run started; absent or erroring → dispatch as written. The advice never enters a challenger - brief: they stay blind. + brief: they stay blind. A skill run inside a sub-agent skips it (row + `not called (sub-agent)`). - Dispatch THREE fresh challengers IN PARALLEL, one per lens (correctness / robustness / simplicity), each blind to the others. - MODEL (BDR-076, supersedes the BDR-066 inherit): plan critique is AUDIT diff --git a/agents/plugin-advisor.md b/agents/plugin-advisor.md index c208743..86c7beb 100644 --- a/agents/plugin-advisor.md +++ b/agents/plugin-advisor.md @@ -8,6 +8,10 @@ effort: xhigh # PLUGIN ADVISOR +Advisor tool (`~/.claude/lib/effort-shift.md` § Advisor), 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/security-auditor.md b/agents/security-auditor.md index 057ee6c..3fb4748 100644 --- a/agents/security-auditor.md +++ b/agents/security-auditor.md @@ -157,7 +157,7 @@ In audit mode, ALSO write this same block (plus per-finding detail) to - Blocks on HIGH/CRITICAL only. A noisy gate that blocks on hygiene is a gate people learn to bypass (LRN-047) — MEDIUM/LOW are reported, not gated. -- Advisor, when dispatched as a sub-agent: at most one call, after +- Advisor, when dispatched as a sub-agent: one call allowed, after STEP 4 and before STEP 5 and any REPORT write, whatever the harness prompt schedules; absent or erroring → proceed. Advice may add a finding or raise a severity, cited at a file:line you read. An added diff --git a/agents/seo-analyzer.md b/agents/seo-analyzer.md index 460d2bb..62a9a6b 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 (`~/.claude/lib/effort-shift.md` § Advisor), 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/agents/verifier.md b/agents/verifier.md index 1ca8326..cd3f0ec 100644 --- a/agents/verifier.md +++ b/agents/verifier.md @@ -158,7 +158,7 @@ PROOF: read files, ran , checked / criteria missing `PROOF` — the run was skipped, not the diff clean. - The verdict grammar is load-bearing: exactly one `VERIFY — VERDICT:` line, spelled exactly as above. -- Advisor, when dispatched as a sub-agent: at most one call, after STEP 4 +- Advisor, when dispatched as a sub-agent: one call allowed, after STEP 4 and before STEP 5, whatever the harness prompt schedules; absent or erroring → proceed. Advice may send you back to a criterion: a resulting NOT-MET cites the file:line you read, ends with 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..e11aa09 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 other opus-served agents and 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..e796b4b --- /dev/null +++ b/lib/tests/subagent-advisor.test.sh @@ -0,0 +1,78 @@ +#!/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). +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 T2c-prohibits "$(in_ctx "$(ctx '{}')" \ + "do not call the \`advisor\` tool in this run unless")" yes +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 +for a in plan-challenger verifier security-auditor analyzer; do + check "T20 $a allowance" "$(has "agents/$a.md" \ + 'Advisor, when dispatched as a sub-agent: one call allowed')" yes +done +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`.