feat: code intelligence — code graph, coverage, impact, and spec↔code mapping

[lsmonki]

Summary

Add a specd impact command that, given a spec identifier, file path, or symbol name, computes the full blast radius across both the spec graph and the code graph, and produces an actionable task list for the change.

Today, understanding the impact of any change — to a spec or to code — requires manual cross-referencing: checking which specs depend on which, tracing what code implements a spec, and separately analyzing code-level dependencies. This is slow, error-prone, and the kind of work that should be automated by a spec-driven tool.

Why

• The primary question in spec-driven development is "I'm changing this spec — what breaks?" A spec change can affect dependent specs, the code that implements it, and transitively all code that depends on that code. Today there is no way to answer this question without manual grep and domain knowledge.
• The reverse is equally important: "I'm changing this code — which specs are affected?" A code change may violate constraints from one or more specs, but today there is no formal link between source files and the specs that govern them.
• Reduces risk of incomplete changes. Without unified impact analysis, changes that satisfy the compiler can still silently violate spec constraints, and spec changes can leave implementations out of sync.
• Enables automated task generation. With both graphs connected, specd can generate a concrete, ordered list of changes needed — specs to update, files to modify, tests to add.

Primary use case: spec change impact

specd impact specs/core/snapshot-hasher/spec.md

Expected answer:

1. Dependent specs — which other specs depend on this one (upstream dependsOn traversal)
2. Implementing code — which source files implement this spec (spec→code mapping)
3. Code blast radius — for each implementing file, what other code depends on it (code graph)
4. Transitive spec impact — for each affected code file, which other specs does it fall under
5. Task list — ordered list of everything that needs review or update

This is the most natural question in a spec-driven workflow, and today it cannot be answered without manual effort.

Secondary use case: code change impact

specd impact src/domain/services/content-hash.ts
specd impact --symbol contentHash

Expected answer: the reverse — which specs govern this code, which other specs depend on those, and what the full code blast radius is.

What specd has today

Capability	Source	What it connects
Spec → spec dependencies	dependsOn in .specd-metadata.yaml	Spec graph traversal
Spec → its own files	contentHashes in .specd-metadata.yaml	Freshness of spec.md, verify.md — not source code
Schema → spec sections	contextSections selectors in schema	Which sections to extract from spec files

Note: the specs/<package>/ layout convention used in specd's own repository is project-specific — each team can organize their specs differently. specd does not infer a spec→package mapping from directory structure, and any impact tool must not assume one.

What does NOT exist today

• Spec → code mapping. There is no formal link between a spec and the source files that implement it. This is the critical missing piece for the primary use case. The contentHashes field tracks the spec's own files, not source code.
• Code → spec mapping. The reverse is also missing — no way to ask "which spec covers content-hash.ts?"
• Code graph. specd has no understanding of import/call relationships between source files.
• Unified impact view. No way to go from "I'm changing this spec/file/symbol" to "here's everything affected."

What needs to be built

1. Spec ↔ Code mapping (bidirectional)

The most critical missing piece. A mechanism to associate specs with the source code that implements them, and vice versa. The mapping must not require modifying source code files — it lives entirely in spec-side artifacts.

Option A: Explicit covers field in spec metadata
Add a covers field to .specd-metadata.yaml:

covers:
  - src/domain/services/content-hash.ts
  - src/application/use-cases/_shared/compute-artifact-hash.ts

• Spec → code: read the covers field
• Code → spec: build an inverted index across all specs

Pros: Explicit, precise, queryable, works regardless of directory layout conventions, bidirectional from a single source, no source code modifications.
Cons: Per-spec maintenance burden, can go stale if files move without updating metadata.

Option B: Centralized mapping file
A project-level specd-covers.yaml (or section in specd.yaml) that maps all specs to their implementing files:

mappings:
  core/snapshot-hasher:
    - packages/core/src/domain/services/content-hash.ts
    - packages/core/src/infrastructure/fs/hash.ts
  core/validate-artifacts:
    - packages/core/src/application/use-cases/validate-artifacts.ts

• Spec → code: look up the spec in the mapping
• Code → spec: build an inverted index

Pros: Single file to audit, easy to review in PRs, no source code modifications, no per-spec metadata overhead.
Cons: One more file to maintain, can desynchronize with reality, doesn't scale well for very large projects.

Option C: Hybrid — metadata covers + centralized file
Allow both. The impact engine merges both sources.
Pros: Teams choose what fits their workflow. Cons: Complexity, potential conflicts.

Recommendation: Start with Option A (covers in metadata) — it's the most natural place since it lives alongside the spec it describes. Staleness can be mitigated with specd verify --covers to validate listed files still exist. An agent can automate covers updates as part of the change workflow.

2. Code graph — language-agnostic via Tree-sitter

specd must be language-agnostic. The code graph cannot depend on a specific compiler or language toolchain. Tree-sitter is the right foundation:

• MIT licensed — no licensing concerns. Each language grammar is also MIT or similarly permissive.
• Native Node.js bindings — tree-sitter and node-tree-sitter on npm.
• Proven at scale — used by GitHub, Neovim, Zed, and other tools for multi-language analysis.
• Fast — native C parsers, incremental parsing, handles large codebases.

Architecture

Source files → Tree-sitter parser (per language) → Language-specific AST
  → Query extractor (per language) → Unified symbol model
  → Graph builder → Code knowledge graph
  → Impact engine → Blast radius

Core (language-agnostic):

• A unified symbol model: File, Function, Class, Method, Import
• A unified relation model: CALLS, IMPORTS, EXPORTS, EXTENDS, IMPLEMENTS
• Graph builder, traversal, and impact analysis — all operate on the unified model
• Serialized index (e.g., JSON or SQLite) for fast incremental queries

Language adapters (per language):
Each language adapter is a set of Tree-sitter queries (S-expression patterns) that extract symbols and relations from that language's AST into the unified model. What changes per language is only the query file — the rest of the pipeline is shared.

Example — a TypeScript adapter would have queries for:

• import_statement → IMPORTS relation
• export_statement → EXPORTS relation
• function_declaration, method_definition → Function/Method nodes
• call_expression → CALLS relation
• class_declaration, extends_clause → Class + EXTENDS

A Python adapter would have different queries (import_from_statement, def, class, etc.) but produce the same unified model.

Bundled languages:

