@selvakumaresra/specship 0.4.0 → 0.6.0

package/README.md

@@ -24,7 +24,7 @@
 Requires Node.js 22.5+ (Node 24.x recommended — its bundled SQLite has FTS5, which SpecShip needs):
 
 ```bash
-npm i -g @selvakumaresra/specship@0.1.0
+npm i -g @selvakumaresra/specship@0.5.0
 ```
 
 Offline / air-gapped client workstation? Clone or copy this repo onto the machine and run:
@@ -121,7 +121,7 @@ When Claude Code explores a codebase, it spawns **Explore agents** that scan fil
 | **Always Fresh** | File watcher uses native OS events (FSEvents/inotify/ReadDirectoryChangesW) with debounced auto-sync — the graph stays current as you code, zero config |
 | **20+ Languages** | TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Objective-C, Swift, Kotlin, Dart, Lua, Luau, Svelte, Liquid, Pascal/Delphi |
 | **Framework-aware Routes** | Recognizes web-framework routing files and links URL patterns to their handlers across 14 frameworks |
-| **Desktop UI** | Live dashboard for cost, drift, tool-call heatmap, cache analytics, plus a project picker that auto-discovers every project you've used Claude Code in |
+| **Desktop UI** | Live dashboard for cost, drift, tool-call heatmap, cache analytics, SpecShip token impact, plus a project picker that auto-discovers every project you've used Claude Code in |
 | **100% Local** | No data leaves your machine. No API keys. No external services. SQLite database only |
 
 <details>
@@ -207,6 +207,15 @@ One big number — your **cache read rate** — plus a 2×2 breakdown: creation
 
 > **Project & time scope.** Every numeric on this page respects the project picker's active selection and the range selector top-right. Switching projects re-fetches without a page reload.
 
