bmottin/claude_mac
1
0
Fork 0
forked from bchanot/claude
Code Pull Requests Activity

feat(skills): add 3-way adversarial plan-challenge phase to reflection orchestrators

Browse Source 
After a plan/reflection is elaborated and before it executes, three fresh blind
sub-agents (correctness / robustness / simplicity) attack it on the big model;
the main loop RE-THINKS every aspect a BLOCKER lands (a named plan change, or
[deferred]) and re-challenges once if the plan materially changed. Advisory into
each skill's existing human gate — the human stays the decider.

- lib/challenge-plan.md — reusable phase: fail-safe (never fail open),
  severity-driven (any single-lens BLOCKER = must-address), RE-THINK loop
- agents/plan-challenger.md — challenger role (read-only, big-model per BDR-066)
- lib/tests/plan-challenger.test.sh — 41-assertion structure lock
- wired into 11 orchestrators: ship-feature/init-project/feat/bugfix (build-plan),
  onboard/audit-delta/code-clean (proposals), seo/geo/harden/web-validate (fix-bundle)

Hardened by dogfooding: 3 blind challengers reviewed this feature's own v1 plan
and caught 4 BLOCKERs (fail-open, consensus-buries-lone-finding, wrong model
tier vs BDR-066, false on-disk-plan premise) — all fixed here.
This commit is contained in:
Bastien Chanot
2026-07-17 22:51:50 +02:00
parent 23c8c290d7
commit 6bfc0543e5
15 changed files with 443 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/audit-delta/SKILL.md
+21
View File
@@ -166,10 +166,31 @@ Append to `.claude/audits/AUDIT-DELTA.md` (create if absent), append-only:
Then show the user the same compact table inline.
### 3b-bis. CHALLENGE THE PROPOSALS (before the gate)
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
`$HOME/.claude/lib/challenge-plan.md` with `PLAN` = that file, `KIND` =
`proposals`, `SCOPE` = this axis' STEP 1 audit set, `CONSTRAINTS` = the axis
spec + the project CLAUDE.md norms already loaded. Three blind challengers ask
whether these are the RIGHT findings/priorities and what the audit under-rated;
the main loop RE-THINKS every aspect a BLOCKER lands (a named change to the
finding set, or `[deferred <date>]`) and re-challenges once if it materially
changed. Feed the REVISED findings + a CHALLENGE SUMMARY into 3c.
### 3c. APPROVAL GATE ★ MANDATORY STOP
Show the CHALLENGE SUMMARY (from 3b-bis) with the 3b findings table, then
AskUserQuestion: **fix all / pick which / none**.
```
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)
```
- "Fix what you find" said **in the invocation** does NOT skip this gate:
nobody can approve findings that did not exist yet. The gate is about
*these specific findings*.
skills/bugfix/SKILL.md
+13
View File
@@ -117,6 +117,19 @@ RISK: <low/medium — what could go wrong>
- If the fix is significant (>10 lines, multiple files,
behavior change): wait for user approval.
## STEP 3b — CHALLENGE THE FIX PLAN (before the contract)
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
`$HOME/.claude/lib/challenge-plan.md` with `PLAN` = that file, `KIND` = `build-plan`,
`SCOPE` = the FIX PLAN files, `CONSTRAINTS` = the STEP 2 in-force BDR/LRN/BLK
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.
## STEP 3.5 — CONTRACT
Run `$HOME/.claude/lib/contract-interview.md` (main loop). The DIAGNOSIS
skills/code-clean/SKILL.md
+19 -1
View File
@@ -119,11 +119,29 @@ TOTALS: <N blocking, N warn, N info>
If no issues found: report clean state and stop.
## STEP 3b — CHALLENGE THE SCOPE (before approval)
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
per line), then run `$HOME/.claude/lib/challenge-plan.md` with `PLAN` = that
file, `KIND` = `proposals`, `SCOPE` = the scanned target ($ARGUMENTS or repo
root), `CONSTRAINTS` = the STEP 1 project norms + the iron law (zero behavior
change). Three blind challengers ask whether these are the RIGHT items and what
the scan under- or over-scoped; the main loop RE-THINKS every aspect a BLOCKER
lands (a named scope change re-written into the report, or `[deferred <date>]`)
and re-challenges once if the scope materially changed. Feed the REVISED scope +
a CHALLENGE SUMMARY into STEP 4. Advisory — the human still approves per item.
## STEP 4 — VALIDATION GATE (interactive)
Present the report from STEP 3. Then ask:
Present the report from STEP 3 with the STEP 3b CHALLENGE SUMMARY. Then ask:
```
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)
AskUserQuestion:
Approve which items for execution? (all / <item numbers> / clarify <item>)
```
skills/feat/SKILL.md
+11
View File
@@ -117,6 +117,17 @@ PLAN:
If the approach is ambiguous: ask the user ONE focused question BEFORE
dispatching — never after (the executor cannot relay questions).
## STEP 1b — CHALLENGE THE PLAN (before branching)
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`,
`SCOPE` = the STEP 1 files, `CONSTRAINTS` = the STEP 0.6 in-force BDR/LRN dispositions.
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 via
STEP 1's one-question gate.
## STEP 2 — BRANCH
**Gitflow aiguillage (before dispatch):** follow `$HOME/.claude/lib/gitflow-aiguillage.md`
skills/geo/SKILL.md
+19
View File
@@ -58,6 +58,20 @@ $ARGUMENTS
"""
```
## STEP 1b — CHALLENGE THE FIX BUNDLE (advisory, before apply)
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
`$HOME/.claude/lib/challenge-plan.md` with `PLAN` = that file, `KIND` = `fix-bundle`,
`SCOPE` = the target site files the items touch, `CONSTRAINTS` = the geo-analyzer
file-ownership (robots.txt, llms.txt, JSON-LD, content shape) + the shared-file edit
discipline each item carries + intervention mode. Three blind challengers ask, per item:
will it ACHIEVE its goal / could it BREAK or regress the page / is a simpler (or no) fix
better. This main loop RE-THINKS every aspect a BLOCKER lands (a named bundle change, or
`[deferred <date>]`) and re-challenges once if the bundle materially changed. Advisory —
it sits BEFORE (never replaces) the STEP 2 GATED approval; carry its CHALLENGE SUMMARY
into that gate.
## STEP 2 — Apply the fix bundle (from THIS main loop, at L1)
The analyzer returned a `## FIX BUNDLE`. Apply it by dispatching
@@ -90,6 +104,11 @@ Present every GATED item (G5.x) in ONE gate:
```
GEO — gated content-shape changes need approval (visible):
G5.1 <change> — impact: <visible change>
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)
Approve all / select (ids) / skip all?
```
skills/harden/SKILL.md
+20
View File
@@ -518,6 +518,21 @@ Extract the score and critical-alert count from `.claude/audits/HARDEN.md` for t
---
## STEP 2b — CHALLENGE THE FIX BUNDLE (MODE=fix only, advisory)
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
`$HOME/.claude/lib/challenge-plan.md` with `PLAN` = that file, `KIND` = `fix-bundle`,
`SCOPE` = the config/target files each patch touches (.htaccess, next.config.js, _headers…),
`CONSTRAINTS` = the STEP 1 strict scope + framework-native mechanism rule (no `.htaccess`
on Next/Astro) + the severity guide. Three blind challengers ask, per patch: will it ACHIEVE
the hardening goal / could it BREAK the site (over-broad CSP, redirect loop) / is a simpler
fix better. This main loop RE-THINKS every aspect a BLOCKER lands (a named bundle change, or
`[deferred <date>]`) and re-challenges once if the bundle materially changed. Advisory — it
sits BEFORE (never replaces) the STEP 3 confirmation; carry its CHALLENGE SUMMARY into that gate.
---
## STEP 3 — Apply fixes (MODE=fix only)
Skip this step if MODE=audit.
@@ -534,6 +549,11 @@ If MODE=fix and `.claude/audits/HARDEN.md` ends with `READY TO APPLY — awaitin
- .htaccess (3 fixes : HTTP→HTTPS redirect, HSTS, 404 page)
- next.config.js (2 fixes : CSP header, X-Frame-Options)
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)
Options :
A) Apply all
B) Review each diff before applying
skills/init-project/SKILL.md
+15
View File
@@ -155,12 +155,27 @@ implemented on a `feature/*` branch off `develop` (STEP 8).
Invoke `superpowers:writing-plans` with BRIEF + skeleton.
Granular tasks (2-5 min each), exact file paths, TDD: tests before code.
## STEP 6b — CHALLENGE THE PLAN (before the gate)
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
paths, `CONSTRAINTS` = the STEP 4-validated architecture + founding decisions.
Three blind challengers (correctness / robustness / simplicity) attack it; the main
loop RE-THINKS every aspect a BLOCKER lands (a named plan change, or `[deferred]`),
re-challenges once if the plan materially changed, and feeds the REVISED plan + a
CHALLENGE SUMMARY into STEP 7. Advisory — the human remains the decider.
## STEP 7 — VALIDATION GATE #2 ★ MANDATORY STOP
```
INIT PROJECT — IMPLEMENTATION PLAN
SKELETON: ✅ build passes
FEATURES: <N> → <M> tasks
<numbered task list with paths>
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)
Approve and start? (yes / request changes)
```
Changes → back to STEP 6. Approved → continue.
skills/onboard/SKILL.md
+21
View File
@@ -869,6 +869,22 @@ Vérifier que les 4 fichiers `.claude/audits/ONBOARD_REPORT.md`, `.claude/audits
---
## STEP 7b — CHALLENGE THE PROPOSALS (before the human gate)
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` =
`.claude/audits/AUDIT_PROPOSALS.md`, `KIND` = `proposals`, `SCOPE` = the audited
project paths (the `audit_stack` coverage), `CONSTRAINTS` = the STEP 1 archetype
profile + the STEP 3 interview constraints (stade, légal, budget perf). Three
blind challengers ask whether these are the RIGHT priorities and what the audit
under-rated; the main loop RE-THINKS every aspect a BLOCKER lands (a named
proposals change re-written into `AUDIT_PROPOSALS.md`, or `[deferred <date>]`)
and re-challenges once if the file materially changed. Feed the REVISED
proposals + a CHALLENGE SUMMARY into STEP 8. Advisory — the human remains the
decider.
---
## STEP 8 — VALIDATION GATE ★ MANDATORY STOP
Afficher à l'utilisateur :
@@ -893,6 +909,11 @@ TOP 5 PRIORITÉS :
4. [P1 Haute] <titre>
5. [P2 Moyenne] <titre>
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)
Prochaine étape : générer .claude/tasks/TODO.md depuis .claude/audits/AUDIT_PROPOSALS.md approuvé.
Options :
skills/seo/SKILL.md
+18
View File
@@ -447,6 +447,19 @@ applies your bundle in STEP 1.5 and merges the reports.
"""
```
## STEP 1b — CHALLENGE THE FIX BUNDLE (advisory, before apply)
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
`$HOME/.claude/lib/challenge-plan.md` with `PLAN` = that file, `KIND` = `fix-bundle`,
`SCOPE` = the target site files the items touch, `CONSTRAINTS` = the STEP 0 file-ownership
matrix + shared-file edit discipline + confirmed Canonical NAP + intervention mode. Three
blind challengers ask, per item: will it ACHIEVE its goal / could it BREAK or regress the
page / is a simpler (or no) fix better. This main loop RE-THINKS every aspect a BLOCKER
lands (a named bundle change, or `[deferred <date>]`) and re-challenges once if the bundle
materially changed. Advisory — it sits BEFORE (never replaces) the STEP 1.5 GATED approval;
carry its CHALLENGE SUMMARY into that gate.
## STEP 1.5 — Apply fix bundles (from THIS main loop, at L1)
Both analyzers returned an envelope containing a `## FIX BUNDLE` section
@@ -493,6 +506,11 @@ Collect every GATED item from BOTH bundles and present ONE gate:
SEO/GEO — gated changes need approval (visible / structural):
D1 <change> — impact: <visible change> [seo]
G5.1 <change> — impact: <visible change> [geo]
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)
Approve all / select (ids) / skip all?
```
skills/ship-feature/SKILL.md
+18
View File
@@ -115,6 +115,19 @@ Invoke `superpowers:writing-plans` with the validated design AND the 0d digest:
must be consistent with the in-force constraints; where a task implements or affects one,
note the ID inline. Break design into tasks (2-5 min each). Each task: exact file paths, full code, verification steps.
## STEP 2b — CHALLENGE THE PLAN (adversarial, before the gate)
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`
- `SCOPE` = the files/dirs the plan touches
- `CONSTRAINTS` = the STEP 1 validated design's decided trade-offs / rejected options
Three blind `plan-challenger` subagents (correctness / robustness / simplicity)
attack it in parallel on the big model; the main loop RE-THINKS every aspect a
BLOCKER lands (a named plan change, or `[deferred <date>]`), re-challenges once if
the plan materially changed, and feeds the REVISED plan + a CHALLENGE SUMMARY into
STEP 3. Advisory — the human remains the decider.
## STEP 3 — VALIDATION GATE ★ MANDATORY STOP
```
SHIP FEATURE — VALIDATION GATE
@@ -127,6 +140,11 @@ RELATED MEMORY — disposition CLAIMED by this plan (review each):
- BLK-009 [already seen] — <how avoided / why N-A>
Review the claims above — flag any item the plan does NOT actually honor.
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)
Approve and execute? (yes / request changes)
```
This block EXPOSES each in-force item with the plan's CLAIMED disposition, for human
skills/web-validate/SKILL.md
+21
View File
@@ -251,6 +251,22 @@ grep -c '^### \[Critique\]' .claude/audits/VALIDATE.md
---
## STEP 2b — CHALLENGE THE FIX BUNDLE (MODE=fix only, advisory)
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
`$HOME/.claude/lib/challenge-plan.md` with `PLAN` = that file, `KIND` = `fix-bundle`,
`SCOPE` = the HTML/CSS files each fix touches, `CONSTRAINTS` = the STEP 1 strict scope (W3C
validity + WCAG 2.1) + the conservative auto-fix rule (structural/syntactic only, content →
§6) + the shared-template discipline (targeted Edit, never Write — templates carry /seo +
/geo content). Three blind challengers ask, per fix: will it ACHIEVE conformance / could it
BREAK rendering or regress another SC / is a simpler fix better. This main loop RE-THINKS
every aspect a BLOCKER lands (a named bundle change, or `[deferred <date>]`) and re-challenges
once if the bundle materially changed. Advisory — it sits BEFORE (never replaces) the STEP 3
confirmation; carry its CHALLENGE SUMMARY into that gate.
---
## STEP 3 — Apply fixes (MODE=fix only)
Skip this step if `MODE=audit`.
@@ -271,6 +287,11 @@ Files to modify (N) :
Critical : X | Haute : Y | Moyenne : Z | Basse : W
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)
Options :
A) Apply all
B) Review each diff before applying