Files

Andris Enins 91cd18aec6 feat: initial implementation — all 35 requirements across phases 1-3

Backend (Spring Boot 3.2 / Java 21 / PostgreSQL):
- JWT auth with BCrypt password hashing
- User profile + Mifflin-St Jeor BMR calculator
- Food search + barcode via OpenFoodFacts API with local cache
- Meal CRUD with user data isolation and ownership checks
- AI photo analysis (OpenAI Vision) with confidence intervals
- AI correction feedback loop for personalisation
- Flyway DB migrations + RFC-7807 error responses

Mobile (React Native / TypeScript):
- Full navigation stack (Auth → Tabs → Home stack)
- Design tokens (WCAG 2.2 AA colours, 8px grid, 48px touch targets)
- 10 screens: Login, Register, Home, Search, Camera, AI Result, Edit Meal,
  Daily Details, History, Profile
- Confidence-aware calorie display (kcal ± range)
- Repeat last meal shortcut + macro tracking

Docs:
- docs/PLAN-AND-REQUIREMENTS.md
- docs/traceability.csv (35 requirements, all Implemented)

2026-05-18 21:56:13 +03:00

15 KiB

Raw Permalink Blame History

Virsaitis Requirements Documentation

Version: 3.0.0 Status: Draft Owner: Toms Eisaks Updated: 2026-04-20

📋 Overview

This directory contains complete requirements specification for Virsaitis v3.0 - a three-layer AI governance system achieving 95%+ compliance through Agent, MCP Server, and VS Code Extension.

Total Requirements: 85 (71 functional + 14 non-functional)

📚 Document Structure

Core Requirements

Document	Purpose	Requirements	Status
index.md	Requirements overview and navigation	-	✅ Complete
functional-spec.md	Functional requirements REQ-GOV, REQ-SEC	28	✅ Complete
functional-spec-part2.md	REQ-MCP, REQ-EXT, REQ-AGT, REQ-SKL, REQ-TEST	43	✅ Complete
nonfunctional-spec.md	Performance, scalability, usability NFRs	14	✅ Complete

Supporting Documents

Document	Purpose	Status
traceability.csv	REQ-ID → Implementation → Test mapping	✅ Complete
glossary.md	Terminology definitions	✅ Complete
assumptions.md	Documented assumptions with validation plans	✅ Complete
risk-register.md	Risk identification and mitigation	✅ Complete

🎯 Requirements Categories

REQ-GOV: Governance Core (12 requirements)

Foundational governance capabilities:

REQ-GOV-001 (TIER-0): Protected file modification enforcement
REQ-GOV-002 (TIER-0): Atomic sentence structure
REQ-GOV-003 (TIER-1): TIER system definition
REQ-GOV-004 (TIER-1): REQ-ID traceability
REQ-GOV-005 (TIER-1): CHANGELOG maintenance
REQ-GOV-006 (TIER-1): Discovery-first workflow
REQ-GOV-007 (TIER-1): Test coverage enforcement ≥70%
REQ-GOV-008 (TIER-1): Modular governance architecture
REQ-GOV-009 (TIER-2): Consequence documentation
REQ-GOV-010 (TIER-1): Traceability CSV management
REQ-GOV-011 (TIER-1): Version synchronization
REQ-GOV-012 (TIER-1): Quality gates

Status: 8/12 Implemented (Agent + modular governance + TIER system + discovery-first + CHANGELOG + version sync + consequences)

REQ-SEC: Security Controls (16 requirements)

Security enforcement:

REQ-SEC-001 (TIER-0): Secret detection 100% coverage
REQ-SEC-002 (TIER-0): Credential rotation <1 hour
REQ-SEC-003 (TIER-0): Environment variable enforcement
REQ-SEC-004 (TIER-1): Path traversal validation
REQ-SEC-005 (TIER-1): Command injection prevention
REQ-SEC-006 (TIER-2): ReDoS prevention
REQ-SEC-007 (TIER-1): Error message sanitization
REQ-SEC-008 (TIER-1): Audit logging
REQ-SEC-009 (TIER-2): Least privilege
REQ-SEC-010 (TIER-2): Defense in depth
REQ-SEC-011 (TIER-2): Secure defaults
REQ-SEC-012 (TIER-2): Cryptography standards
REQ-SEC-013 (TIER-1): Security test coverage 100%
REQ-SEC-014 (TIER-2): PII logging prevention
REQ-SEC-015 (TIER-1): Security scan automation
REQ-SEC-016 (TIER-3): Vulnerability disclosure policy

