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.
|
file or other shell. Hermetic tests run through `make test [suite=…]` only.
|
||||||
- Stronger model needed (an approach to settle before building, a stuck
|
- Stronger model needed (an approach to settle before building, a stuck
|
||||||
problem, a long task before calling it done) → the main loop calls
|
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
|
the advisor tool when it is listed (settings `advisorModel`, Fable,
|
||||||
not. Fable is never routed or pinned: the router tops out at opus
|
set by /advisor), at least at the points of
|
||||||
(BDR-150).
|
`~/.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,
|
- Ask rather than guess. A choice visible in the result (placement,
|
||||||
wording, order, behavior), a name that becomes public (command, flag,
|
wording, order, behavior), a name that becomes public (command, flag,
|
||||||
endpoint, file), or a scope the request leaves open → ask, even mid-task;
|
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
|
(STEP 1's missing/unreadable-plan verdict) is part of the grammar: it
|
||||||
carries only the `PLAN:` line — no FINDINGS, no PROOF — and the
|
carries only the `PLAN:` line — no FINDINGS, no PROOF — and the
|
||||||
orchestrator treats it as a dispatcher-side failure, not a challenge result.
|
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)
|
## 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
|
- 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
|
gate people learn to bypass (LRN-047) — MEDIUM/LOW are reported, not
|
||||||
gated.
|
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)
|
## 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.
|
missing `PROOF` — the run was skipped, not the diff clean.
|
||||||
- The verdict grammar is load-bearing: exactly one `VERIFY — VERDICT:`
|
- The verdict grammar is load-bearing: exactly one `VERIFY — VERDICT:`
|
||||||
line, spelled exactly as above.
|
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)
|
## ORCHESTRATOR PROTOCOL (consumer contract — wiring reference)
|
||||||
|
|
||||||
|
|||||||
+23
-7
@@ -101,13 +101,29 @@ Measure the split any time: `python3 ~/.claude/lib/effort-audit.py`
|
|||||||
## Advisor
|
## Advisor
|
||||||
|
|
||||||
Fable runs as the advisor (settings `advisorModel`), never a route or pin
|
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
|
target (BDR-150). It is a server tool: the router cannot see or refuse it.
|
||||||
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
|
Main loop, at least at these points (for work outside them, see the
|
||||||
see or refuse it. The main loop calls it; sub-agents do not, even when the
|
triggers in CLAUDE.global.md § Workflow):
|
||||||
tool is listed. Advisor absent or erroring (Fable out of credits, for
|
1. Before settling an approach: ahead of writing a skill's plan (`/feat`,
|
||||||
example) → proceed as written. Advice is input, never consent: it waives no
|
`/bugfix`, `/ship-feature`).
|
||||||
gate, cap or guard; at a loop cap it feeds the STOP diagnosis.
|
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
|
## Never
|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user