+#### SpecShip Impact · is SpecShip earning its keep?
+
+A dedicated page that puts SpecShip's own token cost next to what it saved, per prompt → session → project → all-projects (the Session Detail page carries the same per-prompt chip and per-session line). Two numbers, deliberately kept apart:
+
+- **Spend — measured.** The exact tokens SpecShip's own tool calls put into the conversation.
+- **Saved — estimated.** For each code-graph query, the size of the files its symbols live in — what a `Read` of them would have cost — deduplicated per prompt.
+
+**"Saved" is a conservative lower bound.** It credits only a single direct read of the named files, *not* the multi-call grep + read exploration (re-reads, dead-ends, extra turns) SpecShip actually replaces — the end-to-end win that the [benchmarks](#why-specship) measure with a with-vs-without comparison. So treat spend as exact and saved as a floor; a fixed per-session tool-definition overhead is shown separately, and every estimate is marked `est.`.
+
 #### Beyond the dashboard
 
 Same shell, same shortcuts, more depth:
@@ -219,6 +228,7 @@ Same shell, same shortcuts, more depth:
 | **Workflows + Runs** | Run any bundled or project-tier workflow, watch its DAG advance live via SSE, approve / reject pause gates, inspect per-step artifacts (plan.md, diff.md, test_results.md). |
 | **Chat** | A codegraph-aware companion chat with slash commands, collapsible tool calls, and per-turn cost footers. |
 | **Sessions / Heatmap / Costs / Compare / Tips** | The Claude Code analytics suite — sessions deep-dive with per-prompt expand, file/tool/subagent heatmap drilldowns, per-day cost line + by-model donut, cross-project comparison. |
+| **SpecShip Impact** | Measured tokens SpecShip's tools spent vs. an estimated (conservative) count of tokens saved, per prompt / session / project / all-projects, with a spend-vs-saved trend and per-tool breakdown. |
 | **Memory** | The full `CLAUDE.md` hierarchy (managed / user / project / subdir) plus `@import` resolution plus `~/.claude/memory/*.md` agent-written notes. Sources view + Effective (merged-precedence) view. |
 | **Design system** | The visual reference for the entire app — every token, palette swatch, semantic state, button/pill family, and the 4 px node-color legibility test that the graph relies on. |
 
@@ -252,7 +262,7 @@ SpecShip detects web-framework routing files and emits `route` nodes linked by `
 ## Quick Start
 
 ```bash
-npm i -g @selvakumaresra/specship@0.1.0
+npm i -g @selvakumaresra/specship@0.5.0
 specship install --yes           # writes ~/.claude.json + ~/.claude/settings.json
 cd your-project && specship init -i
 # restart Claude Code
@@ -284,7 +294,7 @@ specship install --no-permissions            # skip auto-allow list
 
 **Install globally:**
 ```bash
-npm install -g @selvakumaresra/specship@0.1.0
+npm install -g @selvakumaresra/specship@0.5.0
 ```
 
 **Add to `~/.claude.json`:**
@@ -470,7 +480,7 @@ that drive the graph directly: `DatabaseConnection`, `QueryBuilder`,
 
 **Embedding requirements**
 
-- Install from npm (`npm i @selvakumaresra/specship@0.1.0`) so the matching
+- Install from npm (`npm i @selvakumaresra/specship@0.5.0`) so the matching
   per-platform package — which carries the compiled library and its
   dependencies — is fetched alongside the shim.
 - The API runs on **your** runtime, so it needs **Node 22.5+** for the built-in
@@ -551,9 +561,9 @@ See [Get Started](#get-started) for the one-line install commands.
 
 **MCP hits `database is locked`** — current builds shouldn't: SpecShip bundles its own Node runtime and uses Node's built-in `node:sqlite` in WAL mode, where concurrent reads never block on a writer. If you still see it:
 
-- **You're on an old (pre-0.9) install.** Reinstall: `npm i -g @selvakumaresra/specship@0.1.0`.
-- **`specship status` shows `Journal:` other than `wal`** — WAL couldn't be enabled on this filesystem (common on network shares and WSL2 `/mnt`), so reads can block on writes. Move the project (with its `.specship/` folder) onto a local disk.
+- **You're on an old (pre-0.9) install.** Reinstall: `npm i -g @selvakumaresra/specship@0.5.0`.
 
+**`specship status` shows `Journal:` other than `wal`** — WAL couldn't be enabled on this filesystem (common on network shares and WSL2 `/mnt`), so reads can block on writes. Move the project (with its `.specship/` folder) onto a local disk.
 **MCP server not connecting** — Ensure the project is initialized/indexed, verify the path in your MCP config, and check that `specship serve --mcp` works from the command line.
 
 **Missing symbols** — The MCP server auto-syncs on save (wait a couple seconds). Run `specship sync` manually if needed. Check that the file's language is supported and isn't inside a `.gitignore`d or default-excluded directory (e.g. `node_modules`, `dist`).

package/commands/ss-brainstorm.md

@@ -0,0 +1,68 @@
+---
+description: Brainstorm a requirement — analyse, ground in code, explore approaches, loop with you, and ONLY on your explicit confirmation write a design brief and hand off to /ss-spec-author. Nothing is written until you confirm.
+argument-hint: <requirement to brainstorm>
+allowed-tools: Read, Write, Edit, Bash, mcp__specship__specship_explore, mcp__specship__specship_search, mcp__specship__specship_node, mcp__specship__specship_files, mcp__specship__specship_spec
+---
+
+# SpecShip Brainstorm: `$ARGUMENTS`
+
+The **divergent** front of spec-driven development. You explore the problem with the human and DECIDE; `/ss-spec-author` formalizes the decision into a spec. Run this conversationally — do NOT batch.
+
+## The hard rule (read first)
+
+**Write NOTHING to disk until the human EXPLICITLY confirms.** No brief, no spec, no scratch file during the loop. Treat the default as no-write. A vague "maybe", "looks ok", silence, or a follow-up question is **not** confirmation — only an unambiguous "yes, write it" / "confirmed" / "go ahead" counts. If the human ends the conversation without confirming, you have produced zero files, and that is correct.
+
+## The loop
+
+1. **Scope check.** Refuse "brainstorm the whole app" — pick one feature area. If `$ARGUMENTS` is empty, ask what they want to brainstorm.
+2. **Ground in code.** Call `mcp__specship__specship_explore` (and `specship_search`) on terms from `$ARGUMENTS` to find where similar features live, conventions to mirror, and which files the work will likely touch. Summarize what you found.
+3. **Approaches.** Propose **2–3 distinct approaches** with trade-offs, and lead with your recommendation and why.
+4. **Clarify.** Ask the human **one question at a time** about the things the graph can't tell you — UX, edge cases, acceptance criteria, non-goals. Don't dump a list.
+5. **Iterate** 3–4 until the human is satisfied with a direction. Then ask: *"Want me to write this up as a brief and hand it to /ss-spec-author?"* — and WAIT for an explicit yes.
+
+## On explicit confirmation (and only then)
+
+1. Derive a kebab-case `<slug>` from the feature.
+2. Write the brief to **`specs/<slug>/brief.md`** using the format below. Leave the `spec:` field **unset** for now.
+3. Hand off: invoke **`/ss-spec-author`** with the brief — pass the brief's path so spec-author reads it and does NOT re-ground in code (the brief already has the grounding). spec-author assigns the real spec **ID** and writes `specs/<ID>.md`.
+4. Once spec-author has written the spec: set the brief's `spec:` field to the new ID, and add a **`brief:`** field to the spec's frontmatter holding the path to the brief **relative to the spec file's own directory**. For the usual flat layout (`specs/<ID>.md`) that is exactly `brief: <slug>/brief.md`; if spec-author ever nests the spec (e.g. `specs/<area>/<ID>.md`), write the correct relative path instead (e.g. `../<slug>/brief.md`) so the dashboard can resolve it. This links the two both ways.
+5. If spec-author fails, STOP and tell the human: the brief exists with `spec:` unset; retry is re-running `/ss-spec-author` with the same brief path. Do not hand-write a spec.
+6. Point them at `/ss-spec-review <ID>` then `/ss-implement <ID>`.
+
+## Brief format (`specs/<slug>/brief.md`)
+
+```markdown
+---
+slug: <slug>
+spec:            # set to the REQ-… id after /ss-spec-author writes the spec
+created: <date>
+---
+
+# Brainstorm: <feature>
+
+## Problem
+<what we're solving and why>
+
+## Code grounding
+<relevant files / symbols / conventions found via specship_explore>
+
+## Approaches considered
+1. <A> — <trade-offs>
+2. <B> — <trade-offs>
+**Chosen: <X>** — <rationale>
+
+## Key decisions
+<the calls made during the loop>
+
+## Edge cases & non-goals
+<…>
+
+## Acceptance criteria
+<…>
+```
+
+## Anti-patterns
+- **Writing before confirmation.** The single most important rule — see above.
+- **Re-interviewing about taste / proposing your own variants without grounding.** Ground first, then propose.
+- **Duplicating spec-author.** You decide; spec-author formats. Don't write the formal `specs/<ID>.md` yourself.
+- **Treating a question as confirmation.** Only an explicit yes writes files.

package/dist/analytics/specship-impact.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Pure classifiers and symbol-extraction helpers for SpecShip Token Impact.
+ *
+ * No I/O, no DB, no imports beyond types. Intended to be imported by the
+ * ingestor (Task 4) and the aggregation endpoint (later tasks).
+ */
+/**
+ * Returns true iff `name` is routed through the SpecShip MCP server
+ * (i.e. starts with `mcp__specship__`).
+ */
+export declare function isSpecshipTool(name: string): boolean;
+/**
+ * Returns true iff the tool returns code-graph source that can displace a
+ * native Read/Grep. See SOURCE_RETURNING_TOOLS for the authoritative set.
+ */
+export declare function isSourceReturningTool(name: string): boolean;
+/**
+ * Extracts the symbol names a tool call was asking about from its serialised
+ * input JSON. Returns `[]` when no symbols are resolvable.
+ *
+ * Heuristic for `specship_explore` and `specship_search` (which both accept a
+ * free-form `query` string):
+ *   - Tokenise on whitespace.
+ *   - If ALL tokens match SYMBOL_TOKEN_RE AND there are ≤ MAX_SYMBOL_BAG_TOKENS
+ *     tokens, treat as a symbol bag and return the token list.
+ *   - Otherwise (natural-language prose detected) return [].
+ *
+ * Input keys verified against src/mcp/tools.ts:
+ *   - specship_node / callers / callees / impact → `symbol` (string, required)
+ *   - specship_explore                           → `query`  (string, required)
+ *   - specship_search                            → `query`  (string, required)
+ *   - specship_files / others                   → [] (no named-symbol input)
+ */
+export declare function extractRequestedSymbols(toolName: string, inputJson: string | null | undefined): string[];
+/**
+ * Minimal interface for the graph-backed read-equivalent estimator.
+ * Keeps the ingestor and tests decoupled from the full SpecShip class.
+ */
+export interface GraphLike {
+    estimateReadEquivalent(symbols: string[]): {
+        files: {
+            path: string;
+            size: number;
+        }[];
+        resolved: boolean;
+    };
+}
+/**
+ * Classify one tool call and compute the three ingest columns:
+ *   - `isSpecship`     — 1 if this is any `mcp__specship__*` call, else 0.
+ *   - `resolution`     — 'resolved' | 'unresolved' | 'n/a' | null.
+ *   - `displacedFiles` — JSON string `[[path,size],…]` or null.
+ *
+ * Logic:
+ *   1. Not a specship tool → { isSpecship:0, resolution:null, displacedFiles:null }.
+ *   2. Specship + source-returning + result has content:
+ *      a. No symbols extractable → unresolved / null.
+ *      b. No graph available    → unresolved / null.
+ *      c. graph.estimateReadEquivalent returns resolved=true → resolved + files JSON.
+ *      d. resolved=false        → unresolved / null.
+ *   3. Specship but not a source-returning call, or zero-length result → n/a / null.
+ */
+export declare function classifyToolCall(call: {
+    toolName: string;
+    inputJson: string | null | undefined;
+    resultLength: number;
+}, graph: GraphLike | null): {
+    isSpecship: 0 | 1;
+    resolution: 'resolved' | 'unresolved' | 'n/a' | null;
+    displacedFiles: string | null;
+};
+//# sourceMappingURL=specship-impact.d.ts.map

package/dist/analytics/specship-impact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"specship-impact.d.ts","sourceRoot":"","sources":["../../src/analytics/specship-impact.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAsEH;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAI3D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACnC,MAAM,EAAE,CA+BV;AAMD;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG;QACzC,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QACxC,QAAQ,EAAE,OAAO,CAAC;KACnB,CAAC;CACH;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,EACtF,KAAK,EAAE,SAAS,GAAG,IAAI,GACtB;IAAE,UAAU,EAAE,CAAC,GAAG,CAAC,CAAC;IAAC,UAAU,EAAE,UAAU,GAAG,YAAY,GAAG,KAAK,GAAG,IAAI,CAAC;IAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CA0C5G"}

package/dist/analytics/specship-impact.js

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * Pure classifiers and symbol-extraction helpers for SpecShip Token Impact.
+ *
+ * No I/O, no DB, no imports beyond types. Intended to be imported by the
+ * ingestor (Task 4) and the aggregation endpoint (later tasks).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSpecshipTool = isSpecshipTool;
+exports.isSourceReturningTool = isSourceReturningTool;
+exports.extractRequestedSymbols = extractRequestedSymbols;
+exports.classifyToolCall = classifyToolCall;
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Prefix shared by every MCP tool routed through the specship server. */
+const MCP_SPECSHIP_PREFIX = 'mcp__specship__';
+/**
+ * Strip-prefix base names of SpecShip tools that return code-graph source.
+ * These are the tools a SpecShip call can displace a native Read/Grep with.
+ * Excluded: designer_*, specship_link_assert, specship_link_verify,
+ * specship_spec, specship_drifted, specship_status — they don't return
+ * indexed source symbols.
+ */
+const SOURCE_RETURNING_TOOLS = new Set([
+    'specship_explore',
+    'specship_node',
+    'specship_callers',
+    'specship_callees',
+    'specship_impact',
+    'specship_search',
+    'specship_files',
+]);
+/**
+ * Tools whose input carries a `symbol` key (single identifier string).
+ * Verified against src/mcp/tools.ts inputSchema `required: ['symbol']`.
+ */
+const SYMBOL_KEY_TOOLS = new Set([
+    'specship_node',
+    'specship_callers',
+    'specship_callees',
+    'specship_impact',
+]);
+/**
+ * Regex for a single valid identifier token (with optional Class.method
+ * qualifier). A token matches if every character is a JS/TS identifier char
+ * or a single interior dot separating two identifier segments.
+ *
+ * Class.method tokens are kept whole — downstream resolution will try the
+ * qualified name, which biases an overloaded name to the named type's own
+ * definition (e.g. `DataRequest.task` → DataRequest's `task`, not the
+ * abstract base).
+ */
+const SYMBOL_TOKEN_RE = /^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)?$/;
+/**
+ * Regex that a token must match to be considered "code-ish" rather than
+ * natural-language prose. Pure lowercase ASCII words (e.g. "find", "the",
+ * "all") look like prose; real symbol names almost always contain at least
+ * one of: uppercase letter, underscore, dollar sign, digit, or a dot
+ * (qualifying separator). A token matches this regex if it has any of those
+ * signals.
+ *
+ * Examples that pass:  AuthService  handleRequest  _private  $el  renderV2  UserService.login
+ * Examples that fail:  find  all  the  auth  handlers  does  updating
+ */
+const CODE_SIGNAL_RE = /[A-Z_$\d.]/;
+/** Cap on how many symbol-shaped tokens we pull from one query (bounds the
+ *  downstream graph lookups; queries naming more than this are rare). */
+const MAX_SYMBOLS_PER_QUERY = 16;
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Returns true iff `name` is routed through the SpecShip MCP server
+ * (i.e. starts with `mcp__specship__`).
+ */
+function isSpecshipTool(name) {
+    return name.startsWith(MCP_SPECSHIP_PREFIX);
+}
+/**
+ * Returns true iff the tool returns code-graph source that can displace a
+ * native Read/Grep. See SOURCE_RETURNING_TOOLS for the authoritative set.
+ */
+function isSourceReturningTool(name) {
+    if (!name.startsWith(MCP_SPECSHIP_PREFIX))
+        return false;
+    const base = name.slice(MCP_SPECSHIP_PREFIX.length);
+    return SOURCE_RETURNING_TOOLS.has(base);
+}
+/**
+ * Extracts the symbol names a tool call was asking about from its serialised
+ * input JSON. Returns `[]` when no symbols are resolvable.
+ *
+ * Heuristic for `specship_explore` and `specship_search` (which both accept a
+ * free-form `query` string):
+ *   - Tokenise on whitespace.
+ *   - If ALL tokens match SYMBOL_TOKEN_RE AND there are ≤ MAX_SYMBOL_BAG_TOKENS
+ *     tokens, treat as a symbol bag and return the token list.
+ *   - Otherwise (natural-language prose detected) return [].
+ *
+ * Input keys verified against src/mcp/tools.ts:
+ *   - specship_node / callers / callees / impact → `symbol` (string, required)
+ *   - specship_explore                           → `query`  (string, required)
+ *   - specship_search                            → `query`  (string, required)
+ *   - specship_files / others                   → [] (no named-symbol input)
+ */
+function extractRequestedSymbols(toolName, inputJson) {
+    if (!inputJson)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(inputJson);
+    }
+    catch {
+        return [];
+    }
+    if (parsed === null || typeof parsed !== 'object')
+        return [];
+    const args = parsed;
+    if (!toolName.startsWith(MCP_SPECSHIP_PREFIX))
+        return [];
+    const base = toolName.slice(MCP_SPECSHIP_PREFIX.length);
+    // --- symbol-keyed tools (specship_node, callers, callees, impact) ---------
+    if (SYMBOL_KEY_TOOLS.has(base)) {
+        const sym = args['symbol'];
+        return typeof sym === 'string' && sym.length > 0 ? [sym] : [];
+    }
+    // --- query-keyed tools (specship_explore, specship_search) ----------------
+    if (base === 'specship_explore' || base === 'specship_search') {
+        const q = args['query'];
+        if (typeof q !== 'string' || q.length === 0)
+            return [];
+        return symbolBagFromQuery(q);
+    }
+    // --- all other specship tools (files, status, spec, drifted, designer_*…) -
+    return [];
+}
+/**
+ * Classify one tool call and compute the three ingest columns:
+ *   - `isSpecship`     — 1 if this is any `mcp__specship__*` call, else 0.
+ *   - `resolution`     — 'resolved' | 'unresolved' | 'n/a' | null.
+ *   - `displacedFiles` — JSON string `[[path,size],…]` or null.
+ *
+ * Logic:
+ *   1. Not a specship tool → { isSpecship:0, resolution:null, displacedFiles:null }.
+ *   2. Specship + source-returning + result has content:
+ *      a. No symbols extractable → unresolved / null.
+ *      b. No graph available    → unresolved / null.
+ *      c. graph.estimateReadEquivalent returns resolved=true → resolved + files JSON.
+ *      d. resolved=false        → unresolved / null.
+ *   3. Specship but not a source-returning call, or zero-length result → n/a / null.
+ */
+function classifyToolCall(call, graph) {
+    const { toolName, inputJson, resultLength } = call;
+    if (!isSpecshipTool(toolName)) {
+        return { isSpecship: 0, resolution: null, displacedFiles: null };
+    }
+    // It's a specship tool. Check if it returns source AND returned something.
+    if (isSourceReturningTool(toolName) && resultLength > 0) {
+        const symbols = extractRequestedSymbols(toolName, inputJson);
+        if (symbols.length === 0) {
+            return { isSpecship: 1, resolution: 'unresolved', displacedFiles: null };
+        }
+        if (graph === null) {
+            return { isSpecship: 1, resolution: 'unresolved', displacedFiles: null };
+        }
+        // A locked/corrupt index can make estimateReadEquivalent throw. The estimate
+        // is best-effort decoration on the tool call — it must NEVER break core
+        // transcript ingest. Degrade to 'unresolved' on any failure.
+        let files;
+        let resolved;
+        try {
+            ({ files, resolved } = graph.estimateReadEquivalent(symbols));
+        }
+        catch {
+            return { isSpecship: 1, resolution: 'unresolved', displacedFiles: null };
+        }
+        if (resolved) {
+            return {
+                isSpecship: 1,
+                resolution: 'resolved',
+                displacedFiles: JSON.stringify(files.map((f) => [f.path, f.size])),
+            };
+        }
+        else {
+            return { isSpecship: 1, resolution: 'unresolved', displacedFiles: null };
+        }
+    }
+    // Specship tool but not source-returning, or returned nothing (designer/spec/mutating tools).
+    return { isSpecship: 1, resolution: 'n/a', displacedFiles: null };
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Pull the symbol-shaped tokens out of a free-form `query`.
+ *
+ * Real `explore`/`search` queries are MIXED bags — symbol names interleaved
+ * with lowercase keywords ("live", "save", "install", "the") and often 10+
+ * tokens long. So we FILTER (not all-or-nothing): keep each token that matches
+ * SYMBOL_TOKEN_RE (a valid identifier or `Class.method`) AND CODE_SIGNAL_RE
+ * (has an uppercase letter, underscore, dollar, digit, or dot — i.e. looks like
+ * code, not a plain lowercase word). Drop the rest.
+ *
+ * A pure natural-language question ("how does the user log in") has no code-ish
+ * tokens, so it yields [] — still correctly treated as "no symbols". Capped at
+ * MAX_SYMBOLS_PER_QUERY to bound the downstream graph lookups.
+ */
+function symbolBagFromQuery(query) {
+    const symbols = query
+        .trim()
+        .split(/\s+/)
+        .filter((t) => SYMBOL_TOKEN_RE.test(t) && CODE_SIGNAL_RE.test(t));
+    return symbols.slice(0, MAX_SYMBOLS_PER_QUERY);
+}
+//# sourceMappingURL=specship-impact.js.map

package/dist/analytics/specship-impact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specship-impact.js","sourceRoot":"","sources":["../../src/analytics/specship-impact.ts"],"names":[],"mappings":"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"}

package/dist/bin/specship.js

@@ -1676,8 +1676,8 @@ function main() {
     program
         .command('install')
         .description('Install specship MCP server into Claude Code')
-        .option('-l, --location <where>', 'Install location: "global" or "local". Default: prompt')
-        .option('-y, --yes', 'Non-interactive: defaults to --location=global, auto-allow on')
+        .option('-l, --location <where>', 'Install location: "global" or "local". Default: prompt (local)')
+        .option('-y, --yes', 'Non-interactive: defaults to --location=local, auto-allow on')
         .option('--no-permissions', 'Skip writing the auto-allow permissions list')
         .option('--no-sdd', 'Skip the spec-driven-development steering (CLAUDE.md rule + spec-author nudge hook)')
         .option('--print-config', 'Print MCP config snippet for Claude Code and exit (no file writes)')
@@ -1787,8 +1787,8 @@ function main() {
     program
         .command('uninstall')
         .description('Remove specship from Claude Code')
-        .option('-l, --location <where>', 'Uninstall location: "global" or "local". Default: prompt')
-        .option('-y, --yes', 'Non-interactive: defaults to --location=global')
+        .option('-l, --location <where>', 'Uninstall location: "global" or "local". Default: prompt (local)')
+        .option('-y, --yes', 'Non-interactive: defaults to --location=local')
         // vestigial — kept so existing `--target claude` invocations keep working.
         .option('-t, --target <ids>', '(vestigial) accepted: "claude" | "auto" | "all" | "none"')
         .action(async (opts) => {
@@ -1861,6 +1861,179 @@ function main() {
             cg.close();
         }
     });
+    // @implements REQ-FUNNEL-004
+    program
+        .command('spec [id]')
+        .description('Spec lifecycle funnel (idea → spec → implemented). With an id, show that spec/brief detail.')
+        .option('--json', 'emit JSON')
+        .action(async (id, options) => {
+        const projectRoot = path.resolve(process.cwd());
+        if (!(0, directory_1.isInitialized)(projectRoot)) {
+            error(`SpecShip not initialized in ${projectRoot}. Run \`specship init -i\` first.`);
+            process.exit(1);
+        }
+        const { default: SpecShip } = await loadSpecShip();
+        const { summarizeBriefFunnel, resolveBriefLink, findBriefsForSpec } = await Promise.resolve().then(() => __importStar(require('../resolution/brief-link-resolver')));
+        const cg = await SpecShip.open(projectRoot);
+        try {
+            const sq = cg.getSpecQueries();
+            // Implementation rollup for a document's requirements.
+            const docRollup = (docId) => {
+                const reqs = sq.getSpecsByParent(docId).filter((s) => s.kind === 'requirement');
+                const r = { requirements: reqs.length, implemented: 0, verified: 0, drifted: 0, broken: 0, orphaned: 0 };
+                for (const req of reqs) {
+                    for (const lk of sq.getLinksBySpec(req.id)) {
+                        if (lk.state === 'implemented')
+                            r.implemented++;
+                        else if (lk.state === 'verified')
+                            r.verified++;
+                        else if (lk.state === 'drifted')
+                            r.drifted++;
+                        else if (lk.state === 'broken')
+                            r.broken++;
+                        else if (lk.state === 'orphaned')
+                            r.orphaned++;
+                    }
+                }
+                return r;
+            };
+            const degraded = (r) => r.drifted + r.broken + r.orphaned;
+            // ---- Detail view (an id was given) ----
+            if (id) {
+                const spec = sq.getSpecById(id);
+                if (!spec) {
+                    if (options.json) {
+                        // eslint-disable-next-line no-console
+                        console.log(JSON.stringify({ error: 'not_found', id }, null, 2));
+                    }
+                    else {
+                        error(`No spec or brief with id "${id}".`);
+                    }
+                    process.exit(1);
+                }
+                if (spec.kind === 'brief') {
+                    const entry = summarizeBriefFunnel(sq, spec);
+                    const link = resolveBriefLink(sq, spec);
+                    if (options.json) {
+                        // eslint-disable-next-line no-console
+                        console.log(JSON.stringify({ ...entry, briefSide: link.briefSide, specSide: link.specSide }, null, 2));
+                    }
+                    else {
+                        /* eslint-disable no-console */
+                        console.log(`${spec.id}  (brief)  ${spec.title}`);
+                        console.log(`  state: ${entry.state}`);
+                        if (entry.state === 'conflict') {
+                            console.log(`  ⚠ conflict: brief → ${link.briefSide}, spec → ${link.specSide} (resolve the mismatched pointer)`);
+                        }
+                        else if (entry.linkedSpecId) {
+                            console.log(`  linked spec: ${entry.linkedSpecId}`);
+                        }
+                        if (entry.rollup) {
+                            const r = entry.rollup;
+                            console.log(`  rollup: ${r.requirements} reqs · ${r.implemented} implemented · ${r.verified} verified · ${degraded(r)} degraded`);
+                        }
+                        /* eslint-enable no-console */
+                    }
+                }
+                else {
+                    const links = sq.getLinksBySpec(spec.id);
+                    const briefs = spec.kind === 'document' ? findBriefsForSpec(sq, spec.id) : [];
+                    if (options.json) {
+                        const detail = { id: spec.id, kind: spec.kind, title: spec.title, links };
+                        if (spec.kind === 'document')
+                            detail.rollup = docRollup(spec.id);
+                        detail.briefs = briefs.map((b) => b.briefId);
+                        // eslint-disable-next-line no-console
+                        console.log(JSON.stringify(detail, null, 2));
+                    }
+                    else {
+                        /* eslint-disable no-console */
+                        console.log(`${spec.id}  (${spec.kind})  ${spec.title}`);
+                        if (spec.kind === 'document') {
+                            const r = docRollup(spec.id);
+                            console.log(`  rollup: ${r.requirements} reqs · ${r.implemented} implemented · ${r.verified} verified · ${degraded(r)} degraded`);
+                            if (briefs.length)
+                                console.log(`  from briefs: ${briefs.map((b) => b.briefId).join(', ')}`);
+                        }
+                        for (const lk of links) {
+                            console.log(`  [${lk.state}] → ${lk.targetFilePath}:${lk.targetQualifiedName}`);
+                        }
+                        /* eslint-enable no-console */
+                    }
+                }
+                return;
+            }
+            // ---- Funnel view (no id) ----
+            const all = sq.getAllSpecs();
+            const briefs = all.filter((s) => s.kind === 'brief');
+            const documents = all.filter((s) => s.kind === 'document');
+            const requirements = all.filter((s) => s.kind === 'requirement');
+            const entries = briefs.map((b) => summarizeBriefFunnel(sq, b));
+            const byState = (st) => entries.filter((e) => e.state === st);
+            const links = sq.getAllLinks();
+            const lc = (st) => links.filter((l) => l.state === st).length;
+            if (all.length === 0) {
+                if (options.json) {
+                    // eslint-disable-next-line no-console
+                    console.log(JSON.stringify({ summary: { ideas: 0, specified: 0, conflicts: 0, documents: 0, requirements: 0 }, specs: [], briefs: [] }, null, 2));
+                }
+                else {
+                    // eslint-disable-next-line no-console
+                    console.log('No specs or briefs found. Author one with /ss-spec-author or /ss-brainstorm.');
+                }
+                return;
+            }
+            if (options.json) {
+                // eslint-disable-next-line no-console
+                console.log(JSON.stringify({
+                    summary: {
+                        ideas: byState('idea').length,
+                        specified: byState('specified').length,
+                        conflicts: byState('conflict').length,
+                        documents: documents.length,
+                        requirements: requirements.length,
+                        links: { implemented: lc('implemented'), verified: lc('verified'), drifted: lc('drifted'), broken: lc('broken'), orphaned: lc('orphaned') },
+                    },
+                    specs: documents.map((d) => ({ id: d.id, title: d.title, rollup: docRollup(d.id) })),
+                    briefs: entries,
+                }, null, 2));
+                return;
+            }
+            /* eslint-disable no-console */
+            console.log('Spec lifecycle funnel');
+            console.log(`  ideas        ${byState('idea').length}`);
+            console.log(`  specified    ${byState('specified').length}`);
+            if (byState('conflict').length)
+                console.log(`  conflicts    ${byState('conflict').length}  ⚠`);
+            console.log(`  documents    ${documents.length}`);
+            console.log(`  requirements ${requirements.length}   (implemented ${lc('implemented')} · verified ${lc('verified')} · degraded ${lc('drifted') + lc('broken') + lc('orphaned')})`);
+            if (documents.length) {
+                console.log('\nDocuments:');
+                for (const d of documents) {
+                    const r = docRollup(d.id);
+                    console.log(`  ${d.id}  —  ${d.title}   [${r.requirements} reqs · ${r.implemented} impl · ${r.verified} ver${degraded(r) ? ` · ${degraded(r)} degraded` : ''}]`);
+                }
+            }
+            const ideas = byState('idea');
+            if (ideas.length) {
+                console.log('\nIdeas (unlinked briefs):');
+                for (const e of ideas) {
+                    const b = sq.getSpecById(e.briefId);
+                    console.log(`  ${e.briefId}  —  ${b?.title ?? ''}`);
+                }
+            }
+            const conflicts = byState('conflict');
+            if (conflicts.length) {
+                console.log('\nConflicts (mismatched brief↔spec pointers):');
+                for (const e of conflicts)
+                    console.log(`  ${e.briefId}  ⚠`);
+            }
+            /* eslint-enable no-console */
+        }
+        finally {
+            cg.close();
+        }
+    });
     program
         .command('workflow <action> [arg]')
         .description('Workflow engine: list | run <name> | resume <runId> | cancel <runId> | approve <runId> | reject <runId> | runs')