ci: let medium-confidence triages auto-fire propose-fix and write-docs

[bpamiri]

Summary

• Widen the auto-fire gate on bot-propose-fix.yml and bot-write-docs.yml so medium-confidence triage / research / docs-request markers fire the next stage. Low-confidence still stays manual.
• Triage and research prompts now emit a :medium marker alongside :high.
• The triage auto-downgrade rules are preserved as informational metadata; medium ratings auto-fire, but propose-fix.md step 4 and write-docs.md step 4 (the existing sensitive-area safety nets) keep the actual halt.

Why

Previously the gate doubled as a halt: medium meant "don't auto-fire," which stopped useful work on ambiguous-but-actionable issues. Reviewer A and Reviewer B (with the Senior Advisor on deadlock) are better suited to filter borderline fixes than the triage rating is. Human approval on develop is still the merge gate, so nothing merges autonomously.

Files

• .github/workflows/bot-propose-fix.yml — if: now accepts triage-confidence:high|medium and research-confidence:high|medium
• .github/workflows/bot-write-docs.yml — if: now accepts docs-confidence:high|medium
• .claude/commands/triage-issue.md — emits :medium marker for medium-confidence triages (docs-request + bug paths)
• .claude/commands/research-frameworks.md — emits :medium marker for medium-confidence research
• CLAUDE.md + docs/contributing/wheels-bot.md — pipeline table, marker conventions, and narrative updated

Test plan

Propose-fix path (bug + framework-design)

• YAML parses (verified locally with PyYAML).
• Real medium-confidence bug triage fires bot-propose-fix.yml from the bot's :medium marker comment.
• Sensitive-area medium triage (security / middleware / migrations / deploy / DI / cross-engine) produces a wheels-bot:fix-held:<issue> comment from propose-fix's step-4 safety net, not a draft PR.
• Real medium-confidence research comment fires bot-propose-fix.yml on the framework-design path.
• Low-confidence bug + research triages remain manual (no auto-fire).

Write-docs path (docs-request)

• Real medium-confidence docs-request triage fires bot-write-docs.yml from the bot's :medium marker comment.
• Structural-docs-decision medium triage (>5 files, new top-level section, significant code-reading needed) produces a wheels-bot:docs-held:<issue> comment from write-docs's step-4 safety net, not a draft PR.
• Low-confidence docs-request triages remain manual (no auto-fire).

🤖 Generated with Claude Code

[wheels-bot]

Wheels Bot - Reviewer A

This PR widens the bot auto-fire gate so that medium-confidence triage, research, and docs-request markers trigger propose-fix and write-docs, with low-confidence remaining manual. The design is sound and the YAML condition logic is correct. I verified the propose-fix and write-docs safety nets directly and they exist and are appropriately scoped. Overall verdict: comment (one documentation inaccuracy, no blocking issues).

---

Correctness

The if: conditions in both workflows are correctly structured. The new ||contains() clauses are grouped inside the existing parenthesised block, the bot-identity check (github.event.comment.user.login == wheels-bot[bot]) is preserved on both, and the concurrency group uses cancel-in-progress: false so a double-trigger from the same issue serialises rather than races.

The idempotency skip-check looks for wheels-bot:fix:ISSUE / wheels-bot:fix-held:ISSUE (propose-fix) and wheels-bot:write-docs:ISSUE / wheels-bot:docs-held:ISSUE (write-docs), so a medium-confidence trigger that fires after a high-confidence run on the same issue is correctly skipped.

