@specship/specship-win32-arm64 0.24.0 → 0.28.0

package/lib/dist/skills/spec-author/references/format.md

@@ -0,0 +1,210 @@
+# Spec format reference
+
+The SpecShip parser at `src/extraction/specs/markdown-spec-extractor.ts` accepts a strict Markdown subset. This file is the contract — if your draft doesn't match what's described here, `specship sync` will emit `spec_missing_id`, `spec_stranded_id`, or `spec_bad_frontmatter` errors and the spec won't enter the graph.
+
+## File location
+
+```
+<project-root>/specs/<slug>.md
+```
+
+The directory is configurable but `specs/` is the default. One file can hold one document with many requirements; you don't need one file per REQ.
+
+## Top-to-bottom anatomy
+
+```markdown
+---                                          ← YAML frontmatter (optional)
+id: AUTH-DOC
+title: Authentication
+owner: security-team
+priority: high
+version: 1
+---
+
+<!-- id: AUTH-DOC -->                        ← embedded ID for the document
+# Authentication                              ← H1 = document body
+
+This document covers login, session         ← document body text
+management, and rate-limiting.
+
+<!-- id: REQ-AUTH-001 -->                    ← embedded ID for a requirement
+## Failed logins MUST be rate-limited        ← H2 = requirement
+
+The login endpoint rejects more than 5
+failed attempts per IP per minute.
+
+implementations:                              ← optional code-link block
+  - src/auth/login.ts:authenticate
+  - src/auth/rate-limit.ts:enforce
+
+verifies:                                     ← optional test-evidence block
+  - __tests__/auth-rate-limit.test.ts:rejectsSixthAttempt
+
+## Acceptance                                 ← unnumbered subheading, OK
+<!-- id: REQ-AUTH-001.A1 -->                 ← embedded ID for an acceptance bullet
+- A 6th failed attempt within 60 s from
+  the same IP returns 429 with `Retry-After`.
+<!-- id: REQ-AUTH-001.A2 -->
+- A successful login resets the counter
+  for that IP.
+```
+
+## The five hard rules
+
+### 1. Every heading needs an embedded ID immediately above it
+
+```markdown
+<!-- id: REQ-FOO-001 -->         ← required
+## Title here                    ← heading
+```
+
+If you forget the marker, the parser emits `spec_missing_id` (severity `error`) and the spec doesn't index. The marker must be on the line immediately above the heading — blank lines or other content between them break the pairing.
+
+### 2. Two ID comments in a row produces a stranded-ID warning
+
+```markdown
+<!-- id: REQ-A -->
+<!-- id: REQ-B -->               ← REQ-A becomes "stranded"
+## Title
+```
+
+This is `spec_stranded_id` (severity `warning`). The first ID is lost. Don't paste IDs from old drafts without their headings.
+
+### 3. Hierarchy is heading depth
+
+Levels nest naturally: H2 is a child of H1, H3 is a child of H2 (or H1 if no H2 above it), etc. The document spec (`kind: 'document'`) sits above all of them.
+
+Practical translation:
+- `# H1` → typically the document body (or a single requirement if there's no other heading)
+- `## H2` → requirements
+- `### H3` → child requirements OR acceptance bullets parent
+- `#### H4+` → child acceptance bullets (rarely used)
+
+### 4. Acceptance bullets get their own ID markers
+
+The convention is `<REQ-ID>.A1`, `.A2`, etc.:
+
+```markdown
+<!-- id: REQ-AUTH-001 -->
+## Failed logins MUST be rate-limited
+
+## Acceptance
+<!-- id: REQ-AUTH-001.A1 -->
+- A 6th failed attempt within 60 s ...
+<!-- id: REQ-AUTH-001.A2 -->
+- A successful login resets the counter ...
+```
+
+The `## Acceptance` heading is conventional but not required by the parser — it just helps the human reader. The ID markers on the bullets ARE required if you want them queryable as individual spec nodes.
+
+### 5. Frontmatter ID is optional but useful
+
+If you provide an `id:` field in YAML frontmatter, the document spec uses that ID. If you don't, the document only emits a node when an H1 with an embedded ID is present. Most files should declare frontmatter `id:` so the document is always addressable.
+
+## IDs must be unique within the file
+
+Two markers declaring the same ID do not error — the specs are stored with `INSERT OR REPLACE`, so the **LAST** occurrence overwrites the earlier ones. The earlier heading's title, body, and links are silently gone. Scan for accidental duplicates before writing the file (a common cause: copy-pasting a REQ block and forgetting to bump the number).
+
+## YAML frontmatter fields
+
+All optional except as noted. The parser reads any string-typed field; unknown keys become `metadata`.
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | string | Document-level spec ID. Conventional: `<AREA>-DOC` (e.g. `AUTH-DOC`). |
+| `title` | string | Human title. Falls back to the H1 if absent. |
+| `owner` | string | Team or person. Convention: `security`, `payments-team`, `@alice`. |
+| `priority` | string | Free-form. Convention: `high` / `medium` / `low`. |
+| `version` | string \| number | Spec version. Convention: integer that increments on contract changes. |
+| `format` | string | Defaults to `markdown`. Don't set unless you know why. |
+| `depends_on` | string \| list | Spec IDs this document depends on. Accepts one id, a comma-separated list, or `[a, b]`. |
+| `metadata` | object | Arbitrary nested object. Reserved for future indexing. |
+
+Stop the frontmatter with `---` on its own line. The parser tolerates a missing trailing `---` but emits `spec_bad_frontmatter` as a warning.
+
+## The link blocks: `implementations:` and `verifies:`
+
+Both blocks live in the **body of a requirement** (not at the file level), and both use the same bullet syntax. They differ only in the kind of link they create.
+
+```markdown
+<!-- id: REQ-FOO-001 -->
+## Some requirement
+
+Body text...
+
+implementations:
+  - src/foo/bar.ts:doThing
+  - src/foo/baz.ts:Baz.handle
+
+verifies:
+  - __tests__/foo.test.ts:doThingRejectsEmptyInput
+```
+
+Shared syntax rules:
+
+- Each bullet is `<file-path>:<qualified-symbol>`.
+- File paths are project-root-relative.
+- Qualified symbols use dots: `Class.method`, `Class.staticMethod`, `module.function`.
+- The pattern `[-*]\s+([^\s:]+)\s*:\s*([A-Za-z0-9_$.]+)` is what the parser matches.
+- A bullet that has no `:symbol` (a bare path — e.g. a pointer at a slash-command markdown file) creates **no edge**. It's tolerated, doesn't end the block, and emits a `spec_bare_path_ref` warning naming the bullet. Use it only when there genuinely is no code symbol to point at.
+- Only the FIRST block of each keyword in a requirement body is read. A block ends at the first non-blank, non-bullet line.
+
+### `implementations:` → link kind `implements`
+
+This block is the **backstop** for spec-to-code links. The agent SHOULD call `specship_link_assert` programmatically after implementing the spec — but if it forgets, the `implementations:` block re-asserts the link on every index. Either way, the link enters state `implemented`.
+
+Leave `implementations:` empty (or omit it) in a fresh spec — the agent fills it in via `link_assert` once the code lands. Specify it up-front when you have a strong sense of where the implementation will live.
+
+### `verifies:` → link kind `tests`
+
+This is the **test-evidence** declaration, and it's what gates promotion from `implemented` to `verified`. A requirement with implementation code but no passing test evidence does not count as verified, no matter how complete the code is.
+
+Point each bullet at a **real test symbol** — an exported test helper or a named test function. A bare `describe(...)` / `it(...)` string is not a symbol in the graph, so it can't be a link target; if the test file has no addressable symbol, either name a helper function the test calls or leave `verifies:` out until there is one.
+
+Omit `verifies:` from a spec being authored before the tests exist. Adding it speculatively produces an orphan link that pollutes the drift queue.
+
+## RFC 2119 keywords in titles + bodies
+
+Use **MUST / SHOULD / MAY** in the requirement title and body. The parser doesn't validate these, but the review checklist does. Conventional usage:
+
+| Keyword | Meaning |
+|---|---|
+| **MUST** | Required for compliance. Test failure means the spec is broken. |
+| **SHOULD** | Strongly recommended. Deviation requires justification. |
+| **MAY** | Optional. Choose freely; no compliance impact. |
+| **MUST NOT** / **SHOULD NOT** | Negative forms. Same strength as positive. |
+
+Avoid weasel words: "ought to", "could", "supports". They're un-testable and the review will flag them.
+
+## Slug conventions
+
+For the filename:
+
+- **Kebab-case**, no spaces.
+- **Feature name**, not date — git history records the when.
+- **One file per logical area** when reasonable. `auth.md` is better than `auth-login.md` + `auth-logout.md` + `auth-rate-limit.md` if all three live under `AUTH-DOC`.
+
+## What the parser explicitly DOES NOT support
+
+- **No Markdown extensions** (footnotes, definition lists, task lists with `- [ ]`). They render fine, but the parser doesn't extract structure from them.
+- **No HTML other than the `<!-- id: -->` comment.** Don't embed `<div>` or `<table>`.
+- **No code blocks treated specially.** Triple-backtick fenced blocks render but are body content, not structure.
+- **No links treated specially.** A `[REQ-AUTH-005](#req-auth-005)` link is rendered text, not a queryable cross-reference. Use the markers + heading text; the indexer's name-matcher handles cross-spec lookups.
+- **No multi-file specs.** One spec file = one document. Cross-document parent references aren't supported (`depends_on` in frontmatter is the one cross-document relation).
+
+If you find yourself wanting these, write a regular Markdown doc under `docs/` instead and let the spec layer focus on what it parses.
+
+## Quick checklist before writing the file
+
+- [ ] Frontmatter ID set (`id: <AREA>-DOC` or similar).
+- [ ] Every heading has `<!-- id: ... -->` immediately above it.
+- [ ] No two ID comments in a row (stranded ID).
+- [ ] No ID declared twice in the file (the last one silently overwrites the first).
+- [ ] Acceptance bullets each have their own `.A<N>` ID.
+- [ ] `implementations:` paths (if specified) point at real symbols (verified via `specship_explore` or `specship_node`).
+- [ ] `verifies:` bullets (if specified) point at real test symbols, not `describe`/`it` strings.
+- [ ] RFC 2119 keywords used correctly (or not at all).
+- [ ] No `<div>` / `<table>` / Markdown-extension syntax in the body.
+- [ ] Filename is kebab-case, no date prefix, feature-named.
+
+If all ten pass, the file will index cleanly.

package/lib/dist/skills/spec-author/references/gap-questions.md

@@ -0,0 +1,152 @@
+# Gap-fill questions catalog
+
+The user gave you a one-line feature description. Your draft fills in the obvious parts. This catalog is what you use to find the **non-obvious** parts you should ask about before writing the file.
+
+## How to use this catalog
+
+1. Read your draft.
+2. For each category below, ask: "did the user's description or my draft cover this?"
+3. If yes → move on; no question needed.
+4. If no → either ask the user, or insert a `[needs user confirmation]` marker in the draft.
+
+**Limit per round: 3–5 questions.** Don't dump the whole catalog on the user. Pick the ones that matter most for this spec; mark the rest as `[needs review]` and proceed.
+
+The one exception is **Project invariants** at the end: always walk that section, because a spec that contradicts a house invariant gets rejected at review no matter how well-formed it is.
+
+## The catalog
+
+### Identity & ownership
+
+| Q | Why it matters | Example phrasing |
+|---|---|---|
+| Owner team or person? | A spec without an owner drifts and nobody fixes it. | "Who owns this — `security`, `payments`, or someone else?" |
+| Priority? | Helps when the drift queue is long. | "Priority — high, medium, low?" |
+| Existing parent doc, or new one? | Decides whether to append or create a file. | "Should this go under your existing `AUTH-DOC`, or is this a new feature area?" |
+
+### Trigger & scope
+
+| Q | Why it matters | Example phrasing |
+|---|---|---|
+| What's the entry point? | An endpoint? A function call? A scheduled job? A webhook? | "Where does this kick off — REST endpoint, internal function, cron, webhook?" |
+| Who/what can invoke it? | Authenticated users? System only? Admins? Anonymous? | "Who's allowed to invoke — authenticated only, admins, anonymous?" |
+| Synchronous or async? | Affects the acceptance criteria around timing. | "Is the caller blocked waiting for the result, or is this fire-and-forget?" |
+| Idempotent? | Critical for retry semantics. | "If the same input is sent twice, do we want the same result, or distinct ones?" |
+
+### Success path
+
+| Q | Why it matters | Example phrasing |
+|---|---|---|
+| What's the contract observable from outside? | This IS the spec. If you can't answer it, you don't have a spec yet. | "When this succeeds, what's the contract — the response shape, the side effects, the state change?" |
+| What's the latency target, if any? | Often skipped, often relevant. | "Is there a latency expectation — sub-100ms, sub-second, eventually-consistent?" |
+| Cache or memoize? | Affects idempotency and observability bullets. | "Should successful results be cached? For how long?" |
+
+### Failure modes
+
+| Q | Why it matters | Example phrasing |
+|---|---|---|
+| What happens on transient failure? | Retry semantics live here. | "If a downstream call fails transiently, do we retry, return an error, or queue?" |
+| What happens on permanent failure? | The unhappy path is half the spec. | "If the operation can't succeed (validation fails, dependency dead), what does the caller see?" |
+| What's the timeout? | Even "no timeout" is a decision worth stating. | "Is there a hard timeout? After how long?" |
+| Partial-success semantics? | For multi-step operations. | "If step 3 of 5 fails, does the work roll back, or do we leave the partial state?" |
+
+### Edge cases & ambiguity
+
+| Q | Why it matters | Example phrasing |
+|---|---|---|
+| What about empty/null inputs? | Often unspecified, often the source of bugs. | "What happens on empty input — error, no-op, default?" |
+| What about boundary values? | Off-by-one and rate-limit thresholds. | "Exactly 5 attempts allowed, or fewer-than-5?" |
+| What about repeated identical inputs in a tight loop? | Race conditions. | "Two parallel requests with the same payload — same result, or do they race?" |
+| What about very-large inputs? | Resource exhaustion. | "Is there a max payload size?" |
+
+### Persistence & state
+
+| Q | Why it matters | Example phrasing |
+|---|---|---|
+| Does this produce persisted state? | If yes, the schema is part of the contract. | "Does this write to a database / audit log / event store?" |
+| TTL on persisted state? | Storage costs and privacy concerns. | "Do those records expire? After how long?" |
+| Is the state queryable? | Determines whether queries are part of the spec. | "Are those records queryable by other services, or internal-only?" |
+| Schema migration on existing data? | Hidden complexity. | "Does this affect any existing rows in the system?" |
+
+### Security & access control
+
+| Q | Why it matters | Example phrasing |
+|---|---|---|
+| AuthZ — who can call it? | Often implicit but should be stated. | "Authorization — what roles or scopes are required?" |
+| Sensitive data in inputs/outputs? | Affects logging and storage requirements. | "Does this handle PII / payment data / secrets?" |
+| Rate limiting required? | Even if "no", state it. | "Should this endpoint be rate-limited? Per-IP, per-user, per-tenant?" |
+| Audit log requirement? | Compliance-relevant. | "Do we need an audit trail for this operation?" |
+
+### Observability
+
+| Q | Why it matters | Example phrasing |
+|---|---|---|
+| What metric should be emitted? | Counter / timer / gauge. | "What metric do we want — count, latency, error rate?" |
+| What log lines? | Specific events to log. | "Any structured log events for this operation?" |
+| What alert? | When does this wake somebody up? | "Should an alert fire if this fails repeatedly?" |
+| Distributed tracing? | If your system uses it, the span name matters. | "Trace span name — what should it be?" |
+
+### Compatibility & migration
+
+| Q | Why it matters | Example phrasing |
+|---|---|---|
+| Backwards-compatible with prior version? | If you're changing existing behavior. | "Does this preserve the old behavior for existing callers?" |
+| Migration path? | For schema or contract changes. | "How do existing consumers move to the new contract?" |
+| Deprecation timeline? | If replacing something. | "Is the old endpoint deprecated? When does it sunset?" |
+
+### Project invariants
+
+Some projects carry invariants that a spec can violate without looking wrong. Walk this section against the **surface the spec touches** — these are questions to answer in the draft, not necessarily questions to put to the user.
+
+In SpecShip itself (and in any project whose `CLAUDE.md` states equivalents), the surfaces are:
+
+| Surface the spec touches | What the spec must account for |
+|---|---|
+| **MCP tools** (`src/mcp/`) — new tool, changed output, changed budget | Explore budgets are **monotonic**: a change may not shrink what a given budget returns. And `src/mcp/server-instructions.ts` is the **single source of truth** for agent-facing tool guidance — a spec that changes how the agent should use a tool must say that file is updated, not that guidance is duplicated elsewhere. |
+| **Installer** (`src/installer/`) — new asset, new target, changed layout | Name **which targets** are affected (Claude Code is the only default target; Gemini CLI is opt-in and MCP-entry-only). Say how **markers** are handled, so install is idempotent and uninstall fully reverses. Require a **CHANGELOG entry** — installer regressions break every new install silently. |
+| **Retrieval** — anything that changes how an answer is assembled | The budget is **tool-call count + wall-clock latency**, not tokens. A flow question must still resolve in 1–5 specship calls with zero Read/Grep. An acceptance bullet that lets the answer get slower or need more calls is a regression, however good the output looks. |
+| **Extraction** (`src/extraction/`) — new language, new node/edge type | Use the **exact `NodeKind` / `EdgeKind` strings** from `src/types.ts`; inventing a kind silently drops the data. Any new SQL or grammar `.wasm` must be added to **`copy-assets`** or it won't ship in the package. |
+
+Questions worth asking the user when the surface is ambiguous:
+
+- "Does this change what an existing tool returns for the same input?" (→ monotonicity + a CHANGELOG-visible behavior change)
+- "Should this ship on a default install, or behind an opt-in flag?" (→ installer tiering)
+- "Is this allowed to cost an extra tool call to get a better answer?" (→ the retrieval budget; the answer is usually no)
+
+## Decision framework — which to ask
+
+You can't ask every question. Ranking:
+
+1. **Trigger & scope** — without this, the spec has no boundary. **Always confirm.**
+2. **Success path contract** — without this, there's nothing to test. **Always confirm.**
+3. **Project invariants** — cheap to check, and a violation invalidates the spec. **Always walk.**
+4. **Failure modes** — usually 2/3 of the spec body, often skipped by the user's initial description. **Ask if not covered.**
+5. **Owner + priority** — quick to ask, valuable to record. **Ask if not in the description.**
+6. **Edge cases** — pick the 1–2 most likely to be wrong; mark the rest `[needs review]`.
+7. **Persistence, security, observability, compatibility** — ask only what the feature description suggests is relevant. Don't ask "is there a TTL" for a pure-function spec.
+
+## Example application
+
+User says: *"I want to add a spec for password reset via email."*
+
+You draft a first pass covering: entry endpoint, success response, email content reference, link expiry. The catalog walk gives you:
+
+- Trigger & scope — covered by "via email" (entry point inferred).
+- Success path — covered.
+- **Failure modes** — what if the email doesn't exist? rate-limited account? mailer down?
+- **TTL** — how long is the link valid?
+- **Rate limiting** — abuse vector if not rate-limited.
+- **Sensitive data** — is the reset link a secret? logged anywhere?
+- Observability — `[needs review]` (low priority for this spec).
+- Compatibility — `[needs review]` (greenfield, no existing version).
+- Owner — user said "auth team" implicitly via the feature name.
+- Project invariants — no MCP / installer / retrieval / extraction surface touched; nothing to account for.
+
+Your gap-fill round:
+
+> Before I write the file, four things:
+> 1. **Link TTL** — 1 hour? 24 hours? Until first use?
+> 2. **Rate limit per email** — how many resets per day per address before we throttle?
+> 3. **Non-existent email** — do we return success anyway (to prevent enumeration), or return 404?
+> 4. **What's in the email** — link only, or also a code? Are there constraints on the link format (custom domain, length)?
+
+That's 4 questions covering the high-impact gaps. The other catalog categories become `[needs review]` markers in the draft.

package/lib/dist/skills/spec-author/references/quality-rubric.md

@@ -0,0 +1,125 @@
+# Quality rubric
+
+The spec parser is forgiving — it'll accept anything with the right markers. This rubric is what separates a spec that ships from a spec that wastes everyone's time. Apply it before writing the file.
+
+## Seven properties of a good spec
+
+### 1. Specifies the contract, not the implementation
+
+A spec says **what**. Code says **how**. The split is load-bearing because:
+
+- Implementation details belong to the team that owns the code, not the spec author. Forcing them through a spec process is friction.
+- Specs that mirror implementation become brittle. Every refactor flags drift; the gate goes noisy; people stop trusting it.
+- Implementation can evolve; the contract is what users depend on.
+
+| ❌ Implementation-leak | ✅ Contract |
+|---|---|
+| MUST use bcrypt with cost factor 12 | Stored passwords MUST resist offline cracking with current GPU hardware |
+| MUST be a JWT signed with RS256 and 24 h TTL | Session tokens MUST be cryptographically tamper-evident and expire within 24 h |
+| MUST store events in PostgreSQL | Events MUST persist beyond process restart and remain queryable for ≥30 days |
+| MUST use Redis for the counter | The rate-limit counter MUST survive a single-instance restart |
+| MUST be at `POST /api/login` | MUST be addressable as a single POST endpoint at the auth-service boundary |
+
+Test for implementation-leak: "Could I swap the implementation library tomorrow and still satisfy this?" If no, it's too prescriptive.
+
+### 2. Testable acceptance criteria
+
+Every acceptance bullet is something a test can verify mechanically. Vague verbs ("handles", "supports", "manages") are not testable.
+
+| ❌ Untestable | ✅ Testable |
+|---|---|
+| Handles failed payments gracefully | A failed-payment webhook produces exactly one row in `billing_events` with `kind: 'retry_attempt'` |
+| Validates user input | Email addresses without `@` return 400 with `code: invalid_email` |
+| Supports concurrent requests | 100 concurrent requests to the same endpoint complete with no shared-state contamination (measured: distinct response IDs) |
+| Logs everything | Every state transition appends a line to `audit.log` with `(timestamp, actor, before, after)` |
+
+If you can't sketch how a test would assert against the bullet, rewrite it until you can. This matters twice over in SpecShip: the bullet is what a `verifies:` link's test has to actually assert, and an untestable bullet can never reach `verified`.
+
+### 3. One concern per REQ
+
+REQs are the unit of drift detection. When the implementation moves and a REQ's link goes `drifted`, you want to know exactly what to re-verify. A REQ that mixes concerns ("logs, validates, AND notifies on failure") means a small change to any one part flags the whole REQ — noise.
+
+| ❌ Mixed concerns | ✅ Split |
+|---|---|
+| REQ-AUTH-001: Login MUST be rate-limited AND audit-logged | REQ-AUTH-001: Login MUST be rate-limited. + REQ-AUTH-002: Auth failures MUST be audit-logged. |
+
+Test: read the REQ title. If you have to use "and" or "also", split.
+
+### 4. RFC 2119 keyword used correctly
+
+| Keyword | Use when |
+|---|---|
+| **MUST** / **MUST NOT** | Non-negotiable. Failing this is a bug or compliance breach. |
+| **SHOULD** / **SHOULD NOT** | Strongly recommended. Deviation requires written justification. |
+| **MAY** | Optional. Pure permission grant. No compliance impact either way. |
+
+Common mistakes:
+
+- **"MUST" inflation** — using MUST for everything dilutes the signal. Reserve it for things you genuinely won't ship without.
+- **"SHOULD" hedging** — using SHOULD because you're nervous about MUST. Either it's required or it isn't; pick.
+- **Weasel words mixed in** — "MUST ideally", "SHOULD probably", "ought to". Strike the modifiers.
+
+### 5. Parent/child structure that mirrors the conceptual hierarchy
+
+Document → requirements → acceptance bullets. Use heading depth to express this; don't flatten everything to H2.
+
+| ❌ Flat | ✅ Structured |
+|---|---|
+| `## REQ-AUTH-001: Failed logins rate-limited` <br>`## REQ-AUTH-002: Rate limit returns 429` <br>`## REQ-AUTH-003: Rate limit has Retry-After header` <br>`## REQ-AUTH-004: Counter resets on success` | `# Authentication` <br>`## REQ-AUTH-001 Failed logins MUST be rate-limited` <br>`### Acceptance`<br>`- A1: returns 429` <br>`- A2: includes Retry-After` <br>`- A3: counter resets on success` |
+
+The flat version makes drift detection useless (no concept of "this REQ has 4 acceptance criteria"); the structured version means changing the threshold is one drift event, not four.
+
+### 6. Owner and priority set
+
+Every spec needs:
+- **Owner** — who decides on contract changes. A team, a person, or a role. "Engineering" is too broad.
+- **Priority** — `high` / `medium` / `low` is fine. Helps when the drift queue is long.
+
+These belong in the frontmatter:
+
+```yaml
+---
+id: AUTH-DOC
+owner: security-team
+priority: high
+---
+```
+
+A spec without an owner is a spec without a stakeholder. It'll drift and nobody will fix it.
+
+### 7. Grounded in code that exists
+
+If `mcp__specship__specship_explore` is available and the feature touches existing code, the draft references real symbols. Don't write:
+
+```markdown
+implementations:
+  - src/auth.ts:login
+```
+
+…if the actual code is at `src/services/auth-service.ts:AuthService.handleLogin`. The wrong path becomes a permanent orphan link, polluting the drift queue.
+
+For greenfield work (no existing code yet), leave `implementations:` empty and omit `verifies:` entirely. The agent fills them in via `specship_link_assert` once the code and tests land.
+
+## Anti-patterns
+
+These are spec-author mistakes that produce specs the team will ignore.
+
+- **Specs that read like product requirements.** "User clicks the login button and sees a friendly error message." Specs are contracts, not UX storyboards. Strip the narrative.
+- **Specs that re-state the obvious.** "MUST not crash" applies to all code; it's not a spec, it's an axiom. Same for "MUST be secure" — too broad to test.
+- **Specs that future-proof aggressively.** "MUST support OAuth, SAML, OIDC, magic link, and passkeys." If you only need email + password today, spec that. Extend the spec when the second method actually lands.
+- **Specs written as TODO lists.** "MUST add a rate limiter, MUST write tests, MUST update docs." That's a task list, not a spec. The spec describes the contract after the work is done.
+- **Specs that quote regulations verbatim.** Cite the regulation in the body, paraphrase the operational requirement in the acceptance bullets. Verbatim regulatory text is uninterpretable for testing.
+
+## Sanity check before review
+
+Answer these for your draft:
+
+1. Could a teammate implement this in two different reasonable ways and both satisfy the spec? (If no, you've over-specified — implementation leak.)
+2. Could a teammate read the acceptance criteria and write the tests without asking you what you meant? (If no, the criteria are vague.)
+3. If a future refactor moves the linked symbol, does the spec still apply unchanged? (If no, the spec depends on implementation, not contract.)
+4. Does each REQ title have one concern? (If you used "and", split.)
+5. Is there at least one MUST and the right number of SHOULDs? (No MUSTs = the spec isn't required. All MUSTs = MUST is meaningless.)
+6. Owner and priority in frontmatter? (If not, add.)
+7. Do the `implementations:` paths exist (per `specship_explore` / `specship_node`)? (If unverified, mark `[needs review]`.)
+
+Seven yeses → proceed to gap-fill.

package/lib/dist/skills/spec-author/references/review-checklist.md

@@ -0,0 +1,175 @@
+# Review checklist
+
+After gap-fill, run this checklist against the draft before writing the file. It's also the rubric `/specship:spec review` uses for review-only mode.
+
+Output findings as a numbered list keyed to specific lines in the draft. Don't be polite — if something is broken, say so. The user will appreciate a sharp review more than a soft one.
+
+## Structural checks (must pass before writing)
+
+These produce HARD findings — block writing the file until fixed.
+
+### S1. Every heading has an embedded ID immediately above it
+
+Mental scan: for each heading, was the previous non-blank line `<!-- id: ... -->`?
+
+Failure: spec won't parse. `specship sync` will reject with `spec_missing_id`.
+
+Finding format: *"Line N: heading `## Foo` has no `<!-- id: -->` marker on line N-1."*
+
+### S2. No stranded IDs (two ID comments in a row)
+
+Mental scan: for each `<!-- id: ... -->`, is the next non-blank line a heading?
+
+Failure: parser emits `spec_stranded_id` warning. The first ID is silently lost.
+
+Finding format: *"Line N: `<!-- id: REQ-X -->` is followed by another `<!-- id: -->` on line N+1, not a heading. The first ID will be discarded."*
+
+### S3. IDs are unique within the file
+
+Two markers with the same ID do not error. Specs are stored with `INSERT OR REPLACE`, so the **LAST occurrence overwrites earlier ones** — the earlier heading's title, body, and links are silently gone, and nothing warns. This makes duplicates worse than they look: the REQ the reader sees first is not the REQ in the graph.
+
+Finding format: *"Lines N and M both declare `<!-- id: REQ-AUTH-001 -->`. The occurrence at line M overwrites the one at line N — the earlier requirement's body and links are lost. Renumber one of them."*
+
+### S4. Frontmatter is well-formed
+
+Open `---`, close `---`, valid YAML between. Parser emits `spec_bad_frontmatter` warning on malformed but tolerates it (the document just won't have a doc-level ID).
+
+Finding format: *"Frontmatter on lines N–M is missing the closing `---`."* / *"Frontmatter key `<key>` is not parseable as YAML."*
+
+### S5. `implementations:` / `verifies:` block syntax matches the parser
+
+Pattern: `[-*]\s+([^\s:]+)\s*:\s*([A-Za-z0-9_$.]+)`. Common breakages:
+- Missing the leading `-` or `*`.
+- Path contains spaces.
+- Qualified symbol has parentheses or generics — keep it to identifier chars and dots.
+- A bare path with no `:symbol` — tolerated, but creates **no edge** and emits `spec_bare_path_ref`. Only acceptable when there genuinely is no code symbol (e.g. a slash-command markdown file).
+
+Finding format: *"Line N: implementations entry `…` doesn't match the parser pattern. The link won't be extracted."*
+
+## Quality checks (block writing on critical, warn on minor)
+
+### Q1. RFC 2119 keyword used (CRITICAL if missing)
+
+Each requirement (H2-level node) should have at least one **MUST / SHOULD / MAY** in the title or body. Drafts without an RFC 2119 word read as wishful thinking, not as contracts.
+
+Finding format: *"REQ-X has no MUST/SHOULD/MAY in title or body. Recommend MUST since this looks like a hard requirement."*
+
+### Q2. Weasel words flagged
+
+Strike on sight: *should probably*, *ought to*, *could*, *might*, *generally*, *normally*, *ideally*, *in most cases*, *handles*, *supports*, *manages*, *implements* (when used vaguely as in "MUST implement authentication").
+
+Finding format: *"Line N uses `…ought to…`. RFC 2119 doesn't have a SHOULD-ish equivalent; pick MUST, SHOULD, or MAY."*
+
+### Q3. Implementation leak (CRITICAL)
+
+Strike on sight: specific library names, algorithm names, language versions, database systems, cache keys, internal class names. Specs describe the contract, not the choice.
+
+| Leak signal | Why |
+|---|---|
+| `MUST use bcrypt` | Names an algorithm. |
+| `MUST be stored in Redis` | Names a system. |
+| `MUST inherit from BaseAuthService` | Names an internal class. |
+| `MUST return JSON: { "ok": true, ... }` | Specifies the wire format precisely — only OK if the wire format IS the contract (public API). |
+| `MUST use the existing rate-limiter` | Hedges; names an implementation choice without saying what behavior is required. |
+
+Finding format: *"REQ-X line N specifies the implementation library `…`. Rewrite as the contract: `…cryptographically tamper-evident with a 24 h TTL…`."*
+
+### Q4. Acceptance bullets are individually testable
+
+Each `## Acceptance` bullet must be checkable by a single test assertion. If a bullet requires reading three other docs to know what to test, it's vague.
+
+Finding format: *"REQ-X.A2 (`bullet text`) is not directly testable. Suggest splitting into Aa: `…` and Ab: `…`, each with a concrete assertion."*
+
+### Q5. Title has one concern
+
+Use "and"/"or" as a tripwire. Two concerns = two REQs.
+
+Finding format: *"REQ-X title `Login MUST be rate-limited AND audit-logged` mixes two concerns. Split into REQ-X (rate-limit) and REQ-Y (audit-log)."*
+
+### Q6. Acceptance bullets cover the failure path
+
+Most drafts cover the happy path. Failure paths are half the spec.
+
+Quick heuristic: count happy-path bullets vs failure-path bullets. If failure-path < 1, that's almost certainly a gap.
+
+Finding format: *"REQ-X has 3 happy-path bullets (A1, A2, A3) but no failure-path bullets. What happens on: (a) invalid input, (b) downstream dependency failure, (c) timeout?"*
+
+### Q7. `implementations:` block points at code that exists (when applicable)
+
+When `mcp__specship__specship_explore` or `mcp__specship__specship_node` is available, verify each `implementations:` entry resolves. Skip for greenfield specs (where the code doesn't exist yet).
+
+Finding format: *"REQ-X line N points at `src/auth/login.ts:authenticate`. `specship_node` returns no symbol at that path. Either the path is wrong (suggestion: `src/services/auth-service.ts:AuthService.handleLogin`) or this is a greenfield spec (then leave `implementations:` empty)."*
+
+### Q8. `verifies:` block points at real test symbols (when present)
+
+`verifies:` is the test-evidence declaration that gates promotion to `verified`, so a wrong entry means the REQ can never reach that state. Check that each bullet names an addressable symbol — a bare `describe(...)` / `it(...)` string is not one.
+
+Finding format: *"REQ-X line N's `verifies:` bullet points at a test-case description, not a symbol. Either name a test helper function, or drop the block until the tests exist."*
+
+### Q9. No project invariant is contradicted
+
+Re-read the **Project invariants** section of `references/gap-questions.md` against the surface this spec touches (MCP tools, installer, retrieval, extraction). A spec that quietly shrinks an explore budget, adds an agent target, trades latency for output quality, or invents a NodeKind is broken regardless of how clean the markdown is.
+
+Finding format: *"REQ-X.A2 allows the explore answer to take two extra tool calls. The retrieval budget is a tool-call count, not a token count — restate the bullet so the call count doesn't grow, or say explicitly why this surface is exempt."*
+
+## Hygiene checks (warn, don't block)
+
+### H1. Frontmatter owner + priority set
+
+Not strictly required, but recommended. `[needs review]` markers are fine for a first draft.
+
+Finding format: *"Frontmatter is missing `owner:` and `priority:`. Consider adding even if you mark them `[needs review]`."*
+
+### H2. No stale `[needs review]` markers
+
+If gap-fill ran and the user answered, the markers should be replaced with their answers. Markers that survive review are still legitimate (the user genuinely doesn't know yet) but flag them anyway.
+
+Finding format: *"Lines N, M, P still carry `[needs review]` markers. List them so the user can address before commit."*
+
+### H3. No TODO / FIXME / WIP in the body
+
+These are work-in-progress signals that shouldn't ship in a spec.
+
+Finding format: *"Line N contains `TODO`. Specs are contracts; address before committing."*
+
+### H4. Body is concise
+
+Spec bodies that read like essays usually contain narrative justification that belongs in the commit message, not the spec.
+
+Finding format (subjective): *"REQ-X body is ~N words. Consider trimming the rationale — keep the spec to the contract; put motivation in the commit message."*
+
+## Sample review output
+
+For the password-reset draft from the gap-questions example:
+
+```
+Quality review of specs/password-reset.md:
+
+STRUCTURAL — all pass
+
+QUALITY:
+1. Line 12 — REQ-AUTH-005 title uses "should ideally". Drop "ideally";
+   either MUST or SHOULD.
+2. Line 18 — body specifies `JWT signed with HS256`. Implementation leak.
+   Rewrite as contract: "the reset token MUST be unguessable and
+   single-use".
+3. Line 24 — REQ-AUTH-005.A2 ("Handles expired links gracefully") is
+   not testable. Split: A2 = "An expired link returns 410 Gone";
+   A2b = "An expired link logs an audit event with reason
+   'reset_link_expired'".
+4. Line 31 — `implementations:` points at `src/auth/reset.ts:reset` but
+   `specship_node` returns no symbol there. This is a greenfield spec —
+   leave `implementations:` empty; the agent fills it in via
+   `link_assert` after implementation lands.
+
+HYGIENE:
+5. Frontmatter has owner but no priority. Suggest `priority: medium`.
+6. Line 8 has a stale `[needs review]` marker on the link-TTL question
+   you answered during gap-fill — replace with the agreed value (1 hour).
+
+Net: 4 quality issues, 2 hygiene. Recommend addressing items 2 + 3
+before writing the file. Items 1, 4, 5, 6 can be addressed in this draft
+or as a follow-up commit.
+```
+
+The review names line numbers, says what's wrong, suggests a fix. Don't waffle; users want sharp signal.