feat: FMP equity-analyst + v6.8.x traceability/compliance stack (post-review)

super-legal-mcp-refactored/.env.example

@@ -76,6 +76,20 @@ FRED_API_KEY=
 
 # NASA NTRS - No API key required (public, unauthenticated)
 
+# FMP - Financial Modeling Prep (equity-analyst integration)
+# REQUIRED for the equity-analyst subagent's native API path. With key absent,
+# the hybrid client gracefully degrades to Exa websearch fallback.
+# Ultimate plan ($149/mo developer tier — transcript-enabled). Production
+# activation gated behind FMP_ENABLED=false until FMP Enterprise contract +
+# Data Display & Redistribution Agreement signs.
+# Sign up: https://site.financialmodelingprep.com/developer/docs
+FMP_API_KEY=
+FMP_ENABLED=false
+# Allow returning unbounded raw responses (forbidden in production)
+ALLOW_FULL_RESPONSE=false
+# Allow returning full earnings-call transcripts (~150 KB each)
+ALLOW_FULL_TRANSCRIPT=false
+
 # =============================================================================
 # SERVER CONFIGURATION
 # =============================================================================
@@ -101,6 +115,24 @@ METRICS_PORT=9090
 OTEL_ENABLED=false
 OTEL_EXPORTER_ENDPOINT=https://telemetry.googleapis.com/v1/traces
 
+# OpenTelemetry trace sampling (v6.8.5 W5.1) — bound Cloud Trace cost.
+# Without these, OTel SDK defaults to AlwaysOn → ~30-60 spans per session ×
+# N sessions/day → unbounded cost. parentbased_traceidratio + 0.1 = 10%
+# sample with parent-context inheritance (sampled traces stay coherent).
+# Tunable via Cloud Run revision env if a different rate is needed for
+# incident investigation. Only meaningful when OTEL_ENABLED=true.
+OTEL_TRACES_SAMPLER=parentbased_traceidratio
+OTEL_TRACES_SAMPLER_ARG=0.1
+
+# Build-time commit SHA (v6.8.4 W5.4 / Tier 3 reproducibility).
+# NOT a runtime env you set in .env directly — injected via Dockerfile ARG/ENV
+# at build time:
+#   docker build --build-arg COMMIT_SHA=$(git rev-parse HEAD) ...
+# Without this, hook_audit_log.event_data.bridge_metadata.git_sha defaults to
+# 'unknown' — graceful but breaks regulator-replay audit trail. The deploy +
+# client-provisioner skills pass this arg automatically.
+COMMIT_SHA=
+
 # Wave 3: Compliance & Governance
 WAL_ENABLED=false
 ACCESS_AUDIT=false

super-legal-mcp-refactored/.github/workflows/integration-tests.yml

@@ -0,0 +1,80 @@
+name: Integration Tests (Postgres-backed)
+
+# Runs PR-gating integration tests that require a real Postgres instance.
+# These tests are skipped in the main `test` job (deploy.yml) when
+# PG_CONNECTION_STRING is unset; this workflow provides Postgres so they run.
+#
+# Day 6.H — added to catch hook → DB persistence regressions before merge
+# (see docs/testing-integration-tests.md). Gated to PRs touching specific
+# files to bound CI cost.
+
+on:
+  pull_request:
+    paths:
+      - 'src/tools/codeExecutionBridge.js'
+      - 'src/utils/hookDBBridge.js'
+      - 'src/utils/sdkMetrics.js'
+      - 'src/utils/buildVersion.js'
+      - 'src/utils/citationParser.js'
+      - 'src/utils/retentionManager.js'
+      - 'src/schemas/toolEnvelopes.js'
+      - 'src/server/dbFrontendRouter.js'
+      - 'src/hooks/sdkHooks.js'
+      - 'src/db/postgres.js'
+      - 'src/config/legalSubagents/_promptConstants.js'
+      - 'migrations/**'
+      - 'flags.env'
+      - 'Dockerfile'
+      - 'test/sdk/code-execution-hook-e2e.test.js'
+      - 'test/sdk/hookDBBridge-integration.test.js'
+      - '.github/workflows/integration-tests.yml'
+  workflow_dispatch:
+
+jobs:
+  integration:
+    name: Integration tests (Postgres)
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_DB: super_legal
+          POSTGRES_USER: super_legal
+          POSTGRES_PASSWORD: super_legal_dev
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U super_legal -d super_legal"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
+    env:
+      PG_CONNECTION_STRING: postgresql://super_legal:super_legal_dev@localhost:5432/super_legal
+      CODE_EXECUTION_BRIDGE: 'true'
+      HOOK_DB_PERSISTENCE: 'true'
+      NODE_OPTIONS: --experimental-vm-modules
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run hook → DB integration tests
+        run: |
+          npx jest \
+            test/sdk/code-execution-hook-e2e.test.js \
+            test/sdk/hookDBBridge-integration.test.js \
+            --runInBand \
+            --testTimeout=30000
+
+      - name: Show Postgres logs on failure
+        if: failure()
+        run: |
+          docker logs $(docker ps -q --filter ancestor=pgvector/pgvector:pg16) | tail -50

super-legal-mcp-refactored/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 All notable changes to the Super Legal MCP Server are documented in this file.
 
+## [6.8.0] - 2026-05-02 — equity-analyst integration (FMP)
+
+### Added
+
+New `equity-analyst` subagent + 36-tool FMP client + 11 code-execution models, gated behind `FMP_ENABLED=false` feature flag (production activation requires FMP Enterprise contract + Data Display & Redistribution Agreement, expected 4–8 weeks parallel commercial track).
+
+**Day 1–2** (commits `a94b7115`..`68069e4f`) — empirical foundation: 182 FMP `/stable` fixtures across 36 endpoint families; 73 live filter probes; surfaced 8 hard-filter tools.
+
+**Day 3** (commits `29e3af14`..`e3954371`) — spec doc empirical revisions: Section 14.5 byte budgets re-tabled with measurements; Section 19 banner replaced; M50/M53/M55 dataFields reconciled; M58 stub spec added; Tier 3 LLM transcript summarization REMOVED; TruncationMetadata typedef added; FMP class casing aligned to all-caps.
+
+**Day 4** (commits `e83b25c7`..`b9ee2c34`) — foundation build:
+- `src/utils/responseProfileManager.js` — 12-profile budget registry + validator + SessionBudgetTracker
+- `src/utils/equityCanonicalSchema.js` — 15 JSDoc typedefs (vendor-agnostic contract)
+- `src/api-clients/FMPClient.js` — 36 native REST methods (30s timeout, 429 backoff, 3-retry, error-envelope detection)
+- `src/api-clients/FMPWebSearchClient.js` — 36 Exa-fallback mirror methods
+- `src/api-clients/FMPHybridClient.js` — orchestrator + `_applySliceProfile` DRY helper + transcript Tier 0/1/2 deterministic extractors + `addMetadata` override
+- `test/sdk/fmp-hybrid-test.js` — 143 unit-test assertions, fixture-driven
+- Three review rounds caught 13 real findings — all fixed; BaseHybridClient.js byte-identical
+
+**Day 5** (commits `8b2dcaf5`..`7c1b3e94`) — wiring:
+- 7 platform touchpoints + new equity-analyst subagent
+- featureFlags.js (FMP_ENABLED + ALLOW_FULL_TRANSCRIPT)
+- apiConfig.js (fmp rate limiter, 5 req/sec)
+- toolDefinitions.js (equitiesTools, 36 JSON Schemas)
+- toolImplementations.js (DOMAIN_MAPPING + 36 wrapWithConversation)
+- domainMcpServers.js (conditional 'equities' domain + equity-analyst SUBAGENT_DOMAIN_MAP)
+- clientRegistry.js (FMPHybridClient instantiation; 38 API clients now)
+- equity-analyst.js (new Sonnet subagent)
+- _promptConstants.js (EQUITY_ANALYST_CAPABILITY + 2 token-budget/transcript-profile constants)
+- 44 → 45 subagents
+
+**Day 6** — code-execution models:
+- 11 new equity-analysis models registered: M46–M55 + M58 (45 → 56)
+- New "Earnings Quality" category (13th)
+- 11 input examples added with realistic mock data (real tickers AAPL/MSFT/GOOGL/JPM/XLK/SPY)
+- Live test runner: 11/11 PASS (32 charts produced across the suite, ~$3 API cost, ~22 min runtime)
+- FMP citation template added to `prompts/memorandum-synthesis/legal-standards.md` (8 patterns)
+- Subagent keyword extension in equity-analyst.js
+- README + intake-research.md updates
+
+**Day 6.C–6.E** — pre-PR conformance polish + observability registration (commits `c2abfcaa`..`0c5a3500`):
+- **Day 6.C** — prompt-surface alignment: legal-research-coordinator Domain Routing Matrix row for equity-analyst; MCP_FALLBACK_INSTRUCTIONS equities block; roles.md FMP source-family entry; cross-reference notes in securities-researcher and government-affairs-analyst.
+- **Day 6.D** — alignment polish from 3-agent review: header tool count 183→197 corrected; routing row keyword trim; MCP block header normalization; README v6.8.0 model-count narrative.
+- **Day 6.E** — observability registration: `classifyAgent` (hookSSEBridge.js) maps equity-analyst → `research_support` stage parallel to financial-analyst/data-analyst; `RESEARCH_AGENTS` set membership in p0GateHook.js (no-docs path verified safe via agentStreamHandler.js gate condition); `AGENT_STAGE_MAP` entry in app.js + companion `.phase-badge.research_support` CSS rule (also fixes latent peer issue); equity-analyst.js prompt restructured to peer pattern; M58 category folded into M&A Analysis; M49/M54/M55 descriptions expanded.
+- **Phase 2 runbook** — 4 mandatory post-flag-flip verifications appended to § 8.4.X (hook_audit_log for FMP tool calls, hook_audit_log for M46–M58 run_python_analysis, Cloud Trace SubagentStart with `stage=research_support`, citation-websearch-verifier accepts FMP format). Each with explicit pass/fail criteria + escalation path.
+
+**Day 6.E meta-improvement** — `.claude/skills/` (project-level, not git-tracked) updated with patterns derived from this integration so all future API integrations + code-execution model batches benefit by default:
+- `api-integration/SKILL.md` (591 → 857 lines): NEW Phase 1.5 (Empirical Capture & Probing) + Phase 1.6 (Endpoint Classification with 7-pattern framework + defensive engineering consequence map) — formally encodes "measure before architect" as prerequisite for client implementation. NEW Phase 7 (Observability & Dispatch Registration) covering 9 surfaces (coordinator routing, MCP_FALLBACK, roles.md, classifyAgent, p0GateHook, AGENT_STAGE_MAP, CSS, agentDisplayMeta+agentClassifications, flags.env+ENV.SDK.example) + 4-step production-gate verification template.
+- `code-execution-models/SKILL.md` (365 → 454 lines): NEW Phase 5.5 (Subagent Integration & Live Testing) covering CAPABILITY constant enumeration, agent description keyword updates, peer-reusable live test runner pattern (`equity-models-live-test.mjs` template), audit log SQL verification.
+
+These skill updates are global to the project's Claude config — not part of this branch's diff but documented here for traceability. Future integrations that follow the updated skills will avoid the 3-pass post-hoc audit cycle that surfaced Day 6.C–6.E findings.
+
+### Changed
+- README subagent count: 44 → 45
+- Code-execution model catalog: 45 → 56 (new "Earnings Quality" category)
+- API client count: 37 → 38
+
+### Deferred to Phase 2
+- FMP Enterprise contract + Data Display & Redistribution Agreement (parallel commercial track)
+- Production activation (FMP_ENABLED=true) gated behind contract signing
+- Cross-quarter transcript embedding via existing embeddingService.js pipeline
+
 ## [6.7.3] - 2026-04-28
 
 ### Changed — Final source-level emoji suppression (executive-memo aesthetic, pt. 3)

super-legal-mcp-refactored/Dockerfile

@@ -58,6 +58,12 @@ EXPOSE 3001
 HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
   CMD node -e "fetch('http://localhost:3001/health').then(r => process.exit(r.ok ? 0 : 1))"
 
+# v6.8.4 Tier 3: COMMIT_SHA for reproducibility audit (regulator replay).
+# Build with: docker build --build-arg COMMIT_SHA=$(git rev-parse HEAD) ...
+# Defaults to 'unknown' if not passed; server falls back gracefully.
+ARG COMMIT_SHA=unknown
+ENV COMMIT_SHA=${COMMIT_SHA}
+
 ENV NODE_ENV=production
 ENV NODE_OPTIONS="--max-old-space-size=4096"
 ENV DEBUG_CLAUDE_AGENT_SDK=1

super-legal-mcp-refactored/ENV.SDK.example

@@ -15,6 +15,10 @@ SHADOW_LOG_SAMPLE_PCT=0
 # REGULATIONS_API_KEY=your_api_data_gov_key
 # FRED_API_KEY=your_fred_api_key_here
 # NASA NTRS requires no key
+# FMP equity-analyst integration (v6.8.0) — REQUIRED for native API path; degrades to Exa fallback if missing
+# FMP_API_KEY=your_fmp_ultimate_or_enterprise_key
+# FMP_ENABLED=false  # set true only after FMP Enterprise contract signs (see flags.env)
+# ALLOW_FULL_TRANSCRIPT=false  # production default; toggle true only for dev deep-dives
 # ANTHROPIC_API_KEY=your_key_here
 # SDK_MODEL=claude-sonnet-4-5-20250929
 # LEGACY_URL=http://localhost:3000/api/research