@specship/specship-win32-arm64 0.24.0 → 0.28.0

package/lib/dist/server/routes/graph.js

@@ -158,7 +158,8 @@ export async function registerGraphRoutes(app) {
     /**
      * GET /api/graph/health — feeds the Graph overview panel:
      *   - linkHealth: spec-link counts per state (verified/drifted/broken/orphaned/…)
-     *   - edgeKinds:  edge counts grouped into calls / implements-documents / tests
+     *   - edgeKinds:  calls / implements-documents edge counts, plus `tests` —
+     *                 resolved test-evidence spec_links, not an edge bucket
      *   - hubs:       the most-connected nodes (by total degree), for the "Most connected" list
      *   - anchored:   nodes that are spec_links targets (by degree), for the "Anchored" list
      */
@@ -173,13 +174,12 @@ export async function registerGraphRoutes(app) {
         }
         const db = getDb(cg);
         // Edge kinds — bucket by the node kinds the edge connects, mirroring the
-        // design's "calls / implements / tests" legend. spec endpoints → implements,
-        // test endpoints → tests, everything else → calls.
+        // design's "calls / implements" legend. spec endpoints → implements,
+        // everything else → calls.
         const edgeKinds = db.prepare(`
       SELECT
         CASE
           WHEN ns.kind = 'spec' OR nt.kind = 'spec' THEN 'implements'
-          WHEN ns.kind = 'test' OR nt.kind = 'test' THEN 'tests'
           ELSE 'calls'
         END as bucket,
         COUNT(*) as count
@@ -191,6 +191,16 @@ export async function registerGraphRoutes(app) {
         const edgeKindMap = { calls: 0, implements: 0, tests: 0 };
         for (const r of edgeKinds)
             edgeKindMap[r.bucket] = r.count;
+        // Test evidence is a spec_links relationship, not an edge between node
+        // kinds — there is no `test` NodeKind, so the old `ns.kind = 'test'`
+        // bucket was permanently 0 (REQ-REVINT-008.A1). Count the resolved
+        // tests/validates links instead: a spec whose `verifies:` block points at
+        // a real symbol is exactly one test-evidence relationship.
+        const testEvidence = db.prepare(`
+      SELECT COUNT(*) as c FROM spec_links
+      WHERE kind IN ('tests', 'validates') AND resolved_node_id IS NOT NULL
+    `).get();
+        edgeKindMap['tests'] = testEvidence.c ?? 0;
         // Synthesized (heuristic) edge count — dashed in the legend.
         const synth = db.prepare(`SELECT COUNT(*) as c FROM edges WHERE provenance = 'heuristic'`).get();
         edgeKindMap['synth'] = synth.c ?? 0;
@@ -236,6 +246,13 @@ export async function registerGraphRoutes(app) {
      * among them. Isolated (degree-0) nodes are omitted — an overview shows the
      * connected core. `total` reports the full node count so the UI can say
      * "showing N of M".
+     *
+     * Traceability is unioned in on top of that cut (REQ-TVIZ-010.A1). A spec
+     * node's degree is 1–2, so the top-N pass pruned every spec↔code edge out of
+     * the whole-repo view: the one relationship the product exists to show was
+     * the first thing dropped. Spec nodes that participate in an edge — and the
+     * code nodes on the other end — are therefore kept regardless of degree. A
+     * spec node with no edges is still omitted; it would draw as an island.
      */
     app.get('/api/graph/full', async (req, reply) => {
         const cg = await resolveCg(app, req, reply);
@@ -255,15 +272,44 @@ export async function registerGraphRoutes(app) {
       JOIN nodes n ON n.id = deg.node
       ORDER BY deg.degree DESC
     `).all(limit);
+        // Spec nodes with at least one edge, plus whatever sits at the other end
+        // of those edges — the traceability union (REQ-TVIZ-010.A1).
+        const traceRows = db.prepare(`
+      SELECT n.id, n.name, n.kind, n.file_path as filePath, COALESCE(deg.degree, 0) as degree
+      FROM nodes n
+      LEFT JOIN (
+        SELECT node, COUNT(*) as degree FROM (
+          SELECT source as node FROM edges
+          UNION ALL
+          SELECT target as node FROM edges
+        ) GROUP BY node
+      ) deg ON deg.node = n.id
+      WHERE n.id IN (
+        SELECT e.source FROM edges e JOIN nodes s ON s.id = e.source WHERE s.kind = 'spec'
+        UNION
+        SELECT e.target FROM edges e JOIN nodes t ON t.id = e.target WHERE t.kind = 'spec'
+        UNION
+        SELECT e.target FROM edges e JOIN nodes s ON s.id = e.source WHERE s.kind = 'spec'
+        UNION
+        SELECT e.source FROM edges e JOIN nodes t ON t.id = e.target WHERE t.kind = 'spec'
+      )
+    `).all();
         const keep = new Set(nodeRows.map((n) => n.id));
+        const nodes = nodeRows.map((n) => ({ id: n.id, name: n.name, kind: n.kind, filePath: n.filePath, degree: n.degree }));
+        for (const n of traceRows) {
+            if (keep.has(n.id))
+                continue;
+            keep.add(n.id);
+            nodes.push({ id: n.id, name: n.name, kind: n.kind, filePath: n.filePath, degree: n.degree });
+        }
         const allEdges = db.prepare(`SELECT source as "from", target as "to", kind, provenance FROM edges`).all();
         const edges = allEdges.filter((e) => keep.has(e.from) && keep.has(e.to));
         const totalRow = db.prepare(`SELECT COUNT(*) as c FROM nodes`).get();
         return {
-            nodes: nodeRows.map((n) => ({ id: n.id, name: n.name, kind: n.kind, filePath: n.filePath, degree: n.degree })),
+            nodes,
             edges,
-            total: totalRow.c ?? nodeRows.length,
-            shown: nodeRows.length,
+            total: totalRow.c ?? nodes.length,
+            shown: nodes.length,
         };
     });
 }

