@selvakumaresra/specship 0.3.0 → 0.5.0

package/README.md

@@ -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. |
 

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/commands/ss-design-implement.md

@@ -6,6 +6,11 @@ allowed-tools: Read, Write, Edit, Bash, mcp__specship__specship_explore, mcp__sp
 
 # SpecShip Design → Spec → Implement: `$ARGUMENTS`
 
+> **Already settled on a design?** This command imports it by URL. If you instead want to *run
+> the taste loop first* — iterate variants with the human via the `designer` MCP and only then
+> spec the chosen one — use **`/ss-design-loop`**, which drives the loop and hands the resulting
+> bundle to this same workflow via its `HANDOFF_DIR` input.
+
 Run the bundled `claude-design-implement` workflow against the Claude Design URL in `$ARGUMENTS`. The workflow:
 
 1. **Snapshots** the design source byte-for-byte into `specs/<slug>/snapshot.html` (zero-loss fidelity layer).

package/commands/ss-design-loop.md

@@ -0,0 +1,125 @@
+---
+description: Run the full design→code loop — taste a claude.ai/design with the human via the designer MCP, then snapshot → spec → review → hand off to /ss-implement. Two human gates.
+argument-hint: [intent — what you want to design]
+allowed-tools: Read, Write, Edit, Bash, mcp__specship__designer_session, mcp__specship__designer_prompt, mcp__specship__designer_ask, mcp__specship__designer_list, mcp__specship__designer_snapshot, mcp__specship__designer_handoff, mcp__specship__specship_explore, mcp__specship__specship_search, mcp__specship__specship_node, mcp__specship__specship_spec, mcp__specship__specship_files
+---
+
+# SpecShip Design Loop: `$ARGUMENTS`
+
+One continuous pipeline: **intent → taste → design → handoff → spec → `/ss-implement`**.
+You (the orchestrator) drive `claude.ai/design` through the `designer` MCP while the
+**human tastes** the variants, then promote the chosen design into a SpecShip spec via the
+bundled `claude-design-implement` workflow. Two human gates:
+
+- **Gate 1 (aesthetic):** the human says *"that's it"* in the taste loop. Driven here, conversationally.
+- **Gate 2 (contract):** the human walks the spec's `[needs review]` markers at the workflow's approval gate.
+
+This is the deeper companion to `/ss-design-implement` — that command imports a design you've
+*already* settled on (by URL); this one runs the taste loop first, then hands the resulting
+bundle to the same workflow. `$ARGUMENTS` is the human's opening intent (optional).
+
+## Preflight
+
+1. **Designer runtime ready?** The designer tools are part of SpecShip's MCP now
+   (`mcp__specship__designer_*`), so they're always present. Probe the *runtime* with
+   `designer_session({ action: "status" })`: a clean status means you're ready. If it errors
+   with "CDP not up" or "Not signed in", the one-time Chrome setup hasn't run — tell the human to
+   run `designer setup` (creates the debug-Chrome profile + login) and stop. Do NOT fall back to a
+   blind fetch; the taste loop needs the live browser.
+2. **SpecShip initialized?** `specship status` should succeed. If not, `specship init -i` first.
+
+## Phase A — Taste loop (Gate 1)
+
+Follow the **`designer-loop` skill** (`~/.claude/skills/designer-loop/SKILL.md`) — it is the
+authority on this loop. The condensed version, if the skill isn't installed:
+
+> The human is the designer; Claude Design has taste; you are translation + plumbing. Don't
+> propose your own variants, don't interview about aesthetics — scope questions only.
+
+1. **Read the room — capabilities drive the design.** Before relaying any intent, survey the
+   target repo for what it actually *does* and feed that into the prompt verbatim. Use
+   `specship_explore` / `specship_search` to pull: entities + their fields, operations /
+   endpoints, states (loading / empty / error / success), failure modes, hard constraints
+   (auth, rate limits), and existing design tokens. The human's intent tells Claude *how*; the
+   codebase tells it *what*. Transfer capability facts unabridged — summarizing is filtering.
+2. **Create / resume the session.** `designer_session({ key: "<slug>", action: "create",
+   name: "<seed intent>", fidelity: "highfi" })`. Reuse a stable `key` derived from the intent
+   so parallel loops don't collide.
+3. **Relay a minimal, faithful prompt.** `designer_prompt({ key, prompt })` — intent +
+   capability facts; let Claude's taste make the aesthetic calls. Ask for the variant shape you
+   want ("3 full-page files", "states as toggles") and lock any hard brand tokens explicitly.
+4. **Hand the human the URL** returned in `url`. That live surface has working tweak sliders and
+   the variant switcher — it is the default taste path. Ask *"what do you think?"*, not
+   "accept or reject?".
+5. **Interpret + iterate.** Translate each reaction into the next `designer_prompt` (or a cheap
+   `designer_ask` to consult Claude on a small adjustment). Repeat 3–4 until the human says
+   **"that's it."** Capture their final reaction verbatim — it goes in the record.
+
+Stay in the loop until Gate 1 is explicitly passed. "Almost" is not "yes."
+
+## Bridge — promote the chosen design
+
+1. `designer_handoff({ key, openFile: "<chosen variant>.html" })`. This fetches the project
+   export zip into `./artifacts/<key>/handoff-<ts>/` — `project/*` (all variants + assets) plus
+   `decision-record.md` (the verbatim transcript + the human's final reaction). Note the
+   **absolute path** of that `handoff-<ts>/` directory and the **chosen variant filename**.
+2. Derive `FILE_LABEL` (human label) and `SLUG` (kebab-case) from the chosen file / intent. If
+   the slug is ambiguous, ask the human — one scope question, not an interview.
+
+## Phase B — Spec pipeline (Gate 2)
+
+Run the bundled workflow against the bundle on disk (no re-fetch, no CDP):
+
+```bash
+specship workflow run claude-design-implement \
+  --input HANDOFF_DIR="<absolute path to handoff-<ts>/>" \
+  --input CHOSEN_FILE="<chosen variant>.html" \
+  --input FILE_LABEL="<File Label>" \
+  --input SLUG="<slug>" \
+  --json
+```
+
+(Add `--input OWNER="<team>"` / `--input PRIORITY="high|medium|low"` to populate frontmatter;
+otherwise they default to empty and surface as `[needs review]`.)
+
+The workflow runs headless to its approval gate, then **pauses** (status `paused`). It:
+snapshots `project/<chosen>.html` byte-for-byte into `specs/<slug>/snapshot.html`, folds
+`decision-record.md` into `specs/<slug>/source.md`, extracts `specs/<slug>/tokens.css`, and
+drafts the spec.
+
+**At the pause (Gate 2):** read the run's approval message / the drafted spec artifact, present
+it to the human, and walk the `[needs review]` markers + gap-fill questions together. Then:
+
+- **Approve:** `specship workflow approve <runId> --comment "<gap-fill answers>"` then
+  `specship workflow resume <runId>`. The answers are captured into the spec.
+- **Needs changes:** collect the feedback and re-run the workflow (a reject cancels the run;
+  existing REQ IDs are preserved across re-imports, so in-flight work survives).
+
+## Phase C — Hand off to implementation
+
+When the workflow completes it prints the bridge message. Relay it to the human:
+- the spec path `specs/<slug>.md` and its REQ IDs,
+- the reference files (`snapshot.html`, `tokens.css`, `source.md`),
+- the exact next step: **`/ss-implement <first REQ ID>`**.
+
+Remind them: the implementer reads `snapshot.html` for visual fidelity — the spec is
+contract-only.
+
+## Anti-patterns
+
+- **Skipping the capability survey.** Designing before reading what the repo *does* produces
+  designs that look good and don't fit. Phase A step 1 is load-bearing.
+- **Proposing your own variants / interviewing about taste.** Claude Design proposes; you relay.
+  Scope questions only.
+- **Auto-promoting.** Don't `designer_handoff` on every iteration — only once Gate 1 passes.
+- **Re-fetching in the workflow.** Always pass `HANDOFF_DIR` (the bundle you just fetched), never
+  `CONNECTOR_URL` — that re-drives Chrome from a headless subprocess and is fragile. The URL path
+  is what `/ss-design-implement` is for.
+- **Putting hex/pixels in the spec.** Reference tokens by name; values live in `tokens.css`.
+- **Skipping Gate 2.** The gap-fill questions are where the static design's blind spots (failure
+  modes, real-time updates, keyboard order) get closed.
+
+If `designer_session` errors with a CDP / sign-in problem, stop and route the human to
+`designer setup` (debug-Chrome profile + login) — this command cannot run the taste loop without
+the live browser. To import a design you've already settled on by URL, use
+`/ss-design-implement <url>` instead.

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,9 +1676,10 @@ 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)')
         // -t/--target is vestigial — kept so existing `--target claude` / `--target auto`
         // invocations (including our own offline-install scripts) keep working.
