@specship/specship-win32-arm64 0.28.0 → 0.30.0

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

@@ -16,10 +16,85 @@ import { writeSseHead } from './sse.js';
 import { promises as fs, watch } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { createSlugResolver } from '../ingest/project-paths.js';
+import { createSlugResolver, encodeProjectSlug } from '../ingest/project-paths.js';
+import { recordedProjects } from '../ingest/recorded-projects.js';
+import { transcriptAdapters } from '../ingest/transcripts/index.js';
+import { CLAUDE_PROFILE } from '../host-profiles.js';
 const projectsBus = new EventEmitter();
 projectsBus.setMaxListeners(0); // many SSE subscribers + internal
 export async function enumerate(claudeRoot, resolverOpts) {
+    const fromTranscripts = await enumerateTranscriptProjects(claudeRoot, resolverOpts);
+    // Projects any agent has SpecShip installed in (REQ-AGENTSWITCH-011) — the
+    // only source for an agent whose session folders cannot be mapped back to a
+    // path. Listed once: a project already found above keeps that entry.
+    const seen = new Set(fromTranscripts.map((p) => p.path));
+    // Agents that keep their own project list (REQ-AGENTSWITCH-019.A1).
+    const fromAgents = [];
+    const home = resolverOpts?.home ?? os.homedir();
+    for (const adapter of transcriptAdapters()) {
+        let found = [];
+        try {
+            found = adapter.listProjects?.(home) ?? [];
+        }
+        catch { /* one agent's files never block another's */ }
+        for (const p of found) {
+            if (seen.has(p.path))
+                continue;
+            seen.add(p.path);
+            fromAgents.push({ ...(await projectState(p.path)), slug: encodeProjectSlug(p.path), path: p.path, sessionCount: p.sessionCount, lastModifiedMs: p.lastModifiedMs, driftCount: null });
+        }
+    }
+    const fromRecord = [];
+    for (const rec of recordedProjects(resolverOpts?.recordPath)) {
+        if (seen.has(rec.path))
+            continue;
+        seen.add(rec.path);
+        let exists = false;
+        let initialized = false;
+        try {
+            exists = (await fs.stat(rec.path)).isDirectory();
+        }
+        catch { /* gone */ }
+        if (exists) {
+            try {
+                initialized = (await fs.stat(path.join(rec.path, '.specship'))).isDirectory();
+            }
+            catch { /* not initialized */ }
+        }
+        fromRecord.push({
+            slug: encodeProjectSlug(rec.path),
+            path: rec.path,
+            exists,
+            initialized,
+            sessionCount: 0,
+            lastModifiedMs: rec.recordedAtMs,
+            driftCount: null,
+        });
+    }
+    return [...fromTranscripts, ...fromAgents, ...fromRecord].sort(byRecency);
+}
+async function projectState(p) {
+    let exists = false;
+    let initialized = false;
+    try {
+        exists = (await fs.stat(p)).isDirectory();
+    }
+    catch { /* gone */ }
+    if (exists) {
+        try {
+            initialized = (await fs.stat(path.join(p, '.specship'))).isDirectory();
+        }
+        catch { /* not initialized */ }
+    }
+    return { exists, initialized };
+}
+/** Recent activity first; ties broken by path. */
+function byRecency(a, b) {
+    if (b.lastModifiedMs !== a.lastModifiedMs)
+        return b.lastModifiedMs - a.lastModifiedMs;
+    return a.path.localeCompare(b.path);
+}
+async function enumerateTranscriptProjects(claudeRoot, resolverOpts) {
     let entries;
     try {
         entries = await fs.readdir(claudeRoot, { withFileTypes: true });
@@ -71,11 +146,7 @@ export async function enumerate(claudeRoot, resolverOpts) {
         out.push({ slug, path: decoded, exists, initialized, sessionCount, lastModifiedMs, driftCount: null });
     }
     // Recent activity first; ties broken by path.
-    out.sort((a, b) => {
-        if (b.lastModifiedMs !== a.lastModifiedMs)
-            return b.lastModifiedMs - a.lastModifiedMs;
-        return a.path.localeCompare(b.path);
-    });
+    out.sort(byRecency);
     return out;
 }
 /**
@@ -167,7 +238,7 @@ function stopWatcher() {
 }
 // --- Route registration -----------------------------------------------------
 export async function registerProjectsRoutes(app) {
-    const claudeRoot = path.join(os.homedir(), '.claude', 'projects');
+    const claudeRoot = path.join(os.homedir(), CLAUDE_PROFILE.configDir, 'projects');
     startWatcher(claudeRoot, false);
     app.addHook('onClose', async () => { stopWatcher(); });
     const driftSource = (slug) => app.projects.getBySlug(slug);

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

@@ -7,6 +7,7 @@
  * boot-time primary). Returns 409 / `no_project` when neither is selectable.
  */
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 /**
  * Resolve a project-relative path to an absolute path under the project
@@ -85,6 +86,119 @@ function atomicWriteFile(targetPath, content) {
     fs.writeFileSync(tmp, content, 'utf-8');
     fs.renameSync(tmp, targetPath);
 }
+const PLAN_DRIFT_STATES = ['drifted', 'broken', 'orphaned'];
+const metaString = (meta, key) => {
+    const v = meta?.[key];
+    return typeof v === 'string' && v.trim() ? v.trim() : null;
+};
+/**
+ * The JIRA base URL for issue links — and ONLY that. Reads
+ * `SPECSHIP_JIRA_BASE_URL`, else the `baseUrl` field of the user-level JIRA
+ * config (`SPECSHIP_JIRA_CONFIG` or `~/.specship/jira.json`). That file also
+ * holds credentials; nothing but `baseUrl` is ever read out of the parsed
+ * object, returned or logged. No JIRA request is made (REQ-DASHSIMPLE-003.A4).
+ */
+export function readJiraBaseUrl() {
+    const fromEnv = process.env.SPECSHIP_JIRA_BASE_URL;
+    let base = fromEnv && fromEnv.trim() ? fromEnv.trim() : null;
+    if (!base) {
+        const file = process.env.SPECSHIP_JIRA_CONFIG ?? path.join(os.homedir(), '.specship', 'jira.json');
+        try {
+            const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+            const v = parsed && typeof parsed === 'object' ? parsed.baseUrl : undefined;
+            if (typeof v === 'string' && v.trim())
+                base = v.trim();
+        }
+        catch { /* absent or malformed → no links, plain-text keys */ }
+    }
+    if (!base || !/^https?:\/\//i.test(base))
+        return null;
+    return base.replace(/\/+$/, '');
+}
+const byFileOrder = (a, b) => a.sourcePath < b.sourcePath ? -1 : a.sourcePath > b.sourcePath ? 1 : (a.startLine ?? 0) - (b.startLine ?? 0);
+/**
+ * Epic → story → task from the indexed specs alone (REQ-DASHSIMPLE-003).
+ * `epicKey` and `jira_issue_<REQ>` come from each document's stored metadata
+ * (its frontmatter, as indexed) — the spec files are not re-parsed here.
+ * Documents sharing an `epicKey` merge into one epic in file order; a document
+ * without one is its own group titled after the document.
+ */
+// @implements REQ-DASHSIMPLE-003
+export function buildPlan(cg, jiraBaseUrl) {
+    const sq = cg.getSpecQueries();
+    const all = sq.getAllSpecs();
+    const coverage = new Map(cg.getSpecCoverage().requirements.map((r) => [r.specId, r]));
+    const docs = all.filter((s) => s.kind === 'document').sort(byFileOrder);
+    const docIds = new Set(docs.map((d) => d.id));
+    const reqsByDoc = new Map();
+    const looseByFile = new Map();
+    for (const s of all) {
+        if (s.kind !== 'requirement')
+            continue;
+        if (s.parentId && docIds.has(s.parentId)) {
+            const arr = reqsByDoc.get(s.parentId) ?? [];
+            arr.push(s);
+            reqsByDoc.set(s.parentId, arr);
+        }
+        else {
+            // A requirement outside any document still belongs in the plan.
+            const arr = looseByFile.get(s.sourcePath) ?? [];
+            arr.push(s);
+            looseByFile.set(s.sourcePath, arr);
+        }
+    }
+    const story = (s, meta) => {
+        const cov = coverage.get(s.id) ?? null;
+        return {
+            specId: s.id,
+            title: s.title,
+            body: s.body ?? '',
+            jiraKey: metaString(meta, `jira_issue_${s.id}`),
+            coverage: cov,
+            tasks: (cov?.criteria ?? []).map((c) => ({ specId: c.specId, title: c.title, verdict: c.verdict })),
+        };
+    };
+    const entries = [];
+    for (const d of docs) {
+        const reqs = (reqsByDoc.get(d.id) ?? []).sort(byFileOrder);
+        entries.push({
+            key: metaString(d.metadata, 'epicKey'),
+            title: d.title,
+            sourcePath: d.sourcePath,
+            startLine: d.startLine,
+            doc: { id: d.id, title: d.title, stories: reqs.map((r) => story(r, d.metadata)) },
+        });
+    }
+    for (const [file, reqs] of looseByFile) {
+        entries.push({
+            key: null, title: file, sourcePath: file,
+            doc: { id: file, title: file, stories: reqs.sort(byFileOrder).map((r) => story(r, undefined)) },
+        });
+    }
+    entries.sort(byFileOrder);
+    const epics = [];
+    const byKey = new Map();
+    for (const e of entries) {
+        if (e.key) {
+            const hit = byKey.get(e.key);
+            if (hit) {
+                hit.docs.push(e.doc);
+                continue;
+            }
+            const epic = { key: e.key, title: e.title, docs: [e.doc] };
+            byKey.set(e.key, epic);
+            epics.push(epic);
+        }
+        else {
+            epics.push({ key: null, title: e.title, docs: [e.doc] });
+        }
+    }
+    const titles = new Map(all.map((s) => [s.id, s.title]));
+    const driftLinks = sq
+        .getLinksByState([...PLAN_DRIFT_STATES])
+        .map((l) => ({ ...l, specTitle: titles.get(l.specId) ?? null }));
+    return { jiraBaseUrl, epics, driftLinks };
+}
 async function resolveCg(app, req, reply) {
     const cg = await app.activeCg(req);
     if (!cg) {
@@ -148,6 +262,17 @@ export async function registerSpecRoutes(app) {
         const scope = req.query.spec && req.query.spec.length > 0 ? req.query.spec : undefined;
         return cg.getSpecCoverage(scope);
     });
+    /**
+     * GET /api/spec/plan — epic → story → task for the Plan reader
+     * (REQ-DASHSIMPLE-003). Read-only, no JIRA call; the only JIRA config field
+     * it exposes is the base URL.
+     */
+    app.get('/api/spec/plan', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        return buildPlan(cg, readJiraBaseUrl());
+    });
     app.get('/api/spec/:id', async (req, reply) => {
         const cg = await resolveCg(app, req, reply);
         if (!cg)

package/lib/dist/server/server.js

@@ -190,10 +190,16 @@ export async function createServer(options) {
         const primaryPath = options.projectRoot ?? null;
         const isPrimary = primaryPath ? primaryProjectMatcher(primaryPath) : () => false;
         const resolveGraph = (projectPath) => primaryPath && isPrimary(projectPath) ? primaryCg : null;
-        watcher = startWatcher(dbHandle, { verbose, resolveGraph });
+        // projectPaths lets hash-keyed transcripts (Gemini CLI) resolve to the
+        // primary project's real path (REQ-AGENTSWITCH-004).
+        watcher = startWatcher(dbHandle, {
+            verbose,
+            resolveGraph,
+            projectPaths: primaryPath ? [primaryPath] : [],
+        });
         ownedWatcher = true;
         if (verbose)
-            console.error('[specship-server] JSONL ingest watcher started');
+            console.error('[specship-server] transcript ingest watcher started');
         // 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,

package/lib/dist/skills/design-md/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: design-md
+description: Turn a Claude Design project (claude.ai/design link or handoff bundle) or a Figma file (figma.com link) into specs/<slug>/design.md, a pixel-exact design reference that even a small model (Haiku, Gemini Flash) can build the UI from without guessing. Use this when someone shares a design to build or update, asks to "capture", "document" or "import" a design, or the design changed and design.md must catch up. Also use it to implement UI from an existing design.md.
+---
+
+# design.md: a pixel-exact design reference
+
+design.md is one Markdown file per design, at `specs/<slug>/design.md`. It
+states every visual value **verbatim** in a fixed layout, so whoever builds the
+UI looks a value up instead of inferring it. A small model given the raw design
+rounds `13.5px` to `14px`, swaps `#5B93F2` for "blue-500", and forgets the
+hover state. Given design.md, it doesn't have to decide anything.
+
+There are two halves, and the split is the point:
+
+- **Values come from code, not from you.** `specship design extract` reads the
+  source and writes the *Generated reference*: every custom property, color,
+  font, size, spacing, radius, shadow, transition, breakpoint and style rule,
+  verbatim, with usage counts. **Never type a value into design.md yourself.**
+  Copy it from the generated block, which copied it from the source.
+- **Structure comes from you.** You write the *authored* sections (screens,
+  components and states, motion, responsive, assets). They explain how the
+  values assemble, and they cite selectors and values from the generated block.
+
+`specship design check` decides when you're done. It fails on a missing
+section, an empty authored section, approximate wording, a stale source, or a
+source value missing from the reference.
+
+## The loop
+
+### 1. Capture the source verbatim
+
+Pick a slug from the design's name (kebab-case). Save everything under
+`specs/<slug>/`. Read `references/sources.md` for each source's exact steps:
+
+| The user gave you | Capture with | Save as |
+|---|---|---|
+| `claude.ai/design/...` link | designer tools: `designer_session` → `designer_snapshot` | `snapshot.html` + every local stylesheet it links |
+| a designer handoff bundle (`handoff-<ts>/`) | copy from `project/` (no fetch) | `snapshot.html` + linked CSS, decision record into `source.md` |
+| `figma.com/design/...` link | Figma MCP: `get_metadata`, `get_design_context`, `get_variable_defs`, `get_screenshot` | `figma/<frame>.tsx`, `figma/variables.json`, `figma/<frame>.png`, `figma/metadata.xml` |
+| exported HTML/CSS files | copy as-is | keep the file names |
+
+Hard rules:
+- **Never plain-fetch a design link.** A `claude.ai/design` URL returns a
+  1 KB loader shell, and a Figma URL returns a login page. If the tools
+  are missing, stop and give the setup step:
+  - designer tools: run `designer setup` once.
+  - Figma MCP: `claude mcp add --transport http figma https://mcp.figma.com/mcp`.
+- Save tool output **byte for byte**. Don't reformat, summarise or "clean up"
+  a snapshot.
+
+### 2. Extract
+
+```bash
+specship design extract specs/<slug>/snapshot.html \
+  --out specs/<slug>/design.md --title "<Design name>" --origin "<the link>"
+```
+
+For Figma, pass the captured files instead:
+
+```bash
+specship design extract specs/<slug>/figma/<frame>.tsx specs/<slug>/figma/variables.json --out ...
+```
+
+If the generated block says **Missing linked stylesheet**, capture that file
+next to the snapshot and run extract again with `--update`. The reference is
+incomplete until then.
+
+### 3. Write the authored sections
+
+Fill **Screens & layout**, **Components & states**, **Interactions & motion**,
+**Responsive behaviour** and **Assets**. `references/authored-sections.md`
+gives the exact shape of each, with an example. The rules:
+
+- Every number, color and font you write must appear in the Generated
+  reference (or Figma `metadata.xml` for frame sizes). Cite the selector:
+  "Card padding `16px 20px` (`.card`)".
+- Name every state the source styles: `:hover`, `:focus-visible`, `:active`,
+  `:disabled`, `[aria-*]`, `.is-*` classes. For each one, list the values
+  that change.
+- Look at the screenshot or rendered snapshot for order, alignment and
+  grouping. Only the generated block gives you the numbers.
+- No approximate words: approximately, roughly, about 12, ~12, similar to,
+  etc., TBD. `check` rejects them. If the source doesn't say, write
+  "Not specified in the design; ask the designer" rather than inventing a value.
+- Delete each `<!-- design-md: … -->` hint once its section is written.
+
+### 4. Check until clean
+
+```bash
+specship design check specs/<slug>/design.md
+```
+
+Fix every error and run it again. **You are finished only when it passes.**
+
+### 5. Connect it to the spec
+
+Add `design: specs/<slug>/design.md` to the frontmatter of the spec that
+covers this UI. `/specship:spec implement` then has the implementer read
+design.md before any UI edit. The spec keeps the contract (behaviour,
+accessibility, data). design.md keeps the pixels. Never copy values into the
+spec.
+
+## When the design changes
+
+Capture the new source over the old files (step 1), then:
+
+```bash
+specship design extract <same sources> --update specs/<slug>/design.md
+```
+
+Only the generated block is replaced. Your authored sections are kept, and a
+dated **Change log** entry lists every token and value that was added, removed
+or changed (`old → new`). Go through that entry and update each authored
+sentence that cites a changed value. Then run `check` again.
+
+## When code changes the UI
+
+design.md describes the UI that ships, so it changes in the same commit as
+the UI code. That applies to a new component, a changed state, layout or
+token, and a copy change.
+
+1. Update the authored sections that describe what moved.
+2. Add a dated line under **Change log**: what changed and the requirement
+   id. For example, `- 2026-10-27: Sign In button gains a loading state
+   (REQ-AUTH-004).`
+3. If the design source changed too (a new snapshot or Figma export), run
+   `specship design extract <sources> --update <design.md>` first. Only the
+   generated block is replaced, and the value changes are logged for you.
+4. Run `specship design check <design.md>`.
+
+`specship postcheck` enforces this, and `/specship:spec implement` runs it.
+The check fails if a change touches UI files that a design-backed spec
+governs, but that spec's design.md gets no new Change log entry, or no
+longer passes `check`. A spec is design-backed when its frontmatter has
+`design:`. The UI files it governs are the `.tsx`/`.jsx`/`.vue`/`.svelte`/
+`.css`/`.html` files in its `implementations:` blocks. While you implement
+that spec, every UI file you change counts.
+
+## Building UI from design.md
+
+This applies to you, or to any implementer you brief:
+
+1. Read design.md top to bottom once: Fidelity rules first.
+2. Rebuild the **Element outline** element by element: same nesting, each
+   element's inline style exactly, text exactly, and each `svg … = <svg …>`
+   pasted as is. For class selectors, use the declarations in **Style rules
+   (verbatim)** exactly. Use the **Design tokens** table to keep
+   `var(--…)` names when the project's stack supports CSS variables.
+3. Reuse a project token only when its value is exactly equal. Otherwise add
+   the value as written.
+4. Build every state in **Components & states**, and every breakpoint in
+   **Responsive behaviour**.
+5. Add no CSS the design doesn't have. No resets, no normalizers, no
+   `button { font: inherit }` "fixes". Leave an element design.md doesn't
+   style on the browser default: the design was rendered with that default,
+   and one invented reset moves every pixel after it.
+6. Anything design.md doesn't state is a question, not a guess.
+7. **Verify, then fix, until it matches.** Render your UI to static HTML. A
+   plain `.html` build already is; for a framework, save the rendered page.
+   Then run:
+
+   ```bash
+   specship design verify <build.html> --against specs/<slug>/design.md
+   ```
+
+   It compares your build's element outline with design.md's, line by line
+   (nesting, tags, classes, attributes, text and SVG), and checks that your
+   stylesheet rules keep design.md's order wherever a later rule would
+   override an earlier one. Fix each reported line or rule pair and run it
+   again. **You are done when it matches.** A small model that
+   misnests one container gets caught here and fixes it in one pass.

package/lib/dist/skills/design-md/references/authored-sections.md

@@ -0,0 +1,90 @@
+# Writing the authored sections
+
+The Generated reference has the values. The authored sections say how they
+assemble into screens and components. Write them so a small model can build the
+UI by following them in order.
+
+Shared rules:
+- Follow the **Element outline**'s nesting exactly. When you write
+  "Anatomy", list only the direct children of that element, in outline
+  order, and say which parent each part sits in. A part that is a sibling of
+  a row is never "in" that row. The outline is authoritative: if your prose
+  and the outline disagree, a builder follows the outline, and your prose
+  was wrong.
+- Every value you write appears in the Generated reference, or in
+  `figma/metadata.xml` for frame sizes. Copy it exactly: `13.5px` stays
+  `13.5px`, and `#5B93F2` keeps its case.
+- Cite the selector (or Figma layer name) behind every value, in backticks.
+- One bullet per fact. Short, declarative, no adjectives that carry no value
+  ("nice", "subtle", "slightly").
+- When the source doesn't specify something, write: "Not specified in the
+  design; ask the designer."
+- `specship design check` rejects these words: approximately, roughly,
+  about <n>, ~<n>, similar to, etc., TBD, something like.
+
+## Screens & layout
+
+One `###` per screen or frame. Cover:
+- the frame size and the background,
+- the layout model: grid or flex, direction, columns, gaps, max-width,
+  alignment,
+- the regions top to bottom, or left to right, each with its size and the
+  selector that styles it.
+
+```markdown
+### Spec detail (1440 × 900)
+
+- Background `#0B0D11` (`#boot-splash`); text `#E8EBF0`.
+- Two columns: sidebar `280px` fixed (`div.col`) + content `1fr`; no gap.
+- Content padding `28px 32px 56px` (`div.scroll-y`), scrolls vertically.
+- Top to bottom: header row (`div.row.gap-8`, padding `15px 16px`), metadata line
+  (`div.sp-metaline`, margin-top `32px`), criteria list.
+```
+
+## Components & states
+
+One `###` per component. Cover:
+- its selector or selectors,
+- its anatomy: the child parts in order,
+- its exact box: size, padding, radius, border, shadow,
+- its typography: family, size, weight, line height, letter spacing, color,
+- then **one bullet per state**, naming the values that change. Cover every
+  state the source styles: default, `:hover`, `:focus-visible`, `:active`,
+  `:disabled`, `[aria-selected]` / `[aria-expanded]`, `.is-*`, loading, empty,
+  error.
+
+```markdown
+### Nav item (`a` in the sidebar)
+
+- Height `32px`; padding `0px 10px`; gap `10px`; radius `6px`.
+- Label `13px` / weight `450`, color `#8A93A3`.
+- States:
+  - default: background transparent.
+  - `:hover`: background `rgba(255,255,255,0.06)`, label `#E8EBF0`.
+  - `[aria-current=page]`: background `rgba(91,147,242,0.12)`, label weight `600`.
+  - `:focus-visible`: outline `2px solid #5B93F2`, offset `2px`.
+```
+
+## Interactions & motion
+
+For each transition or animation, give:
+- the trigger,
+- the animated properties,
+- the duration, easing and delay,
+- the keyframes name.
+
+If there are none, write "None in this design."
+
+## Responsive behaviour
+
+For each breakpoint in the Generated reference's **Breakpoints** inventory,
+say exactly what changes. If there are none, write "Single fixed layout."
+
+## Assets
+
+For each image, icon and font, give:
+- the file or link,
+- the rendered size,
+- where it's used.
+
+Include icon sets with the icon names used. If there are none, write "None."

package/lib/dist/skills/design-md/references/sources.md

@@ -0,0 +1,71 @@
+# Capturing a design source
+
+Every path ends with the source saved **byte for byte** under `specs/<slug>/`,
+so `specship design extract` can read it and `specship design check` can tell
+when it changes. Never plain-fetch a design URL.
+
+## Claude Design: a `claude.ai/design` link
+
+The link looks like `https://claude.ai/design/p/<project-id>/?file=<File+Name>.html`.
+The file name comes from the `file=` parameter (`Data+Flow.html` is
+`Data Flow.html`).
+
+1. `designer_session({ action: "status" })`. If it reports that CDP is not up
+   or Chrome is not signed in, tell the user to run `designer setup` once and
+   **stop**.
+2. If the session isn't on this project yet, `designer_session({ action: "adopt" })`
+   on an open tab, or `resume` the stored URL.
+3. `designer_snapshot({ filename: "<File Name>.html" })`. It returns
+   `htmlPath`, the real rendered HTML read from inside the preview frame.
+4. Copy it byte for byte: `cp "<htmlPath>" specs/<slug>/snapshot.html`.
+5. Copy every **local** stylesheet the snapshot links
+   (`<link rel="stylesheet" href="styles.css">`) next to it, keeping the
+   relative path. Remote font links (Google Fonts) stay as links.
+6. Write `specs/<slug>/source.md` with the link, the file name and today's
+   date.
+
+## Claude Design: a handoff bundle
+
+A bundle is `handoff-<ts>/` holding `project/` and `decision-record.md`. It is
+already on disk, so nothing is fetched.
+
+1. Choose the file: `project/<chosen>.html`. If there are several and the user
+   hasn't said which, ask.
+2. `cp` it to `specs/<slug>/snapshot.html`, along with the CSS, JS and assets it
+   references from `project/`.
+3. Write `specs/<slug>/source.md` with the bundle path, then append
+   `decision-record.md` verbatim. It records why the design looks the way it
+   does.
+
+## Figma: a `figma.com` link
+
+The link looks like `https://www.figma.com/design/<fileKey>/<name>?node-id=<a>-<b>`.
+The node id is `<a>:<b>`. Use the Figma MCP server's tools. If they aren't in
+the session, tell the user to run
+`claude mcp add --transport http figma https://mcp.figma.com/mcp`, sign in,
+and restart. Then **stop**.
+
+For each frame (screen) in scope:
+
+| Tool | Gives you | Save as |
+|---|---|---|
+| `get_metadata` | the layer tree with every frame's x, y, width, height | `specs/<slug>/figma/metadata.xml` |
+| `get_design_context` | code for the frame, including every color, size and spacing as a literal | `specs/<slug>/figma/<frame>.tsx` |
+| `get_variable_defs` | the variables (tokens) the frame uses, as name → value | `specs/<slug>/figma/variables.json` |
+| `get_screenshot` | a rendered image of the frame | `specs/<slug>/figma/<frame>.png` |
+
+- Save each response verbatim. When `get_design_context` returns code, write
+  the code exactly. Don't convert it to the project's framework yet; that
+  is implementation.
+- If a frame is too large for one `get_design_context` call, call it on each
+  child frame named in `metadata.xml`. Save each one as its own `.tsx`.
+- Then extract:
+  `specship design extract specs/<slug>/figma/*.tsx specs/<slug>/figma/variables.json --out specs/<slug>/design.md --origin "<link>"`.
+- Frame sizes for **Screens & layout** come from `metadata.xml`. Look at the
+  `.png` to see order and grouping.
+
+## Exported HTML / CSS
+
+Copy the files into `specs/<slug>/` with their names unchanged, and pass the
+HTML entry file to `extract`. Local stylesheets it links are read
+automatically.

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

@@ -132,7 +132,7 @@ Next steps:
 
 ## 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:
+This skill is the **lightweight path** — runs conversationally in your coding agent, 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="..."

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

@@ -102,7 +102,7 @@ In SpecShip itself (and in any project whose `CLAUDE.md` states equivalents), th
 | 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. |
+| **Installer** (`src/installer/`) — new asset, new target, changed layout | Name **which targets** are affected (Claude Code and Gemini CLI both get the full surface — MCP entry, steering, hooks, commands, skills, subagent — except the Claude-only status line; `specship install` with no target wires the agent it runs under). 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. |
 

package/lib/dist/spec-lint/lint.d.ts

@@ -20,7 +20,7 @@ export type LintSeverity = 'error' | 'warning';
  * code (`spec_missing_id`, `spec_stranded_id`, `spec_bare_path_ref`,
  * `spec_acceptance_parent_mismatch`) so one vocabulary spans both layers.
  */
-export type LintCode = 'spec_duplicate_id' | 'spec_orphan_acceptance_parent' | 'spec_requirement_without_acceptance' | 'spec_needs_review_marker' | 'spec_unknown_evidence_kind' | 'spec_external_fact_missing_provenance' | 'spec_malformed_enforced_rule' | 'spec_no_negative_case' | 'spec_missing_non_goals' | 'spec_missing_test_plan' | 'spec_requirement_without_rfc2119' | string;
+export type LintCode = 'spec_duplicate_id' | 'spec_duplicate_id_cross_file' | 'spec_orphan_acceptance_parent' | 'spec_requirement_without_acceptance' | 'spec_needs_review_marker' | 'spec_unknown_evidence_kind' | 'spec_external_fact_missing_provenance' | 'spec_malformed_enforced_rule' | 'spec_no_negative_case' | 'spec_missing_non_goals' | 'spec_missing_test_plan' | 'spec_requirement_without_rfc2119' | string;
 export interface LintFinding {
     code: LintCode;
     severity: LintSeverity;
@@ -47,6 +47,31 @@ export interface LintReport {
     /** The exit-code predicate (A3): errors fail, warnings alone do not. */
     hasErrors: boolean;
 }
+/**
+ * Every `<!-- id: X -->` declaration in a spec file, in line order (1-indexed).
+ * A brief or design transcript declares nothing — it is not a spec, so its
+ * markers (quoted from elsewhere) must not collide with real ones.
+ */
+export declare function collectIdDeclarations(filePath: string, source: string): Array<{
+    id: string;
+    line: number;
+}>;
+/** Where one id is declared: a project-relative file and a 1-indexed line. */
+export interface IdDeclarationSite {
+    filePath: string;
+    line: number;
+}
+/**
+ * Ids declared in more than one spec file (REQ-MULTIDEV-001). The persistence
+ * layer upserts by id, so after a merge where two branches picked the same id
+ * in different files, one section silently replaces the other. Repeats inside a
+ * single file are `spec_duplicate_id`'s job and are not reported here.
+ *
+ * Emits one error per colliding id per declaring file, anchored at that file's
+ * first declaration, with every `path:line` listed (sorted) in the message.
+ * Callers decide which of the returned findings belong to a linted file.
+ */
+export declare function findCrossFileDuplicates(decls: Map<string, IdDeclarationSite[]>): LintFinding[];
 /**
  * Lint one spec file's source. `filePath` is used verbatim in findings, so
  * callers should pass a project-relative path.