API-Spec Drift Checker (openapi-doc)

Scan the Go source and report where the implementation has drifted from the custom-YAML API spec at docs/api/ — the spec-first source of truth, authored by neo's Architect (neo → templates/api-spec.md). This skill writes nothing: the api-spec is the contract, Go is what gets measured, and the output is a drift report the Architect uses to reconcile the YAML (sync-back). Every report rests on evidence (a deterministic script) + an independent fresh-eyes pass + a completeness sweep, never on the running agent's confidence.

ASSET_DIR = <skill base dir>/assets, SKILL_DIR = <skill base dir> (the skill-load message gives the "Base directory for this skill"). Currently optimized for Go (Fiber, Echo, Chi, Gin).

What it compares (Go ↔ docs/api/*.yaml)

• Routes — every Go route (method + path) is documented by a spec endpoint, and every spec endpoint is implemented by a Go route. _meta.yaml's extra_endpoints (e.g. a health probe with no spec file) count as documented.
• Fields — per matched endpoint, the spec's request_body.fields and each responses[].objects.<Name> are diffed against the Go struct (reverse-matched by json names): an undocumented Go field (serializable, no spec row), a stale spec field (no Go field), an M/O disagreement (mandatory: M|O vs the struct tags), and a confident type disagreement (bool/[]T/numeric vs Boolean/Array/Number).
• A difference the script cannot decide confidently (no struct match, the response envelope wrapper, handler-inline query/path params, error-status tracing) becomes a NOTE for the fresh-eyes pass — never a false drift.

Required input

• docs/api/*.yaml — the api-spec must already exist. Missing → STOP: "no api-spec at docs/api/ — run neo (Architect) to author it first." This skill never creates it.
• Go source with go.mod. Not a Go project (no go.mod, no references/<lang>-scan-patterns.md) → STOP (Go only; do not guess patterns). Monorepo (multiple go.mod) → ask which service, then scope --src and the docs/api/ path to that one service.