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
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 <files touched>` (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.
+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
+7
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,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
+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
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
+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
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 <files touched>` (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.
+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
([[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
+5
View File
@@ -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:
+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
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
+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):