Status: 0/16 Implemented (Phase 2 focus)

REQ-MCP: MCP Server (11 requirements)

TypeScript governance validation engine:

REQ-MCP-001 (TIER-1): TypeScript 5.0+ implementation
REQ-MCP-002 (TIER-1): MCP Protocol SDK integration
REQ-MCP-003 (TIER-0): File operation validation engine
REQ-MCP-004 (TIER-1): Agent.md governance loading
REQ-MCP-005 (TIER-1): stdio transport
REQ-MCP-006 (TIER-0): Secret scanning tool
REQ-MCP-007 (TIER-1): Path validation tool
REQ-MCP-008 (TIER-1): Command validation tool
REQ-MCP-009 (TIER-1): Audit log integration
REQ-MCP-010 (TIER-2): Server configuration
REQ-MCP-011 (TIER-1): Post-iteration compliance check

Status: 1/11 Implemented (stdio transport defined)

REQ-EXT: VS Code Extension (10 requirements)

Real-time file interception:

REQ-EXT-001 (TIER-2): Extension activation <200ms
REQ-EXT-002 (TIER-0): File save interception
REQ-EXT-003 (TIER-1): MCP client communication
REQ-EXT-004 (TIER-2): Status bar integration
REQ-EXT-005 (TIER-3): Shield icon decoration
REQ-EXT-006 (TIER-2): Override request command
REQ-EXT-007 (TIER-2): Configuration settings
REQ-EXT-008 (TIER-1): Extension packaging .vsix <5MB
REQ-EXT-009 (TIER-1): Webpack build configuration
REQ-EXT-010 (TIER-1): Extension Development Host testing

Status: 0/10 Implemented (Phase 3 parallel with MCP)

REQ-AGT: Agent (8 requirements)

Behavioral control document:

REQ-AGT-001 (TIER-0): Atomic sentence implementation ✅ (v3.0: 262 lines)
REQ-AGT-002 (TIER-1): Agent governance rule loading ✅
REQ-AGT-003 (TIER-2): Consequence chain documentation ✅
REQ-AGT-004 (TIER-1): Workflow pattern definition ✅
REQ-AGT-005 (TIER-1): Uncertainty response pattern ✅
REQ-AGT-006 (TIER-1): Modular governance reference ✅
REQ-AGT-007 (TIER-2): Integration awareness ✅
REQ-AGT-008 (TIER-2): Self-limitation acknowledgment ✅

Status: 8/8 Implemented (Agent v3.0 complete)

REQ-SKL: Skills (5 requirements)

Native VS Code Agent Skills:

REQ-SKL-001 (TIER-1): Core skills creation (6 skills)
REQ-SKL-002 (TIER-1): YAML frontmatter metadata
REQ-SKL-003 (TIER-1): Consequences section mandatory
REQ-SKL-004 (TIER-2): Progressive disclosure levels
REQ-SKL-005 (TIER-2): Validation commands

Status: 0/5 Implemented (Phase 4 parallel with Extension)

REQ-TEST: Testing & QA (10 requirements)

Quality assurance framework:

REQ-TEST-001 (TIER-1): Test coverage ≥70%
REQ-TEST-002 (TIER-1): Security test coverage 100%
REQ-TEST-003 (TIER-1): Vitest for MCP
REQ-TEST-004 (TIER-1): @vscode/test-electron for Extension
REQ-TEST-005 (TIER-2): TDD red-green-refactor
REQ-TEST-006 (TIER-2): Unit test naming convention
REQ-TEST-007 (TIER-2): Mocking strategy
REQ-TEST-008 (TIER-1): Integration test suite
REQ-TEST-009 (TIER-1): Pre-commit test execution
REQ-TEST-010 (TIER-2): Regression test suite

Status: 0/10 Implemented (Throughout all phases)

