tribunal-kit 7.0.0 → 8.0.0

package/.agent/history/snapshots/test__unit__production_readiness_evidence.test.js.json

@@ -0,0 +1,21 @@
+{
+  "file": "test/unit/production_readiness_evidence.test.js",
+  "riskScore": "Low",
+  "blastRadius": 0,
+  "imports": {
+    "fs": [],
+    "path": [],
+    "child_process": [],
+    "../../.agent/scripts/impact_classifier": [],
+    "../../.agent/scripts/socratic_gate_policy": [],
+    "../../.agent/scripts/token_budget_broker": [],
+    "../../.agent/scripts/integrity_manifest": [],
+    "../../bin/mcp-server": [
+      "handleRequest",
+      "stripBoilerplate",
+      "runTribunalAudit"
+    ]
+  },
+  "dependents": [],
+  "content": "/**\n * production_readiness_evidence.test.js\n * ══════════════════════════════════════════════════════════════════\n * Empirical evidence that the Tribunal-Kit repository state is:\n *   1. SAFE — input sanitization, path bounds, secret hygiene\n *   2. DETERMINISTIC — repeatable tier classification and budgets\n *   3. FAILURE TOLERANT — JS fallback, graceful degradation\n *   4. OBSERVABLE — structured error outputs, exit codes, audit logs\n *   5. REPRODUCIBLE — stable manifest hashes, version metadata\n *   6. PRODUCTION RELEASE SUITABLE — no phantom references, no count drift\n *\n * Zero external dependencies. Tests use only Node.js stdlib + Jest.\n */\n\n'use strict';\n\nconst fs = require('fs');\nconst path = require('path');\nconst { execFileSync } = require('child_process');\n\nconst fail = (msg = 'Test failed') => {\n  throw new Error(msg);\n};\n\nconst ROOT = path.resolve(__dirname, '../..');\n\n// ─── Module Under Test: Impact Classifier ────────────────────────────────────\nconst { classifyImpact } = require('../../.agent/scripts/impact_classifier');\n\n// ─── Module Under Test: Socratic Gate Policy ─────────────────────────────────\nconst { evaluateSocraticGate } = require('../../.agent/scripts/socratic_gate_policy');\n\n// ─── Module Under Test: Token Budget Broker ──────────────────────────────────\nconst { getTokenBudget, TIER_TOKEN_LIMITS } = require('../../.agent/scripts/token_budget_broker');\n\n// ─── Module Under Test: Integrity Manifest ───────────────────────────────────\nconst {\n  generateManifest,\n  parseFrontmatter,\n  crawlAgents: _crawlAgents,\n  crawlSkills: _crawlSkills,\n  crawlScripts: _crawlScripts,\n  crawlWorkflows: _crawlWorkflows,\n} = require('../../.agent/scripts/integrity_manifest');\n\n// ─── Module Under Test: MCP Server ───────────────────────────────────────────\nprocess.env.NODE_ENV = 'test';\nconst { handleRequest, stripBoilerplate } = require('../../bin/mcp-server');\n\n// ─────────────────────────────────────────────────────────────────────────────\n// SECTION 1: SAFETY\n// ─────────────────────────────────────────────────────────────────────────────\n\ndescribe('SAFETY: Input Sanitization & Boundary Enforcement', () => {\n  describe('Impact Classifier — malformed inputs', () => {\n    test('handles null opts gracefully', async () => {\n      const result = classifyImpact(null);\n      expect(result).toHaveProperty('tier');\n      expect(typeof result.tier).toBe('number');\n      expect(result.tier).toBeGreaterThanOrEqual(0);\n      expect(result.tier).toBeLessThanOrEqual(3);\n    });\n\n    test('handles undefined opts gracefully', async () => {\n      const result = classifyImpact(undefined);\n      expect(result).toHaveProperty('tier');\n      expect(typeof result.score).toBe('number');\n    });\n\n    test('handles empty object gracefully', async () => {\n      const result = classifyImpact({});\n      expect(result).toHaveProperty('tier');\n      expect(result).toHaveProperty('score');\n      expect(result).toHaveProperty('maxReviewers');\n      expect(result).toHaveProperty('requireGate');\n      expect(result).toHaveProperty('reasoning');\n      expect(result).toHaveProperty('fastPass');\n    });\n\n    test('filters non-string entries from files array', async () => {\n      const result = classifyImpact({\n        files: [null, undefined, 42, '', 'valid.css', { name: 'bad' }],\n        task: 'fix style',\n        lineCount: 2,\n      });\n      expect(result).toHaveProperty('tier');\n      // Only \"valid.css\" should be considered\n      expect(result.tier).toBe(0); // CSS file, small edit => Tier 0\n    });\n\n    test('handles numeric task gracefully (type coercion safety)', async () => {\n      const result = classifyImpact({ task: 12345, files: [] });\n      expect(result).toHaveProperty('tier');\n      // Numeric task should be treated as empty string, not crash\n    });\n\n    test('handles negative lineCount gracefully', async () => {\n      const result = classifyImpact({ lineCount: -10 });\n      expect(result).toHaveProperty('tier');\n      expect(result.tier).toBeGreaterThanOrEqual(0);\n    });\n\n    test('handles Infinity lineCount gracefully', async () => {\n      const result = classifyImpact({ lineCount: Infinity });\n      expect(result).toHaveProperty('tier');\n    });\n\n    test('handles NaN lineCount gracefully', async () => {\n      const result = classifyImpact({ lineCount: NaN });\n      expect(result).toHaveProperty('tier');\n    });\n  });\n\n  describe('Token Budget Broker — boundary inputs', () => {\n    test('handles negative tier by clamping to 0', async () => {\n      const result = getTokenBudget(-5);\n      expect(result.tier).toBe(0);\n      expect(result.maxTokens).toBe(0);\n    });\n\n    test('handles tier > 3 by clamping to 3', async () => {\n      const result = getTokenBudget(99);\n      expect(result.tier).toBe(3);\n      expect(result.maxTokens).toBe(32000);\n    });\n\n    test('handles NaN tier by defaulting to tier 1', async () => {\n      const result = getTokenBudget(NaN);\n      expect(result.tier).toBe(1);\n      expect(result.maxTokens).toBe(2000);\n    });\n\n    test('handles string tier by defaulting to tier 1', async () => {\n      const result = getTokenBudget('invalid');\n      expect(result.tier).toBe(1);\n      expect(result.maxTokens).toBe(2000);\n    });\n\n    test('handles undefined tier by defaulting to tier 1', async () => {\n      const result = getTokenBudget(undefined);\n      expect(result.tier).toBe(1);\n      expect(result.maxTokens).toBe(2000);\n    });\n\n    test('rounds fractional tiers to nearest integer', async () => {\n      const result = getTokenBudget(1.7);\n      expect(result.tier).toBe(2);\n      expect(result.maxTokens).toBe(8000);\n    });\n  });\n\n  describe('MCP Server — argument validation', () => {\n    test('rejects tools/call with missing params.name', async () => {\n      const req = { jsonrpc: '2.0', id: 1, method: 'tools/call', params: {} };\n      await expect(handleRequest(req)).rejects.toThrow();\n    });\n\n    test('rejects unknown tool name with -32601', async () => {\n      const req = {\n        jsonrpc: '2.0',\n        id: 1,\n        method: 'tools/call',\n        params: { name: 'nonexistent_tool_xyz' },\n      };\n      try {\n        await handleRequest(req);\n        fail('Should have thrown');\n      } catch (e) {\n        expect(e.code).toBe(-32601);\n      }\n    });\n\n    test('rejects search_case_law with non-string query', async () => {\n      const req = {\n        jsonrpc: '2.0',\n        id: 1,\n        method: 'tools/call',\n        params: { name: 'search_case_law', arguments: { query: 123 } },\n      };\n      try {\n        await handleRequest(req);\n        fail('Should have thrown');\n      } catch (e) {\n        expect(e.code).toBe(-32602);\n      }\n    });\n\n    test('rejects get_tribunal_agent with non-string name', async () => {\n      const req = {\n        jsonrpc: '2.0',\n        id: 1,\n        method: 'tools/call',\n        params: { name: 'get_tribunal_agent', arguments: { name: 42 } },\n      };\n      try {\n        await handleRequest(req);\n        fail('Should have thrown');\n      } catch (e) {\n        expect(e.code).toBe(-32602);\n      }\n    });\n\n    test('rejects get_tribunal_skill with non-string name', async () => {\n      const req = {\n        jsonrpc: '2.0',\n        id: 1,\n        method: 'tools/call',\n        params: { name: 'get_tribunal_skill', arguments: { name: null } },\n      };\n      try {\n        await handleRequest(req);\n        fail('Should have thrown');\n      } catch (e) {\n        expect(e.code).toBe(-32602);\n      }\n    });\n\n    test('rejects store_memory with invalid type', async () => {\n      const req = {\n        jsonrpc: '2.0',\n        id: 1,\n        method: 'tools/call',\n        params: { name: 'store_memory', arguments: { type: 'invalid_type', content: 'test' } },\n      };\n      try {\n        await handleRequest(req);\n        fail('Should have thrown');\n      } catch (e) {\n        expect(e.code).toBe(-32602);\n      }\n    });\n  });\n\n  describe('MCP Server — path traversal defense', () => {\n    test('get_tribunal_agent sanitizes path traversal attempts', async () => {\n      const req = {\n        jsonrpc: '2.0',\n        id: 1,\n        method: 'tools/call',\n        params: { name: 'get_tribunal_agent', arguments: { name: '../../etc/passwd' } },\n      };\n      // Should not throw a path traversal error — path.basename strips traversal\n      // Should return \"not found\" because \"passwd\" is not an agent\n      const result = await handleRequest(req);\n      expect(result.content[0].text).toContain('not found');\n    });\n\n    test('get_tribunal_skill sanitizes path traversal attempts', async () => {\n      const req = {\n        jsonrpc: '2.0',\n        id: 1,\n        method: 'tools/call',\n        params: { name: 'get_tribunal_skill', arguments: { name: '../../../etc/shadow' } },\n      };\n      const result = await handleRequest(req);\n      expect(result.content[0].text).toContain('not found');\n    });\n  });\n\n  describe('Socratic Gate — flag override safety', () => {\n    test('only recognized flags bypass the gate', async () => {\n      // Unrecognized flag should NOT bypass\n      const result = evaluateSocraticGate({ tier: 3, flags: { randomFlag: true } });\n      expect(result.shouldBlock).toBe(true);\n    });\n\n    test('no-gate flag bypasses even Tier 3', async () => {\n      const result = evaluateSocraticGate({ tier: 3, flags: { 'no-gate': true } });\n      expect(result.shouldBlock).toBe(false);\n    });\n  });\n});\n\n// ─────────────────────────────────────────────────────────────────────────────\n// SECTION 2: DETERMINISM\n// ─────────────────────────────────────────────────────────────────────────────\n\ndescribe('DETERMINISM: Repeatable Classification & Budget Allocation', () => {\n  describe('Impact Classifier — deterministic tier assignment', () => {\n    const DETERMINISTIC_CASES = [\n      {\n        label: 'CSS typo fix → Tier 0',\n        input: { files: ['src/button.css'], task: 'fix typo in comment', lineCount: 3 },\n        expectedTier: 0,\n      },\n      {\n        label: 'Single component logic → Tier 1',\n        input: { files: ['src/Header.tsx'], task: 'update toggle', lineCount: 15 },\n        expectedTier: 1,\n      },\n      {\n        label: 'Auth file → Tier 3 (critical path)',\n        input: { files: ['src/auth/jwt.ts'], task: 'update token check', lineCount: 8 },\n        expectedTier: 3,\n      },\n      {\n        label: 'Schema migration → Tier 3 (critical path)',\n        input: { files: ['db/schema.prisma'], task: 'add user column', lineCount: 5 },\n        expectedTier: 3,\n      },\n      {\n        label: 'Multiple large files → Tier 2+',\n        input: {\n          files: ['src/api/routes.ts', 'src/api/handlers.ts'],\n          task: 'refactor API',\n          lineCount: 120,\n        },\n        expectedTier: 3, // refactor + large diff\n      },\n    ];\n\n    test.each(DETERMINISTIC_CASES)('$label', ({ input, expectedTier }) => {\n      // Run 10 times to prove determinism\n      for (let i = 0; i < 10; i++) {\n        const result = classifyImpact(input);\n        expect(result.tier).toBe(expectedTier);\n      }\n    });\n\n    test('score is always a finite number between 0 and 1', async () => {\n      const cases = [\n        {},\n        { files: ['a.css'], task: 'typo', lineCount: 1 },\n        { files: ['auth.ts'], task: 'security refactor migration', lineCount: 500 },\n      ];\n      for (const input of cases) {\n        const result = classifyImpact(input);\n        expect(Number.isFinite(result.score)).toBe(true);\n        expect(result.score).toBeGreaterThanOrEqual(0);\n        expect(result.score).toBeLessThanOrEqual(1);\n      }\n    });\n\n    test('fastPass is true if and only if tier === 0', async () => {\n      const tier0 = classifyImpact({ files: ['readme.md'], task: 'fix docs typo', lineCount: 1 });\n      expect(tier0.fastPass).toBe(tier0.tier === 0);\n\n      const tier3 = classifyImpact({ files: ['auth.ts'], task: 'update jwt', lineCount: 10 });\n      expect(tier3.fastPass).toBe(false);\n    });\n  });\n\n  describe('Token Budget Broker — deterministic budget allocation', () => {\n    test.each([\n      [0, 0],\n      [1, 2000],\n      [2, 8000],\n      [3, 32000],\n    ])('Tier %i always returns %i maxTokens', (tier, expectedTokens) => {\n      for (let i = 0; i < 10; i++) {\n        expect(getTokenBudget(tier).maxTokens).toBe(expectedTokens);\n      }\n    });\n\n    test('TIER_TOKEN_LIMITS is immutable (frozen or consistent)', async () => {\n      expect(TIER_TOKEN_LIMITS[0]).toBe(0);\n      expect(TIER_TOKEN_LIMITS[1]).toBe(2000);\n      expect(TIER_TOKEN_LIMITS[2]).toBe(8000);\n      expect(TIER_TOKEN_LIMITS[3]).toBe(32000);\n    });\n  });\n\n  describe('Socratic Gate — deterministic decisions', () => {\n    test.each([\n      [0, 0.0, false],\n      [1, 0.0, false],\n      [2, 0.3, false],\n      [2, 0.8, true],\n      [3, 0.0, true],\n    ])('Tier %i + ambiguity %d → shouldBlock = %s', (tier, ambiguityScore, expected) => {\n      for (let i = 0; i < 10; i++) {\n        expect(evaluateSocraticGate({ tier, ambiguityScore }).shouldBlock).toBe(expected);\n      }\n    });\n  });\n});\n\n// ─────────────────────────────────────────────────────────────────────────────\n// SECTION 3: FAILURE TOLERANCE\n// ─────────────────────────────────────────────────────────────────────────────\n\ndescribe('FAILURE TOLERANCE: Graceful Degradation Under Failure', () => {\n  test('wrapper.js runRustBinary contains graceful fallback pattern (not process.exit on spawn error)', async () => {\n    const wrapperSource = fs.readFileSync(path.join(ROOT, 'bin/wrapper.js'), 'utf8');\n\n    // Extract the runRustBinary function body to verify it returns false on error\n    // instead of calling process.exit(1)\n    const fnMatch = wrapperSource.match(/function runRustBinary[\\s\\S]*?^}/m);\n    expect(fnMatch).not.toBeNull();\n    const fnBody = fnMatch[0];\n\n    // The old dangerous pattern: process.exit(1) inside runRustBinary on result.error\n    expect(fnBody).not.toContain('process.exit(1)');\n\n    // The new safe pattern: return false to fall through\n    expect(fnBody).toContain('return false');\n    expect(wrapperSource).toContain('Falling back to JS engine');\n  });\n\n  test('TRIBUNAL_FORCE_JS=1 forces JS fallback without crashing', async () => {\n    const wrapperPath = path.join(ROOT, 'bin/wrapper.js');\n    // This should not throw — it should execute via JS engine\n    try {\n      const out = execFileSync(process.execPath, [wrapperPath, 'status'], {\n        encoding: 'utf8',\n        env: { ...process.env, TRIBUNAL_FORCE_JS: '1' },\n        stdio: ['ignore', 'pipe', 'pipe'],\n        timeout: 15000,\n      });\n      expect(typeof out).toBe('string');\n    } catch (err) {\n      // Non-zero exit is acceptable (e.g. \"not installed\"), but unhandled crash is not\n      expect(err.status).toBeDefined();\n      expect(err.status).not.toBe(null);\n    }\n  });\n\n  test('MCP server handles batch JSON-RPC requests (protocol resilience)', async () => {\n    const batch = [\n      { jsonrpc: '2.0', id: 1, method: 'ping' },\n      { jsonrpc: '2.0', id: 2, method: 'resources/list' },\n    ];\n    // Simulate batch by processing individually (batch is handled in rl.on line)\n    for (const req of batch) {\n      const result = await handleRequest(req);\n      expect(result).toBeDefined();\n    }\n  });\n\n  test('MCP server handles notification methods without response (no crash)', async () => {\n    const notificationReq = { method: 'notifications/initialized' };\n    const result = await handleRequest(notificationReq);\n    expect(result).toBeNull();\n  });\n\n  test('MCP server returns proper error for unknown methods', async () => {\n    const req = { jsonrpc: '2.0', id: 99, method: 'completely/unknown' };\n    try {\n      await handleRequest(req);\n      fail('Should have thrown');\n    } catch (e) {\n      expect(e.code).toBe(-32601);\n      expect(e.message).toContain('Unknown method');\n    }\n  });\n\n  test('integrity manifest handles missing .agent directory gracefully', async () => {\n    const result = generateManifest('/nonexistent/path/that/does/not/exist');\n    expect(result).toHaveProperty('error');\n    expect(typeof result.error).toBe('string');\n  });\n\n  test('parseFrontmatter handles empty string without crash', async () => {\n    expect(parseFrontmatter('')).toEqual({});\n  });\n\n  test('parseFrontmatter handles malformed YAML without crash', async () => {\n    const malformed = '---\\n\\n---\\n\\nContent';\n    const result = parseFrontmatter(malformed);\n    // Should return empty object (no valid key-value pairs)\n    expect(typeof result).toBe('object');\n  });\n});\n\n// ─────────────────────────────────────────────────────────────────────────────\n// SECTION 4: OBSERVABILITY\n// ─────────────────────────────────────────────────────────────────────────────\n\ndescribe('OBSERVABILITY: Structured Errors & Audit Outputs', () => {\n  test('MCP initialize response contains valid server info', async () => {\n    const req = { jsonrpc: '2.0', id: 1, method: 'initialize', params: {} };\n    const result = await handleRequest(req);\n\n    expect(result.protocolVersion).toBe('2025-03-26');\n    expect(result.serverInfo.name).toBe('tribunal-kit-mcp');\n    expect(typeof result.serverInfo.version).toBe('string');\n    expect(result.serverInfo.version).toMatch(/^\\d+\\.\\d+\\.\\d+$/);\n  });\n\n  test('MCP tools/list returns well-formed tool descriptors', async () => {\n    const req = { jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} };\n    const result = await handleRequest(req);\n\n    expect(Array.isArray(result.tools)).toBe(true);\n    expect(result.tools.length).toBeGreaterThan(0);\n\n    for (const tool of result.tools) {\n      expect(typeof tool.name).toBe('string');\n      expect(tool.name.length).toBeGreaterThan(0);\n      expect(typeof tool.description).toBe('string');\n      expect(tool.inputSchema).toBeDefined();\n      expect(tool.inputSchema.type).toBe('object');\n    }\n  });\n\n  test('Impact classifier returns structured reasoning array', async () => {\n    const result = classifyImpact({ files: ['auth.ts'], task: 'update jwt', lineCount: 10 });\n    expect(Array.isArray(result.reasoning)).toBe(true);\n    expect(result.reasoning.length).toBeGreaterThan(0);\n    for (const reason of result.reasoning) {\n      expect(typeof reason).toBe('string');\n      expect(reason.length).toBeGreaterThan(0);\n    }\n  });\n\n  test('Socratic gate returns structured reason string', async () => {\n    const result = evaluateSocraticGate({ tier: 3 });\n    expect(typeof result.reason).toBe('string');\n    expect(result.reason.length).toBeGreaterThan(0);\n  });\n\n  test('Token budget returns all expected fields for observability', async () => {\n    const result = getTokenBudget(2);\n    expect(result).toHaveProperty('tier');\n    expect(result).toHaveProperty('maxTokens');\n    expect(result).toHaveProperty('includeFullRepo');\n    expect(result).toHaveProperty('maxSkills');\n    expect(result).toHaveProperty('maxReviewers');\n  });\n\n  test('stripBoilerplate function preserves core content while removing guardrail boilerplate', async () => {\n    const input = 'Core content here.\\n\\n## Pre-Flight Checklist\\nBoilerplate content';\n    const result = stripBoilerplate(input);\n    expect(result).toContain('Core content here.');\n    expect(result).not.toContain('Pre-Flight Checklist');\n  });\n});\n\n// ─────────────────────────────────────────────────────────────────────────────\n// SECTION 5: REPRODUCIBILITY\n// ─────────────────────────────────────────────────────────────────────────────\n\ndescribe('REPRODUCIBILITY: Stable Manifests & Version Metadata', () => {\n  test('integrity manifest is reproducible (two runs produce identical structure)', async () => {\n    const manifest1 = generateManifest(ROOT);\n    const manifest2 = generateManifest(ROOT);\n\n    // Remove timestamps for comparison\n    delete manifest1.generated_at;\n    delete manifest2.generated_at;\n\n    expect(manifest1.agents.total).toBe(manifest2.agents.total);\n    expect(manifest1.skills.total).toBe(manifest2.skills.total);\n    expect(manifest1.scripts.total).toBe(manifest2.scripts.total);\n    expect(manifest1.workflows.total).toBe(manifest2.workflows.total);\n    expect(manifest1.integrity.phantom_references).toBe(manifest2.integrity.phantom_references);\n    expect(manifest1.integrity.invalid_claims).toBe(manifest2.integrity.invalid_claims);\n  });\n\n  test('package.json version matches Cargo.toml version', async () => {\n    const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));\n    const cargoToml = fs.readFileSync(path.join(ROOT, 'crates/core/Cargo.toml'), 'utf8');\n    const cargoVersion = cargoToml.match(/^version\\s*=\\s*\"([^\"]+)\"/m)?.[1];\n\n    expect(cargoVersion).toBe(pkg.version);\n  });\n\n  test('package.json version matches Cargo.lock tribunal-core version', async () => {\n    const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));\n    const cargoLock = fs.readFileSync(path.join(ROOT, 'Cargo.lock'), 'utf8');\n    const lockVersion = cargoLock.match(\n      /name\\s*=\\s*\"tribunal-core\"\\s+version\\s*=\\s*\"([^\"]+)\"/,\n    )?.[1];\n\n    expect(lockVersion).toBe(pkg.version);\n  });\n\n  test('optionalDependencies versions are in sync with package.json version', async () => {\n    const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));\n    const expectedVersion = `^${pkg.version}`;\n\n    for (const [_name, version] of Object.entries(pkg.optionalDependencies || {})) {\n      expect(version).toBe(expectedVersion);\n    }\n  });\n\n  test('package-lock.json root version matches package.json', async () => {\n    const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));\n    const lock = JSON.parse(fs.readFileSync(path.join(ROOT, 'package-lock.json'), 'utf8'));\n\n    expect(lock.version).toBe(pkg.version);\n  });\n});\n\n// ─────────────────────────────────────────────────────────────────────────────\n// SECTION 6: PRODUCTION RELEASE SUITABILITY\n// ─────────────────────────────────────────────────────────────────────────────\n\ndescribe('PRODUCTION RELEASE SUITABILITY: Structural Integrity', () => {\n  test('critical files exist for production release', async () => {\n    const criticalFiles = [\n      'package.json',\n      'README.md',\n      'LICENSE',\n      'SECURITY.md',\n      'CONTRIBUTING.md',\n      'bin/wrapper.js',\n      'bin/mcp-server.js',\n      'bin/tribunal-kit.js',\n      'dist/cli.js',\n      'dist/index.d.ts',\n      'Cargo.toml',\n      'crates/core/Cargo.toml',\n      'crates/core/src/main.rs',\n      '.agent/scripts/impact_classifier.js',\n      '.agent/scripts/token_budget_broker.js',\n      '.agent/scripts/integrity_manifest.js',\n      '.agent/scripts/context_broker.js',\n      '.agent/scripts/guardrail_engine.js',\n    ];\n\n    for (const file of criticalFiles) {\n      const fullPath = path.join(ROOT, file);\n      expect(fs.existsSync(fullPath)).toBe(true);\n    }\n  });\n\n  test('bin/wrapper.js shebang is correct for cross-platform npm bin', async () => {\n    const wrapper = fs.readFileSync(path.join(ROOT, 'bin/wrapper.js'), 'utf8');\n    expect(wrapper.startsWith('#!/usr/bin/env node')).toBe(true);\n  });\n\n  test('bin/mcp-server.js shebang is correct', async () => {\n    const mcp = fs.readFileSync(path.join(ROOT, 'bin/mcp-server.js'), 'utf8');\n    expect(mcp.startsWith('#!/usr/bin/env node')).toBe(true);\n  });\n\n  test('package.json exports are correctly defined', async () => {\n    const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));\n\n    expect(pkg.main).toBe('dist/cli.js');\n    expect(pkg.types).toBe('dist/index.d.ts');\n    expect(pkg.exports['.']).toBeDefined();\n    expect(pkg.exports['.'].types).toBe('./dist/index.d.ts');\n    expect(pkg.exports['.'].import).toBe('./dist/esm/index.mjs');\n    expect(pkg.exports['.'].require).toBe('./dist/cli.js');\n  });\n\n  test('package.json bin entries point to existing files', async () => {\n    const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));\n\n    for (const [_binName, binPath] of Object.entries(pkg.bin || {})) {\n      const fullPath = path.resolve(ROOT, binPath);\n      expect(fs.existsSync(fullPath)).toBe(true);\n    }\n  });\n\n  test('package.json engines specifies minimum Node version', async () => {\n    const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));\n    expect(pkg.engines).toBeDefined();\n    expect(pkg.engines.node).toBeDefined();\n    expect(pkg.engines.node).toMatch(/>=\\s*18/);\n  });\n\n  test('no hardcoded secrets in source files', async () => {\n    const sensitivePatterns = [\n      /sk-[a-zA-Z0-9]{20,}/, // OpenAI API keys\n      /ghp_[a-zA-Z0-9]{36}/, // GitHub personal access tokens\n      /AKIA[A-Z0-9]{16}/, // AWS access keys\n      /password\\s*[:=]\\s*[\"'][^\"']{8,}/i, // Hardcoded passwords\n    ];\n\n    const filesToCheck = [\n      'bin/wrapper.js',\n      'bin/mcp-server.js',\n      'bin/tribunal-kit.js',\n      'dist/cli.js',\n      '.agent/scripts/context_broker.js',\n      '.agent/scripts/guardrail_engine.js',\n    ];\n\n    for (const file of filesToCheck) {\n      const content = fs.readFileSync(path.join(ROOT, file), 'utf8');\n      for (const pattern of sensitivePatterns) {\n        expect(pattern.test(content)).toBe(false);\n      }\n    }\n  });\n\n  test('integrity manifest reports phantom references accurately', async () => {\n    const manifest = generateManifest(ROOT);\n    if (manifest.error) {\n      // If .agent not found, skip (edge case in CI)\n      return;\n    }\n\n    // The manifest should report phantom references deterministically\n    expect(typeof manifest.integrity.phantom_references).toBe('number');\n    expect(typeof manifest.integrity.invalid_claims).toBe('number');\n  });\n\n  test('routing_index.json exists and has valid structure', async () => {\n    const routingIndexPath = path.join(ROOT, '.agent', 'routing_index.json');\n    if (!fs.existsSync(routingIndexPath)) {\n      // Skip if routing_index.json doesn't exist yet\n      return;\n    }\n\n    const routingIndex = JSON.parse(fs.readFileSync(routingIndexPath, 'utf8'));\n    expect(routingIndex).toHaveProperty('summary');\n    expect(typeof routingIndex.summary.total_agents).toBe('number');\n    expect(typeof routingIndex.summary.total_workflows).toBe('number');\n    expect(typeof routingIndex.summary.total_skills).toBe('number');\n  });\n\n  test('RUST_COMMANDS set in wrapper.js matches Rust core command modules', async () => {\n    const wrapperSource = fs.readFileSync(path.join(ROOT, 'bin/wrapper.js'), 'utf8');\n\n    // Extract command names from the RUST_COMMANDS set\n    const commandMatch = wrapperSource.match(/RUST_COMMANDS\\s*=\\s*new\\s+Set\\(\\[([\\s\\S]*?)\\]\\)/);\n    expect(commandMatch).not.toBeNull();\n\n    // Verify the set is not empty\n    const commandsBlock = commandMatch[1];\n    const commands = commandsBlock.match(/['\"]([^'\"]+)['\"]/g);\n    expect(commands).not.toBeNull();\n    expect(commands.length).toBeGreaterThan(0);\n\n    // Verify essential commands are present\n    const commandNames = commands.map(c => c.replace(/['\"]/g, ''));\n    expect(commandNames).toContain('init');\n    expect(commandNames).toContain('validate');\n    expect(commandNames).toContain('status');\n    expect(commandNames).toContain('memory');\n  });\n});\n"
+}

