The gate door: the checkpoint your agent has to pass
Run the enforcement gate, work the drift queue, repair a broken spec↔code link, and read graph-derived code health — one door that keeps intent and code honest. Drift is a signal, not a failure, and the gate only bites when you ask it to.
SE
Selva E.
Jul 1, 2026 · 9 min read
The first two doors get intent into the graph and code out of it. This one keeps them honest with each other over time — because the failure mode of AI-assisted development isn't writing bad code, it's writing plausible code that quietly drifts away from what was promised, and rots the architecture a little on every commit. The gate door is the checkpoint that notices.
/specship:check is one door over four jobs: run the gate, work the drift queue, repair a broken link, and read code health. It routes on the first word.
The gate
Open it with no argument and it runs the enforcement gate — specship check — which composes four graph-derived checks into one verdict: spec↔code drift, architecture fitness (your layering rules), maintainability (coupling, god-files, cycles), and the spec→test→verify behaviour chain. It's the single command an agent runs before it calls a change done.
Opt-in, not opinionated by default. With no enforce configuration the gate only advises — it reports what it found and exits 0, so it never blocks a repo that never asked to be gated. You turn specific checks into hard failures when you're ready, and only those bite. The gate meets you where you are instead of imposing a policy you didn't choose.
The drift queue
Every spec is a node with an edge to the code that satisfies it. Change that code and the edge tells the truth about what happened. /specship:check drifted calls specship_drifted and surfaces the links that need a human's eye, in three states:
drifted
the spec or the code changed since the link was verified — the two may no longer agree.
broken
a linked test ran and failed — the code no longer satisfies the requirement.
orphaned
the target symbol is gone — renamed or deleted out from under the spec.
Drift isn’t the bug. Drift is the alarm you actually wanted — the renamed field or deleted function landing in a review queue instead of silently shipping under a “verified” requirement.
Repairing a link
Two sub-actions close the loop once the queue flags something:
fix <SPEC_ID> runs the bundled spec-fix workflow. It diagnoses which side moved — comparing the spec's hash, the code's signature, and any failing test — proposes the repair, pauses for approval, applies it, and calls specship_link_verify to move the link back to verified. You're never guessing whether to change the spec or the code; the diagnosis tells you.
relink <SPEC_ID> handles the orphaned case — the target symbol has a new home or a new name. It re-points the edge at the symbol's new location and re-asserts, so a rename doesn't cost you the traceability you'd already earned.
Code health
/specship:check health runs specship maintainability — code health read straight off the graph, no linter to configure. By default it shows the high-precision findings: oversized symbols, god files, and dependency cycles, ranked and capped so you get the ten that matter, not a thousand-line wall. Two flags open it up:
the gate door
# the gate — advises by default, gates only what you configure
/specship:check
# the review queue
/specship:check drifted# repair a drifted / broken link
/specship:check fix REQ-AUTH-005# code health — add --deep for coupling + dead code, --json for CI
/specship:check health
Add --deep for the lower-confidence dead-code and coupling findings, and --json for the full tagged set — the shape you wire into CI when you're ready to let the gate actually fail a build.
Three doors, one loop
Stand back and the three doors are a cycle, not a menu. The reads door is where you understand — explore, trace, impact. The intent door is where you decide and build — author a spec, implement it, link it. And the gate door is where you verify and maintain — check the change, catch the drift, keep the architecture from rotting.
Each door hides several tools behind a single intent, so the agent describes what it's trying to do rather than picking an instrument. And each hands off to the next: a trace becomes a spec, a spec becomes linked code, linked code becomes a drift signal the day it moves. The doors are small on the surface and deep behind — which is exactly the shape you want a tool to have when an agent, not a human, is the one walking through.
#doors#drift#maintainability#ci
SE
Selva E.
Building SpecShip · graph, specs & harness
Works on the parsing, storage, and spec layers of SpecShip. Spends an unreasonable amount of time thinking about edges.