forked from bchanot/claude
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:
1 parent
d059658067
commit
58a5273b5c
5 files changed
+63
-14
No files matched your search
+8
-7
@@ -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;
|
||||
|
||||
@@ -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
@@ -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
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in new issue
Block a user