package/.agent/history/snapshots/test__unit__selfInstall.test.js.json

@@ -1,6 +1,5 @@
 {
   "file": "test/unit/selfInstall.test.js",
-  "hash": "65b099af8b884c6c1d174f7f70c6d836c27e02ea",
   "riskScore": "Low",
   "blastRadius": 0,
   "imports": {
@@ -15,9 +14,10 @@
       "isSelfInstall",
       "CORE_AGENTS",
       "CORE_SKILLS",
-      "generateIDEBridges"
+      "generateIDEBridges",
+      "cmdMarathon"
     ]
   },
   "dependents": [],
-  "content": "'use strict';\r\n\r\nconst path = require('path');\r\nconst fs   = require('fs');\r\nconst os   = require('os');\r\nconst { isSelfInstall } = require('../../bin/tribunal-kit');\r\n\r\ndescribe('isSelfInstall', () => {\r\n    test('returns true when target is the kit root (package root)', () => {\r\n        // The kit root is one level above bin/\r\n        const kitRoot = path.resolve(__dirname, '../../');\r\n        expect(isSelfInstall(kitRoot)).toBe(true);\r\n    });\r\n\r\n    test('returns false for an unrelated directory', () => {\r\n        expect(isSelfInstall(os.tmpdir())).toBe(false);\r\n    });\r\n\r\n    test('returns true when target package.json has name \"tribunal-kit\"', () => {\r\n        // Create a temp dir with a fake package.json mimicking the kit\r\n        const fakeKitDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fake-tk-'));\r\n        fs.writeFileSync(\r\n            path.join(fakeKitDir, 'package.json'),\r\n            JSON.stringify({ name: 'tribunal-kit', version: '1.0.0' })\r\n        );\r\n        expect(isSelfInstall(fakeKitDir)).toBe(true);\r\n        fs.rmSync(fakeKitDir, { recursive: true, force: true });\r\n    });\r\n\r\n    test('returns false when target package.json has a different name', () => {\r\n        const fakeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'other-pkg-'));\r\n        fs.writeFileSync(\r\n            path.join(fakeDir, 'package.json'),\r\n            JSON.stringify({ name: 'my-other-project', version: '1.0.0' })\r\n        );\r\n        expect(isSelfInstall(fakeDir)).toBe(false);\r\n        fs.rmSync(fakeDir, { recursive: true, force: true });\r\n    });\r\n\r\n    test('returns false when target has no package.json', () => {\r\n        const emptyDir = fs.mkdtempSync(path.join(os.tmpdir(), 'no-pkg-'));\r\n        expect(isSelfInstall(emptyDir)).toBe(false);\r\n        fs.rmSync(emptyDir, { recursive: true, force: true });\r\n    });\r\n});\r\n"
+  "content": "'use strict';\n\nconst path = require('path');\nconst fs = require('fs');\nconst os = require('os');\nconst { isSelfInstall } = require('../../bin/tribunal-kit');\n\ndescribe('isSelfInstall', () => {\n  test('returns true when target is the kit root (package root)', () => {\n    // The kit root is one level above bin/\n    const kitRoot = path.resolve(__dirname, '../../');\n    expect(isSelfInstall(kitRoot)).toBe(true);\n  });\n\n  test('returns false for an unrelated directory', () => {\n    expect(isSelfInstall(os.tmpdir())).toBe(false);\n  });\n\n  test('returns true when target package.json has name \"tribunal-kit\"', () => {\n    // Create a temp dir with a fake package.json mimicking the kit\n    const fakeKitDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fake-tk-'));\n    fs.writeFileSync(\n      path.join(fakeKitDir, 'package.json'),\n      JSON.stringify({ name: 'tribunal-kit', version: '1.0.0' }),\n    );\n    expect(isSelfInstall(fakeKitDir)).toBe(true);\n    fs.rmSync(fakeKitDir, { recursive: true, force: true });\n  });\n\n  test('returns false when target package.json has a different name', () => {\n    const fakeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'other-pkg-'));\n    fs.writeFileSync(\n      path.join(fakeDir, 'package.json'),\n      JSON.stringify({ name: 'my-other-project', version: '1.0.0' }),\n    );\n    expect(isSelfInstall(fakeDir)).toBe(false);\n    fs.rmSync(fakeDir, { recursive: true, force: true });\n  });\n\n  test('returns false when target has no package.json', () => {\n    const emptyDir = fs.mkdtempSync(path.join(os.tmpdir(), 'no-pkg-'));\n    expect(isSelfInstall(emptyDir)).toBe(false);\n    fs.rmSync(emptyDir, { recursive: true, force: true });\n  });\n});\n"
 }

