CHORUS-TRACE-003: Add Requirement Traceability (@goal: tags) Across All Source Files #3

New Issue

tony · 2025-09-21T06:25:55Z

tony commented

2025-09-21 06:25:55 +00:00

Problem

No @goal: tags found in any Go source files in the CHORUS project, indicating missing requirement traceability throughout the codebase. This violates the development plan requirement for traceable implementations.

Scope

All Go source files in CHORUS project lacking @goal: tags

Requirements from Development Plan

Per the e2e harness and traceability documentation, all code must include:

@goal: tags linking to specific requirements
Comments referencing roadmap phases (SEC-SLURP, SEC-SHHH, SEC-COOEE)
Traceable connections between goals → code → tests → runtime evidence

Missing Traceability Examples

SLURP Components

pkg/slurp/slurp.go - All functions need @goal: SEC-SLURP-* tags
pkg/slurp/interfaces.go - Interface definitions need requirement links
pkg/slurp/leader/ - Leadership components need roadmap phase tags

DHT Components

internal/dht/ - All DHT functionality needs @goal: DHT-* tags
Storage layer needs traceability to persistence requirements

P2P Infrastructure

internal/p2p/ - Network layer needs @goal: P2P-* tags
Mesh management needs requirement links

Implementation Requirements

Tag Format

// @goal: CHORUS-REQ-001, SEC-SLURP-1.1 - Brief description
// WHY: Explanation of requirement fulfillment
func FunctionName() {
    // implementation
}

Required @goal: Tag Categories

CHORUS-REQ-* - Basic functionality requirements
SEC-SLURP-* - SLURP roadmap phase requirements
SEC-SHHH-* - SHHH secrets management requirements
SEC-COOEE-* - COOEE mesh monitoring requirements
CHORUS-OBS-* - Observability requirements
CHORUS-PER-* - Performance requirements

Enforcement Integration

Once implemented, this supports:

Pre-commit hooks checking for @goal: tags
CI Requirements Traceability Matrix (RTM) generation
Runtime telemetry with goal.ids attributes
Grafana "Goal Drill-Down" dashboards

Priority

Medium - Process improvement for maintainability and auditability

Requirement Traceability

@goal: CHORUS-TRACE-003, E2E-TRACE - Development plan compliance

Dependencies

Development plan e2e harness documentation
Roadmap phase definitions (SEC-SLURP, SEC-SHHH, SEC-COOEE)
Future: speclint tool for automated validation

Implementation Approach

Audit existing functions - Identify all public functions and key private functions
Map to requirements - Link each function to specific roadmap phases or requirements
Add @goal: tags - Use consistent format with requirement IDs
Document rationale - Include WHY comments explaining requirement fulfillment
Test integration - Verify tags work with future RTM tooling

Acceptance Criteria

All public functions have @goal: tags with valid requirement IDs
Key private functions have requirement traceability
Tags reference valid roadmap phases (SEC-SLURP, etc.)
Comments explain requirement fulfillment rationale
Consistent tag format across all files
Tags support future speclint validation
Integration with OpenTelemetry goal.ids attributes

## Problem No `@goal:` tags found in any Go source files in the CHORUS project, indicating missing requirement traceability throughout the codebase. This violates the development plan requirement for traceable implementations. ## Scope **All Go source files** in CHORUS project lacking `@goal:` tags ## Requirements from Development Plan Per the e2e harness and traceability documentation, all code must include: - `@goal:` tags linking to specific requirements - Comments referencing roadmap phases (SEC-SLURP, SEC-SHHH, SEC-COOEE) - Traceable connections between goals → code → tests → runtime evidence ## Missing Traceability Examples ### SLURP Components - `pkg/slurp/slurp.go` - All functions need `@goal: SEC-SLURP-*` tags - `pkg/slurp/interfaces.go` - Interface definitions need requirement links - `pkg/slurp/leader/` - Leadership components need roadmap phase tags ### DHT Components - `internal/dht/` - All DHT functionality needs `@goal: DHT-*` tags - Storage layer needs traceability to persistence requirements ### P2P Infrastructure - `internal/p2p/` - Network layer needs `@goal: P2P-*` tags - Mesh management needs requirement links ## Implementation Requirements ### Tag Format ```go // @goal: CHORUS-REQ-001, SEC-SLURP-1.1 - Brief description // WHY: Explanation of requirement fulfillment func FunctionName() { // implementation } ``` ### Required @goal: Tag Categories 1. **CHORUS-REQ-*** - Basic functionality requirements 2. **SEC-SLURP-*** - SLURP roadmap phase requirements 3. **SEC-SHHH-*** - SHHH secrets management requirements 4. **SEC-COOEE-*** - COOEE mesh monitoring requirements 5. **CHORUS-OBS-*** - Observability requirements 6. **CHORUS-PER-*** - Performance requirements ## Enforcement Integration Once implemented, this supports: - Pre-commit hooks checking for `@goal:` tags - CI Requirements Traceability Matrix (RTM) generation - Runtime telemetry with `goal.ids` attributes - Grafana "Goal Drill-Down" dashboards ## Priority **Medium** - Process improvement for maintainability and auditability ## Requirement Traceability @goal: CHORUS-TRACE-003, E2E-TRACE - Development plan compliance ## Dependencies - Development plan e2e harness documentation - Roadmap phase definitions (SEC-SLURP, SEC-SHHH, SEC-COOEE) - Future: speclint tool for automated validation ## Implementation Approach 1. **Audit existing functions** - Identify all public functions and key private functions 2. **Map to requirements** - Link each function to specific roadmap phases or requirements 3. **Add @goal: tags** - Use consistent format with requirement IDs 4. **Document rationale** - Include WHY comments explaining requirement fulfillment 5. **Test integration** - Verify tags work with future RTM tooling ## Acceptance Criteria - [ ] All public functions have `@goal:` tags with valid requirement IDs - [ ] Key private functions have requirement traceability - [ ] Tags reference valid roadmap phases (SEC-SLURP, etc.) - [ ] Comments explain requirement fulfillment rationale - [ ] Consistent tag format across all files - [ ] Tags support future speclint validation - [ ] Integration with OpenTelemetry `goal.ids` attributes

tony added the

bzzz-task

label 2025-09-21 06:32:49 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: tony/CHORUS#3