Skip to content

spec.md

Latest commit

 

History

History
143 lines (94 loc) · 9.79 KB

spec.md

File metadata and controls

143 lines (94 loc) · 9.79 KB

Feature Specification: Constitution Compliance

Feature Branch: 002-constitution-compliance
Created: 2025-11-02
Status: Draft
Input: User description: "incorporate changes in the @constitution.md"

Clarifications

Session 2025-11-02

  • Q: When should constitution violations be detected and handled - at development time, at runtime, or both? → A: Multiple layers - automated tests during development, runtime checks during execution, plus manual verification

User Scenarios & Testing (mandatory)

User Story 1 - Ensure Local-Only Processing (Priority: P1)

A system administrator needs to ensure that the entity data model implementation complies with constitution requirements for local-only processing (no external API dependencies for core functionality).

Why this priority: Core compliance - the constitution explicitly requires "Local embeddings + FAISS storage" and "No external API dependency for core functionality". Any deviation requires explicit justification and amendment.

Independent Test: Can be fully tested by verifying that entity storage, querying, and relationship navigation operate without external API calls, and that all embeddings and LLM inference use local models only. Delivers immediate value by ensuring constitutional compliance.

Acceptance Scenarios:

  1. Given the entity data model implementation is complete, When all entity operations (save, load, query, cascade delete) are executed, Then no external API calls are made
  2. Given the RAG system needs to generate embeddings for decision items, When embeddings are generated, Then local embedding models are used (no remote API calls)
  3. Given the system needs to generate RAG responses, When LLM inference is performed, Then local LLM models are used (no remote API calls)

User Story 2 - Enforce Python-Only Execution (Priority: P1)

A developer needs to verify that all entity data model operations use only Python standard library and Python packages (no external binaries or system dependencies beyond Python runtime).

Why this priority: Core compliance - the constitution requires "Python-only execution environment". This ensures portability and reduces deployment complexity.

Independent Test: Can be fully tested by checking that all entity operations use only Python code paths, JSON file storage (standard library), and Python-native dependencies. Delivers value by ensuring cross-platform compatibility and reducing deployment complexity.

Acceptance Scenarios:

  1. Given the entity storage implementation, When entities are saved and loaded, Then only Python standard library (json) and Python packages are used
  2. Given the system runs on a clean Python environment, When all entity operations execute, Then no system-level binaries or external dependencies beyond Python runtime are required
  3. Given the system needs to query relationships, When index files are read, Then only Python file I/O and JSON parsing are used

User Story 3 - Validate FAISS Storage Compliance (Priority: P2)

A developer needs to ensure that FAISS vector storage remains local and compatible with the entity data model's RAG functionality.

Why this priority: Important compliance - the constitution requires "Local embeddings + FAISS storage". The entity model must maintain compatibility with existing FAISS-based RAG queries.

Independent Test: Can be fully tested by verifying that FAISS indexes can be created from entity-based decision items and that RAG queries work with the new entity structure. Delivers value by preserving RAG functionality while maintaining constitutional compliance.

Acceptance Scenarios:

  1. Given decision items are stored in the entity model, When embeddings are generated for RAG indexing, Then FAISS indexes are created and stored locally
  2. Given a FAISS index exists for entity-based data, When a RAG query is executed, Then the query uses the local FAISS index and returns results from entity-based meeting data
  3. Given the system performs RAG indexing, When FAISS indexes are created, Then all index files are stored locally (no remote storage)

User Story 4 - Verify CLI Support Compliance (Priority: P2)

A user needs to access all entity data model operations via CLI commands as required by the constitution.

Why this priority: Important compliance - the constitution requires "CLI support for all major pipeline stages". Users must be able to interact with the entity model through command-line interface.

Independent Test: Can be fully tested by executing all entity operations (query workgroup, query person, query meeting, etc.) via CLI commands and verifying they work without external dependencies. Delivers value by ensuring accessible command-line interface for all functionality.