package/.agent/history/snapshots/test__unit__semver.test.js.json

@@ -1,6 +1,5 @@
 {
   "file": "test/unit/semver.test.js",
-  "hash": "d3b4e92656e66f496f034174abd53012ed00b33c",
   "riskScore": "Low",
   "blastRadius": 0,
   "imports": {
@@ -12,9 +11,10 @@
       "isSelfInstall",
       "CORE_AGENTS",
       "CORE_SKILLS",
-      "generateIDEBridges"
+      "generateIDEBridges",
+      "cmdMarathon"
     ]
   },
   "dependents": [],
-  "content": "'use strict';\r\n\r\nconst { compareSemver } = require('../../bin/tribunal-kit');\r\n\r\ndescribe('compareSemver', () => {\r\n    test('returns 1 when a > b (patch)', () => {\r\n        expect(compareSemver('2.4.2', '2.4.1')).toBe(1);\r\n    });\r\n\r\n    test('returns 1 when a > b (minor)', () => {\r\n        expect(compareSemver('2.5.0', '2.4.9')).toBe(1);\r\n    });\r\n\r\n    test('returns 1 when a > b (major)', () => {\r\n        expect(compareSemver('3.0.0', '2.9.9')).toBe(1);\r\n    });\r\n\r\n    test('returns 0 when a === b', () => {\r\n        expect(compareSemver('2.4.2', '2.4.2')).toBe(0);\r\n    });\r\n\r\n    test('returns -1 when a < b (patch)', () => {\r\n        expect(compareSemver('2.4.1', '2.4.2')).toBe(-1);\r\n    });\r\n\r\n    test('returns -1 when a < b (minor)', () => {\r\n        expect(compareSemver('2.4.9', '2.5.0')).toBe(-1);\r\n    });\r\n\r\n    test('strips leading \"v\" prefix from a', () => {\r\n        expect(compareSemver('v2.4.2', '2.4.2')).toBe(0);\r\n    });\r\n\r\n    test('strips leading \"v\" prefix from b', () => {\r\n        expect(compareSemver('2.4.2', 'v2.4.2')).toBe(0);\r\n    });\r\n\r\n    test('strips leading \"v\" from both', () => {\r\n        expect(compareSemver('v2.4.3', 'v2.4.2')).toBe(1);\r\n    });\r\n\r\n    test('handles missing patch segment (treats as 0)', () => {\r\n        expect(compareSemver('2.4', '2.4.0')).toBe(0);\r\n    });\r\n});\r\n"
+  "content": "'use strict';\n\nconst { compareSemver } = require('../../bin/tribunal-kit');\n\ndescribe('compareSemver', () => {\n  test('returns 1 when a > b (patch)', () => {\n    expect(compareSemver('2.4.2', '2.4.1')).toBe(1);\n  });\n\n  test('returns 1 when a > b (minor)', () => {\n    expect(compareSemver('2.5.0', '2.4.9')).toBe(1);\n  });\n\n  test('returns 1 when a > b (major)', () => {\n    expect(compareSemver('3.0.0', '2.9.9')).toBe(1);\n  });\n\n  test('returns 0 when a === b', () => {\n    expect(compareSemver('2.4.2', '2.4.2')).toBe(0);\n  });\n\n  test('returns -1 when a < b (patch)', () => {\n    expect(compareSemver('2.4.1', '2.4.2')).toBe(-1);\n  });\n\n  test('returns -1 when a < b (minor)', () => {\n    expect(compareSemver('2.4.9', '2.5.0')).toBe(-1);\n  });\n\n  test('strips leading \"v\" prefix from a', () => {\n    expect(compareSemver('v2.4.2', '2.4.2')).toBe(0);\n  });\n\n  test('strips leading \"v\" prefix from b', () => {\n    expect(compareSemver('2.4.2', 'v2.4.2')).toBe(0);\n  });\n\n  test('strips leading \"v\" from both', () => {\n    expect(compareSemver('v2.4.3', 'v2.4.2')).toBe(1);\n  });\n\n  test('handles missing patch segment (treats as 0)', () => {\n    expect(compareSemver('2.4', '2.4.0')).toBe(0);\n  });\n});\n"
 }

