openlore 2.0.6 → 2.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. package/README.md +140 -23
  2. package/dist/cli/commands/decisions.d.ts.map +1 -1
  3. package/dist/cli/commands/decisions.js +187 -174
  4. package/dist/cli/commands/decisions.js.map +1 -1
  5. package/dist/cli/commands/mcp.d.ts +694 -0
  6. package/dist/cli/commands/mcp.d.ts.map +1 -1
  7. package/dist/cli/commands/mcp.js +417 -203
  8. package/dist/cli/commands/mcp.js.map +1 -1
  9. package/dist/constants.d.ts +6 -0
  10. package/dist/constants.d.ts.map +1 -1
  11. package/dist/constants.js +14 -0
  12. package/dist/constants.js.map +1 -1
  13. package/dist/core/analyzer/artifact-generator.d.ts.map +1 -1
  14. package/dist/core/analyzer/artifact-generator.js +59 -4
  15. package/dist/core/analyzer/artifact-generator.js.map +1 -1
  16. package/dist/core/analyzer/call-graph.d.ts +19 -1
  17. package/dist/core/analyzer/call-graph.d.ts.map +1 -1
  18. package/dist/core/analyzer/call-graph.js +128 -28
  19. package/dist/core/analyzer/call-graph.js.map +1 -1
  20. package/dist/core/architecture/check.d.ts +63 -0
  21. package/dist/core/architecture/check.d.ts.map +1 -0
  22. package/dist/core/architecture/check.js +192 -0
  23. package/dist/core/architecture/check.js.map +1 -0
  24. package/dist/core/architecture/rules.d.ts +73 -0
  25. package/dist/core/architecture/rules.d.ts.map +1 -0
  26. package/dist/core/architecture/rules.js +201 -0
  27. package/dist/core/architecture/rules.js.map +1 -0
  28. package/dist/core/decisions/lock.d.ts +10 -0
  29. package/dist/core/decisions/lock.d.ts.map +1 -0
  30. package/dist/core/decisions/lock.js +77 -0
  31. package/dist/core/decisions/lock.js.map +1 -0
  32. package/dist/core/decisions/project.d.ts +59 -0
  33. package/dist/core/decisions/project.d.ts.map +1 -0
  34. package/dist/core/decisions/project.js +68 -0
  35. package/dist/core/decisions/project.js.map +1 -0
  36. package/dist/core/decisions/verifier.d.ts +10 -0
  37. package/dist/core/decisions/verifier.d.ts.map +1 -1
  38. package/dist/core/decisions/verifier.js +48 -5
  39. package/dist/core/decisions/verifier.js.map +1 -1
  40. package/dist/core/provenance/change-coupling.d.ts +68 -0
  41. package/dist/core/provenance/change-coupling.d.ts.map +1 -0
  42. package/dist/core/provenance/change-coupling.js +134 -0
  43. package/dist/core/provenance/change-coupling.js.map +1 -0
  44. package/dist/core/provenance/git-provenance.d.ts +67 -0
  45. package/dist/core/provenance/git-provenance.d.ts.map +1 -0
  46. package/dist/core/provenance/git-provenance.js +177 -0
  47. package/dist/core/provenance/git-provenance.js.map +1 -0
  48. package/dist/core/provenance/project.d.ts +37 -0
  49. package/dist/core/provenance/project.d.ts.map +1 -0
  50. package/dist/core/provenance/project.js +46 -0
  51. package/dist/core/provenance/project.js.map +1 -0
  52. package/dist/core/services/edge-store.d.ts +41 -0
  53. package/dist/core/services/edge-store.d.ts.map +1 -1
  54. package/dist/core/services/edge-store.js +251 -3
  55. package/dist/core/services/edge-store.js.map +1 -1
  56. package/dist/core/services/llm-service.d.ts +9 -0
  57. package/dist/core/services/llm-service.d.ts.map +1 -1
  58. package/dist/core/services/llm-service.js +15 -4
  59. package/dist/core/services/llm-service.js.map +1 -1
  60. package/dist/core/services/mcp-handlers/architecture.d.ts +19 -0
  61. package/dist/core/services/mcp-handlers/architecture.d.ts.map +1 -0
  62. package/dist/core/services/mcp-handlers/architecture.js +104 -0
  63. package/dist/core/services/mcp-handlers/architecture.js.map +1 -0
  64. package/dist/core/services/mcp-handlers/change-coupling.d.ts +16 -0
  65. package/dist/core/services/mcp-handlers/change-coupling.d.ts.map +1 -0
  66. package/dist/core/services/mcp-handlers/change-coupling.js +57 -0
  67. package/dist/core/services/mcp-handlers/change-coupling.js.map +1 -0
  68. package/dist/core/services/mcp-handlers/graph.d.ts +27 -0
  69. package/dist/core/services/mcp-handlers/graph.d.ts.map +1 -1
  70. package/dist/core/services/mcp-handlers/graph.js +98 -16
  71. package/dist/core/services/mcp-handlers/graph.js.map +1 -1
  72. package/dist/core/services/mcp-handlers/orient.d.ts.map +1 -1
  73. package/dist/core/services/mcp-handlers/orient.js +122 -2
  74. package/dist/core/services/mcp-handlers/orient.js.map +1 -1
  75. package/dist/core/services/mcp-handlers/reachability.d.ts +30 -0
  76. package/dist/core/services/mcp-handlers/reachability.d.ts.map +1 -0
  77. package/dist/core/services/mcp-handlers/reachability.js +222 -0
  78. package/dist/core/services/mcp-handlers/reachability.js.map +1 -0
  79. package/dist/core/services/mcp-handlers/structural-diff.d.ts +31 -0
  80. package/dist/core/services/mcp-handlers/structural-diff.d.ts.map +1 -0
  81. package/dist/core/services/mcp-handlers/structural-diff.js +268 -0
  82. package/dist/core/services/mcp-handlers/structural-diff.js.map +1 -0
  83. package/dist/core/services/mcp-handlers/test-impact.d.ts +34 -0
  84. package/dist/core/services/mcp-handlers/test-impact.d.ts.map +1 -0
  85. package/dist/core/services/mcp-handlers/test-impact.js +221 -0
  86. package/dist/core/services/mcp-handlers/test-impact.js.map +1 -0
  87. package/dist/core/services/mcp-handlers/tool-guard.d.ts +45 -0
  88. package/dist/core/services/mcp-handlers/tool-guard.d.ts.map +1 -0
  89. package/dist/core/services/mcp-handlers/tool-guard.js +81 -0
  90. package/dist/core/services/mcp-handlers/tool-guard.js.map +1 -0
  91. package/dist/core/services/mcp-handlers/utils.d.ts.map +1 -1
  92. package/dist/core/services/mcp-handlers/utils.js +15 -1
  93. package/dist/core/services/mcp-handlers/utils.js.map +1 -1
  94. package/dist/core/services/mcp-watcher.d.ts.map +1 -1
  95. package/dist/core/services/mcp-watcher.js +9 -0
  96. package/dist/core/services/mcp-watcher.js.map +1 -1
  97. package/package.json +9 -8
