Merge pull request #182 from clay-good/fix/e2e-hardening-post-v2.1.2

fix: e2e hardening for v2.1.3 (first-run gitignore, no-throw contracts, panic concurrency, large-output + federation conformance)

Author: clay-good

CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+All notable changes to OpenLore are documented here. This project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.1.3] - 2026-06-22
+
+Everything merged since v2.1.2: a batch of new agent-facing capabilities plus a
+deep end-to-end hardening and dogfooding pass. The version is read from
+`package.json`, so the CLI and the MCP server both report `2.1.3`.
+
+### Added
+
+- **Agent behavioral governance ("panic")** — opt-in, off by default (#175). A
+  PreToolUse destabilization guard (`openlore panic-check`), an observe→memory
+  feedback loop that feeds behavioral hotspots into `orient`, an optional Gryph
+  runtime observer, and an accuracy-validation harness
+  (`panic-validate` / `panic-calibrate` / `panic-replay`). Enable per project with
+  `openlore setup --panic <mode>` and install the hooks with
+  `openlore setup --hooks <format>` (remove them with `--hooks none`).
+- **External spec-store binding** — the `spec_store_status` MCP tool (federation
+  preset) reports the read-only health of a `.openlore/config.json` `specStore`
+  binding and its indexed targets (#178).
+- **Working-set context briefing** — the `working_set_context` MCP tool assembles
+  one token-budgeted, per-target structural briefing for an active change across
+  its spec-store targets (#180).
+- **Change-impact certificate** — the `change_impact_certificate` MCP tool and the
+  `openlore impact-certificate` CLI certify what a diff touches: the paths it
+  newly opens into declared covering surfaces (differential, no LLM), blast
+  radius, drifted specs, and the tests to run (#181).
+- **Live dependency graph in watch mode** — `watch` now reconciles file creates &
+  deletes and keeps `dependency-graph.json` import edges (including inline
+  `<script>` and HTML asset edges) fresh incrementally (#173).
+- **Pi extension** — marketplace gallery preview image (#174); Windows daemon
+  hardening so no console window flashes (#177).
+
+### Changed
+
+- Removed the `get_decisions` MCP tool. ADRs are now surfaced through
+  `search_specs` (domain `decisions`) and via `orient`'s ADR matches, which now
+  work without an embedding server (#179).
+- `.mjs` / `.cjs` / `.mts` / `.cts` files are now recognized as JavaScript /
+  TypeScript and included in the call graph and signature index (previously
+  silently dropped).
+- Panic-state: the on-disk file is the single source of truth for the
+  cross-process intervention counter; all writers (MCP server, hook, daemon)
+  serialize through one lock.
+- Documentation: Windows setup steps in CONTRIBUTING (#176); corrected and guarded
+  MCP tool-count references.
+
+### Fixed
+
+End-to-end hardening pass (PR #182), all with regression tests:
+
+- **First run** — `openlore init` and `openlore run` now create `.gitignore` on a
+  fresh `git init` repo, so `.openlore/` analysis artifacts (multi-MB lance
+  binaries) aren't accidentally committed and don't pollute diff-based tools.
+- **MCP no-throw / robustness** — `get_spec` confines its `domain` argument
+  (path-traversal fix); `get_file_dependencies` guards a partial dependency-graph
+  artifact; `change_impact_certificate` drops non-object surface members and
+  `buildLeaseAnchors` never escapes the handler; a malformed `callGraph` is
+  normalized instead of crashing graph handlers; large tool results stay valid
+  JSON when capped to the byte budget.
+- **LLM generation** — all providers tolerate malformed or `usage`-less responses
+  (common with OpenAI-compatible gateways) instead of crashing or reporting `$NaN`
+  cost.
+- **Panic** — fixed a cross-process lost-update on the intervention counter;
+  untrusted `panic-state.json` fields are sanitized and a NaN timestamp is treated
+  as expired; panic hooks gained an uninstall path and update in place on a format
+  change.
+- **Multi-repo federation** — a registered repo that throws mid-query is skipped
+  with a reason instead of aborting the whole fleet query; tool output no longer
+  leaks absolute host paths.
+- **CLI** — `verify --json` and `decisions --sync` now exit non-zero on failure
+  (they previously reported failure but exited 0, defeating CI gates); `decisions`
+  has a top-level error boundary; `openlore view` reports a friendly message on a
+  port-in-use, sanitizes errors before logging, and serves a 404 (not 500) for a
+  missing graph artifact.
+
+**Full Changelog**: https://github.com/clay-good/OpenLore/compare/v2.1.2...v2.1.3

README.md

@@ -14,7 +14,7 @@
   <br>
   <img src="https://img.shields.io/badge/MCP-ready-7c3aed?logo=anthropic&logoColor=white" alt="MCP ready">
   <img src="https://img.shields.io/badge/languages-18-f97316" alt="18 languages">
-  <img src="https://img.shields.io/badge/tests-3900%2B-success" alt="3900+ tests">
+  <img src="https://img.shields.io/badge/tests-4400%2B-success" alt="4400+ tests">
   <img src="https://img.shields.io/badge/API_key-not_required-0ea5e9" alt="No API key required">
   <a href="https://github.com/clay-good/OpenLore/stargazers"><img src="https://img.shields.io/github/stars/clay-good/OpenLore?style=social" alt="GitHub stars"></a>
 </p>
@@ -312,7 +312,7 @@ If you only install one thing, install `openlore-orient`. The workflow skills ar
 
 Continuously maintains a structural representation of your codebase using pure static analysis. Builds a full call graph persisted to SQLite, runs label-propagation community detection to cluster tightly coupled functions, computes McCabe cyclomatic complexity for every function, and extracts DB schemas, HTTP routes, UI components, middleware chains, and environment variables. Outputs `.openlore/analysis/CODEBASE.md` — a ~600-token structural digest that compresses the equivalent of tens of thousands of exploratory tokens into a small, queryable summary.
 
-With `--watch-auto`, the call graph updates incrementally on every file save: changed file and its direct callers are re-parsed and the graph is atomically swapped. Orient and BFS queries remain live between full analyze runs.
+With `--watch-auto`, the call graph updates incrementally on every file save: the changed file and its direct callers are re-parsed and the graph is atomically swapped. File creates and deletes are reconciled too, and `dependency-graph.json` import edges (including HTML asset edges) stay live. Orient and BFS queries remain live between full analyze runs.
 
 **Generate** (API key required)
 
@@ -525,6 +525,8 @@ openlore federation list                                     # ✓ indexed / ⚠
 
 Once peers are registered, `analyze_impact`, `find_dead_code`, `select_tests`, and `find_path` take an opt-in `federation` flag and answer across the fleet — who consumes a published symbol, whether an export is dead *everywhere*, which consumer tests a change touches — always naming the repos consulted vs skipped, never guessing for an unindexed one. The capability is opt-in: `openlore mcp --preset federation`. See [docs/cli-reference.md](docs/cli-reference.md#federation-multi-repo).
 
+The same `federation` preset also exposes a spec-store arc — binding OpenLore to an external spec store and reasoning about a change against it: `spec_store_status` (read-only health of a `.openlore/config.json` `specStore` binding and its indexed targets), `working_set_context` (one token-budgeted, per-target structural briefing for an active change across its targets), and `change_impact_certificate` (the paths a diff *newly opens* into declared covering surfaces, plus blast radius, drifted specs, and tests to run — also as `openlore impact-certificate`). All read-only, conclusion-shaped, and advisory.
+
 ---
 
 ## Documentation

docs/agent-setup.md

@@ -100,7 +100,7 @@ Wire the generated digest into your agent's context:
 
 **Claude Code — MCP config (token-efficient two-server setup)**
 
-MCP clients load all tool schemas at session start. With 61 tools, this costs ~15k tokens of `tools/list` before any work begins (Spec 28 measured it; the lossless server-side trim is only ~2%, so the real lever is deferral). Claude Code supports `alwaysLoad: false` (deferred, default) — tools load only when the agent searches for them via Tool Search.
+MCP clients load all tool schemas at session start. With 62 tools, this costs ~16k tokens of `tools/list` before any work begins (Spec 28 measured it; the lossless server-side trim is only ~2%, so the real lever is deferral). Claude Code supports `alwaysLoad: false` (deferred, default) — tools load only when the agent searches for them via Tool Search.
 
 The recommended setup uses two server entries: one always-visible core server and one deferred full server:
 
@@ -124,7 +124,7 @@ The recommended setup uses two server entries: one always-visible core server an
 ```
 
 - **`openlore-core`** exposes 6 tools always visible in context (~600 tokens): `orient`, `search_code`, `record_decision`, `detect_changes`, `check_spec_drift`, `get_health_map`. These are the tools most likely to be called at session start.
-- **`openlore`** exposes all 61 tools deferred — loaded on demand when the agent uses Tool Search (e.g. "find tool for BFS graph traversal").
+- **`openlore`** exposes all 62 tools deferred — loaded on demand when the agent uses Tool Search (e.g. "find tool for BFS graph traversal").
 
 If you only need one server entry, use `alwaysLoad: false` (the default) with the standard `openlore mcp` command — all tools are deferred and searchable via Tool Search.
 

docs/mcp-tools.md

@@ -184,7 +184,6 @@ Most tools run on **pure static analysis** — no LLM quota consumed. Exceptions
 |------|-------------|:---:|
 | `get_spec` | Read the full content of an OpenSpec domain spec by domain name. | Yes (generate) |
 | `get_mapping` | Requirement->function mapping produced by `openlore generate`. Shows which functions implement which spec requirements, confidence level, and orphan functions with no spec coverage. | Yes (generate) |
-| `get_decisions` | List or search Architecture Decision Records (ADRs) stored in `openspec/decisions/`. Optional keyword query. | Yes (generate) |
 | `check_spec_drift` | Detect code changes not reflected in OpenSpec specs. Compares git-changed files against spec coverage maps. Issues: gap / stale / uncovered / orphaned-spec / adr-gap. | Yes (generate) |
 | `search_specs` | Semantic search over OpenSpec specifications to find requirements, design notes, and architecture decisions by meaning. Also searches ADR files (`openspec/decisions/adr-*.md`) indexed under domain `decisions`. Returns linked source files for graph highlighting. Use this when asked "which spec covers X?" or "where should we implement Z?" or "what decisions were made about Y?". Requires a spec index built with `openlore analyze` or `--reindex-specs`. | Yes (generate) |
 | `list_spec_domains` | List all OpenSpec domains available in this project. Use this to discover what domains exist before doing a targeted `search_specs` call. | Yes (generate) |
@@ -426,12 +425,6 @@ maxDepth        number   Maximum path length in hops (default: 6)
 maxPaths        number   Maximum number of paths to return (default: 10, max: 50)
 ```
 
-**`get_decisions`**
-```
-directory  string   Absolute path to the project directory
-query      string   Optional keyword to filter ADRs by title or content
-```
-
 **`get_spec`**
 ```
 directory  string   Absolute path to the project directory

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "openlore",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "description": "Persistent architectural memory and structural cognition for AI coding agents.",
   "type": "module",
   "main": "dist/api/index.js",

package.json

@@ -27,6 +27,7 @@ vi.mock('../core/services/gitignore-manager.js', () => ({
   gitignoreExists: vi.fn(),
   isInGitignore: vi.fn(),
   addToGitignore: vi.fn(),
+  ensureGitignored: vi.fn(),
 }));
 
 import {
@@ -44,6 +45,7 @@ import {
   gitignoreExists,
   isInGitignore,
   addToGitignore,
+  ensureGitignored,
 } from '../core/services/gitignore-manager.js';
 
 const mockDetectProjectType = vi.mocked(detectProjectType);
@@ -56,6 +58,7 @@ const mockCreateOpenSpecStructure = vi.mocked(createOpenSpecStructure);
 const mockGitignoreExists = vi.mocked(gitignoreExists);
 const mockIsInGitignore = vi.mocked(isInGitignore);
 const mockAddToGitignore = vi.mocked(addToGitignore);
+const mockEnsureGitignored = vi.mocked(ensureGitignored);
 
 // ============================================================================
 // SETUP
@@ -76,6 +79,7 @@ beforeEach(() => {
   mockGitignoreExists.mockResolvedValue(false);
   mockIsInGitignore.mockResolvedValue(false);
   mockAddToGitignore.mockResolvedValue(true);
+  mockEnsureGitignored.mockResolvedValue('created');
 });
 
 // ============================================================================
@@ -94,30 +98,12 @@ describe('openloreInit', () => {
       expect(mockCreateOpenSpecStructure).toHaveBeenCalledOnce();
     });
 
-    it('adds .openlore/ to .gitignore when gitignore exists', async () => {
-      mockGitignoreExists.mockResolvedValue(true);
-      mockIsInGitignore.mockResolvedValue(false);
-
-      await openloreInit({ rootPath: ROOT });
-
-      expect(mockAddToGitignore).toHaveBeenCalledWith(ROOT, '.openlore/', expect.any(String));
-    });
-
-    it('skips addToGitignore when .openlore/ already in gitignore', async () => {
-      mockGitignoreExists.mockResolvedValue(true);
-      mockIsInGitignore.mockResolvedValue(true);
-
-      await openloreInit({ rootPath: ROOT });
-
-      expect(mockAddToGitignore).not.toHaveBeenCalled();
-    });
-
-    it('skips addToGitignore when no .gitignore file', async () => {
-      mockGitignoreExists.mockResolvedValue(false);
-
+    it('delegates .openlore/ gitignore handling to ensureGitignored (which creates the file when absent)', async () => {
       await openloreInit({ rootPath: ROOT });
 
-      expect(mockAddToGitignore).not.toHaveBeenCalled();
+      // The create-or-append/skip decision lives in ensureGitignored (covered by its
+      // own tests); init just delegates so a fresh `git init` repo always gets ignored.
+      expect(mockEnsureGitignored).toHaveBeenCalledWith(ROOT, '.openlore/', expect.any(String));
     });
 
     it('skips createOpenSpecStructure when openspec dir already exists', async () => {

src/api/init.test.ts

@@ -19,11 +19,7 @@ import {
   createOpenSpecStructure,
   detectExistingSpecDir,
 } from '../core/services/config-manager.js';
-import {
-  gitignoreExists,
-  isInGitignore,
-  addToGitignore,
-} from '../core/services/gitignore-manager.js';
+import { ensureGitignored } from '../core/services/gitignore-manager.js';
 import type { InitApiOptions, InitResult, ProgressCallback } from './types.js';
 
 function progress(onProgress: ProgressCallback | undefined, step: string, status: 'start' | 'progress' | 'complete' | 'skip', detail?: string): void {
@@ -92,16 +88,11 @@ export async function openloreInit(options: InitApiOptions = {}): Promise<InitRe
     progress(onProgress, 'OpenSpec directory exists', 'skip');
   }
 
-  // Update .gitignore
-  const hasGitignore = await gitignoreExists(rootPath);
-  if (hasGitignore) {
-    const alreadyIgnored = await isInGitignore(rootPath, `${OPENLORE_DIR}/`);
-    if (!alreadyIgnored) {
-      progress(onProgress, 'Updating .gitignore', 'start');
-      await addToGitignore(rootPath, `${OPENLORE_DIR}/`, 'openlore analysis artifacts');
-      progress(onProgress, 'Updating .gitignore', 'complete');
-    }
-  }
+  // Ensure .openlore/ analysis artifacts (multi-MB lance binaries) are ignored,
+  // creating .gitignore when absent so a fresh `git init` repo doesn't leak them.
+  progress(onProgress, 'Updating .gitignore', 'start');
+  const gitignoreResult = await ensureGitignored(rootPath, `${OPENLORE_DIR}/`, 'openlore analysis artifacts');
+  progress(onProgress, 'Updating .gitignore', gitignoreResult === 'present' ? 'skip' : 'complete');
 
   return {
     configPath: OPENLORE_CONFIG_REL_PATH,

src/api/init.ts

@@ -39,6 +39,7 @@ vi.mock('../core/services/gitignore-manager.js', () => ({
   gitignoreExists: vi.fn(),
   isInGitignore: vi.fn(),
   addToGitignore: vi.fn(),
+  ensureGitignored: vi.fn(),
 }));
 
 vi.mock('../core/services/llm-service.js', () => ({
@@ -110,7 +111,7 @@ import { access, stat, readFile } from 'node:fs/promises';
 import { isCacheFresh } from '../core/services/mcp-handlers/utils.js';
 import { detectProjectType, getProjectTypeName } from '../core/services/project-detector.js';
 import { getDefaultConfig, readOpenLoreConfig, writeOpenLoreConfig, openloreConfigExists, openspecDirExists, createOpenSpecStructure } from '../core/services/config-manager.js';
-import { gitignoreExists, isInGitignore, addToGitignore } from '../core/services/gitignore-manager.js';
+import { gitignoreExists, isInGitignore, addToGitignore, ensureGitignored } from '../core/services/gitignore-manager.js';
 import { createLLMService } from '../core/services/llm-service.js';
 import { RepositoryMapper } from '../core/analyzer/repository-mapper.js';
 import { DependencyGraphBuilder } from '../core/analyzer/dependency-graph.js';
@@ -133,6 +134,7 @@ const mockCreateOpenSpecStructure = vi.mocked(createOpenSpecStructure);
 const mockGitignoreExists = vi.mocked(gitignoreExists);
 const mockIsInGitignore = vi.mocked(isInGitignore);
 const mockAddToGitignore = vi.mocked(addToGitignore);
+const mockEnsureGitignored = vi.mocked(ensureGitignored);
 const mockCreateLLMService = vi.mocked(createLLMService);
 const mockIsCacheFresh = vi.mocked(isCacheFresh);
 
@@ -188,6 +190,7 @@ function setupMocks({ configExists = false, analysisRecent = false } = {}) {
   mockGitignoreExists.mockResolvedValue(false);
   mockIsInGitignore.mockResolvedValue(false);
   mockAddToGitignore.mockResolvedValue(true);
+  mockEnsureGitignored.mockResolvedValue('created');
 
   // Analysis mocks
   const mtime = analysisRecent ? RECENT_MTIME : OLD_MTIME;
@@ -254,6 +257,13 @@ describe('openloreRun', () => {
       expect(mockWriteOpenLoreConfig).toHaveBeenCalled();
     });
 
+    it('delegates .openlore/ gitignore handling to ensureGitignored when creating config', async () => {
+      setupMocks({ configExists: false, analysisRecent: true });
+      await openloreRun({ rootPath: ROOT });
+
+      expect(mockEnsureGitignored).toHaveBeenCalledWith(ROOT, '.openlore/', expect.any(String));
+    });
+
     it('skips init when config exists and force=false', async () => {
       setupMocks({ configExists: true, analysisRecent: true });
       const result = await openloreRun({ rootPath: ROOT });

src/api/run.test.ts

@@ -23,11 +23,7 @@ import {
   openspecDirExists,
   createOpenSpecStructure,
 } from '../core/services/config-manager.js';
-import {
-  gitignoreExists,
-  isInGitignore,
-  addToGitignore,
-} from '../core/services/gitignore-manager.js';
+import { ensureGitignored } from '../core/services/gitignore-manager.js';
 import { createLLMService } from '../core/services/llm-service.js';
 import type { LLMService } from '../core/services/llm-service.js';
 import { RepositoryMapper } from '../core/analyzer/repository-mapper.js';
@@ -112,13 +108,10 @@ export async function openloreRun(options: RunApiOptions = {}): Promise<RunResul
       await createOpenSpecStructure(fullOpenspecPath);
     }
 
-    const hasGitignore = await gitignoreExists(rootPath);
-    if (hasGitignore) {
-      const alreadyIgnored = await isInGitignore(rootPath, `${OPENLORE_DIR}/`);
-      if (!alreadyIgnored) {
-        await addToGitignore(rootPath, `${OPENLORE_DIR}/`, 'openlore analysis artifacts');
-      }
-    }
+    // Ensure .openlore/ analysis artifacts (multi-MB lance binaries) are ignored,
+    // creating .gitignore when absent so a fresh `git init` repo doesn't leak them
+    // into git status and diff-based tools.
+    await ensureGitignored(rootPath, `${OPENLORE_DIR}/`, 'openlore analysis artifacts');
 
     initResult = {
       configPath: OPENLORE_CONFIG_REL_PATH,