docs(doctrine): challenge route rides the first challenge call; summary Advisor row; feat/bugfix skip the end call on clean gates

This commit is contained in:
bchanot committed 2026-11-18 14:57:07 +01:00
1 parent 858bd41782
commit 2b7aeb8605
14 files changed
+59 -34

No files matched your search

+2 -1
View File
@@ -170,7 +170,7 @@ Then show the user the same compact table inline.
### 3b-bis. CHALLENGE THE PROPOSALS (before the gate)
`mcp__model-router__route(phase="plan")` first (route: own level before the challenge; send it with the challenger dispatch).
`mcp__model-router__route(phase="plan")` first (route: own level before the challenge; send it with the first tool call of lib/challenge-plan.md, the advisor call when one is due).
This axis' findings + proposed fixes are a proposal set worth attacking before
the human gate. Persist THIS axis' finding list (not the whole append-only
report) to `.claude/tasks/plans/<date>-<axis>-<HHMM>.md`, then run
@@ -192,6 +192,7 @@ CHALLENGE SUMMARY (3b-bis — 3 lenses):
BLOCKERs addressed : <n> — <finding → the named finding-set change that closes it>
Deferred (human-ack): <list | none>
Lenses returned : correctness / robustness / simplicity (NAME any that failed to return)
Advisor : <the finding-set change it drove | called, no change | not called (absent | error | already called this run)>
```
- "Fix what you find" said **in the invocation** does NOT skip this gate:
+10 -6
View File
@@ -127,7 +127,7 @@ RISK: <low/medium — what could go wrong>
fast-path is not exempt: a 1-line fix with a visible choice still asks.
## STEP 3b — CHALLENGE THE FIX PLAN (before the contract)
`mcp__model-router__route(phase="reflect")` first (route: own level before the challenge; send it with the challenger dispatch).
`mcp__model-router__route(phase="reflect")` first (route: own level before the challenge; send it with the first tool call of lib/challenge-plan.md, the advisor call when one is due).
Unless the fix is the trivial 1-2 line case STEP 3 already fast-paths, the
DIAGNOSIS + FIX PLAN is a reflection worth attacking before it hardens into a
contract. Persist it to `.claude/tasks/plans/<date>-<slug>-<HHMM>.md`, then run
@@ -137,8 +137,8 @@ dispositions. Three blind challengers attack it (correctness = is the root cause
right; robustness = blast radius / regressions; simplicity = is the fix minimal);
RE-THINK every aspect a BLOCKER lands, re-challenge once if the plan materially
changed. STEP 3.5 writes the contract from the REVISED plan. Print a CHALLENGE SUMMARY
(BLOCKERs addressed / deferred / lenses returned), folding any deferred BLOCKER into
the STEP 3 approval gate.
(BLOCKERs addressed / deferred / lenses returned / advisor), folding any
deferred BLOCKER into the STEP 3 approval gate.
## STEP 3.5 — CONTRACT
@@ -233,9 +233,12 @@ Parse the `BUGFIX-EXEC REPORT`:
two sentences of body).
`mcp__model-router__route(phase="reflect")` first (route: end-of-run review).
Before the summary, the main loop prints the run's diff stat, then makes its
end-of-run advisor call (`lib/effort-shift.md` § Advisor); its answer
goes into the summary as an `Advisor:` line, and a fix it drives goes
back through the gates.
end-of-run advisor call (`lib/effort-shift.md` § Advisor), skipped when
GATE 0 said MET, the verifier CONFORME and security PASS (not DEGRADED),
each on its first attempt; any other verdict, a retry, a loop iteration or
a verdict no longer in view runs the call. The answer, or the skip, goes
into the summary's `ADVISOR` field, and a fix it drives goes back through
the gates.
4. Print summary:
```
BUGFIX COMPLETE
@@ -244,6 +247,7 @@ Parse the `BUGFIX-EXEC REPORT`:
FILE(S) : <changed files>
TEST(S) : <added/updated tests, or "none — verified manually">
REGRESSION : <checked areas>
ADVISOR : <one-line answer | skipped (gates clean on first pass) | not called (absent | error)>
```
## STEP 7 — DOC SYNC (automatic)
+2 -1
View File
@@ -122,7 +122,7 @@ TOTALS: <N blocking, N warn, N info>
If no issues found: report clean state and stop.
## STEP 3b — CHALLENGE THE SCOPE (before approval)
`mcp__model-router__route(phase="plan")` first (route: own level before the challenge; send it with the challenger dispatch).
`mcp__model-router__route(phase="plan")` first (route: own level before the challenge; send it with the first tool call of lib/challenge-plan.md, the advisor call when one is due).
The STEP 3 report is the proposed cleanup scope — worth attacking before the
human approves it. It is still inline, so FIRST persist it to
`.claude/tasks/plans/<date>-<slug>-<HHMM>.md` (STEP 3 report format, one item
@@ -144,6 +144,7 @@ CHALLENGE SUMMARY (STEP 3b — 3 lenses):
BLOCKERs addressed : <n> — <finding → the named scope change that closes it>
Deferred (human-ack): <list | none>
Lenses returned : correctness / robustness / simplicity (NAME any that failed to return)
Advisor : <the scope change it drove | called, no change | not called (absent | error | already called this run)>
AskUserQuestion:
Approve which items for execution? (all / <item numbers> / clarify <item>)
+10 -6
View File
@@ -124,7 +124,7 @@ in the contract's CLARIFICATIONS `[gated]` and in the plan. A choice that
surfaces only during execution comes back as `NEED-DECISION` (STEP 3).
## STEP 1b — CHALLENGE THE PLAN (before branching)
`mcp__model-router__route(phase="reflect")` first (route: own level before the challenge; send it with the challenger dispatch).
`mcp__model-router__route(phase="reflect")` first (route: own level before the challenge; send it with the first tool call of lib/challenge-plan.md, the advisor call when one is due).
The STEP 1 plan is a reflection worth attacking before a branch is spent on it.
Persist it to `.claude/tasks/plans/<date>-<slug>-<HHMM>.md`, then run
`$HOME/.claude/lib/challenge-plan.md` with `PLAN` = that file, `KIND` = `build-plan`,
@@ -132,8 +132,8 @@ Persist it to `.claude/tasks/plans/<date>-<slug>-<HHMM>.md`, then run
Three blind challengers attack it; RE-THINK every aspect a BLOCKER lands (a named
plan change, or `[deferred]`), re-challenge once if the plan materially changed. The
STEP 3 executor receives the REVISED plan. Before dispatch, print a CHALLENGE SUMMARY
(BLOCKERs addressed / deferred / lenses returned), surfacing any deferred BLOCKER in
the STEP 1 pass B batch.
(BLOCKERs addressed / deferred / lenses returned / advisor), surfacing any
deferred BLOCKER in the STEP 1 pass B batch.
## STEP 2 — BRANCH
@@ -207,9 +207,12 @@ propose/apply executor).
Then `mcp__model-router__route(phase="reflect")` (route: nested commit-change loaded at apply; reload feat's level).
Before the summary, the main loop prints the run's diff stat, then makes its
end-of-run advisor call (`lib/effort-shift.md` § Advisor); its answer
goes into the summary as an `Advisor:` line, and a fix it drives goes
back through the gates.
end-of-run advisor call (`lib/effort-shift.md` § Advisor), skipped when
GATE 0 said MET, the verifier CONFORME and security PASS (not DEGRADED),
each on its first attempt; any other verdict, a retry, a loop iteration or
a verdict no longer in view runs the call. The answer, or the skip, goes
into the summary's `ADVISOR` field, and a fix it drives goes back through
the gates.
Print summary:
```
@@ -218,6 +221,7 @@ FEATURE : <name>
FILE(S) : <created/modified files>
TEST(S) : <added tests>
VERIFIED : <what was checked>
ADVISOR : <one-line answer | skipped (gates clean on first pass) | not called (absent | error)>
```
## STEP 6 — DOC SYNC (automatic)
+2 -1
View File
@@ -522,7 +522,7 @@ Extract the score and critical-alert count from `.claude/audits/HARDEN.md` for t
---
## STEP 2b — CHALLENGE THE FIX BUNDLE (MODE=fix only, advisory)
`mcp__model-router__route(phase="reflect")` first (route: own level before the challenge; send it with the challenger dispatch).
`mcp__model-router__route(phase="reflect")` first (route: own level before the challenge; send it with the first tool call of lib/challenge-plan.md, the advisor call when one is due).
Skip if MODE=audit (no bundle exists). Else, before the STEP 3 gate, harden the bundle:
extract the `## 8. Fix bundle` section from HARDEN.md to
`.claude/tasks/plans/<date>-<slug>-<HHMM>.md` (a clean, blind-judgeable artifact), then run
@@ -557,6 +557,7 @@ If MODE=fix and `.claude/audits/HARDEN.md` ends with `READY TO APPLY — awaitin
BLOCKERs addressed : <n> — <finding → the named bundle change that closes it>
Deferred (human-ack): <list | none>
Lenses returned : correctness / robustness / simplicity (NAME any that failed to return)
Advisor : <the bundle change it drove | called, no change | not called (absent | error | already called this run)>
Options :
A) Apply all
+3 -3
View File
@@ -94,7 +94,7 @@ point. Run it ONLY when the settled fix touches control flow or behaviour — an
off-by-one, a wrong operator/variable, a behaviour-changing config value, or a
missing import that alters execution. In doubt → it is probably a `/bugfix`.
`mcp__model-router__route(phase="reflect")` first (route: own level before the challenge; send it with the challenger dispatch).
`mcp__model-router__route(phase="reflect")` first (route: own level before the challenge; send it with the first tool call of lib/challenge-plan.md, the advisor call when one is due).
For a logic fix: persist the STEP 1 located fix (root cause + the exact edit) to
`.claude/tasks/plans/<date>-<slug>-<HHMM>.md`, then run
`$HOME/.claude/lib/challenge-plan.md` with `PLAN` = that file, `KIND` =
@@ -102,8 +102,8 @@ For a logic fix: persist the STEP 1 located fix (root cause + the exact edit) to
contract's acceptance criteria. Three blind challengers attack the fix; the main
loop RE-THINKS any aspect a BLOCKER lands (a named change to the fix, or
`[deferred]`) and re-challenges once if it materially changed. Print a
CHALLENGE SUMMARY (BLOCKERs addressed / deferred / lenses returned). A BLOCKER
that shows the fix is wrong or incomplete means this was never
CHALLENGE SUMMARY (BLOCKERs addressed / deferred / lenses returned / advisor).
A BLOCKER that shows the fix is wrong or incomplete means this was never
a hotfix — escalate to `/bugfix` (its STEP 3b runs the same phase under the full
verify+secure loop).
+2 -1
View File
@@ -192,7 +192,7 @@ Invoke `writing-plans` (vendored superpowers skill) with BRIEF + skeleton.
Granular tasks (2-5 min each), exact file paths, TDD: tests before code.
## STEP 6b — CHALLENGE THE PLAN (before the gate)
`mcp__model-router__route(phase="plan")` first (route: own level before the challenge; send it with the challenger dispatch).
`mcp__model-router__route(phase="plan")` first (route: own level before the challenge; send it with the first tool call of lib/challenge-plan.md, the advisor call when one is due).
Before the human sees the implementation plan, harden it. Run
`$HOME/.claude/lib/challenge-plan.md` with `PLAN` = the plan STEP 6 wrote under
`docs/superpowers/plans/`, `KIND` = `build-plan`, `SCOPE` = the skeleton + task file
@@ -213,6 +213,7 @@ CHALLENGE SUMMARY (STEP 6b — 3 lenses):
BLOCKERs addressed : <n> — <finding → the named plan change that closes it>
Deferred (human-ack): <list | none>
Lenses returned : correctness / robustness / simplicity (NAME any that failed to return)
Advisor : <the plan change it drove | called, no change | not called (absent | error | already called this run)>
Approve and start? (yes / request changes)
```
Changes → back to STEP 6. Approved → continue.
+2 -1
View File
@@ -917,7 +917,7 @@ Vérifier que les 4 fichiers `.claude/audits/ONBOARD_REPORT.md`, `.claude/audits
---
## STEP 7b — CHALLENGE THE PROPOSALS (before the human gate)
`mcp__model-router__route(phase="plan")` first (route: own level before the challenge; send it with the challenger dispatch).
`mcp__model-router__route(phase="plan")` first (route: own level before the challenge; send it with the first tool call of lib/challenge-plan.md, the advisor call when one is due).
The 4 audit files are on disk; `AUDIT_PROPOSALS.md` is the artifact worth
attacking before the human spends a gate on it. Run
`$HOME/.claude/lib/challenge-plan.md` with `PLAN` =
@@ -961,6 +961,7 @@ CHALLENGE SUMMARY (STEP 7b — 3 lenses):
BLOCKERs addressed : <n> — <finding → the named proposals change that closes it>
Deferred (human-ack): <list | none>
Lenses returned : correctness / robustness / simplicity (NAME any that failed to return)
Advisor : <the proposals change it drove | called, no change | not called (absent | error | already called this run)>
Prochaine étape : générer .claude/tasks/TODO.md depuis .claude/audits/AUDIT_PROPOSALS.md approuvé.
+2 -1
View File
@@ -86,7 +86,7 @@ your bundle."
```
## STEP 1b — CHALLENGE THE FIX BUNDLE (advisory, before apply)
`mcp__model-router__route(phase="reflect")` first (route: own level before the challenge; send it with the challenger dispatch).
`mcp__model-router__route(phase="reflect")` first (route: own level before the challenge; send it with the first tool call of lib/challenge-plan.md, the advisor call when one is due).
The analyzer returned a `## FIX BUNDLE` — worth attacking before any edit lands.
**Skip if intervention mode = conservative** (nothing is applied). Else persist the
bundle verbatim to `.claude/tasks/plans/<date>-<slug>-<HHMM>.md`, then run
@@ -138,6 +138,7 @@ CHALLENGE SUMMARY (STEP 1b — 3 lenses):
BLOCKERs addressed : <n> — <finding → the named bundle change that closes it>
Deferred (human-ack): <list | none>
Lenses returned : correctness / robustness / simplicity (NAME any that failed to return)
Advisor : <the bundle change it drove | called, no change | not called (absent | error | already called this run)>
Approve all / select (ids) / skip all?
```
+2 -1
View File
@@ -511,7 +511,7 @@ the reports."
```
## STEP 1b — CHALLENGE THE FIX BUNDLE (advisory, before apply)
`mcp__model-router__route(phase="reflect")` first (route: own level before the challenge; send it with the challenger dispatch).
`mcp__model-router__route(phase="reflect")` first (route: own level before the challenge; send it with the first tool call of lib/challenge-plan.md, the advisor call when one is due).
Both envelopes now carry a `## FIX BUNDLE` — worth attacking before any edit lands.
**Skip if intervention mode = conservative** (nothing is applied). Else persist both
bundles (seo + geo, verbatim) to `.claude/tasks/plans/<date>-<slug>-<HHMM>.md`, then run
@@ -583,6 +583,7 @@ CHALLENGE SUMMARY (STEP 1b — 3 lenses):
BLOCKERs addressed : <n> — <finding → the named bundle change that closes it>
Deferred (human-ack): <list | none>
Lenses returned : correctness / robustness / simplicity (NAME any that failed to return)
Advisor : <the bundle change it drove | called, no change | not called (absent | error | already called this run)>
Approve all / select (ids) / skip all?
```
@@ -256,7 +256,7 @@ grep -c '^### \[Critique\]' .claude/audits/VALIDATE.md
---
## STEP 2b — CHALLENGE THE FIX BUNDLE (MODE=fix only, advisory)
`mcp__model-router__route(phase="reflect")` first (route: own level before the challenge; send it with the challenger dispatch).
`mcp__model-router__route(phase="reflect")` first (route: own level before the challenge; send it with the first tool call of lib/challenge-plan.md, the advisor call when one is due).
Skip if MODE=audit (no bundle exists). Else, before the STEP 3 gate, harden the bundle:
extract the `## 5. Fix bundle` section from VALIDATE.md to
`.claude/tasks/plans/<date>-<slug>-<HHMM>.md` (a clean, blind-judgeable artifact), then run
@@ -296,6 +296,7 @@ CHALLENGE SUMMARY (STEP 2b — 3 lenses) :
BLOCKERs addressed : <n> — <finding → the named bundle change that closes it>
Deferred (human-ack): <list | none>
Lenses returned : correctness / robustness / simplicity (NAME any that failed to return)
Advisor : <the bundle change it drove | called, no change | not called (absent | error | already called this run)>
Options :
A) Apply all
+2 -1
View File
@@ -133,7 +133,7 @@ request nor the STEP 1 brainstorm settled (check the contract's CLARIFICATIONS
first) → one batch before STEP 2b; answers append to the contract `[gated]`.
## STEP 2b — CHALLENGE THE PLAN (adversarial, before the gate)
`mcp__model-router__route(phase="plan")` first (route: own level before the challenge; send it with the challenger dispatch).
`mcp__model-router__route(phase="plan")` first (route: own level before the challenge; send it with the first tool call of lib/challenge-plan.md, the advisor call when one is due).
Before the human sees the plan, harden it. Run `$HOME/.claude/lib/challenge-plan.md`:
- `PLAN` = the plan STEP 2 wrote under `docs/superpowers/plans/`
- `KIND` = `build-plan`
@@ -163,6 +163,7 @@ CHALLENGE SUMMARY (STEP 2b — 3 lenses):
BLOCKERs addressed : <n> — <finding → the named plan change that closes it>
Deferred (human-ack): <list | none>
Lenses returned : correctness / robustness / simplicity (NAME any that failed to return)
Advisor : <the plan change it drove | called, no change | not called (absent | error | already called this run)>
Approve and execute? (yes / request changes)
```
This block EXPOSES each in-force item with the plan's CLAIMED disposition, for human