decision-os-mcp 0.3.2 → 0.5.1

package/AGENTS.md

@@ -0,0 +1,101 @@
+# Decision OS MCP
+
+MCP server for Decision OS — an LLM-native decision tracking and learning system. TypeScript, Node.js 18+, ES modules, `@modelcontextprotocol/sdk`, YAML storage, Zod validation.
+
+## Commands
+
+```bash
+npm install          # Install dependencies
+npm run build        # Compile TypeScript (tsc)
+npm run dev          # Watch mode (tsc --watch)
+npm test             # Run all tests (vitest run)
+npm run test:watch   # Watch tests (vitest)
+npm start            # Run server (set DECISION_OS_PATH first)
+```
+
+Run `npm run build && npm test` before committing. All tests must pass.
+
+## Architecture
+
+```
+src/
+├── index.ts                       # Public API surface (re-exports)
+├── core/
+│   ├── schemas.ts                 # Zod schemas for all types (Decision OS + Observer)
+│   ├── storage.ts                 # Single-scope storage engine (YAML read/write)
+│   ├── hierarchical-storage.ts    # Multi-scope storage (PROJECT + GLOBAL cascading)
+│   └── services.ts                # Thin service layer over storage (used by observer)
+├── observer/
+│   ├── engine.ts                  # observe(state, newTurns) → events + actions
+│   ├── state.ts                   # ObserverMetaState creation + event reducer
+│   ├── projections.ts             # Map observer actions → Decision OS core calls + feedback
+│   ├── orchestrator.ts            # Full cycle: detect → project → feedback → persist
+│   └── persistence.ts             # Save/load observer sessions as JSON
+├── integrations/
+│   └── litellm/
+│       └── callback-handler.ts    # LiteLLM callback → observer orchestrator
+└── server/
+    └── index.ts                   # MCP server entry, tool definitions, request handler
+test/
+├── storage.test.ts
+├── hierarchical-storage.test.ts
+└── observer.test.ts
+templates/                         # Setup templates for consumers
+```
+
+### Core
+- Entry point registers 13 MCP tools via `@modelcontextprotocol/sdk`
+- All tool input validation uses Zod schemas from `core/schemas.ts`
+- Storage is YAML-based, file-system only, no network calls
+- Hierarchical storage merges `~/.decision-os/` (GLOBAL) with project-level `.decision-os/` (PROJECT)
+- PROJECT scope wins over GLOBAL on conflicts
+- `DecisionOSService` provides a programmatic API over storage (no MCP dependency)
+
+### Observer
+- Session-local meta-state tracks task stage, case lifecycle, and pressure signals
+- `observe()` processes new conversation turns incrementally (not full conversation)
+- V1 uses heuristic detection for 3 transitions: TASK_START, PRESSURE_DETECTED, COMPLETION_SIGNAL
+- `projectActions()` maps observer actions into Decision OS core calls via the service layer
+- `toFeedbackEvents()` converts projection results back into state events (CASE_OPENED, CASE_CLOSED)
+- `runCycle()` composes the full loop: detect → project → feedback → state update
+- `ObserverOrchestrator` wraps `runCycle()` with persistence load/save
+- Observer state persists under `.decision-os/observer/sessions/` as JSON
+- **Core never imports from observer.** Observer calls core through the service layer.
+
+### LiteLLM Integration
+- `LiteLLMCallbackHandler` converts LiteLLM callback events into ObserverTurns
+- Normalizes roles (user/assistant/tool), skips system messages
+- Feeds turns through the ObserverOrchestrator on each successful callback
+
+## Conventions
+
+- ES modules (`"type": "module"` in package.json) — use `.js` extensions in imports
+- Strict TypeScript (`strict: true`, target ES2022, NodeNext module resolution) — no `any`, no `@ts-ignore`
+- Tool definitions in `TOOLS` array follow MCP SDK `Tool` type with `annotations`
+- All tool handlers live in the `switch` block inside `CallToolRequestSchema` handler
+- Zod for all input validation; errors formatted as `path: message`
+- Error handling: `ZodError` → formatted validation message; `Error` → `.message`; else → `String(error)`
+- Regret values accept both number (0-3) and string ("0"-"3") via `z.preprocess`
+- Foundation IDs: `F-NNNN` (project), `GF-NNNN` (global)
+- Pressure event IDs: `PE-NNNN`
+- Case IDs: `NNNN-slug-title`
+
+## Testing
+
+- Tests use Vitest with temp directories for isolation
+- Test files: `test/storage.test.ts`, `test/hierarchical-storage.test.ts`, `test/observer.test.ts`
+
+## Adding a New Tool
+
+1. Add input schema to `core/schemas.ts`
+2. Add `Tool` definition to `TOOLS` array in `server/index.ts` (include `annotations`)
+3. Add handler case to the `switch` block in the `CallToolRequestSchema` handler
+4. Add tests in `test/`
+5. Update tool table in `README.md`
+
+## PR Guidelines
+
+- Title format: descriptive summary of the change
+- Run `npm run build && npm test` before opening a PR
+- Include test coverage for new tools or storage logic
+- Update `README.md` tool table if adding/removing tools