package/README.md CHANGED
@@ -16,7 +16,7 @@ AI agents are powerful but amnesiac. On every new task:
16
16
  - They re-read the same source files to understand structure
17
17
  - They forget architectural decisions made two sessions ago
18
18
  - They have no link between specs and code — drift is invisible
19
- - File-by-file navigation often burns **15,000–50,000 tokens** per orientation pass, before a single line of useful code is written
19
+ - File-by-file navigation often burns an estimated **15,000–50,000 tokens** per orientation pass, before a single line of useful code is written (measured benefit is task-dependent — it shows up on deep questions in larger codebases, not on small/familiar repos; see the † note below)
20
20
  - In long sessions, they drift from authoritative retrieval toward internally cached reasoning — producing subtly wrong architectural assumptions that compound silently until a refactor breaks
21
21
 
22
22
  openlore closes this loop. Run a full analysis once, then keep the graph incrementally updated as the codebase evolves. Even greenfield projects become cognitively "brownfield" after only a few agent sessions — architectural context fragments, decisions disappear, and agents repeatedly reconstruct the same understanding from scratch.
@@ -33,7 +33,7 @@ Three layers, each usable independently:
33
33
  |-------|-------------|----------|
34
34
  | **1. Static Analysis** | Call graph, clusters, McCabe CC, external deps → `CODEBASE.md` digest | No |