package/lib/dist/server/routes/knowledge.js

@@ -0,0 +1,118 @@
+/**
+ * GET /api/knowledge (REQ-KNOW-007).
+ *
+ * Read-only knowledge view: every domain fact with its id, title, type and the
+ * requirement ids it links to at the spec tier (`parentId` + `depends_on`),
+ * plus — for `type: external` facts — the dependency it is pinned to, the
+ * version it was verified against, and its freshness against the version
+ * installed in the project (`fresh` / `stale` / `unverifiable`).
+ *
+ * Like the domain route, it reaches the engine only through the dynamically
+ * loaded instance (`cg.getSpecQueries()`, `cg.getProjectRoot()`) and never
+ * runtime-imports the bare `@specship/specship` package (DOM-SPECSHIP-004).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+function linkedIds(parentId, dependsOn) {
+    const out = [];
+    if (typeof parentId === 'string' && parentId.length > 0)
+        out.push(parentId);
+    if (Array.isArray(dependsOn)) {
+        for (const d of dependsOn)
+            if (typeof d === 'string' && d.length > 0)
+                out.push(d);
+    }
+    else if (typeof dependsOn === 'string' && dependsOn.length > 0) {
+        for (const d of dependsOn.split(','))
+            if (d.trim())
+                out.push(d.trim());
+    }
+    return [...new Set(out)];
+}
+/** Read one flat `key: value` from a markdown file's frontmatter. */
+function frontmatterValue(file, key) {
+    let source;
+    try {
+        source = readFileSync(file, 'utf-8');
+    }
+    catch {
+        return undefined;
+    }
+    const lines = source.split(/\r?\n/);
+    if ((lines[0] ?? '').trim() !== '---')
+        return undefined;
+    for (let i = 1; i < lines.length; i++) {
+        const line = (lines[i] ?? '').trim();
+        if (line === '---')
+            break;
+        const idx = line.indexOf(':');
+        if (idx > 0 && line.slice(0, idx).trim() === key) {
+            return line.slice(idx + 1).trim().replace(/^(['"])(.*)\1$/, '$2') || undefined;
+        }
+    }
+    return undefined;
+}
+/** The version of `dependency` installed under `<projectRoot>/node_modules`. */
+function installedVersion(projectRoot, dependency) {
+    if (dependency.includes('..'))
+        return undefined;
+    const pkg = path.join(projectRoot, 'node_modules', dependency, 'package.json');
+    if (!existsSync(pkg))
+        return undefined;
+    try {
+        const v = JSON.parse(readFileSync(pkg, 'utf-8')).version;
+        return typeof v === 'string' ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function registerKnowledgeRoutes(app) {
+    app.get('/api/knowledge', async (req, reply) => {
+        const cg = await app.activeCg(req);
+        if (!cg) {
+            reply.code(409).send({ error: 'no project selected', code: 'no_project' });
+            return;
+        }
+        const projectRoot = cg.getProjectRoot();
+        const facts = [];
+        for (const f of cg.getSpecQueries().getSpecsByKind('domain')) {
+            const meta = (f.metadata ?? {});
+            const type = typeof meta.type === 'string' ? meta.type : '';
+            const fact = {
+                id: f.id,
+                title: f.title,
+                type,
+                linkedRequirementIds: linkedIds(f.parentId, meta.depends_on),
+            };
+            if (type === 'external') {
+                const dependency = typeof meta.dependency === 'string' ? meta.dependency : undefined;
+                // `version` is a known top-level frontmatter key the extractor keeps as
+                // the numeric spec version, so a semver string may not survive into
+                // metadata — fall back to the fact's own frontmatter on disk.
+                const version = typeof meta.version === 'string'
+                    ? meta.version
+                    : frontmatterValue(path.join(projectRoot, f.sourcePath), 'version');
+                // Freshness from the project's own node_modules only. The CLI's
+                // `specship knowledge stale` (findStaleExternalFacts) also consults the
+                // global npm root; the server stays local-only and never imports the
+                // engine package directly (DOM-SPECSHIP-004), so a dependency installed
+                // only globally reads `unverifiable` here — never `fresh`.
+                const installed = dependency ? installedVersion(projectRoot, dependency) : undefined;
+                fact.dependency = dependency;
+                fact.version = version;
+                fact.stale =
+                    installed === undefined || version === undefined
+                        ? 'unverifiable'
+                        : installed === version
+                            ? 'fresh'
+                            : 'stale';
+                if (installed !== undefined)
+                    fact.installedVersion = installed;
+            }
+            facts.push(fact);
+        }
+        facts.sort((a, b) => a.id.localeCompare(b.id));
+        return { facts };
+    });
+}

package/lib/dist/server/routes/mcp.js

@@ -400,17 +400,18 @@ function collectUsage(cg) {
         if (!s || s.example)
             continue;
         try {
-            s.example = { tool, args: JSON.parse(row.input_json) };
+            s.example = { tool, args: JSON.parse(row.input_json), synthesized: false };
         }
         catch { /* skip bad row */ }
     }
-    // Fallback example: the server's top tool with empty args.
+    // Fallback example: the server's top tool with empty args. Flagged
+    // synthesized so the page can't pass it off as a recorded call.
     for (const s of byServer.values()) {
         if (s.example)
             continue;
         const top = [...s.tools.entries()].sort((a, b) => b[1].calls - a[1].calls)[0];
         if (top)
-            s.example = { tool: top[0], args: {} };
+            s.example = { tool: top[0], args: {}, synthesized: true };
     }
     return byServer;
 }

package/lib/dist/server/routes/projects.js

@@ -79,10 +79,10 @@ export async function enumerate(claudeRoot, resolverOpts) {
     return out;
 }
 /**
- * Bound on how many projects get a live driftCount per request. Mirrors the
- * /api/events sweep: every lookup opens the project's graph through the
- * registry LRU (maxOpen 16), so an unbounded pass over a large project list
- * churns open/close cycles on every GET. enumerate() sorts by recency, so
+ * Bound on how many projects get a live driftCount per request: every lookup
+ * opens the project's graph through the registry LRU (maxOpen 16), so an
+ * unbounded pass over a large project list churns open/close cycles on every
+ * GET. enumerate() sorts by recency, so
  * the bounded prefix is exactly what the switcher surfaces first; the rest
  * stay `null` (unknown), which the UI renders as no pill.
  */

package/lib/dist/server/routes/spec.js

@@ -130,6 +130,24 @@ export async function registerSpecRoutes(app) {
             return;
         return cg.getSpecFunnel();
     });
+    /**
+     * GET /api/spec/coverage[?spec=<id>] — the test-coverage rollup
+     * (REQ-VSTATE-006.A2).
+     *
+     * Registered before `/api/spec/:id` and matched statically (same shape as
+     * `/api/spec/funnel`), so `coverage` is never read as a spec id. Computed on
+     * the dynamically-loaded instance — no runtime import of the package here.
+     *
+     * The verdicts come from `tests` links only, which is the point: the
+     * dashboard previously counted an `implements` link as "met".
+     */
+    app.get('/api/spec/coverage', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const scope = req.query.spec && req.query.spec.length > 0 ? req.query.spec : undefined;
+        return cg.getSpecCoverage(scope);
+    });
     app.get('/api/spec/:id', async (req, reply) => {
         const cg = await resolveCg(app, req, reply);
         if (!cg)
@@ -244,25 +262,32 @@ export async function registerSpecRoutes(app) {
         const spec = sq.getSpecById(body.spec_id);
         if (!spec)
             return reply.code(404).send({ error: 'spec not found' });
+        // Validate the target against the graph before recording (REQ-REVINT-003.A3
+        // — same rule as the MCP tool). The dashboard's caller can't retry from a
+        // refusal the way an agent can, so an unresolvable target is recorded as
+        // `orphaned` and reported back as such — never as `implemented`.
+        const nodeKind = body.target_node_kind ?? 'function';
+        const node = cg
+            .getSpecLinkResolver()
+            .findLogicalTarget(body.target_file_path, body.target_qualified_name, nodeKind);
         const now = Date.now();
         const id = sq.upsertSpecLink({
             specId: body.spec_id,
             targetFilePath: body.target_file_path,
             targetQualifiedName: body.target_qualified_name,
-            targetNodeKind: body.target_node_kind ?? 'function',
-            resolvedNodeId: undefined,
+            targetNodeKind: nodeKind,
+            resolvedNodeId: node?.id,
             kind: body.kind ?? 'implements',
-            state: 'implemented',
+            state: node ? 'implemented' : 'orphaned',
             driftAxis: null,
             specHashAtLink: spec.contentHash,
-            nodeSigAtLink: undefined,
+            nodeSigAtLink: node?.signature,
             provenance: 'agent-asserted',
             confidence: 1.0,
             createdAt: now,
             updatedAt: now,
         });
-        cg.getSpecLinkResolver().resolveLinksForFiles([body.target_file_path]);
-        return { id, ok: true };
+        return { id, ok: true, resolved: node !== null, state: node ? 'implemented' : 'orphaned' };
     });
     app.post('/api/spec/link-verify', async (req, reply) => {
         const cg = await resolveCg(app, req, reply);
@@ -280,8 +305,13 @@ export async function registerSpecRoutes(app) {
         // tool: promoting an `implements` link to verified requires the spec to
         // have at least one test-evidence link (kind='tests'). Without this the
         // dashboard's Verify button would bypass the gate.
+        // File-derived evidence only (REQ-REVINT-005.A2): an agent-asserted `tests`
+        // link is a DB-only row, so it can't underwrite a promotion.
         if (body.result === 'pass' && link.kind === 'implements') {
-            const hasEvidence = sq.getLinksBySpec(link.specId).some((l) => l.kind === 'tests');
+            const hasEvidence = sq
+                .getLinksBySpec(link.specId)
+                .some((l) => l.kind === 'tests' &&
+                (l.provenance === 'spec-declaration' || l.provenance === 'code-comment'));
             if (!hasEvidence) {
                 return reply.code(409).send({
                     error: `no test evidence linked to ${link.specId} — declare its proving test via a "verifies:" block in the spec (or an @verifies comment on the test) before promoting to verified`,
@@ -290,6 +320,18 @@ export async function registerSpecRoutes(app) {
             }
         }
         sq.updateSpecLinkState(body.link_id, body.result === 'pass' ? 'verified' : 'broken', null);
+        // Persist the evidence behind the verdict (REQ-REVINT-004) — same record
+        // shape as the MCP tool, so both surfaces render one audit trail.
+        const verification = {
+            result: body.result,
+            verifiedAt: new Date().toISOString(),
+        };
+        if (body.reason)
+            verification.reason = body.reason;
+        const evidence = (body.evidence ?? []).filter((e) => typeof e === 'string' && e.length > 0);
+        if (evidence.length > 0)
+            verification.evidence = evidence;
+        sq.updateSpecLinkMetadata(body.link_id, { ...(link.metadata ?? {}), verification });
         return { ok: true, state: body.result === 'pass' ? 'verified' : 'broken' };
     });
     /**

package/lib/dist/server/server.js

@@ -17,7 +17,6 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import Fastify from 'fastify';
 import cors from '@fastify/cors';
 import { startWatcher, primaryProjectMatcher } from './ingest/index.js';
-import { backfillDisplaced } from './ingest/impact-backfill.js';
 import { recostUnpricedPrompts } from './ingest/pricing-backfill.js';
 import { ProjectRegistry } from './project-registry.js';
 import { makeStaticHandler, isAssetPath } from './static-handler.js';
@@ -28,10 +27,10 @@ import { registerClaudeRoutes } from './routes/claude.js';
 import { registerStatusRoutes } from './routes/status.js';
 import { registerMemoryRoutes } from './routes/memory.js';
 import { registerProjectsRoutes } from './routes/projects.js';
-import { registerEventsRoutes } from './routes/events.js';
 import { registerReflectRoutes } from './routes/reflect.js';
 import { registerMaintainabilityRoutes } from './routes/maintainability.js';
 import { registerDomainRoutes } from './routes/domain.js';
+import { registerKnowledgeRoutes } from './routes/knowledge.js';
 import { registerMcpRoutes } from './routes/mcp.js';
 import { registerConfigRoutes } from './routes/config.js';
 import { readServerConfig } from './server-config.js';
@@ -112,12 +111,36 @@ export async function createServer(options) {
             credentials: false,
         });
     }
+    // Test-only fault injection (REQ-TVIZ-004.A2). `E2E_FAULT` holds a
+    // comma-separated list of `/api` path substrings; a matching request is
+    // answered 500 instead of reaching its handler, so the e2e suite can prove
+    // the SPA degrades to an error state on any route without a code change per
+    // test. The hook is registered ONLY when the variable is set — with it unset
+    // (every production boot) there is no hook and no per-request work at all.
+    const faultPatterns = (process.env.E2E_FAULT ?? '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (faultPatterns.length > 0) {
+        console.error(`[specship-server] E2E_FAULT active — 500ing /api paths matching: ${faultPatterns.join(', ')}`);
+        app.addHook('onRequest', async (req, reply) => {
+            const pathOnly = req.url.split('?')[0] ?? req.url;
+            if (!pathOnly.startsWith('/api/'))
+                return;
+            const hit = faultPatterns.find((p) => pathOnly.includes(p));
+            if (!hit)
+                return;
+            await reply.code(500).send({ error: `injected fault (E2E_FAULT=${hit})`, code: 'e2e_fault' });
+        });
+    }
     // Lazy-load specship. Used as the open() impl for the registry, and
     // (only when a primary path is set) to open the primary instance below.
     const cgMod = await loadSpecShip();
-    // maxOpen must exceed the /api/events cross-project sweep size (10) plus
-    // the primary and a user-picked project, or the sweep churns open/close
-    // cycles through the LRU on every poll.
+    // maxOpen must exceed the /api/projects drift sweep size
+    // (DRIFT_SWEEP_LIMIT = 10 in routes/projects.ts) plus the primary and a
+    // user-picked project, or the sweep churns open/close cycles through the
+    // LRU on every request. (The removed cross-project alert poller swept the
+    // same width — REQ-SURF-001.A2.)
     const registry = new ProjectRegistry({ verbose, maxOpen: 16 }, (p) => cgMod.SpecShip.open(p));
     // Primary project (optional). When set, specship-scoped routes default to
     // it when no `?project=<slug>` is provided, and the analytics ingest
@@ -171,17 +194,8 @@ export async function createServer(options) {
         ownedWatcher = true;
         if (verbose)
             console.error('[specship-server] JSONL ingest watcher started');
-        // Backfill displaced_files / resolution for pre-upgrade rows (is_specship=1,
-        // resolution IS NULL). Idempotent — safe to run on every boot. Non-fatal:
-        // a failure here must never abort server startup.
-        try {
-            backfillDisplaced(dbHandle, resolveGraph);
-            if (verbose)
-                console.error('[specship-server] specship-impact backfill complete');
-        }
-        catch (err) {
-            console.error('[specship-server] specship-impact backfill failed (non-fatal):', err instanceof Error ? err.message : String(err));
-        }
+        // The specship-impact boot backfill is gone with the engine it fed
+        // (REQ-SURF-005) — nothing reads displaced_files/resolution any more.
         // Re-cost prompts ingested while their model family was unpriced,
         // e.g. fable sessions stuck at $0 (REQ-DASHINT-001.A2). Idempotent.
         try {
@@ -259,10 +273,10 @@ export async function createServer(options) {
     await registerClaudeRoutes(app);
     await registerMemoryRoutes(app);
     await registerProjectsRoutes(app);
-    await registerEventsRoutes(app);
     await registerReflectRoutes(app);
     await registerMaintainabilityRoutes(app);
     await registerDomainRoutes(app);
+    await registerKnowledgeRoutes(app);
     // Chat routes removed (CHAT-REMOVE-DOC) — /api/chat and /api/chat/stream
     // intentionally 404; the reviewer loop lives on Workflows + Runs.
     await registerMcpRoutes(app);

package/lib/dist/skills/spec-author/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: spec-author
+description: Author SpecShip-compatible specs from a feature description — draft the markdown, walk a gap-filling checklist, run a quality review, and write the file under `specs/`. Use this whenever the user wants to write a new requirement, draft a spec for a feature they're about to build, capture acceptance criteria, define a contract, or asks "what should the spec for X look like." Also trigger on phrases like "write a spec", "draft a requirement", "create a REQ", "new spec for", "I want to add a feature and capture the requirements", "spec out", "let's write the requirements for". The skill produces a spec that `specship sync` parses cleanly, grounded in the project's existing code via `mcp__specship__specship_explore`. Do NOT use this skill for reverse-engineering existing code into specs, or for implementing an already-written spec (use `/specship:spec implement` for that).
+---
+
+# Spec Author
+
+You're helping the user write a SpecShip-compatible Markdown spec from scratch. Your job is to produce a draft that (a) parses cleanly under `specship sync`, (b) follows the project's quality rubric, and (c) is grounded in the project's actual code so the resulting implementation has a real target.
+
+The user usually starts with a one-line feature description. You're going to turn that into a complete spec, asking only the questions the description doesn't already answer.
+
+## What this skill does NOT do
+
+- **It does not invent business motivation.** If the user doesn't tell you why a feature is needed, don't make it up. Mark the purpose as `[needs user confirmation]` instead.
+- **It does not implement code.** Spec only. Implementation is `/specship:spec implement`'s job.
+- **It does not promise a perfect spec.** Specs are negotiable; the skill produces a first draft that the user reviews. Every uncertain section carries a `[needs review]` flag so the user knows where to focus.
+- **It does not bulk-author.** One requirement, or one document with N children, per invocation. "Spec the whole app" gets refused.
+
+## The format your output must follow
+
+Read `references/format.md` before writing the file. The spec parser at `src/extraction/specs/markdown-spec-extractor.ts` is strict about one thing: **every heading must have an `<!-- id: REQ-X -->` comment immediately above it**. Get this wrong and `specship sync` errors out.
+
+Short version:
+
+```markdown
+---
+id: AUTH-DOC
+title: Authentication
+owner: security
+priority: high
+---
+
+<!-- id: AUTH-DOC -->
+# Authentication
+
+This document covers login, session management, and rate-limiting.
+
+<!-- id: REQ-AUTH-001 -->
+## Failed logins MUST be rate-limited
+
+The login endpoint rejects more than 5 failed attempts per IP per minute.
+
+implementations:
+  - src/auth/login.ts:authenticate
+  - src/auth/rate-limit.ts:enforce
+
+verifies:
+  - __tests__/auth-rate-limit.test.ts:rejectsSixthAttempt
+
+## Acceptance
+<!-- id: REQ-AUTH-001.A1 -->
+- 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.
+```
+
+`references/format.md` covers the edge cases: optional frontmatter fields, the `implementations:` and `verifies:` block syntax, hierarchy by heading depth, kind inference (document / requirement / acceptance), `.A1`-style child IDs for acceptance bullets.
+
+## The loop
+
+### Step 1 — Scope check
+
+Confirm the user wants:
+- **One requirement** under an existing document (most common — pick this if unsure), or
+- **A new document with N child requirements** (when they're spec'ing a whole feature area), or
+- **Refine an existing draft** (they paste markdown; you review and gap-fill).
+
+If they say "spec the whole app", refuse and ask them to pick a feature area. Bulk-authored specs without per-REQ thinking are unreviewable.
+
+### Step 2 — Ground in the code
+
+If `mcp__specship__specship_explore` is available, call it on terms from the feature description before drafting. Two things this gives you:
+
+- **Realistic file paths and symbol names** for the `implementations:` block. Don't write `implementations: - src/auth.ts:login` if the project has `src/services/auth-service.ts:AuthService.handleLogin`.
+- **Existing conventions to align with.** If the codebase already has rate-limiting, your draft should reference the existing rate limiter rather than inventing a new one.
+
+Skip this step only if (a) you don't have specship tools available, or (b) the feature is greenfield (no existing code to ground in).
+
+### Step 3 — Draft the spec
+
+Produce the full markdown body. Cover:
+
+- **Frontmatter** (optional but recommended) — `id`, `title`, `owner`, `priority`.
+- **Document body or single requirement** — depending on scope. Use RFC 2119 keywords (MUST / SHOULD / MAY) in the requirement title.
+- **Acceptance criteria** — under a `## Acceptance` heading, one bullet per testable condition, each with its own `.A<N>` ID. Each bullet must be independently checkable — "MUST reject more than 5 attempts" not "MUST rate-limit".
+- **`implementations:` block** — when you have grounding from Step 2, list the file paths + symbol names the implementation will live in. Speculative; the spec writer can adjust before implementation runs.
+- **`verifies:` block** — the test-evidence declaration. Leave it out of a fresh spec unless the tests already exist; it's what promotes a link to `verified`.
+- **`[needs user confirmation]` flags** — wherever you made an assumption (owner, priority, edge case behavior, exact threshold). Don't ask the user every question in one pass; mark the gap in the draft and surface it in Step 4.
+
+Apply `references/quality-rubric.md`: no implementation leak, one concern per REQ, testable bullets, parent/child structure, RFC 2119 keywords used correctly.
+
+### Step 4 — Gap-fill
+
+Walk the checklist in `references/gap-questions.md` against your draft. Most categories — failure modes, TTLs, concurrency, observability, security, ownership — will already be answered by Steps 2–3. **Ask the user only about the gaps that remain**, no more than 3–5 questions in one round.
+
+The catalog's **Project invariants** section is the one part you should always walk: a spec that contradicts a house invariant gets rejected at review, no matter how well-formed it is.
+
+Phrase questions so the user can answer in one line each:
+
+> A few details to nail down before I write the file:
+> 1. Owner — `security`, or someone else?
+> 2. When the 5-attempt threshold is hit, do we just return 429, or also fire a webhook / log?
+> 3. Counter reset on successful login — only for that IP, or for all sessions on the account?
+
+Update the draft with their answers. If they say "skip these for now," leave the markers in and proceed.
+
+### Step 5 — Review
+
+Run `references/review-checklist.md` against the final draft. Surface findings as a short numbered list:
+
+> Quality review:
+> 1. REQ-AUTH-001.A1 — could be more specific. Suggest naming the response header (`Retry-After`) and the duration.
+> 2. The `implementations:` block points at `src/auth/login.ts:authenticate` — that symbol exists per `specship_node` ✓.
+> 3. No explicit acceptance criterion for "counter reset on successful login" — add as A3?
+
+Apply the user's choices to the draft.
+
+### Step 6 — Write the file
+
+Use the `Write` tool against `<project-root>/specs/<slug>.md`. Choose the slug from the feature name (kebab-case, no date prefix — the date is in git). If a file with that name already exists, append to it (with the new REQ markers) rather than overwriting; tell the user what you did.
+
+After writing:
+
+```
+Wrote specs/<slug>.md.
+
+Next steps:
+  1. Review the file (a few `[needs review]` flags remain if you skipped questions in Step 4).
+  2. specship sync   # picks up the new spec into the graph
+  3. /specship:spec implement <REQ-ID>   # when you're ready to build it
+```
+
+## When to use the workflow instead of the skill directly
+
+This skill is the **lightweight path** — runs conversationally in Claude Code, no formal approval gates. For team contexts that want the same discipline `spec-implement` enforces, point the user at:
+
+```
+specship workflow run spec-author --input DESCRIPTION="..."
+```
+
+That workflow wraps this same loop with two approval gates — one after gap-fill, one before file write — and a git-worktree-isolated artifact directory. Use it when (a) the spec author is reviewing a teammate's draft, or (b) the team has agreed every new spec gets a written review step.
+
+## Anti-patterns
+
+- **Writing the spec without grounding in code.** The result is a beautiful document that points at symbols which don't exist. Use `specship_explore` first.
+- **Asking the user every question in the catalog.** Five questions is plenty per round; the rest become `[needs review]` markers the user resolves at their pace.
+- **Specifying the implementation.** "MUST use JWT signed with RS256" is implementation. "MUST be cryptographically tamper-evident with a 24 h TTL" is contract. The skill steers toward contract; review and rewrite if you find yourself naming algorithms.
+- **One REQ that does too much.** "MUST handle login, logout, and password reset" is three REQs. Split before drafting.
+- **Forgetting the embedded `<!-- id: -->` markers.** Every heading needs one immediately above. Without it `specship sync` fails the file with `spec_missing_id`.
+- **Reusing an ID already used in the same file.** The later occurrence wins (the store does `INSERT OR REPLACE`), so the earlier heading's content is silently overwritten.
+- **Using today's date in the slug.** The date lives in git; the slug should be the feature name (`payment-retry.md`, not `2026-06-18-payment-retry.md`).
+
+## Reference files
+
+The references/ directory is organized by stage:
+
+| File | Stage | What it covers |
+|---|---|---|
+| `references/format.md` | Step 3 (draft) | Exact markdown the parser accepts |
+| `references/quality-rubric.md` | Step 3 (draft) | What makes a "good" spec |
+| `references/gap-questions.md` | Step 4 (gap-fill) | Catalog of questions to walk, plus the project invariants |
+| `references/review-checklist.md` | Step 5 (review) | What to scan for before finalizing |
+
+Read the relevant reference before each step. Don't paraphrase from memory — the format file in particular is the parser's contract.