calorie-counter/.github/copilot-modules/requirements-engineering.md

Every functional change needs a REQ-ID. Search virsaitis-requirements/ first. Do not invent requirements.

Requirements Engineering - Virsaitis

Module: Requirements Engineering Load: When implementing features, updating traceability Version: 3.0.0 Updated: 2026-02-17

---

🎯 Purpose

Defines REQ-ID format, traceability management, and requirement lifecycle for all Virsaitis development.

---

🤖 Machine Policy

[REQ_ID_FORMAT]
PATTERN=^REQ-[A-Z]{2,4}-[0-9]{3}$
INVENTION=prohibited
VALIDATION=mandatory
TRACEABILITY=required

[LIFECYCLE]
CREATE_REQUIREMENT → IMPLEMENT → TEST → TRACE → VERIFY

[TRACEABILITY]
CSV_FILE=virsaitis-development/virsaitis-requirements/traceability.csv
UPDATE_ON_IMPLEMENTATION=required
UPDATE_ON_TEST_CREATION=required

---

📋 REQ-ID Format (TIER-1)

Structure

PATTERN: REQ-[CATEGORY]-[NUMBER]

REGEX: ^REQ-[A-Z]{2,4}-[0-9]{3}$

EXAMPLES:

• REQ-GOV-001 - Governance Core requirement #1
• REQ-SEC-015 - Security Controls requirement #15
• REQ-MCP-003 - MCP Server feature #3

Categories

Category	Code	Purpose	Example
Governance	GOV	Core governance rules	REQ-GOV-001
Security	SEC	Security controls	REQ-SEC-012
MCP	MCP	MCP Server features	REQ-MCP-005
Extension	EXT	Extension features	REQ-EXT-008
Agent	AGT	Agent capabilities	REQ-AGT-004
Skills	SKL	Agent Skills	REQ-SKL-002
Testing	TEST	Testing requirements	REQ-TEST-007
NFR	NFR	Non-Functional	REQ-NFR-010

Number Assignment

FORMAT: 3 digits with leading zeros

✅ GOOD:

• REQ-GOV-001
• REQ-GOV-010
• REQ-GOV-100

❌ BAD:

• REQ-GOV-1 (missing leading zeros)
• REQ-GOV-1000 (too many digits, split category)

Never Invent REQ-IDs

RULE: AI must NEVER create REQ-IDs

WHY:

• REQ-IDs managed by humans
• Traceability requires authority
• Invented IDs create confusion
• Audit trail must be accurate

IF NO REQ-ID EXISTS:

RESPONSE: "REQUIREMENT_NOT_FOUND: No REQ-ID for this feature"

STOP: Do not invent REQ-ID
REQUEST: User create requirement first
SUGGEST: Check virsaitis-development/virsaitis-requirements/

---

📂 Requirements Structure

Directory Organization

virsaitis-development/virsaitis-requirements/
├── index.md                      (requirements overview)
├── functional-spec.md            (functional requirements)
├── nonfunctional-spec.md         (NFRs)
├── security-controls.md          (security requirements)
├── testing-requirements.md       (test requirements)
├── glossary.md                   (terminology)
├── assumptions.md                (assumptions log)
├── risk-register.md              (risks and mitigations)
├── traceability.csv              (REQ-ID → Implementation mapping)
└── archive/                      (deprecated requirements)

Requirement Document Format

STRUCTURE:

## REQ-GOV-001: Protected File Modification

**Priority**: TIER-0 (Safety-Critical)
**Category**: Governance
**Status**: Approved
**Created**: 2026-02-17
**Updated**: 2026-02-17

### Description

The system MUST prevent modification of protected files without explicit approval.

Protected files include:
- `.github/copilot-instructions.md`
- `.github/copilot-modules/**/*.md`
- `.github/agents/Virsaitis.agent.md`
- `virsaitis-development/virsaitis-requirements/**`

### Rationale

Protected files control governance enforcement.
Unauthorized modification bypasses all safety controls.
Preventing modification maintains system integrity.

### Acceptance Criteria

1. GIVEN protected file modification attempted
   WHEN governance validation runs
   THEN operation is BLOCKED

2. GIVEN non-protected file modification
   WHEN governance validation runs
   THEN operation is ALLOWED

3. GIVEN protected file modification with override token
   WHEN governance validation runs
   THEN operation is ALLOWED with audit log

### Dependencies

- REQ-GOV-002 (TIER Definition)
- REQ-MCP-005 (File Validation Tool)

### Implementation Reference

- `virsaitis-mcp/src/governance/validator.ts`
- `virsaitis-extension/src/governance/file-interceptor.ts`

### Test Reference

- `virsaitis-mcp/tests/governance/validator.test.ts`
- `virsaitis-extension/test/suite/governance.test.ts`