package/README.md

@@ -32,7 +32,9 @@ cp -r templates/.decision-os /path/to/your-project/
 
 Edit `config.yaml` with your project name.
 
-### 3. Configure Cursor
+### 3. Configure Your Agent
+
+#### Cursor
 
 Add to your project's `.cursor/mcp.json`:
 
@@ -56,6 +58,35 @@ Copy the Cursor rules template:
 cp templates/.cursor/rules/decision-os.mdc /path/to/your-project/.cursor/rules/
 ```
 
+#### Claude Code / Claude Desktop
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "decision-os": {
+      "command": "npx",
+      "args": ["-y", "decision-os-mcp"],
+      "env": {
+        "DECISION_OS_PATH": "/absolute/path/to/your-project/.decision-os"
+      }
+    }
+  }
+}
+```
+
+Copy the agent instructions template (includes a `.claude/rules/` symlink to AGENTS.md):
+
+```bash
+cp templates/AGENTS.md /path/to/your-project/
+cp -R templates/.claude /path/to/your-project/
+```
+
+> **Note:** Claude Desktop requires absolute paths in `DECISION_OS_PATH` (no `${workspaceFolder}`).
+
+[AGENTS.md](https://agents.md) is an open standard supported by 20+ coding agents including OpenAI Codex, Google Jules, Claude Code, Cursor, Aider, Zed, Warp, VS Code, and more. The `.claude/rules/` symlink lets Claude Code pick it up automatically too — one file, every agent.
+
 ## Tools
 
 | Tool | Description |
@@ -178,10 +209,14 @@ your-project/
 │   │       └── ...
 │   └── defaults/
 │       └── foundations.yaml  # F-prefixed project learnings
-├── .cursor/
+├── .cursor/                  # Cursor setup
 │   ├── mcp.json              # MCP server config
 │   └── rules/
-│       └── decision-os.mdc   # LLM instructions
+│       └── decision-os.mdc   # LLM instructions (Cursor format)
+├── .claude/                  # Claude Code setup
+│   └── rules/
+│       └── decision-os.md    # -> symlink to ../../AGENTS.md
+├── AGENTS.md                 # Agent instructions (Claude Code, Codex, Jules, etc.)
 └── src/
 ```
 

package/dist/core/hierarchical-storage.d.ts

@@ -0,0 +1,128 @@
+import { DecisionOSStorage } from "./storage.js";
+import type { Foundation, Case, PressureEvent, ProjectConfig } from "./schemas.js";
+/**
+ * Extended Foundation type with source layer information for conflict visibility
+ */
+export interface FoundationWithSource extends Foundation {
+    _source_layer: string;
+    _source_scope: "GLOBAL" | "PROJECT";
+}
+/**
+ * Conflict information when foundations overlap across scopes
+ */
+export interface FoundationConflict {
+    title: string;
+    global_foundation: Foundation;
+    project_foundation: Foundation;
+    recommendation: string;
+}
+/**
+ * Hierarchical storage layer for Decision OS.
+ * Manages GLOBAL → PROJECT cascading scope model.
+ *
+ * Resolution order: PROJECT wins over GLOBAL for conflicts.
+ * Global foundations are recommendations, not rules.
+ */
+export declare class HierarchicalDecisionOSStorage {
+    private layers;
+    private projectLayer;
+    private globalLayer;
+    constructor(workspacePath: string);
+    /**
+     * Discover all .decision-os layers by walking up from workspace path.
+     * Returns [nearest, ..., global] order.
+     */
+    private discoverLayers;
+    /**
+     * Initialize all layers
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get the base path of the project layer
+     */
+    getProjectPath(): string;
+    /**
+     * Get the base path of the global layer (if exists)
+     */
+    getGlobalPath(): string | null;
+    getConfig(): Promise<ProjectConfig>;
+    updateConfig(config: Partial<ProjectConfig>): Promise<void>;
+    getActiveCase(): string | null;
+    setActiveCase(caseId: string | null): Promise<void>;
+    listCases(): Promise<Case[]>;
+    getCase(caseId: string): Promise<Case | null>;
+    createCase(input: Parameters<DecisionOSStorage["createCase"]>[0]): Promise<Case>;
+    updateCase(caseId: string, updates: Partial<Case>): Promise<Case>;
+    closeCase(caseId: string, outcome: Parameters<DecisionOSStorage["closeCase"]>[1]): Promise<{
+        case: Case;
+        forgotten: boolean;
+    }>;
+    getPressureEvents(caseId: string): Promise<PressureEvent[]>;
+    logPressure(input: Parameters<DecisionOSStorage["logPressure"]>[0]): Promise<PressureEvent>;
+    searchPressures(query: string): Promise<PressureEvent[]>;
+    /**
+     * Get merged foundations from all layers.
+     * Project foundations take precedence over global on title conflict.
+     * Returns foundations annotated with source information.
+     */
+    getFoundations(filters?: {
+        context_tags?: string[];
+        min_confidence?: number;
+    }): Promise<FoundationWithSource[]>;
+    /**
+     * Detect conflicts where project and global have foundations with same title
+     * or overlapping context_tags.
+     */
+    detectConflicts(): Promise<FoundationConflict[]>;
+    /**
+     * Promote pressure events to a foundation in the specified scope.
+     */
+    promoteToFoundation(input: {
+        title: string;
+        default_behavior: string;
+        context_tags: string[];
+        counter_contexts?: string[];
+        source_pressures: string[];
+        exit_criteria?: string;
+        scope?: "GLOBAL" | "PROJECT";
+        origin_project?: string;
+    }): Promise<Foundation>;
+    /**
+     * Elevate a project foundation to global scope.
+     * Creates a new foundation in global with GF- prefix.
+     */
+    elevateFoundation(input: {
+        foundation_id: string;
+        reason?: string;
+    }): Promise<Foundation>;
+    /**
+     * Cross-validate that a global foundation applies in the current project.
+     * Increases confidence and adds project to validated_in list.
+     */
+    validateFoundation(input: {
+        foundation_id: string;
+        validation_notes?: string;
+    }): Promise<Foundation>;
+    suggestReview(): ReturnType<DecisionOSStorage["suggestReview"]>;
+    checkPolicy(signals: Parameters<DecisionOSStorage["checkPolicy"]>[0]): ReturnType<DecisionOSStorage["checkPolicy"]>;
+    getContext(): Promise<{
+        project: string;
+        active_case: Case | null;
+        recent_pressures: PressureEvent[];
+        relevant_foundations: FoundationWithSource[];
+        conflicts: FoundationConflict[];
+        layers: string[];
+    }>;
+    /**
+     * Rank foundations by relevance to the active case.
+     * Foundations matching the case's affected_surface or touched_areas
+     * are marked "directly_relevant" and sorted first.
+     */
+    private rankFoundationsByRelevance;
+}
+/**
+ * Create a hierarchical storage instance, discovering layers from workspace path.
+ * Falls back to creating project-only storage if no hierarchy found.
+ */
+export declare function createHierarchicalStorage(workspacePath: string): HierarchicalDecisionOSStorage;
+//# sourceMappingURL=hierarchical-storage.d.ts.map

package/dist/core/hierarchical-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hierarchical-storage.d.ts","sourceRoot":"","sources":["../../src/core/hierarchical-storage.ts"],"names":[],"mappings":"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"}

package/dist/core/hierarchical-storage.js

@@ -0,0 +1,368 @@
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+import { DecisionOSStorage } from "./storage.js";
+/**
+ * Hierarchical storage layer for Decision OS.
+ * Manages GLOBAL → PROJECT cascading scope model.
+ *
+ * Resolution order: PROJECT wins over GLOBAL for conflicts.
+ * Global foundations are recommendations, not rules.
+ */
+export class HierarchicalDecisionOSStorage {
+    layers = []; // [project, global] - nearest first
+    projectLayer;
+    globalLayer = null;
+    constructor(workspacePath) {
+        this.layers = this.discoverLayers(workspacePath);
+        if (this.layers.length === 0) {
+            throw new Error(`No .decision-os found starting from ${workspacePath}`);
+        }
+        this.projectLayer = this.layers[0];
+        this.globalLayer = this.layers.length > 1 ? this.layers[this.layers.length - 1] : null;
+    }
+    /**
+     * Discover all .decision-os layers by walking up from workspace path.
+     * Returns [nearest, ..., global] order.
+     */
+    discoverLayers(startPath) {
+        const layers = [];
+        const seenPaths = new Set();
+        // First, check if startPath itself is or contains .decision-os
+        let currentPath = startPath;
+        // If startPath ends with .decision-os, use its parent as start
+        if (currentPath.endsWith(".decision-os")) {
+            currentPath = dirname(currentPath);
+        }
+        // Walk up directory tree looking for .decision-os folders
+        while (currentPath !== "/" && currentPath !== dirname(currentPath)) {
+            const dosPath = join(currentPath, ".decision-os");
+            if (existsSync(dosPath) && !seenPaths.has(dosPath)) {
+                seenPaths.add(dosPath);
+                layers.push(new DecisionOSStorage(dosPath));
+            }
+            currentPath = dirname(currentPath);
+        }
+        // Always include global ~/.decision-os if it exists
+        const globalPath = join(homedir(), ".decision-os");
+        if (existsSync(globalPath) && !seenPaths.has(globalPath)) {
+            seenPaths.add(globalPath);
+            layers.push(new DecisionOSStorage(globalPath));
+        }
+        return layers;
+    }
+    /**
+     * Initialize all layers
+     */
+    async initialize() {
+        for (const layer of this.layers) {
+            await layer.initialize();
+        }
+    }
+    /**
+     * Get the base path of the project layer
+     */
+    getProjectPath() {
+        return this.projectLayer.basePath;
+    }
+    /**
+     * Get the base path of the global layer (if exists)
+     */
+    getGlobalPath() {
+        return this.globalLayer ? this.globalLayer.basePath : null;
+    }
+    // ============================================================================
+    // CONFIG
+    // ============================================================================
+    async getConfig() {
+        return this.projectLayer.getConfig();
+    }
+    async updateConfig(config) {
+        return this.projectLayer.updateConfig(config);
+    }
+    // ============================================================================
+    // ACTIVE CASE (project-local)
+    // ============================================================================
+    getActiveCase() {
+        return this.projectLayer.getActiveCase();
+    }
+    async setActiveCase(caseId) {
+        await this.projectLayer.setActiveCase(caseId);
+    }
+    // ============================================================================
+    // CASES (project-local)
+    // ============================================================================
+    async listCases() {
+        return this.projectLayer.listCases();
+    }
+    async getCase(caseId) {
+        return this.projectLayer.getCase(caseId);
+    }
+    async createCase(input) {
+        return this.projectLayer.createCase(input);
+    }
+    async updateCase(caseId, updates) {
+        return this.projectLayer.updateCase(caseId, updates);
+    }
+    async closeCase(caseId, outcome) {
+        return this.projectLayer.closeCase(caseId, outcome);
+    }
+    // ============================================================================
+    // PRESSURE EVENTS (project-local)
+    // ============================================================================
+    async getPressureEvents(caseId) {
+        return this.projectLayer.getPressureEvents(caseId);
+    }
+    async logPressure(input) {
+        return this.projectLayer.logPressure(input);
+    }
+    async searchPressures(query) {
+        // Search only in project layer (per user's answer to Q3)
+        return this.projectLayer.searchPressures(query);
+    }
+    // ============================================================================
+    // FOUNDATIONS (merged across layers)
+    // ============================================================================
+    /**
+     * Get merged foundations from all layers.
+     * Project foundations take precedence over global on title conflict.
+     * Returns foundations annotated with source information.
+     */
+    async getFoundations(filters) {
+        const seen = new Map(); // Track by title
+        const merged = [];
+        for (const layer of this.layers) {
+            const foundations = await layer.getFoundations(filters);
+            const layerPath = layer.basePath;
+            const isGlobal = layerPath === join(homedir(), ".decision-os");
+            for (const f of foundations) {
+                const annotated = {
+                    ...f,
+                    _source_layer: layerPath,
+                    _source_scope: isGlobal ? "GLOBAL" : "PROJECT",
+                };
+                if (!seen.has(f.title)) {
+                    // First occurrence (nearest layer) wins
+                    seen.set(f.title, annotated);
+                    merged.push(annotated);
+                }
+                // If already seen, project wins over global (first layer is project)
+            }
+        }
+        return merged;
+    }
+    /**
+     * Detect conflicts where project and global have foundations with same title
+     * or overlapping context_tags.
+     */
+    async detectConflicts() {
+        if (!this.globalLayer)
+            return [];
+        const projectFoundations = await this.projectLayer.getFoundations();
+        const globalFoundations = await this.globalLayer.getFoundations();
+        const conflicts = [];
+        for (const pf of projectFoundations) {
+            // Check for title match
+            const titleMatch = globalFoundations.find((gf) => gf.title.toLowerCase() === pf.title.toLowerCase());
+            if (titleMatch) {
+                conflicts.push({
+                    title: pf.title,
+                    global_foundation: titleMatch,
+                    project_foundation: pf,
+                    recommendation: `Project foundation "${pf.title}" shadows global foundation. ` +
+                        `Project version will be used. Consider if global should be updated or removed.`,
+                });
+                continue;
+            }
+            // Check for overlapping context_tags
+            for (const gf of globalFoundations) {
+                const overlappingTags = pf.context_tags.filter((t) => gf.context_tags.includes(t));
+                if (overlappingTags.length > 0 && pf.title !== gf.title) {
+                    // Different titles but same context - potential friction
+                    const pfBehavior = pf.default_behavior.toLowerCase();
+                    const gfBehavior = gf.default_behavior.toLowerCase();
+                    // Simple heuristic: if behaviors seem contradictory
+                    const contradictory = (pfBehavior.includes("always") && gfBehavior.includes("never")) ||
+                        (pfBehavior.includes("never") && gfBehavior.includes("always")) ||
+                        (pfBehavior.includes("prefer") && gfBehavior.includes("avoid"));
+                    if (contradictory) {
+                        conflicts.push({
+                            title: `${pf.title} vs ${gf.title}`,
+                            global_foundation: gf,
+                            project_foundation: pf,
+                            recommendation: `Potential conflict: Both apply to [${overlappingTags.join(", ")}] ` +
+                                `but may have contradictory guidance. Review and clarify.`,
+                        });
+                    }
+                }
+            }
+        }
+        return conflicts;
+    }
+    /**
+     * Promote pressure events to a foundation in the specified scope.
+     */
+    async promoteToFoundation(input) {
+        const scope = input.scope ?? "PROJECT";
+        const config = await this.projectLayer.getConfig();
+        const originProject = input.origin_project ?? config.project;
+        const targetLayer = scope === "GLOBAL" && this.globalLayer
+            ? this.globalLayer
+            : this.projectLayer;
+        // Create foundation with scope and origin metadata
+        const foundation = await targetLayer.promoteToFoundation({
+            title: input.title,
+            default_behavior: input.default_behavior,
+            context_tags: input.context_tags,
+            counter_contexts: input.counter_contexts,
+            source_pressures: input.source_pressures,
+            exit_criteria: input.exit_criteria,
+            scope,
+            origin_project: originProject,
+        });
+        return foundation;
+    }
+    /**
+     * Elevate a project foundation to global scope.
+     * Creates a new foundation in global with GF- prefix.
+     */
+    async elevateFoundation(input) {
+        if (!this.globalLayer) {
+            throw new Error("No global .decision-os found at ~/.decision-os. " +
+                "Create it first with: mkdir -p ~/.decision-os/defaults && " +
+                "echo 'foundations: []' > ~/.decision-os/defaults/foundations.yaml");
+        }
+        // Find the foundation in project layer
+        const projectFoundations = await this.projectLayer.getFoundations();
+        const foundation = projectFoundations.find((f) => f.id === input.foundation_id);
+        if (!foundation) {
+            throw new Error(`Foundation not found in project: ${input.foundation_id}`);
+        }
+        const config = await this.projectLayer.getConfig();
+        // Create in global with GF- prefix (scope: GLOBAL triggers the prefix)
+        const globalFoundation = await this.globalLayer.promoteToFoundation({
+            title: foundation.title,
+            default_behavior: foundation.default_behavior +
+                (input.reason ? `\n\n[Elevated from ${config.project}: ${input.reason}]` : ""),
+            context_tags: foundation.context_tags,
+            counter_contexts: foundation.counter_contexts,
+            source_pressures: foundation.source_pressures,
+            exit_criteria: foundation.exit_criteria,
+            scope: "GLOBAL",
+            origin_project: config.project,
+        });
+        // Retire the project copy — knowledge now lives in global
+        await this.projectLayer.removeFoundation(input.foundation_id);
+        console.error(`Retired project foundation ${input.foundation_id} — elevated to ${globalFoundation.id}`);
+        return globalFoundation;
+    }
+    /**
+     * Cross-validate that a global foundation applies in the current project.
+     * Increases confidence and adds project to validated_in list.
+     */
+    async validateFoundation(input) {
+        // Find the foundation across all layers
+        const allFoundations = await this.getFoundations();
+        const foundation = allFoundations.find((f) => f.id === input.foundation_id);
+        if (!foundation) {
+            throw new Error(`Foundation not found: ${input.foundation_id}`);
+        }
+        const config = await this.projectLayer.getConfig();
+        // Update validated_in
+        const validatedIn = [...(foundation.validated_in ?? [])];
+        if (!validatedIn.includes(config.project)) {
+            validatedIn.push(config.project);
+        }
+        // Increase confidence if validated in multiple projects (3+ validations = confidence boost)
+        let newConfidence = foundation.confidence;
+        if (validatedIn.length >= 3 && newConfidence < 3) {
+            newConfidence = Math.min(3, newConfidence + 1);
+        }
+        // Update the foundation in its source layer
+        const targetLayer = foundation._source_scope === "GLOBAL" && this.globalLayer
+            ? this.globalLayer
+            : this.projectLayer;
+        // Use the updateFoundation method to persist
+        const updatedFoundation = await targetLayer.updateFoundation(input.foundation_id, {
+            validated_in: validatedIn,
+            confidence: newConfidence,
+        });
+        return updatedFoundation;
+    }
+    // ============================================================================
+    // SUGGEST REVIEW (delegates to project layer)
+    // ============================================================================
+    async suggestReview() {
+        return this.projectLayer.suggestReview();
+    }
+    // ============================================================================
+    // POLICY CHECK (delegates to project layer)
+    // ============================================================================
+    checkPolicy(signals) {
+        return this.projectLayer.checkPolicy(signals);
+    }
+    // ============================================================================
+    // CONTEXT (merged)
+    // ============================================================================
+    async getContext() {
+        const config = await this.getConfig();
+        const activeCase = this.getActiveCase()
+            ? await this.getCase(this.getActiveCase())
+            : null;
+        let recentPressures = [];
+        if (activeCase) {
+            recentPressures = await this.getPressureEvents(activeCase.id);
+        }
+        const allFoundations = await this.getFoundations();
+        const active = allFoundations.filter((f) => f.confidence >= 1);
+        const conflicts = await this.detectConflicts();
+        // Rank foundations by relevance to active case
+        const ranked = this.rankFoundationsByRelevance(active, activeCase);
+        return {
+            project: config.project,
+            active_case: activeCase,
+            recent_pressures: recentPressures.slice(-5),
+            relevant_foundations: ranked,
+            conflicts,
+            layers: this.layers.map((l) => l["basePath"]),
+        };
+    }
+    /**
+     * Rank foundations by relevance to the active case.
+     * Foundations matching the case's affected_surface or touched_areas
+     * are marked "directly_relevant" and sorted first.
+     */
+    rankFoundationsByRelevance(foundations, activeCase) {
+        if (!activeCase)
+            return foundations;
+        // Collect case context tags from signals and touched_areas
+        const caseTags = new Set();
+        const surfaces = activeCase.signals?.context?.affected_surface ?? [];
+        for (const s of surfaces)
+            caseTags.add(s.toUpperCase());
+        const areas = activeCase.context?.touched_areas ?? [];
+        for (const a of areas)
+            caseTags.add(a.toUpperCase());
+        if (caseTags.size === 0)
+            return foundations;
+        // Score each foundation by tag overlap
+        const scored = foundations.map((f) => {
+            const overlap = f.context_tags.filter((t) => caseTags.has(t.toUpperCase())).length;
+            return { foundation: f, overlap };
+        });
+        // Sort: directly relevant first, then general
+        scored.sort((a, b) => b.overlap - a.overlap);
+        return scored.map(({ foundation, overlap }) => ({
+            ...foundation,
+            _relevance: overlap > 0 ? "directly_relevant" : "general",
+        }));
+    }
+}
+/**
+ * Create a hierarchical storage instance, discovering layers from workspace path.
+ * Falls back to creating project-only storage if no hierarchy found.
+ */
+export function createHierarchicalStorage(workspacePath) {
+    return new HierarchicalDecisionOSStorage(workspacePath);
+}
+//# sourceMappingURL=hierarchical-storage.js.map