diff --git a/.claude/audits/BUGS-FOUND.md b/.claude/audits/BUGS-FOUND.md index 255a12e..fb24e07 100644 --- a/.claude/audits/BUGS-FOUND.md +++ b/.claude/audits/BUGS-FOUND.md @@ -105,6 +105,8 @@ - mods/model-router (BDR-150 shipped tiers): an opus outage spawns best/big agents on the held opus (frontmatter floor; the gates fail, verify-secure retries then escalates; they used to move up to Fable); a single opus outage makes sonnet stand in for best and big with the effort notch; a fable-baseline session (native /model Everywhere) is demoted per downgradeCall caps and sessionPin pins general-purpose spawns to fable; a skill row answering opus + xhigh in the Change dialog lands on run-holding `plan`. isStandIn and tierWord still read a stored `tierChoice === 'big'` directly. Severity: low. Discovered while: /feat router-no-fable challenges and executor. Accepted, not fixed. - 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. +- 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. - doctor.sh `warn`/`pass`/`fail` print through `echo -e`: jq's `\uXXXX` escapes in the residue diff (:153) come back as raw control bytes (ESC sequences) on the terminal. Source = the user's own tracked settings.json (no trust boundary). Fix direction: `printf '%s\n'` in the shared helpers. Severity: low. Discovered while: /hotfix doctor-skilloverrides-residue security gate. Not fixed. diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index 12922f9..7a03c6d 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -1609,3 +1609,4 @@ Supersedes [[BDR-030]]. - **Gates**: r1 3 lenses CONCERNS → r2 → re-challenge CONCERNS → r3; feater DONE 661 tests; GATE 0 MET; verifier CONFORME; security PASS (MEDIUM fixed: stored answer survives ask-tier off); commits 24b0f35, docs 42385d2. - **Refs**: amends [[BDR-123]], [[BDR-135]]; supersedes [[LRN-224]]; [[BLK-030]], [[BDR-077]] (Fable dispatch pins: separate run). - **Status (2026-11-17)**: accepted, completed: pins opus beebfe2 (gate row 'fixed at spawn' passes a pinned sub-agent), doctrine c3507ea (main loop calls advisor, sub-agents do not, absent advisor -> proceed, advice waives no gate) +- **Status (2026-11-17)**: accepted, amended 6ef3069: main loop named call points (before a skill's plan, once per verify-secure run at first gate loop failing twice, before merge); plan-challenger/verifier/security-auditor at most one call before verdict, advice add-only (security: STEP 3 class severity, no class -> REPORTED LOW); other sub-agents do not diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index 8ec7965..491d21c 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -774,3 +774,4 @@ rules: ## 2026-11-17 - Advisor doctrine (c3507ea, docs): CLAUDE.global § Workflow + effort-shift § Advisor: main loop calls Fable advisor (approach, stuck, before done), sub-agents do not (they have tool listed: prose-only, residual), absent → proceed, advice waives no gate/cap/guard. Stale Fable prose → opus (effort-shift, challenge-plan, plan-challenger, tour). BDR-150 change complete: router 24b0f35, pins beebfe2, doctrine c3507ea. +- Advisor call points run A (6ef3069): transcript count showed main loop 2 calls on Opus (409k/680k uncached) vs 18/20 opus sub-agents on Fable (~70k); doctrine now names main-loop points (plan, first gate loop failing twice, merge) + judgment agents once, advice add-only; 2 challenge rounds, gates found block E double count, fixed r5. Runs B, C next. diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md index 16d4b3e..5a4a25d 100644 --- a/.claude/memory/learnings.md +++ b/.claude/memory/learnings.md @@ -2128,3 +2128,9 @@ Rule: when editing a doctrine file under structure locks, grep the test's lock s - **Context**: 2026-11-17 advisor doctrine (BDR-150, c3507ea). Plan assumed advisor = main-loop tool. Robustness challenger (typed sub-agent, tools Read/Grep/Glob/Bash) had `advisor` listed + system prompt saying call it before/after work; same for verifier, security-auditor, executors. Each call forwards that agent's full transcript to Fable outside router caps (server tool, hooks cannot see/refuse). - **Apply**: ask a dispatched agent what tools it has (or read its prompt) before writing a scope rule; prefer mechanical scope (settings/tool lists) over prose; when only prose exists, log as residual (BUGS-FOUND d292911). - **Reference**: CLAUDE.global.md § Workflow, lib/effort-shift.md § Advisor + +## LRN-295 — Measure advisor calls from transcripts: per caller, model, uncached input (2026-11-17) +- **Pattern**: measure advisor use from session transcripts, not from feel. Main transcript `~/.claude/projects//.jsonl`, sub-agents `/subagents/*.jsonl` (+ `.meta.json` agentType). Call = content block `server_tool_use` name `advisor`; model + tokens = `message.usage.iterations[]` with `type=="advisor_message"`. Usage rows repeat once per content block: dedupe by `message.id`. +- **Context**: 2026-11-17, user asked if advisor called when needed. Since /advisor (2026-11-16 16:19Z): main loop 2 calls, served by Opus (conversation kept old advisor), 409k + 680k input tokens, cache_read 0; 18/20 opus sub-agents 19 calls on Fable, median 70k (43k-119k), total 1.46M; 8 sonnet sub-agents 0. Data reversed "main loop only" (c3507ea) → 6ef3069 (judgment agents once, main loop named points). +- **Apply**: before scoping who calls advisor, or judging cost: count per caller + model + uncached input; main-loop call in long session costs ~6-10 sub-agent calls. Run C (/memory-feedback advisor section) automates it. +- **Reference**: lib/effort-shift.md § Advisor, BDR-150, LRN-294 diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index 9733513..fc7d7fd 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -3,6 +3,12 @@ ## Open (reconciled 2026-11-12 before 3.0.0, /reconcile on the BDR-125 phases; full pass 2026-10-23) Done history before 2026-10-08 removed 2026-10-23 (git keeps it: `git log -p -- .claude/tasks/TODO.md`); decisions live in `.claude/memory/`. +### Advisor call points (user 2026-11-17: "oui 1 et 2, et le 3 aussi"; amends BDR-150) +- [x] Run A DONE 6ef3069 (docs + memory below) /feat feature/advisor-call-points: CLAUDE.global § Workflow + lib/effort-shift.md § Advisor + plan-challenger/verifier/security-auditor one-call rule (contract .claude/tasks/contracts/2026-11-17-advisor-call-points-1130.md) +- [ ] Run B /feat: inline advisor call lines at the step sites (plan step of skills/feat, bugfix, ship-feature; second-failure + cap sites in lib/verify-secure-loop.md; merge proposal), citing `lib/effort-shift.md § Advisor` +- [ ] 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) +- [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) + ### BDR-125 close-out run (user 2026-11-12): no phase 0/0b/4a/1/5/2/4b/4c/4d line left in TODO or BUGS-FOUND Decisions at start (asked once): faunosteo memory v2 on `chore/memory-v2` off develop in a fresh worktree (split already on develop 7a75974, 11 rules); settings.json `npm -g` deny lines removed on the block E branch, classifier test = `npm install -g --dry-run cowsay`; 3.0.0 cut right after block A (/release-candidate), later blocks land under the next Unreleased; LRN-270 bisect = user-run interactive sessions, one `--settings` file per pack. Merge prompts (`gitflow finish` ask) = the human signal per block once gates are green. - [x] A merged 1b82a25 (routing `confirmed` row a2f352e) diff --git a/.claude/tasks/contracts/2026-11-17-advisor-call-points-1130.md b/.claude/tasks/contracts/2026-11-17-advisor-call-points-1130.md new file mode 100644 index 0000000..7ce0744 --- /dev/null +++ b/.claude/tasks/contracts/2026-11-17-advisor-call-points-1130.md @@ -0,0 +1,48 @@ +# CONTRACT — advisor-call-points, run A (BDR-150 amendment) +- date: 2026-11-17 | flow: feat | branch: feature/advisor-call-points (off develop) +- status: active +- plan: .claude/tasks/plans/2026-11-17-advisor-call-points-1130.md (r4) + +## REQUEST (verbatim — IMMUTABLE) +User 2026-11-17, after the transcript count (main loop 2 advisor calls on Opus, 409k/680k uncached tokens; 18 of 20 opus sub-agents 19 calls on Fable, median 70k; sonnet 0 of 8), answering the three proposals: "oui 1 et 2, et le 3 aussi". Proposal 1: let the judgment agents (plan-challenger, verifier, security-auditor) call the advisor once, before their verdict; sonnet executors stay without; for the security-auditor, advice can add a finding or raise a severity, never clear a semgrep HIGH or CRITICAL. Proposal 2: name the main loop's call points in the skills rather than leave them to its judgment: before settling the approach (ahead of the plan of /feat, /bugfix, /ship-feature), at the second failure of a gate loop before re-dispatching or escalating, and before proposing the merge; the text lives in lib/effort-shift.md § Advisor, the skills cite it, the doctrine-citers census checks it. Proposal 3: count advisor calls per session (main loop vs sub-agents, model served). + +## CLARIFICATIONS +- [gated 2026-11-17] user: split in runs. Run A (this contract) = doctrine (CLAUDE.global.md, lib/effort-shift.md § Advisor) + the three judgment agents. Run B = inline call lines in skills/feat, skills/bugfix, skills/ship-feature, lib/verify-secure-loop.md. Run C = the counter. +- [gated 2026-11-17] user: the counter (proposal 3) is a section of /memory-feedback (run C). +- [internal 2026-11-17] gates round 1 (verifier CONFORME, security PASS) flagged block E: a raise double-counted in BLOCK(n), a no-class finding had no severity → block E r5 (plan), criterion 4 gains 'so it counts once' and 'REPORTED as LOW'. +- [gated 2026-11-17] user: an advisor-added or -raised security finding takes the severity of the STEP 3 checklist class it matches; no matching class → REPORTED, non-blocking (block E r4). +- [internal 2026-11-17] executor NEED-DECISION: block B line reworded to "(for work outside them, see the / triggers in CLAUDE.global.md § Workflow):" (census T3 read "§ Workflow names"). +- [internal 2026-11-17] re-challenge → plan r4 (section "r4 changes"): criterion 1 markers + 315 lines, criterion 2/4 markers, EVIDENCE: pending lines. +- [internal 2026-11-17] challenge round 1 → plan r3 (section "r3 changes"): criteria re-scoped (criterion 2 counts STEP inside § Advisor only), blocks per r3. +- [internal 2026-11-17] advisor review: blocks C-E carry "absent or erroring → proceed" (they read their agent file and CLAUDE.global.md, never lib/effort-shift.md); block E carries a grounding clause (added or raised finding cites a file:line read); "at most once" wording in both block A and B; no skill step numbers in block B. + +## RELATED MEMORY +- BDR-150 (accepted): amended here, "sub-agents do not" (c3507ea) becomes "the three judgment agents at most once"; "never routed or pinned" kept. +- LRN-294: honored, scope set from observed tool lists, rest named a prose rule. +- BDR-066 / LRN-083: loop decisions stay in the main loop; advice is input. + +## ACCEPTANCE CRITERIA +1. CLAUDE.global.md carries block A: the three-agent scope and the § Advisor pointer. + CHECK: cd /home/bchanot/Documents/claude && echo "$({ grep -c 'and security-auditor at most once, before the verdict; other' CLAUDE.global.md || true; })/$({ grep -c 'sub-agents do not. Fable is never routed' CLAUDE.global.md || true; })/$({ grep -cF '`~/.claude/lib/effort-shift.md` § Advisor' CLAUDE.global.md || true; })/$(wc -l < CLAUDE.global.md)" + EXPECT: 1/1/1/315 + EVIDENCE: MET exit=0 marker-found :: 1/1/1/315 +2. lib/effort-shift.md § Advisor carries block B, with no skill step number. + CHECK: cd /home/bchanot/Documents/claude && sec() { sed -n '/^## Advisor/,/^## Never/p' lib/effort-shift.md; }; echo "$(grep -c '^## Advisor' lib/effort-shift.md)/$(sec | grep -c 'Main loop, at least at these points')/$(sec | grep -c 'once per verify-secure run, at the first gate loop')/$(sec | grep -c 'never enters an executor brief')/$(sec | grep -c 'once per dispatch, before their verdict')/$(sec | grep -c STEP)" + EXPECT: 1/1/1/1/1/0 + EVIDENCE: MET exit=0 marker-found :: 1/1/1/1/1/0 +3. Each judgment agent carries its one-call rule with the proceed clause. + CHECK: cd /home/bchanot/Documents/claude && for f in plan-challenger verifier security-auditor; do printf '%s/' "$({ grep -c 'Advisor (when listed): at most one call' agents/$f.md || true; })$({ grep -c 'erroring → proceed' agents/$f.md || true; })"; done; echo + EXPECT: 11/11/11/ + EVIDENCE: MET exit=0 marker-found :: 11/11/11/ +4. Advice can only add: security-auditor routes and tags it, verifier and plan-challenger never clear. + CHECK: cd /home/bchanot/Documents/claude && echo "$({ grep -c 'It never removes,' agents/security-auditor.md || true; })/$({ grep -c 'BLOCK(n) like any other' agents/security-auditor.md || true; })/$({ grep -c 'so it counts once' agents/security-auditor.md || true; })/$({ grep -c 'is REPORTED as LOW,' agents/security-auditor.md || true; })/$({ grep -c 'Advice alone never clears a' agents/verifier.md || true; })/$({ grep -c 'alone never drops or lowers one' agents/plan-challenger.md || true; })" + EXPECT: 1/1/1/1/1/1 + EVIDENCE: MET exit=0 marker-found :: 1/1/1/1/1/1 +5. Full make test green (run with GATES_TIMEOUT=400). + 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 +6. Touched lines ≤ 80 columns; blocks applied verbatim from plan r4; no other wording changed in the five files (manual). + +## FILE SCOPE +CLAUDE.global.md (§ Workflow bullet ~:81-85), lib/effort-shift.md (§ Advisor body ~:103-110), agents/plan-challenger.md (§ RULES), agents/verifier.md (§ RULES), agents/security-auditor.md (§ RULES). diff --git a/.claude/tasks/plans/2026-11-17-advisor-call-points-1130.md b/.claude/tasks/plans/2026-11-17-advisor-call-points-1130.md new file mode 100644 index 0000000..f133389 --- /dev/null +++ b/.claude/tasks/plans/2026-11-17-advisor-call-points-1130.md @@ -0,0 +1,198 @@ +# PLAN — advisor call points, run A (r4 after re-challenge) +Contract: .claude/tasks/contracts/2026-11-17-advisor-call-points-1130.md +Branch: feature/advisor-call-points (off develop) + +## Why +User 2026-11-17 approved points 1 and 2 after transcript data: since /advisor +(2026-11-16 16:19Z) the main loop called the advisor 2 times in 3 skill runs +(served by Opus, 409k and 680k uncached input tokens each); 18 of 20 opus +sub-agents called it (19 calls, Fable, median 70k tokens, 1.46M total); 0 of 8 +sonnet sub-agents. The doctrine of c3507ea ("main loop only") is inverted by the +data on both use and cost. Reverses BDR-150's "sub-agents do not" for the three +judgment agents. + +## Files (5) +1. CLAUDE.global.md § Workflow, lines 81-85: replace the whole "- Stronger model + needed …" bullet with block A (verbatim; 8 lines, file 312 → 315, guard 320). +2. lib/effort-shift.md § Advisor (lines 101-110): replace the section body + (heading kept) with block B (verbatim). Nothing else in the file changes. +3. agents/plan-challenger.md § RULES: append block C as the last bullet of the + RULES list (before `## ORCHESTRATOR PROTOCOL`). +4. agents/verifier.md § RULES: append block D as the last bullet of the RULES + list (before `## ORCHESTRATOR PROTOCOL`). +5. agents/security-auditor.md § RULES: append block E as the last bullet of the + RULES list (before the next `## ` heading). + +### Block A (CLAUDE.global.md) +``` +- Stronger model needed (an approach to settle before building, a stuck + problem, a long task before calling it done) → the main loop 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; plan-challenger, verifier + and security-auditor at most once, before the verdict; other + sub-agents do not. Fable is never routed or pinned: the router tops + out at opus (BDR-150). +``` + +### Block B (lib/effort-shift.md § Advisor body) +``` +Fable runs as the advisor (settings `advisorModel`), never a route or pin +target (BDR-150). It is a server tool: the router cannot see or refuse it. + +Main loop, at least at these points (for work outside them, see the +triggers in CLAUDE.global.md § Workflow): +1. Before settling an approach: ahead of writing a skill's plan (`/feat`, + `/bugfix`, `/ship-feature`). +2. When stuck: once per verify-secure run, at the first gate loop to fail + twice (floor, conformity, security, or a second structural failure), + before re-dispatching or escalating. At a cap the STOP diagnosis + reuses that advice and says it predates the last iteration. The + advice stays in the main loop: it feeds the main loop's own decision + (a contract micro-gate, an early escalation, the STOP diagnosis) and + never enters an executor brief. +3. Before proposing a merge (`gitflow finish`) or calling a long task + done. + +Sub-agents: plan-challenger, verifier and security-auditor call it at most +once per dispatch, before their verdict; executors and every other +sub-agent do not, even when the tool is listed. + +Advisor absent or erroring (Fable out of credits, for example) → proceed +as written. Advice is input, never consent: it waives no gate, cap or +guard; at a loop cap it feeds the STOP diagnosis. +``` + +### Block C (agents/plan-challenger.md) +``` +- Advisor (when listed): at most one call, 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 rests on your own re-read, + cited at file:line. +``` + +### Block D (agents/verifier.md) +``` +- Advisor (when listed): at most one call, 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 + `(advisor-prompted)` and counts in STEP 5 like any other. Advice adds + no gap outside the contract's criteria. Advice alone never clears a + gap and is never evidence for a MET: any change rests on your own + re-read or run (STEP 2). +``` + +### Block E (agents/security-auditor.md) +``` +- Advisor (when listed): at most one call, 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 finding's rule/check + is `advisor:`; a raised one keeps its own line, its + rule/check becoming `+advisor`, so it counts once. The severity + is that STEP 3 class's, which overrides the STEP 2 mapping for that + finding only; an added finding matching no class is REPORTED as LOW, + and a raise matching no class changes nothing. It enters STEP 5's + dedup and BLOCK(n) like any other, and PROOF ends with `; advisor + added/raised`. It never removes, lowers or waives a finding from + semgrep, the checklist or STEP 4. +``` + +## Edge cases +- Each block's lines ≤ 80 columns (block A keeps the 2-space bullet indent). +- Blocks C-E sit inside the RULES list, keeping its blank-line-between-bullets + style if the list uses one. +- No other wording in the five files changes (wiring points, Limits, ask-tier, + `## Never` untouched). + +## Tests +No hermetic test asserts this prose (grep lib/tests: none). Oracles are the +contract's grep criteria + full `make test`. The doctrine-citers census (T6, +lib/tests/doctrine-citers.test.sh:213-214) also scans CLAUDE.global.md, so block +A's `~/.claude/lib/effort-shift.md` § Advisor citation is checked once it sits +on one line (the extractor is per line; r4 keeps it on one line), and block +B's `CLAUDE.global.md § Workflow` citation too. + +## Split (user 2026-11-17) +- Run A (this plan): doctrine + three judgment agents, 5 files. +- Run B: inline advisor call lines at the step sites (plan step of skills/feat, + skills/bugfix, skills/ship-feature; second-failure and cap sites in + lib/verify-secure-loop.md; the merge proposal), citing + `lib/effort-shift.md § Advisor`. +- Run C (point 3): advisor usage counter as a section of /memory-feedback + (user choice); dedupe usage rows by message.id, model from the + `advisor_message` iteration, main transcript vs subagents/*.jsonl. +- Stale citers for doc-sync / capitalize: README, USAGE, CHANGELOG + [Unreleased] advisor bullet, BUGS-FOUND d292911 residual, BDR-150 status, + LRN-294. + +## Disposition +- amends BDR-150 (its "sub-agents do not" clause, c3507ea) by allowing the three + judgment agents one call; keeps "never routed or pinned". +- applies LRN-294 only partly: sub-agents get the tool, CLAUDE.global.md and a + harness prompt asking for "at least once before … and once before declaring + done"; blocks C-E say the one-call rule overrides it, but that is prose + against a harness instruction: logged as a BUGS-FOUND residual at capitalize. +- honors BDR-066/LRN-083: loop decisions stay in the main loop; advice is input. + +## r3 changes (challenge round 1: correctness FATAL(2), robustness CONCERNS(3), simplicity CONCERNS(1)) +- C1 BLOCKER oracle: contract criterion 2 counts STEP inside § Advisor only. +- C2 BLOCKER + R5: block E routes an advisor-added/raised finding into STEP 5's + merge and BLOCK(n), tagged `advisor-added` / `advisor-raised from ` in + ; REPORT written after the advisor call (R6). +- R3: block D mirrors E (never clears NOT-MET, UNVERIFIABLE, FLOOR, out-of-scope; + may add a gap at file:line); C5: MET evidence defers to STEP 2. +- R4: block C "may add or sharpen, never drop or lower". +- S1 + C4: block A minimal: keeps its generic triggers, points to + `~/.claude/lib/effort-shift.md` § Advisor, no copied list. +- S4 + R1 + C8: block B = the approved points only. One stuck call per loop at + its second failure (structural failures included), the cap reuses it; "any + non-trivial change" dropped; done + merge one point. +- R2: second-failure advice stays in the main loop, never enters an executor + brief (verify-secure-loop "nothing else" briefs kept). +- S2: cost sentence and sub-agent evidence sentence moved out of block B (the + rationale goes to the BDR-150 amendment). +- R6 + C7: blocks C-E say "whatever the harness prompt schedules"; block B names + the residual. +- C6: main-loop calls served by Opus are explained by the /advisor output in + this conversation ("keeps Opus until /clear"); doctrine names the advisor by + `advisorModel`. +- S3 rejected in part: the advice-specific clauses in C and D stay, because + R3/R4 need them (they now carry new rules, not repeats). + +## r4 changes (re-challenge: correctness CONCERNS(3), robustness CONCERNS(3), simplicity CONCERNS(1); no third round, these go to the CHALLENGE SUMMARY) +- RC1/RR1: block A keeps "`~/.claude/lib/effort-shift.md` § Advisor" on one + line so the per-line census extractor sees it; criterion 1 greps it. +- RC2: contract criteria 1-5 carry `EVIDENCE: pending` (gates.sh ERROR otherwise). +- RC3/RR2/RS2: block D: advice can only send the verifier back to a criterion; + a resulting NOT-MET is tagged `(advisor-prompted)` and counts in STEP 5; no + gap outside the criteria; advice alone never clears; no copied gap list. +- RR3/RC5/RC6/RS3/RR8: block E: rule/check `advisor:` or + `+advisor`; severity = the matching STEP 3 class (overrides the STEP 2 + mapping for that finding only); no matching class → REPORTED, non-blocking + (so one opinion cannot BLOCK, hence no /hotfix revert on opinion alone); + PROOF gets `; advisor added/raised`. +- RR4: calls placed late: verifier/auditor after STEP 4 before STEP 5; + challenger after drafting findings. +- RS1/RR5/RC4: "advice alone never drops/lowers/clears": a change rests on the + agent's own re-read, cited. +- RR6: main loop stuck call once per verify-secure run; the STOP says the + advice predates the last iteration. +- RC7: block B points are a floor ("at least"), CLAUDE.global.md § Workflow + triggers cover work outside them. +- RS4: block B residual sentence dropped (BUGS-FOUND carries it); "whatever the + harness prompt schedules" kept (one verifier made 2 calls on 2026-11-16). +- RR7: live-install note: ~/.claude/CLAUDE.md and ~/.claude/agents are symlinks + into this repo, so the edits apply to every session as soon as written, + including this run's own verifier and security-auditor. Rollback: + `git restore` of the five files on the branch. +- Execution NEED-DECISION (internal, 2026-11-17): census read "§ Workflow + names" as heading "Workflow names" (T3 DANGLING). Block B line reworded so the + citation ends at "§ Workflow)". Agent RULES bullets sit tight under the + previous bullet (the lists are tight), accepted. +- Gate findings (security PASS + verifier CONFORME, 2026-11-17): block E r5. + A raise keeps its own line (rule/check `+advisor`) so STEP 5 dedup counts + it once; an added no-class finding is REPORTED as LOW; a raise with no class + changes nothing. diff --git a/CHANGELOG.md b/CHANGELOG.md index d62ed45..7102420 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,7 +20,7 @@ The BDR-125 context queue is delivered: phases 0, 0b, 4a, 1, 5, 2 and 4b-4d ship - **memory commit chokepoint**: `lib/memory.sh check --staged`, run by `lib/memory-commit.sh commit` before every memory commit (rc 6, registry unstaged), also refuses a staged v2 registry whose new `## ` entry does not carry the next free ID: the highest ID seen at any heading level, fenced or not, in HEAD and above the entry in the staged file, plus one, the same reading `add` uses. stderr: `memory: :: new entry is not the next free ID -NNN`. A committed ID is never renamed: fix the uncommitted heading and every uncommitted mention of its ID (the `superseded by` line from `add --supersedes`, the journal line), or drop the new entry and re-add it with `memory.sh add`. Skipped when the registry is absent from HEAD, HEAD is v1 (an `upgrade` commit), HEAD has an open code fence, or HEAD has no well-formed `## ` entry. Tests: `lib/tests/memory.test.sh`. - **model-router write guard fails closed**: when the guard's own check throws or times out, a main-loop Edit, Write or NotebookEdit of a code file outside a skill run is held with `model-router: the write guard failed (), so this write is held. Enter /hotfix, /feat, /bugfix or /ship-feature, or re-enter the skill you were running, then make this edit.` One log line per session: `model-router: write guard failed (): main-loop code writes are held until a skill runs`. Sub-agents, skill runs (typed, model-declared phase, typed `/route`) and `.md` / `.txt` files still pass; an error raised by a downstream tool is replayed as before. The guard used to let the write through on its own failure. Tests: `mods/model-router/hooks/register.test.ts` (GUARD: a failing guard …). - **model-router: Fable leaves auto-routing**: the `best` and `big` tiers default to opus then sonnet (were fable>opus>sonnet and opus>fable>sonnet), so Opus is the strongest model the router routes to and Fable is the advisor (`advisorModel` in settings.json). Fable stays in the model table and first in the fallback rank, so a hand pick of fable ranks above opus. The first-use Change dialog offers opus, sonnet and haiku; the bare `/model` dialog still offers fable, labelled `fable (custom)`. The ask before Fable only fires when a machine override puts fable at the head of `best`: otherwise `/route ask-tier on` answers `(inert: best is not headed by fable)` and `/route show` prints `ask-tier: inert`. An agent on a best or big row keeps its opus frontmatter when Opus is down. The `tiers.best does not lead the fallback chain` log is gone; `routing.json` is unchanged. Tests: `mods/model-router/hooks/register.test.ts`; `lib/tests/effort-routing.test.sh` floors every row on its tier's head. The `/client-handover` skill-runner children and the `lib/model-gate.md` dispatch doctrine pin `model: "opus"` instead of `"fable"` (BDR-150: Fable is the advisor, never a dispatch target), and the model gate lets a sub-agent pass when the route answer says its model is `fixed at spawn`. Tests: `lib/tests/model-routing.test.sh` refuses any fable dispatch pin under agents/, skills/ and lib/; `lib/tests/effort-routing.test.sh` checks the 7 opus/effort="high" client-handover dispatches. -- **Advisor doctrine (`CLAUDE.global.md` § Workflow, `lib/effort-shift.md` § Advisor)**: when a stronger model is needed (an approach to settle before building, a stuck problem, a long task before calling it done), the main loop calls the advisor tool (Fable, settings `advisorModel`, set by `/advisor`); sub-agents do not, even when the tool is listed. Advisor absent or erroring → proceed as written; advice waives no gate, cap or guard and, at a loop cap, feeds the STOP diagnosis. Fable on main comes only from a hand pick, a typed `/route model=fable`, a phase naming `model: fable` or a machine override that puts fable in a tier (BDR-150). Prose that still named Fable as the `audit` row head or a skill-runner pin (`agents/plan-challenger.md`, `lib/challenge-plan.md`, `lib/effort-shift.md`, `skills/tour/SKILL.md`) now says opus. +- **Advisor doctrine (`CLAUDE.global.md` § Workflow, `lib/effort-shift.md` § Advisor, `agents/plan-challenger.md`, `agents/verifier.md`, `agents/security-auditor.md`)**: when a stronger model is needed (an approach to settle before building, a stuck problem, a long task before calling it done), the main loop calls the advisor tool (Fable, settings `advisorModel`, set by `/advisor`), at least before writing a skill's plan (`/feat`, `/bugfix`, `/ship-feature`), once per verify-secure run at the first gate loop to fail twice (the advice stays in the main loop and never enters an executor brief; at a cap the STOP diagnosis reuses it and says it predates the last iteration), and before proposing a merge (`gitflow finish`) or calling a long task done. `plan-challenger`, `verifier` and `security-auditor` may call it at most once per dispatch, late, before their verdict, and advice only adds: the verifier may go back to a contract criterion and tags a resulting NOT-MET `(advisor-prompted)`, never clearing a gap on advice; the challenger never drops or lowers a finding on advice alone; the security-auditor tags an added finding `advisor:` and a raised one `+advisor`, at that class's severity (an added finding matching no class is REPORTED LOW), and its PROOF ends with `; advisor added/raised`. Executors and every other sub-agent do not call it, even when the tool is listed. Advisor absent or erroring → proceed as written; advice waives no gate, cap or guard and, at a loop cap, feeds the STOP diagnosis. Fable on main comes only from a hand pick, a typed `/route model=fable`, a phase naming `model: fable` or a machine override that puts fable in a tier (BDR-150). Prose that still named Fable as the `audit` row head or a skill-runner pin (`agents/plan-challenger.md`, `lib/challenge-plan.md`, `lib/effort-shift.md`, `skills/tour/SKILL.md`) now says opus. ### Removed - `hooks/design-toolchain-reminder.sh`, its `UserPromptSubmit` entry in `settings.json` (`ctx7-reminder` stays the only one) and its suite `lib/tests/design-toolchain-reminder.test.sh`. Measured 2026-10-31: 59 fires, 0 Reads of `rules/web-building.md`. Design routing stays with the `rules/web-building.md` path rule and the `CLAUDE.global.md` pointer. The fire log `~/.claude/logs/design-toolchain-fires.log` is left in place. diff --git a/CLAUDE.global.md b/CLAUDE.global.md index 0e0b8bb..38b6441 100644 --- a/CLAUDE.global.md +++ b/CLAUDE.global.md @@ -80,9 +80,12 @@ code" wins. Repo-specific instructions override both. file or other shell. Hermetic tests run through `make test [suite=…]` only. - Stronger model needed (an approach to settle before building, a stuck problem, a long task before calling it done) → the main loop calls - the advisor tool when it is listed (Fable, set by /advisor); sub-agents do - not. Fable is never routed or pinned: the router tops out at opus - (BDR-150). + 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; plan-challenger, verifier + and security-auditor at most once, before the verdict; other + sub-agents do not. 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; diff --git a/README.md b/README.md index 0004cb8..33d5aee 100644 --- a/README.md +++ b/README.md @@ -74,10 +74,15 @@ Doctrine: the main loop runs on the `opus` session model; the model-router rows route main-loop reflection (brainstorm, plan, contract, audit judgment, loop decisions) to the `best` tier, opus at the phase's effort. Fable is never auto-routed: it is the advisor (`advisorModel` in settings.json) and a hand -pick. The main loop calls the advisor before settling an approach, when stuck -and before calling a long task done; sub-agents do not, even when the tool is -listed. 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 +pick. The main loop calls the advisor at least before writing a skill's plan +(`/feat`, `/bugfix`, `/ship-feature`), once per verify-secure run at the first +gate loop to fail twice (the advice stays in the main loop, never in an +executor brief), and before proposing a merge or calling a long task done. +plan-challenger, verifier and security-auditor may call it once, before their +verdict: 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 +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 gates run as dispatched agents on the `audit` row. The Fable/Opus model floor is enforced by a blocking gate (`lib/model-gate.md`) at the entry of the 17 diff --git a/USAGE.md b/USAGE.md index cbc28d1..272f10d 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 avant d'arrêter une approche, quand elle bloque et avant de déclarer finie une longue tâche ; les sous-agents ne l'appellent pas. 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 avant d'écrire le plan d'un skill (`/feat`, `/bugfix`, `/ship-feature`), 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), et avant de proposer un merge ou de déclarer finie une longue tâche ; plan-challenger, verifier et security-auditor peuvent l'appeler une fois, avant leur verdict : 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`. 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/plan-challenger.md b/agents/plan-challenger.md index 9e969c9..bf61757 100644 --- a/agents/plan-challenger.md +++ b/agents/plan-challenger.md @@ -97,6 +97,11 @@ 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 listed): at most one call, 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 rests on your own re-read, + cited at file:line. ## ORCHESTRATOR PROTOCOL (consumer contract — wiring reference) diff --git a/agents/security-auditor.md b/agents/security-auditor.md index 965a094..c1f82ab 100644 --- a/agents/security-auditor.md +++ b/agents/security-auditor.md @@ -157,6 +157,18 @@ 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 listed): at most one call, 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 finding's rule/check + is `advisor:`; a raised one keeps its own line, its + rule/check becoming `+advisor`, so it counts once. The severity + is that STEP 3 class's, which overrides the STEP 2 mapping for that + finding only; an added finding matching no class is REPORTED as LOW, + and a raise matching no class changes nothing. It enters STEP 5's + dedup and BLOCK(n) like any other, and PROOF ends with `; advisor + added/raised`. It never removes, lowers or waives a finding from + semgrep, the checklist or STEP 4. ## ORCHESTRATOR PROTOCOL (consumer contract — wiring reference) diff --git a/agents/verifier.md b/agents/verifier.md index 7223721..0e430f4 100644 --- a/agents/verifier.md +++ b/agents/verifier.md @@ -158,6 +158,14 @@ 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 listed): at most one call, 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 + `(advisor-prompted)` and counts in STEP 5 like any other. Advice adds + no gap outside the contract's criteria. Advice alone never clears a + gap and is never evidence for a MET: any change rests on your own + re-read or run (STEP 2). ## ORCHESTRATOR PROTOCOL (consumer contract — wiring reference) diff --git a/lib/effort-shift.md b/lib/effort-shift.md index 41649d2..d2bc9f9 100644 --- a/lib/effort-shift.md +++ b/lib/effort-shift.md @@ -101,13 +101,29 @@ Measure the split any time: `python3 ~/.claude/lib/effort-audit.py` ## Advisor Fable runs as the advisor (settings `advisorModel`), never a route or pin -target (BDR-150). Call it before committing to an approach on non-trivial -work, when stuck (the `escalate` moment, before raising effort to max) and -before declaring a long task done. It is a server tool: the router cannot -see or refuse it. The main loop calls it; sub-agents do not, even when the -tool is listed. Advisor absent or erroring (Fable out of credits, for -example) → proceed as written. Advice is input, never consent: it waives no -gate, cap or guard; at a loop cap it feeds the STOP diagnosis. +target (BDR-150). It is a server tool: the router cannot see or refuse it. + +Main loop, at least at these points (for work outside them, see the +triggers in CLAUDE.global.md § Workflow): +1. Before settling an approach: ahead of writing a skill's plan (`/feat`, + `/bugfix`, `/ship-feature`). +2. When stuck: once per verify-secure run, at the first gate loop to fail + twice (floor, conformity, security, or a second structural failure), + before re-dispatching or escalating. At a cap the STOP diagnosis + reuses that advice and says it predates the last iteration. The + advice stays in the main loop: it feeds the main loop's own decision + (a contract micro-gate, an early escalation, the STOP diagnosis) and + never enters an executor brief. +3. Before proposing a merge (`gitflow finish`) or calling a long task + done. + +Sub-agents: plan-challenger, verifier and security-auditor call it at most +once per dispatch, before their verdict; executors and every other +sub-agent do not, even when the tool is listed. + +Advisor absent or erroring (Fable out of credits, for example) → proceed +as written. Advice is input, never consent: it waives no gate, cap or +guard; at a loop cap it feeds the STOP diagnosis. ## Never