synthesis-preflight · diff

v1.1.1 to v2.0.0

19 added, 106 removed. Audit A to A.

---

name: synthesis-preflight

- description: >

- Pre-merge quality gate framework with six orthogonal dimensions: branch

- hygiene, clean tree, tests and types, code audit, temporary considerations,

- and commit history. Produces a mechanical go/no-go verdict. Use when asked

- to: preflight, pre-merge check, ready to merge, can I ship this, branch

- ready, quality gate, merge readiness, pre-PR check.

+ description: "Pre-merge gate that grades six dimensions (branch, clean tree, tests and types, code audit, temporary workarounds, commit history) into a mechanical go/no-go verdict. Use for preflight, pre-merge or pre-PR check, ready to merge, can I ship this, branch ready, quality gate, merge readiness."

license: "CC0-1.0"

depends_on: ["synthesis-code-audit"]

metadata:

author: "Emil Peñaló"

- version: "1.1.1"

+ version: "2.0.0"

+ format: v5

source_repo: "github.com/synthesisengineering/synthesis-skills"

source_type: "public"

---

# Synthesis Preflight

Preflight is a branch readiness gate. It does not evaluate whether your code is correct — that is the job of synthesis-implementation-integrity (self-review) and synthesis-code-audit (quality scan). Preflight asks a different question: *is this branch mechanically ready to become a PR?*

A branch can contain perfectly good code and still fail preflight: tests broken, uncommitted changes left behind, vague commit messages, a stale workaround that should have been removed. Preflight catches the things that fall between "the code works" and "the branch is ready."

- ---

- ## Where This Fits

- | Skill | Scope | When to use |

- |-------|-------|-------------|

- | **implementation-integrity** | Self-verification of a single implementation | After completing work — "Is my code genuinely complete?" |

- | **code-audit** | 10-dimension quality scan of a diff | After implementation — systematic quality measurement |

- | **preflight** (this one) | Branch readiness gate | Before creating a PR — "Is this branch ready?" |

+ ## Binding rules

- **The handoff:** Implement and verify the change, reconcile branch readiness, then create the PR and complete required peer review. These scopes may share evidence; invoking another skill does not require another audit.

+ 1. **Grade all six dimensions on every run.** N/A needs a concrete reason tied to the project contract; a missing tool, absent required suite, inaccessible environment or failed check is UNKNOWN or FAIL, never N/A.

+ 2. **The verdict is mechanical.** Any required FAIL or UNKNOWN makes the branch NOT READY; warnings inform and never block. An approved contract amendment may change a requirement, never relabel a failed or missing observation as a pass.

+ 3. **Refuse on a protected branch.** Preflight runs on a feature, fix or working branch, never on the default branch.

+ 4. **The default test gate is the full suite plus the configured type checker.** Targeted tests alone do not satisfy it; only an explicit project or user policy narrows it, never silence.

+ 5. **Reuse evidence only while it is still valid:** same source and base hashes, inputs, environment and criterion. After a change, rerun the affected checks and every check the repository requires; a same-session timestamp proves nothing.

+ 6. **Consume current evidence instead of repeating it.** Check that implementation-integrity and audit evidence covers the exact branch state, and audit only what is uncovered.

+ 7. **A secret in a commit message fails the branch,** because it persists in git history even when the code is clean.

+ 8. **A tracked workaround or known failure never excuses a required check.** Remove resolved temporary considerations and report them.

+ 9. **READY grants nothing.** It is not merge, release or deployment authority; apply the [decision-ownership contract](../synthesis-thinking-framework/references/decision-ownership.md) and the action owner's gate. When another workflow invoked preflight, return the full report to it.

- Preflight consumes current implementation-integrity and audit evidence. It checks that the evidence covers the exact proposed branch state and required consumers; it does not repeat an unchanged review merely to produce another report. A readiness verdict does not grant merge, release or deployment authority. Apply the shared [decision-ownership contract](../synthesis-thinking-framework/references/decision-ownership.md) and the action owner's existing gate.

+ ## Contents

- ---

+ - [references/dimensions-and-rules.md](references/dimensions-and-rules.md): the full checks for each of the six dimensions, and the grading rules. Read on every preflight run, before grading.

+ - [references/temporary-considerations.md](references/temporary-considerations.md): the temporary considerations pattern: what to track, the entry format, and why preflight checks it. Read when the project tracks workarounds or should start to.

+ - [references/background.md](references/background.md): where preflight sits beside implementation-integrity and code-audit, the handoff between them, and decision ownership. Read when choosing between these skills.

+ - [references/coverage-map.md](references/coverage-map.md): where each part of the 1.1.1 text now lives (ruling D8).

+ - The Quality Gate Framework, Verdict: below. The five grades and the report format.

## The Quality Gate Framework

Preflight evaluates six orthogonal dimensions. Each is graded independently:

- **Pass** — no issues

- **Warning** — potential concern, does not block

- **Fail** — blocks the PR until resolved

- **Unknown** — required evidence is unavailable, incomplete or stale; blocks readiness

- **N/A** — the dimension does not apply, with a concrete reason tied to the project contract

A single FAIL or UNKNOWN in a required dimension means the branch is NOT READY. Warnings are surfaced for awareness but do not block. An approved contract amendment may change a requirement; it cannot relabel a failed or missing observation as a pass.

- ---

- ## Quality Dimensions

- ### 1. Branch Verification

