docs: design — shadow-review auto-merge gate + daily ship-report #404

Merged

joshtronic merged 2 commits from design/automerge-review-gate-shipreport into master

2026-07-20 21:51:56 +00:00

igor commented

2026-07-20 21:39:34 +00:00

Collaborator

Design doc for the shadow-review auto-merge gate + daily ship-report (the "get Josh out of the per-PR loop safely" project).

Please review the design here before we write the implementation plan. Nothing is implemented yet — this is the spec.

Key decisions captured:

Review-gate selector via agent.json automerge.require_human (carve-outs = joshing.you, igor.bot; igor kept never-merge via no smoke.url + AUTOMERGE_SELF_REPO).
Shadow APPROVE-only gates the default; COMMENT still routes to you; all existing CI/mergeable/behind/RC gates unchanged.
Flags-first rollout order (no window where a carve-out is unflagged but the logic is live).
Scripted daily ship-report: needs-you / shipped (tagged shadow-vs-you) / in-flight; runs above the health gate.

Spec: docs/superpowers/specs/2026-07-20-automerge-review-gate-and-ship-report-design.md

Design doc for the shadow-review auto-merge gate + daily ship-report (the "get Josh out of the per-PR loop safely" project). **Please review the design here before we write the implementation plan.** Nothing is implemented yet — this is the spec. Key decisions captured: - Review-gate selector via `agent.json` `automerge.require_human` (carve-outs = joshing.you, igor.bot; igor kept never-merge via no smoke.url + `AUTOMERGE_SELF_REPO`). - Shadow `APPROVE`-only gates the default; `COMMENT` still routes to you; all existing CI/mergeable/behind/RC gates unchanged. - Flags-first rollout order (no window where a carve-out is unflagged but the logic is live). - Scripted daily ship-report: needs-you / shipped (tagged shadow-vs-you) / in-flight; runs above the health gate. Spec: `docs/superpowers/specs/2026-07-20-automerge-review-gate-and-ship-report-design.md`

igor added 1 commit

2026-07-20 21:39:34 +00:00

docs: design for shadow-review auto-merge gate + daily ship-report

Lint / check-sync (pull_request) Successful in 6s

Details

Lint / check-sync (push) Successful in 5s

Details

c6e8149e9c

Approved design (pre-implementation): flip the auto-merge review gate from
human to the shadow reviews APPROVE for most repos, with a per-repo
agent.json automerge.require_human flag pinning the carve-outs (joshing.you,
igor.bot) to human review; igor stays never-auto-merge via no smoke.url +
the AUTOMERGE_SELF_REPO structural guard. Plus a scripted daily ship-report
(needs-you / shipped / in-flight) as the safety valve. Flags-first rollout.

igor added 1 commit

2026-07-20 21:44:54 +00:00

docs: add porksicle.com to the human-gated carve-outs (needs play-testing)

Lint / check-sync (push) Successful in 4s

Details

Lint / check-sync (pull_request) Successful in 5s

Details

fb72bd471e

igor commented

2026-07-20 21:46:02 +00:00

Author

Collaborator

🤖 Review — `APPROVE` (automated)

CI for fb72bd47: success

Doc-only PR: adds a single 152-line design spec (docs/superpowers/specs/2026-07-20-automerge-review-gate-and-ship-report-design.md) for the shadow-review auto-merge gate + daily ship-report project. Nothing is implemented; this is the spec. Verdict: approve.

Scope: one new file, clean addition, well under the 400-line bar, no drive-by changes. In scope for a design-doc PR.
Honest checklist: the description's "nothing is implemented yet — this is the spec" is accurate; every key decision it lists (agent.json require_human selector, APPROVE-only gate, flags-first rollout, scripted ship-report above the health gate) maps to a corresponding section in the doc. No fabricated work claims.
Tests/lint: none needed — no code changed. The doc's "Testing" section correctly describes future test work rather than claiming tests exist here. CI is success.
Security/correctness: N/A for prose; no secrets, no config touched.

One substantive note for whoever writes the implementation (not blocking, since it's not code yet): the design flips the fleet-wide auto-merge default from human-gated to shadow-APPROVE-gated. That's the whole point, but it's also the highest-risk decision here — worth Josh explicitly signing off on the carve-out list (joshing.you, igor.bot, porksicle.com, igor) being complete before the gate logic PR lands, since a repo that should be human-gated but isn't flagged will silently ship unattended. The doc's fail-closed reasoning (smoke.url onboarding gate) mitigates new repos but not an existing onboarded repo that simply wasn't flagged. Flag that as the review focus on PR #3, not here.

Approving the spec as-is.

_{Independent review by the harness on claude-opus-4-8 (effort: high). The human reviewer is requested once Igor has reviewed; a human still merges.}

### 🤖 Review — `APPROVE` _(automated)_ CI for `fb72bd47`: **success** Doc-only PR: adds a single 152-line design spec (`docs/superpowers/specs/2026-07-20-automerge-review-gate-and-ship-report-design.md`) for the shadow-review auto-merge gate + daily ship-report project. Nothing is implemented; this is the spec. Verdict: approve. - **Scope:** one new file, clean addition, well under the 400-line bar, no drive-by changes. In scope for a design-doc PR. - **Honest checklist:** the description's "nothing is implemented yet — this is the spec" is accurate; every key decision it lists (agent.json `require_human` selector, APPROVE-only gate, flags-first rollout, scripted ship-report above the health gate) maps to a corresponding section in the doc. No fabricated work claims. - **Tests/lint:** none needed — no code changed. The doc's "Testing" section correctly describes *future* test work rather than claiming tests exist here. CI is `success`. - **Security/correctness:** N/A for prose; no secrets, no config touched. One substantive note for whoever writes the implementation (not blocking, since it's not code yet): the design flips the fleet-wide auto-merge default from human-gated to shadow-`APPROVE`-gated. That's the whole point, but it's also the highest-risk decision here — worth Josh explicitly signing off on the carve-out list (joshing.you, igor.bot, porksicle.com, igor) being *complete* before the gate logic PR lands, since a repo that should be human-gated but isn't flagged will silently ship unattended. The doc's fail-closed reasoning (smoke.url onboarding gate) mitigates *new* repos but not an existing onboarded repo that simply wasn't flagged. Flag that as the review focus on PR #3, not here. Approving the spec as-is. --- <sub>Independent review by the harness on `claude-opus-4-8` (effort: high). The human reviewer is requested once Igor has reviewed; a human still merges.</sub>

igor added spent time

2026-07-20 21:46:02 +00:00

20 seconds

igor requested review from joshtronic

2026-07-20 21:46:02 +00:00