docs(doctrine): judgment agents advise only when dispatched; auditor raises only upward; protocol mirror; end-of-run point sites

This commit is contained in:
bchanot committed 2026-11-17 18:10:02 +01:00
1 parent f48343e2d7
commit 24354d9b68
4 files changed
+39 -22

No files matched your search

+12 -7
View File
@@ -97,17 +97,21 @@ 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.
- Advisor, when dispatched as a sub-agent: 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)
How an orchestrator runs the plan-challenge phase (the loop + synthesis live in
the MAIN loop, never here):
- ADVISOR FIRST (main loop): per `lib/challenge-plan.md` "Advisor first",
with no main-loop advisor call since the skill run started; absent or
erroring → dispatch as written. The advice never enters a challenger
brief: they stay blind.
- Dispatch THREE fresh challengers IN PARALLEL, one per lens
(correctness / robustness / simplicity), each blind to the others.
- MODEL (BDR-076, supersedes the BDR-066 inherit): plan critique is AUDIT
@@ -131,5 +135,6 @@ the MAIN loop, never here):
- RE-CHALLENGE ONCE if synthesis materially changed the plan (a fix can open a
new flaw); max 1 extra pass, then the human gate.
- ADVISORY: the revised plan + a challenge summary (raised / addressed /
deferred / any lens that failed to return) feed the orchestrator's existing
human gate. The human decides — this is not a hard block.
deferred / any lens that failed to return / an `Advisor:` row) feed the
orchestrator's existing human gate. The human decides — this is not a
hard block.
+15 -12
View File
@@ -157,18 +157,21 @@ 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.
- Advisor, when dispatched as a sub-agent: 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>`; it takes that
class's severity, for that finding only, and is REPORTED as LOW when
it matches no class. A raise applies only when its class's severity
is higher than the finding's own: it keeps the finding's line, its
rule/check becoming `<rule>+advisor`, so it counts once. A raise
that does not apply, or matches no class, changes nothing: no tag,
no PROOF count. An added or applied finding enters STEP 5's dedup and
BLOCK(n) like any other, and PROOF ends with
`; advisor <n> added/raised`.
Advice never removes, lowers or waives a finding from semgrep, the
checklist or STEP 4.
## ORCHESTRATOR PROTOCOL (consumer contract — wiring reference)
+2 -2
View File
@@ -158,8 +158,8 @@ 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
- Advisor, when dispatched as a sub-agent: 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
+10 -1
View File
@@ -115,7 +115,16 @@ triggers in CLAUDE.global.md § Workflow):
(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.
done. Wired at the end step of feat, bugfix, ship-feature,
init-project, a11y, guardrails, audit-delta and tour, and at the
release gate of release-candidate: one end-of-run call per skill
run, never skipped for an earlier plan or stuck call; audit-delta
and tour skip it when the run applied no fix. In the six flows that
run the gates, the main loop first prints the run's diff stat, a fix
the answer drives goes back through the gates, and a later proposal
reuses the answer and says it predates the newer commits. Elsewhere
the answer is reported only and a fix it calls for is a new run.
Inside a skill run, the points above also cover the triggers of
CLAUDE.global.md § Workflow; no second call for the same recommendation.