• TypeScript / JavaScript — included by default (specd's own language)
• Additional languages installed as optional grammar packages

Plugin model for grammars:

# specd.yaml
codeGraph:
  languages:
    - typescript   # built-in
    - python       # requires tree-sitter-python
    - go           # requires tree-sitter-go

Each grammar is an npm package (tree-sitter-typescript, tree-sitter-python, etc.) plus a specd query file that maps that language's AST nodes to the unified model.

Why not other approaches

Approach	Why not
TypeScript compiler API / ts-morph	TypeScript-only — violates language-agnostic requirement
LSP	Requires running language servers, heavy, hard to batch, different protocol quirks per server
Regex import parsing	No call graph, no symbol-level precision, fragile across languages
External tool integration	Licensing risk, dependency on third-party maintenance, can't guarantee availability
Source code annotations	Requires modifying source files — invasive, couples code to spec tooling

3. Unified impact engine

Combine spec graph + code graph + spec↔code mapping:

Input: spec
  → Spec graph: find dependent specs (upstream dependsOn)
  → Spec→code mapping: find implementing source files (covers)
  → Code graph: for each implementing file, find callers at depth 1/2/3
  → Code→spec mapping: for each affected code file, find other governing specs
  → Output: unified blast radius + ordered task list

Input: file or symbol
  → Code graph: find all callers/importers at depth 1/2/3
  → Code→spec mapping: for each affected file, find governing specs
  → Spec graph: for each affected spec, traverse dependsOn upstream
  → Output: unified blast radius + ordered task list

Output format

Human-readable (default)

specd impact specs/core/snapshot-hasher/spec.md

Dependent specs (via dependsOn):
  - specs/core/validate-artifacts/spec.md
  - specs/core/compile-context/spec.md
  - specs/cli/change-approve/spec.md
  ... (6 total)

Implementing code (via covers):
  - packages/core/src/domain/services/content-hash.ts
  - packages/core/src/infrastructure/fs/hash.ts

Code blast radius:
  d=1 (WILL BREAK):      4 files
  d=2 (LIKELY AFFECTED):  5 files
  d=3 (MAY NEED TESTING): 4 files

Cross-spec impact:
  Code in blast radius also covered by:
  - specs/core/compile-context/spec.md (3 files)
  - specs/core/validate-artifacts/spec.md (2 files)

Task list (15 files, 7 specs):
  1. [spec]  Review/update 6 dependent specs
  2. [code]  Modify 2 implementing files
  3. [code]  Update 8 affected callers
  4. [test]  Update 3 test files

Risk: CRITICAL | Files: ~15 | Specs: 7

Machine-readable (--format json)

Full JSON output for consumption by agents, CI, or other tools.

Rollout

Phase	Scope	Depends on
v1	Spec-only impact (dependsOn traversal — no code)	Existing metadata
v1.5	Spec↔code mapping (covers field) + staleness check	Metadata extension
v2	Tree-sitter code graph (TS/JS built-in) + unified impact	Tree-sitter integration
v2.5	Additional language adapters (Python, Go, Rust, etc.)	Grammar packages + query files
v3	Change-level impact, CI integration, MCP tool	v2+

Related issues

• fix(core): incomplete context when specs lack dependsOn metadata #20 — Incomplete context when specs lack dependsOn metadata (resolved — prerequisite for reliable spec graph traversal)
• Deterministic metadata generation via schema-declared extraction #5 — Deterministic metadata extraction (partially resolves fix(core): incomplete context when specs lack dependsOn metadata #20 for schemas that declare metadataExtraction.dependsOn)

Acceptance criteria

• specd impact <spec-path> returns dependent specs + implementing code + code blast radius
• specd impact <file-path> returns affected code files + governing specs + dependent specs
• specd impact --symbol <name> resolves symbol and runs full analysis
• specd impact --change <id> analyzes all files in a change
• Output includes risk assessment (LOW/MEDIUM/HIGH/CRITICAL)
• Output includes ordered task list
• JSON output available via --format json
• MCP tool available for agent consumption
• specd verify --covers validates that files listed in covers still exist
• Code graph is language-agnostic via Tree-sitter
• TypeScript/JavaScript grammar built-in; additional languages via plugin grammars
• Language adapters are Tree-sitter query files mapping to a unified symbol model
• No source code modifications required — mapping lives entirely in spec-side artifacts

[lsmonki]

Research: Architectural decisions & prior art

Investigation into existing tools, database choices, and how others solve spec↔code mapping. This informs implementation decisions for the phased rollout.

---

1. Database choice: Vector vs Graph vs Flat

Option	Used by	Purpose	Tradeoff
Graph (KuzuDB)	GitNexus	Traversals: "what depends on what", blast radius, paths between nodes	Precision for structural relations, queries like "all callers at depth 3"
Vector (LanceDB)	spec-gen, Cursor	Semantic search: "what code resembles this spec"	Fuzzy matching, good for spec↔code mapping when no explicit link exists
JSON/SQLite flat	Aider (RepoMap), dependency-cruiser	Fast index, PageRank over in-memory graph	Simple, no dependencies, sufficient for small-medium graphs
None (in-memory)	Most CLIs	Build graph on-demand, don't persist	Fast for projects < 1000 files, doesn't scale

Key insight: The issue describes traversals ("get all dependent specs, then implementing code, then callers at depth 1/2/3"). This is pure graph, not semantic search. The covers field provides an explicit link — no need for fuzzy vector matching.

Recommendation: JSON flat / in-memory graph for v1-v2. Evaluate KuzuDB or SQLite if it doesn't scale. No vector DB needed for the core use case.

---

2. How others solve spec↔code mapping

Approach	How it works	Pros/Cons
Traceability matrices (DO-178C, ISO 26262)	Explicit req→code table in a separate document	Industry standard for regulated sectors. Manual, drifts.
Cucumber/Gherkin + step defs	Feature files link to step definitions that are code	Link is executable (tests). Only covers tested code.
Backstage (Spotify)	catalog-info.yaml per component declares ownership and deps	Centralized, machine-readable. Doesn't reach file-level.
CODEOWNERS (GitHub)	Path→team mapping	Not spec→code, but solves ownership.
Convention by structure	specs/core/auth/ → packages/core/src/auth/	Zero config. Fragile, assumes consistent naming.
Auto-derived (embeddings)	Embedding spec + embedding code → similarity	No manual maintenance. Imprecise, black box.
covers in metadata (this issue's proposal)	Each spec declares what files implement it	Explicit, bidirectional via inverted index, lives alongside the spec.

What works well (Cucumber, Backstage): the link is explicit and machine-readable, not inferred.

Open question — who maintains covers?

• Manual — dev updates it when creating/modifying specs
• Semi-auto — specd suggest-covers uses heuristics (name, path, imports) to propose
• Agent-assisted — agent updates covers as part of the change workflow
• Verified — specd verify --covers alerts when files don't exist or specs lack covers

---

3. Existing tools evaluated for code graph layer

Tier 1: Directly usable as Node.js libraries

Tool	Best for	Limitation
@ast-grep/napi	Multi-language AST parsing/querying with typed Node.js API. 20+ languages, MIT.	No graphs out of the box; you build them
dependency-cruiser	JS/TS import/module dependency graph (programmatic cruise() API). MIT.	JS/TS only, module-level only
ts-morph	Deep TS/JS semantic analysis with compiler accuracy. MIT.	TS/JS only, slow on large codebases
node-tree-sitter	Direct tree-sitter access (spec-gen uses this). MIT.	Low-level, needs manual query authoring

Tier 2: Usable as CLI pipeline

Tool	Best for	Limitation
SCIP (scip-typescript)	Compiler-accurate symbol index with cross-repo navigation. Apache-2.0.	CLI-only, Protobuf output, no direct graphs

Tier 3: Design references (study the approach)

Tool	Key pattern to study
Aider RepoMap	tree-sitter def/ref extraction + PageRank ranking over file graph
GitNexus	Multi-phase pipeline: parse, resolve, cluster, search over KuzuDB property graph
Cursor indexing	Merkle-tree incremental sync + embedding-based semantic search
Repomix	tree-sitter signature extraction for context compression
spec-gen	tree-sitter call graph + LanceDB vector index + significance scoring

Not recommended

Tool	Reason
stack-graphs	Archived/abandoned by GitHub (Jan 2025)
tree-sitter-graph DSL	Rust-only, no Node.js bindings
Semgrep	Security scanner, not a graph tool; cross-file features now commercial
GitNexus (for embedding)	PolyForm Noncommercial license — cannot be used in a product

---

4. Architecture recommendation for specd

specd has a clean ports/adapters architecture. The code graph should follow the same pattern:

domain/          → new entities (CodeFile, Symbol, CodeEdge)
application/     → new port: CodeGraphProvider + use cases (BuildCodeGraph, ComputeImpact)
infrastructure/  → adapters: ast-grep/napi (default), dependency-cruiser (JS/TS), SCIP (precision)

A CodeGraphProvider port allows swapping implementations without touching the impact engine.

---

5. Key decisions to make

Decision	Viable options	Suggested
DB for code graph	JSON flat / SQLite / KuzuDB	JSON flat for v1-v2, evaluate KuzuDB if it doesn't scale
Spec↔code mapping	covers in metadata (as proposed)	Yes, with specd verify --covers + semi-auto suggest
Multi-language parser	@ast-grep/napi / tree-sitter direct	@ast-grep/napi (better DX in TS, same foundation)
Graph granularity	File / Symbol / Call	File-level for v1.5, symbol+call for v2
Who maintains covers	Manual / semi-auto / agent	Semi-auto with verification
Architecture in specd	Port CodeGraphProvider + adapters	Yes, follows existing pattern

---

References

• ast-grep NAPI docs
• dependency-cruiser API
• SCIP protocol
• Aider RepoMap approach
• spec-gen call graph

[lsmonki]

Package architecture & boundaries

Following the research above, here's the refined package structure for the code-aware layer in specd.

---

Package map

@specd/core              → Deterministic
                           Defines ports: CodeGraphProvider (interface)
                           New entities: CodeFile, Symbol, CodeEdge
                           Use cases: ComputeDrift, FindCoverageGaps, ComputeImpact
                           Compares spec graph vs code graph vs git state
                           No native dependencies added

@specd/code-graph        → Deterministic, new package
                           tree-sitter via @ast-grep/napi
                           Builds code graph: imports, calls, symbols
                           Implements CodeGraphProvider port
                           Native dependencies (NAPI bindings) isolated here
                           No LLM, no embeddings

@specd/gen               → Non-deterministic (LLM + embeddings), new package
                           Owns its own LLM client + embedding client (API keys, endpoints)
                           Autonomous pipeline: bootstrap, drift-fix (batch)
                           Consumes @specd/code-graph for analysis
                           Does NOT go through LLM CLIs (Claude, Codex, etc.)

@specd/skills            → Prompt/instruction packages for LLM CLIs
                           Core skills: write-spec, suggest-covers, review-drift, etc.
                           Adapts quality based on available packages
                           If @specd/code-graph is installed → enriched context
                           If @specd/gen is installed → can leverage its analysis
                           Single package, no skills-gen split

@specd/cli               → Registers commands based on available packages
                           specd impact, specd drift → always (core + code-graph)
                           specd gen bootstrap, specd gen drift-fix → if @specd/gen installed

@specd/mcp               → Exposes tools based on available packages
                           Same progressive enhancement as CLI

---

Boundary: gen vs skills

The key distinction is who controls the LLM:

	Skills	Gen
LLM	The CLI's LLM (Claude, Codex, etc.)	Gen's own LLM client
Embeddings	Not possible	Yes, batch via /embeddings endpoint
Orchestration	Single-pass, interactive	Multi-step pipeline, batch
API keys	None (uses host CLI)	Own config (provider, model, endpoint)
Use case	Punctual tasks with dev supervision	Batch operations, bootstrapping

A skill can invoke gen commands via shell (e.g., "run specd gen suggest-covers") but the skill itself doesn't contain the pipeline logic.

Task placement

Task	Where	Why
bootstrap (legacy repo → initial specs)	gen	Batch, N files, clustering, embeddings for grouping
drift-fix batch (12 stale specs)	gen	Multi-spec pipeline, orchestrated
suggest-covers for a single spec	skill	LLM sees code + spec, proposes paths
write-spec for a change	skill	Punctual, interactive, dev supervises
review-drift for 1 spec	skill	LLM compares spec vs code, suggests update
Index code graph	code-graph	tree-sitter batch, no LLM needed

---

Progressive enhancement pattern

Skills adapt based on what's installed — they don't break without optional packages:

@specd/skills only
  → write-spec works with basic context (spec + workspace files)

@specd/skills + @specd/code-graph
  → write-spec gets enriched context (imports, callers, dependency graph)

@specd/skills + @specd/code-graph + @specd/gen
  → write-spec can leverage gen's analysis artifacts if available

Same skill, better results. No separate skills-gen package needed.

---

Deterministic vs non-deterministic boundary

This is the architectural invariant:

Deterministic (no LLM):
  core         → drift detection, coverage gaps, impact analysis, spec graph
  code-graph   → code graph building, symbol extraction, import/call resolution

Non-deterministic (LLM):
  gen          → spec generation, batch drift fixes, bootstrapping
  skills       → instructions for external LLM CLIs

specd drift tells you what's wrong (deterministic). specd gen drift-fix proposes how to fix it (LLM). specd drift --check in CI fails the build (deterministic). A skill in Claude Code helps you fix one spec interactively (LLM via host CLI).

---

Dependency graph

@specd/core          ← no new heavy deps
    ↑
@specd/code-graph    ← @ast-grep/napi + tree-sitter grammars
    ↑
@specd/gen           ← LLM client + embedding client
    
@specd/skills        → reads core, optionally detects code-graph and gen
@specd/cli           → registers commands from core, code-graph, gen
@specd/mcp           → exposes tools from core, code-graph, gen

[lsmonki]

Storage decision: LadybugDB as unified graph + vector store

After evaluating the options (separate graph DB + vector DB, JSON flat files, SQLite, etc.), the decision is to use LadybugDB as the single storage engine for @specd/code-graph.

Why LadybugDB

LadybugDB is the community fork of KuzuDB (acquired by Apple, Oct 2025). It's an embedded columnar graph database — "DuckDB for graphs" — with native vector search support.

• Embeddable: runs in-process like SQLite, no server, single .lbug file
• Graph + Vector in one: native HNSW vector index extension + Cypher queries
• Node.js bindings: @ladybugdb/core on npm, prebuilt binaries
• MIT license
• Actively maintained: v0.15.1 (March 2026), 592+ stars, inherited battle-tested KuzuDB engine from University of Waterloo

Why one DB instead of two

The impact analysis use case needs both structural traversals AND semantic similarity. With separate databases (e.g., SQLite for graph + LanceDB for vectors), hybrid queries require application-level joins. With LadybugDB, it's a single Cypher query:

-- Hybrid: find specs covering code similar to a query, within 2 imports of auth.ts
MATCH (f:File)-[:IMPORTS*1..2]->(target:File {path: 'src/auth.ts'})
WITH f
ORDER BY array_cosine_similarity(f.embedding, $query_vector) DESC
LIMIT 10
MATCH (s:Spec)-[:COVERS]->(f)
RETURN s, f

Schema sketch

-- Nodes
CREATE NODE TABLE Spec (id STRING, title STRING, content_hash STRING, PRIMARY KEY(id))
CREATE NODE TABLE File (path STRING, language STRING, embedding FLOAT[768], PRIMARY KEY(path))
CREATE NODE TABLE Symbol (id STRING, name STRING, kind STRING, file_path STRING, PRIMARY KEY(id))

-- Structural relations (deterministic, from code-graph)
CREATE REL TABLE COVERS (FROM Spec TO File)
CREATE REL TABLE DEPENDS_ON (FROM Spec TO Spec)
CREATE REL TABLE IMPORTS (FROM File TO File)
CREATE REL TABLE CALLS (FROM Symbol TO Symbol)
CREATE REL TABLE DEFINES (FROM File TO Symbol)

-- Vector index (for gen/skills)
CALL create_hnsw_index('File', 'embedding', 'file_embedding_idx')

How each package uses it

@specd/code-graph    → Owns the LadybugDB instance
                       Writes: File, Symbol, IMPORTS, CALLS, DEFINES nodes/rels
                       Reads: structural traversals for impact analysis
                       Storage: .specd/code-graph.lbug

@specd/core          → Reads via CodeGraphProvider port
                       Impact engine: traversals (COVERS, DEPENDS_ON, IMPORTS, CALLS)
                       Drift detection: compare content_hash vs git state
                       Does NOT depend on LadybugDB directly (port abstraction)

@specd/gen           → Reads + writes via code-graph
                       Writes: embeddings into File.embedding
                       Reads: hybrid queries (traversal + vector similarity)
                       Uses vector search for: suggest-covers, bootstrap clustering

@specd/skills        → Reads via code-graph (if available)
                       Enriched context from graph traversals
                       No direct DB dependency (goes through code-graph API)

What this replaces

Previous assumption	New decision
JSON flat files for v1-v2, evaluate graph DB later	LadybugDB from v2 (when code graph enters). v1 spec-only impact still uses in-memory traversal
Separate vector DB (LanceDB) in @specd/gen	Vector index lives in the same LadybugDB instance
Two storage engines to maintain	One embedded file, one query language

Risk

LadybugDB is a ~5 month old fork. The engine is mature (KuzuDB research + enterprise use), but the community is young. Mitigation: the CodeGraphProvider port abstraction means the storage backend can be swapped without touching core or gen.

[lsmonki]

MCP tools: exposing the code graph to LLM CLIs

The code graph in LadybugDB becomes significantly more valuable when exposed as MCP tools. Instead of an LLM exploring the repo blindly (grep, glob, read N files), it gets precise, structured answers from the graph in a single tool call.

Proposed MCP tools

Tool	Input	Output	Source
search_symbol	name, kind, pattern	Matching symbols + file + line	Structural query
search_file	path or glob pattern	Files + specs that cover them	Structural query
get_callers	symbol name, depth (1-3)	Call chain (who calls this)	Graph traversal
get_importers	file path, depth (1-3)	Files that import this file	Graph traversal
get_spec_coverage	file or symbol	Specs that cover this code	Graph traversal (COVERS⁻¹)
get_impact	spec or file path	Full blast radius (specs + code + tasks)	Unified traversal
suggest_covers	spec id	Candidate files ranked by relevance	Hybrid (traversal + vector)
get_context	spec or file	Compiled context enriched with graph data	Traversal + core context

Why this matters

Without MCP (LLM explores blind):

LLM: "I need to understand what depends on computeHash..."
  → grep for "computeHash" across repo
  → read 15 files to understand imports
  → grep for spec files that mention hashing
  → read 8 more files
  → ~50 tool calls, ~30k tokens consumed, still might miss things

With MCP (LLM queries the graph):

LLM: tool: get_callers("computeHash", depth=2)
     tool: get_spec_coverage("src/domain/services/content-hash.ts")
  → 2 tool calls, structured response, complete and precise

Less tokens, less hallucination, better results. The LLM spends its context on reasoning instead of exploration.

Relationship with skills

Skills become thin instruction layers that tell the LLM which MCP tools to use and in what order. The skill provides the workflow; the MCP tools provide the capability.

Skill: "suggest-covers"
  Instructions:
    1. Read the spec with get_context({spec_id})
    2. Find related code with suggest_covers({spec_id})
    3. For each candidate, verify with get_callers() and get_importers()
    4. Propose the covers list to the user

  The skill has zero logic — it's a prompt.
  All capability comes from the MCP tools.

Implementation

These tools live in @specd/mcp, which already exists as a scaffolded package. The MCP server queries the CodeGraphProvider port from core, which is backed by @specd/code-graph (LadybugDB). Tools that need vector search (like suggest_covers) are only available when @specd/gen has populated embeddings.

Progressive enhancement applies here too:

• code-graph installed: all structural tools available (search, callers, importers, impact, coverage)
• code-graph + gen: hybrid tools also available (suggest_covers with vector ranking)
• neither installed: only spec-level tools (existing specd MCP tools for spec/change management)

[lsmonki]

Spec discovery: how to detect what needs specs

The problem

How does specd know what specs are missing? What code deserves a spec? This is inherently language-dependent — what constitutes an "entry point" or "public contract" varies by language and framework.

Graph concepts glossary

The code graph represents files and symbols as nodes, and their relationships (imports, calls) as edges. From this structure, several metrics emerge that help identify what code is architecturally significant.

Core metrics

• fanIn — the number of incoming edges to a node. For a file: how many other files import it. For a symbol: how many other symbols call it. High fanIn = many things depend on this → changes here have wide impact.
• fanOut — the number of outgoing edges from a node. For a file: how many other files it imports. For a symbol: how many other symbols it calls. High fanOut = this depends on many things → it's a coordinator or orchestrator.
• depth — the shortest path length from the nearest seed entry point to this node. depth=0 is the entry point itself, depth=1 is what it directly loads, etc. Lower depth = closer to the surface, higher priority for specs.

Node classifications

These classifications are derived purely from graph topology — no language knowledge needed.

Classification	How it's identified	What it means	Example
Entry point	Has external importers (or is a seed file) but no internal callers. Nothing inside the project calls it — it's where execution begins.	The public surface of the application. Almost always needs a spec.	src/index.ts, main.go, an Express app setup file
Hub	fanIn >= N (configurable, default 5). Many files/symbols depend on this one.	Core business logic. A change here ripples through the codebase. High-risk if unspecced.	A UserService imported by 12 other files
Bridge	Removing this node would disconnect two clusters — it's the only link between them.	Critical integration point between domains. If it breaks, two parts of the system lose contact.	A shared EventBus used by both auth/ and billing/ modules
Cluster	A group of files that are tightly connected to each other (many internal edges) and loosely connected to the rest. Detected via graph community algorithms.	A natural domain boundary. Clusters often map 1:1 to specs.	All files under src/auth/ that import each other heavily
Cluster boundary	A file inside one cluster that is imported by files in other clusters.	The interface between domains. Changes here affect multiple clusters.	src/auth/types.ts imported by both auth/ and api/ clusters
Leaf	fanIn = 0 (nothing depends on this). It's a terminal node in the dependency tree.	Low risk — changing it affects nothing else. Low priority for specs.	src/utils/format-date.ts
Orphan	No edges at all — not imported by anything, doesn't import anything relevant.	Likely dead code, a standalone script, or a file missed by the parser. Worth investigating.	src/legacy/old-migration.ts

Visual example

                    ┌─────────────┐
                    │  index.ts   │  ← Entry point (depth=0, no callers)
                    └──────┬──────┘
                           │ imports
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ routes/  │ │ routes/  │ │ config.ts│
        │ auth.ts  │ │ users.ts │ └──────────┘
        └────┬─────┘ └────┬─────┘     depth=1
             │             │
             ▼             ▼
        ┌──────────────────────┐
        │   UserService.ts     │  ← Hub (fanIn=8, many importers)
        └──────────┬───────────┘
                   │                  depth=2
          ┌────────┼────────┐
          ▼        ▼        ▼
     ┌────────┐┌────────┐┌────────┐
     │UserRepo││EventBus││Logger  │
     └────────┘└───┬────┘└────────┘
                   │                  ← Bridge (connects auth + billing clusters)
          ┌────────┼────────┐
          ▼                 ▼
     ┌─────────┐      ┌──────────┐
     │auth/    │      │billing/  │  ← Two clusters
     │tokens.ts│      │invoice.ts│
     └─────────┘      └──────────┘
                                      depth=3+

     ┌──────────────┐
     │ old-migr.ts  │  ← Orphan (no edges)
     └──────────────┘

Two-layer approach

Layer 1: Graph metrics (language-agnostic, always works)

Pure graph analysis over the code graph. No language knowledge needed.

Signal	Detection	What it means
Entry point	Node with external importers but no internal callers	Public API surface, likely needs spec
Hub	Node with fanIn >= N (configurable)	Core business logic, high-risk if unspecced
Bridge	Node whose removal disconnects two clusters	Critical integration point
Cluster boundary	Files imported by other clusters	Interface between domains
Orphan	Node with no edges	Dead code or standalone utility
Leaf	Node with no dependents	Low risk, low priority for specs

This layer works for any language without configuration. It answers "these 5 files are hubs with no spec coverage" purely from graph topology.

Layer 2: Language adapters (opt-in, precise)

Tree-sitter queries per language that identify contracts — things the code explicitly exposes to the outside world. Each adapter maps language-specific AST patterns to a unified Contract model.

The impact engine only sees Contract — it doesn't know if it came from a TypeScript export or a Python decorator.

TypeScript / JavaScript

Pattern	AST query target
Public API exports	export_statement, export default from index.ts / barrel files
HTTP routes	Express/Fastify/Hono route handlers, Next.js/Nuxt page exports
CLI commands	commander .command(), yargs builders
Event handlers	.on(), .addEventListener(), event emitter patterns
Exported types/interfaces	export interface, export type (contract surface)

Python

Pattern	AST query target
HTTP routes	@app.route, @router.get/post, FastAPI @app.get, Django urlpatterns
CLI commands	@click.command, @app.command (Typer), argparse subparsers
Public API	Functions/classes in __init__.py, __all__ declarations
Celery tasks	@app.task, @shared_task
Test fixtures	@pytest.fixture (for verify.md coverage)

Go

Pattern	AST query target
Public API	Exported functions/types (capitalized names)
HTTP handlers	http.HandleFunc, mux.Handle, Gin/Echo/Fiber handlers
CLI commands	cobra.Command definitions
gRPC services	RegisterXxxServer(), service interface implementations
Main entry	func main() in package main

Rust

Pattern	AST query target
Public API	pub fn, pub struct, pub trait, pub mod
HTTP handlers	Actix #[get]/#[post], Axum handler functions, Rocket #[route]
CLI	clap derive macros, #[command] attributes
Entry point	#[tokio::main], fn main()
FFI boundary	#[no_mangle], extern "C"

Java / Kotlin

Pattern	AST query target
HTTP endpoints	@RestController, @GetMapping, @PostMapping, @RequestMapping
Public API	public methods on public classes
Spring beans	@Service, @Component, @Bean
CLI	Picocli @Command, Spring Boot CommandLineRunner
Events	@EventListener, ApplicationEvent publishers
gRPC	@GrpcService, generated stub implementations

PHP

Pattern	AST query target
HTTP routes	Laravel Route::get/post, Symfony #[Route] attribute, @Route annotation
Controllers	Laravel controller methods (public methods in *Controller classes), Symfony controller actions
Artisan commands	protected $signature in classes extending Command, Symfony #[AsCommand]
Public API	public function on classes, interface implementations
Event listeners	Laravel $listen array in EventServiceProvider, Symfony #[AsEventListener]
Middleware	Laravel middleware handle() methods, Symfony kernel event subscribers
Service providers	register() and boot() in ServiceProvider classes
Queue jobs	Laravel handle() in Job classes, Symfony Messenger handlers

Ruby

Pattern	AST query target
HTTP routes	Rails resources, get/post/put in routes.rb, Sinatra get '/' blocks
Controllers	Public methods in *Controller classes
CLI	Thor desc/method_option, Rake tasks
Public API	public methods, module includes
Jobs	Sidekiq perform, ActiveJob perform
Events	ActiveSupport callbacks, after_commit, pub/sub patterns

C# / .NET

Pattern	AST query target
HTTP endpoints	[HttpGet], [HttpPost], [ApiController], Minimal API MapGet/MapPost
Public API	public methods on public classes
CLI	System.CommandLine handlers
gRPC	Service implementations, [GrpcService]
Events	event declarations, INotificationHandler (MediatR)
Middleware	IMiddleware.InvokeAsync, pipeline delegates

Unified Contract model

All language adapters produce the same output:

interface Contract {
  id: string              // "file::ClassName.method"
  name: string            // human-readable name
  kind: ContractKind      // 'http-route' | 'export' | 'cli-command' | 'event' | 'public-api' | 'job' | 'middleware'
  filePath: string
  line: number
  language: string
  metadata?: {
    httpMethod?: string   // GET, POST, etc.
    httpPath?: string     // /api/users/:id
    visibility?: string   // public, exported, etc.
  }
}

Coverage analysis output

specd coverage

Spec coverage: 64/87 files (73%)

  CRITICAL (contracts without specs):
    ⚠ src/api/routes/auth.ts        → 3 HTTP routes, no spec
    ⚠ src/api/routes/webhooks.ts    → 2 HTTP routes, no spec
    ⚠ src/cli/commands/deploy.ts    → CLI command, no spec

  HIGH (graph hubs without specs):
    ⚠ src/domain/services/billing.ts  → fanIn: 12, 0 specs
    ⚠ src/domain/services/permissions.ts → fanIn: 8, bridge node, 0 specs

  MEDIUM (cluster boundaries without specs):
    ◦ src/infrastructure/cache/redis.ts → imported by 3 clusters
    ◦ src/infrastructure/queue/worker.ts → imported by 2 clusters

  LOW (leaf nodes without specs):
    · src/utils/format-date.ts → 0 dependents
    · src/utils/slugify.ts → 0 dependents

  specd gen bootstrap --priority critical   # generate specs for critical gaps
  specd gen bootstrap --priority high       # include hub nodes

Configurable discovery rules

In specd.yaml, teams can declare what matters for their project:

specDiscovery:
  rules:
    - pattern: "src/domain/entities/*.ts"     # every entity needs a spec
    - pattern: "src/api/routes/*.ts"          # every route needs a spec
    - pattern: "app/Http/Controllers/*.php"   # every controller needs a spec
    - kind: entryPoint                        # every entry point from graph
    - kind: hub                               # every hub function
    - minFanIn: 5                             # any file with 5+ importers
  ignore:
    - pattern: "src/utils/**"                 # utils don't need specs
    - pattern: "src/generated/**"             # generated code
    - kind: leaf                              # leaf nodes are low priority

Integration with gen

specd coverage is deterministic (core + code-graph). It identifies what needs specs.
specd gen bootstrap is non-deterministic (gen + LLM). It generates the actual specs.

The coverage output feeds directly into gen as a prioritized work list.

[lsmonki]

Spec discovery strategy: follow-the-code + top-down

Follow-the-code: seed-based discovery

Instead of scanning all files and guessing what's important, start from known entry points and follow imports recursively. The code tells you what matters.

Step 1: Detect seeds (layer 0 — glob patterns, no parsing)

Language	Seed files by convention
PHP	index.php, public/index.php, routes/web.php, routes/api.php, artisan
JS/TS	index.ts, main.ts, app.ts, server.ts, package.json#main/exports
Python	__main__.py, main.py, app.py, wsgi.py, asgi.py, manage.py
Go	main.go (in package main), cmd/*/main.go
Rust	main.rs, lib.rs
Java	*Application.java (Spring Boot), Main.java
Ruby	config.ru, config/routes.rb, Rakefile, bin/*
C#	Program.cs, Startup.cs

Seed detection can live in core — just glob patterns, no code-graph dependency needed.

Step 2: Follow imports recursively (BFS from seeds)

index.php
  → require 'bootstrap/app.php'
    → require 'routes/web.php'
      → Route::get('/users', [UserController::class, 'index'])
        → UserController::index()
          → UserService::getAll()
            → UserRepository::findAll()

Each file gets a depth from the nearest entry point. Depth = natural priority:

• d=0: entry point itself → critical spec
• d=1: what it loads directly (routes, bootstrap) → API/config spec
• d=2: controllers/handlers → domain specs
• d=3+: services, repos → implementation specs

In LadybugDB:

MATCH path = (seed:File {path: 'index.php'})-[:IMPORTS*1..5]->(f:File)
RETURN f.path, length(path) as depth
ORDER BY depth

Combined strategy: follow-the-code + top-down

Both approaches complement each other:

	Follow-the-code	Top-down (full scan + graph metrics)
Finds	All live code, with natural depth	Everything, including orphans and dead code
Misses	Orphan code, standalone scripts, unused files	Doesn't know what's actually important vs residual
Strength	Priority comes from the code itself	Completeness

Merged result:

1. Follow-the-code from seeds → marks each file with depth from entry point → this is "live code"
2. Top-down full scan → everything NOT reached = orphan or dead code
3. Merge: priority = depth + graph metrics (fanIn, hub, bridge) + contracts (from language adapters)

Combined coverage output

specd coverage

Reachable code (from 3 entry points):
  CRITICAL: 4 HTTP routes without specs (depth 2)
  HIGH: 3 hub services without specs (depth 3, fanIn > 5)
  MEDIUM: 7 files at depth 4+ without specs

Unreachable code (not imported from any entry point):
  ⚠ src/legacy/old-billing.ts → orphan, was it removed?
  ⚠ src/utils/deprecated-hash.ts → orphan
  · src/scripts/migrate.ts → standalone script (expected)

specd gen bootstrap --priority critical    # generate specs for critical gaps
specd gen bootstrap --reachable-only       # skip orphan code

Discovery layers summary

Layer 0: File conventions (glob patterns, core, no parsing)
  → Detect seed entry points by filename
  → Works without code-graph installed

Layer 1: Follow-the-code (code-graph, BFS from seeds)
  → Recursive import traversal from seeds
  → Depth = natural priority
  → Finds all live code

Layer 2: Graph metrics (code-graph, language-agnostic)
  → fanIn, fanOut, hubs, bridges, clusters, orphans
  → Enriches priority, detects unreachable code

Layer 3: Language adapters (code-graph, tree-sitter queries)
  → Contracts: HTTP routes, exports, CLI commands, handlers
  → Maximum precision for what deserves a spec

Each layer adds precision. Layer 0 works with zero dependencies. Layer 3 gives full contract-level discovery. Teams choose how deep to go.

[lsmonki]

Proposed CLI commands inventory

Commands that emerged during the architectural discussion. Follows the existing specd CLI pattern: specd <group> <action> [options].

specd graph — Code graph management (@specd/code-graph)

Command	Description
specd graph index	Parse all source files via tree-sitter, extract symbols/imports/calls, and build the full code graph in LadybugDB. Overwrites any existing index.
specd graph index --incremental	Compute git diff since last indexed commit, re-parse only changed files, and update affected nodes/edges in the graph.
specd graph status	Print last indexed commit hash, timestamp, total file count, and whether the index is stale (files changed since last index).
specd graph stats	Print graph metrics: node count (files, symbols), edge count (imports, calls, covers), cluster count, orphan files, hub nodes, bridge nodes.

specd impact — Impact analysis (@specd/core + @specd/code-graph)

Command	Description
specd impact <specId>	Traverse dependsOn to find dependent specs. With code-graph: also resolve covers to find implementing files, walk importers/callers at depth 1-3, and map affected files back to other specs. Output: unified blast radius + ordered task list + risk level.
specd impact <file-path>	Walk importers/callers of the file at depth 1-3, map each affected file to its governing specs via covers inverted index, then traverse dependsOn upstream for each affected spec. Output: code blast radius + spec impact + task list.
specd impact --symbol <name>	Resolve the symbol in the graph, then trace callers of that specific symbol (not the whole file). Map affected symbols/files to specs. Output: same as file impact but scoped to the symbol's call chain.
specd impact --change <id>	Read all files registered under the change (via register-file records), run file-level impact for each, merge results, deduplicate, and produce a unified blast radius across all files in the change.

specd coverage — Spec coverage analysis (@specd/code-graph)

Command	Description
specd coverage	Scan all files in the code graph, check each against the covers inverted index, and report uncovered files grouped by priority: CRITICAL (contracts/entry points), HIGH (hubs), MEDIUM (cluster boundaries), LOW (leaves). Includes reachable vs orphan breakdown.
specd coverage --reachable-only	Same as above but skip files not reachable from any seed entry point (orphan/dead code).

specd search — Code and spec search (@specd/code-graph + @specd/gen)

Command	Description
specd search <query>	Auto mode: run BM25 full-text search first; if fewer than 3 results and semantic index exists, fall back to vector similarity. Return matched files/symbols with scores.
specd search <query> --mode symbol	Look up symbols by exact name, glob pattern, or kind filter in the graph. Return matching symbols with file path, line number, kind, and fanIn/fanOut.
specd search <query> --mode text	Run BM25 full-text search over indexed file content. Return matching files ranked by relevance score with matching line excerpts.
specd search <query> --mode semantic	Compute embedding for the query, run cosine similarity against file embeddings in LadybugDB vector index. Return top-N files ranked by similarity. Requires @specd/gen to have populated embeddings.

specd drift — Spec↔code drift detection (@specd/core + @specd/code-graph)

Command	Description
specd drift	For each spec with covers, compare the spec's contentHashes against current file state and git history. Report specs where covered code changed after the spec was last updated, grouped by severity.
specd drift --check	Same analysis as specd drift but exit with non-zero code if any drift is detected. Designed for CI pipelines.
specd drift --fix	Run drift detection, then for each drifted spec invoke @specd/gen to propose an updated spec based on the code changes. Output proposed diffs for review. Requires @specd/gen.

specd gen — Spec generation (@specd/gen)

Command	Description
specd gen bootstrap	Read the code graph, cluster files by domain, and generate initial spec.md + verify.md for each cluster using LLM. Uses embeddings for clustering and significance scoring for prioritization. Creates spec directories and populates covers.
specd gen bootstrap --priority <level>	Same as bootstrap but only generate specs for coverage gaps at or above the given priority (critical, high, medium). Reads priority from specd coverage output.
specd gen bootstrap --reachable-only	Same as bootstrap but skip files not reachable from seed entry points.
specd gen drift-fix	Read all drifted specs (from specd drift), batch-generate proposed spec updates using LLM with code diff context. Output one delta per drifted spec for review.
specd gen suggest-covers [specId]	Compute embedding for the spec content, run vector similarity against file embeddings, and propose a ranked list of candidate files for covers. If specId omitted, run for all specs missing covers.

specd change — New subcommands for change tracking

Command	Description
specd change track <name>	Record current HEAD as baseline commit for this change and set SPECD_ACTIVE_CHANGE=<name> in the session environment (via $CLAUDE_ENV_FILE). Hooks can then read this variable to associate file modifications with the change.
specd change untrack <name>	Clear SPECD_ACTIVE_CHANGE from session env. Compute merged diff of all registered files against the baseline commit. Extract modified files and symbols from the diff. Map files to the change's specs and propose covers updates.
specd change register-file <name> <file>	Compute diff of <file> against the baseline commit recorded at track. Compare with last registered diff for this file+change: if equal → no-op, if different → store new version, if first time → store. Called by hooks automatically or by skills as backup.

Existing commands extended

Command	Description
specd spec validate [specId] --covers	For each file listed in the spec's covers field, check that the file exists on disk. Report missing files as errors. If code-graph is available, also check that listed symbols still exist in the graph.

Notes

• specd impact progressively enhances: spec-only (core), full blast radius (core + code-graph)
• specd search has three modes: symbol (structural), text (BM25 full-text), semantic (vector). Default auto tries text first, falls back to semantic if few results
• specd coverage is deterministic and feeds into specd gen bootstrap as a prioritized work list
• specd drift is deterministic detection (core); specd drift --fix delegates to gen
• specd change track/untrack are session context commands for hook integration — not lifecycle transitions
• All commands support --format json for machine consumption and MCP tool exposure

[lsmonki]

Change tracking: auto-registering file changes during LLM operations

Problem

When an LLM executes a skill to implement a change, it modifies files. Those modifications should be automatically associated with the change and its specs — this is how covers gets populated without manual maintenance.

Challenges:

• The LLM may forget to call a registration command
• Hooks (Claude Code) see all Write/Edit but don't know which change they belong to
• Multiple Claude sessions may run concurrently
• Skills don't know the session_id
• Files may have uncommitted changes in the working tree — diffing against the last commit would include unrelated modifications
• Must be robust against LLM failures and duplicate registrations

Solution: track / untrack + pre/post snapshots

Starting change tracking

specd change track <change-id>

Records current HEAD as the fallback baseline commit and sets SPECD_ACTIVE_CHANGE=<change-id> in the session environment via $CLAUDE_ENV_FILE.

Hook integration (Claude Code)

PostToolUse hook on Bash: inspects tool_input.command. If it detects specd change track <change-id>, extracts the change id and writes to the session environment:

SPECD_ACTIVE_CHANGE=<change-id>

CLAUDE_ENV_FILE is session-specific — concurrent sessions don't share state:

session A → /tmp/claude-env-1234   → SPECD_ACTIVE_CHANGE=fix-auth
session B → /tmp/claude-env-5678   → SPECD_ACTIVE_CHANGE=add-billing

File change capture: pre/post snapshot pattern

The baseline commit is not reliable if the working tree has uncommitted changes. Instead, we capture a pre-modification snapshot of each file before the LLM touches it.

PreToolUse hook (Write/Edit):

1. Read SPECD_ACTIVE_CHANGE from env
2. If set, call specd change register-file <change-id> <file> --pre
3. This copies the file's current content (which may include uncommitted changes) to .specd/tracking/<change-id>/<file>
4. If a snapshot already exists for this file+change → no-op (we already have the original state)

PostToolUse hook (Write/Edit):

1. Read SPECD_ACTIVE_CHANGE from env
2. If set, call specd change register-file <change-id> <file>
3. This computes the diff of the file against:
   • The pre-snapshot in .specd/tracking/<change-id>/<file> (preferred — captures real pre-modification state)
   • Fallback: the baseline commit from track (if no snapshot exists, e.g., skill calling register-file without hooks)

Idempotency: if the computed diff equals the last registered diff for this file+change → no-op. If different → store new version. If first time → store.

PreToolUse:   register-file fix-auth src/auth/handler.ts --pre
                → copies current handler.ts to .specd/tracking/fix-auth/src/auth/handler.ts

LLM edits the file...

PostToolUse:  register-file fix-auth src/auth/handler.ts
                → diff current handler.ts vs .specd/tracking/fix-auth/src/auth/handler.ts
                → registers diff₁

LLM edits the file again...

PreToolUse:   register-file fix-auth src/auth/handler.ts --pre
                → snapshot already exists → no-op (we want the original, not the intermediate)

PostToolUse:  register-file fix-auth src/auth/handler.ts
                → diff current vs original snapshot → diff₂ ≠ diff₁ → registers new version

Dual mechanism: hooks + explicit calls

Mechanism	Pre-snapshot	Post-diff	Limitation
Hook capture (PreToolUse + PostToolUse)	Automatic	Automatic	Needs hook support
Skill explicit call	Skill calls --pre before modifying	Skill calls after modifying	LLM may forget
Both together	Belt and suspenders	Belt and suspenders	—

Ending change tracking

specd change untrack <change-id>

This triggers:

1. Clears SPECD_ACTIVE_CHANGE from session env
2. Merges all registered diffs into a single changeset
3. Extracts modified files and symbols from the merged diff
4. Associates files → change → specs
5. Proposes covers updates for affected specs
6. Cleans up .specd/tracking/<change-id>/ snapshots

Full flow example

1. specd change create fix-auth --specs core:auth/oauth
2. specd change track fix-auth
     → records HEAD as fallback baseline
     → sets SPECD_ACTIVE_CHANGE=fix-auth in session env

3. LLM is about to write src/auth/handler.ts:
     PreToolUse hook → register-file fix-auth src/auth/handler.ts --pre
       → copies current handler.ts to .specd/tracking/fix-auth/...
     LLM writes the file
     PostToolUse hook → register-file fix-auth src/auth/handler.ts
       → diffs current vs snapshot → stores diff

4. LLM is about to edit src/auth/service.ts:
     PreToolUse hook → register-file fix-auth src/auth/service.ts --pre
       → copies current service.ts
     LLM edits the file
     PostToolUse hook → register-file fix-auth src/auth/service.ts
       → diffs current vs snapshot → stores diff

5. specd change untrack fix-auth
     → merges all diffs
     → extracts: [handler.ts, service.ts] + symbols changed
     → maps to change fix-auth → spec core:auth/oauth
     → proposes updating covers for core:auth/oauth
     → cleans up .specd/tracking/fix-auth/

What this solves

Problem	Solution
covers drifts out of sync	Auto-updated from actual LLM modifications
Don't know what files implement a spec	The changes tell you
Hooks don't know the change context	track establishes context via CLAUDE_ENV_FILE
Concurrent sessions	Each session has its own env file
Uncommitted changes in working tree	Pre-snapshot captures real state, not commit state
LLM forgets to register	Hook as backup, diff comparison prevents duplicates
LLM CLI without hooks (Codex, etc.)	Skill calls register-file --pre and register-file explicitly
Duplicate registrations	Use case compares diffs — same diff = no-op

CLI commands

Command	Description
specd change track <change-id>	Record current HEAD as fallback baseline and set SPECD_ACTIVE_CHANGE in session env via $CLAUDE_ENV_FILE. Hooks can then associate file modifications with this change.
specd change untrack <change-id>	Clear SPECD_ACTIVE_CHANGE from session env. Merge all registered diffs into a single changeset, extract modified files and symbols, map to the change's specs, propose covers updates, and clean up tracking snapshots.
specd change register-file <change-id> <file> --pre	Copy the file's current content to .specd/tracking/<change-id>/<file> as a pre-modification snapshot. No-op if snapshot already exists for this file+change. Called by PreToolUse hooks or explicitly by skills before modifying a file.
specd change register-file <change-id> <file>	Compute diff of the file against its pre-snapshot (or fallback baseline commit if no snapshot exists). Compare with last registered diff: if equal → no-op, if different → store new version, if first time → store. Called by PostToolUse hooks or explicitly by skills after modifying a file.

Future improvements

• Record content_hash per snapshot to optimize diff comparison
• Persist change events in an event log for audit
• Allow reassigning files if tracking starts late
• Add metrics: files per change, auto-discovered covers per change
• specd change tracked to list all changes with active tracking

[lsmonki]

Identified gaps — resolved

All gaps have been discussed and decisions captured. Summary below for reference.

1. Auto-refresh strategy for the code graph

Decision: No auto-refresh. Commands (impact, drift, coverage) warn if the graph is stale but execute with current data. In CI, --check fails if the graph is stale — CI pipelines should run specd graph index --incremental before specd drift --check. LLM agents can ask the user and run specd graph index --background which forks a subprocess that copies the .lbug file, updates the copy, and does an atomic rename when done — queries are never blocked.

2. Multi-workspace code graph

Decision: One global graph. All workspaces' codeRoot are indexed into a single .specd/code-graph.lbug. File nodes carry a workspace property for filtering. IMPORTS edges cross workspaces naturally.

3. Cross-language edges

Decision: Out of scope. covers + dependsOn already connect code across languages via specs. If a spec covers both frontend/auth.ts and backend/auth.py, impact connects them through the spec — no need for HTTP route matching. The unified model supports cross-language edges if a future adapter needs them.

4. Covers granularity: symbol-level when possible, file-level fallback

Decision: Both formats coexist. On untrack, the merged diff is cross-referenced with symbol line ranges from the graph: if code-graph has the language adapter, extract changed symbols → file::symbol. If not, fall back to file-level. Impact engine traces callers of specific symbols when available, whole file when not.

5. Code-graph configuration in specd.yaml

Decision: Minimal config, no languages field — autodetect by file extension via tree-sitter. Exclude patterns handle filtering.

codeGraph:
  seeds:
    - src/index.ts
    - src/main.py
  discovery:
    hubThreshold: 5
    maxDepth: 10
  storage:
    path: .specd/code-graph.lbug

6. Rollout and acceptance criteria

Decision: Deferred. The issue is serving as a design notebook. Rollout phases and acceptance criteria will be revised when implementation starts.

7. Graceful degradation

Decision:

• covers points to deleted files → warn in specd spec validate --covers, no auto-remove
• tree-sitter can't parse a file → skip with warning, file appears as node without symbols
• Import can't be resolved → dead edge, no relation created, warning in verbose
• LadybugDB corrupted → rebuild with specd graph index from scratch (.lbug is derived data, no loss)
• code-graph not installed → spec-only fallback via progressive enhancement

[lsmonki]

Update: SymbolNode.comment field for full-text search

Added a comment field to SymbolNode (string | undefined) that stores the raw comment text (JSDoc, block, or line comments) immediately preceding each symbol declaration. This enables full-text search over symbol documentation without requiring vector embeddings.

What changed

Specs updated:

• specs/code-graph/symbol-model/spec.md — new comment field in SymbolNode requirement
• specs/code-graph/language-adapter/spec.md — comment extraction requirement for adapters
• specs/code-graph/graph-store/spec.md — comment substring filter in SymbolQuery, comment STRING column in LadybugDB schema
• All corresponding verify.md files with new scenarios

Code implemented:

• SymbolNode interface: readonly comment: string | undefined
• SymbolQuery interface: readonly comment?: string (substring match)
• TypeScriptLanguageAdapter: extracts preceding comment from AST via node.prev()
• LadybugGraphStore: persists comment column, supports CONTAINS filter in findSymbols
• InMemoryGraphStore: substring filter via .includes()
• 4 new tests (80 total, all passing)

How it works

const provider = createCodeGraphProvider({ storagePath: '/project' })
await provider.open()
await provider.index({ workspacePath: '/project' })

// Full-text search in symbol comments
const results = await provider.findSymbols({ comment: 'validates user' })
// Returns all symbols whose JSDoc/comment contains "validates user"

This is independent of the embedding field (deferred to v2+) — it's a simple, immediate full-text search capability.