synaptiai PR Lifecycle
Policy reference for PR creation and the pre-merge finding-ledger gate; the runnable bash lives in commands/pr.md and commands/merge.md.
Contract
Iron law: no PR without verification — a PR body that cannot show test, lint, and runtime evidence is not ready. Consumed by /flow:pr (Phase 1 pre-flight; Phase 4 verification gate, body assembly, push, create, reviewer suggestion at step 11) and by /flow:merge Phase 1 (finding-ledger check). Returns the policy those commands apply: four pre-flight conditions, five verification-gate conditions, the PR body section order, the reviewer cascade, and the two ledger rules that block a merge. Permitted skips: none — pre-flight conditions 1, 2, and 4 are hard errors; condition 3 is a warning that offers /flow:commit.
Pre-Flight Gate (/flow:pr Phase 1)
| # | Condition | On failure |
|---|---|---|
| 1 | Not on the default branch | Hard error — PRs come from feature branches |
| 2 | At least one commit ahead of the default branch | Hard error — empty PRs are noise |
| 3 | No uncommitted changes | Warning — offer /flow:commit first |
| 4 | No existing open PR for this branch | Hard error — update the existing PR |
Verification Gate (/flow:pr Phase 4)
All five must hold before creation; otherwise stop:
- All quality commands (lint, test, typecheck) pass — output captured for the PR body.
- Self-review completed against the
code-quality-principleschecklist. - Change classification shows no out-of-context files.
- Every acceptance criterion has a "Met" or "Interpreted" status with concrete evidence.
- No P1 findings remain from code review.
"Get the PR up and fix it after", "the reviewer will catch it", "small change", and "CI will validate it" are not exemptions. The eight quality gates flow enforces are mapped in gate-configuration.md.
PR Body
Generated from templates/pr-body.md plus review findings and the decision journal. Section order: Summary (2–3 sentences), Closes, Changes (grouped by area), Comprehension Report, Key Decisions (public journal entries; internal entries redacted), Requirements Adherence (criterion → status → file:line evidence), Review Findings (P1/P2/P3), Known cosmetic notes, Review Cycle History, Verification checklist, Verification Verdict, Files Changed. Reviewers skim Summary, Requirements Adherence, Verification in under thirty seconds.
Reviewer Suggestion (/flow:pr Phase 4 step 11)
Priority cascade: (1) CODEOWNERS entries for paths in the diff; (2) file expertise — contributors to the same files in the last 30 days; (3) recent activity in adjacent areas; (4) workload balance — among equals, fewest outstanding review requests. Surface the top 2–3 with a one-line rationale each; the author decides.
Push and Create
git push -u origin <branch> and gh pr create are Tier 2 (journal-and-proceed). Afterwards verify with gh pr view --json number,url,state,title, surface the URL, and suggest /flow:review {number}.
Merge Prerequisite: Finding-Ledger Check (/flow:merge Phase 1)
PR comments carry FLOW_REVIEW_CYCLE:{N} FINDINGS:[...] and FLOW_RESOLUTION_CYCLE:{N} RESOLVED:[...] ESCALATED:[...] DISPUTED:[...] markers; the latest of each is parsed and compared (grammar and trust filter in finding-ledger-parser.md). The merge blocks when:
- The
ESCALATEDarray is non-empty — an escalated finding is unresolved. - Any ID in
FINDINGShas no entry inRESOLVED.
To clear: run /flow:address {pr_number} until every finding appears in RESOLVED and ESCALATED is empty, then re-run /flow:merge. This is the "no incomplete shipments" boundary.
Keeping Policy and Bash Aligned
Pre-flight: commands/pr.md Phase 1. Body assembly, push, create: Phase 4. Reviewer suggestion: Phase 4 step 11. Ledger gate: commands/merge.md Phase 1. A new check, section, or marker changes the command and this reference together.