MergeGate

Spec format — mergegate/feature@1

A spec is a Markdown file under specs/ whose YAML front matter has schema: mergegate/feature@1. Markdown without a schema: key is ignored, and so is any file whose name starts with _. Unknown keys are rejected.

---
schema: mergegate/feature@1
id: F-014                     # F-<3+ digits>, stable
title: Refund policy
status: active                # draft | active | deprecated
owners: [kev]                 # optional
code_refs:                    # optional — what this spec talks about (drives 🟡)
  - path: src/payments/refund.ts
    symbols: [REFUND_WINDOW_DAYS, canRefund]
assertions:                   # optional — what code must prove (drives 🔴)
  - id: A-F014-001            # A-<CODE>-<3 digits>, never reused
    claim: "Refunds are allowed for 7 days"   # 1–200 chars, shown to humans, never read by the judge
    type: const.equals
    source: src/payments/refund.ts#REFUND_WINDOW_DAYS
    expect: 7
    severity: warn            # optional: lower a blocking type to 🟡 only
    note: "free text"         # optional
---

How a verdict is reached

  1. The engine resolves source syntactically (no type checker, no code execution).
  2. If the value is fully resolved and differs from expect → 🔴, but only for blocking types below.
  3. If the value cannot be resolved with certainty — a function call, an environment read, a spread, a computed key, an unsupported format — the result is 🟡 with the reason. Never 🔴.
  4. A code change that touches a code_refs symbol produces a 🟡 anchor note, even when every assertion still holds. Comment- or whitespace-only edits are silent.
  5. A 🔴 that was already 🔴 at the base commit is reported as pre-existing and does not fail the check.

source syntax

path[#Symbol[.member…][selector…]]

Form Meaning Example
path the file itself (routes, env reads, regex, file existence) src/routes.ts
#Name a top-level declaration (const, enum, type alias, interface, function, class) #REFUND_WINDOW_DAYS
#default the default export (export default defineConfig({...}) unwraps to the object) config.ts#default
.member object property, interface field or enum member #CFG.days
[n] array index #TIERS[0]
[*] or [] map over an array #TIERS[*].name
[key=value] filter array items by a literal property #CHANNELS[type=http].timeout

Same-file const references and relative imports are followed up to depth 3. Numeric arithmetic on literals (30 * 60_000) is folded. new Set([...literals]) resolves to its de-duplicated array unless the file declares or imports its own Set.

Assertion types

Type expect Can be 🔴 Notes
const.equals scalar or array of scalars yes normalize: [trim, lower, collapse-ws] for strings
enum.members { mode: exact|includes, members: [...], distinct? } yes works on enums, literal unions, arrays, new Set; members may be strings, numbers, booleans
object.keys { mode: exact|includes|superset, keys: [...] } or { mode: count, count: n } yes prefer superset for i18n tables, save schemas and config objects that grow
symbol.exists true yes
file.exists true yes
route.exists { framework, routes: ["GET /x"], mode?: includes|exact } yes frameworks: express, hono, nextjs-app, nestjs, fastapi, chi, gin, spring. Mounted sub-routers make the result partial (🟡)
env.default scalar, or { name, value } yes only process.env.X ?? literal / || literal
schema.field { type?, optional?, value?, exists?, default?, unique? } yes TS interfaces and fields today; SQL migrations are 🟡 (unsupported)
env.declared [NAME, …] or { name } no absence is never provable (dynamic access)
regex.present pattern string or { pattern } no severity: block is a schema error; dotAll flag is fixed

Writing assertions that survive

Repository settings — specs/_config.yml

schema: mergegate/config@1
mode: shadow          # shadow (report only) | block (a new 🔴 fails the check). Your plan may cap this.
anchors:
  file_level: true    # code_refs without `symbols` raise 🟡 whenever the file changes
ignore_paths:         # changes in these files never raise anchor 🟡
  - "src/generated/**"
on_incomplete: pass   # pass | fail — in block mode, fail a change MergeGate could not evaluate
                      # (fetch error, timeout, daily limit) instead of letting it through

All keys are optional except schema. A missing file means the defaults above. An invalid file is reported on the check and the defaults are used — MergeGate keeps judging. Settings can make MergeGate quieter or opt into blocking; no setting can hide or soften a 🔴.

Settings are read from the pull request's base, not its head: a PR that changes this file is judged with the settings it replaces, and the new ones apply once it merges.

Making blocking stick

mode: block fails the check on a new 🔴. To stop the merge, also:

  1. Add mergegate/spec-drift as a required status check (branch protection or a ruleset).
  2. Protect specs/ with CODEOWNERS and require code-owner review. A PR may update a spec together with the code — that is how specs stay true — so MergeGate never fails a PR for editing a spec. It lists every change to what is checked (an expect that moved, a removed assertion, a spec that no longer parses, new settings) under "This pull request changes what is checked", and such a run is never green.
  3. Decide on_incomplete. GitHub treats a neutral run as passing, so with the default pass a change MergeGate could not evaluate goes through; fail blocks it until a re-run succeeds.

A 🟡 never fails, whatever the settings: a renamed or computed value that MergeGate cannot resolve needs a human, not a red check.

When one commit is the head of several open pull requests, MergeGate judges it against each of their bases and posts the strictest result (GitHub keeps one check run per commit).

MergeGate judges declared values. It notices the usual ways a value is changed after its declaration (reassigned, destructured into, mutated by push/Object.assign, written through an alias or from a module that imports it) and reports those as 🟡. Code written to change a value at runtime in less direct ways is for code review, not for a value check.