package/.agent/history/snapshots/test__unit__skill_evolution.test.js.json

@@ -0,0 +1,11 @@
+{
+  "file": "test/unit/skill_evolution.test.js",
+  "riskScore": "Low",
+  "blastRadius": 0,
+  "imports": {
+    "../../.agent/scripts/signal_detector": [],
+    "../../.agent/scripts/skill_evolution": []
+  },
+  "dependents": [],
+  "content": "const { detectSignals } = require('../../.agent/scripts/signal_detector');\nconst { _semanticDelta, _architecturalWeight } = require('../../.agent/scripts/skill_evolution');\n\ndescribe('signal_detector.js', () => {\n  it('should extract signals from JS stack trace', () => {\n    const log = `TypeError: Cannot read property 'split' of undefined\\n    at processFile (src/utils.js:45:20)\\n    at Object.run (src/main.js:10:5)`;\n    const signals = detectSignals(log);\n    expect(signals.length).toBeGreaterThan(0);\n    expect(signals[0].type).toBe('log_error');\n    expect(signals[0].file).toBe('src/utils.js');\n    expect(signals[0].line).toBe(45);\n  });\n\n  it('should extract signals from Python traceback', () => {\n    const log = `Traceback (most recent call last):\\n  File \"src/main.py\", line 12, in <module>\\n    foo()\\nZeroDivisionError: division by zero`;\n    const signals = detectSignals(log);\n    expect(signals.length).toBeGreaterThan(0);\n    expect(signals[0].type).toBe('log_error');\n    expect(signals[0].file).toBe('src/main.py');\n    expect(signals[0].line).toBe(12);\n  });\n\n  it('should extract signals from Rust compiler error', () => {\n    const log = `error[E0308]: mismatched types\\n  --> src/main.rs:12:34\\n   |\\n12 |     let x: u32 = \"hello\";\\n   |                  ^^^^^^^ expected \\`u32\\`, found \\`&str\\``;\n    const signals = detectSignals(log);\n    expect(signals.length).toBeGreaterThan(0);\n    expect(signals[0].type).toBe('log_error');\n    expect(signals[0].file).toBe('src/main.rs');\n    expect(signals[0].line).toBe(12);\n  });\n\n  it('should extract signals from ESLint inline line', () => {\n    const log = `src/index.js: line 5, col 10, Error - 'x' is defined but never used (no-unused-vars)`;\n    const signals = detectSignals(log);\n    expect(signals.length).toBeGreaterThan(0);\n    expect(signals[0].type).toBe('log_error');\n    expect(signals[0].file).toBe('src/index.js');\n    expect(signals[0].line).toBe(5);\n    expect(signals[0].message).toContain('no-unused-vars');\n  });\n\n  it('should extract signals from performance bottleneck', () => {\n    const log = `Slow query detected - execution time: 1200ms\\nSELECT * FROM users;`;\n    const signals = detectSignals(log);\n    expect(signals.length).toBeGreaterThan(0);\n    expect(signals[0].type).toBe('perf_bottleneck');\n  });\n});\n"
+}

