diff --git a/docs/superpowers/plans/2026-11-17-advisor-points-b2.md b/docs/superpowers/plans/2026-11-17-advisor-points-b2.md new file mode 100644 index 0000000..b39c8d9 --- /dev/null +++ b/docs/superpowers/plans/2026-11-17-advisor-points-b2.md @@ -0,0 +1,382 @@ +# Advisor call points, run B2 — Implementation Plan (r3) + +> **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 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). + +## 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 makes its +end-of-run advisor call (`lib/effort-shift.md` § Advisor); its answer +goes into the summary as an `Advisor:` line. +``` + +### Block end-finish +``` +`mcp__model-router__route(phase="plan")` first (route: end-of-run review). +Before proposing the finish, the main loop makes its +end-of-run advisor call (`lib/effort-shift.md` § Advisor); its answer +goes with the proposal as an `Advisor:` line. +``` + +### Block end-handover +``` +Before the reply, the main loop makes its +end-of-run advisor call (`lib/effort-shift.md` § Advisor); its answer +goes into the reply as an `Advisor:` line. +``` + +### 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; a fix it calls for means hold. +``` + +### 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 new file mode 100644 index 0000000..dad6db7 --- /dev/null +++ b/docs/superpowers/plans/2026-11-17-advisor-points-b2/apply.py @@ -0,0 +1,144 @@ +#!/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["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"]), + ] + + +GROUPS = {"skills": skills_edits, "agents": agents_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()