docs: sub-agent advisor scope in README, USAGE, ARCHITECTURE, CHANGELOG
This commit is contained in:
1 parent
b71db282f0
commit
4bd0af6753
4 files changed
+10
-6
No files matched your search
+1
-1
@@ -20,7 +20,7 @@ claude-config/
|
||||
├── update-all.sh # One-command update for all components
|
||||
├── Makefile # Unified entry point: make install / doctor / update / test (make help)
|
||||
├── plugins.lock.json # Version pinning for non-marketplace dependencies and vendored skills
|
||||
├── hooks/ # Claude Code hooks: session start, statusline, RTK rewrite, ctx7 reminder, attention notify, unpushed-work guard, manual-mode push guard, system-dir extraction guard, instruction-load log, memory digest and memory feedback reminder at session start, code-limits line-width signal
|
||||
├── hooks/ # Claude Code hooks: session start, statusline, RTK rewrite, ctx7 reminder, attention notify, unpushed-work guard, manual-mode push guard, system-dir extraction guard, instruction-load log, memory digest and memory feedback reminder at session start, code-limits line-width signal, sub-agent advisor rule at spawn
|
||||
├── githooks/ # Generated git hooks (pre-commit, post-commit, post-merge, reference-transaction), git's global core.hooksPath
|
||||
├── .githooks/ # This repo's own copy of the same hooks
|
||||
├── .claude/rules/ # This repo's project path rules (paths: frontmatter), loaded on Read of a matching file
|
||||
|
||||
@@ -45,6 +45,7 @@ The BDR-125 context queue is delivered: phases 0, 0b, 4a, 1, 5, 2 and 4b-4d ship
|
||||
- `settings.json`: the `autoMode.hard_deny` entry "Disarming the guardrails" now names turning a mod off as disarming: `"enabled": false` in `~/.claude/<mod>.json`, a mod's `enabledPlugins` entry set to false, or `profile.sh disable` of a mod. These switches turn off the model-router write guard and the memory mod; the user still sets them by hand.
|
||||
- `lib/gates.sh` (GATE 0 floor): an unindented line under `## ACCEPTANCE CRITERIA` that starts with a digit but is not `N. text` (`1b.`, `1.1`, `2)`) is now a parse error, `malformed criterion label at line N`, and a second `CHECK:`, `EXPECT:` or `EVIDENCE:` on one criterion is one too, `second CHECK: at line N in criterion M`. Either gives `VERDICT: ERROR(n)` (rc 2) and no CHECK runs. An oracle under a label the parser missed used to overwrite the previous criterion's, so a failing criterion could read MET. A label that is not digit-led (indented, bullet) is caught only when the criterion before it already has that attribute; after a manual criterion its oracle is still absorbed. With no criterion parsed, the `no numbered criteria` error now ends with the first parse error. Test: `lib/tests/gates.test.sh`.
|
||||
- Security gate readers (`lib/verify-secure-loop.md`, `agents/security-auditor.md` ORCHESTRATOR PROTOCOL, `skills/hotfix/SKILL.md` STEP 4) no longer read `DEGRADED` as a value of the `SECURITY — VERDICT:` line. The auditor prints `VERDICT: PASS` on a scan without semgrep and reports DEGRADED on its `TOOL:` line, so the old `DEGRADED` branch never fired: a degraded scan read as a clean PASS, the checklist result and the `make plugin` hint were never surfaced, and hotfix's `SECURITY: DEGRADED (checklist only)` summary could not be reached. The `PASS` branch now reads the `TOOL:` line first, and a PASS with no `TOOL:` line is a structural failure (one fresh retry, then escalation). `lib/effort-shift.md` § Advisor names the `TOOL:` line in the feat/bugfix skip condition. The auditor's output format is unchanged. Test: `lib/tests/loops-light.test.sh` (DEGRADED on the TOOL line).
|
||||
- **Advisor in sub-agents**: opus sub-agents, general-purpose ones included, called the `advisor` tool on their own: 30 calls, 7.1M input tokens. The tool is listed to every sub-agent, its own instructions ask for calls, and the rule in `CLAUDE.global.md` reached them only as an attachment. A new SubagentStart hook, `hooks/subagent-advisor.sh` (`settings.json`, timeout 5 s), tells every sub-agent at spawn not to call it unless its agent definition or its dispatcher's brief allows it, then at most once. The allowed set is plan-challenger, verifier, security-auditor, `analyzer` and an opus code review (`/ship-feature` STEP 6, `/init-project` STEP 10, a standalone subagent-driven-development final review), whose brief allows one call. plugin-advisor, seo-analyzer, geo-analyzer, doc-syncer, commit-changer and handover-doc-writer, and the opus briefs of `/onboard`, client-handover-writer and `/tour` Phase B, carry a never-call line. A standalone subagent-driven-development run dispatches every worker on sonnet, task reviews and fix rounds included. `Advisor:` rows gain `not called (sub-agent)`. Test: `lib/tests/subagent-advisor.test.sh`.
|
||||
|
||||
## [3.0.0] — 2026-11-12
|
||||
|
||||
|
||||
@@ -85,10 +85,13 @@ security PASS, not DEGRADED, each on its first attempt, their summary's
|
||||
`ADVISOR` field then reading `skipped (gates clean on first pass)`;
|
||||
`/audit-delta` and `/tour` when the run applied no fix), and before
|
||||
recommending a change to the doctrine, the architecture or a public interface.
|
||||
plan-challenger, verifier, security-auditor and `analyzer` may call it once
|
||||
when dispatched as a sub-agent, before their verdict or report: advice can
|
||||
add a finding or raise its severity, never drop, lower or clear one. Other
|
||||
sub-agents do not, even when the tool is listed. An absent or
|
||||
plan-challenger, verifier, security-auditor, `analyzer` and an opus code
|
||||
review (`/ship-feature` STEP 6, `/init-project` STEP 10, a standalone
|
||||
subagent-driven-development final review) may call it once when dispatched
|
||||
as a sub-agent, before their verdict or report: advice can add a finding or
|
||||
raise its severity, never drop, lower or clear one. Other sub-agents never
|
||||
call it, even when the tool is listed; the SubagentStart hook
|
||||
`hooks/subagent-advisor.sh` restates the rule in every sub-agent at spawn. An absent or
|
||||
failing advisor changes nothing, and its advice waives no gate, cap or guard
|
||||
(`lib/effort-shift.md` § Advisor). The main loop writes no
|
||||
code outside a skill run (the router's guard redirects it to a skill); the fresh
|
||||
|
||||
@@ -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 <nom>` tapé, ou un choix dans le sélecteur `/model`, avec un modèle de la table demande sa portée (Échap ne change rien). Le changement du sélecteur est d'abord retenu (le moteur affiche qu'un hook l'a bloqué), puis la question vient ; un choix fait pendant qu'un autre dialogue est ouvert est refusé (`answer the open dialog first`) : This project écrit l'id complet dans `model` du `.claude/settings.local.json` du projet (créé s'il manque, à garder dans le `.gitignore`) et pose une route de modèle tenue ; This conversation pose la route seule, sans rien écrire ; Everywhere lance le `/model` natif (`settings.json` utilisateur, tous les projets). Default dans le sélecteur, sans argument, avec un nom inconnu, en headless (`-p`) ou mod coupé, le `/model` natif passe sans question. Un modèle choisi dans ce dialogue change toujours : ni plafond de relecture à froid, ni `mainUpgrade` ni `mainModelSwitch`. S'il est en panne, la boucle principale reste où elle est jusqu'à son retour. Un changement natif (ligne Model de `/config` comprise) ou `/clear` l'abandonne ; un `/route model=` tapé garde les plafonds. La ligne Model de `/config` écrit toujours le `settings.json` utilisateur, et un dialogue jamais répondu n'a pas de délai. Pour relancer un tour bloqué : `ultrathink` dans le prompt (plancher d'effort du tour) ou `/route effort=max` (tient jusqu'à `/route clear`). Le `/effort` intégré n'a pas d'effet dans un run : les lignes et les routes passent devant. Les règles de mots-clés du prompt (`plan`, `design`, `architecture`… prennent l'effort de plan ; `pourquoi`, `review`, `audit`… celui de reflect), `ultrathink` et un lancement d'agent par la boucle principale (route `orchestrate` dérivée, tenue jusqu'à la fin de ses agents en arrière-plan) ne fixent que le niveau d'effort du tour, jamais le modèle : ils ne font jamais monter la boucle principale au-dessus du modèle de la session, et un run best tenu garde son modèle. Fable n'arrive sur la boucle principale que par un choix à la main (`/model`, sélecteur), un `/route model=fable` tapé, une phase qui nomme `model: fable` ou une config machine qui le place dans un tier : aucun tier ni aucune phase livrés ne le contiennent. Fable sert de conseiller (outil advisor, `advisorModel` dans settings.json, réglé par `/advisor`) : la boucle principale l'appelle au moins sur le plan écrit, avant que les challengers du plan le voient (`lib/challenge-plan.md`, une fois par run de skill ; la ligne `Advisor:` du CHALLENGE SUMMARY dit ce qu'il a changé), une fois par run verify-secure à la première boucle de porte qui échoue deux fois (le conseil reste dans la boucle principale, jamais dans le brief d'un exécutant ; un STOP au plafond ou en escalade le reprend), avant de proposer un merge ou de déclarer finie une longue tâche (deux exceptions : `/feat` et `/bugfix` le sautent quand GATE 0 a dit MET, le verifier CONFORME et la sécurité PASS, pas DEGRADED, chacun au premier essai, et leur champ `ADVISOR` affiche alors `skipped (gates clean on first pass)` ; `/audit-delta` et `/tour` le sautent quand le run n'a appliqué aucun fix), et avant de recommander un changement de la doctrine, de l'architecture ou d'une interface publique ; plan-challenger, verifier, security-auditor et `analyzer` peuvent l'appeler une fois, seulement quand ils sont lancés comme sous-agents, avant leur verdict ou leur rapport : un conseil peut ajouter un constat ou relever sa sévérité, jamais le retirer, l'abaisser ni l'effacer ; les autres sous-agents ne l'appellent pas, même quand l'outil est listé. Conseiller absent ou en erreur : on continue ; un conseil ne lève aucune porte, aucun plafond ni aucune garde. Un prompt tapé sans règle, skill ni route en cours passe par un classifieur (un appel au petit modèle, 3 secondes au plus) : le tour prend la route de la phase devinée : son niveau d'effort, et son modèle, jamais au-dessus de celui de la session. Une devinette `coding` ou `bookkeeping` fait descendre la boucle principale vers un modèle moins cher quand `mainModelSwitch` est actif (par défaut) et que la relecture à froid tient sous `downgradeMaxTokens` (120000 tokens par défaut). Cette relecture compte aussi le prompt qui vient d'être envoyé (un token pour 3 caractères), et un document joint bloque la descente pour cette étape. Le cache compte comme chaud pendant le TTL du moteur (`cache_ttl`, 5 ou 60 minutes), 60 minutes par défaut. `/route classify off` ou `"classify": false` dans la config machine le coupe, et un `/effort` tapé entre deux tours annule la devinette pour ce toLine truncated
|
||||
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 <nom>` tapé, ou un choix dans le sélecteur `/model`, avec un modèle de la table demande sa portée (Échap ne change rien). Le changement du sélecteur est d'abord retenu (le moteur affiche qu'un hook l'a bloqué), puis la question vient ; un choix fait pendant qu'un autre dialogue est ouvert est refusé (`answer the open dialog first`) : This project écrit l'id complet dans `model` du `.claude/settings.local.json` du projet (créé s'il manque, à garder dans le `.gitignore`) et pose une route de modèle tenue ; This conversation pose la route seule, sans rien écrire ; Everywhere lance le `/model` natif (`settings.json` utilisateur, tous les projets). Default dans le sélecteur, sans argument, avec un nom inconnu, en headless (`-p`) ou mod coupé, le `/model` natif passe sans question. Un modèle choisi dans ce dialogue change toujours : ni plafond de relecture à froid, ni `mainUpgrade` ni `mainModelSwitch`. S'il est en panne, la boucle principale reste où elle est jusqu'à son retour. Un changement natif (ligne Model de `/config` comprise) ou `/clear` l'abandonne ; un `/route model=` tapé garde les plafonds. La ligne Model de `/config` écrit toujours le `settings.json` utilisateur, et un dialogue jamais répondu n'a pas de délai. Pour relancer un tour bloqué : `ultrathink` dans le prompt (plancher d'effort du tour) ou `/route effort=max` (tient jusqu'à `/route clear`). Le `/effort` intégré n'a pas d'effet dans un run : les lignes et les routes passent devant. Les règles de mots-clés du prompt (`plan`, `design`, `architecture`… prennent l'effort de plan ; `pourquoi`, `review`, `audit`… celui de reflect), `ultrathink` et un lancement d'agent par la boucle principale (route `orchestrate` dérivée, tenue jusqu'à la fin de ses agents en arrière-plan) ne fixent que le niveau d'effort du tour, jamais le modèle : ils ne font jamais monter la boucle principale au-dessus du modèle de la session, et un run best tenu garde son modèle. Fable n'arrive sur la boucle principale que par un choix à la main (`/model`, sélecteur), un `/route model=fable` tapé, une phase qui nomme `model: fable` ou une config machine qui le place dans un tier : aucun tier ni aucune phase livrés ne le contiennent. Fable sert de conseiller (outil advisor, `advisorModel` dans settings.json, réglé par `/advisor`) : la boucle principale l'appelle au moins sur le plan écrit, avant que les challengers du plan le voient (`lib/challenge-plan.md`, une fois par run de skill ; la ligne `Advisor:` du CHALLENGE SUMMARY dit ce qu'il a changé), une fois par run verify-secure à la première boucle de porte qui échoue deux fois (le conseil reste dans la boucle principale, jamais dans le brief d'un exécutant ; un STOP au plafond ou en escalade le reprend), avant de proposer un merge ou de déclarer finie une longue tâche (deux exceptions : `/feat` et `/bugfix` le sautent quand GATE 0 a dit MET, le verifier CONFORME et la sécurité PASS, pas DEGRADED, chacun au premier essai, et leur champ `ADVISOR` affiche alors `skipped (gates clean on first pass)` ; `/audit-delta` et `/tour` le sautent quand le run n'a appliqué aucun fix), et avant de recommander un changement de la doctrine, de l'architecture ou d'une interface publique ; plan-challenger, verifier, security-auditor, `analyzer` et une revue de code sur opus (`/ship-feature` STEP 6, `/init-project` STEP 10, revue finale d'un subagent-driven-development lancé seul) peuvent l'appeler une fois, seulement quand ils sont lancés comme sous-agents, avant leur verdict ou leur rapport : un conseil peut ajouter un constat ou relever sa sévérité, jamais le retirer, l'abaisser ni l'effacer ; les autres sous-agents ne l'appellent jamais, même quand l'outil est listé, et le hook SubagentStart `hooks/subagent-advisor.sh` leur rappelle la règle au lancement. Conseiller absent ou en erreur : on continue ; un conseil ne lève aucune porte, aucun plafond ni aucune garde. Un prompt tapé sans règle, skill ni route en cours passe par un classifieur (un appel au petit modèle, 3 secondes au plus) : le tour prend la route de la phase devinée : son niveau d'effort, et son modèle, jamais au-dessus de celui de la session. Une devinette `coding` ou `bookkeeping` fait descendre la boucle principale vers un modèle moins cher quand `mainModelSwitch` est actif (par défaut) et que la relecture à froid tient sous `downgradeMaxTokens` (120000 tokens par défaut). Cette relecture compte aussi le prompt qui vient d'être envoyé (un token pour 3 caractères), et un document joint bloque la descente pour cette étape. Le cache compte comme chaLine truncated
|
||||
|
||||
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 (<kind>), 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.
|
||||
|
||||
|
||||
Reference in new issue
Block a user