35
35
  | **2. Spec Layer** | LLM-generated living specs, ADRs, drift detection, decision gates | For generation |
36
- | **3. Agent Runtime** | 45 MCP tools — `orient()`, semantic search, graph expansion | No |
36
+ | **3. Agent Runtime** | 50 MCP tools — `orient()`, semantic search, graph expansion | No |
37
37
 
38
38
  You can use layer 1 alone to give agents structural context. Add layer 2 for semantic intent and architectural governance through OpenSpec-compatible living specifications. Layer 3 keeps that context continuously accessible through graph-native MCP tools once `openlore mcp` is running.
39
39
 
@@ -47,9 +47,24 @@ You can use layer 1 alone to give agents structural context. Add layer 2 for sem
47
47
  | Spec drift detection | ❌ | ❌ | ✓ milliseconds, no API |
48
48
  | Architectural decision gates | ❌ | ❌ | ✓ pre-commit hook |
49
49
  | Offline structural analysis | ❌ | ❌ | ✓ |
50
- | Token-efficient orient() | ❌ | ❌ | ✓ ~1–3k vs 15–50k tokens |
50
+ | Token-efficient orient() | ❌ | ❌ | ✓ ~1–3k vs 15–50k tokens |
51
51
  | Living spec generation | ❌ | ❌ | ✓ |
52
52
  | Persistent cross-session architectural memory | ❌ | Partial | ✓ |
53
+
54
+ † **Measured, and it depends on the task.** The exact token figures above remain
55
+ an estimate, but the Spec 14 agent benchmark (`npm run bench:agent`, WITH vs
56
+ WITHOUT openlore, `claude -p`, N=4 medians) now gives a measured two-tier result:
57
+ - **Small, familiar repos + shallow "who-calls-X" queries:** openlore *adds*
58
+ ~43% cost — the model already knows the code, so there's no orientation to save.
59
+ - **Larger codebases + deep "how does X flow through Y" questions (its target):**
60
+ with the lean `--preset navigation` tool surface, openlore is a **net win —
61
+ −7% cost and −26% tool-calls at N=4, scaling with repo size (up to −21% on
62
+ ~640–790-file repos)**, at 100% answer correctness in both arms.
63
+
64
+ So the headline savings hold where openlore is designed to help, not on toy
65
+ queries. Full results, methodology, and honest caveats:
66
+ [docs/AGENT-BENCHMARKS.md](docs/AGENT-BENCHMARKS.md). The plumbing latency (orient
67
+ ~430µs p50) is separate and real — see [scripts/BENCHMARKS.md](scripts/BENCHMARKS.md).
53
68
  | Long-session confidence decay (Epistemic Lease) | ❌ | ❌ | ✓ |
54
69
 
55
70
  Traditional coding agents reconstruct architecture from repeated file reads every session. openlore persists it as a queryable graph.
@@ -82,7 +97,7 @@ See [docs/install.md](docs/install.md). The MCP server keeps the index fresh as
82
97
 
83
98
  Then ask your agent: **`orient("add a new payment method")`**
84
99
 
85
- That single call returns the relevant functions, their call neighbours, matching spec sections, and insertion-point candidates — preserving architectural continuity across sessions instead of forcing the agent to repeatedly reconstruct context from raw file reads. In practice, this often reduces orientation cost from ~30,000 exploratory tokens to ~1,000 targeted tokens.
100
+ That single call returns the relevant functions, their call neighbours, matching spec sections, and insertion-point candidates — preserving architectural continuity across sessions instead of forcing the agent to repeatedly reconstruct context from raw file reads. The Spec 14 benchmark ([docs/AGENT-BENCHMARKS.md](docs/AGENT-BENCHMARKS.md)) measures this directly: on deep "how does X flow through Y" questions in larger codebases, openlore (with `--preset navigation`) cuts cost ~7% and tool-calls ~26% at N=4 (more on bigger repos); on small/familiar repos with shallow queries it adds overhead instead. Net: it pays off in its target arena, not on toy queries.
86
101
 
87
102
  **Full pipeline** (specs + decisions — optional and additive):
88
103
 
