@specship/specship 0.11.0

package/dist/activation/starter-prompt.js

@@ -0,0 +1,164 @@
+"use strict";
+/**
+ * First-run starter-prompt generation (ACTIVATION-DOC).
+ *
+ * Manufactures one perceivable retrieval moment: a concrete flow/impact question
+ * naming real symbols from THIS repo, derived from a flow verified to connect in
+ * the graph. A botched first impression is worse than none, so generation never
+ * emits a flow whose endpoints don't connect and never sources a flow from a
+ * god-file's fan-out; when no good flow exists it falls back to an impact
+ * question (which needs only one real symbol and can't fail to connect).
+ *
+ * Graph access is behind `GraphProbe` so the selection policy is unit-testable;
+ * `generateStarterPrompt` wires the real probe over a live `SpecShip` graph.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectStarterPrompt = selectStarterPrompt;
+exports.isNoiseName = isNoiseName;
+exports.isUninterestingFile = isUninterestingFile;
+exports.realProbe = realProbe;
+exports.generateStarterPrompt = generateStarterPrompt;
+/**
+ * Choose the starter prompt. Pure: a flow across ≥2 files over a multi-hop path
+ * wins; otherwise an impact question on the busiest symbol; otherwise null.
+ */
+function selectStarterPrompt(probe) {
+    for (const entry of probe.entryCandidates()) {
+        const flow = probe.traceFlow(entry);
+        if (flow && flow.files.length >= 2 && flow.hops >= 2) {
+            return {
+                kind: 'flow',
+                from: entry.name,
+                to: flow.to,
+                prompt: `How does \`${entry.name}\` reach \`${flow.to}\`?`,
+            };
+        }
+    }
+    const top = probe.topFanInSymbol();
+    if (top) {
+        return { kind: 'impact', from: top.name, prompt: `What breaks if I change \`${top.name}\`?` };
+    }
+    return null;
+}
+/**
+ * Generic names that are usually name-collision artifacts (e.g. a prepared
+ * statement's `all`, an object's `set`) — they make a dumb starter prompt, so
+ * they're never chosen as an endpoint. (Human-facing precision bar.)
+ */
+const NOISE_NAMES = new Set([
+    'all', 'get', 'set', 'now', 'find', 'sort', 'map', 'run', 'init', 'close', 'open',
+    'next', 'then', 'add', 'has', 'key', 'value', 'data', 'result', 'handle', 'exec',
+    'call', 'apply', 'tostring', 'valueof', 'constructor', 'default', 'index', 'main',
+    // Generic accessor/field-ish names that read poorly as a flow endpoint.
+    'code', 'error', 'message', 'name', 'id', 'type', 'kind', 'status', 'body', 'path',
+    'url', 'text', 'log', 'length', 'size', 'count', 'item', 'items', 'args', 'opts',
+    'options', 'params', 'ctx', 'req', 'res', 'err', 'val', 'obj', 'fn', 'cb',
+]);
+/** A short or generic name that would make an unconvincing starter prompt. */
+function isNoiseName(name) {
+    return name.length <= 2 || NOISE_NAMES.has(name.toLowerCase());
+}
+/** Test/fixture/build files — never the source or sink of the manufactured moment. */
+function isUninterestingFile(file) {
+    return (/(^|\/)(__tests__|tests?|spec|fixtures?|examples?|node_modules|dist|build)(\/|$)/i.test(file) ||
+        /\.(test|spec)\.[a-z]+$/i.test(file));
+}
+/** Edge kinds that represent a call-like flow worth tracing. */
+const FLOW_EDGE_KINDS = new Set(['calls', 'references', 'instantiates']);
+/**
+ * Node kinds a flow should *end* on — a meaningful call/instantiation sink, not a
+ * field/property/variable access (which makes a vague "reach `code`" prompt).
+ */
+const SINK_KINDS = new Set(['function', 'method', 'class', 'route']);
+const MAX_HOPS = 6;
+const MAX_NODES_EXPLORED = 4000;
+const MAX_ENTRY_CANDIDATES = 40;
+/** Build a `GraphProbe` over a live SpecShip graph. */
+function realProbe(cg) {
+    const godFiles = new Set(cg.getMaintainability().godFiles.map((g) => g.filePath));
+    // A worthwhile endpoint: not in a god-file, not a test/fixture/build file, and
+    // not a generic noise name.
+    const worthwhile = (n) => !godFiles.has(n.filePath) && !isUninterestingFile(n.filePath) && !isNoiseName(n.name);
+    const fanIn = (id) => cg.getIncomingEdges(id).length;
+    return {
+        entryCandidates() {
+            // Routes keep their `GET /path` names (not noise), but still skip fixtures.
+            const routes = cg.getNodesByKind('route').filter((n) => !godFiles.has(n.filePath) && !isUninterestingFile(n.filePath));
+            const fns = [...cg.getNodesByKind('function'), ...cg.getNodesByKind('method')]
+                .filter(worthwhile)
+                .sort((a, b) => fanIn(b.id) - fanIn(a.id));
+            return [...routes, ...fns]
+                .slice(0, MAX_ENTRY_CANDIDATES)
+                .map((n) => ({ name: n.name, file: n.filePath, id: n.id }));
+        },
+        traceFlow(entry) {
+            const start = cg.getNodesByName(entry.name).find((n) => n.filePath === entry.file);
+            if (!start)
+                return null;
+            const visited = new Set([start.id]);
+            let explored = 0;
+            let best = null;
+            let bestScore = -1;
+            // Prefer a richer flow: a synthesized (dynamic-dispatch) hop dominates,
+            // then more hops, then more files — a deeper path shows off more of the
+            // system than the first shallow utility call near the handler.
+            const score = (synth, hops, files) => (synth ? 1000 : 0) + hops * 10 + files;
+            let frontier = [
+                { id: start.id, depth: 0, files: new Set([start.filePath]), synthesized: false },
+            ];
+            while (frontier.length && explored < MAX_NODES_EXPLORED) {
+                const next = [];
+                for (const cur of frontier) {
+                    if (cur.depth >= MAX_HOPS)
+                        continue;
+                    for (const edge of cg.getOutgoingEdges(cur.id)) {
+                        if (!FLOW_EDGE_KINDS.has(edge.kind))
+                            continue;
+                        if (visited.has(edge.target))
+                            continue;
+                        visited.add(edge.target);
+                        explored++;
+                        const target = cg.getNode(edge.target);
+                        if (!target)
+                            continue;
+                        const files = new Set(cur.files);
+                        files.add(target.filePath);
+                        const synthesized = cur.synthesized || edge.provenance === 'heuristic';
+                        const depth = cur.depth + 1;
+                        // Only end on a worthwhile, callable leaf (not noise / test /
+                        // god-file, and a function/method/class — not a field access) so the
+                        // prompt names a meaningful sink.
+                        if (files.size >= 2 && depth >= 2 && SINK_KINDS.has(target.kind) && worthwhile(target)) {
+                            const s = score(synthesized, depth, files.size);
+                            if (s > bestScore) {
+                                bestScore = s;
+                                best = { to: target.name, hops: depth, files: [...files], synthesized };
+                            }
+                        }
+                        next.push({ id: target.id, depth, files, synthesized });
+                    }
+                }
+                frontier = next;
+            }
+            return best;
+        },
+        topFanInSymbol() {
+            const candidates = [...cg.getNodesByKind('function'), ...cg.getNodesByKind('method')].filter(worthwhile);
+            let best = null;
+            let bestFanIn = 0;
+            for (const n of candidates) {
+                const f = fanIn(n.id);
+                if (f > bestFanIn) {
+                    bestFanIn = f;
+                    best = n;
+                }
+            }
+            return best ? { name: best.name, file: best.filePath } : null;
+        },
+    };
+}
+/** Generate the starter prompt for a live project, or null if none fits. */
+function generateStarterPrompt(cg) {
+    return selectStarterPrompt(realProbe(cg));
+}
+//# sourceMappingURL=starter-prompt.js.map

