docs(doctrine): judgment agents advise only when dispatched; auditor raises only upward; protocol mirror; end-of-run point sites
This commit is contained in:
1 parent
f48343e2d7
commit
24354d9b68
4 files changed
+39
-22
No files matched your search
@@ -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
@@ -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
@@ -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
@@ -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.
|
||||
|
||||
|
||||
Reference in new issue
Block a user