package/.agent/history/snapshots/test__unit__stress.test.js.json

@@ -0,0 +1,15 @@
+{
+  "file": "test/unit/stress.test.js",
+  "riskScore": "Low",
+  "blastRadius": 0,
+  "imports": {
+    "path": [],
+    "../../scripts/stress_benchmark": [
+      "app",
+      "parseUser",
+      "runStressSuite"
+    ]
+  },
+  "dependents": [],
+  "content": "/**\n * test/unit/stress.test.js — Tribunal-Kit Stress & Performance Unit Test\n */\n\n'use strict';\n\nconst _path = require('path');\nconst { runStressSuite } = require('../../scripts/stress_benchmark');\n\ndescribe('Tribunal-Kit Governance Stress Suite', () => {\n  let stressResults;\n\n  beforeAll(async () => {\n    // Run stress suite in memory\n    stressResults = await runStressSuite();\n  }, 30000); // 30s timeout for heavy stress run\n\n  test('Concurrency stress test passes with high throughput', () => {\n    expect(stressResults.concurrency).toBeDefined();\n    expect(stressResults.concurrency.all_passed).toBe(true);\n    expect(stressResults.concurrency.ops_per_sec).toBeGreaterThan(50);\n  });\n\n  test('Scale stress test handles 10,000 LOC within budget', () => {\n    expect(stressResults.scale).toBeDefined();\n    expect(stressResults.scale.lines_of_code).toBeGreaterThanOrEqual(10000);\n    expect(stressResults.scale.parse_time_ms).toBeLessThan(5000);\n  });\n\n  test('Token compression achieves token savings', () => {\n    expect(stressResults.token_compression).toBeDefined();\n    expect(stressResults.token_compression.savings_percent).toBeGreaterThan(0);\n  });\n\n  test('Anti-hallucination barrier catches 100% of malicious security payloads', () => {\n    expect(stressResults.anti_hallucination).toBeDefined();\n    expect(stressResults.anti_hallucination.detection_rate_percent).toBe(100);\n    expect(stressResults.anti_hallucination.caught_swarm_hallucination).toBe(true);\n  });\n});\n"
+}