@@ -158,6 +173,32 @@ One graph query replaces most exploratory file reads. The agent knows exactly wh
158
173
 
159
174
  ---
160
175
 
176
+ ## Agent Cheat Sheet
177
+
178
+ The full surface is 50 tools, but day-to-day work needs a handful. Reach for the right one by situation:
179
+
180
+ | Situation | Tool |
181
+ |-----------|------|
182
+ | Starting any task | `orient(task)` — functions, callers, specs, insertion points in one call |
183
+ | "Which file/function handles X?" | `search_code` |
184
+ | Call topology across many files | `get_subgraph` / `analyze_impact` |
185
+ | "What's the blast radius if I change this?" | `analyze_impact` — risk score + up/downstream chain + **governing decisions** |
186
+ | "What decisions constrain this code?" | `analyze_impact` / `get_subgraph` → `governingDecisions` (Spec 16) |
187
+ | Planning where to add a feature | `suggest_insertion_points` |
188
+ | "How does request X reach function Y?" | `trace_execution_path` |
189
+ | "I changed X — which tests should I run?" | `select_tests` — backward reachability to the reaching tests + paths (Spec 19) |
190
+ | "What's dead / what dies if I delete X?" | `find_dead_code` — cross-language reachability, confidence-tagged candidates (Spec 20) |
191
+ | "What changed structurally / whose callers are now stale?" | `structural_diff` — graph diff, stale callers, rename flags (Spec 21) |
192
+ | "What changes together with this / what's volatile?" | `get_change_coupling` — co-change + churn from git history (Spec 22) |
193
+ | "May I add this import here / what breaks the architecture?" | `check_architecture` — pre-edit verdict against declared rules (Spec 23) |
194
+ | Recording an architectural choice | `record_decision` **before** writing the code |
195
+ | Reading / checking a spec | `get_spec` · `search_specs` · `check_spec_drift` |
196
+ | Ranking what changed by risk | `detect_changes` |
197
+
198
+ Everything else (read a file, grep, list files) uses your native tools. Full reference: [docs/mcp-tools.md](docs/mcp-tools.md).
199
+
200
+ ---
201
+
161
202
  ## Use OpenLore as a Claude Code Skill
162
203
 