package/dist/activation/starter-prompt.js.map

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

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/behaviour/behaviour-surface.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Behaviour surface (REQ-BEHAVIOUR-001).
+ *
+ * Given a requirement, surface the code it links to PLUS the routes /
+ * components / handlers around it, partitioned into a UI tier and a
+ * backend/batch tier — the precise flow map the `/ss-behaviour` skill turns into
+ * end-to-end tests, without having to re-explore the codebase.
+ *
+ * `computeBehaviourSurface` is a pure function over a `deps` snapshot so it is
+ * testable without a database; `SpecShip.getBehaviourSurface()` assembles the
+ * snapshot (requirement + acceptance children → their linked nodes → the
+ * 1-hop caller/callee neighbourhood) and calls it.
+ *
+ * Tier classification is structural: the graph carries no framework marker on a
+ * node, so UI is inferred from `kind === 'component'` or a front-end file
+ * extension; everything else flow-relevant (routes, handlers) is backend/batch.
+ */
+import { Node, NodeKind } from '../types';
+export interface BehaviourFlowElement {
+    /** Qualified name (falls back to the simple name). */
+    name: string;
+    kind: NodeKind;
+    filePath: string;
+    startLine: number;
+    /** True when the requirement links to this node directly (vs a neighbour). */
+    linkedDirectly: boolean;
+}
+export interface BehaviourSurface {
+    requirementId: string;
+    /** False when the requirement id resolves to no spec (REQ-BEHAVIOUR-001.A4). */
+    found: boolean;
+    /** UI flows — Playwright targets. Empty when the project has no UI (A3). */
+    ui: BehaviourFlowElement[];
+    /** Backend / batch flows — API / job test targets. */
+    backend: BehaviourFlowElement[];
+}
+export interface BehaviourSurfaceDeps {
+    requirementId: string;
+    /** Null when the requirement id resolved to no spec. */
+    requirementExists: boolean;
+    /** Resolved nodes the requirement (or its acceptance children) links to. */
+    linkedNodes: Node[];
+    /** 1-hop caller/callee neighbours of the linked nodes. */
+    neighbourNodes: Node[];
+}
+/** A node is UI when it's a component or lives in a front-end file. */
+export declare function isUiNode(node: Node): boolean;
+/**
+ * Build the behaviour surface for a requirement (REQ-BEHAVIOUR-001). Linked
+ * nodes are always included (the implementation); neighbours are included only
+ * when flow-relevant (routes / components / handlers — A1). Each element carries
+ * its symbol, kind, and file location (A2). A requirement that resolves to no
+ * spec returns `found: false` (A4); a project with no UI yields an empty `ui`
+ * tier rather than an error (A3).
+ */
+export declare function computeBehaviourSurface(deps: BehaviourSurfaceDeps): BehaviourSurface;
+/** Render a behaviour surface as markdown for the `specship_spec` response. */
+export declare function renderBehaviourSurface(surface: BehaviourSurface): string;
+//# sourceMappingURL=behaviour-surface.d.ts.map

