From 58a5273b5c162690f2c852113cd146cb79e9733d Mon Sep 17 00:00:00 2001 From: bchanot Date: Tue, 17 Nov 2026 14:03:42 +0100 Subject: [PATCH 1/4] docs(doctrine): advisor before plan challenge, at gate stuck points, analyzer joins Main loop consults the advisor on the written plan before the challengers (once per skill run) and at a gate loop's second failure; dispatched analyzer may call it once; new trigger before recommending a doctrine, architecture or public-interface change (amends BDR-150). --- CLAUDE.global.md | 15 ++++++++------- agents/analyzer.md | 6 ++++++ lib/challenge-plan.md | 18 +++++++++++++++++- lib/effort-shift.md | 16 ++++++++++------ lib/verify-secure-loop.md | 22 ++++++++++++++++++++++ 5 files changed, 63 insertions(+), 14 deletions(-) diff --git a/CLAUDE.global.md b/CLAUDE.global.md index 38b6441..1a25f5b 100644 --- a/CLAUDE.global.md +++ b/CLAUDE.global.md @@ -79,13 +79,14 @@ code" wins. Repo-specific instructions override both. followed instead), never rerun through a wrapper, alias, env 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 (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). + problem, a long task before calling it done, before recommending a change + to the doctrine, the architecture or a public interface) → 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; 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). - 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/agents/analyzer.md b/agents/analyzer.md index 7639ced..335e6a9 100644 --- a/agents/analyzer.md +++ b/agents/analyzer.md @@ -43,6 +43,12 @@ 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 + 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 + alone. Advice proposing a design or a fix counts only where the brief + asks for a fix. --- diff --git a/lib/challenge-plan.md b/lib/challenge-plan.md index 3f55623..7441484 100644 --- a/lib/challenge-plan.md +++ b/lib/challenge-plan.md @@ -27,9 +27,22 @@ explicitly deferred for the human. Nominal path is cheap for a small, clean plan: three parallel challengers return SOLID, synthesis is a no-op. It only costs more when a lens lands a real finding — which is the point. +The main loop's advisor call before the dispatch (below) is the costliest +single item: once per skill run. ## DISPATCH — three fresh challengers, in parallel, blind +**Advisor first (main loop).** Before the first dispatch, with no main-loop +advisor call since the skill run started (so at most once per skill run, not +before a re-challenge), the main loop reads the `PLAN` file unless its full +text is already in this conversation, then calls the advisor when the tool +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. +The advice never enters a challenger brief: they stay blind. + Dispatch THREE fresh `plan-challenger` subagents IN PARALLEL, one per LENS, each blind to the others and to this conversation: @@ -87,6 +100,9 @@ Parse each `CHALLENGE — LENS: … — VERDICT:` line and merge the FINDINGS: Feed the orchestrator's gate: - the REVISED plan, and - a CHALLENGE SUMMARY: each BLOCKER raised → the named change that closed it; - anything `[deferred]`; and any lens that failed to return. + 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)`. The human remains the decider. diff --git a/lib/effort-shift.md b/lib/effort-shift.md index d2bc9f9..b0182c3 100644 --- a/lib/effort-shift.md +++ b/lib/effort-shift.md @@ -105,21 +105,25 @@ 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`). +1. Before settling an approach: on the written plan, before the + challengers see it (`lib/challenge-plan.md`), at most once per skill run. 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 + reuses that advice and says whether 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. +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: 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. +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. 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/verify-secure-loop.md b/lib/verify-secure-loop.md index 8af5f2d..d50e596 100644 --- a/lib/verify-secure-loop.md +++ b/lib/verify-secure-loop.md @@ -36,6 +36,10 @@ single `GATES — VERDICT:` line: nothing else; re-run GATE 0. **No verifier is dispatched** — a red build or a red suite is not a judgement call, and paying an LLM to discover it is waste. **Max 3 floor iterations** → `mcp__model-router__route(phase="escalate")` (route: cap reached, diagnose at max before escalating; send it with the first tool call that gathers the escalation evidence), then STOP + human escalation with the rows. + A second UNMET with no main-loop advisor call since GATE 0 first ran → + the main loop calls it before the re-dispatch + (`lib/effort-shift.md` § Advisor); the answer stays here, never + in the dev brief. - `ABANDONED(n)` → floor green but a handoff stands. Continue to GATE 1; the verifier surfaces it and its `ABANDONED(n)` verdict routes to the human gate. @@ -76,6 +80,10 @@ Parse its single `VERIFY — VERDICT:` line: re-dispatch a FRESH verifier. Repeat. **Max 3 conformity iterations** → `mcp__model-router__route(phase="escalate")` (route: cap reached, diagnose at max before escalating; send it with the first tool call that gathers the escalation evidence), then STOP + human escalation with the CRITERIA table (the contract-vs-realized diff). + A second ECARTS with no main-loop advisor call since GATE 0 first ran → + the main loop calls it before the re-dispatch + (`lib/effort-shift.md` § Advisor); the answer stays here, never + in the dev brief. - `ABANDONED(n)` → direct human gate, never a dev loop (a dev cannot close what was proven impossible). The human lifts the abandonment or accepts the partial delivery; either way the run is never reported as fully @@ -89,6 +97,9 @@ Parse its single `VERIFY — VERDICT:` line: unparsable, crash, `CONFORME` without `PROOF` or without `FLOOR`) → retry ONCE with a fresh verifier; a 2nd structural failure → human escalation. A mute verifier is NEVER a PASS. + A 2nd structural failure with no main-loop advisor call since GATE 0 + first ran → the main loop calls it before escalating + (`lib/effort-shift.md` § Advisor). ## GATE 2 — SECURITY (fresh security-auditor) @@ -108,11 +119,22 @@ Parse its single `SECURITY — VERDICT:` line: BLOCKING table. Every STOP text names the level reached (`$CLAUDE_EFFORT`) and suggests relaunching with `ultrathink` in the prompt (turn floor) or `/route effort=max` (sticky, `/route clear` after). + A second BLOCK with no main-loop advisor call since GATE 0 first ran → + the main loop calls it before the re-dispatch + (`lib/effort-shift.md` § Advisor); the answer stays here, never + in the dev brief. - `DEGRADED` (semgrep absent) → does NOT block on the tool's absence; surface the checklist result + recommend `make plugin`. A DEGRADED run that still BLOCKs (grep-caught secret/injection) blocks like any other. - Structural failure → retry ONCE fresh; 2nd → human escalation. A mute auditor is NEVER a PASS. + A 2nd structural failure with no main-loop advisor call since GATE 0 + first ran → the main loop calls it before escalating + (`lib/effort-shift.md` § Advisor). + +Every cap or escalation STOP above: when the main loop consulted the advisor +since GATE 0 first ran, the STOP carries its answer and says whether it +predates the last iteration. ## Order invariant From 47e5ee838969b59f2b1a5939f3c1c49e837ee151 Mon Sep 17 00:00:00 2001 From: bchanot Date: Tue, 17 Nov 2026 14:07:00 +0100 Subject: [PATCH 2/4] docs: advisor plan point, stuck lines and analyzer in README, USAGE, changelog --- CHANGELOG.md | 2 +- README.md | 18 +++++++++++------- USAGE.md | 2 +- 3 files changed, 13 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7102420..534dd56 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, `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. +- **Advisor doctrine (`CLAUDE.global.md` § Workflow, `lib/effort-shift.md` § Advisor, `lib/challenge-plan.md`, `lib/verify-secure-loop.md`, `agents/plan-challenger.md`, `agents/verifier.md`, `agents/security-auditor.md`, `agents/analyzer.md`)**: when a stronger model is needed (an approach to settle before building, a stuck problem, a long task before calling it done, a change to recommend to the doctrine, the architecture or a public interface), the main loop calls the advisor tool (Fable, settings `advisorModel`, set by `/advisor`), at least on the written plan before the plan challengers are dispatched (`lib/challenge-plan.md`, every skill that challenges a plan, once per skill run, not before a re-challenge: an answer that lands a real flaw revises the plan file as plain plan text with no advisor attribution, the advice never enters a challenger brief, and the CHALLENGE SUMMARY gains an `Advisor:` row), once per verify-secure run at the first gate loop to fail twice (floor, conformity, security, or a second structural failure, counting main-loop calls since GATE 0 first ran; the advice stays in the main loop and never enters an executor brief; every cap or escalation STOP carries it and says whether it predates the last iteration), and before proposing a merge (`gitflow finish`) or calling a long task done. Inside a skill run these points cover the triggers: no second call for the same recommendation. `plan-challenger`, `verifier`, `security-auditor` and `analyzer` may call it at most once per dispatch, late, before their verdict or report; the analyzer's output rests on the code it read, never on the advice alone, and advice proposing a design or a fix counts only where the brief asks for one. For the three gates 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/README.md b/README.md index 33d5aee..c4de5d3 100644 --- a/README.md +++ b/README.md @@ -74,13 +74,17 @@ 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 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 +pick. The main loop calls the advisor at least on the written plan before the +plan challengers see it (`lib/challenge-plan.md`, once per skill run; the +CHALLENGE SUMMARY's `Advisor:` row records what it changed), 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; a cap or escalation STOP carries +it), before proposing a merge or calling a long task done, 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, +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 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 272f10d..ddbb122 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 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`. +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, 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, 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`. 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. From 9033b4a94461c9544ea5f0580fa68fa73b389cae Mon Sep 17 00:00:00 2001 From: bchanot Date: Tue, 17 Nov 2026 14:07:01 +0100 Subject: [PATCH 3/4] chore(audits): two advisor residuals from run B1 --- .claude/audits/BUGS-FOUND.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.claude/audits/BUGS-FOUND.md b/.claude/audits/BUGS-FOUND.md index fb24e07..592f1ab 100644 --- a/.claude/audits/BUGS-FOUND.md +++ b/.claude/audits/BUGS-FOUND.md @@ -107,6 +107,8 @@ - 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. +- 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. +- agents/plan-challenger.md ORCHESTRATOR PROTOCOL (~:111-112, :133-135) — mirror of lib/challenge-plan.md lacks the main-loop "Advisor first" step and the CHALLENGE SUMMARY `Advisor:` row (58a5273); the 12 skills' own summary templates also lack the row (lib rule says append it anyway). Fix direction: patch the mirror, optionally add the row to the templates. Severity: low. Discovered while: /feat advisor-points-b1 re-challenge. 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. From d55f4911ce574f0c5d790967892951900f364fa2 Mon Sep 17 00:00:00 2001 From: bchanot Date: Tue, 17 Nov 2026 14:07:02 +0100 Subject: [PATCH 4/4] chore(memory): LRN-296 simulate checks, BDR-150 amended, run B1 journal --- .claude/memory/decisions.md | 1 + .claude/memory/journal.md | 1 + .claude/memory/learnings.md | 6 + .claude/tasks/TODO.md | 4 +- .../2026-11-17-advisor-points-b1-1500.md | 52 ++++++ .../2026-11-17-advisor-points-b1-1500.md | 176 ++++++++++++++++++ 6 files changed, 239 insertions(+), 1 deletion(-) create mode 100644 .claude/tasks/contracts/2026-11-17-advisor-points-b1-1500.md create mode 100644 .claude/tasks/plans/2026-11-17-advisor-points-b1-1500.md diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index 7a03c6d..f6b16fa 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -1610,3 +1610,4 @@ Supersedes [[BDR-030]]. - **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 +- **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 diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index 491d21c..9948283 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -775,3 +775,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. +- Advisor run B1 (58a5273): plan point moved into lib/challenge-plan.md (once per skill run, Advisor: row), stuck lines inline in verify-secure-loop (main-loop calls only), analyzer joins, trigger for doctrine/architecture/public-interface recommendations. 2 challenge rounds (2 BLOCKERs were my own oracle markers), scratch simulation then MET first run; gates sequential, CONFORME + PASS. diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md index 5a4a25d..4a8e454 100644 --- a/.claude/memory/learnings.md +++ b/.claude/memory/learnings.md @@ -2134,3 +2134,9 @@ Rule: when editing a doctrine file under structure locks, grep the test's lock s - **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 + +## LRN-296 — Simulate contract CHECKs on a scratch copy of the planned edit before dispatch (2026-11-17) +- **Pattern**: before dispatching a prose/doctrine run, apply the planned blocks to a scratch copy (deterministic applier asserting each anchor once) and run every contract CHECK against it. Grepping markers against the block text alone misses cross-block effects. +- **Context**: 2026-11-17 advisor runs A and B1. Markers broke three times: phrase wrapped across two lines (grep per line, count 0); awk `/X/{a=NR}` kept LAST match after a later block mentioned "X"; census extractor read word after `§ Label` as part of heading ("§ Workflow names"). Each would have cost a floor loop. Also `Nb.` criterion label absorbed by gates.sh (LRN-284). Simulation of B1 (apply.py on mktemp copy) passed 5/5 CHECKs; executor then got MET first run. +- **Apply**: any /feat or /bugfix whose oracles are grep/awk markers on prose: write blocks to files, applier script with exact-once asserts, run CHECKs with `cd` swapped to the scratch copy; anchor awk on line start (`/^\*\*Label/`); keep each marker and each `§ Label` citation on one line followed by `)`/`;`. Give the executor the applier. +- **Reference**: lib/gates.sh, lib/tests/doctrine-citers.test.sh, .claude/tasks/plans/2026-11-17-advisor-points-b1-1500.md, LRN-284 diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index 37a609a..f3650bf 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -5,7 +5,9 @@ Done history before 2026-10-08 removed 2026-10-23 (git keeps it: `git log -p -- ### Advisor call points (user 2026-11-17: "oui 1 et 2, et le 3 aussi"; amends BDR-150) - [x] Run A DONE 6ef3069, merged fc2d84d (docs 09277f5, audits c1a0c32, memory 78a6942) /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`; + agents/security-auditor.md advisor bullet: severity applies only when higher, closing sentence "Advice never removes…" (BUGS-FOUND LOW, c1a0c32) = 5 files. Plan notes: test each citation line against the census regex (per line; word after `§ Label` joins the heading); fast oracle `bash lib/tests/doctrine-citers.test.sh` before full make test; settle the merge-proposal site first (/feat and /bugfix never finish); read run B challengers' notes for one late advisor call (first live test of block C) +- [x] Run B1 DONE 58a5273 (docs, memory below) /feat feature/advisor-points-b1 (user 2026-11-17 "oui a, b et c"): (a) main-loop plan point in lib/challenge-plan.md (before first dispatch), (b) analyzer joins judgment agents (CLAUDE.global, effort-shift, agents/analyzer.md), (c) trigger "before recommending a change to the doctrine, the architecture or a public interface", stuck call lines in lib/verify-secure-loop.md (contract .claude/tasks/contracts/2026-11-17-advisor-points-b1-1500.md) +- [ ] Run B2 /feat: stuck trigger line in the gate bullets of skills/feat, skills/bugfix, skills/ship-feature (they restate the loop inline); merge-proposal lines in skills/ship-feature STEP 9 + skills/release-candidate STEP 4; agents/security-auditor.md severity applies only when higher + "Advice never removes…" (BUGS-FOUND LOW c1a0c32). Plan notes: test citation lines against the census regex; fast oracle doctrine-citers; no `Nb.` criterion labels (LRN-284) +- [x] After B1 DONE (doc commit + BDR-150 status + LRN-296): README/USAGE/CHANGELOG say "before writing a skill's plan (/feat, /bugfix, /ship-feature)" and list 3 agents → doc-sync; BDR-150 status line - [ ] 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) diff --git a/.claude/tasks/contracts/2026-11-17-advisor-points-b1-1500.md b/.claude/tasks/contracts/2026-11-17-advisor-points-b1-1500.md new file mode 100644 index 0000000..06bd452 --- /dev/null +++ b/.claude/tasks/contracts/2026-11-17-advisor-points-b1-1500.md @@ -0,0 +1,52 @@ +# CONTRACT — advisor-points-b1 (BDR-150 amendment, run B1) +- date: 2026-11-17 | flow: feat | branch: feature/advisor-points-b1 (off develop) +- status: active +- plan: .claude/tasks/plans/2026-11-17-advisor-points-b1-1500.md (r4) + +## REQUEST (verbatim — IMMUTABLE) +User 2026-11-17: "oui a, b et c dans la run B", answering: (a) move the main loop's "before the plan" point into lib/challenge-plan.md, shared by 9 skills: the main loop consults the advisor on the written plan before dispatching the challengers; (b) add the analyzer to the agents allowed one call; (c) add a concrete trigger to the global line: "before recommending a change to the doctrine, the architecture or a public interface". Run B (from run A) also places inline call lines in lib/verify-secure-loop.md (second failure, caps). + +## CLARIFICATIONS +- [internal 2026-11-17] run B split (/feat max 5 files): B1 = CLAUDE.global.md, lib/effort-shift.md, lib/challenge-plan.md, lib/verify-secure-loop.md, agents/analyzer.md (this contract); B2 = stuck trigger lines in skills/feat, skills/bugfix, skills/ship-feature, skills/init-project gate bullets, merge lines in skills/ship-feature STEP 9 and skills/release-candidate STEP 4, agents/security-auditor.md direction fix. +- [internal 2026-11-17] plan r2: stuck unit "since GATE 0 first ran", block C once, user wording "before recommending", analyzer moved in. +- [internal 2026-11-17] re-challenge (correctness FATAL(2), robustness CONCERNS(1), simplicity CONCERNS(1)) → plan r4, no third round: criterion 3 awk anchored on `^**Advisor first`; block F `Advisor:` row added to whatever summary template the caller prints, states `called, no change` / `not called (…)`; block C dedup "no main-loop advisor call since the skill run started", re-persist PLAN on disk, route clause dropped; block H (nominal-path cost line); block I (named points cover the § Workflow triggers inside a skill run); B2 inline sentence narrowed to the analyzer; E parenthetical dropped. Residuals → BUGS-FOUND at capitalize: verifier/security-auditor advisor rules not dispatch-scoped (inline load path unused today), agents/plan-challenger.md ORCHESTRATOR PROTOCOL mirror lacks the advisor step and row. +- [internal 2026-11-17] challenge round 1 (correctness FATAL(5), robustness CONCERNS(4), simplicity SOLID) → plan r3: plan call once per skill run, reads PLAN first, route sent with it, no attribution in PLAN, CHALLENGE SUMMARY lists advisor-driven changes (block F); stuck unit counts main-loop calls only; STOP clause moved before "## Order invariant" (block G); effort-shift item 2 "says whether it predates"; analyzer rule scoped to dispatch, anchored after TASKS/PROCESS, fix advice allowed where the brief asks; `analyzer` backticked; B2 gains skills/init-project. Rejected: one-line D triggers (S1, the brief ban stays at the site), on-disk stuck marker (R10, over-built). + +## RELATED MEMORY +- BDR-150 (accepted, amended 6ef3069): amended again here. +- LRN-294, LRN-295, BUGS-FOUND advisor residual: prose-only scope, cost per main-loop call. +- BDR-066 / LRN-083: decisions and advice stay in the main loop. + +## ACCEPTANCE CRITERIA +1. CLAUDE.global.md carries block A (trigger c, dispatched analyzer, one-line citation). + CHECK: cd /home/bchanot/Documents/claude && echo "$({ grep -c 'before recommending a change' CLAUDE.global.md || true; })/$({ grep -c 'verifier, security-auditor and `analyzer` at most once, before their' 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/316 + EVIDENCE: MET exit=0 marker-found :: 1/1/1/316 +2. lib/effort-shift.md § Advisor: plan point on the written plan, "whether it predates", dispatched analyzer, inline loads, old wording gone. + CHECK: cd /home/bchanot/Documents/claude && sec() { sed -n '/^## Advisor/,/^## Never/p' lib/effort-shift.md; }; echo "$(sec | grep -c 'on the written plan, before the')/$(sec | grep -c 'says whether it predates')/$(sec | grep -c 'and `analyzer` call it at most once per dispatch')/$(sec | grep -c 'loaded inline by the main loop follows the')/$(sec | grep -c 'no second call for the same recommendation')/$(sec | grep -c "ahead of writing a skill's plan")/$(sec | grep -c STEP)" + EXPECT: 1/1/1/1/1/0/0 + EVIDENCE: MET exit=0 marker-found :: 1/1/1/1/1/0/0 +3. lib/challenge-plan.md: main-loop advisor call before the first dispatch, challengers blind, summary lists advisor-driven changes. + CHECK: cd /home/bchanot/Documents/claude && echo "$({ grep -c 'Advisor first (main loop)' lib/challenge-plan.md || true; })/$({ grep -c 'The advice never enters a challenger brief' lib/challenge-plan.md || true; })/$({ grep -c 'whatever summary template the caller prints' lib/challenge-plan.md || true; })/$({ grep -c 'revises the `PLAN` file on disk before the dispatch' lib/challenge-plan.md || true; })/$(awk '/^\*\*Advisor first/{a=NR} /^Dispatch THREE fresh/{d=NR} END{print (a>0 && a0 && s&1 | tail -1 + EXPECT: FAIL=0 + EVIDENCE: MET exit=0 marker-found :: PASS=23 FAIL=0 +7. 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 +8. Touched lines ≤ 80 columns; blocks applied verbatim from the plan; no other wording changed in the five files (manual). + +## FILE SCOPE +CLAUDE.global.md (§ Workflow bullet ~:81-88), lib/effort-shift.md (§ Advisor items), lib/challenge-plan.md (§ DISPATCH head), lib/verify-secure-loop.md (GATE 0/1/2 bullets ~:38, :78, :91, :110, :115), agents/analyzer.md (§ RULES). diff --git a/.claude/tasks/plans/2026-11-17-advisor-points-b1-1500.md b/.claude/tasks/plans/2026-11-17-advisor-points-b1-1500.md new file mode 100644 index 0000000..b6aa09f --- /dev/null +++ b/.claude/tasks/plans/2026-11-17-advisor-points-b1-1500.md @@ -0,0 +1,176 @@ +# PLAN — advisor call points, run B1 (r4) +Contract: .claude/tasks/contracts/2026-11-17-advisor-points-b1-1500.md +Branch: feature/advisor-points-b1 (off develop) + +## Why +User 2026-11-17 "oui a, b et c dans la run B": outside the named points, +advisor use rested on judgment and under-fired. (a) the main loop's plan point +moves into lib/challenge-plan.md, wired into 12 skills (9 core + seo, geo, +web-validate packs), once per skill run; (b) the dispatched `analyzer` joins the +judgment agents; (c) trigger "before recommending a change to the doctrine, the +architecture or a public interface". Stuck point: inline at the verify-secure +loop sites, counting main-loop calls only. B2 (separate run): stuck trigger in +the gate bullets of skills/feat, bugfix, ship-feature, init-project; merge lines +(ship-feature STEP 9, release-candidate STEP 4); security-auditor severity +direction; file count settled there. + +## Exact edit (deterministic) +The edits are the blocks below, applied by +/tmp/claude-1000/-home-bchanot-Documents-claude/4ba4524e-88fb-4f6c-a31d-fedd261f8925/scratchpad/b1/apply.py +(`python3 apply.py `; blocks dir = .../scratchpad/b1). +It asserts every anchor occurs exactly once and fails loudly otherwise. +Summary of what it does, by file: +1. CLAUDE.global.md § Workflow: the whole "- Stronger model needed … (BDR-150)." + bullet → block A (file 315 → 316 lines, guard 320). +2. lib/effort-shift.md § Advisor: item 1 (2 lines) → B1; the line " reuses that + advice and says it predates the last iteration. The" → B1b; after item 3 + ("…calling a long task\n done.") insert I; the "Sub-agents: …listed." + paragraph → B2. +3. lib/challenge-plan.md: after "— which is the point." insert H; before + "Dispatch THREE fresh" insert C; the 2-line CHALLENGE SUMMARY bullet in + § OUTPUT → F. +4. lib/verify-secure-loop.md (inserts only): Dfloor after "then STOP + human + escalation with the rows."; Dconf after " CRITERIA table (the + contract-vs-realized diff)."; Dstruct after " A mute verifier is NEVER a + PASS."; Dsec after " `/route effort=max` (sticky, `/route clear` after)."; + Dstruct after " auditor is NEVER a PASS."; G before "## Order invariant". +5. agents/analyzer.md § RULES: E after "- Do not modify files". + +### Block A +``` +- Stronger model needed (an approach to settle before building, a stuck + problem, a long task before calling it done, before recommending a change + to the doctrine, the architecture or a public interface) → 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; 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). +``` + +### Block B1 +``` +1. Before settling an approach: on the written plan, before the + challengers see it (`lib/challenge-plan.md`), at most once per skill run. +``` + +### Block B1b +``` + reuses that advice and says whether it predates the last iteration. The +``` + +### Block I +``` +Inside a skill run, the points above also cover the triggers of +CLAUDE.global.md § Workflow; no second call for the same recommendation. +``` + +### Block B2 +``` +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. +``` + +### Block H +``` +The main loop's advisor call before the dispatch (below) is the costliest +single item: once per skill run. +``` + +### Block C +``` +**Advisor first (main loop).** Before the first dispatch, with no main-loop +advisor call since the skill run started (so at most once per skill run, not +before a re-challenge), the main loop reads the `PLAN` file unless its full +text is already in this conversation, then calls the advisor when the tool +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. +The advice never enters a challenger brief: they stay blind. + +``` + +### Block F +``` +- a CHALLENGE SUMMARY: each BLOCKER raised → the named change that closed it; + 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)`. +``` + +### Block Dfloor +``` + A second UNMET with no main-loop advisor call since GATE 0 first ran → + the main loop calls it before the re-dispatch + (`lib/effort-shift.md` § Advisor); the answer stays here, never + in the dev brief. +``` + +### Block Dconf +``` + A second ECARTS with no main-loop advisor call since GATE 0 first ran → + the main loop calls it before the re-dispatch + (`lib/effort-shift.md` § Advisor); the answer stays here, never + in the dev brief. +``` + +### Block Dsec +``` + A second BLOCK with no main-loop advisor call since GATE 0 first ran → + the main loop calls it before the re-dispatch + (`lib/effort-shift.md` § Advisor); the answer stays here, never + in the dev brief. +``` + +### Block Dstruct +``` + A 2nd structural failure with no main-loop advisor call since GATE 0 + first ran → the main loop calls it before escalating + (`lib/effort-shift.md` § Advisor). +``` + +### Block G +``` +Every cap or escalation STOP above: when the main loop consulted the advisor +since GATE 0 first ran, the STOP carries its answer and says whether it +predates the last iteration. + +``` + +### Block E +``` +- Advisor, when dispatched as a sub-agent: at most one call, 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 + alone. Advice proposing a design or a fix counts only where the brief + asks for a fix. +``` + +## Edge cases +- Every new line ≤ 80 columns; every `§ Label` citation on one line followed by + `)` or `;` (census extractor: 6 × effort-shift § Advisor, 2 × CLAUDE.global.md + § Workflow) — checked by script. +- Contract CHECKs 1-5 simulated on a scratch copy with apply.py: all equal EXPECT. +- Stuck-call unit counts main-loop calls only; plan point skipped when the main + loop already consulted the advisor in this skill run. +- lib/tests pin "NEVER a PASS" lines: unchanged. + +## Tests +None added (prose). Oracles: contract greps; fast census +`bash lib/tests/doctrine-citers.test.sh`; full `make test`. + +## Disposition +- amends BDR-150 (6ef3069): plan point in challenge-plan; analyzer joins; (c). +- honors LRN-294 / BUGS-FOUND residual: prose; run C measures. +- honors BDR-066 / LRN-083: advice stays in the main loop, never in an executor + or challenger brief, never attributed in the plan file. +- applies LRN-295 cost: at most one plan call per skill run, at most one stuck + call per verify-secure run, no second call for the same recommendation.