spec-lint
ADLC phase: C1 (P1 gate)
Audits a spec for acceptance criteria that lack a concrete verification method.
Every acceptance criterion must name how it will be checked — a test file, a
command whose output is asserted, an explicit verify: label, an assert
statement, or an exit code reference. Criteria without one are wishes.
Wishes get flagged at exit 2, blocking CI until the spec is tightened.
Usage
spec-lint <spec.md> [--llm] [--json] [--prompt-only] [--record --ticket <id>]
Flags
| Flag | Description |
|---|---|
--llm | Run a cheap-tier LLM pass on VERIFIED criteria to catch vacuous methods ("works correctly", "run tests"). Demoted criteria become WISH. Requires a provider env var (see core). |
--json | Emit machine-readable JSON (for orchestrators). All other output is suppressed. |
--prompt-only | Print the exact LLM prompt and exit 0. Works with zero API keys — paste into any harness. |
--record | On a passing run, record a spec-lint entry into .adlc/manifest.jsonl via gate-manifest, hashing <spec.md> into it. Requires --ticket — an unbound record could satisfy another ticket's P1 gate. Never records on a failing (WISH-containing) run. |
--ticket <id> | Ticket to bind the recorded entry to (required with --record). |
Exit codes
| Code | Meaning |
|---|---|
0 | Gate passes — every acceptance criterion names a verification method. |
1 | Operational error — file missing, unreadable, or LLM call failed. |
2 | Gate fails — one or more criteria are wishes (line numbers printed), or the spec states no acceptance criteria at all. |
What counts as a verification method?
A criterion is VERIFIED if its text contains any of:
- A backtick span that looks like a command or assertion:
`npm test`,`curl -s ... | jq .`,`stripe-test --card=valid`, or a bare span immediately preceded by phrasing like "Verified via" / "Run ". A bare backtick span with no command-like content (e.g. a filename mentioned in passing,`vitest.config.ts`) is not sufficient on its own. - A path matching
*.test.<ext>or*.spec.<ext>:auth.spec.ts verify:orverified byfollowed by texttest:followed by text- The phrase
exit code - The word
assert
Everything else is a WISH.
Where criteria are found
Criteria are extracted from:
- List items (
-,*,1.,- [ ],- [x]) under any heading matching/acceptance|criteria|requirements|definition of done|success/i— this includes a literal markdown heading (## Acceptance Criteria) or a bold-only pseudo-heading line (**Acceptance criteria**:). A list item's wrapped continuation lines (indented, non-blank, not themselves a new list marker/heading) are joined into the same logical criterion before classification, matching how markdown renderers treat a single list item. - Standalone lines starting with
MUSTorSHOULD(anywhere in the file)
LLM demotion (--llm)
Even VERIFIED criteria can be vacuous. "Run tests and verify it works correctly"
contains a backtick command but conveys nothing checkable. The --llm flag sends
VERIFIED criteria to a cheap model asking it to identify vacuous methods and
returns a { vacuous: [indices], reason: {...} } JSON object. Vacuous criteria
are demoted to WISH.
Use --prompt-only to get the exact prompt without making any API calls — useful
for testing, auditing, or pasting into a different model.
JSON output
{
"file": "spec.md",
"total": 5,
"verified": 3,
"wishes": 2,
"criteria": [
{ "line": 8, "status": "VERIFIED", "text": "...", "reason": "..." },
{ "line": 9, "status": "WISH", "text": "...", "reason": "no verification method found" }
]
}
Example
# Run gate — exit 2 if any wishes
spec-lint docs/spec.md
# Machine-readable for CI
spec-lint docs/spec.md --json
# Inspect LLM prompt without API key
spec-lint docs/spec.md --prompt-only
# Full LLM-backed demotion pass
ANTHROPIC_API_KEY=sk-... spec-lint docs/spec.md --llm
Relationship to sibling tools
- C2 premortem — after spec-lint passes, stress-test the approved spec with a frontier model (postmortem framing).
- C3 coldstart — per-ticket gap analysis; spec-lint gates the spec, coldstart gates individual tickets.
- C11 gate-manifest — spec-lint results should be appended to the manifest ledger after a gate run.
Core gaps
None. All required functionality (complete, extractJson, parseArgs,
pass, gateFail, opError, printJson, promptOnly) is present in core.