### Verification

```bash
# Test protected file modification
npm test -- --grep "should block protected file"

---

## 🔗 Traceability Management (TIER-1)

### traceability.csv Format

**COLUMNS**:
```csv
REQ_ID,Description,Priority,ImplementationRef,TestRef,Status
REQ-GOV-001,"Protected file modification",TIER-0,"mcp/src/governance/validator.ts#L45","mcp/tests/governance/validator.test.ts#L12",Implemented
REQ-SEC-012,"Secret scanning",TIER-0,"mcp/src/security/scanner.ts#L23,extension/src/commands/scan.ts#L10","mcp/tests/security/scanner.test.ts#L8",Implemented
REQ-MCP-005,"File validation tool",TIER-1,"mcp/src/tools/validate-operation.ts#L15","mcp/tests/tools/validate-operation.test.ts#L5",Implemented

FIELDS:

• REQ_ID: Requirement identifier
• Description: Short requirement description (50 chars max)
• Priority: TIER-0, TIER-1, TIER-2, or TIER-3
• ImplementationRef: File paths with line numbers (comma-separated)
• TestRef: Test file paths with line numbers (comma-separated)
• Status: Draft, Approved, Implemented, Verified, Deprecated

Update Traceability

WHEN TO UPDATE:

1. Requirement implemented → Add ImplementationRef
2. Tests written → Add TestRef
3. Requirement status changes → Update Status
4. Implementation moved → Update ImplementationRef

HOW TO UPDATE:

# 1. Read current traceability.csv
cat virsaitis-development/virsaitis-requirements/traceability.csv

# 2. Find REQ-ID row

# 3. Update ImplementationRef column
# Example: "mcp/src/governance/validator.ts#L45"

# 4. Update TestRef column
# Example: "mcp/tests/governance/validator.test.ts#L12"

# 5. Update Status column
# Example: "Implemented"

# 6. Save file

# 7. Commit with message referencing REQ-ID
git commit -m "feat(mcp): Implement file validation

Implements: REQ-MCP-005"

---

🔄 Requirement Lifecycle

Lifecycle States

DRAFT → REVIEW → APPROVED → IMPLEMENTED → VERIFIED → (DEPRECATED)

DRAFT:

• Initial creation
• Under discussion
• May change significantly

REVIEW:

• Ready for stakeholder review
• Acceptance criteria defined
• Dependencies identified

APPROVED:

• Approved for implementation
• REQ-ID assigned officially
• Added to traceability.csv

⚡ CHECKPOINT — Does this requirement have acceptance criteria? Use Given-When-Then format.

IMPLEMENTED:

• Code written
• ImplementationRef updated in traceability.csv
• Not yet tested

VERIFIED:

• Tests written and passing
• TestRef updated in traceability.csv
• Ready for release

DEPRECATED:

• No longer applicable
• Moved to archive/
• Marked in traceability.csv

State Transitions

DRAFT → APPROVED:

• Stakeholder approval obtained
• REQ-ID assigned
• Acceptance criteria complete

APPROVED → IMPLEMENTED:

• Code committed
• traceability.csv updated
• CHANGELOG updated

IMPLEMENTED → VERIFIED:

• Tests passing
• Coverage sufficient
• traceability.csv updated

---

📝 Before Implementing Feature

Discovery Workflow

1. USER REQUEST: "Add feature X"
   ↓
2. SEARCH: virsaitis-development/virsaitis-requirements/
   ↓
3. FIND: Relevant REQ-ID (e.g., REQ-MCP-005)
   ↓
4. VALIDATE: REQ-ID format matches regex
   ↓
5. READ: Full requirement document
   ↓
6. UNDERSTAND: Acceptance criteria
   ↓
7. PLAN: Implementation approach
   ↓
8. IMPLEMENT: Write code
   ↓
9. TEST: Write tests matching acceptance criteria
   ↓
10. UPDATE: traceability.csv (ImplementationRef, TestRef)
    ↓
11. COMMIT: Message includes "Implements: REQ-XXX-YYY"

If No REQ-ID Found

RESPONSE PATTERN:

REQUIREMENT_NOT_FOUND

SEARCHED: virsaitis-development/virsaitis-requirements/
QUERY: [search terms used]
RESULT: No matching REQ-ID found

ACTION REQUIRED:
1. Create requirement document in requirements/
2. Define acceptance criteria
3. Obtain stakeholder approval
4. Assign REQ-ID
5. Add to traceability.csv
6. Then implement feature

ALTERNATIVE:
- Feature may be out of scope
- Check: Does this align with Virsaitis mission?

AI Requirement Creation Policy

