diff --git a/docs/superpowers/plans/2026-11-17-advisor-points-b2.md b/docs/superpowers/plans/2026-11-17-advisor-points-b2.md deleted file mode 100644 index 5d141b0..0000000 --- a/docs/superpowers/plans/2026-11-17-advisor-points-b2.md +++ /dev/null @@ -1,395 +0,0 @@ -# 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 && sa80' | 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:`; 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 `+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 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 &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 &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/.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. diff --git a/docs/superpowers/plans/2026-11-17-advisor-points-b2/apply.py b/docs/superpowers/plans/2026-11-17-advisor-points-b2/apply.py deleted file mode 100644 index a2f7080..0000000 --- a/docs/superpowers/plans/2026-11-17-advisor-points-b2/apply.py +++ /dev/null @@ -1,183 +0,0 @@ -#!/usr/bin/env python3 -"""Apply run B2 blocks to a repo root. - -Usage: apply.py -Blocks are read from the plan (### Block + 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:`; a raised one keeps its own line, its\n" - " rule/check becoming `+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" - " 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()