REQ-NFR: Non-Functional Requirements (14 requirements)

Quality attributes:

Performance: 5 requirements (response time, activation time, memory usage)
Scalability: 2 requirements (concurrent operations, large workspaces)
Usability: 2 requirements (error messages, documentation accessibility)
Maintainability: 2 requirements (code modularity, coverage ratcheting)
Portability: 3 requirements (cross-platform, package size)

Status: 0/14 Verified (Continuous measurement starting Phase 2)

📊 Implementation Status

By Priority

TIER	Total	Implemented	Percentage
TIER-0	7	3	43%
TIER-1	41	15	37%
TIER-2	34	3	9%
TIER-3	3	0	0%
Total	85	21	25%

By Category

Category	Total	Implemented	Percentage
Governance (GOV)	12	8	67%
Security (SEC)	16	0	0%
MCP Server	11	1	9%
Extension	10	0	0%
Agent	8	8	100%
Skills	5	0	0%
Testing	10	0	0%
Non-Functional	14	0	0%
Total	85	21	25%

🚀 Implementation Roadmap

Phase 1: Foundation (Current) ✅ 25% Complete

Timeline: 2 weeks Focus: Agent v3.0 + Modular Governance v3.0

Completed:

✅ REQ-GOV-001: Protected file enforcement (3 layers)
✅ REQ-GOV-002: Atomic sentences (Agent v3.0, 262 lines)
✅ REQ-GOV-003: TIER system defined in core-policies
✅ REQ-GOV-005: CHANGELOG maintenance
✅ REQ-GOV-006: Discovery-first workflow
✅ REQ-GOV-008: Hub + 11 modules + definition library
✅ REQ-GOV-009: Consequence documentation
✅ REQ-GOV-010: Traceability CSV
✅ REQ-GOV-011: Version synchronization (all v3.0.0)
✅ REQ-MCP-005: stdio transport defined
✅ REQ-AGT-001 through REQ-AGT-008: Agent v3.0 complete

Deliverables:

Agent v3.0 complete (262 lines, attention-optimized)
11 governance modules complete (v3.0 formatted)
Definition library in .github/ (protected)
Requirements documentation complete
CHANGELOG created

Phase 2: MCP Server (Next) 🎯 Target: 40% Overall

Timeline: 4 weeks Focus: TypeScript validation engine

Target Requirements:

REQ-MCP-001 through REQ-MCP-011: All MCP requirements
REQ-SEC-001, REQ-SEC-002, REQ-SEC-003: Secret management TIER-0
REQ-TEST-003: Vitest framework setup
REQ-TEST-001: Achieve ≥70% coverage

Deliverables:

package.json with dependencies
TypeScript configuration
Agent.md parser
Validation engine
Secret scanning tool
HTTP API endpoint
Audit logging
Test suite with ≥70% coverage

Phase 3: VS Code Extension (Parallel with Phase 4) 🔮 Target: 60% Overall

Timeline: 4 weeks (parallel) Focus: File save interception

Target Requirements:

REQ-EXT-001 through REQ-EXT-010: All Extension requirements
REQ-TEST-004: Extension test framework
REQ-NFR-002: Activation time <200ms

Deliverables:

Extension package.json
Webpack configuration
File save interception
MCP client
Status bar integration
Configuration settings
VSIX packaging
Extension Host testing

Phase 4: Skills (Parallel with Phase 3) 🔮 Target: 70% Overall

Timeline: 4 weeks (parallel) Focus: Domain-specific rules

Target Requirements:

REQ-SKL-001 through REQ-SKL-005: All Skills requirements
REQ-GOV-009: Consequence documentation

Deliverables:

python-development skill
security-controls skill
requirements-engineering skill
testing-validation skill
governance-compliance skill
typescript-development skill
All with Consequences sections

Phase 5: Integration & Distribution 🔮 Target: 95% Overall

Timeline: 3 weeks Focus: Portable packaging + End-to-end testing

Target Requirements:

REQ-TEST-008: Integration tests
REQ-GOV-012: Quality gates
REQ-NFR-013, REQ-NFR-014: Portability
Remaining TIER-2 and TIER-3 requirements