163
204
  OpenLore ships a canonical [Claude Code Skill](https://docs.claude.com/en/docs/claude-code/skills) at [`skills/openlore-orient/`](skills/openlore-orient/). Install it once and Claude Code will automatically call `orient()` at the start of every task — no `CLAUDE.md` editing required.
@@ -200,11 +241,31 @@ Compares git changes against spec mappings in milliseconds. Detects: Gap (code c
200
241
 
201
242
  **MCP** (no API key)
202
243
 
203
- 45 graph-native tools exposed over stdio. Together they act as a persistent architectural runtime for coding agents: orientation, graph traversal, semantic retrieval, drift awareness, decision context, and structural risk analysis.
204
- `orient()` is the main entry point — one call replaces 10+ file reads. `detect_changes` risk-scores changed functions using call graph centrality × change type multiplier. See [docs/mcp-tools.md](docs/mcp-tools.md).
244
+ 50 graph-native tools exposed over stdio. Together they act as a persistent architectural runtime for coding agents: orientation, graph traversal, semantic retrieval, drift awareness, decision context, and structural risk analysis.
245
+ `orient()` is the main entry point — one call replaces 10+ file reads. `detect_changes` risk-scores changed functions using call graph centrality × change type multiplier. Every tool call runs the same guards — input validation against its schema (bad args → JSON-RPC `-32602`), a per-tool timeout, a deterministic output-size cap, and normalized error codes — and the surface carries complete MCP `annotations`. See [docs/mcp-tools.md](docs/mcp-tools.md).
205
246
 
206
247
  `orient()` runs in **~430µs p50** against a 15k-node codebase (TypeScript compiler, ~79k edges). Full benchmark results: [scripts/BENCHMARKS.md](scripts/BENCHMARKS.md).
207
248
 
249
+ **Test impact selection** (no API key, Spec 19)
250
+
251
+ `select_tests` answers "I changed `parseConfig()` — which tests should I run?" by walking the call graph **backward** from the change to every test that transitively reaches it (via `calls` + `tested_by` + inheritance edges), returning each test with its reaching path. This is static, call-graph-based regression test selection (RTS) — established CS — served to the agent at edit time instead of to CI after the fact. grep can't do it (the reach is through indirect calls); the model is slow and guesses; a deterministic graph does it instantly. It is an honest **over-approximate prioritizer** ("run these first"), not a sound replacement for the full suite — the response states its posture, coverage, and caveats (dynamic dispatch / DI can under-select). Inputs: a symbol set or a git diff. Deterministic and offline. See [docs/test-impact-selection.md](docs/test-impact-selection.md).
252
+
253
+ **Reachability & dead-code** (no API key, Spec 20)
254
+
255
+ `find_dead_code` runs cross-language mark-and-sweep over the call graph: reachability from roots (tests, imported symbols, route handlers, `main`), candidate-dead = the unreached remainder, and "what becomes dead if I delete X?" = the set reachable only through X. Prior art (knip, ts-prune) is TS/JS-only; this rides the unified tree-sitter graph across 15+ languages. Results are **confidence-tagged candidates, never deletion authority** — dynamic dispatch, DI, framework routing, and externally-consumed exports cause false positives, stated in the response. A conservative module-level liveness signal keeps high-confidence candidates trustworthy (it cut them from ~470 to ~35 on a real repo). See [docs/reachability-dead-code.md](docs/reachability-dead-code.md).
256
+
257
+ **Structural change analysis** (no API key, Spec 21)
258
+
259
+ `structural_diff` is a graph diff — the structural complement to `git diff`. Between two states (working tree vs a ref, or two refs) it reports functions and edges added/removed, signature changes, and the existing callers in *other* files now **stale** because a callee's signature moved under them. A review/refactor agent gets "this removed `gamma`, changed `alpha`'s signature, and 5 of its callers are now stale" instead of "these 40 lines changed". Only the changed files are re-parsed (old via `git show`, new via the working tree), so it is cheap and never mutates the canonical graph; rename/move ambiguity is flagged, not guessed. See [docs/structural-diff.md](docs/structural-diff.md).
260
+
261
+ **Change-coupling & volatility** (no API key, Spec 22)
262
+
263
+ `get_change_coupling` mines two facts from local git history that the call graph structurally cannot see: **co-change coupling** ("these files almost always change together" — the *invisible* coupling with no import or call edge) and **volatility/churn** ("this file changed 23 times" — a risk flag). Prior art (CodeScene) puts it well: change coupling "isn’t possible to calculate from code alone — it is mined from git." Surfaced additively in `orient` as caution signals. Support/confidence thresholds and a bulk-commit filter keep it honest; it is an **advisory signal, correlation not causation**. Local, deterministic, no network (reuses the Spec 18 git ingestion). See [docs/change-coupling.md](docs/change-coupling.md).
264
+
265
+ **Architecture invariant guardrails** (no API key, Spec 23)
266
+
267
+ `check_architecture` turns an architectural rule from a post-hoc CI failure into a **pre-write** guardrail. A repo declares constraints — `layers`, `forbidden`, `allowedOnly` — in `.openlore/architecture.json` (or via an `Invariant:` marker on a synced ADR, so a recorded decision *carries* its invariant), and the tool answers, before the agent writes the import, *"may a file under A import B?"* with a deterministic verdict + the governing rule + why, plus a full violation scan. Prior art (ArchUnit, dependency-cruiser, import-linter) enforces architecture in CI *after* the code is written and per-language; OpenLore's contributions are **cross-language** rules over the unified dependency graph and **agent-facing, pre-edit** evaluation (reusing the same `classifyLayerEdge` primitive that powers `CODEBASE.md`'s layer report). Opt-in and fully inert until rules are declared; never LLM-inferred; complements, not replaces, CI linters. See [docs/architecture-invariants.md](docs/architecture-invariants.md).
268
+
208
269
  **Epistemic Lease** (no API key)
209
270
 
210
271
  > **Core principle**: EpistemicLease models architectural drift as a behavioral navigation phenomenon rather than a semantic understanding problem. Context decay is driven by where the agent goes (cross-module trajectory), not what it knows.
@@ -232,6 +293,12 @@ When fresh, injection is zero-overhead. Calling `orient()` resets the tracker. U
232
293
 
233
294
  Agents call `record_decision` before writing code. Consolidation runs immediately in the background. At commit time, a pre-commit hook gates the commit until all verified decisions are reviewed and written back as requirements in `spec.md` files. Decisions are classified by scope (`local / component / cross-domain / system`); only `cross-domain` and `system` decisions produce ADR files, keeping the decision log signal-dense.
234
295
 
296
+ Decisions are also **first-class graph nodes**. At analyze time the active decision store is projected — the same parser→projector split that puts Infrastructure-as-Code on the graph — into `decision::<id>` nodes joined to the files they govern by `affects` edges. The relationship is stored, not recomputed: `analyze_impact` and `get_subgraph` return the governing decisions of a symbol and its blast radius as typed neighbors (`nodeType: "decision"`), and `orient` reports which relevant files each decision governs. This turns "what architectural decisions constrain this code, and what does changing it implicate?" into a deterministic graph query — the join no code-navigation competitor offers. The JSON store stays authoritative; the projection is derived and rebuilt on every analyze. See [docs/specs/openlore-spec-16-decisions-as-graph-nodes.md](docs/specs/openlore-spec-16-decisions-as-graph-nodes.md).
297
+
298
+ **Provenance** (no API key, local-only)
299
+
300
+ Reads the local `.git` history (and local `gh` if present) to project `authored_by` (file → person) and `changed_in_pr` (file → PR) edges onto the graph, so `orient` answers "last changed by X in PR #N" — provenance grep cannot surface. **No OAuth, no cloud connector, nothing is ever uploaded**: the git-only path needs no network, and `gh` is an optional enrichment that degrades gracefully when absent or unauthenticated. Bounded (last-touch + top-N recent authors + recent PRs per file) so the graph never bloats; deterministic for a fixed git state. The same local history feeds the change-coupling instrument (Spec 22). See [docs/provenance.md](docs/provenance.md).
301
+
235
302
  **Telemetry** (opt-in, no API key)
236
303
 
237
304
  Cognitive telemetry for empirical measurement of EpistemicLease behavior. Gated by `OPENLORE_TELEMETRY=1` — disabled by default. Writes append-only JSONL to `.openlore/telemetry/` per domain. Agent identity is captured from the MCP `initialize` handshake, enabling per-agent behavioral comparison.
@@ -259,25 +326,66 @@ Key metrics: **obstinacy index** (tool calls after stale before orient — measu
259
326
 
260
327
  OpenSpec provides semantic intent and workflow structure. openlore maintains the evolving implementation as a continuously queryable architectural graph for agents.
261
328
 
329
+ ```mermaid
330
+ flowchart TD
331
+ Code[Codebase] --> Analyze[openlore analyze<br/>tree-sitter · pure static analysis]
332
+ Analyze --> DB[(SQLite graph store<br/>.openlore/analysis/call-graph.db)]
333
+ Analyze --> Digest[CODEBASE.md<br/>~600-token structural digest]
334
+
335
+ subgraph shared["Projected onto shared node + edge primitives"]
336
+ direction LR
337
+ CodeNodes[functions + call edges]
338
+ Iac[IaC resources + references]
339
+ Dec[decisions + affects edges]
340
+ end
341
+ Analyze --> CodeNodes
342
+ Analyze --> Iac
343
+ Analyze -. active decision store .-> Dec
344
+ CodeNodes --> DB
345
+ Iac --> DB
346
+ Dec --> DB
347
+
348
+ DB --> MCP[50 MCP tools<br/>orient · BFS · search · analyze_impact]
349
+ MCP --> Agent((Coding Agent))
350
+
351
+ Code -. optional, API key .-> Gen[openlore generate]
352
+ Gen --> Specs[openspec/specs/*.md<br/>RFC 2119 living specs]
353
+ Code --> Drift[openlore drift<br/>spec/code drift, ms, no API]
354
+ Agent -. record_decision .-> Gate[decisions pre-commit gate]
355
+ Gate --> Specs
262
356
  ```
263
- Codebase
264
-
265
-
266
- openlore analyze ──► SQLite graph store (.openlore/analysis/call-graph.db)
267
- │ │
268
- │ MCP tools (orient, BFS, search…)
269
- │ │
270
- Artifact Generator Agent
271
-
272
- ┌─────┴──────┐
273
- ▼ ▼
274
- CODEBASE.md (optional)
275
- openlore generate ──► openspec/specs/*.md
276
- openlore drift ──► drift report
277
- openlore decisions ► ADR gates
357
+
358
+ The graph and the OpenSpec spec layer are co-equal: the graph makes orientation fast, the specs make it semantically grounded. Drift detection and decision gates connect both. Crucially, application code, Infrastructure-as-Code, and architectural **decisions** all project onto one shared set of node/edge primitives — so a single traversal answers questions that span all three. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full pipeline diagram.
359
+
360
+ **Decisions on the graph** (Spec 16) — a decision becomes a node joined to the files it governs by `affects` edges, so impact analysis returns governance as a neighbor:
361
+
362
+ ```mermaid
363
+ flowchart LR
364
+ D["decision::c6d1ad07<br/>North-star substrate"]:::dec
365
+ D -- affects --> F1[src/cli/export/scip.ts]
366
+ D -- affects --> F2[src/core/analyzer/iac/project.ts]
367
+ F1 -- calls --> G[exportScip]
368
+ classDef dec fill:#6f42c1,stroke:#4b2e83,color:#fff
278
369
  ```
279
370
 
280
- The graph and the OpenSpec spec layer are co-equal: the graph makes orientation fast, the specs make it semantically grounded. Drift detection and decision gates connect both. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full pipeline diagram.
371
+ ---
372
+
373
+ ## Design Decisions
374
+
375
+ OpenLore dogfoods its own decision system. These ADRs were recorded with `record_decision`, gated at commit, and synced into `openspec/specs/` — and (per Spec 16) are now projected onto the graph itself. They are the load-bearing constraints behind the architecture above:
376
+
377
+ | Decision | Rationale | Where |
378
+ |----------|-----------|-------|
379
+ | **North star is a deterministic structural context substrate** | Local-first plumbing (like tree-sitter/SCIP/LSP) that agents build on; every feature must make the coding-agent case more useful and stay grounded in static analysis, not LLM guessing | [ADR-0001](openspec/decisions/adr-0001-north-star-is-a-deterministic-structural-context-s.md) |
380
+ | **IaC resources project onto the existing graph primitives** | One projector maps infrastructure onto `FunctionNode`/`CallEdge` so every MCP tool works on IaC with zero new tooling | `analyzer` spec · `src/core/analyzer/iac/project.ts` |
381
+ | **Decisions project onto the graph the same way** | A parser→projector split turns the decision store into `decision::` nodes + `affects` edges — governance becomes a deterministic graph join | `analyzer` spec · `src/core/decisions/project.ts` (Spec 16) |
382
+ | **EdgeStore uses SCHEMA_VERSION rebuild-on-bump, not migrations** | The graph is fully derivable from source, so a schema change drops and rebuilds — no migration code, no drift | `analyzer` spec · `src/core/services/edge-store.ts` |
383
+ | **BM25 keyword retrieval is the zero-network floor** | `orient`/`search_code` work with no API key or embedding server; dense embeddings are an optional upgrade, never a requirement | `analyzer` spec · Spec 06 |
384
+ | **SCIP is a one-way export, not a round-trip format** | The SQLite graph stays canonical; SCIP exports only the subset it can model, avoiding a lossy bidirectional contract | `cli` spec · `src/cli/export/scip.ts` |
385
+ | **MCP exposes a curated `navigation` preset, not all 50 tools** | A lean graph-traversal surface is what wins the Spec 14 agent benchmark; the full set stays available opt-in | `cli` spec · Spec 14 |
386
+ | **Decision consolidation is serialized with a cross-process file lock** | Concurrent `record_decision` calls were losing drafts; a lock makes consolidation safe and every commit instant | `cli` spec · Spec 15 |
387
+
388
+ This table is not aspirational documentation — it is the live decision log the pre-commit gate enforces and Spec 16 makes queryable. See [docs/governance-dogfooding.md](docs/governance-dogfooding.md).
281
389
 
282
390
  ---
283
391
 
@@ -311,7 +419,7 @@ The manifest captures the public API surface, HTTP routes, stats, dependencies,
311
419
 
312
420
  | Topic | Doc |
313
421
  |-------|-----|
314
- | MCP tools reference (45 tools + parameters) | [docs/mcp-tools.md](docs/mcp-tools.md) |
422
+ | MCP tools reference (50 tools + parameters) | [docs/mcp-tools.md](docs/mcp-tools.md) |
315
423
  | Agent setup (Claude Code, Cline, OpenCode, Vibe…) | [docs/agent-setup.md](docs/agent-setup.md) |
316
424
  | `openlore install` — auto-configure agent surfaces | [docs/install.md](docs/install.md) |
317
425
  | LLM providers + embedding config | [docs/providers.md](docs/providers.md) |
@@ -320,6 +428,13 @@ The manifest captures the public API surface, HTTP routes, stats, dependencies,
320
428
  | CI/CD integration | [docs/ci-cd.md](docs/ci-cd.md) |
321
429
  | Preflight CI staleness gate | [docs/preflight.md](docs/preflight.md) |
322
430
  | SCIP export (Sourcegraph/Glean interop) | [docs/scip-export.md](docs/scip-export.md) |
431
+ | Cross-domain impact (code ↔ infrastructure) | [docs/cross-domain-impact.md](docs/cross-domain-impact.md) |
432
+ | Local provenance (git/PR, no OAuth) | [docs/provenance.md](docs/provenance.md) |
433
+ | Test impact selection (which tests to run) | [docs/test-impact-selection.md](docs/test-impact-selection.md) |
434
+ | Reachability & dead-code analysis | [docs/reachability-dead-code.md](docs/reachability-dead-code.md) |
435
+ | Structural change analysis (graph diff) | [docs/structural-diff.md](docs/structural-diff.md) |
436
+ | Change-coupling & volatility (git-mined) | [docs/change-coupling.md](docs/change-coupling.md) |
437
+ | Architecture invariant guardrails (pre-edit) | [docs/architecture-invariants.md](docs/architecture-invariants.md) |
323
438
  | Federation manifest (cross-repo) | [docs/federation.md](docs/federation.md) |
324
439
  | CLI command reference | [docs/cli-reference.md](docs/cli-reference.md) |
325
440
  | Interactive graph viewer | [docs/viewer.md](docs/viewer.md) |
@@ -363,6 +478,8 @@ The manifest captures the public API surface, HTTP routes, stats, dependencies,
363
478
 
364
479
  **Infrastructure-as-Code**: Terraform/HCL · Kubernetes · Helm · CloudFormation · Ansible · Pulumi · AWS CDK · CDKTF — IaC resources and their references are projected onto the same graph as application code, so `orient`, `search_code`, `get_subgraph`, and `analyze_impact` answer "what is the blast radius of changing this security group / ConfigMap / IAM role?" with zero new tooling. See [docs/iac.md](docs/iac.md).
365
480
 
481
+ **Cross-domain impact** (Spec 17): for embedded IaC (Pulumi/CDK/CDKTF), the code that provisions a resource is linked to it by a `references` edge, so `analyze_impact` traverses the code↔infra boundary **end-to-end** — "what infrastructure does this handler reach?" and the reverse, "what code breaks if I change this resource?". Infra neighbors are surfaced as a typed, ecosystem-tagged `crossDomain` block, distinct from the code blast radius. A code-only navigator structurally cannot answer this. Reproducible example: [docs/cross-domain-impact.md](docs/cross-domain-impact.md).
482
+
366
483
  ---
367
484
 
368
485
  ## Development
@@ -1 +1 @@
1
- {"version":3,"file":"decisions.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/decisions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkLpC,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA0E1E;AAED,wBAAsB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA0D5E;AAeD,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBvE;AAUD,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAczE;AAiDD,eAAO,MAAM,gBAAgB,SAyiBzB,CAAC"}
1
+ {"version":3,"file":"decisions.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/decisions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmLpC,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA0E1E;AAED,wBAAsB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA0D5E;AAeD,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBvE;AAUD,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAczE;AAiDD,eAAO,MAAM,gBAAgB,SAqjBzB,CAAC"}