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
- The engine resolves
sourcesyntactically (no type checker, no code execution). - If the value is fully resolved and differs from
expect→ 🔴, but only for blocking types below. - 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 🔴.
- A code change that touches a
code_refssymbol produces a 🟡 anchor note, even when every assertion still holds. Comment- or whitespace-only edits are silent. - 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
- Give the numbers your spec mentions a name in code.
const INTERVALS = [30, 60, 300]can be asserted; an inline[30, 60, 300]inside a function cannot. - Assert policy, not implementation. "Refund window is 7 days" belongs in a spec; "the loop runs twice" does not.
- Use
supersetfor tables that are expected to grow,exactfor closed sets (statuses, plans). - Keep
claimin plain language for reviewers. The judge never reads it.
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:
- Add
mergegate/spec-driftas a required status check (branch protection or a ruleset). - 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 (anexpectthat 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. - Decide
on_incomplete. GitHub treats aneutralrun as passing, so with the defaultpassa change MergeGate could not evaluate goes through;failblocks 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.