package/.agent/history/snapshots/test__unit__swarm_dispatcher.test.js.json

@@ -1,12 +1,12 @@
 {
   "file": "test/unit/swarm_dispatcher.test.js",
-  "hash": "59ea8d2f8e73dd3a384df1966e55002db2df0947",
   "riskScore": "Low",
   "blastRadius": 0,
   "imports": {
     "path": [],
-    "fs": []
+    "fs": [],
+    "../../.agent/scripts/swarm_dispatcher.js": []
   },
   "dependents": [],
-  "content": "const path = require('path');\r\nconst fs = require('fs');\r\n\r\ndescribe('swarm_dispatcher.js', () => {\r\n    it('should be a valid javascript file', () => {\r\n        const filePath = path.join(__dirname, '../../.agent/scripts/swarm_dispatcher.js');\r\n        expect(fs.existsSync(filePath)).toBe(true);\r\n        const content = fs.readFileSync(filePath, 'utf8');\r\n        expect(content.includes('module.exports')).toBeTruthy();\r\n    });\r\n    \r\n    // As swarm_dispatcher heavily relies on filesystem operations and child_process,\r\n    // we would use jest.mock('child_process') and jest.mock('fs') for deeper testing.\r\n    // This serves as the foundation for the swarm test suite.\r\n});\r\n"
+  "content": "const path = require('path');\nconst fs = require('fs');\nconst {\n  validateWorkerRequest,\n  validateWorkerResult,\n  validateSwarmPayload,\n} = require('../../.agent/scripts/swarm_dispatcher.js');\n\ndescribe('swarm_dispatcher.js', () => {\n  it('should be a valid javascript file', () => {\n    const filePath = path.join(__dirname, '../../.agent/scripts/swarm_dispatcher.js');\n    expect(fs.existsSync(filePath)).toBe(true);\n    const content = fs.readFileSync(filePath, 'utf8');\n    expect(content.includes('module.exports')).toBeTruthy();\n  });\n\n  it('should validate a valid worker request object', () => {\n    const agentsDir = path.join(__dirname, '../../.agent/agents');\n    const validRequest = {\n      task_id: 'task-1',\n      type: 'generate_code',\n      agent: 'backend-specialist',\n      goal: 'Implement authentication route',\n      context: 'Minimal required context',\n    };\n    expect(validateWorkerRequest(validRequest, 0, agentsDir)).toEqual([]);\n  });\n\n  it('should reject invalid worker requests missing required fields', () => {\n    const agentsDir = path.join(__dirname, '../../.agent/agents');\n    const invalidRequest = { worker_id: 'worker-1' };\n    expect(validateWorkerRequest(invalidRequest, 0, agentsDir).length).toBeGreaterThan(0);\n  });\n\n  it('should validate a valid worker result object', () => {\n    const validResult = {\n      task_id: 'task-1',\n      agent: 'backend-specialist',\n      status: 'success',\n      output: 'Created auth handler',\n    };\n    expect(validateWorkerResult(validResult, 0)).toEqual([]);\n  });\n\n  it('should validate a complete swarm payload object', () => {\n    const payload = {\n      goal: 'Build feature',\n      workers: [\n        {\n          task_id: 'task-1',\n          type: 'generate_code',\n          agent: 'backend-specialist',\n          goal: 'Build auth route',\n          context: 'Context info',\n        },\n      ],\n    };\n    const agentsDir = path.join(__dirname, '../../.agent/agents');\n    expect(validateSwarmPayload(payload, agentsDir)).toBe(true);\n  });\n});\n"
 }

