docs(doctrine): advisor call points; judgment agents may consult it once

Main loop calls the advisor before a skill's plan, once per verify-secure run when stuck, and before a merge. plan-challenger, verifier and security-auditor may call it once before the verdict; advice only adds, never clears (amends BDR-150).
This commit is contained in:
bchanot committed 2026-11-17 12:59:15 +01:00
1 parent f3b3987acf
commit 6ef3069f6e
5 files changed
+54 -10

No files matched your search

+6 -3
View File
@@ -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;
+5
View File
@@ -97,6 +97,11 @@ PROOF: read <n> files, inspected <what>, 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)
+12
View File
@@ -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:<STEP 3 class>`; a raised one keeps its own line, its
rule/check becoming `<rule>+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 <n>
added/raised`. It never removes, lowers or waives a finding from
semgrep, the checklist or STEP 4.
## ORCHESTRATOR PROTOCOL (consumer contract — wiring reference)
+8
View File
@@ -158,6 +158,14 @@ PROOF: read <n> files, ran <cmd → result | nothing>, checked <n>/<n> 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)
+23 -7
View File
@@ -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