WHEN AI MAY CREATE REQUIREMENTS: AI may create requirement documents when the user provides sufficient input context. User must state the need, scope, and acceptance intent. AI drafts the requirement following REQ-ID format.

WORKFLOW:

1. User describes feature need with context
2. AI searches existing requirements for overlap
3. AI proposes REQ-ID and drafts document
4. User reviews and approves before commit
5. AI updates traceability.csv

CONSTRAINTS:

• AI must never invent requirements without user input
• AI must check for duplicate REQ-IDs before assignment
• Draft requirements are PROPOSED status until user approval
• Requirement scope must align with Virsaitis mission
• Discuss: Should this be a requirement?

---

## ✅ Acceptance Criteria

### Format

**USE GIVEN-WHEN-THEN**:

GIVEN [initial context] WHEN [action occurs] THEN [expected outcome]

### Examples

**GOOD ACCEPTANCE CRITERIA**:

AC1: Protected File Blocking GIVEN user attempts to modify .github/copilot-instructions.md WHEN MCP validation tool runs THEN operation is BLOCKED with TIER-0 message

AC2: Non-Protected File Allowed GIVEN user attempts to modify src/my-file.ts WHEN MCP validation tool runs THEN operation is ALLOWED without warnings

AC3: Audit Logging GIVEN protected file modification attempted WHEN operation is BLOCKED THEN audit log entry is created with timestamp, user, file, reason

**WHY THIS FORMAT**:
- Testable (can write automated test directly)
- Unambiguous (clear pass/fail)
- Complete (covers happy path and edge cases)

---

## 🧪 Testing Requirements

### Test Coverage per Requirement

**REQUIREMENT → TESTS MAPPING**:
- Each requirement MUST have tests
- Each acceptance criterion → At least one test
- TIER-0/TIER-1 → Multiple test cases (happy path + edge cases)
- TIER-2/TIER-3 → Minimum one test case

**TEST NAMING CONVENTION**:
```typescript
describe('REQ-GOV-001: Protected File Modification', () => {
  describe('AC1: Protected File Blocking', () => {
    it('should block modification of copilot-instructions.md', () => {
      // Test implementation
    });

    it('should block modification of agent files', () => {
      // Test implementation
    });
  });

  describe('AC2: Non-Protected File Allowed', () => {
    it('should allow modification of source files', () => {
      // Test implementation
    });
  });
});

---

⚡ CHECKPOINT — Did you search existing requirements before creating new ones? Avoid duplicate REQ-IDs.

📊 Requirement Metrics

Coverage Metrics

MANDATORY TARGET: 100% of MUST requirements implemented and tested

CALCULATE:

# Count total requirements
total=$(grep -c "^REQ-" traceability.csv)

# Count implemented requirements
implemented=$(grep -c ",Implemented," traceability.csv)

# Calculate percentage
coverage=$((implemented * 100 / total))

echo "Requirement coverage: $coverage%"

QUALITY GATES:

• TIER-0: 100% implemented and verified (no exceptions)
• TIER-1: 100% implemented, ≥95% verified
• TIER-2: ≥80% implemented
• TIER-3: Best effort

---

💡 Best Practices

Requirement Writing

GOOD REQUIREMENT:

• Clear and testable
• One concept per requirement
• Uses "MUST", "SHOULD", or "MAY" (RFC 2119)
• Includes rationale (why)
• Has acceptance criteria
• References dependencies

BAD REQUIREMENT:

• Vague ("The system should be good")
• Multiple concepts mixed
• No acceptance criteria
• No clear pass/fail

Traceability Maintenance

KEEP CSV UP TO DATE:

• Update immediately when implementing
• Add TestRef when tests written
• Update Status when verified
• Review quarterly for accuracy

VERIFY REFERENCES:

• ImplementationRef points to actual code
• Test Ref points to actual tests
• Line numbers are approximate (code changes)
• Update refs when code moves

---

📚 Quick Reference

Aspect	Standard	Location
REQ-ID Format	REQ-[CAT]-[NUM]	All requirements
Traceability	CSV file	requirements/traceability.csv
Acceptance Criteria	Given-When-Then	Requirement docs
Test Coverage	100% MUST requirements	Per REQ-ID
Status	Draft → Verified	Lifecycle

---

Requirements Engineering Module v3.0.0 Traceability and requirement lifecycle management

---

Key Rules From This Module

• Every functional change needs a REQ-ID. Format: REQ-[CAT]-[NUM].
• Search existing requirements before creating new ones. Avoid duplicates.
• Acceptance criteria use Given-When-Then format. Each criterion maps to at least one test.
• AI may draft requirements when user provides context, but drafts need user approval.
• Definitions: .github/virsaitis-definition-library.md

Return to hub: .github/copilot-instructions.md