package/dist/behaviour/behaviour-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"behaviour-surface.d.ts","sourceRoot":"","sources":["../../src/behaviour/behaviour-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAa1C,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,KAAK,EAAE,OAAO,CAAC;IACf,4EAA4E;IAC5E,EAAE,EAAE,oBAAoB,EAAE,CAAC;IAC3B,sDAAsD;IACtD,OAAO,EAAE,oBAAoB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,iBAAiB,EAAE,OAAO,CAAC;IAC3B,4EAA4E;IAC5E,WAAW,EAAE,IAAI,EAAE,CAAC;IACpB,0DAA0D;IAC1D,cAAc,EAAE,IAAI,EAAE,CAAC;CACxB;AAED,uEAAuE;AACvE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAE5C;AAYD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,oBAAoB,GAAG,gBAAgB,CAgCpF;AAED,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CA+BxE"}

package/dist/behaviour/behaviour-surface.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Behaviour surface (REQ-BEHAVIOUR-001).
+ *
+ * Given a requirement, surface the code it links to PLUS the routes /
+ * components / handlers around it, partitioned into a UI tier and a
+ * backend/batch tier — the precise flow map the `/ss-behaviour` skill turns into
+ * end-to-end tests, without having to re-explore the codebase.
+ *
+ * `computeBehaviourSurface` is a pure function over a `deps` snapshot so it is
+ * testable without a database; `SpecShip.getBehaviourSurface()` assembles the
+ * snapshot (requirement + acceptance children → their linked nodes → the
+ * 1-hop caller/callee neighbourhood) and calls it.
+ *
+ * Tier classification is structural: the graph carries no framework marker on a
+ * node, so UI is inferred from `kind === 'component'` or a front-end file
+ * extension; everything else flow-relevant (routes, handlers) is backend/batch.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isUiNode = isUiNode;
+exports.computeBehaviourSurface = computeBehaviourSurface;
+exports.renderBehaviourSurface = renderBehaviourSurface;
+/** Node kinds that are flow-relevant for a behaviour test (others are noise). */
+const FLOW_KINDS = new Set([
+    'component',
+    'route',
+    'function',
+    'method',
+]);
+/** File extensions that are unambiguously front-end / UI. */
+const UI_FILE = /\.(tsx|jsx|vue|svelte|astro)$/i;
+/** A node is UI when it's a component or lives in a front-end file. */
+function isUiNode(node) {
+    return node.kind === 'component' || UI_FILE.test(node.filePath);
+}
+function toElement(node, linkedDirectly) {
+    return {
+        name: node.qualifiedName || node.name,
+        kind: node.kind,
+        filePath: node.filePath,
+        startLine: node.startLine,
+        linkedDirectly,
+    };
+}
+/**
+ * Build the behaviour surface for a requirement (REQ-BEHAVIOUR-001). Linked
+ * nodes are always included (the implementation); neighbours are included only
+ * when flow-relevant (routes / components / handlers — A1). Each element carries
+ * its symbol, kind, and file location (A2). A requirement that resolves to no
+ * spec returns `found: false` (A4); a project with no UI yields an empty `ui`
+ * tier rather than an error (A3).
+ */
+function computeBehaviourSurface(deps) {
+    if (!deps.requirementExists) {
+        return { requirementId: deps.requirementId, found: false, ui: [], backend: [] };
+    }
+    const seen = new Set();
+    const ui = [];
+    const backend = [];
+    const place = (node, linkedDirectly) => {
+        if (seen.has(node.id))
+            return;
+        seen.add(node.id);
+        const el = toElement(node, linkedDirectly);
+        (isUiNode(node) ? ui : backend).push(el);
+    };
+    // Linked nodes first (the implementation) — always included regardless of kind.
+    for (const node of deps.linkedNodes)
+        place(node, true);
+    // Neighbours — only the flow-relevant kinds, and only if not already linked.
+    for (const node of deps.neighbourNodes) {
+        if (FLOW_KINDS.has(node.kind))
+            place(node, false);
+    }
+    // Directly-linked elements sort ahead of neighbours, then by file.
+    const order = (a, b) => Number(b.linkedDirectly) - Number(a.linkedDirectly) ||
+        a.filePath.localeCompare(b.filePath) ||
+        a.startLine - b.startLine;
+    ui.sort(order);
+    backend.sort(order);
+    return { requirementId: deps.requirementId, found: true, ui, backend };
+}
+/** Render a behaviour surface as markdown for the `specship_spec` response. */
+function renderBehaviourSurface(surface) {
+    if (!surface.found) {
+        return `# Behaviour surface — ${surface.requirementId}\n\n_Requirement "${surface.requirementId}" not found. Use specship_spec (query mode) or specship_drifted to discover requirements._`;
+    }
+    const lines = [];
+    lines.push(`# Behaviour surface — ${surface.requirementId}`);
+    lines.push('');
+    lines.push('The routes / components / handlers around this requirement, grouped by tier. ' +
+        'Author a Playwright test per UI flow and an API/batch test per backend flow, ' +
+        'one per acceptance criterion.');
+    lines.push('');
+    const section = (title, els, emptyNote) => {
+        lines.push(`## ${title}`);
+        if (els.length === 0) {
+            lines.push(`_${emptyNote}_`);
+        }
+        else {
+            for (const e of els) {
+                const tag = e.linkedDirectly ? 'linked' : 'nearby';
+                lines.push(`- [${e.kind}] \`${e.name}\` — ${e.filePath}:${e.startLine} (${tag})`);
+            }
+        }
+        lines.push('');
+    };
+    section('UI tier (Playwright)', surface.ui, 'No UI surface — author backend/batch tests only.');
+    section('Backend / batch tier', surface.backend, 'No backend surface found.');
+    return lines.join('\n').trimEnd();
+}
+//# sourceMappingURL=behaviour-surface.js.map