# 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](index.md)** | Requirements overview and navigation | - | ✅ Complete |
| **[functional-spec.md](functional-spec.md)** | Functional requirements REQ-GOV, REQ-SEC | 28 | ✅ Complete |
| **[functional-spec-part2.md](functional-spec-part2.md)** | REQ-MCP, REQ-EXT, REQ-AGT, REQ-SKL, REQ-TEST | 43 | ✅ Complete |
| **[nonfunctional-spec.md](nonfunctional-spec.md)** | Performance, scalability, usability NFRs | 14 | ✅ Complete |

### Supporting Documents

| Document | Purpose | Status |
|----------|---------|--------|
| **[traceability.csv](traceability.csv)** | REQ-ID → Implementation → Test mapping | ✅ Complete |
| **[glossary.md](glossary.md)** | Terminology definitions | ✅ Complete |
| **[assumptions.md](assumptions.md)** | Documented assumptions with validation plans | ✅ Complete |
| **[risk-register.md](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**:
- [x] Agent v3.0 complete (262 lines, attention-optimized)
- [x] 11 governance modules complete (v3.0 formatted)
- [x] Definition library in .github/ (protected)
- [x] Requirements documentation complete
- [x] 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

---

## 🔗 Related Documentation

### Architecture
- [5-Component Architecture](../../virsaitis-documentation/5-COMPONENT-ARCHITECTURE.md) - System design

### Governance Modules
- [Core Policies](../../.github/copilot-modules/core-policies.md) - TIER system
- [Agent Standards](../../.github/copilot-modules/agent-standards.md) - Atomic sentences
- [MCP Standards](../../.github/copilot-modules/mcp-standards.md) - TypeScript patterns
- [Extension Standards](../../.github/copilot-modules/extension-standards.md) - VS Code API
- [Skills Standards](../../.github/copilot-modules/skills-standards.md) - SKILL.md format
- [Development Workflow](../../.github/copilot-modules/development-workflow.md) - 11-step discovery
- [Security Controls](../../.github/copilot-modules/security-controls.md) - Security patterns
- [Requirements Engineering](../../.github/copilot-modules/requirements-engineering.md) - REQ-ID format
- [Testing Quality](../../.github/copilot-modules/testing-quality.md) - Test standards
- [Integration Patterns](../../.github/copilot-modules/integration-patterns.md) - Component interaction
- [Distribution Deployment](../../.github/copilot-modules/distribution-deployment.md) - Packaging

### Implementation
- [Agent Source](../../.github/agents/Virsaitis.agent.md) - Agent.md source
- [MCP Server](../../virsaitis-mcp/) - TypeScript implementation (TBD)
- [VS Code Extension](../../virsaitis-extension/) - Extension implementation (TBD)
- [Skills](../../.github/skills/) - Domain-specific rules (TBD)

---

## ✅ How to Use This Documentation

### For Product Owners
1. Read [index.md](index.md) for high-level overview
2. Review implementation status by phase
3. Monitor [traceability.csv](traceability.csv) for progress
4. Assess [risk-register.md](risk-register.md) monthly

### For Developers
1. Read relevant requirements category (REQ-GOV, REQ-MCP, etc.)
2. Check [traceability.csv](traceability.csv) for implementation files
3. Consult [glossary.md](glossary.md) for terminology
4. Review [assumptions.md](assumptions.md) for validation needs
5. Update traceability.csv ImplementationRef when implementing
6. Update traceability.csv TestRef when writing tests

### For Testers
1. Read REQ-TEST requirements for test strategy
2. Check [traceability.csv](traceability.csv) for TestRef gaps
3. Verify acceptance criteria for each requirement
4. Report validation results in traceability.csv Status column

### For Stakeholders
1. Read [risk-register.md](risk-register.md) for project risks
2. Review implementation roadmap for timeline
3. Check success metrics in [index.md](index.md)
4. Provide feedback on assumptions in [assumptions.md](assumptions.md)

---

## 📝 Maintenance

### Updating Requirements
1. Propose change via GitHub issue
2. Change control board reviews impact
3. Update requirement document
4. Update [traceability.csv](traceability.csv) if REQ-ID affected
5. Update [risk-register.md](risk-register.md) if new risks
6. Increment version number
7. Update CHANGELOG in index.md

### Adding Requirements
1. Assign next sequential REQ-ID in category
2. Document in appropriate spec file
3. Add row to [traceability.csv](traceability.csv)
4. Update totals in [index.md](index.md) and this README
5. Assess risks and update [risk-register.md](risk-register.md) if needed

### Retiring Requirements
1. Mark Status as "Deprecated" with reason
2. Keep in spec file for historical record
3. Update traceability.csv Status column
4. 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*