I read propose-fix.md and write-docs.md directly. The propose-fix step-4 safety net covers: vendor/wheels/security/**, auth flows, migrator files, deploy subsystem, DI container, and cross-engine concerns - it posts fix-held and exits before opening any PR. The write-docs step-4 safety net covers: scope greater than 5 files, new top-level sections, and significant code-reading requirements. Both are robust.

---

Docs

Documentation inaccuracy: wrong step number for the write-docs safety net.

.github/workflows/bot-write-docs.yml post-diff header comment says "write-docs has its own step-2 safety net for structural docs-architecture decisions." The PR description repeats this: "propose-fix.md step 4 and write-docs step 2 (the existing sensitive-area safety nets)."

The safety net in write-docs.md is at step 4 (Auto-downgrade safety net), not step 2. Step 2 is "Read the authoritative context." The propose-fix.md step 4 citation is correct.

The practical risk is low - the safety net exists and fires correctly - but a maintainer debugging a docs-held outcome who searches for "step 2" will not find it.

Suggested fix: change "step-2" to "step-4" in the bot-write-docs.yml header comment.

---

Commits

Single commit: type ci, no scope, subject within 100 chars, not ALL-CAPS. Passes commitlint.

---

Security

The bot-identity check that prevents a human from triggering propose-fix or write-docs by quoting a marker in a reply comment is preserved unchanged in both workflows. No regression.

[bpamiri]

Thanks for the catch — you're right that the write-docs safety net is at step 4 (step 2 is "Read the authoritative context"). Fixed in 6c08f86:

• bot-write-docs.yml header comment: step-2 → step-4
• docs/contributing/wheels-bot.md marker-table row for docs-confidence:medium now also says step-4, symmetrical with the triage-confidence:medium row that already cited step-4

Also corrected the same slip in the PR description. No behavior change — just documentation accuracy.

[wheels-bot]

Wheels Bot — Reviewer B (round 1)

A's review is clean. The step-2/step-4 finding is accurate (verified: write-docs.md step 2 is "Read the authoritative context"; step 4 is "Auto-downgrade safety net"), and A correctly held off request-changes for a comment-level inaccuracy. One additional missed issue on the test plan.

Sycophancy

None detected. A found a real issue and justified the COMMENTED verdict without LGTM-ing over it.

False positives

None detected. A's step-number claim is accurate — .claude/commands/write-docs.md line 55 confirms step 4 is the auto-downgrade safety net. The proposed fix (change step-2 to step-4 in .github/workflows/bot-write-docs.yml line 6) is correct.

Missed issues

• Test plan has no write-docs coverage. The PR description's test plan verifies the propose-fix path (medium triage fires, sensitive-area gives fix-held, low stays manual) but has no equivalent for the write-docs path: no item for "medium docs-confidence fires write-docs" and no item for "structural docs decision gives docs-held instead of a PR." The code in bot-write-docs.yml is correct, but someone clearing the checklist could miss both scenarios entirely.

Verdict alignment

A's COMMENTED verdict (one documentation inaccuracy, no blocking code issues) is consistent with the findings.

Convergence

Aligned on the only required code change: fix step-2 to step-4 in .github/workflows/bot-write-docs.yml:6. The test plan gap is a real omission but does not affect the correctness of the implementation and does not change the convergence outcome. Joint recommendation: apply A's fix.

[wheels-bot]

Wheels Bot — Reviewer A

This is a follow-up review on commit 6c08f86 (addressing the single finding from the prior review at 5a8e080). The commit corrects two documentation references that cited write-docs's structural-docs safety net as "step-2" when the actual step in .claude/commands/write-docs.md is step 4 ("Auto-downgrade safety net"). No behavioral change.

TL;DR: The one doc-inaccuracy finding from the previous review is correctly resolved. The commit is minimal and accurate. No new issues. Approving.

---

Correctness

The fix is exact. .claude/commands/write-docs.md step 4 is confirmed as "Auto-downgrade safety net" — the halt that posts docs-held instead of opening a PR. The previous "step-2" label pointed readers at "Read the authoritative context," which is unrelated. Both changed lines:

.github/workflows/bot-write-docs.yml, top-of-file comment:

-# write-docs has its own step-2 safety net for structural docs-architecture
+# write-docs has its own step-4 safety net for structural docs-architecture

docs/contributing/wheels-bot.md, marker reference table:

-| ... | Structural docs decisions are caught by write-docs's safety net. |
+| ... | Structural docs decisions are caught by write-docs's step-4 safety net. |

Both are now symmetric with the propose-fix row, which cited "step-4" since the prior commit.

---

Commits

Single commit: type ci, no scope, subject <= 100 chars, not ALL-CAPS. Has Signed-off-by trailer. Passes commitlint. Commit message explains the "why" (Reviewer A finding), not just the "what."

[bpamiri]

Thanks for the second look. Both findings are now addressed:

• A's step-number fix (step-2 → step-4 in bot-write-docs.yml): landed in 6c08f86.
• B's missed-issue on test plan: PR description's test plan is now split into a Propose-fix path section (kept the existing 3 items + added a research-path item) and a new Write-docs path section covering the docs-confidence:medium auto-fire, the structural-docs docs-held safety net, and the low-confidence manual case. Both auto-fire chains now have symmetrical verification.

No code change for the test-plan addition — it's a description-only edit. The code consensus from round 1 is already in.

[wheels-bot]

Wheels Bot — Reviewer B (round 1)

A's review of commit 6c08f86 is clean. The step-4 verification is confirmed (write-docs.md line 55: "Auto-downgrade safety net"; step 2 is "Read the authoritative context" — A's claim is accurate). No issues with the commit. Aligning on approve.

Sycophancy

None detected. A verified the actual file before approving rather than rubber-stamping the human's fix.

False positives

None detected. A's claim that step 4 is the auto-downgrade safety net is accurate — confirmed directly in .claude/commands/write-docs.md line 55.

Missed issues

None detected. The commit is two documentation lines only. Commit type ci is correct, subject is ≤100 chars and not ALL-CAPS, Signed-off-by is present. No behavior change, no cross-engine concerns, no security surface.

Verdict alignment

A's APPROVED verdict is consistent with the findings — one accurate doc fix, nothing blocking.

Convergence

Aligned. A's approval is correct and there are no remaining open findings. Joint recommendation: approve and merge.