feat(merge-retrospective): auto-fill retrospective stubs on issue open

[tvna]

Summary

Adds .github/workflows/merge-retrospective-autofill.yml, an
issues: opened/labeled-triggered anthropics/claude-code-action@v1
dispatch that runs skills/merge-retrospective/SKILL.md's content-filling
procedure against a freshly-opened bare stub retrospective issue, so the
retrospective actually gets filled in without depending on an agent
remembering to invoke the skill or a human asking.

Facts

• skills/merge-retrospective/SKILL.md's own trigger is a description
  string with no deterministic enforcement; .github/scripts/gitapex_post_merge_retro.py
  already opens a bare, marker-text-carrying, retrospective-labelled stub
  for every merged PR unattended, but nothing previously filled it in
  short of an interactive session remembering to, or a human explicitly
  asking (as happened for PR refactor(skill-metadata): dedupe find_requires_cycle with its test #762 -> issue chore(retrospective): merge retrospective for PR #762 #763).
• .github/workflows/ranking-the-open-queue-weekly.yml already ships a
  working blueprint for a headless anthropics/claude-code-action@v1
  dispatch from GitHub Actions using the existing secrets.ANTHROPIC_API_KEY
  (already provisioned, documented in CONTRIBUTING.md) and a local
  ghcr.io/github/github-mcp-server container fed secrets.GITHUB_TOKEN.
  This PR reuses that exact pattern -- no new secret.
• New workflow triggers on issues: opened/labeled (not a scheduled
  sweep) so it fires the instant gitapex_post_merge_retro.py's own stub-creating
  POST succeeds -- see the design doc's "Decision" section for why this is
  both faster and simpler than a cron-based race against that same event.
  workflow_dispatch (with an issue_number input) covers manual
  recovery from a missed webhook.
• Permissions: contents: read, issues: write only, both workflow- and
  job-level -- no pull-requests: write anywhere. claude_args: --allowedTools lists exactly five read/issue-scoped tools
  (mcp__github__issue_read, mcp__github__issue_write,
  mcp__github__search_issues, mcp__github__search_commits,
  mcp__github__pull_request_read) and excludes every merge-capable tool.
  A deterministic job-level if: pre-filter (the same stub-marker literal
  gitapex_stale_retro_stub_autoclose.py already uses) means the agent step never
  runs at all for an already-enriched issue or an unrelated
  retrospective-labelled issue.
• python3 .github/scripts/gitapex_gate_routine_scope_enforcement.py --skills-root skills docs/superpowers/specs/2026-08-05-merge-retrospective-autofill-routine.md
  -> PASS (the design doc cites the --allowedTools allowlist above as
  its concrete scoping mechanism for skills/merge-retrospective's
  declared capabilityAssumption: Broad).
• actionlint v1.7.12 (matching .github/workflows/lint.yml's pinned
  version) against every file in .github/workflows/ -> clean, zero
  findings.
• python3 .github/scripts/gitapex_gate_hidden_characters.py -> OK, no
  hidden characters in any tracked file.
• python3 .github/scripts/gitapex_gate_provenance_disclosure.py --diff-added docs/superpowers/specs/2026-08-05-merge-retrospective-autofill-routine.md
  -> PASS.
• uv run pytest -q (full suite, including the 6 new drift-guard tests in
  tests/test_gitapex_merge_retrospective_autofill.py) -> 2683 passed.
• uv run mypy .github/scripts tests hooks skills/battle-testing-a-skill/scripts skills/scorer-gated-skill-edits/scripts skills/evaluating-skill-quality/scripts skills/auditing-agent-product-scope/scripts evals/scripts
  -> Success: no issues found in 120 source files (the new test module is
  added to pyproject.toml's existing Tier B untyped-test-module
  allowlist, matching every other tests/*.py file's own established
  convention -- none of them carry return-type annotations either).
• uv run ruff check . and uv run ruff format --check . -> both clean.
• Checked live workflow-run history for ranking-the-open-queue-weekly.yml
  via mcp__github__actions_list (2026-08-05): every run 2026-07-28
  through 2026-08-03 failed fast (~15-30s), the same shape that doc's own
  2026-07-28 investigation root-caused to an Anthropic Console billing
  block ("Credit balance is too low"). This PR's new workflow reuses the
  identical ANTHROPIC_API_KEY, so its first live dispatch is exposed to
  the same pre-existing, external, owner-side blocker -- disclosed
  explicitly in the design doc's "Status" section rather than glossed
  over, per this repository's live-proof-over-plan-time-intent standard.
• Attempted a real pre-merge live-proof dispatch (with explicit user
  go-ahead): mcp__github__actions_run_trigger run_workflow against
  merge-retrospective-autofill.yml on this branch, targeting real open
  bare-stub issue chore(retrospective): merge retrospective for PR #747 #751. It failed with 404 Not Found on the dispatch
  call itself -- confirms GitHub's documented behavior that
  workflow_dispatch only recognizes a workflow once it exists on the
  repository's default branch. Live verification (either via a real PR
  merge or a post-merge workflow_dispatch) is only reachable after this
  PR merges, not before -- see the design doc's "Status" section, updated
  with this finding.

Assumptions

• (Speculation, flagged as such in the design doc too) The Anthropic
  Console billing block observed through 2026-08-03 is still in effect as
  of this PR -- this session did not re-run ranking-the-open-queue-weekly.yml
  with show_full_output: true to re-confirm the exact current error
  shape, since re-enabling that flag for a check not otherwise needed
  would be unnecessary output exposure. The identical fast-failure shape
  across every run to date is the basis for this inference, not a
  freshly-observed error message.
• issues: opened/labeled webhook delivery is reliable enough in
  practice that a pure event trigger (no scheduled backstop) satisfies
  issue feat(merge-retrospective): trigger retrospective content-fill automatically on PR merge, without relying on agent memory #769's "runs shortly after its stub is opened" criterion; the
  existing stale-retro-stub-autoclose.yml 48h close remains the ultimate
  fallback if a webhook is ever missed, which is pre-existing degraded
  behavior this PR does not change.

Risk / blast radius

Low-to-moderate. The new workflow can only read a PR's history and
read/update one already-open issue (issues: write, no
pull-requests: write, no merge-capable tool in its --allowedTools
list) -- worst case on a prompt-injection attempt from untrusted PR/issue
content is a wrongly-classified repair entry in a retrospective issue
body, not a repository-write or merge action. If the workflow
misbehaves, disabling it (or reverting this PR) leaves the pre-existing
behavior (bare stub, closed after 48h by stale-retro-stub-autoclose.yml)
fully intact -- no other workflow depends on this one.

Rollback

git revert this PR's merge commit. No secrets, schema, or persisted
state are introduced (the workflow reuses the existing ANTHROPIC_API_KEY
and GITHUB_TOKEN); reverting removes the workflow file, the design doc,
the CONTRIBUTING.md cross-reference, the new test file, and its
pyproject.toml mypy-override entry, with no follow-up steps.

Verification

Issue #769's Acceptance Criteria Map, restated:

Criterion	Proof method	Result
Every merged PR's retrospective gets its content filled in automatically, without a human having to ask	For N consecutive merged PRs going forward, each auto-opened stub is enriched within a bounded time window, with zero explicit "fill in the retro"-style prompts	Mechanism shipped; live proof not yet observed. A pre-merge workflow_dispatch attempt against issue #751 confirmed this is not reachable before merge (GitHub 404s a dispatch for a workflow not yet on the default branch); the shared ANTHROPIC_API_KEY may also still carry the pre-existing billing block described above. See the design doc's "Status" section for the full finding and the recommended post-merge verification step.
Must not weaken the 100%-human-merge policy	Review the workflow's permissions: and --allowedTools (both reproduced in the design doc and this PR body)	Met, reviewable now: issues: write only; --allowedTools lists five read/issue-scoped tools, no merge-capable one; tests/test_gitapex_merge_retrospective_autofill.py::test_workflow_never_grants_pull_requests_write and ::test_workflow_has_no_merge_capable_step both pass and will fail CI on any future regression.
Don't duplicate issue #728's backlog-reduction work	This PR touches only the invocation mechanism for newly opened stubs, not existing retrospective issues	Met by construction -- no existing issue is read, closed, or modified by this change.

Skill audit evidence

• design-doc-adversarial-review: RAN -- read docs/superpowers/specs/2026-08-05-merge-retrospective-autofill-routine.md
  against gitapex_gate_routine_scope_enforcement.py's actual scoping-citation
  requirements (confirmed PASS above, not assumed), cross-checked its
  factual claims against live GitHub Actions run history for
  ranking-the-open-queue-weekly.yml rather than trusting the prior design
  doc's own account, and revised the workflow's prompt wording after
  discovering that a literal mcp__github__merge_pull_request mention (a
  legitimate prohibition) would otherwise falsely trip a substring-based
  merge-capability drift test -- caught during this same review pass, not
  after the fact.

Checklist

• Tests pass locally (uv run pytest -q -> 2683 passed)
• Docs updated: new design doc, CONTRIBUTING.md cross-reference
• Issue number cited in every commit
• N/A -- no skills/*/SKILL.md touched, only a new design doc (see Skill audit evidence above)
• N/A -- no evals/*/split.md Kept-edit-log entry added
• N/A -- no skills/*/SKILL.md Stop-boundary bullet or dispatch branch added or increased

Related Issue

Closes #769

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.88%. Comparing base (03948d6) to head (66b5832).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #775   +/-   ##
=======================================
  Coverage   98.87%   98.88%           
=======================================
  Files          60       60           
  Lines       11324    11392   +68     
=======================================
+ Hits        11197    11265   +68     
  Misses        127      127           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.