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).
This commit is contained in:
bchanot committed 2026-11-17 14:03:42 +01:00
1 parent d059658067
commit 58a5273b5c
5 files changed
+63 -14

No files matched your search

+8 -7
View File
@@ -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;
+6
View File
@@ -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.
---
+17 -1
View File
@@ -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.
+10 -6
View File
@@ -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
+22
View File
@@ -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