Acceptance Scenarios:

  1. Given entity data exists, When a user runs archive-rag query-workgroup <id>, Then meetings are returned without requiring external API calls
  2. Given entity data exists, When a user runs archive-rag query-person <id> --action-items, Then action items are returned via CLI
  3. Given the system needs to migrate data, When a user runs migration CLI commands, Then migration completes using only local Python operations

Edge Cases

  • When external API calls are detected during runtime entity operations, system fails with clear error message (runtime compliance check)
  • Automated tests during development detect external API dependencies before deployment (development compliance check)
  • Manual verification confirms constitution compliance through code review and audit processes (manual compliance check)
  • How does the system handle missing Python dependencies without falling back to external services?
  • What happens when local model files are missing but external APIs are available? (Should fail, not fall back to remote)
  • How does the system verify that all entity operations comply with Python-only requirement?
  • What happens if FAISS index creation requires external resources? (Should use local FAISS library only)

Requirements (mandatory)

Functional Requirements

  • FR-001: System MUST operate without external API dependencies for core entity operations (save, load, query, cascade delete)
  • FR-002: System MUST use local embedding models for generating embeddings from decision items (no remote embedding API calls)
  • FR-003: System MUST use local LLM models for RAG generation (no remote LLM API calls)
  • FR-004: System MUST store all FAISS indexes locally (no remote vector database)
  • FR-005: System MUST use only Python standard library and Python packages (no external binaries beyond Python runtime)
  • FR-006: System MUST provide CLI commands for all entity data model operations (query-workgroup, query-person, query-meeting, etc.)
  • FR-007: System MUST validate constitution compliance through multiple layers: automated tests during development detect violations, runtime checks prevent violations during execution, and manual verification confirms compliance
  • FR-008: System MUST maintain compatibility between entity-based data model and existing local FAISS RAG system
  • FR-009: System MUST use JSON file storage for entities (Python standard library, local-only)
  • FR-010: System MUST fail gracefully with clear error messages if external dependencies are detected (do not silently fall back to external services)

Key Entities

(No new entities - this feature ensures existing entity data model complies with constitution)

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: 100% of entity operations (save, load, query, delete) execute without external API calls
  • SC-002: 100% of embedding generation uses local models (no remote API calls)
  • SC-003: 100% of LLM inference uses local models (no remote API calls)
  • SC-004: 100% of FAISS index operations use local storage (no remote vector database)
  • SC-005: All entity operations use only Python standard library and Python packages (no external binaries required)
  • SC-006: All major entity operations are accessible via CLI commands
  • SC-007: System detects and reports constitution violations through multiple layers: automated tests catch violations during development, runtime checks prevent violations during execution with clear error messages, and manual verification confirms compliance
  • SC-008: Entity-based data model maintains full compatibility with existing local FAISS RAG queries (no functional regression)

Assumptions

  • Existing entity data model implementation uses or may use external APIs that need to be replaced with local alternatives
  • Local embedding models (sentence-transformers) and local LLM models (transformers) are available and configured
  • Python environment includes necessary packages (faiss-cpu, sentence-transformers, transformers) for local processing
  • All entity operations can be verified for constitution compliance through automated checks
  • CLI commands are the primary interface for user interaction with entity data model

Dependencies

  • Existing entity data model implementation (specs/001-entity-data-model)
  • Local embedding model availability (sentence-transformers)
  • Local LLM model availability (transformers)
  • Python environment setup with required packages
  • FAISS local storage capability

Notes

  • This feature ensures compliance with Archive-RAG Constitution version 1.0.0
  • Any deviations from constitutional requirements must be documented and justified per governance rules
  • Constitution requires amendments for any changes to "Local embeddings + FAISS" or "No external API dependency" principles
  • This feature focuses on verifying and enforcing existing constitutional requirements rather than changing the constitution itself