docs(doctrine): advisor stuck trigger in gate skills, end-of-run call in code flows

This commit is contained in:
bchanot committed 2026-11-17 18:08:37 +01:00
1 parent b11d642841
commit f48343e2d7
9 files changed
+66 -2

No files matched your search

+6
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 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 verifier, GATE 2 a fresh security-auditor. Loop caps and escalation are
the include's; loop decisions stay in this main loop. 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) ## 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 <files touched>` (never `-A`, never the baseline file) and Then `git add <files touched>` (never `-A`, never the baseline file) and
commit, project convention else 50 words at most. 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 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, and proven (proposal, rule, file), still open and why, the walk's result,
the branch name. Merge waits for the user's explicit signal. 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 ## 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 AUDIT-DELTA COMPLETE — 2026-06-11
security : 3 findings → 2 fixed, 1 declined | marker → fbf3e26 security : 3 findings → 2 fixed, 1 declined | marker → fbf3e26
+7
View File
@@ -200,6 +200,10 @@ Parse the `BUGFIX-EXEC REPORT`:
re-dispatch a FRESH bugfixer with the BLOCKING list + the CONTRACT re-dispatch a FRESH bugfixer with the BLOCKING list + the CONTRACT
path; re-verify the request THEN re-scan, max 3 → escalate. 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 Loop decisions stay HERE, in the main loop (LRN-083). Nominal = one
executor + a free floor run + one verifier + one security dispatch. 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` 3. Commit after approval, message per `$HOME/.claude/lib/commit-message.md`
(project convention first, else short: root cause in the subject, at most (project convention first, else short: root cause in the subject, at most
two sentences of body). 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: 4. Print summary:
``` ```
BUGFIX COMPLETE BUGFIX COMPLETE
+8
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 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. 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 Loop decisions stay HERE, in the main loop (LRN-083). Nominal (clear
request, conform first pass, clean diff) = one executor + a free floor request, conform first pass, clean diff) = one executor + a free floor
run + one verifier + one security dispatch. 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). propose/apply executor).
Then `mcp__model-router__route(phase="reflect")` (route: nested commit-change loaded at apply; reload feat's level). 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: Print summary:
``` ```
FEAT COMPLETE FEAT COMPLETE
+6
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 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 verifier, GATE 2 a fresh security-auditor. Loop caps and escalation are
the include's; loop decisions stay in this main loop. 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) ## 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 <files touched>` (never `-A`, never the baseline file) and Then `git add <files touched>` (never `-A`, never the baseline file) and
commit, project convention else 50 words at most. 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 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 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. for the user, the branch name. Merge waits for the user's explicit signal.
+9
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 against the founding contract. Distinct axis from STEP 10 code review
([[LRN-095]]) — both run. ([[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 ## STEP 10 — CODE REVIEW
Invoke `requesting-code-review` (vendored superpowers skill). **Model routing (BDR-077):** the 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 — 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. > patched docs on the MVP feature branch so they reach the merge.
## STEP 11 — FINISH ## 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 Tests pass, build clean, no placeholders. Integrate the MVP feature into develop
— **only on the user's explicit go** (the `gitflow` finish gate): — **only on the user's explicit go** (the `gitflow` finish gate):
```bash ```bash
+5
View File
@@ -76,6 +76,11 @@ Parse the `RELEASE-EXEC REPORT`:
- `STATUS: BLOCKED` → surface the blocker verbatim, STOP. - `STATUS: BLOCKED` → surface the blocker verbatim, STOP.
### STEP 4 — HUMAN GATE: when to release ### 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: STOP. Show the prep report's `TESTS` result, then:
``` ```
AskUserQuestion: AskUserQuestion:
+9
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 conformity + security vs. craft/design) — both run, neither subsumes the
other ([[LRN-095]]). 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 ## STEP 6 — CODE REVIEW
Invoke `requesting-code-review` (vendored superpowers skill). **Model routing (BDR-077):** the 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 — 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. on the branch FINISH integrates.
## STEP 9 — FINISH ## 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 Tests pass, build clean. Integrate the feature into develop — **only on the
user's explicit go** (the `gitflow` finish gate): user's explicit go** (the `gitflow` finish gate):
```bash ```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 prompt="Read ~/.claude/skills/tour/SKILL.md and execute STEP 1 → STEP 3
for EXACTLY ONE project: <absolute path>. Flags: <--report-only|none>. for EXACTLY ONE project: <absolute path>. Flags: <--report-only|none>.
Skip STEP 0/0b (routing) and the global summary — the dispatcher owns 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 never merge/finish/push main|develop, scoped commits, report appended to that
project's own .claude/audits/TOUR.md. Return EXACTLY: the project's project's own .claude/audits/TOUR.md. Return EXACTLY: the project's
one-line global-summary row (STEP 3 format), then BRANCH: <name|no 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 1. Collects each runner's summary row. A dead or mute runner becomes the
row `<path> : RUNNER FAILED — <reason> | no report` — never a silent row `<path> : RUNNER FAILED — <reason> | no report` — never a silent
absence (a mute runner is NEVER a pass). 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 3. Runs the gated capitalize offer — MAIN LOOP ONLY, never inside a
runner: registries are shared state, and gate decisions stay here runner: registries are shared state, and gate decisions stay here
(LRN-083). (LRN-083).
@@ -261,6 +264,12 @@ order:
Checks: pytest PASS, ruff PASS. Residuals: SEC-2 (needs decision). Commits: 4. BREAKING: 1 (SEC-2). 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 Global summary inline, one line per project (append `BREAKING: n` to
any project line with contract-changing fixes left open for decision): any project line with contract-changing fixes left open for decision):