24 changed files with 852 additions and 31 deletions

No files matched your search

+11
View File
@@ -107,8 +107,19 @@
- CLAUDE.global.md § Workflow + lib/effort-shift.md § Advisor: "sub-agents do not" call the advisor is prose only; sub-agents get the advisor tool listed and the harness prompt tells them to call it (seen live in this run's challengers and gates), each call forwarding that agent's whole transcript to Fable outside the router's caps (cost, BLK-030 credits). Fix direction: a mechanical scope (advisorModel for the main session only, if the CLI allows it), else accept. Severity: low. Discovered while: /feat advisor-doctrine plan challenge and security gate. Not fixed.
SUPERSEDED 2026-11-17 (6ef3069, /feat advisor-call-points): plan-challenger, verifier, security-auditor now may call it at most once before the verdict; other sub-agents do not. Residual kept: still prose only, and the harness prompt asks sub-agents for "at least once before … and once before declaring done" (a verifier made 2 calls on 2026-11-16), against "at most one call". Severity: low.
- agents/security-auditor.md:166 (advisor bullet) — "overrides the STEP 2 mapping for that finding only" has no direction: read alone, an advisor "raise" into a lower STEP 3 class could take a semgrep HIGH out of BLOCK(n); only the closing "never removes, lowers or waives" stops it. Fix direction: "overrides it upward only". Severity: low. Discovered while: /feat advisor-call-points security gate r5 (advisor-sourced LOW). Not fixed.
FIXED 2026-11-17 (24354d9, /ship-feature advisor-points-b2): a raise applies only when its class's severity is higher than the finding's own; a raise that does not apply, or matches no class, changes nothing (no tag, no PROOF count); "Advice never removes, lowers or waives" kept.
- agents/verifier.md + agents/security-auditor.md advisor bullets — not scoped to dispatch (analyzer's is, 58a5273); lib/verify-secure-loop.md:54,:96 still allow "or load agents/<x>.md" inline, where the gate's own call would be a main-loop call and void the stuck-call unit "no main-loop advisor call since GATE 0 first ran". No skill takes the inline path today. Fix direction: "when dispatched" in both bullets. Severity: low. Discovered while: /feat advisor-points-b1 re-challenge. Not fixed.
FIXED 2026-11-17 (24354d9): verifier, security-auditor and plan-challenger read "Advisor, when dispatched as a sub-agent". Residual kept: lib/verify-secure-loop.md:57-58, :106-107 still offer "or load agents/<x>.md" inline (unused today).
- agents/plan-challenger.md ORCHESTRATOR PROTOCOL (~:111-112, :133-135) — mirror of lib/challenge-plan.md lacks the main-loop "Advisor first" step and the CHALLENGE SUMMARY `Advisor:` row (58a5273); the 12 skills' own summary templates also lack the row (lib rule says append it anyway). Fix direction: patch the mirror, optionally add the row to the templates. Severity: low. Discovered while: /feat advisor-points-b1 re-challenge. Not fixed.
FIXED 2026-11-17 (24354d9): the mirror gains ADVISOR FIRST (pointer to the lib, its guards) and the `Advisor:` row. Residual kept: the 12 skills' own CHALLENGE SUMMARY templates still lack the row.
<!-- /ship-feature advisor-points-b2 2026-11-17 (f48343e, 24354d9, 6022b9d): review residuals, not fixed in the run -->
- skills/tour/SKILL.md STEP 0b item 2 — in fan-out the end-of-run advisor call sees only the runners' one-line rows (no diff, no report section), and a `RUNNER FAILED` row can hide fixes already committed, so "when any row reports a fix" can skip the call. Fix direction: read each REPORT's new section (or `git -C <p> diff --stat develop..<branch>`) before the call. Severity: low. Discovered while: /ship-feature advisor-points-b2 STEP 6 review.
- lib/effort-shift.md § Advisor item 3 + lib/verify-secure-loop.md stuck unit — after a fix the end call drives, the re-run gates find a main-loop call "since GATE 0 first ran", so the stuck call is already spent on that re-gate; the budget is plausible but unstated. Wording: "the six flows that run the gates" unnamed; "a later proposal" fits finish flows only; in feat/bugfix the doc and memory commits after the call always make "predates the newer commits" true; item 3 and the CHANGELOG say "the end step" of feat and bugfix, where the call sits at their commit step (STEP 5 / STEP 6), before doc sync and capitalize (the skill lines are placed right). Severity: low. Discovered while: /ship-feature advisor-points-b2 SDD final review and STEP 6 review.
- skills/release-candidate/SKILL.md STEP 4 — the end call's `route(phase="reflect")` has no route back, so STEP 5 (finish and tag) runs at reflect against an apply/low row. Severity: low (cost). Discovered while: same.
- skills/{feat,bugfix,audit-delta,tour}/SKILL.md summary templates — FEAT/BUGFIX/AUDIT-DELTA/TOUR COMPLETE have no `Advisor:` field (only the prose asks for the line), and the end call has no "not called (absent | error | skipped)" wording like the CHALLENGE SUMMARY row. Severity: low. Discovered while: same.
- skills/{ship-feature,init-project}/SKILL.md — the end call runs after STEP 6/10 code review, capitalize and doc sync; a fix it drives re-runs the gates but neither the code review nor the doc sync. Severity: low. Discovered while: same.
- agents/security-auditor.md STEP 5 dedup keys on (file:line, rule/check): an advisor-added `advisor:<class>` finding on a semgrep line counts twice in BLOCK(n) (pre-existing); "An added or applied finding" reads oddly; PROOF suffix for n=0 unspecified. Severity: low. Discovered while: same.
<!-- /hotfix doctor-skilloverrides-residue 2026-11-14: non-blocking gate finding, not BDR-125 -->
- doctor.sh `warn`/`pass`/`fail` print through `echo -e`: jq's `\uXXXX` escapes in the residue diff (:153) come back as raw control bytes (ESC sequences) on the terminal. Source = the user's own tracked settings.json (no trust boundary). Fix direction: `printf '%s\n'` in the shared helpers. Severity: low. Discovered while: /hotfix doctor-skilloverrides-residue security gate. Not fixed.
+1
View File
@@ -1611,3 +1611,4 @@ Supersedes [[BDR-030]].
- **Status (2026-11-17)**: accepted, completed: pins opus beebfe2 (gate row 'fixed at spawn' passes a pinned sub-agent), doctrine c3507ea (main loop calls advisor, sub-agents do not, absent advisor -> proceed, advice waives no gate)
- **Status (2026-11-17)**: accepted, amended 6ef3069: main loop named call points (before a skill's plan, once per verify-secure run at first gate loop failing twice, before merge); plan-challenger/verifier/security-auditor at most one call before verdict, advice add-only (security: STEP 3 class severity, no class -> REPORTED LOW); other sub-agents do not
- **Status (2026-11-17)**: accepted, amended 58a5273: plan point in lib/challenge-plan.md (on written plan before challengers, once per skill run, Advisor: row in CHALLENGE SUMMARY, no attribution in plan); stuck lines inline in verify-secure-loop (main-loop calls only since GATE 0); dispatched analyzer joins; trigger before recommending doctrine/architecture/public-interface change
- **Status (2026-11-17)**: accepted, amended 6022b9d: B2 stuck trigger in 6 gate skills (points to verify-secure-loop); end-of-run call before done/merge in feat, bugfix, ship-feature, init-project, a11y, guardrails, audit-delta+tour (fix applied only), release-candidate STEP 4; own budget; gate flows print diff stat, fix back through gates; verifier/security-auditor/plan-challenger advise only when dispatched; auditor raise upward only; plan-challenger protocol mirror. Commits f48343e 24354d9 6022b9d
+1
View File
@@ -776,3 +776,4 @@ rules:
- Advisor doctrine (c3507ea, docs): CLAUDE.global § Workflow + effort-shift § Advisor: main loop calls Fable advisor (approach, stuck, before done), sub-agents do not (they have tool listed: prose-only, residual), absent → proceed, advice waives no gate/cap/guard. Stale Fable prose → opus (effort-shift, challenge-plan, plan-challenger, tour). BDR-150 change complete: router 24b0f35, pins beebfe2, doctrine c3507ea.
- Advisor call points run A (6ef3069): transcript count showed main loop 2 calls on Opus (409k/680k uncached) vs 18/20 opus sub-agents on Fable (~70k); doctrine now names main-loop points (plan, first gate loop failing twice, merge) + judgment agents once, advice add-only; 2 challenge rounds, gates found block E double count, fixed r5. Runs B, C next.
- Advisor run B1 (58a5273): plan point moved into lib/challenge-plan.md (once per skill run, Advisor: row), stuck lines inline in verify-secure-loop (main-loop calls only), analyzer joins, trigger for doctrine/architecture/public-interface recommendations. 2 challenge rounds (2 BLOCKERs were my own oracle markers), scratch simulation then MET first run; gates sequential, CONFORME + PASS.
- Advisor run B2 (/ship-feature, f48343e 24354d9 6022b9d): stuck line in 6 gate skills, end-of-run call at each flow's end step (9 flows, capitalize-commit untouched), 3 judgment agents dispatch-scoped, auditor raise upward only; plan r3 after 3 lenses + confirm; STEP 6 review fix restated fix path in skills (LRN-297); gates green first pass and after fix. Merge waits for user go.
+12
View File
@@ -2140,3 +2140,15 @@ Rule: when editing a doctrine file under structure locks, grep the test's lock s
- **Context**: 2026-11-17 advisor runs A and B1. Markers broke three times: phrase wrapped across two lines (grep per line, count 0); awk `/X/{a=NR}` kept LAST match after a later block mentioned "X"; census extractor read word after `§ Label` as part of heading ("§ Workflow names"). Each would have cost a floor loop. Also `Nb.` criterion label absorbed by gates.sh (LRN-284). Simulation of B1 (apply.py on mktemp copy) passed 5/5 CHECKs; executor then got MET first run.
- **Apply**: any /feat or /bugfix whose oracles are grep/awk markers on prose: write blocks to files, applier script with exact-once asserts, run CHECKs with `cd` swapped to the scratch copy; anchor awk on line start (`/^\*\*Label/`); keep each marker and each `§ Label` citation on one line followed by `)`/`;`. Give the executor the applier.
- **Reference**: lib/gates.sh, lib/tests/doctrine-citers.test.sh, .claude/tasks/plans/2026-11-17-advisor-points-b1-1500.md, LRN-284
## LRN-297 — Single-source doctrine holds only where acting step loads cited lib (2026-11-17)
- **Pattern**: rule kept once in lib + skills citing it works only if step that acts loads that lib. Citation alone not read at act time.
- **Context**: 2026-11-17 run B2 STEP 6, 2 reviewers (sonnet SDD final, opus craft). Stuck lines fine: gate step loads `lib/verify-secure-loop.md`. End-of-run lines cited `lib/effort-shift.md` § Advisor, loaded only via ROUTING line, never at end step → diff stat + fix path (item 3) unseen; 3 of 9 lines already restated own path, 6 silent read as "report only". Parked ruling withdrawn, clause restated at 6 sites (6022b9d).
- **Apply**: before keeping a procedure only in a lib, check acting step reads that lib (include it loads, not ROUTING line); else one clause at site, lib keeps full rule. Uneven restatement across sibling sites = misread by contrast.
- **Reference**: lib/effort-shift.md § Advisor item 3, lib/verify-secure-loop.md, BDR-150, LRN-296
## LRN-298 — Marker oracles prove presence, not placement semantics (2026-11-17)
- **Pattern**: marker oracles prove text present at position, not placement semantics. Need read of flow's own sequence: who executes site, when run is declared done, can condition be false.
- **Context**: 2026-11-17 run B2: scratch-clone simulation 15/15 MET, yet challengers found end call after FEAT COMPLETE (done already printed), tour runners (sub-agents) execute STEP 3 holding main-loop call, skip "fixed or committed anything" always true (tour commits report each run). Fixed in plan r2/r3 before dispatch.
- **Apply**: anchor position oracles on flow's done/merge moment (summary or finish line), not nearby heading; per site list executor (main loop vs runner/sub-agent) and falsifiable condition. Non-idempotent applier fix after commit: delta group from HEAD + byte-compare with fresh apply from base (review1 == fresh).
- **Reference**: docs plan 2026-11-17-advisor-points-b2 (purged at finish, git keeps), LRN-296, LRN-284
+3 -1
View File
@@ -6,7 +6,9 @@ Done history before 2026-10-08 removed 2026-10-23 (git keeps it: `git log -p --
### Advisor call points (user 2026-11-17: "oui 1 et 2, et le 3 aussi"; amends BDR-150)
- [x] Run A DONE 6ef3069, merged fc2d84d (docs 09277f5, audits c1a0c32, memory 78a6942) /feat feature/advisor-call-points: CLAUDE.global § Workflow + lib/effort-shift.md § Advisor + plan-challenger/verifier/security-auditor one-call rule (contract .claude/tasks/contracts/2026-11-17-advisor-call-points-1130.md)
- [x] Run B1 DONE 58a5273, merged eb1f594 (docs 47e5ee8, audits 9033b4a, memory d55f491) /feat feature/advisor-points-b1 (user 2026-11-17 "oui a, b et c"): (a) main-loop plan point in lib/challenge-plan.md (before first dispatch), (b) analyzer joins judgment agents (CLAUDE.global, effort-shift, agents/analyzer.md), (c) trigger "before recommending a change to the doctrine, the architecture or a public interface", stuck call lines in lib/verify-secure-loop.md (contract .claude/tasks/contracts/2026-11-17-advisor-points-b1-1500.md)
- [ ] Run B2 (10 files, > /feat cap: /ship-feature or split, ask the user): stuck trigger line in the gate bullets of the 6 skills that restate the verify-secure loop (feat, bugfix, ship-feature, init-project, a11y, guardrails); merge point as ONE line in lib/capitalize-commit.md (shared tail of feat, bugfix, hotfix, ship-feature, init-project, audit-delta, tour) + skills/release-candidate STEP 4; agents/security-auditor.md severity applies only when higher + "Advice never removes…"; agents/verifier.md + agents/security-auditor.md advisor bullets scoped to dispatch; agents/plan-challenger.md ORCHESTRATOR PROTOCOL mirror (Advisor first + `Advisor:` row). Low: lib/effort-shift.md block I renders as part of item 3 (needs a blank line); the 12 skills send their reflect route with the challenger dispatch, after the advisor call now. Plan notes: simulate CHECKs on a scratch copy (LRN-296); no `Nb.` labels (LRN-284). Start in a fresh session (main-loop advisor calls here cost 290k-380k tokens each).
- [x] Run B2 DONE f48343e + 24354d9 + 6022b9d on feature/advisor-points-b2 (/ship-feature, user 2026-11-17; merge on the user's go): stuck line in the 6 gate skills; end-of-run call at each flow's own end step (feat, bugfix, ship-feature, init-project, a11y, guardrails, audit-delta + tour when a fix was applied, release-candidate STEP 4), lib/capitalize-commit.md untouched; verifier/security-auditor/plan-challenger advise only when dispatched; auditor raise upward only; plan-challenger protocol mirror; effort-shift item 3 + blank line (contract .claude/tasks/contracts/2026-11-17-advisor-points-b2-1634.md; BUGS-FOUND :109-111 fixed, B2 review residuals logged)
- [ ] The 12 skills send their reflect route with the challenger dispatch, after the advisor call now (low; moved out of B2 by the user 2026-11-17)
- [ ] Decide: feat/bugfix end-of-run advisor call has no skip (audit-delta/tour skip when no fix was applied); nominal /feat or /bugfix = 2 main-loop advisor calls (plan + end), ~0.6-1.4M uncached tokens late in a session; ship-feature STEP 6 opus review and the end call review the same branch back to back (B2 STEP 6 review, user decision)
- [x] After B1 DONE (doc commit + BDR-150 status + LRN-296): README/USAGE/CHANGELOG say "before writing a skill's plan (/feat, /bugfix, /ship-feature)" and list 3 agents → doc-sync; BDR-150 status line
- [ ] Run C /feat: advisor usage section in /memory-feedback (main loop vs sub-agents, model served, input tokens; dedupe usage rows by message.id, model from the `advisor_message` iteration)
- [x] Stale citers after A: README/USAGE/CHANGELOG patched, BUGS-FOUND residual superseded + LOW logged, BDR-150 status, LRN-295 (LRN-294 kept: its lesson holds)
@@ -0,0 +1,127 @@
# CONTRACT — advisor-points-b2
- date: 2026-11-17 | flow: ship-feature | branch: feature/advisor-points-b2 (off develop, created at STEP 4)
- status: active
## REQUEST (verbatim — IMMUTABLE)
Run B2 of the advisor call points (follow-up to BDR-150, runs A 6ef3069 and B1 58a5273, both merged into develop).
Read first:
- .claude/tasks/TODO.md, the "Advisor call points" block: the "Run B2" line holds the full scope
- lib/effort-shift.md § Advisor (the source of truth for the call points)
- .claude/audits/BUGS-FOUND.md, the advisor entries (block E LOW, verifier/security-auditor not limited to dispatch, plan-challenger mirror)
- LRN-295, LRN-296, LRN-284; the B1 contract and plan as a model: .claude/tasks/{contracts,plans}/2026-11-17-advisor-points-b1-1500.md
Scope (10 files):
1. A "stuck" trigger line in the gate step of the 6 skills that restate the verify-secure loop: feat, bugfix, ship-feature, init-project, a11y, guardrails. It points to lib/verify-secure-loop.md and lib/effort-shift.md § Advisor (second failure of a gate loop, main-loop calls only since GATE 0, the advice never goes into an executor's brief).
2. Merge point: ONE line in lib/capitalize-commit.md (the shared tail of feat, bugfix, hotfix, ship-feature, init-project, audit-delta, tour), plus skills/release-candidate STEP 4.
3. agents/security-auditor.md: the class severity applies only when it is higher, and "Advice never removes, lowers or waives…".
4. agents/verifier.md and agents/security-auditor.md: advisor rule limited to "when dispatched".
5. agents/plan-challenger.md: the ORCHESTRATOR PROTOCOL mirror gains the "Advisor first" step and the `Advisor:` row.
Optional, low: blank line before block I in effort-shift § Advisor (it renders as part of item 3).
Over /feat's 5-file cap: ask me first whether this goes through /ship-feature or through two /feat runs (skills, then libs + agents).
Method (lessons from A and B1):
- Apply the advisor rules you're editing: advisor on the written plan before the challengers, before the merge.
- Write each text into a file, apply the edit with an exact-match script on a scratch copy (mktemp, never rm -rf through a variable), and run every contract CHECK on it before dispatch (LRN-296).
- Every marker and every `§ Label` citation stays on a single line, followed by `)` or `;`. Never label a criterion `Nb.` (LRN-284). Use GATES_TIMEOUT=400 for the full make test.
- Gates in order: GATE 0, then the verifier, then security only after CONFORME. Never in parallel.
- At capitalize: call memory_pending first; add a BDR-150 status line; update the BUGS-FOUND entries you fixed.
- Docs: README/USAGE/CHANGELOG [Unreleased], the "Advisor doctrine" bullet.
## CLARIFICATIONS
- Q: route (11 files, 12 with the optional effort-shift line; two /feat runs hold at most 10) / A: /ship-feature, one run [gated 2026-11-17]
- Q: which flows the end-of-run advisor line applies to / A: code flows, no hotfix: feat, bugfix, ship-feature, init-project, audit-delta, tour; hotfix and the memory-only flows (capitalize, prune-memory, memory-feedback, deploy) excluded [gated 2026-11-17]
- Q: plugin gate SET dev / A: no, profile full kept [gated 2026-11-17]
- Q: merge point host (capitalize-commit is read whole only by feat, bugfix, ship-feature, init-project, plus hotfix, /capitalize, commit-changer; audit-delta and tour reach only § WRITE on an accepted offer) / A: each flow's own end step; lib/capitalize-commit.md stays untouched [gated 2026-11-17]
- Q: a11y and guardrails in the merge point / A: yes, included [gated 2026-11-17]
- Q: agents/plan-challenger.md advisor bullet scoped "when dispatched" too / A: yes [gated 2026-11-17]
- Q: TODO low item "12 skills send their reflect route with the challenger dispatch" / A: out of B2, own TODO line [gated 2026-11-17]
- Q: plan r3 deviations from the chat design (feat/bugfix end call before the COMPLETE summaries; audit-delta/tour call only when a fix was applied; route lines in ship-feature, init-project, release-candidate; `Advisor:` line in summaries; tour runner and STEP 0b wiring; effort-shift item 3 carries budget, skips and gate-flow fix path) / A: approved at the STEP 3 validation gate [gated 2026-11-17]
## ACCEPTANCE CRITERIA
1. Each of the 6 verify-secure skills (feat, bugfix, ship-feature, init-project, a11y, guardrails) carries, in its gate step, a stuck trigger citing `lib/verify-secure-loop.md` and `lib/effort-shift.md` § Advisor: second failure of a gate loop, main-loop calls only since GATE 0 first ran, the advice never enters an executor brief.
2. The merge point (effort-shift § Advisor item 3) is wired for the flows of CLARIFICATIONS and in skills/release-candidate STEP 4, citing `lib/effort-shift.md` § Advisor; hotfix, commit-changer and the memory-only flows gain no call.
3. agents/security-auditor.md advisor bullet: a STEP 3 class severity replaces the STEP 2 one only when higher; the sentence that advice never removes, lowers or waives a finding stays.
4. agents/verifier.md and agents/security-auditor.md advisor bullets apply when dispatched as a sub-agent.
5. agents/plan-challenger.md ORCHESTRATOR PROTOCOL mirrors lib/challenge-plan.md: the main-loop "Advisor first" step before the dispatch and the CHALLENGE SUMMARY `Advisor:` row.
6. lib/effort-shift.md § Advisor: a blank line separates item 3 from the "Inside a skill run" paragraph.
CHECK: cd /home/bchanot/Documents/claude && awk '/^Inside a skill run, the points above/{print (prev=="" ? "BLANK-BEFORE-I" : "NO-BLANK")} {prev=$0}' lib/effort-shift.md
EXPECT: BLANK-BEFORE-I
EVIDENCE: MET exit=0 marker-found :: BLANK-BEFORE-I
7. Citation census green (fast oracle).
CHECK: cd /home/bchanot/Documents/claude && bash lib/tests/doctrine-citers.test.sh </dev/null 2>&1 | tail -1
EXPECT: FAIL=0
EVIDENCE: MET exit=0 marker-found :: PASS=23 FAIL=0
8. Full make test green (run gates.sh with GATES_TIMEOUT=400).
CHECK: cd /home/bchanot/Documents/claude && PATH=$HOME/.bun/bin:$PATH make test </dev/null 2>&1 | tail -1
EXPECT: all suites green
EVIDENCE: MET exit=0 marker-found :: all suites green
9. Every test-locked phrase in the touched files stays on one unbroken line; touched lines ≤ 80 columns; no wording changed outside the planned blocks (manual).
10. [gated 2026-11-17] Stuck paragraph in each gate skill, citing the lib and § Advisor.
CHECK: cd /home/bchanot/Documents/claude && for s in feat bugfix ship-feature init-project a11y guardrails; do f=skills/$s/SKILL.md; printf '%s:%s/%s ' "$s" "$(/usr/bin/grep -c 'Stuck: a gate loop fails twice with no main-loop advisor call since GATE 0' "$f")" "$(/usr/bin/grep -cF '(`lib/effort-shift.md` § Advisor); the answer never enters an executor brief.' "$f")"; done; echo
EXPECT: feat:1/1 bugfix:1/1 ship-feature:1/1 init-project:1/1 a11y:1/1 guardrails:1/1
EVIDENCE: MET exit=0 marker-found :: feat:1/1 bugfix:1/1 ship-feature:1/1 init-project:1/1 a11y:1/1 guardrails:1/1
11. [gated 2026-11-17] The stuck paragraph sits in the gate step (after a GATE 2 line, no heading between).
CHECK: cd /home/bchanot/Documents/claude && for s in feat bugfix ship-feature init-project a11y guardrails; do awk -v s="$s" '/GATE 2/{g=NR} /^## /{h=NR} /Stuck: a gate loop fails twice/{m=NR; ok=(g>h)} END{printf "%s:%s ", s, (m&&ok)?"in-gate":"OUT"}' "skills/$s/SKILL.md"; done; echo
EXPECT: feat:in-gate bugfix:in-gate ship-feature:in-gate init-project:in-gate a11y:in-gate guardrails:in-gate
EVIDENCE: MET exit=0 marker-found :: feat:in-gate bugfix:in-gate ship-feature:in-gate init-project:in-gate a11y:in-gate guardrails:in-gate
12. [gated 2026-11-17] The end-of-run marker is in exactly the 9 flows (no hotfix, lib, agent or memory-only flow).
CHECK: cd /home/bchanot/Documents/claude && echo "[$(/usr/bin/grep -rlF 'end-of-run advisor call (`lib/effort-shift.md` § Advisor)' skills lib agents | LC_ALL=C sort | tr '\n' ' ')]"
EXPECT: [skills/a11y/SKILL.md skills/audit-delta/SKILL.md skills/bugfix/SKILL.md skills/feat/SKILL.md skills/guardrails/SKILL.md skills/init-project/SKILL.md skills/release-candidate/SKILL.md skills/ship-feature/SKILL.md skills/tour/SKILL.md ]
EVIDENCE: MET exit=0 marker-found :: [skills/a11y/SKILL.md skills/audit-delta/SKILL.md skills/bugfix/SKILL.md skills/feat/SKILL.md skills/guardrails/SKILL.md skills/init-project…
13. [gated 2026-11-17] Each end marker occurs once, before its flow's done or merge moment.
CHECK: cd /home/bchanot/Documents/claude && for t in 'feat|^## STEP 5 |^FEAT COMPLETE' 'bugfix|^## STEP 6 |BUGFIX COMPLETE' 'ship-feature|^## STEP 9 |finish # feature' 'init-project|^## STEP 11 |finish # feature' 'a11y|^## STEP 10:|^2[.] .mcp__model-router' 'guardrails|^## STEP 12:|^2[.] .mcp__model-router' 'audit-delta|^## STEP 4 |AUDIT-DELTA COMPLETE' 'tour|^Checks: pytest PASS|^TOUR COMPLETE' 'release-candidate|^### STEP 4 |^AskUserQuestion:'; do IFS='|' read -r s a b <<<"$t"; awk -v s="$s" -v a="$a" -v b="$b" '!sa && $0~a {sa=NR} index($0,"end-of-run advisor call (`lib/effort-shift.md` § Advisor)"){n++; m=NR} sa && !sb && NR>sa && $0~b {sb=NR} END{printf "%s:%s ", s, (n==1 && sa<m && m<sb)?"ok":"BAD"}' "skills/$s/SKILL.md"; done; echo
EXPECT: feat:ok bugfix:ok ship-feature:ok init-project:ok a11y:ok guardrails:ok audit-delta:ok tour:ok release-candidate:ok
EVIDENCE: MET exit=0 marker-found :: feat:ok bugfix:ok ship-feature:ok init-project:ok a11y:ok guardrails:ok audit-delta:ok tour:ok release-candidate:ok
14. [gated 2026-11-17] verifier, security-auditor and plan-challenger advise only when dispatched.
CHECK: cd /home/bchanot/Documents/claude && for a in verifier security-auditor plan-challenger; do printf '%s:%s/%s ' "$a" "$(/usr/bin/grep -c '^- Advisor, when dispatched as a sub-agent: at most one call' "agents/$a.md")" "$(/usr/bin/grep -c 'Advisor (when listed)' "agents/$a.md")"; done; echo
EXPECT: verifier:1/0 security-auditor:1/0 plan-challenger:1/0
EVIDENCE: MET exit=0 marker-found :: verifier:1/0 security-auditor:1/0 plan-challenger:1/0
15. [gated 2026-11-17] security-auditor: a raise applies only upward, a no-op raise is neither tagged nor counted, advice never removes, lowers or waives.
CHECK: cd /home/bchanot/Documents/claude && echo "[$(/usr/bin/grep -c 'A raise applies only when its class.s severity' agents/security-auditor.md)/$(/usr/bin/grep -c 'changes nothing: no tag,' agents/security-auditor.md)/$(/usr/bin/grep -c '^ Advice never removes, lowers or waives a finding from semgrep' agents/security-auditor.md)/$(/usr/bin/grep -c 'overrides the STEP 2 mapping' agents/security-auditor.md)/$(/usr/bin/grep -c 'It never removes' agents/security-auditor.md)]"
EXPECT: [1/1/1/0/0]
EVIDENCE: MET exit=0 marker-found :: [1/1/1/0/0]
16. [gated 2026-11-17] plan-challenger ORCHESTRATOR PROTOCOL: ADVISOR FIRST (pointer to the lib, its guards) before the dispatch bullet, `Advisor:` row in ADVISORY.
CHECK: cd /home/bchanot/Documents/claude && echo "[$(/usr/bin/grep -c '^- ADVISOR FIRST (main loop): per `lib/challenge-plan.md`' agents/plan-challenger.md)/$(/usr/bin/grep -c 'with no main-loop advisor call since the skill run started; absent or' agents/plan-challenger.md)/$(/usr/bin/grep -cF 'an `Advisor:` row) feed the' agents/plan-challenger.md)/$(awk '/^## ORCHESTRATOR PROTOCOL/{p=NR} /^- ADVISOR FIRST/{a=NR} /^- Dispatch THREE fresh challengers/{d=NR} END{print (p && p<a && a<d)}' agents/plan-challenger.md)]"
EXPECT: [1/1/1/1]
EVIDENCE: MET exit=0 marker-found :: [1/1/1/1]
17. [gated 2026-11-17] effort-shift § Advisor item 3 keeps its generic trigger, names its sites, its own budget, the audit-delta/tour skip and the gate-flow-only fix path; § Advisor still names no STEP.
CHECK: cd /home/bchanot/Documents/claude && sec() { sed -n '/^## Advisor/,/^## Never/p' lib/effort-shift.md; }; echo "[$(sec | /usr/bin/grep -c 'done. Wired at the end step of feat, bugfix,')/$(sec | /usr/bin/grep -c 'release gate of release-candidate: one end-of-run call per skill')/$(sec | /usr/bin/grep -c 'never skipped for an earlier plan or stuck call')/$(sec | /usr/bin/grep -c 'and tour skip it when the run applied no fix')/$(sec | /usr/bin/grep -c 'the answer is reported only and a fix it calls for is a new run')/$(sec | /usr/bin/grep -c STEP)]"
EXPECT: [1/1/1/1/1/0]
EVIDENCE: MET exit=0 marker-found :: [1/1/1/1/1/0]
18. [gated 2026-11-17] Every added line in the 13 files is at most 80 columns.
CHECK: cd /home/bchanot/Documents/claude && n=$(/usr/bin/git diff develop -U0 -- skills/feat/SKILL.md skills/bugfix/SKILL.md skills/ship-feature/SKILL.md skills/init-project/SKILL.md skills/a11y/SKILL.md skills/guardrails/SKILL.md skills/audit-delta/SKILL.md skills/tour/SKILL.md skills/release-candidate/SKILL.md agents/verifier.md agents/security-auditor.md agents/plan-challenger.md lib/effort-shift.md | /usr/bin/grep '^+[^+]' | cut -c2- | LC_ALL=C.UTF-8 awk 'length>80' | wc -l); [ "$n" -eq 0 ] && echo WIDTH-OK
EXPECT: WIDTH-OK
EVIDENCE: MET exit=0 marker-found :: WIDTH-OK
19. [gated 2026-11-17] Tour fan-out: the main loop makes the call (STEP 0b list) only when a fix was applied, runners never do.
CHECK: cd /home/bchanot/Documents/claude && f=skills/tour/SKILL.md; echo "[$(/usr/bin/grep -c 'when any row reports a fix, makes the' $f)/$(/usr/bin/grep -c 'STEP 3 end-of-run advisor call; then prints the global summary' $f)/$(/usr/bin/grep -c 'them; never call the advisor. Every rule' $f)/$(/usr/bin/grep -c '^Main loop only, never a runner: when the tour applied any fix' $f)]"
EXPECT: [1/1/1/1]
EVIDENCE: MET exit=0 marker-found :: [1/1/1/1]
20. [gated 2026-11-17] ship-feature and init-project route back to their plan level, release-candidate up to reflect, before the end call.
CHECK: cd /home/bchanot/Documents/claude && echo "[$(/usr/bin/grep -cF 'route(phase="plan")` first (route: end-of-run review).' skills/ship-feature/SKILL.md)/$(/usr/bin/grep -cF 'route(phase="plan")` first (route: end-of-run review).' skills/init-project/SKILL.md)/$(/usr/bin/grep -cF 'route(phase="reflect")` first (route: end-of-run review).' skills/release-candidate/SKILL.md)]"
EXPECT: [1/1/1]
EVIDENCE: MET exit=0 marker-found :: [1/1/1]
21. [gated 2026-11-17] In ship-feature and init-project the stuck paragraph follows the "This …" paragraph it would otherwise split from the gates.
CHECK: cd /home/bchanot/Documents/claude && for t in 'ship-feature|^This replaces the old informal' 'init-project|^This adds the security gate'; do IFS='|' read -r s a <<<"$t"; awk -v s="$s" -v a="$a" '$0~a{t=NR} /Stuck: a gate loop fails twice/{m=NR} END{printf "%s:%s ", s, (t && m>t)?"after-this":"BAD"}' "skills/$s/SKILL.md"; done; echo
EXPECT: ship-feature:after-this init-project:after-this
EVIDENCE: MET exit=0 marker-found :: ship-feature:after-this init-project:after-this
## FILE SCOPE
[gated 2026-11-17] (replaces the STEP 0e seed below) skills/feat/SKILL.md (gate
step, STEP 5 summary), skills/bugfix/SKILL.md (gate step, STEP 6 summary),
skills/{ship-feature,init-project}/SKILL.md (gate step, FINISH head),
skills/{a11y,guardrails}/SKILL.md (Gates item, Commit and hand over item 1),
skills/audit-delta/SKILL.md (STEP 4 head), skills/tour/SKILL.md (runner
prompt, STEP 0b list, before the global summary),
skills/release-candidate/SKILL.md (STEP 4 head), agents/verifier.md and
agents/security-auditor.md (advisor bullet), agents/plan-challenger.md
(advisor bullet, ORCHESTRATOR PROTOCOL), lib/effort-shift.md (§ Advisor item 3
and the blank line before block I); transient, purged by `gitflow finish`:
docs/superpowers/plans/2026-11-17-advisor-points-b2.md and
docs/superpowers/plans/2026-11-17-advisor-points-b2/apply.py; this contract.
`lib/capitalize-commit.md` is not touched. Seed criterion 2's "flows of
CLARIFICATIONS" = the end steps of feat, bugfix, ship-feature, init-project,
a11y, guardrails, audit-delta and tour.
Seed (STEP 0e, superseded): skills/{feat,bugfix,ship-feature,init-project,a11y,guardrails}/SKILL.md (gate step), lib/capitalize-commit.md, skills/release-candidate/SKILL.md (STEP 4), agents/security-auditor.md, agents/verifier.md, agents/plan-challenger.md (advisor bullet, ORCHESTRATOR PROTOCOL), lib/effort-shift.md (§ Advisor blank line). Final list settled at STEP 3.
+1 -1
View File
@@ -20,7 +20,7 @@ The BDR-125 context queue is delivered: phases 0, 0b, 4a, 1, 5, 2 and 4b-4d ship
- **memory commit chokepoint**: `lib/memory.sh check --staged`, run by `lib/memory-commit.sh commit` before every memory commit (rc 6, registry unstaged), also refuses a staged v2 registry whose new `## ` entry does not carry the next free ID: the highest ID seen at any heading level, fenced or not, in HEAD and above the entry in the staged file, plus one, the same reading `add` uses. stderr: `memory: <file>:<line>: new entry <ID> is not the next free ID <PREFIX>-NNN`. A committed ID is never renamed: fix the uncommitted heading and every uncommitted mention of its ID (the `superseded by` line from `add --supersedes`, the journal line), or drop the new entry and re-add it with `memory.sh add`. Skipped when the registry is absent from HEAD, HEAD is v1 (an `upgrade` commit), HEAD has an open code fence, or HEAD has no well-formed `## ` entry. Tests: `lib/tests/memory.test.sh`.
- **model-router write guard fails closed**: when the guard's own check throws or times out, a main-loop Edit, Write or NotebookEdit of a code file outside a skill run is held with `model-router: the write guard failed (<kind>), so this write is held. Enter /hotfix, /feat, /bugfix or /ship-feature, or re-enter the skill you were running, then make this edit.` One log line per session: `model-router: write guard failed (<kind>): main-loop code writes are held until a skill runs`. Sub-agents, skill runs (typed, model-declared phase, typed `/route`) and `.md` / `.txt` files still pass; an error raised by a downstream tool is replayed as before. The guard used to let the write through on its own failure. Tests: `mods/model-router/hooks/register.test.ts` (GUARD: a failing guard …).
- **model-router: Fable leaves auto-routing**: the `best` and `big` tiers default to opus then sonnet (were fable>opus>sonnet and opus>fable>sonnet), so Opus is the strongest model the router routes to and Fable is the advisor (`advisorModel` in settings.json). Fable stays in the model table and first in the fallback rank, so a hand pick of fable ranks above opus. The first-use Change dialog offers opus, sonnet and haiku; the bare `/model` dialog still offers fable, labelled `fable (custom)`. The ask before Fable only fires when a machine override puts fable at the head of `best`: otherwise `/route ask-tier on` answers `(inert: best is not headed by fable)` and `/route show` prints `ask-tier: inert`. An agent on a best or big row keeps its opus frontmatter when Opus is down. The `tiers.best does not lead the fallback chain` log is gone; `routing.json` is unchanged. Tests: `mods/model-router/hooks/register.test.ts`; `lib/tests/effort-routing.test.sh` floors every row on its tier's head. The `/client-handover` skill-runner children and the `lib/model-gate.md` dispatch doctrine pin `model: "opus"` instead of `"fable"` (BDR-150: Fable is the advisor, never a dispatch target), and the model gate lets a sub-agent pass when the route answer says its model is `fixed at spawn`. Tests: `lib/tests/model-routing.test.sh` refuses any fable dispatch pin under agents/, skills/ and lib/; `lib/tests/effort-routing.test.sh` checks the 7 opus/effort="high" client-handover dispatches.
- **Advisor doctrine (`CLAUDE.global.md` § Workflow, `lib/effort-shift.md` § Advisor, `lib/challenge-plan.md`, `lib/verify-secure-loop.md`, `agents/plan-challenger.md`, `agents/verifier.md`, `agents/security-auditor.md`, `agents/analyzer.md`)**: when a stronger model is needed (an approach to settle before building, a stuck problem, a long task before calling it done, a change to recommend to the doctrine, the architecture or a public interface), the main loop calls the advisor tool (Fable, settings `advisorModel`, set by `/advisor`), at least on the written plan before the plan challengers are dispatched (`lib/challenge-plan.md`, every skill that challenges a plan, once per skill run, not before a re-challenge: an answer that lands a real flaw revises the plan file as plain plan text with no advisor attribution, the advice never enters a challenger brief, and the CHALLENGE SUMMARY gains an `Advisor:` row), once per verify-secure run at the first gate loop to fail twice (floor, conformity, security, or a second structural failure, counting main-loop calls since GATE 0 first ran; the advice stays in the main loop and never enters an executor brief; every cap or escalation STOP carries it and says whether it predates the last iteration), and before proposing a merge (`gitflow finish`) or calling a long task done. Inside a skill run these points cover the triggers: no second call for the same recommendation. `plan-challenger`, `verifier`, `security-auditor` and `analyzer` may call it at most once per dispatch, late, before their verdict or report; the analyzer's output rests on the code it read, never on the advice alone, and advice proposing a design or a fix counts only where the brief asks for one. For the three gates advice only adds: the verifier may go back to a contract criterion and tags a resulting NOT-MET `(advisor-prompted)`, never clearing a gap on advice; the challenger never drops or lowers a finding on advice alone; the security-auditor tags an added finding `advisor:<STEP 3 class>` and a raised one `<rule>+advisor`, at that class's severity (an added finding matching no class is REPORTED LOW), and its PROOF ends with `; advisor <n> added/raised`. Executors and every other sub-agent do not call it, even when the tool is listed. Advisor absent or erroring → proceed as written; advice waives no gate, cap or guard and, at a loop cap, feeds the STOP diagnosis. Fable on main comes only from a hand pick, a typed `/route model=fable`, a phase naming `model: fable` or a machine override that puts fable in a tier (BDR-150). Prose that still named Fable as the `audit` row head or a skill-runner pin (`agents/plan-challenger.md`, `lib/challenge-plan.md`, `lib/effort-shift.md`, `skills/tour/SKILL.md`) now says opus.
- **Advisor doctrine (`CLAUDE.global.md` § Workflow, `lib/effort-shift.md` § Advisor, `lib/challenge-plan.md`, `lib/verify-secure-loop.md`, `agents/plan-challenger.md`, `agents/verifier.md`, `agents/security-auditor.md`, `agents/analyzer.md`, `skills/{feat,bugfix,ship-feature,init-project,a11y,guardrails,audit-delta,tour,release-candidate}/SKILL.md`)**: when a stronger model is needed (an approach to settle before building, a stuck problem, a long task before calling it done, a change to recommend to the doctrine, the architecture or a public interface), the main loop calls the advisor tool (Fable, settings `advisorModel`, set by `/advisor`), at least on the written plan before the plan challengers are dispatched (`lib/challenge-plan.md`, every skill that challenges a plan, once per skill run, not before a re-challenge: an answer that lands a real flaw revises the plan file as plain plan text with no advisor attribution, the advice never enters a challenger brief, and the CHALLENGE SUMMARY gains an `Advisor:` row; the ORCHESTRATOR PROTOCOL in `agents/plan-challenger.md` mirrors this advisor-first step and the row), once per verify-secure run at the first gate loop to fail twice (floor, conformity, security, or a second structural failure, counting main-loop calls since GATE 0 first ran; the advice stays in the main loop and never enters an executor brief; every cap or escalation STOP carries it and says whether it predates the last iteration), and before proposing a merge (`gitflow finish`) or calling a long task done: one end-of-run call per skill run, never skipped for an earlier plan or stuck call. It sits at the end step of feat, bugfix, ship-feature, init-project, a11y and guardrails: the main loop first prints the run's diff stat, the answer goes into the reply, summary or finish proposal as an `Advisor:` line, a fix it drives goes back through the gates, and a later proposal reuses the answer and says it predates the newer commits. It also sits at the end of audit-delta and tour when the run applied a fix (tour: main loop only, never a runner), and at release-candidate STEP 4 before the go / hold ask. In those three the answer is reported only: a fix it calls for waits for a new run, and at the release gate it makes hold the recommended answer. The same six gate skills carry a `Stuck:` line that points at the verify-secure rule. Inside a skill run these points cover the triggers: no second call for the same recommendation. `plan-challenger`, `verifier`, `security-auditor` and `analyzer` may call it only when dispatched as a sub-agent, at most once per dispatch, late, before their verdict or report; the analyzer's output rests on the code it read, never on the advice alone, and advice proposing a design or a fix counts only where the brief asks for one. For the three gates advice only adds: the verifier may go back to a contract criterion and tags a resulting NOT-MET `(advisor-prompted)`, never clearing a gap on advice; the challenger never drops or lowers a finding on advice alone; the security-auditor tags an added finding `advisor:<STEP 3 class>` at that class's severity (REPORTED LOW when it matches no class), and tags a raised one `<rule>+advisor` only when the class's severity is higher than the finding's own; a raise that does not apply, or matches no class, changes nothing (no tag, no PROOF count). Its PROOF ends with `; advisor <n> added/raised`. Executors and every other sub-agent do not call it, even when the tool is listed. Advisor absent or erroring → proceed as written; advice waives no gate, cap or guard and, at a loop cap, feeds the STOP diagnosis. Fable on main comes only from a hand pick, a typed `/route model=fable`, a phase naming `model: fable` or a machine override that puts fable in a tier (BDR-150). Prose that still named Fable as the `audit` row head or a skill-runner pin (`agents/plan-challenger.md`, `lib/challenge-plan.md`, `lib/effort-shift.md`, `skills/tour/SKILL.md`) now says opus.
### Removed
- `hooks/design-toolchain-reminder.sh`, its `UserPromptSubmit` entry in `settings.json` (`ctx7-reminder` stays the only one) and its suite `lib/tests/design-toolchain-reminder.test.sh`. Measured 2026-10-31: 59 fires, 0 Reads of `rules/web-building.md`. Design routing stays with the `rules/web-building.md` path rule and the `CLAUDE.global.md` pointer. The fire log `~/.claude/logs/design-toolchain-fires.log` is left in place.
+4 -4
View File
@@ -81,10 +81,10 @@ verify-secure run at the first gate loop to fail twice (the advice stays in
the main loop, never in an executor brief; a cap or escalation STOP carries
it), before proposing a merge or calling a long task done, and before
recommending a change to the doctrine, the architecture or a public interface.
plan-challenger, verifier, security-auditor and `analyzer` may call it once,
before their verdict or report: advice can add a finding or raise its
severity, never drop, lower or clear one. Other sub-agents do not, even when
the tool is listed. An absent or
plan-challenger, verifier, security-auditor and `analyzer` may call it once
when dispatched as a sub-agent, before their verdict or report: advice can
add a finding or raise its severity, never drop, lower or clear one. Other
sub-agents do not, even when the tool is listed. An absent or
failing advisor changes nothing, and its advice waives no gate, cap or guard
(`lib/effort-shift.md` § Advisor). The main loop writes no
code outside a skill run (the router's guard redirects it to a skill); the fresh
+1 -1
View File
@@ -200,7 +200,7 @@ l'outil `mcp__model-router__route` (`lib/effort-shift.md`). Les skills
externes vendorés (pile design, superpowers, agent-skills, skills scroll
MengTo, 21st) ont aussi leur ligne.
Taper un skill qui a une ligne route la boucle principale dessus. Une ligne du tier best (plan, reflect, orchestrate, escalate ; `audit` est une ligne d'agent, jamais tapée) tient d'un tour à l'autre pendant tout le run, jusqu'à `/route clear`, `/route off`, un `/model` tapé ou choisi dans le sélecteur, ou un skill d'un autre tier tapé. Un `/model <nom>` tapé, ou un choix dans le sélecteur `/model`, avec un modèle de la table demande sa portée (Échap ne change rien). Le changement du sélecteur est d'abord retenu (le moteur affiche qu'un hook l'a bloqué), puis la question vient ; un choix fait pendant qu'un autre dialogue est ouvert est refusé (`answer the open dialog first`) : This project écrit l'id complet dans `model` du `.claude/settings.local.json` du projet (créé s'il manque, à garder dans le `.gitignore`) et pose une route de modèle tenue ; This conversation pose la route seule, sans rien écrire ; Everywhere lance le `/model` natif (`settings.json` utilisateur, tous les projets). Default dans le sélecteur, sans argument, avec un nom inconnu, en headless (`-p`) ou mod coupé, le `/model` natif passe sans question. Un modèle choisi dans ce dialogue change toujours : ni plafond de relecture à froid, ni `mainUpgrade` ni `mainModelSwitch`. S'il est en panne, la boucle principale reste où elle est jusqu'à son retour. Un changement natif (ligne Model de `/config` comprise) ou `/clear` l'abandonne ; un `/route model=` tapé garde les plafonds. La ligne Model de `/config` écrit toujours le `settings.json` utilisateur, et un dialogue jamais répondu n'a pas de délai. Pour relancer un tour bloqué : `ultrathink` dans le prompt (plancher d'effort du tour) ou `/route effort=max` (tient jusqu'à `/route clear`). Le `/effort` intégré n'a pas d'effet dans un run : les lignes et les routes passent devant. Les règles de mots-clés du prompt (`plan`, `design`, `architecture`… prennent l'effort de plan ; `pourquoi`, `review`, `audit`… celui de reflect), `ultrathink` et un lancement d'agent par la boucle principale (route `orchestrate` dérivée, tenue jusqu'à la fin de ses agents en arrière-plan) ne fixent que le niveau d'effort du tour, jamais le modèle : ils ne font jamais monter la boucle principale au-dessus du modèle de la session, et un run best tenu garde son modèle. Fable n'arrive sur la boucle principale que par un choix à la main (`/model`, sélecteur), un `/route model=fable` tapé, une phase qui nomme `model: fable` ou une config machine qui le place dans un tier : aucun tier ni aucune phase livrés ne le contiennent. Fable sert de conseiller (outil advisor, `advisorModel` dans settings.json, réglé par `/advisor`) : la boucle principale l'appelle au moins sur le plan écrit, avant que les challengers du plan le voient (`lib/challenge-plan.md`, une fois par run de skill ; la ligne `Advisor:` du CHALLENGE SUMMARY dit ce qu'il a changé), une fois par run verify-secure à la première boucle de porte qui échoue deux fois (le conseil reste dans la boucle principale, jamais dans le brief d'un exécutant ; un STOP au plafond ou en escalade le reprend), avant de proposer un merge ou de déclarer finie une longue tâche, et avant de recommander un changement de la doctrine, de l'architecture ou d'une interface publique ; plan-challenger, verifier, security-auditor et `analyzer` peuvent l'appeler une fois, avant leur verdict ou leur rapport : un conseil peut ajouter un constat ou relever sa sévérité, jamais le retirer, l'abaisser ni l'effacer ; les autres sous-agents ne l'appellent pas, même quand l'outil est listé. Conseiller absent ou en erreur : on continue ; un conseil ne lève aucune porte, aucun plafond ni aucune garde. Un prompt tapé sans règle, skill ni route en cours passe par un classifieur (un appel au petit modèle, 3 secondes au plus) : le tour prend la route de la phase devinée : son niveau d'effort, et son modèle, jamais au-dessus de celui de la session. Une devinette `coding` ou `bookkeeping` fait descendre la boucle principale vers un modèle moins cher quand `mainModelSwitch` est actif (par défaut) et que la relecture à froid tient sous `downgradeMaxTokens` (120000 tokens par défaut). Cette relecture compte aussi le prompt qui vient d'être envoyé (un token pour 3 caractères), et un document joint bloque la descente pour cette étape. Le cache compte comme chaud pendant le TTL du moteur (`cache_ttl`, 5 ou 60 minutes), 60 minutes par défaut. `/route classify off` ou `"classify": false` dans la config machine le coupe, et un `/effort` tapé entre deux tours annule la devinette pour ce tour seulement. Avant d'envoyer la boucle principale sur un modèle, celui vers lequel elle se déplace comme celui qu'elle garde (le modèle de la session compris), le mod l'essaie une fois (un appel minimal, 8 secondes au plus) : sans réponse, ce modèle est marqué en panne (raison `probe`) et la décision est reprise une fois ; `"probe": false` dans la confiLine truncated
Taper un skill qui a une ligne route la boucle principale dessus. Une ligne du tier best (plan, reflect, orchestrate, escalate ; `audit` est une ligne d'agent, jamais tapée) tient d'un tour à l'autre pendant tout le run, jusqu'à `/route clear`, `/route off`, un `/model` tapé ou choisi dans le sélecteur, ou un skill d'un autre tier tapé. Un `/model <nom>` tapé, ou un choix dans le sélecteur `/model`, avec un modèle de la table demande sa portée (Échap ne change rien). Le changement du sélecteur est d'abord retenu (le moteur affiche qu'un hook l'a bloqué), puis la question vient ; un choix fait pendant qu'un autre dialogue est ouvert est refusé (`answer the open dialog first`) : This project écrit l'id complet dans `model` du `.claude/settings.local.json` du projet (créé s'il manque, à garder dans le `.gitignore`) et pose une route de modèle tenue ; This conversation pose la route seule, sans rien écrire ; Everywhere lance le `/model` natif (`settings.json` utilisateur, tous les projets). Default dans le sélecteur, sans argument, avec un nom inconnu, en headless (`-p`) ou mod coupé, le `/model` natif passe sans question. Un modèle choisi dans ce dialogue change toujours : ni plafond de relecture à froid, ni `mainUpgrade` ni `mainModelSwitch`. S'il est en panne, la boucle principale reste où elle est jusqu'à son retour. Un changement natif (ligne Model de `/config` comprise) ou `/clear` l'abandonne ; un `/route model=` tapé garde les plafonds. La ligne Model de `/config` écrit toujours le `settings.json` utilisateur, et un dialogue jamais répondu n'a pas de délai. Pour relancer un tour bloqué : `ultrathink` dans le prompt (plancher d'effort du tour) ou `/route effort=max` (tient jusqu'à `/route clear`). Le `/effort` intégré n'a pas d'effet dans un run : les lignes et les routes passent devant. Les règles de mots-clés du prompt (`plan`, `design`, `architecture`… prennent l'effort de plan ; `pourquoi`, `review`, `audit`… celui de reflect), `ultrathink` et un lancement d'agent par la boucle principale (route `orchestrate` dérivée, tenue jusqu'à la fin de ses agents en arrière-plan) ne fixent que le niveau d'effort du tour, jamais le modèle : ils ne font jamais monter la boucle principale au-dessus du modèle de la session, et un run best tenu garde son modèle. Fable n'arrive sur la boucle principale que par un choix à la main (`/model`, sélecteur), un `/route model=fable` tapé, une phase qui nomme `model: fable` ou une config machine qui le place dans un tier : aucun tier ni aucune phase livrés ne le contiennent. Fable sert de conseiller (outil advisor, `advisorModel` dans settings.json, réglé par `/advisor`) : la boucle principale l'appelle au moins sur le plan écrit, avant que les challengers du plan le voient (`lib/challenge-plan.md`, une fois par run de skill ; la ligne `Advisor:` du CHALLENGE SUMMARY dit ce qu'il a changé), une fois par run verify-secure à la première boucle de porte qui échoue deux fois (le conseil reste dans la boucle principale, jamais dans le brief d'un exécutant ; un STOP au plafond ou en escalade le reprend), avant de proposer un merge ou de déclarer finie une longue tâche, et avant de recommander un changement de la doctrine, de l'architecture ou d'une interface publique ; plan-challenger, verifier, security-auditor et `analyzer` peuvent l'appeler une fois, seulement quand ils sont lancés comme sous-agents, avant leur verdict ou leur rapport : un conseil peut ajouter un constat ou relever sa sévérité, jamais le retirer, l'abaisser ni l'effacer ; les autres sous-agents ne l'appellent pas, même quand l'outil est listé. Conseiller absent ou en erreur : on continue ; un conseil ne lève aucune porte, aucun plafond ni aucune garde. Un prompt tapé sans règle, skill ni route en cours passe par un classifieur (un appel au petit modèle, 3 secondes au plus) : le tour prend la route de la phase devinée : son niveau d'effort, et son modèle, jamais au-dessus de celui de la session. Une devinette `coding` ou `bookkeeping` fait descendre la boucle principale vers un modèle moins cher quand `mainModelSwitch` est actif (par défaut) et que la relecture à froid tient sous `downgradeMaxTokens` (120000 tokens par défaut). Cette relecture compte aussi le prompt qui vient d'être envoyé (un token pour 3 caractères), et un document joint bloque la descente pour cette étape. Le cache compte comme chaud pendant le TTL du moteur (`cache_ttl`, 5 ou 60 minutes), 60 minutes par défaut. `/route classify off` ou `"classify": false` dans la config machine le coupe, et un `/effort` tapé entre deux tours annule la devinette pour ce tour seulement. Avant d'envoyer la boucle principale sur un modèle, celui vers lequel elle se déplace comme celui qu'elle garde (le modèle de la session compris), le mod l'essaie une fois (un appel minimal, 8 secondes au plus) : sans réponse, ce modèle est marqué en panne (raison `probe`) et la décision eLine truncated
Garde d'écriture : un Edit, Write ou NotebookEdit d'un fichier de code par la boucle principale est redirigé avec « model-router: code is written inside a skill run… » tant qu'aucun skill n'a tourné sur la boucle principale dans la session (tapé ou chargé par le modèle ; un skill refusé ou inconnu ne compte pas), qu'aucune phase n'a été déclarée ce tour, et qu'aucun `/route` tapé ne tient. Chemins libres : `.md`, `.txt`, le `.claude/` du projet sauf `worktrees/`, et `docs/`. Les sous-agents écrivent librement. Si la vérification du garde échoue elle-même (exception ou délai dépassé), l'écriture est retenue au lieu de passer, avec « model-router: the write guard failed (<kind>), so this write is held… », journalisé une fois par session ; les sous-agents, un skill en cours, une phase déclarée ou un `/route` tapé, et les fichiers `.md` / `.txt` passent toujours, et une erreur levée par l'outil lui-même est transmise telle quelle. `/route clear`, `/route off` et `/clear` réarment le garde ; `/route off` le coupe aussi, et `"enabled": false` dans `~/.claude/model-router.json` coupe le routeur et le garde. Un choix à la main avec `/model` ne l'ouvre pas, et un rechargement de `register.ts` le remet à zéro.
+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
@@ -0,0 +1,395 @@
# Advisor call points, run B2 — Implementation Plan (r3 + STEP 6 review fix)
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Wire the remaining advisor call points of `lib/effort-shift.md` § Advisor into the skills that run them (stuck point, end-of-run point) and fix three advisor bullets in the judgment agents.
**Architecture:** Prose doctrine edits only. Every edit is a block below, applied by `docs/superpowers/plans/2026-11-17-advisor-points-b2/apply.py`, which reads the blocks from THIS file and asserts each anchor occurs exactly once (LRN-296). No other wording changes.
**Tech Stack:** Markdown doctrine, Python 3 applier, bash contract oracles (`lib/gates.sh`), `make test`.
**Spec:** design approved in chat 2026-11-17 (bounded path); contract `.claude/tasks/contracts/2026-11-17-advisor-points-b2-1634.md` (REQUEST verbatim + CLARIFICATIONS [gated]).
## Global Constraints
- Branch `feature/advisor-points-b2` off develop; commits `docs(doctrine): …`.
- 13 doctrine files: skills/{feat,bugfix,ship-feature,init-project,a11y,guardrails,audit-delta,tour,release-candidate}/SKILL.md, agents/{verifier,security-auditor,plan-challenger}.md, lib/effort-shift.md. `lib/capitalize-commit.md` untouched (user 2026-11-17).
- Every new line ≤ 80 columns; every marker and every `§ Label` citation on one line, followed by `)` or `;` (doctrine-citers census).
- Advice stays in the main loop, never in an executor, gate or challenger brief (BDR-066, LRN-083, LRN-208); advice is input, never the go (BDR-136, effort-shift "Advice is input, never consent").
- Stuck unit unchanged from B1: main-loop calls only, "since GATE 0 first ran" (`lib/verify-secure-loop.md` holds the rule; skills only point to it).
- The end-of-run call has its own budget: one per skill run, never skipped for an earlier plan or stuck call (item 3 says it once; the skill lines say "its end-of-run advisor call").
- SDD runs in place, in the main checkout on `feature/advisor-points-b2`: decline the using-git-worktrees offer (every command below is rooted at `/home/bchanot/Documents/claude`).
- Contract criteria integer-labelled (LRN-284); CHECKs one line, `/usr/bin/grep`, `/usr/bin/git` (LRN-171, LRN-176); full suite with `GATES_TIMEOUT=400`.
## Review Focus
- End call read as the run's whole advisor budget after a plan or stuck call → item 3 states its own budget; the skill lines name "its end-of-run advisor call".
- End call placed after the run was already declared done (feat FEAT COMPLETE at STEP 5, bugfix BUGFIX COMPLETE at STEP 6 item 4) → placed just before those summaries (criterion 13).
- Tour fan-out: runners (sub-agents) execute STEP 3, the main loop follows STEP 0b's list → STEP 3 line says "Main loop only, never a runner", STEP 0b item 2 names the call, the runner prompt says "never call the advisor" (criterion 19).
- security-auditor: an advisor raise mapped to a lower STEP 3 class must not lower a semgrep HIGH/CRITICAL, and a raise that does not apply is neither tagged nor counted (criterion 15).
- A census-invisible citation or a test-locked phrase moved → every new citation is `(`lib/effort-shift.md` § Advisor)` on one line; simulated with the full suite on a scratch clone before dispatch.
---
## Edit table (what apply.py does)
| # | File | Anchor (exact, once) | Action |
|---|------|----------------------|--------|
| E1 | skills/feat/SKILL.md | `Loop decisions stay HERE, in the main loop (LRN-083). Nominal (clear` | insert Block stuck + blank line before |
| E2 | skills/bugfix/SKILL.md | ` Loop decisions stay HERE, in the main loop (LRN-083). Nominal = one` | insert Block stuck (3-space indent) + blank line before |
| E3 | skills/ship-feature/SKILL.md | `other ([[LRN-095]]).\n\n## STEP 6 — CODE REVIEW` (end of STEP 5) | insert Block stuck + blank line before the heading |
| E4 | skills/init-project/SKILL.md | `([[LRN-095]]) — both run.\n\n## STEP 10 — CODE REVIEW` (end of STEP 9) | insert Block stuck + blank line before the heading |
| E5 | skills/a11y/SKILL.md, skills/guardrails/SKILL.md | ` the include's; loop decisions stay in this main loop.\n` (end of item 6 Gates) | append Block stuck (3-space indent) inside item 6 |
| E6 | skills/feat/SKILL.md | `\nPrint summary:\n```\nFEAT COMPLETE` (STEP 5, after the commit and the reflect route) | insert Block end-report + blank line before `Print summary:` |
| E7 | skills/bugfix/SKILL.md | ` two sentences of body).\n4. Print summary:` (STEP 6, after the commit) | append Block route-reflect + Block end-report (3-space indent) to item 3 |
| E8 | skills/ship-feature/SKILL.md (`## STEP 9 — FINISH\n`), skills/init-project/SKILL.md (`## STEP 11 — FINISH\n`) | heading line | insert Block end-finish + blank line after the heading |
| E9 | skills/a11y/SKILL.md, skills/guardrails/SKILL.md | ` commit, project convention else 50 words at most.\n2. \`mcp__model-router__route` | append Block end-handover (3-space indent) to item 1, before the apply route |
| E10 | skills/audit-delta/SKILL.md | `## STEP 4 — FINAL SUMMARY\n\n` | insert Block end-audit + blank line after |
| E11 | skills/tour/SKILL.md | `Global summary inline, one line per project (append` | insert Block end-tour + blank line before |
| E12 | skills/tour/SKILL.md | `2. Prints the global summary (STEP 3 format) once ALL runners returned.\n` (STEP 0b main-loop list) | replace with Block tour-dispatch |
| E13 | skills/tour/SKILL.md | runner prompt lines ` Skip STEP 0/0b (routing) and the global summary — the dispatcher owns\n them. Every rule of the skill applies unchanged: max 3 iterations,\n` | replace with Block tour-runner |
| E14 | skills/release-candidate/SKILL.md | `### STEP 4 — HUMAN GATE: when to release\n` | insert Block end-release + blank line after the heading |
| E15 | agents/verifier.md | first 3 lines of the `- Advisor (when listed):` bullet | replace with Block verifier-head |
| E16 | agents/security-auditor.md | the whole `- Advisor (when listed):` bullet (12 lines) | replace with Block auditor |
| E17 | agents/plan-challenger.md | the whole `- Advisor (when listed):` bullet (5 lines) | replace with Block challenger |
| E18 | agents/plan-challenger.md | `- Dispatch THREE fresh challengers IN PARALLEL, one per lens\n` | insert Block protocol-first before |
| E19 | agents/plan-challenger.md | the 3-line `- ADVISORY:` bullet | replace with Block protocol-advisory |
| E20 | lib/effort-shift.md | `3. Before proposing a merge (\`gitflow finish\`) or calling a long task\n done.\n` | replace with Block item3 (ends with a blank line before block I) |
Groups: `skills` = E1-E14 (17 edits), `agents` = E15-E20 (6 edits).
`review1` (STEP 6 code-review fix, from HEAD 24354d9): rewrites the end-report,
end-finish and end-handover blocks in the six gate flows (diff stat, fix back
through the gates), end-release ("makes hold the recommended answer"), and adds
Block route-reflect before the bugfix end call (7 edits).
## Contract additions at STEP 3 (`[gated 2026-11-17]`)
Inserted into the contract's ACCEPTANCE CRITERIA after criterion 9, before
`## FILE SCOPE`, each line tagged `[gated 2026-11-17]`; simulated on a scratch
clone before dispatch (LRN-296). Seed criteria 1-9 stay as written.
```
10. [gated 2026-11-17] Stuck paragraph in each gate skill, citing the lib and § Advisor.
CHECK: cd /home/bchanot/Documents/claude && for s in feat bugfix ship-feature init-project a11y guardrails; do f=skills/$s/SKILL.md; printf '%s:%s/%s ' "$s" "$(/usr/bin/grep -c 'Stuck: a gate loop fails twice with no main-loop advisor call since GATE 0' "$f")" "$(/usr/bin/grep -cF '(`lib/effort-shift.md` § Advisor); the answer never enters an executor brief.' "$f")"; done; echo
EXPECT: feat:1/1 bugfix:1/1 ship-feature:1/1 init-project:1/1 a11y:1/1 guardrails:1/1
EVIDENCE: pending
11. [gated 2026-11-17] The stuck paragraph sits in the gate step (after a GATE 2 line, no heading between).
CHECK: cd /home/bchanot/Documents/claude && for s in feat bugfix ship-feature init-project a11y guardrails; do awk -v s="$s" '/GATE 2/{g=NR} /^## /{h=NR} /Stuck: a gate loop fails twice/{m=NR; ok=(g>h)} END{printf "%s:%s ", s, (m&&ok)?"in-gate":"OUT"}' "skills/$s/SKILL.md"; done; echo
EXPECT: feat:in-gate bugfix:in-gate ship-feature:in-gate init-project:in-gate a11y:in-gate guardrails:in-gate
EVIDENCE: pending
12. [gated 2026-11-17] The end-of-run marker is in exactly the 9 flows (no hotfix, lib, agent or memory-only flow).
CHECK: cd /home/bchanot/Documents/claude && echo "[$(/usr/bin/grep -rlF 'end-of-run advisor call (`lib/effort-shift.md` § Advisor)' skills lib agents | LC_ALL=C sort | tr '\n' ' ')]"
EXPECT: [skills/a11y/SKILL.md skills/audit-delta/SKILL.md skills/bugfix/SKILL.md skills/feat/SKILL.md skills/guardrails/SKILL.md skills/init-project/SKILL.md skills/release-candidate/SKILL.md skills/ship-feature/SKILL.md skills/tour/SKILL.md ]
EVIDENCE: pending
13. [gated 2026-11-17] Each end marker occurs once, before its flow's done or merge moment.
CHECK: cd /home/bchanot/Documents/claude && for t in 'feat|^## STEP 5 |^FEAT COMPLETE' 'bugfix|^## STEP 6 |BUGFIX COMPLETE' 'ship-feature|^## STEP 9 |finish # feature' 'init-project|^## STEP 11 |finish # feature' 'a11y|^## STEP 10:|^2[.] .mcp__model-router' 'guardrails|^## STEP 12:|^2[.] .mcp__model-router' 'audit-delta|^## STEP 4 |AUDIT-DELTA COMPLETE' 'tour|^Checks: pytest PASS|^TOUR COMPLETE' 'release-candidate|^### STEP 4 |^AskUserQuestion:'; do IFS='|' read -r s a b <<<"$t"; awk -v s="$s" -v a="$a" -v b="$b" '!sa && $0~a {sa=NR} index($0,"end-of-run advisor call (`lib/effort-shift.md` § Advisor)"){n++; m=NR} sa && !sb && NR>sa && $0~b {sb=NR} END{printf "%s:%s ", s, (n==1 && sa<m && m<sb)?"ok":"BAD"}' "skills/$s/SKILL.md"; done; echo
EXPECT: feat:ok bugfix:ok ship-feature:ok init-project:ok a11y:ok guardrails:ok audit-delta:ok tour:ok release-candidate:ok
EVIDENCE: pending
14. [gated 2026-11-17] verifier, security-auditor and plan-challenger advise only when dispatched.
CHECK: cd /home/bchanot/Documents/claude && for a in verifier security-auditor plan-challenger; do printf '%s:%s/%s ' "$a" "$(/usr/bin/grep -c '^- Advisor, when dispatched as a sub-agent: at most one call' "agents/$a.md")" "$(/usr/bin/grep -c 'Advisor (when listed)' "agents/$a.md")"; done; echo
EXPECT: verifier:1/0 security-auditor:1/0 plan-challenger:1/0
EVIDENCE: pending
15. [gated 2026-11-17] security-auditor: a raise applies only upward, a no-op raise is neither tagged nor counted, advice never removes, lowers or waives.
CHECK: cd /home/bchanot/Documents/claude && echo "[$(/usr/bin/grep -c 'A raise applies only when its class.s severity' agents/security-auditor.md)/$(/usr/bin/grep -c 'changes nothing: no tag,' agents/security-auditor.md)/$(/usr/bin/grep -c '^ Advice never removes, lowers or waives a finding from semgrep' agents/security-auditor.md)/$(/usr/bin/grep -c 'overrides the STEP 2 mapping' agents/security-auditor.md)/$(/usr/bin/grep -c 'It never removes' agents/security-auditor.md)]"
EXPECT: [1/1/1/0/0]
EVIDENCE: pending
16. [gated 2026-11-17] plan-challenger ORCHESTRATOR PROTOCOL: ADVISOR FIRST (pointer to the lib, its guards) before the dispatch bullet, `Advisor:` row in ADVISORY.
CHECK: cd /home/bchanot/Documents/claude && echo "[$(/usr/bin/grep -c '^- ADVISOR FIRST (main loop): per `lib/challenge-plan.md`' agents/plan-challenger.md)/$(/usr/bin/grep -c 'with no main-loop advisor call since the skill run started; absent or' agents/plan-challenger.md)/$(/usr/bin/grep -cF 'an `Advisor:` row) feed the' agents/plan-challenger.md)/$(awk '/^## ORCHESTRATOR PROTOCOL/{p=NR} /^- ADVISOR FIRST/{a=NR} /^- Dispatch THREE fresh challengers/{d=NR} END{print (p && p<a && a<d)}' agents/plan-challenger.md)]"
EXPECT: [1/1/1/1]
EVIDENCE: pending
17. [gated 2026-11-17] effort-shift § Advisor item 3 keeps its generic trigger, names its sites, its own budget, the audit-delta/tour skip and the gate-flow-only fix path; § Advisor still names no STEP.
CHECK: cd /home/bchanot/Documents/claude && sec() { sed -n '/^## Advisor/,/^## Never/p' lib/effort-shift.md; }; echo "[$(sec | /usr/bin/grep -c 'done. Wired at the end step of feat, bugfix,')/$(sec | /usr/bin/grep -c 'release gate of release-candidate: one end-of-run call per skill')/$(sec | /usr/bin/grep -c 'never skipped for an earlier plan or stuck call')/$(sec | /usr/bin/grep -c 'and tour skip it when the run applied no fix')/$(sec | /usr/bin/grep -c 'the answer is reported only and a fix it calls for is a new run')/$(sec | /usr/bin/grep -c STEP)]"
EXPECT: [1/1/1/1/1/0]
EVIDENCE: pending
18. [gated 2026-11-17] Every added line in the 13 files is at most 80 columns.
CHECK: cd /home/bchanot/Documents/claude && n=$(/usr/bin/git diff develop -U0 -- skills/feat/SKILL.md skills/bugfix/SKILL.md skills/ship-feature/SKILL.md skills/init-project/SKILL.md skills/a11y/SKILL.md skills/guardrails/SKILL.md skills/audit-delta/SKILL.md skills/tour/SKILL.md skills/release-candidate/SKILL.md agents/verifier.md agents/security-auditor.md agents/plan-challenger.md lib/effort-shift.md | /usr/bin/grep '^+[^+]' | cut -c2- | LC_ALL=C.UTF-8 awk 'length>80' | wc -l); [ "$n" -eq 0 ] && echo WIDTH-OK
EXPECT: WIDTH-OK
EVIDENCE: pending
19. [gated 2026-11-17] Tour fan-out: the main loop makes the call (STEP 0b list) only when a fix was applied, runners never do.
CHECK: cd /home/bchanot/Documents/claude && f=skills/tour/SKILL.md; echo "[$(/usr/bin/grep -c 'when any row reports a fix, makes the' $f)/$(/usr/bin/grep -c 'STEP 3 end-of-run advisor call; then prints the global summary' $f)/$(/usr/bin/grep -c 'them; never call the advisor. Every rule' $f)/$(/usr/bin/grep -c '^Main loop only, never a runner: when the tour applied any fix' $f)]"
EXPECT: [1/1/1/1]
EVIDENCE: pending
20. [gated 2026-11-17] ship-feature and init-project route back to their plan level, release-candidate up to reflect, before the end call.
CHECK: cd /home/bchanot/Documents/claude && echo "[$(/usr/bin/grep -cF 'route(phase="plan")` first (route: end-of-run review).' skills/ship-feature/SKILL.md)/$(/usr/bin/grep -cF 'route(phase="plan")` first (route: end-of-run review).' skills/init-project/SKILL.md)/$(/usr/bin/grep -cF 'route(phase="reflect")` first (route: end-of-run review).' skills/release-candidate/SKILL.md)]"
EXPECT: [1/1/1]
EVIDENCE: pending
21. [gated 2026-11-17] In ship-feature and init-project the stuck paragraph follows the "This …" paragraph it would otherwise split from the gates.
CHECK: cd /home/bchanot/Documents/claude && for t in 'ship-feature|^This replaces the old informal' 'init-project|^This adds the security gate'; do IFS='|' read -r s a <<<"$t"; awk -v s="$s" -v a="$a" '$0~a{t=NR} /Stuck: a gate loop fails twice/{m=NR} END{printf "%s:%s ", s, (t && m>t)?"after-this":"BAD"}' "skills/$s/SKILL.md"; done; echo
EXPECT: ship-feature:after-this init-project:after-this
EVIDENCE: pending
```
FILE SCOPE replaced at STEP 3 (`[gated 2026-11-17]`): skills/feat/SKILL.md (gate
step, STEP 5 summary), skills/bugfix/SKILL.md (gate step, STEP 6 summary),
skills/{ship-feature,init-project}/SKILL.md (gate step, FINISH head),
skills/{a11y,guardrails}/SKILL.md (Gates item, Commit and hand over item 1),
skills/audit-delta/SKILL.md (STEP 4 head), skills/tour/SKILL.md (runner
prompt, STEP 0b list, before the global summary),
skills/release-candidate/SKILL.md (STEP 4 head), agents/verifier.md and
agents/security-auditor.md (advisor bullet), agents/plan-challenger.md
(advisor bullet, ORCHESTRATOR PROTOCOL), lib/effort-shift.md (§ Advisor item 3
and the blank line before block I); transient, purged by `gitflow finish`:
docs/superpowers/plans/2026-11-17-advisor-points-b2.md and
docs/superpowers/plans/2026-11-17-advisor-points-b2/apply.py; this contract.
`lib/capitalize-commit.md` is not touched. Seed criterion 2's "flows of
CLARIFICATIONS" = the end steps of feat, bugfix, ship-feature, init-project,
a11y, guardrails, audit-delta and tour.
## Blocks (verbatim; apply.py reads them from here)
### Block stuck
```
Stuck: a gate loop fails twice with no main-loop advisor call since GATE 0
first ran → the main loop calls the advisor per `lib/verify-secure-loop.md`
(`lib/effort-shift.md` § Advisor); the answer never enters an executor brief.
```
### Block end-report
```
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.
```
### Block route-reflect
```
`mcp__model-router__route(phase="reflect")` first (route: end-of-run review).
```
### Block end-finish
```
`mcp__model-router__route(phase="plan")` first (route: end-of-run review).
Before proposing the finish, 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 with the proposal as an `Advisor:` line, and a fix it
drives goes back through the gates.
```
### Block end-handover
```
Before the reply, 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 reply as an `Advisor:` line, and a fix it drives goes
back through the gates.
```
### Block end-audit
```
When the run applied a fix, before the summary, the main loop 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 calls for
waits for a new run.
```
### Block end-tour
```
Main loop only, never a runner: when the tour applied any fix, before
the global summary, the main loop 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 calls for
waits for a new run.
```
### Block tour-dispatch
```
2. Once ALL runners returned: when any row reports a fix, makes the
STEP 3 end-of-run advisor call; then prints the global summary (STEP 3
format).
```
### Block tour-runner
```
Skip STEP 0/0b (routing) and the global summary — the dispatcher owns
them; never call the advisor. Every rule of the skill applies
unchanged: max 3 iterations,
```
### Block end-release
```
`mcp__model-router__route(phase="reflect")` first (route: end-of-run review).
Before the ask, the main loop makes its
end-of-run advisor call (`lib/effort-shift.md` § Advisor); its answer
goes with the ask as an `Advisor:` line, and a fix it calls for makes
hold the recommended answer.
```
### Block verifier-head
```
- 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
```
### Block auditor
```
- 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.
```
### Block challenger
```
- 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.
```
### Block protocol-first
```
- 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.
```
### Block protocol-advisory
```
- ADVISORY: the revised plan + a challenge summary (raised / addressed /
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.
```
### Block item3
```
3. Before proposing a merge (`gitflow finish`) or calling a long task
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.
```
---
### Orchestrator, at branch start (not a dispatched task)
After `gitflow.sh start feature advisor-points-b2`, commit this plan and its
applier on the branch so the executors and reviewers read them from disk
(transient artifacts, purged by `gitflow finish`):
`git add docs/superpowers/plans/2026-11-17-advisor-points-b2.md docs/superpowers/plans/2026-11-17-advisor-points-b2/apply.py && git commit -m "chore(plan): advisor points run B2 plan and applier"`
### Task 1: Skills — stuck trigger and end-of-run line (9 skill files)
**Files:**
- Modify: `skills/feat/SKILL.md` (STEP 4 before "Loop decisions"; STEP 5 before "Print summary:")
- Modify: `skills/bugfix/SKILL.md` (STEP 6 item 1 before "Loop decisions"; STEP 6 end of item 3)
- Modify: `skills/ship-feature/SKILL.md` (end of STEP 5; STEP 9 head)
- Modify: `skills/init-project/SKILL.md` (end of STEP 9; STEP 11 head)
- Modify: `skills/a11y/SKILL.md` (STEP 8 item 6; STEP 10 item 1 end)
- Modify: `skills/guardrails/SKILL.md` (STEP 10 item 6; STEP 12 item 1 end)
- Modify: `skills/audit-delta/SKILL.md` (STEP 4 head)
- Modify: `skills/tour/SKILL.md` (runner prompt; STEP 0b list item 2; before the global summary)
- Modify: `skills/release-candidate/SKILL.md` (STEP 4 head)
**Interfaces:**
- Consumes: `lib/verify-secure-loop.md` stuck lines (B1, unchanged); `lib/effort-shift.md` § Advisor items 2 and 3 (item 3 rewritten in Task 2).
- Produces: the stuck marker in 6 files, the end marker `end-of-run advisor call (\`lib/effort-shift.md\` § Advisor)` in exactly 9 files.
- [ ] **Step 1: Confirm the oracles fail before the edit**
Run the CHECK lines of contract criteria 10, 11, 12, 13, 19, 20 and 21 by hand
(copy each `CHECK:` line; do NOT run `lib/gates.sh`, the orchestrator owns the
floor and its EVIDENCE lines).
Expected: none prints its `EXPECT:` marker.
- [ ] **Step 2: Apply the skills group**
Run: `cd /home/bchanot/Documents/claude && python3 docs/superpowers/plans/2026-11-17-advisor-points-b2/apply.py docs/superpowers/plans/2026-11-17-advisor-points-b2.md . skills`
Expected: `applied 17 edits (skills)`; any anchor count ≠ 1 → it exits 1 and writes nothing.
- [ ] **Step 3: Run the skills oracles**
Run the same seven CHECK lines again.
Expected: each prints its `EXPECT:` marker.
- [ ] **Step 4: Run the locked-phrase suites**
Run: `cd /home/bchanot/Documents/claude && for s in loops-light loops-heavy effort-routing model-routing doctrine-citers; do make test suite=lib/tests/$s.test.sh </dev/null 2>&1 | tail -1; done`
Expected: `all suites green` five times.
- [ ] **Step 5: Commit**
```bash
cd /home/bchanot/Documents/claude
git add skills/feat/SKILL.md skills/bugfix/SKILL.md skills/ship-feature/SKILL.md skills/init-project/SKILL.md skills/a11y/SKILL.md skills/guardrails/SKILL.md skills/audit-delta/SKILL.md skills/tour/SKILL.md skills/release-candidate/SKILL.md
git commit -m "docs(doctrine): advisor stuck trigger in gate skills, end-of-run call in code flows"
```
### Task 2: Agents and effort-shift (4 files)
**Files:**
- Modify: `agents/verifier.md` (advisor bullet head)
- Modify: `agents/security-auditor.md` (advisor bullet)
- Modify: `agents/plan-challenger.md` (advisor bullet; ORCHESTRATOR PROTOCOL)
- Modify: `lib/effort-shift.md` (§ Advisor item 3 + blank line before block I)
**Interfaces:**
- Consumes: `agents/analyzer.md` "Advisor, when dispatched as a sub-agent" wording (precedent); `lib/challenge-plan.md` "Advisor first" guards and the `Advisor:` row (mirror source).
- Produces: criteria 6, 14, 15, 16, 17 markers.
- [ ] **Step 1: Apply the agents group**
Run: `cd /home/bchanot/Documents/claude && python3 docs/superpowers/plans/2026-11-17-advisor-points-b2/apply.py docs/superpowers/plans/2026-11-17-advisor-points-b2.md . agents`
Expected: `applied 6 edits (agents)`.
- [ ] **Step 2: Run the agents and lib oracles and the fast suites**
Run the CHECK lines of contract criteria 6, 14, 15, 16, 17 and 18 by hand, then:
`cd /home/bchanot/Documents/claude && for s in plan-challenger security-auditor contract-verifier gates doctrine-citers; do make test suite=lib/tests/$s.test.sh </dev/null 2>&1 | tail -1; done`
Expected: each CHECK prints its `EXPECT:` marker; `all suites green` five times.
Do NOT run `lib/gates.sh` or the full `make test`: the orchestrator runs the
whole floor (GATE 0, `GATES_TIMEOUT=400`) after this task.
- [ ] **Step 3: Commit**
```bash
cd /home/bchanot/Documents/claude
git add agents/verifier.md agents/security-auditor.md agents/plan-challenger.md lib/effort-shift.md
git commit -m "docs(doctrine): judgment agents advise only when dispatched; auditor raises only upward; protocol mirror; end-of-run point sites"
```
### Orchestrator, after the gates (STEP 7 and STEP 8, not dispatched)
- STEP 7 CAPITALIZE: `memory_pending` first; BDR-150 status line (B2: stuck and
end-of-run points in the skills, three agents dispatch-scoped); BUGS-FOUND
advisor entries updated: :109 FIXED (raise only upward), :110 FIXED for the
bullets with the inline-load tail kept, :111 FIXED for the mirror with the
template-row tail kept; TODO Run B2 line checked, the reflect-route item as
its own line.
- STEP 8 DOC SYNC: doc-syncer audit scope includes CHANGELOG.md (the
[Unreleased] "Advisor doctrine" bullet, the stale auditor "that class's
severity" wording at :23), README.md and USAGE.md advisor lines.
## Disposition
- amends BDR-150 (6ef3069, 58a5273): stuck point and end-of-run point reach the skills; three agents scoped to dispatch.
- honors BDR-034 / LRN-029: `lib/capitalize-commit.md` keeps its single concern (memory commit).
- honors BDR-066 / LRN-083 / LRN-208: no advice in any brief; tour runners never call.
- honors BDR-084: tour's main loop owns the end call in fan-out mode.
- honors BDR-136: advice is never the go; the finish ask stays.
- applies LRN-295: one end call per skill run, skipped by audit-delta and tour when nothing was fixed; the stuck call counts main-loop calls only (B1 unit).
- applies LRN-296 / LRN-284 / LRN-171 / LRN-176: blocks in one file, exact-once applier, simulation on a scratch clone, integer labels, one-line CHECKs.
- Residual (BUGS-FOUND :110 tail): `lib/verify-secure-loop.md` still offers "or load agents/<x>.md" inline; unused today, kept logged.
- Residual (BUGS-FOUND :111 tail): the 12 skills' own CHALLENGE SUMMARY templates still lack the `Advisor:` row (the lib says to append it anyway); kept logged.
- Out of B2 (user 2026-11-17): the 12 skills' reflect route with the challenger dispatch → own TODO line.
@@ -0,0 +1,183 @@
#!/usr/bin/env python3
"""Apply run B2 blocks to a repo root.
Usage: apply.py <plan.md> <repo root> <skills|agents|review1>
Blocks are read from the plan (### Block <name> + fenced body). Every anchor
must occur exactly once in its file; any miss aborts before writing anything.
"""
import pathlib
import re
import sys
ARROW = "→"
DASH = "—"
def read_blocks(plan):
text = pathlib.Path(plan).read_text(encoding="utf-8")
pattern = r"^### Block (\S+)\n```\n(.*?)```\n"
return dict(re.findall(pattern, text, re.S | re.M))
def indent(block, width):
pad = " " * width
return "".join(pad + line if line.strip() else line
for line in block.splitlines(True))
def gate_edits(b):
s0, s3 = b["stuck"], indent(b["stuck"], 3)
loop_feat = "Loop decisions stay HERE, in the main loop (LRN-083). Nominal (clear\n"
loop_bug = " Loop decisions stay HERE, in the main loop (LRN-083). Nominal = one\n"
ship = f"other ([[LRN-095]]).\n\n## STEP 6 {DASH} CODE REVIEW"
init = f"([[LRN-095]]) {DASH} both run.\n\n## STEP 10 {DASH} CODE REVIEW"
item6 = " the include's; loop decisions stay in this main loop.\n"
return [
("skills/feat/SKILL.md", loop_feat, s0 + "\n" + loop_feat),
("skills/bugfix/SKILL.md", loop_bug, s3 + "\n" + loop_bug),
("skills/ship-feature/SKILL.md", ship,
ship.replace("\n\n## ", "\n\n" + s0 + "\n## ")),
("skills/init-project/SKILL.md", init,
init.replace("\n\n## ", "\n\n" + s0 + "\n## ")),
("skills/a11y/SKILL.md", item6, item6 + s3),
("skills/guardrails/SKILL.md", item6, item6 + s3),
]
def end_edits(b):
feat = "\nPrint summary:\n```\nFEAT COMPLETE"
bug = " two sentences of body).\n4. Print summary:"
item1 = (" commit, project convention else 50 words at most.\n"
"2. `mcp__model-router__route")
ho = indent(b["end-handover"], 3)
step9 = f"## STEP 9 {DASH} FINISH\n"
step11 = f"## STEP 11 {DASH} FINISH\n"
audit = f"## STEP 4 {DASH} FINAL SUMMARY\n\n"
tour = "Global summary inline, one line per project (append"
tour_list = "2. Prints the global summary (STEP 3 format) once ALL runners returned.\n"
tour_runner = (f" Skip STEP 0/0b (routing) and the global summary {DASH} the dispatcher owns\n"
" them. Every rule of the skill applies unchanged: max 3 iterations,\n")
rc = f"### STEP 4 {DASH} HUMAN GATE: when to release\n"
return [
("skills/feat/SKILL.md", feat, "\n" + b["end-report"] + feat),
("skills/bugfix/SKILL.md", bug,
bug.replace("\n4. ", "\n" + indent(b["route-reflect"] + b["end-report"], 3)
+ "4. ")),
("skills/ship-feature/SKILL.md", step9, step9 + b["end-finish"] + "\n"),
("skills/init-project/SKILL.md", step11, step11 + b["end-finish"] + "\n"),
("skills/a11y/SKILL.md", item1, item1.replace("\n2. ", "\n" + ho + "2. ")),
("skills/guardrails/SKILL.md", item1,
item1.replace("\n2. ", "\n" + ho + "2. ")),
("skills/audit-delta/SKILL.md", audit, audit + b["end-audit"] + "\n"),
("skills/tour/SKILL.md", tour, b["end-tour"] + "\n" + tour),
("skills/tour/SKILL.md", tour_list, b["tour-dispatch"]),
("skills/tour/SKILL.md", tour_runner, b["tour-runner"]),
("skills/release-candidate/SKILL.md", rc, rc + b["end-release"] + "\n"),
]
def skills_edits(b):
return gate_edits(b) + end_edits(b)
def agents_edits(b):
ver_old = ("- Advisor (when listed): at most one call, after STEP 4 and before\n"
" STEP 5, whatever the harness prompt schedules; absent or\n"
f" erroring {ARROW} proceed. Advice may send you back to a criterion: a\n")
sa_old = (
"- Advisor (when listed): at most one call, after STEP 4 and before\n"
" STEP 5 and any REPORT write, whatever the harness prompt schedules;\n"
f" absent or erroring {ARROW} proceed. Advice may add a finding or raise a\n"
" severity, cited at a file:line you read. An added finding's rule/check\n"
" is `advisor:<STEP 3 class>`; a raised one keeps its own line, its\n"
" rule/check becoming `<rule>+advisor`, so it counts once. The severity\n"
" is that STEP 3 class's, which overrides the STEP 2 mapping for that\n"
" finding only; an added finding matching no class is REPORTED as LOW,\n"
" and a raise matching no class changes nothing. It enters STEP 5's\n"
" dedup and BLOCK(n) like any other, and PROOF ends with `; advisor <n>\n"
" added/raised`. It never removes, lowers or waives a finding from\n"
" semgrep, the checklist or STEP 4.\n")
pc_old = (
"- Advisor (when listed): at most one call, after drafting your findings\n"
" and before the verdict, whatever the harness prompt schedules; absent\n"
f" or erroring {ARROW} proceed. Advice may add or sharpen a finding. Advice\n"
" alone never drops or lowers one: a change rests on your own re-read,\n"
" cited at file:line.\n")
dispatch = "- Dispatch THREE fresh challengers IN PARALLEL, one per lens\n"
advisory_old = (
"- ADVISORY: the revised plan + a challenge summary (raised / addressed /\n"
" deferred / any lens that failed to return) feed the orchestrator's existing\n"
f" human gate. The human decides {DASH} this is not a hard block.\n")
item3_old = ("3. Before proposing a merge (`gitflow finish`) or calling a long task\n"
" done.\n")
return [
("agents/verifier.md", ver_old, b["verifier-head"]),
("agents/security-auditor.md", sa_old, b["auditor"]),
("agents/plan-challenger.md", pc_old, b["challenger"]),
("agents/plan-challenger.md", dispatch, b["protocol-first"] + dispatch),
("agents/plan-challenger.md", advisory_old, b["protocol-advisory"]),
("lib/effort-shift.md", item3_old, b["item3"]),
]
OLD_END_REPORT = (
"Before the summary, the main loop makes its\n"
"end-of-run advisor call (`lib/effort-shift.md` \u00a7 Advisor); its answer\n"
"goes into the summary as an `Advisor:` line.\n")
OLD_END_FINISH = (
"`mcp__model-router__route(phase=\"plan\")` first (route: end-of-run review).\n"
"Before proposing the finish, the main loop makes its\n"
"end-of-run advisor call (`lib/effort-shift.md` \u00a7 Advisor); its answer\n"
"goes with the proposal as an `Advisor:` line.\n")
OLD_END_HANDOVER = (
"Before the reply, the main loop makes its\n"
"end-of-run advisor call (`lib/effort-shift.md` \u00a7 Advisor); its answer\n"
"goes into the reply as an `Advisor:` line.\n")
OLD_END_RELEASE = (
"`mcp__model-router__route(phase=\"reflect\")` first (route: end-of-run review).\n"
"Before the ask, the main loop makes its\n"
"end-of-run advisor call (`lib/effort-shift.md` \u00a7 Advisor); its answer\n"
"goes with the ask as an `Advisor:` line; a fix it calls for means hold.\n")
def review1_edits(b):
"""STEP 6 code-review fix, applied on top of HEAD 24354d9."""
report = b["end-report"]
return [
("skills/feat/SKILL.md", OLD_END_REPORT, report),
("skills/bugfix/SKILL.md", indent(OLD_END_REPORT, 3),
indent(b["route-reflect"] + report, 3)),
("skills/ship-feature/SKILL.md", OLD_END_FINISH, b["end-finish"]),
("skills/init-project/SKILL.md", OLD_END_FINISH, b["end-finish"]),
("skills/a11y/SKILL.md", indent(OLD_END_HANDOVER, 3),
indent(b["end-handover"], 3)),
("skills/guardrails/SKILL.md", indent(OLD_END_HANDOVER, 3),
indent(b["end-handover"], 3)),
("skills/release-candidate/SKILL.md", OLD_END_RELEASE, b["end-release"]),
]
GROUPS = {"skills": skills_edits, "agents": agents_edits,
"review1": review1_edits}
def main():
plan, root, group = sys.argv[1], pathlib.Path(sys.argv[2]), sys.argv[3]
blocks = read_blocks(plan)
edits = GROUPS[group](blocks)
texts = {}
for rel, old, new in edits:
text = texts.get(rel)
if text is None:
text = (root / rel).read_text(encoding="utf-8")
count = text.count(old)
if count != 1:
sys.exit(f"ABORT {rel}: anchor count {count} != 1: {old[:60]!r}")
texts[rel] = text.replace(old, new, 1)
for rel, text in texts.items():
(root / rel).write_text(text, encoding="utf-8")
print(f"applied {len(edits)} edits ({group})")
if __name__ == "__main__":
main()
+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.
+7
View File
@@ -162,6 +162,9 @@ file before anything else. Accepted set empty → stop.
GATE 0 runs every scanner oracle (the per-fix proof), GATE 1 a fresh
verifier, GATE 2 a fresh security-auditor. Loop caps and escalation are
the include's; loop decisions stay in this main loop.
Stuck: a gate loop fails twice with no main-loop advisor call since GATE 0
first ran → the main loop calls the advisor per `lib/verify-secure-loop.md`
(`lib/effort-shift.md` § Advisor); the answer never enters an executor brief.
## STEP 9: Re-pass (prove it all)
@@ -194,6 +197,10 @@ open and say so plainly. Never report a fix the re-pass did not prove.
```
Then `git add <files touched>` (never `-A`, never the baseline file) and
commit, project convention else 50 words at most.
Before the reply, 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 reply as an `Advisor:` line, and a fix it drives goes
back through the gates.
2. `mcp__model-router__route(phase="apply")` for the tail. Reply with: fixed
and proven (proposal, rule, file), still open and why, the walk's result,
the branch name. Merge waits for the user's explicit signal.
+5
View File
@@ -237,6 +237,11 @@ fix commits land inside it and get re-audited — safe overlap, by design.
## STEP 4 — FINAL SUMMARY
When the run applied a fix, before the summary, the main loop 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 calls for
waits for a new run.
```
AUDIT-DELTA COMPLETE — 2026-06-11
security : 3 findings → 2 fixed, 1 declined | marker → fbf3e26
+9
View File
@@ -200,6 +200,10 @@ Parse the `BUGFIX-EXEC REPORT`:
re-dispatch a FRESH bugfixer with the BLOCKING list + the CONTRACT
path; re-verify the request THEN re-scan, max 3 → escalate.
Stuck: a gate loop fails twice with no main-loop advisor call since GATE 0
first ran → the main loop calls the advisor per `lib/verify-secure-loop.md`
(`lib/effort-shift.md` § Advisor); the answer never enters an executor brief.
Loop decisions stay HERE, in the main loop (LRN-083). Nominal = one
executor + a free floor run + one verifier + one security dispatch.
@@ -227,6 +231,11 @@ Parse the `BUGFIX-EXEC REPORT`:
3. Commit after approval, message per `$HOME/.claude/lib/commit-message.md`
(project convention first, else short: root cause in the subject, at most
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.
4. Print summary:
```
BUGFIX COMPLETE
+9
View File
@@ -185,6 +185,10 @@ produced, `TEST` = the suite named in its report:
STEP 5. BLOCK → re-dispatch a FRESH feater with the BLOCKING list + the
CONTRACT path; re-verify the request THEN re-scan, max 3 → escalate.
Stuck: a gate loop fails twice with no main-loop advisor call since GATE 0
first ran → the main loop calls the advisor per `lib/verify-secure-loop.md`
(`lib/effort-shift.md` § Advisor); the answer never enters an executor brief.
Loop decisions stay HERE, in the main loop (LRN-083). Nominal (clear
request, conform first pass, clean diff) = one executor + a free floor
run + one verifier + one security dispatch.
@@ -202,6 +206,11 @@ commit-changer (propose opus / apply sonnet, BDR-077); never inline-load the bar
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.
Print summary:
```
FEAT COMPLETE
+7
View File
@@ -236,6 +236,9 @@ file before anything else. Accepted set empty → stop.
GATE 0 runs every scanner oracle (the per-fix proof), GATE 1 a fresh
verifier, GATE 2 a fresh security-auditor. Loop caps and escalation are
the include's; loop decisions stay in this main loop.
Stuck: a gate loop fails twice with no main-loop advisor call since GATE 0
first ran → the main loop calls the advisor per `lib/verify-secure-loop.md`
(`lib/effort-shift.md` § Advisor); the answer never enters an executor brief.
## STEP 11: Re-pass (prove it all)
@@ -271,6 +274,10 @@ open and say so plainly. Never report a fix the re-pass did not prove.
```
Then `git add <files touched>` (never `-A`, never the baseline file) and
commit, project convention else 50 words at most.
Before the reply, 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 reply as an `Advisor:` line, and a fix it drives goes
back through the gates.
2. `mcp__model-router__route(phase="apply")` for the tail. Reply with: fixed
and proven (proposal, rule, file), still open and why, MANUAL steps left
for the user, the branch name. Merge waits for the user's explicit signal.
+10
View File
@@ -267,6 +267,10 @@ deferred to a later /onboard) and turns the informal analyze into a verdict
against the founding contract. Distinct axis from STEP 10 code review
([[LRN-095]]) — both run.
Stuck: a gate loop fails twice with no main-loop advisor call since GATE 0
first ran → the main loop calls the advisor per `lib/verify-secure-loop.md`
(`lib/effort-shift.md` § Advisor); the answer never enters an executor brief.
## STEP 10 — CODE REVIEW
Invoke `requesting-code-review` (vendored superpowers skill). **Model routing (BDR-077):** the
review subagent it dispatches MUST carry `model: "opus"` and `effort="xhigh"` in the Agent call —
@@ -351,6 +355,12 @@ patched. Report per its rc table — rc 4 = a LOUD upstream BDR-022 anomaly, not
> patched docs on the MVP feature branch so they reach the merge.
## STEP 11 — FINISH
`mcp__model-router__route(phase="plan")` first (route: end-of-run review).
Before proposing the finish, 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 with the proposal as an `Advisor:` line, and a fix it
drives goes back through the gates.
Tests pass, build clean, no placeholders. Integrate the MVP feature into develop
— **only on the user's explicit go** (the `gitflow` finish gate):
```bash
+6
View File
@@ -76,6 +76,12 @@ Parse the `RELEASE-EXEC REPORT`:
- `STATUS: BLOCKED` → surface the blocker verbatim, STOP.
### STEP 4 — HUMAN GATE: when to release
`mcp__model-router__route(phase="reflect")` first (route: end-of-run review).
Before the ask, the main loop makes its
end-of-run advisor call (`lib/effort-shift.md` § Advisor); its answer
goes with the ask as an `Advisor:` line, and a fix it calls for makes
hold the recommended answer.
STOP. Show the prep report's `TESTS` result, then:
```
AskUserQuestion:
+10
View File
@@ -249,6 +249,10 @@ against the contract. It is a DISTINCT axis from STEP 6 code review (contract
conformity + security vs. craft/design) — both run, neither subsumes the
other ([[LRN-095]]).
Stuck: a gate loop fails twice with no main-loop advisor call since GATE 0
first ran → the main loop calls the advisor per `lib/verify-secure-loop.md`
(`lib/effort-shift.md` § Advisor); the answer never enters an executor brief.
## STEP 6 — CODE REVIEW
Invoke `requesting-code-review` (vendored superpowers skill). **Model routing (BDR-077):** the
review subagent it dispatches MUST carry `model: "opus"` and `effort="xhigh"` in the Agent call —
@@ -315,6 +319,12 @@ surfaced a forbidden path), not a silent skip. It runs BEFORE FINISH so the doc
on the branch FINISH integrates.
## STEP 9 — FINISH
`mcp__model-router__route(phase="plan")` first (route: end-of-run review).
Before proposing the finish, 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 with the proposal as an `Advisor:` line, and a fix it
drives goes back through the gates.
Tests pass, build clean. Integrate the feature into develop — **only on the
user's explicit go** (the `gitflow` finish gate):
```bash
+11 -2
View File
@@ -92,7 +92,8 @@ Agent(subagent_type="general-purpose",
prompt="Read ~/.claude/skills/tour/SKILL.md and execute STEP 1 → STEP 3
for EXACTLY ONE project: <absolute path>. Flags: <--report-only|none>.
Skip STEP 0/0b (routing) and the global summary — the dispatcher owns
them. Every rule of the skill applies unchanged: max 3 iterations,
them; never call the advisor. Every rule of the skill applies
unchanged: max 3 iterations,
never merge/finish/push main|develop, scoped commits, report appended to that
project's own .claude/audits/TOUR.md. Return EXACTLY: the project's
one-line global-summary row (STEP 3 format), then BRANCH: <name|no
@@ -104,7 +105,9 @@ The main loop then:
1. Collects each runner's summary row. A dead or mute runner becomes the
row `<path> : RUNNER FAILED — <reason> | no report` — never a silent
absence (a mute runner is NEVER a pass).
2. Prints the global summary (STEP 3 format) once ALL runners returned.
2. Once ALL runners returned: when any row reports a fix, makes the
STEP 3 end-of-run advisor call; then prints the global summary (STEP 3
format).
3. Runs the gated capitalize offer — MAIN LOOP ONLY, never inside a
runner: registries are shared state, and gate decisions stay here
(LRN-083).
@@ -261,6 +264,12 @@ order:
Checks: pytest PASS, ruff PASS. Residuals: SEC-2 (needs decision). Commits: 4. BREAKING: 1 (SEC-2).
```
Main loop only, never a runner: when the tour applied any fix, before
the global summary, the main loop 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 calls for
waits for a new run.
Global summary inline, one line per project (append `BREAKING: n` to
any project line with contract-changing fixes left open for decision):