@@ -1708,10 +1709,14 @@ function main() {
                 : opts.yes
                     ? true
                     : undefined;
+            // Commander's `--no-sdd` makes `opts.sdd === false`; omitting it leaves
+            // it `true`. Spec-driven steering is on by default — forward `false`
+            // only when the user explicitly opted out.
             await runInstallerWithOptions({
                 target: opts.target,
                 location: opts.location,
                 autoAllow,
+                sdd: opts.sdd === false ? false : undefined,
                 yes: opts.yes,
             });
         }
@@ -1720,6 +1725,57 @@ function main() {
             process.exit(1);
         }
     });
+    /**
+     * specship spec-nudge  (internal — installed as a UserPromptSubmit hook)
+     *
+     * Reads the UserPromptSubmit JSON payload from stdin and, when the prompt
+     * looks like feature/bug work, prints a non-blocking reminder (as
+     * `hookSpecificOutput.additionalContext`) to author the spec via spec-author
+     * first. Always exits 0 so the prompt proceeds. Conservative: skips clear
+     * questions / read-only asks so it doesn't nag (SDD-INSTALL-DOC, REQ-SDD-002).
+     */
+    program
+        .command('spec-nudge')
+        .description('Internal hook: nudge toward spec-author on feature/bug intent (UserPromptSubmit)')
+        .action(async () => {
+        const shouldNudge = (prompt) => {
+            const text = (prompt || '').trim();
+            if (text.length < 12)
+                return false;
+            if (/[?]\s*$/.test(text))
+                return false; // a question
+            const lower = text.toLowerCase();
+            // Read-only / interrogative openers — never spec-shaped.
+            if (/^(what|why|how|where|who|when|is|are|does|do|can|could|should|explain|show|list|describe|tell|summar|read|find|search|look|run|why)\b/.test(lower))
+                return false;
+            // Feature / bug-shaped intent verbs.
+            return /\b(add|implement|build|create|introduce|support|enhance|fix|bug|broken|refactor|rewrite|migrate|change|modify|update|wire|integrate|feature|spec out)\b/.test(lower);
+        };
+        const chunks = [];
+        try {
+            for await (const c of process.stdin)
+                chunks.push(c);
+        }
+        catch { /* no stdin — nothing to nudge */ }
+        const raw = Buffer.concat(chunks).toString('utf-8').trim();
+        let prompt = '';
+        if (raw) {
+            try {
+                const parsed = JSON.parse(raw);
+                prompt = typeof parsed?.prompt === 'string' ? parsed.prompt : raw;
+            }
+            catch {
+                prompt = raw; // not JSON — treat as the raw prompt text
+            }
+        }
+        if (shouldNudge(prompt)) {
+            const additionalContext = 'This repo uses spec-driven development (SpecShip). Before any brainstorming or ' +
+                'planning skill, FIRST invoke spec-author to author the spec under specs/ for this ' +
+                'work — the spec is the contract; implement from it with /ss-implement.';
+            process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext } }) + '\n');
+        }
+        process.exit(0);
+    });
     /**
      * specship uninstall
      *
@@ -1731,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) => {
@@ -1891,6 +1947,16 @@ function main() {
                             process.exit(1);
                         }
                     }
+                    // Apply declared defaults for any optional input not passed. This
+                    // makes the schema's `default` field actually take effect and means
+                    // a `$INPUT.X` reference to a declared-but-omitted optional input
+                    // resolves to its default (or "") instead of throwing OutputRefError
+                    // mid-run. Required inputs are already enforced above.
+                    for (const inp of loaded.workflow.inputs ?? []) {
+                        if (!(inp.name in inputs)) {
+                            inputs[inp.name] = inp.default ?? '';
+                        }
+                    }
                     const result = await executor.start(loaded.workflow, {
                         projectRoot,
                         inputs,