Deliverables:

Integration test suite
Portable installer (Windows/macOS/Linux)
User acceptance testing
Documentation complete
Release packaging

Architecture

5-Component Architecture - System design

Governance Modules

Core Policies - TIER system
Agent Standards - Atomic sentences
MCP Standards - TypeScript patterns
Extension Standards - VS Code API
Skills Standards - SKILL.md format
Development Workflow - 11-step discovery
Security Controls - Security patterns
Requirements Engineering - REQ-ID format
Testing Quality - Test standards
Integration Patterns - Component interaction
Distribution Deployment - Packaging

Implementation

Agent Source - Agent.md source
MCP Server - TypeScript implementation (TBD)
VS Code Extension - Extension implementation (TBD)
Skills - Domain-specific rules (TBD)

✅ How to Use This Documentation

For Product Owners

Read index.md for high-level overview
Review implementation status by phase
Monitor traceability.csv for progress
Assess risk-register.md monthly

For Developers

Read relevant requirements category (REQ-GOV, REQ-MCP, etc.)
Check traceability.csv for implementation files
Consult glossary.md for terminology
Review assumptions.md for validation needs
Update traceability.csv ImplementationRef when implementing
Update traceability.csv TestRef when writing tests

For Testers

Read REQ-TEST requirements for test strategy
Check traceability.csv for TestRef gaps
Verify acceptance criteria for each requirement
Report validation results in traceability.csv Status column

For Stakeholders

Read risk-register.md for project risks
Review implementation roadmap for timeline
Check success metrics in index.md
Provide feedback on assumptions in assumptions.md

📝 Maintenance

Updating Requirements

Propose change via GitHub issue
Change control board reviews impact
Update requirement document
Update traceability.csv if REQ-ID affected
Update risk-register.md if new risks
Increment version number
Update CHANGELOG in index.md

Adding Requirements

Assign next sequential REQ-ID in category
Document in appropriate spec file
Add row to traceability.csv
Update totals in index.md and this README
Assess risks and update risk-register.md if needed

Retiring Requirements

Mark Status as "Deprecated" with reason
Keep in spec file for historical record
Update traceability.csv Status column
Update totals in summary tables

📞 Support

Requirements Questions: Create GitHub issue with label requirements
Requirement Clarification: Tag @toms.eisaks in issue
Traceability Updates: Update traceability.csv directly via PR
Change Requests: Use GitHub issue with label change-request

Requirements Package Status: ✅ Complete v2.0.0 Total Documents: 8 files Total Requirements: 85 (71 functional + 14 non-functional) Current Implementation: 16% (14/85 requirements) Ready for: Phase 2 (MCP Server Development)

Virsaitis Requirements v2.0.0 - Comprehensive specification for three-layer AI governance system

15 KiB Raw Permalink Blame History

Virsaitis Requirements Documentation

📋 Overview

📚 Document Structure

Core Requirements

Supporting Documents

🎯 Requirements Categories

REQ-GOV: Governance Core (12 requirements)

REQ-SEC: Security Controls (16 requirements)

REQ-MCP: MCP Server (11 requirements)

REQ-EXT: VS Code Extension (10 requirements)

REQ-AGT: Agent (8 requirements)

REQ-SKL: Skills (5 requirements)

REQ-TEST: Testing & QA (10 requirements)

REQ-NFR: Non-Functional Requirements (14 requirements)

📊 Implementation Status

By Priority

By Category

🚀 Implementation Roadmap

Phase 1: Foundation (Current) ✅ 25% Complete

Phase 2: MCP Server (Next) 🎯 Target: 40% Overall

Phase 3: VS Code Extension (Parallel with Phase 4) 🔮 Target: 60% Overall

Phase 4: Skills (Parallel with Phase 3) 🔮 Target: 70% Overall

Phase 5: Integration & Distribution 🔮 Target: 95% Overall

🔗 Related Documentation

Architecture

Governance Modules

Implementation

✅ How to Use This Documentation

For Product Owners

For Developers

For Testers

For Stakeholders

📝 Maintenance

Updating Requirements

Adding Requirements

Retiring Requirements

📞 Support

15 KiB

Raw Permalink Blame History