Skip to content

feat(v3): exemptions + CI awareness + round tracking + audit-paths prompt#8

Merged
ashbrener merged 1 commit into
mainfrom
feat/wingman-v3-exemptions-and-ci-awareness
Apr 30, 2026
Merged

feat(v3): exemptions + CI awareness + round tracking + audit-paths prompt#8
ashbrener merged 1 commit into
mainfrom
feat/wingman-v3-exemptions-and-ci-awareness

Conversation

@ashbrener

Copy link
Copy Markdown
Owner

Summary

Four upgrades to the codex-review pre-push hook (hook version stamp 2 -> 3):

  • Exemption file (.wingman-exemptions.yaml) — codex sees ratified out-of-scope decisions and stops re-flagging them. Sample shipped at assets/.wingman-exemptions.yaml.sample; installer copies it to the user's repo as .wingman-exemptions.yaml.sample (NEVER auto-creates the active file).
  • CI status awareness — after the review, hook calls gh pr checks and prepends a synthetic [P1] finding if a required check is RED, so the next remediation round addresses CI-red instead of bandaging code that's locally green.
  • Round tracking + convergence detection.reviews/_convergence.json ledger; emits [CONVERGENCE NOTICE] when the stop-rule fires (0 P1 + <=2 P2 for 2 consecutive rounds) or [STAGNATION ALERT] when the same finding flags twice in a row.
  • Audit-related-paths prompt — codex now audits code paths importing from / imported by the changed modules in the same review, surfacing same-class defects together.

Rationale

Direct lessons from project-arc spec 004's 12-round wingman convergence. Each gap was felt for 3+ rounds before being addressed by hand:

Round Pain
1-3 Codex re-flagged "preserve old import paths via shims" 3 times despite constitution v0.1.3 rejecting it -> Feature 1
All 12 quality-gate required check was red the entire time, wingman never noticed -> Feature 2
1-12 No "are we done yet?" signal -> Feature 3
4-8 Each fix introduced 1-2 same-class bugs in neighbouring files codex saw next round -> Feature 4

Full feature write-up: docs/wingman-v3-features.md. Schema bump documented in README.

Test plan

  • CI green: lint (shellcheck), syntax (bash -n + py_compile of both embedded heredocs), install-smoke (6 scenarios — fresh / v1->v3 upgrade / v2->v3 upgrade / --force / exemption parsing / convergence ledger schema)
  • Local: bash -n scripts/install.sh && bash -n assets/pre-push.sample -> clean
  • Local: shellcheck --severity=error on both -> clean
  • Local: v2 -> v3 upgrade in tmp repo via install.sh -> v3 marker present, exactly 1 wingman block, exemption sample copied
  • Local: exemption file parsed without PyYAML; rendered prompt includes id + rationale + banner
  • Local: _convergence.json schema matches spec — branch, rounds[], convergence{stop_rule, trend, stagnation}; stop-rule fires correctly at round 3 of 0,0,0 P1
  • Manual: install on a real consumer (project-arc) post-merge and run a real codex review with a populated .wingman-exemptions.yaml

Stays DRAFT

This PR stays DRAFT per workflow policy — only the human un-drafts after review.

Four upgrades to the codex-review pre-push hook based on lessons from
spec 004's 12-round wingman convergence on project-arc:

1. Exemption file (.wingman-exemptions.yaml) — codex skips findings
   ratified out-of-scope by the project. Saves 30-50% of late-round
   noise where codex re-flags decisions like "preserve old import
   paths via shims" that conflict with constitutional rules.

2. CI status awareness — hook calls gh pr checks after the review;
   prepends a synthetic P1 finding if required-status-check is RED.
   Catches "wingman happy, CI screaming" pattern (12 rounds of
   undetected test failure on spec 004).

3. Round tracking + convergence detection — .reviews/_convergence.json
   ledger; emits [CONVERGENCE NOTICE] when stop-rule met (0 P1 +
   bounded P2 for 2 consecutive rounds) or [STAGNATION ALERT] when
   same finding flagged 2 rounds in a row.

4. Audit-related-paths prompt — codex prompt extended to audit code
   paths importing from / imported by the changed files for the
   same defect class. Bigger per-round prompts -> fewer total rounds.

Hook version bumped 2->3. Installer's idempotent block-replacer
upgrades v2 hooks in place. Sample exemption file at
assets/.wingman-exemptions.yaml.sample for users to copy.

CI smoke test extended: v2->v3 upgrade scenario, exemption parsing,
_convergence.json schema validation.
@ashbrener ashbrener marked this pull request as ready for review April 30, 2026 05:34
@ashbrener ashbrener merged commit fb82fed into main Apr 30, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant