Dashboard/PRISM/Context/Compliance-Assessment.md
PRISM

Context/Compliance-Assessment.md

Archived 2026-04-14 — This document describes the v1 architecture (ModuleInterface pattern) which has been fully removed. The current architecture is documented in Architecture/unified-module-architecture.md.

created: 2026-04-08 updated: 2026-04-08 type: context project: PRISM tags: [prism, compliance, assessment, standards]

PRISM Compliance Assessment

Assessment of PRISM codebase against vault standards as of 2026-04-08. This is the "what needs to happen" document for PRISM refactoring.

Summary Verdicts

Standard Verdict Priority
CodingSOPs Mostly compliant, 3 gaps Medium
TestingSOPs Partially compliant, 3 structural gaps Medium
FolderStructure Non-compliant (expected debt) Low (migrate opportunistically)
Manifesto Core spirit compliant, contract drift High (extract shared-py)
AgentHarnessPatterns Architecturally aligned N/A

CodingSOPs Gaps

Gap 1: No Adapter Pattern (HIGH)

Standard: "Every external API gets an adapter class. Unit tests inject mock adapter. Integration tests inject live adapter."

PRISM: Modules call APIs directly via httpx or library calls. No adapter interfaces. No constructor injection.

Impact: Cannot swap mock/live adapters. Unit tests must call real APIs or monkeypatch. Violates Dependency Inversion (SOLID-D).

Fix: Extract adapter interfaces to shared-py/adapters/. Each module constructor accepts adapters. See Adapter-Interfaces.

Effort: Medium. Touches all 20 modules (constructor changes) + new adapter package. No logic changes.

Gap 2: Function Length (LOW)

Standard: Max 20 lines per function.

PRISM: Many collector and module functions exceed 20 lines (some 50-80 lines).

Fix: Extract sub-functions. The collector/enricher/validator split already helps; within each file, break long functions into named steps.

Gap 3: Inconsistent Docstrings (LOW)

Standard: Docstring on every public class, method, function.

PRISM: Present on many but not all public methods.

Fix: Docstring pass across all module files. Mechanical.

TestingSOPs Gaps

Gap 1: No TDD (MEDIUM)

Standard: "Write the test first, always. RED-GREEN-REFACTOR."

PRISM: Built implementation-first, tests-after (based on session logs).

Fix: For future modules, enforce TDD. Existing modules: retroactive TDD is not practical. Focus on test quality, not test-first ordering.

Gap 2: No Adapter-Based Mocks (HIGH)

Standard: "Unit tests inject mock adapter. Zero real API calls."

PRISM: Tests either call real APIs (integration) or skip (no unit tests with mock adapters). This means unit tests are actually integration tests.

Fix: After implementing adapter pattern (CodingSOPs Gap 1), create MockPerplexityAdapter, MockBuiltWithAdapter, etc. Rewrite test_*_collector files to use mock adapters for unit tests.

Gap 3: Flat Test Structure (LOW)

Standard: packages/{module}/tests/{unit,integration,contract}/

PRISM: All tests in flat tests/ directory at project root.

Fix: Restructure when migrating to monorepo layout. Low priority.

FolderStructure Gaps

Gap: Non-Standard Layout (LOW)

Standard: apps/packages/services/shared-py/workflows/

PRISM: Flat src/prism_platform/ with frontend/.

Fix: Full restructure to:

apps/web/          -- Next.js frontend
services/prism/    -- Python backend (current prism_platform/)
shared-py/core/    -- Extracted ModuleInterface, types, adapters
workflows/         -- Temporal workflow definitions

When: Do this when starting LENS. Extract shared-py from PRISM, then both PRISM and LENS import from shared-py.

Gap: CLAUDE.md is 26KB (MEDIUM)

Standard: <60 lines, 3 sections: Identity, Vault Pointers, Active Context.

Fix: Move operating constitution to vault (already partially done via this knowledge extraction). Slim CLAUDE.md to a pointer file.

Manifesto Gaps

Gap 1: No Shared Base Layer (HIGH)

Standard: Two-layer system. shared-py/core owns base classes.

PRISM: ModuleInterface, ModuleResult, Source, EvidenceTier all live inside PRISM. Not extractable for LENS.

Fix: Move to shared-py/core/. PRISM imports from shared-py. LENS will too.

Gap 2: ModuleResult Schema Drift (MEDIUM)

Standard (updated in v0.2.0): ModuleResult has trace_id, input_hash, failure_category.

PRISM: Missing trace_id, input_hash, failure_category. Uses generic output: dict instead of typed findings.

Fix: Add trace_id (generate UUID in ExecutionContext). Add input_hash (hash of domain + config). Add FailureCategory enum. Keep output: dict for now (typed output per module is enforced at validation time, not at container type).

Gap 3: No PromptModule (LOW)

Standard v0.1.0: PromptModule as Layer 0. No module builds its own prompt.

Updated in v0.2.0: Prompts are part of the module spec, not a runtime service. This is a spec-level concern, not a code-level concern.

Fix: Ensure each module spec includes its enrichment prompt template. No code changes needed; this is a documentation task.

Gap 4: Only 2 of 4 Interface Surfaces (LOW)

Standard: Python + CLI + FastAPI + MCP.

PRISM: Python + FastAPI only. No CLI, no MCP server.

Fix: Add Click CLI for operator use. Add MCP server for Claude integration. Low priority for initial deployment.

Refactoring Priority Order

  1. Extract shared-py/core -- ModuleInterface, types, adapters. Unblocks LENS.
  2. Implement adapter pattern -- 20 modules get constructor-injected adapters. Unblocks proper unit testing.
  3. Add trace_id + input_hash to ModuleResult -- Small change, big debugging value.
  4. Add FailureCategory -- Explicit F1-F5 on failures. Changes error handling in all modules.
  5. Slim CLAUDE.md -- Move content to vault, make CLAUDE.md a pointer.
  6. Monorepo restructure -- apps/services/shared-py layout. Do when starting LENS.
  7. Docstring pass -- Mechanical. Do opportunistically.
  8. Test restructure -- Move to per-module test directories. Do with monorepo restructure.

What NOT to Refactor

  • Wave execution model -- already compliant with Manifesto + AgentHarnessPatterns
  • Pydantic everywhere -- already compliant with CodingSOPs
  • Error handling -- already production-grade (try/catch, specific exceptions)
  • Logging -- structlog is arguably better than the SOP's pipe format. Keep structlog.
  • Database caching -- PostgreSQL-first caching is a good decision. Keep it.
  • Evidence tier system -- already matches the new Evidence-Tier-Spec
  • Architecture-Overview -- full architecture
  • Manifesto -- the standards being assessed against
  • CodingSOPs -- coding standards
  • TestingSOPs -- testing standards
  • FolderStructure -- folder structure standards