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:
1 parent
f3b3987acf
commit
6ef3069f6e
5 files changed
+54
-10
No files matched your search
+6
-3
@@ -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;
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
|
||||
Reference in new issue
Block a user