- - Confirm you are on a feature, fix, or working branch — not on the default branch (main, master, or whatever the project designates as protected). Refuse to proceed if on a protected branch.

- - Count commits ahead of the base branch. If the branch is behind the base, warn that a sync may be needed before PR creation.

- ### 2. Clean Working Tree

- - Check for uncommitted changes. If any exist, warn that they will not be included in the PR.

- - If there are unstaged changes, surface them explicitly so the developer can decide whether to commit or discard before proceeding.

- - The goal is awareness, not enforcement — uncommitted work may be intentional (unrelated experiments, local config).

- ### 3. Test & Type Verification

- - The default gate is the project's full test suite and configured type checker, plus any additional repository requirements. Consume valid results for the exact candidate, relevant inputs and environment; run missing or invalidated checks. Targeted authoring tests alone do not satisfy the default full-suite gate. A narrower gate requires an explicit governing project or user policy, never an inference from silence.

- - Report actual passed, failed, skipped and not-run coverage. A required check that failed or did not execute blocks readiness.

- - A new preflight invocation alone does not invalidate a completed check.

- ### 4. Code Audit

- - Confirm current audit evidence covers the full branch diff (base to HEAD). Apply synthesis-code-audit to uncovered changes and affected risks; consume valid coverage instead of commissioning another identical audit.

- - Any FAIL dimension in the audit = preflight FAIL for this gate.

- - WARNING dimensions are surfaced in the preflight report but do not block.

- - A "Clean" audit verdict = PASS for this gate.

- ### 5. Temporary Considerations

- Check whether the project tracks temporary workarounds, known issues, or time-limited technical debt.

- For each tracked entry:

- 1. **Run its resolution verification check.** Each temporary consideration should define criteria for when it can be removed (a flag is deleted, a migration is complete, a dependency is upgraded).

- 2. **Resolved entries** — remove them from tracking. Report the resolution in the preflight output.

- 3. **Still-active entries** — list them in the preflight output. Verify each proposed exclusion against the governing contract and its actual decision owner. A tracked workaround or known failure is not permission to skip a required check. Keep unresolved required checks blocking and preserve the original evidence.

- If the project does not track temporary considerations, grade this dimension as N/A.

- ### 6. Commit History

- Review the commits on this branch (from the base branch to HEAD):

- - **Secrets or credentials in commit messages** — FAIL. Even if the secret is not in the code, its presence in a commit message means it will persist in git history.

- - **Message clarity within repository policy** — flag unclear messages when the repository calls for descriptive subjects. Explicit disclosure rules may require generic messages; do not demand sensitive detail or history rewriting to satisfy a generic style preference.

- - **Convention compliance** — check that commit messages follow the project's documented format (conventional commits, imperative mood, character limits, or whatever the project specifies). Flag violations.

- ---

## Verdict

Present findings as a status report:

```

PREFLIGHT REPORT — {branch-name}

Branch: pass/warning/fail/unknown (details)

Clean tree: pass/warning/fail/unknown (details)

Tests & types: pass/fail/unknown/N/A (X passed, Y failed; applicability)

Code audit: pass/warning/fail/unknown (coverage and findings)

Temp items: pass/fail/unknown/N/A (N resolved, N still active)

Commit history: pass/warning/fail/unknown (details)

VERDICT: READY / NOT READY (with blockers listed)

```

**READY** — all required dimensions have current passing evidence; genuine N/A dimensions and nonblocking warnings are explained.

**NOT READY** — one or more required dimensions are FAIL or UNKNOWN. List blockers in priority order. For each blocker, state what is wrong or missing and what observation will resolve it.

- ---

- ## The Temporary Considerations Pattern

- This pattern is worth explaining because most projects do not formalize it, and workarounds accumulate silently as a result.

- ### What to Track

- - Workarounds for known bugs in dependencies or infrastructure

- - Feature flags that were meant to be temporary

- - Hardcoded values that should come from configuration after a specific migration

- - Compatibility shims for deprecated APIs

- - Any code with an implicit expiration date

- ### Entry Format

- Each tracked consideration should include:

- - **Description** — what the workaround does and why it exists

- - **Reason it is temporary** — what event or change will make it unnecessary

- - **Resolution verification** — a concrete, checkable condition (a file is deleted, a config key exists, a dependency version is above X, a feature flag is removed)

- - **Proposed exclusions** — identify the affected requirement, its decision owner and any applicable grant. Record failures once without suppressing their blocking consequence. No exclusion arises merely from being listed here.

- ### Why Preflight Checks This

- Workarounds that are not tracked and not checked tend to become permanent. Preflight auto-cleaning resolved entries prevents accumulation. The developer who resolves the underlying issue may not remember every workaround it affects — preflight remembers for them.

- ---

- ## Rules

- - Never skip a dimension. A genuinely inapplicable check may be N/A with evidence of why it does not apply. A missing tool, absent required suite, inaccessible environment or failed check is UNKNOWN or FAIL, never N/A.

- - The verdict is mechanical. Any required FAIL or UNKNOWN makes it NOT READY.

- - Warnings are informational. They surface concerns but do not block.

- - If preflight is invoked by another workflow (a shipping or CI pipeline), return the full report to that workflow for decision-making.

- - Reuse evidence only while its source/base hashes, relevant inputs, tool/environment assumptions and criterion remain valid. After a change, rerun the affected checks and every check the repository explicitly requires; retain unaffected evidence. A same-session timestamp alone does not establish validity.