package/.agent/history/snapshots/test__unit__utils.test.js.json

@@ -0,0 +1,10 @@
+{
+  "file": "test/unit/utils.test.js",
+  "riskScore": "Low",
+  "blastRadius": 0,
+  "imports": {
+    "../../.agent/scripts/_utils": []
+  },
+  "dependents": [],
+  "content": "'use strict';\n\nconst { normalizeCommand } = require('../../.agent/scripts/_utils');\n\ndescribe('normalizeCommand', () => {\n  test('only appends .cmd for Windows package-manager shims', () => {\n    expect(normalizeCommand('npm', 'win32')).toBe('npm.cmd');\n    expect(normalizeCommand('node', 'win32')).toBe('node');\n    expect(normalizeCommand('cargo', 'win32')).toBe('cargo');\n    expect(normalizeCommand('C:\\\\tools\\\\node.exe', 'win32')).toBe('C:\\\\tools\\\\node.exe');\n  });\n});\n"
+}

package/.agent/scripts/ast_context_loader.js

@@ -0,0 +1,137 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Normalizes a file path to consistently use forward slashes for cross-platform compatibility.
+ */
+function normalizePath(p) {
+  return path.normalize(p).replace(/\\/g, '/');
+}
+
+/**
+ * Loads the dependency graph from .tribunal/graph.json.
+ * @param {string} projectRoot - The root directory of the project
+ * @returns {Object|null} The semantic graph object or null if not found
+ */
+function loadGraph(projectRoot) {
+  const graphPath = path.join(projectRoot, '.tribunal', 'graph.json');
+  if (!fs.existsSync(graphPath)) {
+    return null;
+  }
+  try {
+    const data = fs.readFileSync(graphPath, 'utf8');
+    return JSON.parse(data);
+  } catch (err) {
+    console.error('[AST Context] Failed to parse graph.json:', err.message);
+    return null;
+  }
+}
+
+/**
+ * Gets the direct dependencies (files imported by) and dependents (files that import) a target file.
+ * Includes transitive dependencies up to 2 levels deep.
+ * @param {string} projectRoot - The root directory of the project
+ * @param {string} targetFile - The relative or absolute path of the target file
+ * @returns {Object} An object containing { dependencies, dependents } as arrays of file paths
+ */
+function getContext(projectRoot, targetFile) {
+  const graph = loadGraph(projectRoot);
+  if (!graph || !graph.nodes) {
+    return { error: 'Graph not found or invalid. Run `tribunal-core graph-ast .` first.' };
+  }
+
+  // Convert target to a consistent format (usually absolute, normalized)
+  const normalizedTarget = normalizePath(path.resolve(projectRoot, targetFile));
+
+  const dependencies = new Set();
+  const dependents = new Set();
+
+  // Helper to resolve imports and find matching files
+  function resolveImports(filePath, imports) {
+    const resolved = new Set();
+    const fileDir = path.dirname(filePath);
+
+    for (const imp of imports || []) {
+      if (imp.startsWith('.')) {
+        const resolvedImport = normalizePath(path.resolve(fileDir, imp));
+        // Find actual file matching this import
+        const matchingNodes = graph.nodes.filter(n => {
+          const nAbs = normalizePath(path.resolve(projectRoot, n.file_path));
+          return nAbs === resolvedImport;
+        });
+        matchingNodes.forEach(m =>
+          resolved.add(normalizePath(path.resolve(projectRoot, m.file_path))),
+        );
+      }
+    }
+    return resolved;
+  }
+
+  // First pass: find direct dependencies and dependents
+  graph.nodes.forEach(node => {
+    const nodeAbsPath = normalizePath(path.resolve(projectRoot, node.file_path));
+    const nodeDir = path.dirname(nodeAbsPath);
+
+    // Does this node import our target?
+    for (const imp of node.imports || []) {
+      if (imp.startsWith('.')) {
+        const resolvedImport = normalizePath(path.resolve(nodeDir, imp));
+        // Check if resolved import matches our target exactly
+        if (normalizedTarget === resolvedImport) {
+          dependents.add(nodeAbsPath);
+        }
+      }
+    }
+
+    // Is this node our target? If so, what does it import?
+    if (nodeAbsPath === normalizedTarget) {
+      const directDeps = resolveImports(nodeAbsPath, node.imports || []);
+      directDeps.forEach(dep => dependencies.add(dep));
+    }
+  });
+
+  // Second pass: find transitive dependencies (dependencies of dependencies)
+  const directDependencies = Array.from(dependencies);
+  directDependencies.forEach(dep => {
+    // Find the node for this dependency
+    const depNode = graph.nodes.find(
+      n => normalizePath(path.resolve(projectRoot, n.file_path)) === dep,
+    );
+
+    if (depNode) {
+      const transitiveDeps = resolveImports(dep, depNode.imports || []);
+      transitiveDeps.forEach(tdep => {
+        // Don't add the target itself or create cycles
+        if (tdep !== normalizedTarget && !dependencies.has(tdep)) {
+          dependencies.add(tdep);
+        }
+      });
+    }
+  });
+
+  return {
+    target: normalizedTarget,
+    dependencies: Array.from(dependencies),
+    dependents: Array.from(dependents),
+  };
+}
+
+module.exports = {
+  loadGraph,
+  getContext,
+};
+
+// If run directly from CLI
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  if (args.length < 1) {
+    console.error('Usage: node ast_context_loader.js <target_file>');
+    process.exit(1);
+  }
+
+  const target = args[0];
+  const projectRoot = process.cwd();
+  const result = getContext(projectRoot, target);
+
+  console.log(JSON.stringify(result, null, 2));
+}