From f48343e2d74e78af3a3ca5ff6ecc1e66dd1e87af Mon Sep 17 00:00:00 2001 From: bchanot Date: Tue, 17 Nov 2026 18:08:37 +0100 Subject: [PATCH] docs(doctrine): advisor stuck trigger in gate skills, end-of-run call in code flows --- skills/a11y/SKILL.md | 6 ++++++ skills/audit-delta/SKILL.md | 5 +++++ skills/bugfix/SKILL.md | 7 +++++++ skills/feat/SKILL.md | 8 ++++++++ skills/guardrails/SKILL.md | 6 ++++++ skills/init-project/SKILL.md | 9 +++++++++ skills/release-candidate/SKILL.md | 5 +++++ skills/ship-feature/SKILL.md | 9 +++++++++ skills/tour/SKILL.md | 13 +++++++++++-- 9 files changed, 66 insertions(+), 2 deletions(-) diff --git a/skills/a11y/SKILL.md b/skills/a11y/SKILL.md index fa0c3ea..cdd79ab 100644 --- a/skills/a11y/SKILL.md +++ b/skills/a11y/SKILL.md @@ -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,9 @@ open and say so plainly. Never report a fix the re-pass did not prove. ``` Then `git add ` (never `-A`, never the baseline file) and commit, project convention else 50 words at most. + 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. 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. diff --git a/skills/audit-delta/SKILL.md b/skills/audit-delta/SKILL.md index 95de729..624bdeb 100644 --- a/skills/audit-delta/SKILL.md +++ b/skills/audit-delta/SKILL.md @@ -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 diff --git a/skills/bugfix/SKILL.md b/skills/bugfix/SKILL.md index 1208f8b..4cec813 100644 --- a/skills/bugfix/SKILL.md +++ b/skills/bugfix/SKILL.md @@ -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,9 @@ 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). + 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. 4. Print summary: ``` BUGFIX COMPLETE diff --git a/skills/feat/SKILL.md b/skills/feat/SKILL.md index f6cedfc..030659e 100644 --- a/skills/feat/SKILL.md +++ b/skills/feat/SKILL.md @@ -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,10 @@ 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 makes its +end-of-run advisor call (`lib/effort-shift.md` § Advisor); its answer +goes into the summary as an `Advisor:` line. + Print summary: ``` FEAT COMPLETE diff --git a/skills/guardrails/SKILL.md b/skills/guardrails/SKILL.md index 7ab339c..0a39711 100644 --- a/skills/guardrails/SKILL.md +++ b/skills/guardrails/SKILL.md @@ -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,9 @@ open and say so plainly. Never report a fix the re-pass did not prove. ``` Then `git add ` (never `-A`, never the baseline file) and commit, project convention else 50 words at most. + 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. 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. diff --git a/skills/init-project/SKILL.md b/skills/init-project/SKILL.md index 1f5d501..4d9b3cc 100644 --- a/skills/init-project/SKILL.md +++ b/skills/init-project/SKILL.md @@ -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,11 @@ 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 makes its +end-of-run advisor call (`lib/effort-shift.md` § Advisor); its answer +goes with the proposal as an `Advisor:` line. + Tests pass, build clean, no placeholders. Integrate the MVP feature into develop — **only on the user's explicit go** (the `gitflow` finish gate): ```bash diff --git a/skills/release-candidate/SKILL.md b/skills/release-candidate/SKILL.md index 08e9be5..4f2282b 100644 --- a/skills/release-candidate/SKILL.md +++ b/skills/release-candidate/SKILL.md @@ -76,6 +76,11 @@ 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; a fix it calls for means hold. + STOP. Show the prep report's `TESTS` result, then: ``` AskUserQuestion: diff --git a/skills/ship-feature/SKILL.md b/skills/ship-feature/SKILL.md index ecf8ba4..4e24f6f 100644 --- a/skills/ship-feature/SKILL.md +++ b/skills/ship-feature/SKILL.md @@ -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,11 @@ 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 makes its +end-of-run advisor call (`lib/effort-shift.md` § Advisor); its answer +goes with the proposal as an `Advisor:` line. + Tests pass, build clean. Integrate the feature into develop — **only on the user's explicit go** (the `gitflow` finish gate): ```bash diff --git a/skills/tour/SKILL.md b/skills/tour/SKILL.md index 5b5e6a9..c8e02e6 100644 --- a/skills/tour/SKILL.md +++ b/skills/tour/SKILL.md @@ -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: . 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: : RUNNER FAILED — | 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):