diff --git a/.github/prompts/repository-audit.prompt.md b/.github/prompts/repository-audit.prompt.md index 527892d..f825e35 100644 --- a/.github/prompts/repository-audit.prompt.md +++ b/.github/prompts/repository-audit.prompt.md @@ -1,136 +1,1900 @@ ---- -mode: agent -description: > - Read-only audit workflow for the PoKeysHal repository. Assesses traceability, - C99/PoKeysLib structure, async boundaries, HAL integration, RT constraints, - protocol evidence, test layers, HIL fixture gating, and documentation consistency. -applyTo: - - "**/.github/**/*.md" - - "**/docs/**/*.md" - - "**/README.md" ---- - -# Repository Audit – PoKeysHal - -Focused read-only audit of the PoKeysHal repository. -Produce findings and a corrective plan only. - -Do not edit source files, issue templates, customization files, or tests. -Do not execute build commands, hardware operations, or CI workflows. -Do not redesign or replace the approved HIL baseline from issues #138 and #139. -Do not duplicate complete content from agents, instructions, or skills. - -## Audit areas - -### 1. Issue and acceptance-criterion traceability - -- Confirm issue types StR, REQ-F, REQ-NF, ADR, ARC-C, TEST exist with labels. -- Confirm REQ issues link upward to StR; TEST issues carry `Verifies: #N`. -- Confirm source uses `/* Implements: #N (REQ-F-xxx) */`; tests use `/* Verifies: #N */`. -- Confirm PRs use `Fixes #N` or `Implements #N`. -- Flag orphaned requirements, untraced tests, and PRs without an issue link. - -### 2. C99 and PoKeysLib structure - -- Confirm file responsibilities match `c-architecture-realtime.instructions.md`. -- Flag VLA, `malloc`, `calloc`, `realloc`, or unbounded loops on any RT-reachable path. -- Flag use of prohibited C features (dynamic allocation, blocking calls, non-constant - bounds) in files included on RT-reachable call paths. - -### 3. Async infrastructure / subsystem / integration-shell boundaries - -- `PoKeysLibAsync.c`: mailbox and dispatch infrastructure only — no subsystem logic. -- `PoKeysLib*Async.c`: per-subsystem HAL export, send, parse, and optional scheduler - registration only — no cross-subsystem calls, no transport logic. -- `experimental/pokeys_async.c`: integration shell only — no business logic. -- Report any cross-boundary leakage as a finding with file and line reference. - -### 4. LinuxCNC HAL exports and component integration - -- HAL-visible struct members must use `hal_u32_t`, `hal_s32_t`, `hal_bit_t`, or - `hal_float_t`. Flag any raw C type used where a HAL type is required. -- Confirm pin names follow the documented naming convention. -- Confirm exported pins are updated on every HAL function invocation. -- Confirm the userspace and RT component entry points match the integration shell. - -### 5. Verification layers - -Assess what evidence exists at each layer: - -| Layer | How assessed | -|---|---| -| Compile and link | `bash test_compile.sh`, `make -f Makefile.noqmake` results | -| Unit tests | parsing, conversion, state transitions in `tests/` | -| Protocol tests | command IDs, offsets, retry, timeout coverage | -| Async mailbox tests | mailbox matching, stale response, timeout exhaustion | -| Userspace HAL smoke | `halrun` component load, pin export, basic update | -| RT-environment | LinuxCNC RT load and execution evidence | -| HIL tests | named tests on verified/runnable fixtures | -| Timing validation | measured result against documented threshold | - -Note which layers have no evidence; mark them as gaps. - -### 6. RT-path constraints - -- No blocking calls, dynamic allocation, or unbounded loops on any path reachable - from a LinuxCNC real-time function. -- Claims of RT-safety require RT-validated evidence. A non-blocking appearance or - successful compilation does not constitute RT-validated status. -- Flag any `RT-safe` or equivalent claim without supporting RT-validated evidence. - -### 7. Protocol-specification evidence - -- Each command code, byte offset, mask, and response field must be traceable to the - PoKeys protocol specification (comment, issue, or documented reference). -- Flag undocumented constants, inferred offsets, and values copied from apparently - similar subsystems without a spec citation. - -### 8. HIL fixture gating - -- A fixture must have `runnable: true` and `fixture_status: verified` before - it may be used in automation. -- Draft fixtures must not be treated as verified. -- Use `.github/skills/hil-tdd/references/result-schema.md` for outcome vocabulary: - `HIL-observed`, `HIL-test-executed`, `HIL-verified`. -- A required HIL job that produces zero test results must not be reported as green. - -### 9. Documentation consistency - -- Documentation must describe implemented behavior only. Claims beyond - Implemented/Compiled/Tested are findings unless supported by named evidence. -- Flag documentation that describes planned or aspirational behavior as fact. -- Flag any active customization file (`.github/agents/`, `.github/instructions/`, - `.github/skills/`, `.github/prompts/`) with duplicate or conflicting guidance. -- Each layer has a defined scope: prompts are entry points; agents own role behavior; - instructions own mandatory invariants; skills own detailed repeatable procedures. - -## Evidence and claim vocabulary - -Use these terms consistently in findings: - -| Term | Meaning | -|---|---| -| Implemented | Production behavior exists in source | -| Compiled | Compilation succeeded only | -| Tested | Named tests executed and passed | -| HIL-observed | Exploratory observation recorded as oracle evidence | -| HIL-test-executed | Named HIL test ran to completion | -| HIL-verified | Named HIL test passed on a named fixture at a stated revision | -| RT-validated | Tested in the applicable LinuxCNC RT environment | -| Timing-validated | Measured against a documented threshold with an identified method | - -Claims without corresponding evidence are overstatements; record them as findings. - -## Unavailable checks - -State explicitly which layers could not be assessed and why (no hardware, no RT -kernel, no registered fixture, no CI output). Do not substitute compilation for -hardware or timing validation. - -## Output format - -1. **Findings** — one entry per issue, with: area number, file or issue reference, - observed state, required state, risk level. - -2. **Corrective plan** — prioritized list with recommended issue type (REQ-F, TEST, - ARC-C, or process change) and link to the finding it addresses. +--- +mode: agent +applyTo: + - "**/README.md" + - "**/.github/**/*.md" + - "**/docs/**/*.md" +--- + +# Repository Audit Prompt + +You are a **Software Quality Auditor** following **ISO/IEC/IEEE 12207:2017** and **ISO/IEC/IEEE 29148:2018** standards. + +## 🎯 Objective + +Perform comprehensive audit of existing repository to: +1. **Assess current compliance** with spec-driven development standards +2. **Identify gaps** between current state and template requirements +3. **Generate migration roadmap** with prioritized action items +4. **Estimate effort** required for full compliance +5. **Provide recommendations** for gradual adoption + +## 🔍 Repository Analysis Framework + +### Step 1: Structure Analysis + +**Analyze repository structure against template**: + +#### **Expected Structure** (GitHub Issues-First Template): +``` +project/ +├── README.md # Project overview (references GitHub Issues) +├── docs/ # Supplementary documentation (MUST reference issues) +│ ├── 01-stakeholder-requirements/ # Phase 01 (optional supplementary docs) +│ │ ├── stakeholder-interviews.md # References StR issues via #N +│ │ └── business-case.md # References StR issues via #N +│ ├── 02-requirements/ # Phase 02 (optional supplementary docs) +│ │ └── user-stories.md # References REQ-F issues via #N +│ ├── 03-architecture/ # Phase 03 (C4 diagrams reference ADR/ARC-C) +│ │ ├── diagrams/ # C4 Context, Container, Component +│ │ └── architecture-views.md # References #ADR and #ARC-C issues +│ ├── 04-design/ # Phase 04 (design docs reference #ARC-C) +│ │ ├── components/ # Component designs referencing ARC-C issues +│ │ └── interfaces/ # API specs referencing ARC-C issues +│ ├── 05-implementation/ # Phase 05 (code with issue references) +│ ├── 06-integration/ # Phase 06 (integration docs) +│ ├── 07-verification-validation/ # Phase 07 (test results) +│ ├── 08-transition/ # Phase 08 (deployment docs) +│ └── lifecycle-guide.md # Process documentation +├── .github/ +│ ├── ISSUE_TEMPLATE/ # Issue templates (StR, REQ-F, REQ-NF, ADR, ARC-C, TEST) +│ ├── prompts/ # Copilot prompts +│ └── workflows/ # CI/CD with traceability validation +├── src/ # Source code (docstrings reference issues) +├── tests/ # Test code (tests reference issues) +└── package.json # Dependencies & scripts +``` + +**Key Principle**: GitHub Issues are the single source of truth. Markdown files are OPTIONAL supplementary documentation that MUST reference canonical issues using `#N` syntax. + +#### **Structure Audit Checklist** (GitHub Issues-First): +- [ ] `.github/ISSUE_TEMPLATE/` folder exists with issue templates (StR, REQ-F, REQ-NF, ADR, ARC-C, QA-SC, TEST) +- [ ] GitHub Issues configured with proper labels: + - `type:stakeholder-requirement`, `type:requirement:functional`, `type:requirement:non-functional` + - `type:architecture:decision`, `type:architecture:component`, `type:architecture:quality-scenario` + - `type:test`, `type:bug`, `type:integration`, `type:deployment` + - `phase:01-stakeholder-requirements` through `phase:09-operation-maintenance` + - `priority:p0`, `priority:p1`, `priority:p2`, `priority:p3` + - `status:approved`, `status:in-progress`, `status:blocked` +- [ ] `docs/` folder exists (optional supplementary docs MUST reference issues) +- [ ] `.github/prompts/` folder exists with Issue-Driven prompts +- [ ] Source code organized logically with issue references in docstrings +- [ ] Tests organized and separated from source (test files reference issues) +- [ ] README.md exists and references GitHub Issues workflow +- [ ] Package management files exist (package.json, requirements.txt, etc.) +- [ ] `.github/workflows/` contains CI/CD with traceability validation + +### Step 2: Documentation Analysis + +**Analyze existing documentation against standards**: + +#### **Phase 2A: Copilot-Generated Artifact Detection** +**CRITICAL FOR BROWNFIELD PROJECTS**: Identify and catalog all Copilot-generated documentation for intent recovery. + +**Search Patterns for Copilot Artifacts**: +- [ ] **Copilot Chat Sessions**: `*.copilot-chat.*`, `copilot-*.md`, `.vscode/copilot/` +- [ ] **Copilot-Generated Documentation**: Files with Copilot signatures + - Headers: "Generated by GitHub Copilot", "Copilot Chat Session" + - Timestamps: Recent modifications with AI assistant patterns + - Structure: Q&A format, implementation explanations +- [ ] **Implementation Notes**: `NOTES.md`, `DECISIONS.md`, `ARCHITECTURE.md` with Copilot origins +- [ ] **Comment Patterns**: Code comments with Copilot generation markers + +**Artifact Categorization**: +```markdown +### Copilot Artifact Inventory +**Total Artifacts Found**: [X] + +**Architecture & Design**: +- [file path] - [date] - [topics covered] +- [file path] - [date] - [topics covered] + +**Implementation Discussions**: +- [file path] - [date] - [topics covered] +- [file path] - [date] - [topics covered] + +**Problem-Solution Contexts**: +- [file path] - [date] - [topics covered] +- [file path] - [date] - [topics covered] + +**Staleness Assessment**: +- **Fresh** (< 1 month): [X artifacts] +- **Recent** (1-3 months): [X artifacts] +- **Stale** (3+ months): [X artifacts] +``` + +**Intent Recovery Validation**: +- [ ] **Code-Documentation Alignment**: Cross-reference current code with documented intentions +- [ ] **Decision Context**: Extract architectural decisions and rationale +- [ ] **Problem Context**: Identify original problems being solved +- [ ] **Implementation Alternatives**: Document rejected approaches and reasons + +#### **Phase 2B: Standard Documentation Requirements** + +#### **Phase 01: Stakeholder Requirements (GitHub Issues-Based)** +- [ ] **StR GitHub Issues exist**: Issues with label `type:stakeholder-requirement`, `phase:01-stakeholder-requirements` +- [ ] **Stakeholder identification**: Source stakeholder documented in each StR issue body +- [ ] **Business case**: ROI, justification documented (supplementary docs reference StR issues via #N) +- [ ] **Success criteria**: Measurable outcomes defined in StR issue bodies +- [ ] **Traceability infrastructure**: Issue templates configured, labels set up +- [ ] **Acceptance criteria**: Gherkin format in StR issue bodies + +**Findings Template** (GitHub Issues Audit): +```markdown +### Phase 01 Assessment (GitHub Issues) +**Status**: [COMPLETE ✅ / PARTIAL 🟡 / MISSING 🔴] +**Compliance Score**: [X/10] + +**Found**: +- StR Issues: [count] issues with label `type:stakeholder-requirement` +- Issue Templates: [YES/NO] `.github/ISSUE_TEMPLATE/stakeholder-requirement.yml` +- Labels Configured: [YES/NO] `type:stakeholder-requirement`, `phase:01-stakeholder-requirements` +- Supplementary Docs: [file paths] (audit for #N issue references) + +**Missing**: +- [ ] StR issue template not configured +- [ ] No StR issues created (only file-based docs found) +- [ ] StR issues lack acceptance criteria +- [ ] No proper labels configured + +**Quality Issues**: +- StR issues lack unique titles (format: "StR-XXX: [Title]") +- No source stakeholder documented in issue bodies +- Acceptance criteria missing from StR issues +- Supplementary docs don't reference canonical issues +``` + +#### **Phase 02: System Requirements (GitHub Issues-Based)** +- [ ] **REQ-F GitHub Issues exist**: Issues with label `type:requirement:functional`, `phase:02-requirements` +- [ ] **REQ-NF GitHub Issues exist**: Issues with label `type:requirement:non-functional`, `phase:02-requirements` +- [ ] **Requirements quality**: INVEST criteria documented in issue bodies +- [ ] **Acceptance criteria**: Given-When-Then scenarios in issue bodies +- [ ] **Traceability**: All REQ issues link to parent StR issues via "Traces to: #N" +- [ ] **Requirements completeness**: All scenarios covered, no orphaned requirements +- [ ] **Issue templates configured**: `.github/ISSUE_TEMPLATE/requirement-functional.yml`, `requirement-non-functional.yml` + +#### **Phase 03: Architecture (GitHub Issues-Based)** +- [ ] **ADR GitHub Issues exist**: Issues with label `type:architecture:decision`, `phase:03-architecture` +- [ ] **ARC-C GitHub Issues exist**: Issues with label `type:architecture:component`, `phase:03-architecture` +- [ ] **QA-SC GitHub Issues exist**: Issues with label `type:architecture:quality-scenario`, `phase:03-architecture` +- [ ] **Architecture diagrams**: C4 model diagrams in `docs/03-architecture/diagrams/` reference #ADR and #ARC-C issues +- [ ] **Decision records**: ADR issues document Context, Decision, Alternatives, Consequences +- [ ] **Technology stack**: Documented in ADR issues with rationale +- [ ] **Non-functional requirements**: ADR issues link to REQ-NF issues via "Addresses: #N" +- [ ] **Traceability**: ADR and ARC-C issues link to satisfied requirements + +#### **Phase 04: Detailed Design (Issue-Referenced)** +- [ ] **Design specifications**: ARC-C issues updated with detailed design in issue bodies/comments +- [ ] **API documentation**: OpenAPI, GraphQL schemas in `docs/04-design/interfaces/` reference #ARC-C issues +- [ ] **Data models**: Database schemas in `docs/04-design/data-models/` reference #ARC-C issues +- [ ] **Algorithm specifications**: Complex logic documented in ARC-C issue bodies +- [ ] **Error handling**: Exception scenarios designed in ARC-C issues +- [ ] **Supplementary design docs**: All files in `docs/04-design/` MUST reference canonical #ARC-C issues + +#### **Phase 05: Implementation (Code with Issue Traceability)** +- [ ] **Source code**: Well-organized, following standards +- [ ] **Code documentation**: Docstrings reference implementing issues ("Implements: #N", "Architecture: #N", "Verifies: #N") +- [ ] **Pull Requests**: All PRs link to issues via "Fixes #N" or "Implements #N" +- [ ] **Configuration**: Environment configs, deployment settings +- [ ] **Dependencies**: Managed, documented, up-to-date +- [ ] **Build system**: Automated build, package management +- [ ] **Code traceability audit**: Run grep search for issue references in code + +#### **Phase 06-07: Integration & Testing (GitHub Issues-Based)** +- [ ] **TEST GitHub Issues exist**: Issues with label `type:test`, `test-type:unit|integration|e2e|acceptance` +- [ ] **Test traceability**: All TEST issues link to verified requirements via "Verifies: #N (REQ-F-XXX)" +- [ ] **Test coverage**: >80% unit test coverage +- [ ] **Test quality**: AAA pattern, meaningful test names +- [ ] **Test automation**: CI/CD integration +- [ ] **Test documentation**: TEST issue bodies document test approach, expected results + +#### **Phase 07: Deployment** +- [ ] **Deployment guide**: Step-by-step deployment process +- [ ] **Environment configuration**: Dev, staging, prod configs +- [ ] **Infrastructure as code**: Terraform, CloudFormation, etc. +- [ ] **Monitoring**: Logging, metrics, alerting setup +- [ ] **Operations guide**: Troubleshooting, maintenance + +### Step 3: Code Quality Analysis + +**Analyze code against best practices**: + +#### **Code Organization** +```bash +# Analyze directory structure +find . -type f -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.java" | head -20 + +# Check for separation of concerns +ls -la src/ +ls -la tests/ +``` + +#### **Code Standards Compliance** +- [ ] **Naming conventions**: Consistent, meaningful names +- [ ] **Code structure**: SOLID principles, clean architecture +- [ ] **Error handling**: Proper exception handling +- [ ] **Security**: No hardcoded secrets, input validation +- [ ] **Performance**: No obvious performance issues + +#### **Test Coverage Analysis** +```bash +# Check test coverage (examples for different languages) +npm run test:coverage # Node.js +pytest --cov=src # Python +mvn test jacoco:report # Java +go test -cover ./... # Go +``` + +**Coverage Standards**: +- **Critical paths**: 95-100% coverage +- **Business logic**: 85-95% coverage +- **Integration points**: 80-90% coverage +- **UI components**: 70-80% coverage +- **Overall target**: >80% coverage + +### Step 4: Process Compliance Analysis + +**Analyze development process compliance**: + +#### **Version Control** +- [ ] **Git history**: Meaningful commit messages +- [ ] **Branching strategy**: Clear branching model +- [ ] **Code reviews**: Pull request process +- [ ] **Release management**: Tagging, versioning + +#### **CI/CD Pipeline** +- [ ] **Automated builds**: Build on every commit +- [ ] **Automated testing**: Tests run in CI +- [ ] **Quality gates**: Linting, security scans +- [ ] **Deployment automation**: Automated deployment process + +#### **Documentation Maintenance** +- [ ] **Up-to-date docs**: Documentation reflects current state +- [ ] **API documentation**: Auto-generated from code +- [ ] **Change logs**: Record of changes and releases +- [ ] **Contributing guide**: Guidelines for contributors + +### Step 5: Traceability Analysis + +**Analyze traceability between artifacts**: + +#### **Forward Traceability** +- **Business Needs** → **Stakeholder Requirements** → **System Requirements** → **Design** → **Code** → **Tests** + +#### **Backward Traceability** +- **Tests** → **Code** → **Design** → **System Requirements** → **Stakeholder Requirements** → **Business Needs** + +**Traceability Assessment**: +```markdown +### Traceability Matrix Analysis + +| From | To | Status | Coverage | Quality | +|------|-------|--------|----------|---------| +| Business Needs | Stakeholder Req | 🔴 Missing | 0% | N/A | +| Stakeholder Req | System Req | 🟡 Partial | 60% | Low | +| System Req | Design | 🔴 Missing | 0% | N/A | +| Design | Code | 🟡 Partial | 40% | Medium | +| Code | Tests | ✅ Good | 78% | High | + +**Critical Gaps**: +- No business requirements documentation +- Missing system requirements specification +- No design documentation +- Partial code-to-requirements traceability +``` + +## 📊 Comprehensive Audit Report Template + +```markdown +# Repository Audit Report + +**Date**: [Audit Date] +**Repository**: [Repository Name] +**Auditor**: GitHub Copilot +**Template Version**: [Template Version] + +## Executive Summary + +**Overall Compliance Score**: [X/100] +**Readiness for Spec-Driven Development**: [HIGH 🟢 / MEDIUM 🟡 / LOW 🔴] + +### Key Findings +- ✅ **Strengths**: [Top 3 strengths] +- ⚠️ **Improvement Areas**: [Top 3 areas needing work] +- 🔴 **Critical Gaps**: [Top 3 critical missing elements] + +### Migration Effort Estimate +- **High Priority (Must Fix)**: [X] weeks +- **Medium Priority (Should Fix)**: [Y] weeks +- **Low Priority (Nice to Have)**: [Z] weeks +- **Total Estimated Effort**: [X+Y+Z] weeks + +## Detailed Assessment + +### 1. Repository Structure Analysis + +**Score**: [X/10] + +#### Current Structure +``` +[Current directory tree - first 3 levels] +``` + +#### Compliance Analysis + +| Expected | Current | Status | Gap | +|----------|---------|--------|-----| +| docs/01-stakeholder-requirements/ | [path or MISSING] | ✅/🟡/🔴 | [description] | +| docs/02-requirements/ | [path or MISSING] | ✅/🟡/🔴 | [description] | +| docs/03-architecture/ | [path or MISSING] | ✅/🟡/🔴 | [description] | +| .github/prompts/ | [path or MISSING] | ✅/🟡/🔴 | [description] | + +#### Recommendations +1. **Create missing phase directories**: [Specific actions] +2. **Reorganize existing docs**: [Specific actions] +3. **Set up prompt library**: [Specific actions] + +### 2. Documentation Compliance + +#### Phase-by-Phase Analysis + +##### Phase 01: Stakeholder Requirements +**Score**: [X/10] +**Status**: [COMPLETE ✅ / PARTIAL 🟡 / MISSING 🔴] + +**Found Documentation**: +- Business requirements: [files found] +- User stories: [files found] +- Stakeholder info: [files found] + +**Quality Assessment**: +- Stakeholder identification: [X/10] +- Business case documentation: [X/10] +- Success criteria definition: [X/10] +- Requirements traceability: [X/10] + +**Critical Gaps**: +- [ ] No formal stakeholder requirements specification +- [ ] Missing business case with ROI analysis +- [ ] Undefined success criteria and metrics +- [ ] No stakeholder approval process + +**Migration Actions**: +1. Use `project-kickoff.prompt.md` to gather stakeholder requirements +2. Create formal stakeholder requirements specification +3. Document business case and success criteria + +##### Phase 02: System Requirements +**Score**: [X/10] +**Status**: [COMPLETE ✅ / PARTIAL 🟡 / MISSING 🔴] + +**Found Documentation**: +- Requirements specs: [files found] +- User stories: [files found] +- Acceptance criteria: [files found] + +**Quality Assessment**: +- Requirements completeness: [X/10] +- Requirements quality (INVEST): [X/10] +- Acceptance criteria: [X/10] +- Traceability: [X/10] + +**Migration Actions**: +1. Use `code-to-requirements.prompt.md` to reverse-engineer requirements +2. Use `requirements-elicit.prompt.md` to fill gaps +3. Use `requirements-refine.prompt.md` to improve quality + +##### Phase 03: Architecture +**Score**: [X/10] +**Status**: [COMPLETE ✅ / PARTIAL 🟡 / MISSING 🔴] + +**Found Documentation**: +- Architecture docs: [files found] +- Design diagrams: [files found] +- Decision records: [files found] + +**Existing Architecture Analysis**: + +#### **1. Architecture Pattern Detection** +```bash +# Analyze codebase structure to identify architecture patterns +find src -type f -name "*.js" -o -name "*.ts" -o -name "*.py" | xargs grep -l "controller\|service\|repository\|model" +find . -name "*Controller*" -o -name "*Service*" -o -name "*Repository*" +ls -la src/components src/services src/models src/controllers 2>/dev/null +``` + +**Detected Patterns**: +- **MVC**: ✅/🔴 Controllers, Models, Views identified +- **Layered Architecture**: ✅/🔴 Presentation, Business, Data layers +- **Microservices**: ✅/🔴 Service boundaries and communication +- **Event-Driven**: ✅/🔴 Event handlers and publishers +- **Hexagonal/Clean**: ✅/🔴 Ports and adapters structure +- **Domain-Driven Design**: ✅/🔴 Domain entities and services + +**Pattern Consistency Score**: [X/10] +**Pattern Clarity Score**: [X/10] + +#### **2. Architecture Quality Assessment** + +**Structural Analysis**: +```typescript +// Example analysis for Node.js/TypeScript project +// Check dependency directions and layers +interface ArchitectureLayer { + name: string; + dependencies: string[]; + violations: string[]; +} + +const layers: ArchitectureLayer[] = [ + { + name: "Controllers", + dependencies: ["Services"], // Should only depend on Services + violations: ["Direct database access", "Business logic in controllers"] + }, + { + name: "Services", + dependencies: ["Repositories", "Domain"], + violations: ["HTTP dependencies", "UI coupling"] + }, + { + name: "Repositories", + dependencies: ["Database", "Domain"], + violations: ["Business logic in data layer"] + } +]; +``` + +**Architecture Violations Detection**: +- **Circular Dependencies**: [Count] violations found + ```bash + # Check for circular deps (Node.js example) + npx madge --circular src/ + ``` +- **Layer Violations**: [Count] violations found + - Controllers calling Repositories directly + - Data layer containing business logic + - UI components in business layer +- **Coupling Issues**: [Count] violations found + - High coupling between modules + - Tight coupling to external services + - Database schema leaked to business layer + +#### **3. Architecture Discrepancy Analysis** + +**Intended vs Actual Architecture**: + +| Aspect | Intended (from docs/ADRs) | Actual (from code) | Discrepancy | Intentional? | +|--------|---------------------------|-------------------|-------------|--------------| +| Database Access | Repository Pattern | Direct ORM calls | 🔴 High | ❓ Unclear | +| Service Communication | Event-driven | Direct HTTP calls | 🟡 Medium | ✅ Documented | +| Error Handling | Centralized | Scattered try-catch | 🔴 High | 🔴 Accidental | +| Authentication | JWT with refresh | Basic JWT only | 🟡 Medium | ⚠️ Simplified | +| Caching Strategy | Redis distributed | In-memory only | 🔴 High | ❓ Unknown | + +#### **4. Architecture Intent Analysis** + +**Decision Traceability**: +```bash +# Check for ADRs and architectural decisions +find . -name "*ADR*" -o -name "*decision*" -o -name "*architecture*" | grep -i record +git log --grep="architecture\|refactor\|redesign" --oneline +``` + +**Intent Assessment Framework**: + +**✅ Intentional Architecture Decisions** (Clear documentation/rationale): +- Decision has corresponding ADR +- Consistent implementation across codebase +- Recent commits reference the decision +- Team discussion in PR/issue comments + +**❓ Unclear Intent** (Needs investigation): +- Partial implementation of pattern +- Inconsistent application across modules +- No documentation but appears deliberate +- Mixed old/new patterns coexisting + +**🔴 Accidental Inconsistencies** (Likely unintentional): +- Violates documented architecture +- Inconsistent with established patterns +- Quick fixes without pattern consideration +- Copy-paste code with different patterns + +#### **5. Technical Debt & Problem Areas** + +**Code Smell Detection**: +```bash +# Static analysis for common issues +npx eslint src/ --ext .js,.ts | grep -E "(complexity|cognitive|duplicate)" +flake8 src/ --max-complexity=10 # Python +sonarqube-scanner # Comprehensive analysis +``` + +**Critical Problem Areas**: + +**🔴 High Severity**: +- **God Classes**: [Count] classes >500 lines + - `UserService.js` (847 lines) - Handles auth, profile, notifications + - `OrderController.py` (623 lines) - Mixed business/presentation logic +- **Circular Dependencies**: [Count] modules + - `auth.service` ↔ `user.service` ↔ `notification.service` +- **Security Anti-patterns**: [Count] issues + - Hardcoded secrets in configuration files + - SQL injection vulnerabilities in legacy queries + - Missing input validation on 12 endpoints + +**🟡 Medium Severity**: +- **Performance Bottlenecks**: [Count] issues + - N+1 queries in user profile loading + - Missing database indexes on frequent queries + - Inefficient serialization in API responses +- **Maintenance Issues**: [Count] issues + - Dead code in deprecated modules (23% of codebase) + - Inconsistent error handling patterns + - Missing test coverage on critical paths (45% coverage) + +**⚠️ Design Issues**: +- **Violation of SOLID Principles**: + - Single Responsibility: Controllers doing business logic + - Open/Closed: Hardcoded logic without extension points + - Dependency Inversion: Direct dependencies on concrete classes +- **Poor Abstraction**: + - Business logic scattered across layers + - No clear domain boundaries + - Mixed concerns in single modules + +#### **6. Architecture Evolution Analysis** + +**Historical Pattern Changes**: +```bash +# Analyze architecture evolution over time +git log --stat --since="1 year ago" | grep -E "(src/|lib/)" | head -20 +git blame $(find src -name "*.js" | head -10) | cut -d' ' -f1 | sort | uniq -c +``` + +**Evolution Timeline**: +- **Phase 1** (6 months ago): Simple MVC structure +- **Phase 2** (3 months ago): Added service layer, some repositories +- **Phase 3** (1 month ago): Attempted microservices split (incomplete) +- **Current**: Mixed patterns, partial migrations + +**Migration Inconsistencies**: +- Old modules still using direct database access +- New modules follow repository pattern +- API endpoints split between old/new authentication +- Half-migrated from REST to GraphQL + +**Migration Actions**: +1. **Use `architecture-starter.prompt.md` to generate proper architecture spec** +2. **Create C4 diagrams documenting current actual architecture** +3. **Use `code-to-requirements.prompt.md` to understand intended behavior** +4. **Document architectural decisions as ADRs** with rationale for discrepancies +5. **Create architecture modernization roadmap** with migration priorities +6. **Establish architecture governance** to prevent future inconsistencies + +**Architecture Modernization Priority**: +1. **CRITICAL**: Resolve security anti-patterns and circular dependencies +2. **HIGH**: Standardize data access patterns and error handling +3. **MEDIUM**: Complete partial migrations and remove dead code +4. **LOW**: Optimize performance and improve test coverage + +[Continue for Phases 04-07...] + +### 3. Code Quality & Problem Area Assessment + +**Overall Score**: [X/10] + +#### **1. Code Organization Analysis** +- **Structure**: [X/10] - [Comments on organization] +- **Naming**: [X/10] - [Comments on naming conventions] +- **Modularity**: [X/10] - [Comments on SOLID principles] +- **Documentation**: [X/10] - [Comments on code docs] + +#### **2. Comprehensive Problem Detection** + +**Static Analysis Tools**: +```bash +# Multi-language static analysis +eslint src/ --ext .js,.ts --format json > eslint-report.json +sonarqube-scanner -Dsonar.projectKey=audit +flake8 src/ --output-file=flake8-report.txt +pylint src/ --output-format=json > pylint-report.json +detekt --input src/ --report xml:detekt-report.xml # Kotlin +swiftlint > swiftlint-report.json # Swift +``` + +#### **🔴 Critical Problems (Fix Immediately)** + +**Security Vulnerabilities**: +```bash +# Security scanning +npm audit --audit-level=high +safety check # Python +snyk test +bandit -r src/ # Python security issues +``` + +**Critical Issues Found**: +- **SQL Injection**: [Count] vulnerable queries + ```sql + -- Example: user_controller.py line 45 + query = f"SELECT * FROM users WHERE id = {user_id}" # VULNERABLE + ``` +- **Hardcoded Secrets**: [Count] instances + ```javascript + // Example: config.js line 12 + const API_KEY = "sk-1234567890abcdef"; // HARDCODED SECRET + ``` +- **Authentication Bypass**: [Count] endpoints + ```python + # Example: No auth check on admin endpoints + @app.route('/admin/users', methods=['DELETE']) + def delete_user(): # MISSING AUTH CHECK + ``` +- **XSS Vulnerabilities**: [Count] injection points +- **CSRF Missing Protection**: [Count] state-changing endpoints + +**Data Integrity Issues**: +- **Race Conditions**: [Count] concurrent access issues +- **Transaction Boundaries**: [Count] incomplete transactions +- **Data Validation**: [Count] missing input validation +- **Injection Attacks**: [Count] unsanitized inputs + +#### **🟡 High Priority Problems (Fix This Sprint)** + +**Performance Bottlenecks**: +```bash +# Performance analysis +npx clinic doctor -- node server.js +py-spy top --pid $(pgrep python) +java -javaagent:profiler.jar MyApp +``` + +**Performance Issues Found**: +- **N+1 Query Problems**: [Count] instances + ```python + # Example: Inefficient data loading + users = User.all() + for user in users: + profile = UserProfile.get(user.id) # N+1 QUERY + ``` +- **Memory Leaks**: [Count] potential leaks + ```javascript + // Example: Event listeners not cleaned up + setInterval(() => { /* ... */ }, 1000); // NEVER CLEARED + ``` +- **Inefficient Algorithms**: [Count] O(n²) or worse complexity +- **Large Object Creation**: [Count] unnecessary object allocations +- **Missing Indexes**: [Count] slow database queries +- **Synchronous I/O**: [Count] blocking operations + +**Maintainability Issues**: +- **God Classes**: [Count] classes >500 lines + ```typescript + // Example: UserService.ts (1,247 lines) + class UserService { + // Handles auth, profiles, notifications, billing, analytics... + } + ``` +- **Long Methods**: [Count] methods >50 lines +- **High Complexity**: [Count] methods with cyclomatic complexity >10 +- **Code Duplications**: [Count] duplicated code blocks +- **Technical Debt**: Estimated [X] hours to address + +#### **⚠️ Medium Priority Problems (Fix Next Sprint)** + +**Design Pattern Violations**: +```bash +# Anti-pattern detection +grep -r "instanceof" src/ # Potential violation of OCP +grep -r "switch.*type" src/ # Missing polymorphism +find src -name "*.js" -exec wc -l {} \; | sort -nr | head -10 # Large files +``` + +**Anti-Patterns Found**: +- **Spaghetti Code**: [Count] modules with >10 dependencies +- **God Objects**: [Count] classes doing too much +- **Tight Coupling**: [Count] direct class instantiations +- **Magic Numbers**: [Count] unexplained constants +- **Dead Code**: [Count] unused methods/classes + ```bash + # Unused code detection + npx ts-unused-exports tsconfig.json + vulture src/ # Python dead code + ``` + +**Code Smells**: +- **Long Parameter Lists**: [Count] methods >5 parameters +- **Feature Envy**: [Count] methods using other classes excessively +- **Data Clumps**: [Count] repeated parameter groups +- **Primitive Obsession**: [Count] complex data as primitives + +#### **3. Test Coverage Analysis** +``` +Current Coverage: [X]% +Target Coverage: 80% +Gap: [Y]% points + +Coverage by Component: +- [Component 1]: [X]% +- [Component 2]: [Y]% +- [Component 3]: [Z]% + +Critical Untested Code: +- [List of critical paths without tests] + +Test Quality Issues: +- [Count] flaky tests (fail intermittently) +- [Count] slow tests (>1s execution time) +- [Count] tests without assertions +- [Count] tests that test implementation details +``` + +**Test Problem Analysis**: +- **Missing Edge Cases**: [Count] boundary conditions untested +- **Insufficient Mocking**: [Count] tests hitting real dependencies +- **Test Isolation Issues**: [Count] tests depending on each other +- **Outdated Tests**: [Count] tests failing due to code changes + +**Migration Actions**: +1. Use `test-gap-filler.prompt.md` to identify missing tests +2. Implement TDD going forward with `tdd-compile.prompt.md` +3. Refactor code for better testability + +#### **4. Security Assessment Deep Dive** + +**Vulnerability Scanning**: +```bash +# Comprehensive security analysis +npm audit --audit-level=moderate +safety check --json # Python +snyk test --severity-threshold=medium +semgrep --config=auto src/ +``` + +**Security Issues Found**: + +**🔴 Critical Security Issues**: +- **Secrets Management**: [X/10] - [Count] hardcoded secrets found + - API keys in source code: [locations] + - Database passwords in config: [files] + - JWT secrets in environment files: [files] +- **Authentication Flaws**: [X/10] - [Count] auth bypass opportunities + - Missing authentication on [count] endpoints + - Weak password requirements + - No account lockout mechanism +- **Authorization Issues**: [X/10] - [Count] privilege escalation risks + - Missing role-based access control + - Horizontal privilege escalation in [endpoints] + - Admin functions accessible to regular users + +**🟡 Medium Security Issues**: +- **Input Validation**: [X/10] - [Count] injection vulnerabilities + - SQL injection in [count] queries + - XSS vulnerabilities in [count] forms + - Path traversal in [count] file operations +- **Data Protection**: [X/10] - [Count] data exposure risks + - PII logged in plain text: [locations] + - Sensitive data in error messages + - Missing encryption for data at rest +- **Dependencies**: [X/10] - [Count] vulnerable dependencies + ```bash + # Example vulnerable dependencies + lodash: 4.17.15 (CVE-2020-8203) + express: 4.16.1 (CVE-2022-24999) + ``` + +#### **5. Architecture & Design Problem Assessment** + +**SOLID Principles Violations**: +- **Single Responsibility**: [Count] classes doing multiple things +- **Open/Closed**: [Count] classes requiring modification for extension +- **Liskov Substitution**: [Count] inheritance hierarchy violations +- **Interface Segregation**: [Count] fat interfaces forcing unused methods +- **Dependency Inversion**: [Count] direct dependencies on concrete classes + +**Design Problems**: +- **Inappropriate Intimacy**: [Count] classes knowing too much about others +- **Refused Bequest**: [Count] subclasses not using inherited methods +- **Parallel Inheritance**: [Count] hierarchies that must change together +- **Shotgun Surgery**: [Count] changes requiring edits in many places + +#### **6. Problem Prioritization Matrix** + +| Problem Category | Impact | Frequency | Fix Effort | Priority Score | +|------------------|--------|-----------|------------|----------------| +| SQL Injection | 🔴 Critical | High | Medium | 95/100 | +| Performance N+1 | 🟡 High | High | Low | 80/100 | +| God Classes | 🟡 Medium | Medium | High | 60/100 | +| Dead Code | ⚠️ Low | Low | Low | 30/100 | + +#### **7. Automated Problem Detection Setup** + +**Continuous Monitoring**: +```yaml +# .github/workflows/code-quality.yml +name: Code Quality Analysis +on: [push, pull_request] +jobs: + quality-check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Security Scan + run: | + npm audit --audit-level=high + snyk test + - name: Code Quality + run: | + eslint src/ --max-warnings 0 + sonarqube-scanner + - name: Performance Check + run: | + npm run test:performance +``` + +**Quality Gates**: +- **Security**: Zero high/critical vulnerabilities +- **Coverage**: Minimum 80% code coverage +- **Complexity**: Max cyclomatic complexity 10 +- **Duplication**: <3% code duplication +- **Maintainability**: Maintainability index >70 + +**Problem Tracking**: +```markdown +# Create GitHub issues for each problem category +- Security: "Fix SQL injection vulnerabilities" +- Performance: "Resolve N+1 query problems" +- Architecture: "Refactor God classes" +- Test: "Improve test coverage to 80%" +``` + +### 4. Process Compliance + +**Overall Score**: [X/10] + +#### Development Process +- **Git Workflow**: [X/10] - [Assessment] +- **Code Reviews**: [X/10] - [Assessment] +- **CI/CD Pipeline**: [X/10] - [Assessment] +- **Release Management**: [X/10] - [Assessment] + +#### Quality Gates +- **Automated Testing**: [X/10] - [Assessment] +- **Code Quality Checks**: [X/10] - [Assessment] +- **Security Scanning**: [X/10] - [Assessment] +- **Performance Testing**: [X/10] - [Assessment] + +### 5. Traceability Assessment + +**Overall Score**: [X/10] + +#### Traceability Matrix + +| Level | Forward Trace | Backward Trace | Coverage | Quality | +|-------|---------------|----------------|----------|---------| +| Business → Stakeholder | [%] | [%] | [X]/10 | [X]/10 | +| Stakeholder → System | [%] | [%] | [X]/10 | [X]/10 | +| System → Architecture | [%] | [%] | [X]/10 | [X]/10 | +| Architecture → Design | [%] | [%] | [X]/10 | [X]/10 | +| Design → Code | [%] | [%] | [X]/10 | [X]/10 | +| Code → Tests | [%] | [%] | [X]/10 | [X]/10 | + +**Migration Actions**: +1. Use `traceability-builder.prompt.md` to establish missing links +2. Implement requirement IDs in code comments +3. Link tests to requirements via naming conventions + +## Migration Roadmap + +### Phase 1: Foundation (Weeks 1-2) +**Priority**: CRITICAL +**Effort**: [X] weeks + +**Objectives**: +- Establish basic spec-driven structure +- Address critical compliance gaps +- Set up essential tooling + +**Actions**: +1. **Repository Structure** + - Create docs/ folder with phase subdirectories + - Set up .github/prompts/ with essential prompts + - Reorganize existing documentation + +2. **Critical Documentation** + - Create stakeholder requirements specification + - Document business case and success criteria + - Establish requirements traceability + +3. **Quality Foundation** + - Set up automated testing in CI/CD + - Implement basic security scanning + - Establish code review process + +**Success Criteria**: +- [ ] Repository structure matches template +- [ ] Basic stakeholder requirements documented +- [ ] CI/CD pipeline with quality gates operational + +### Phase 2: Requirements & Architecture (Weeks 3-5) +**Priority**: HIGH +**Effort**: [Y] weeks + +**Objectives**: +- Complete requirements documentation +- Document existing architecture +- Establish full traceability + +**Actions**: +1. **Requirements Engineering** + - Reverse-engineer system requirements from code + - Create formal requirements specification + - Add acceptance criteria to all requirements + +2. **Architecture Documentation** + - Generate C4 diagrams from existing system + - Document architectural decisions (ADRs) + - Create architecture specification + +3. **Traceability Implementation** + - Link all code to requirements + - Establish forward/backward traceability + - Create traceability matrix + +**Success Criteria**: +- [ ] Complete system requirements specification +- [ ] Architecture fully documented with C4 diagrams +- [ ] 80%+ traceability coverage established + +### Phase 3: Testing & Quality (Weeks 6-8) +**Priority**: MEDIUM +**Effort**: [Z] weeks + +**Objectives**: +- Achieve target test coverage +- Implement comprehensive quality gates +- Complete process automation + +**Actions**: +1. **Test Coverage Improvement** + - Identify and fill test gaps + - Implement TDD for new features + - Achieve 80%+ test coverage + +2. **Quality Automation** + - Implement comprehensive linting + - Add security vulnerability scanning + - Set up performance monitoring + +3. **Process Completion** + - Complete all phase documentation + - Implement full spec-driven workflow + - Train team on new processes + +**Success Criteria**: +- [ ] 80%+ test coverage achieved +- [ ] All quality gates operational +- [ ] Team trained on spec-driven development + +### Phase 4: Optimization (Weeks 9-10) +**Priority**: LOW +**Effort**: [W] weeks + +**Objectives**: +- Optimize processes and tooling +- Complete nice-to-have improvements +- Establish continuous improvement + +**Actions**: +1. **Process Optimization** + - Streamline development workflow + - Optimize build and deployment pipelines + - Implement advanced monitoring + +2. **Documentation Polish** + - Complete all optional documentation + - Improve documentation quality + - Add advanced examples and guides + +3. **Team Enablement** + - Advanced training on tools and processes + - Establish communities of practice + - Create internal best practices guide + +## 🔍 Missing Specification Detection Framework + +### **⚠️ CRITICAL: Identify Lost or Missing Original Specifications** + +**The Problem**: Brownfield projects often have code that was implemented based on specifications, standards, or business rules that are now missing, outdated, or never properly documented. Simply auditing existing documentation may miss the original context that drove implementation decisions. + +#### **1. Specification Artifact Detection** + +**Identify what specifications may have existed but are now missing**: + +```bash +# Look for traces of original specifications +find . -name "*spec*" -o -name "*requirement*" -o -name "*standard*" -o -name "*policy*" +find . -name "*.doc" -o -name "*.docx" -o -name "*.pdf" | grep -i "spec\|requirement\|design" + +# Check for references to external documents in code comments +grep -r "see document\|reference\|spec\|standard\|policy" src/ --include="*.js" --include="*.py" --include="*.java" +grep -r "TODO.*spec\|FIXME.*requirement\|NOTE.*standard" src/ + +# Look for orphaned documentation +find docs/ -name "*.md" -exec grep -l "DRAFT\|TODO\|INCOMPLETE\|OUTDATED" {} \; +``` + +**Common Missing Specification Types**: +```markdown +### Specification Gaps Checklist + +#### Business Requirements +- [ ] **Original Business Case**: Why was this system built? +- [ ] **Stakeholder Requirements**: Who are the users and what do they need? +- [ ] **Success Criteria**: How is success measured? +- [ ] **Regulatory Requirements**: What compliance is needed? + +#### Domain-Specific Standards +- [ ] **Industry Standards**: ISO, IEEE, NIST, etc. applicable to domain +- [ ] **Legal Requirements**: GDPR, HIPAA, PCI-DSS, SOX, etc. +- [ ] **Company Policies**: Internal security, data handling, coding standards +- [ ] **SLA Requirements**: Performance, availability, security commitments + +#### Technical Specifications +- [ ] **Architecture Decisions**: Why this architecture was chosen +- [ ] **Technology Standards**: Approved technology stack rationale +- [ ] **Security Requirements**: Threat model, security controls +- [ ] **Performance Requirements**: Benchmarks, scalability targets +- [ ] **Integration Standards**: API contracts, data formats + +#### Operational Requirements +- [ ] **Deployment Standards**: Environment requirements, deployment process +- [ ] **Monitoring Requirements**: What to monitor, alerting thresholds +- [ ] **Backup/Recovery**: Data protection and disaster recovery requirements +- [ ] **Support Requirements**: Maintenance procedures, escalation paths +``` + +#### **2. Code Archaeology for Missing Context** + +**Analyze code patterns that suggest missing specifications**: + +```javascript +// Example: Hardcoded business rules without context +const CREDIT_LIMIT = 5000; // MISSING: Credit policy documentation +const TAX_RATES = { // MISSING: Tax jurisdiction rules + 'CA': 0.08, + 'NY': 0.04, + 'TX': 0.00 +}; + +function validateAge(user) { + if (user.age < 18) { // MISSING: Legal age requirements by jurisdiction + throw new Error('User must be 18 or older'); + } + if (user.age >= 65) { // MISSING: Senior citizen business rules + user.discount = 0.1; + } +} + +// MISSING SPECIFICATIONS IDENTIFIED: +// SPEC-MISSING-001: Credit limit policy (financial regulations) +// SPEC-MISSING-002: Tax jurisdiction rules (accounting requirements) +// SPEC-MISSING-003: Age verification legal requirements +// SPEC-MISSING-004: Senior citizen discount business rules +``` + +**Suspicious Code Patterns**: +```python +# Pattern: Magic numbers and hardcoded thresholds +class OrderProcessor: + def process_payment(self, amount): + if amount > 1000: # MISSING: Large transaction policy + return self.require_additional_verification() + + retry_count = 3 # MISSING: SLA or technical requirement? + timeout = 30000 # MISSING: Performance requirement? + + def calculate_shipping(self, weight, distance): + # Complex calculation without documented formula + base_rate = 5.99 + weight_factor = 0.12 + distance_factor = 0.08 + # MISSING: Shipping rate calculation specification +``` + +#### **3. Domain Expert Interview Framework** + +**Structured approach to recover missing specifications**: + +```markdown +### Domain Expert Interview Template + +#### Session 1: Business Context Recovery +**Participants**: Product Owner, Original Stakeholders, Domain Experts + +**Questions to Ask**: +1. **Original Vision**: What problem was this system designed to solve? +2. **Business Rules**: What business logic was this code supposed to implement? +3. **Regulatory Context**: What regulations or standards apply to this domain? +4. **Success Metrics**: How was the system supposed to be measured? +5. **Stakeholder Needs**: Who were the primary users and what did they need? + +#### Session 2: Technical Context Recovery +**Participants**: Original Architects, Senior Developers, Technical Leads + +**Questions to Ask**: +1. **Architecture Decisions**: Why was this technical approach chosen? +2. **Performance Requirements**: What were the original performance targets? +3. **Security Requirements**: What security threats were being addressed? +4. **Integration Requirements**: What systems needed to integrate and how? +5. **Scalability Requirements**: What growth was the system designed for? + +#### Session 3: Operational Context Recovery +**Participants**: DevOps, Support Team, Operations Staff + +**Questions to Ask**: +1. **Deployment Requirements**: What were the original deployment constraints? +2. **Monitoring Requirements**: What operational metrics were important? +3. **Support Requirements**: What support processes were defined? +4. **Disaster Recovery**: What backup and recovery requirements existed? +5. **Maintenance Requirements**: What ongoing maintenance was planned? +``` + +#### **4. External Validation Sources** + +**Cross-reference implementation against external standards**: + +```markdown +### External Specification Sources + +#### Industry Standards Research +- **ISO Standards**: Search ISO database for domain-relevant standards +- **IEEE Standards**: Technical implementation standards +- **NIST Guidelines**: Security and technology best practices +- **Industry Associations**: Domain-specific guidelines (medical, financial, etc.) + +#### Regulatory Requirements Research +- **Government Regulations**: Federal, state, local applicable laws +- **Industry Regulations**: Sector-specific compliance requirements +- **International Standards**: Cross-border requirements +- **Professional Standards**: Licensed profession requirements + +#### Competitive Intelligence +- **Industry Best Practices**: How do competitors handle similar requirements? +- **Public Documentation**: Open source similar projects +- **Conference Papers**: Industry conference presentations +- **Case Studies**: Similar implementation stories + +#### Historical Context Research +- **Git History Analysis**: Commit messages, PR discussions, issue comments +- **Email Archives**: Search company email for project discussions +- **Meeting Notes**: Historical project meeting documentation +- **Wiki/Confluence**: Internal knowledge bases +``` + +#### **5. Specification Gap Analysis** + +**Systematic identification of missing specifications**: + +```markdown +### Gap Analysis Matrix + +| Code Feature | Current Implementation | Missing Specification | Validation Source | Priority | +|-------------|----------------------|---------------------|------------------|----------| +| User Authentication | JWT with 24h expiry | Security policy requiring specific timeout | Security team review | HIGH | +| Tax Calculation | Hardcoded rates by state | Tax jurisdiction rules and update process | Legal/Accounting team | CRITICAL | +| Payment Processing | 3 retry attempts | SLA requirement or technical constraint | Product owner interview | HIGH | +| Data Retention | No deletion logic | Data retention policy and legal requirements | Compliance team | CRITICAL | + +### Specification Recovery Action Plan + +#### CRITICAL Priority (Address Immediately) +1. **SPEC-GAP-001: Data Retention Policy** + - **Current Risk**: Potential legal compliance violation + - **Recovery Action**: Legal team consultation, GDPR compliance review + - **Timeline**: 1 week + - **Owner**: Compliance Officer + +2. **SPEC-GAP-002: Tax Calculation Rules** + - **Current Risk**: Incorrect tax calculations, audit issues + - **Recovery Action**: Accounting team review, tax software integration + - **Timeline**: 2 weeks + - **Owner**: Finance team + +#### HIGH Priority (Address This Sprint) +1. **SPEC-GAP-003: Security Token Policy** + - **Current Risk**: Security vulnerability, compliance gap + - **Recovery Action**: Security team policy review + - **Timeline**: 1 week + - **Owner**: Security team + +2. **SPEC-GAP-004: Performance SLA Requirements** + - **Current Risk**: User experience issues, no performance baseline + - **Recovery Action**: Product owner and technical review + - **Timeline**: 2 weeks + - **Owner**: Technical lead +``` + +#### **6. Automated Specification Gap Detection** + +**Set up automated detection of missing specifications**: + +```javascript +// Automated specification gap detector +class SpecificationGapDetector { + constructor(codebaseAnalyzer) { + this.analyzer = codebaseAnalyzer; + } + + detectMissingSpecs() { + const gaps = []; + + // Detect hardcoded business rules + const hardcodedRules = this.analyzer.findHardcodedBusinessRules(); + hardcodedRules.forEach(rule => { + gaps.push({ + type: 'MISSING_BUSINESS_RULE', + severity: 'HIGH', + location: rule.file + ':' + rule.line, + description: `Hardcoded value: ${rule.value}`, + recommendation: 'Document business justification and make configurable', + validationNeeded: 'Business stakeholder review' + }); + }); + + // Detect regulatory compliance patterns + const compliancePatterns = this.analyzer.findCompliancePatterns(); + compliancePatterns.forEach(pattern => { + gaps.push({ + type: 'MISSING_COMPLIANCE_SPEC', + severity: 'CRITICAL', + location: pattern.file + ':' + pattern.line, + description: `Compliance-sensitive code: ${pattern.pattern}`, + recommendation: 'Verify against regulatory requirements', + validationNeeded: 'Legal/compliance team review' + }); + }); + + // Detect undocumented integrations + const integrations = this.analyzer.findExternalIntegrations(); + integrations.forEach(integration => { + gaps.push({ + type: 'MISSING_INTEGRATION_SPEC', + severity: 'MEDIUM', + location: integration.file + ':' + integration.line, + description: `External integration: ${integration.service}`, + recommendation: 'Document integration contract and SLA', + validationNeeded: 'Technical architecture review' + }); + }); + + return gaps; + } +} + +// Usage in CI/CD pipeline +const detector = new SpecificationGapDetector(codeAnalyzer); +const gaps = detector.detectMissingSpecs(); + +if (gaps.filter(g => g.severity === 'CRITICAL').length > 0) { + console.error('CRITICAL specification gaps detected - review required'); + process.exit(1); +} +``` + +#### **7. Specification Recovery Report Template** + +```markdown +# Missing Specification Recovery Report + +## Executive Summary +- **Total Specification Gaps Identified**: [N] +- **Critical Gaps Requiring Immediate Attention**: [N] +- **Stakeholder Interviews Scheduled**: [N] +- **External Validation Sources Identified**: [N] + +## Critical Specification Gaps + +### SPEC-GAP-001: [Title] +**Severity**: CRITICAL/HIGH/MEDIUM/LOW +**Category**: Business Logic/Compliance/Security/Performance/Integration +**Description**: [What specification is missing and why it's needed] +**Current Implementation**: [What the code currently does without specification] +**Risk if Unaddressed**: [Potential consequences] +**Recovery Method**: +- [ ] Stakeholder interview +- [ ] External standard research +- [ ] Regulatory compliance review +- [ ] Technical expert consultation +**Owner**: [Who will recover this specification] +**Timeline**: [When recovery is needed] +**Dependencies**: [Other gaps that must be resolved first] + +## Stakeholder Interview Schedule + +### Business Context Recovery Sessions +- **Session 1**: Product vision and business rules (Product Owner, Domain Experts) +- **Session 2**: Regulatory and compliance context (Legal, Compliance Officer) +- **Session 3**: User needs and success criteria (UX, Customer Support) + +### Technical Context Recovery Sessions +- **Session 4**: Architecture and design decisions (Technical Architect, Senior Developers) +- **Session 5**: Performance and scalability requirements (Performance Engineer, SRE) +- **Session 6**: Security and integration requirements (Security team, Integration team) + +## External Validation Plan + +### Industry Standards Research +- [ ] **ISO/IEEE Standards**: [List relevant standards to research] +- [ ] **Regulatory Requirements**: [List regulations to verify against] +- [ ] **Industry Best Practices**: [List competitive analysis needed] + +### Internal Knowledge Recovery +- [ ] **Git History Analysis**: Mine commit messages and PR discussions +- [ ] **Documentation Archaeology**: Search wiki, email, meeting notes +- [ ] **Team Knowledge Transfer**: Interviews with original team members + +## Implementation Timeline + +### Week 1-2: Critical Gap Recovery +- Address CRITICAL severity gaps +- Complete urgent stakeholder interviews +- Begin regulatory compliance verification + +### Week 3-4: High Priority Gap Recovery +- Address HIGH severity gaps +- Complete technical context interviews +- Research relevant industry standards + +### Week 5-8: Medium Priority Gap Recovery +- Address remaining gaps +- Complete external validation research +- Document all recovered specifications + +## Success Criteria +- [ ] All CRITICAL specification gaps addressed +- [ ] 90% of HIGH priority gaps addressed +- [ ] All recovered specifications documented and validated +- [ ] Stakeholder sign-off on recovered business context +- [ ] Technical team sign-off on recovered technical context + +## Next Steps +1. **Immediate**: Schedule critical stakeholder interviews +2. **This Week**: Begin regulatory compliance research +3. **This Month**: Complete specification recovery for critical gaps +4. **This Quarter**: Establish process to prevent future specification loss +``` + +## Risk Assessment + +### High Risks +1. **Team Resistance to Change** + - **Mitigation**: Gradual adoption, training, show benefits + - **Contingency**: Executive sponsorship, change management + +2. **Technical Debt Blocking Progress** + - **Mitigation**: Prioritize refactoring, incremental improvement + - **Contingency**: Parallel development of new components + +3. **Resource Constraints** + - **Mitigation**: Phase implementation, leverage automation + - **Contingency**: Extend timeline, reduce scope + +### Medium Risks +- Integration complexity with existing systems +- Learning curve for new tools and processes +- Maintaining momentum through long migration + +### Low Risks +- Tool compatibility issues +- Documentation maintenance overhead +- Performance impact of new processes + +## Success Metrics + +### Compliance Metrics +- **Overall compliance score**: Target 90%+ within 10 weeks +- **Phase completion**: All 7 phases documented and operational +- **Traceability coverage**: 85%+ forward and backward links + +### Quality Metrics +- **Test coverage**: 80%+ within 8 weeks +- **Defect density**: <1 defect per 1000 lines of code +- **Security vulnerabilities**: Zero high/critical issues + +### Process Metrics +- **Build success rate**: 95%+ automated builds pass +- **Deployment frequency**: Weekly releases achievable +- **Lead time**: 50% reduction in feature delivery time + +## Recommendations + +### Immediate Actions (This Week) +1. Set up basic repository structure +2. Copy essential prompts from template +3. Begin stakeholder requirements gathering +4. Establish project communication plan + +### Short Term (Next Month) +1. Complete Phase 1 migration activities +2. Begin Phase 2 requirements and architecture work +3. Train core team on spec-driven development +4. Establish regular progress reviews + +### Long Term (Next Quarter) +1. Complete full migration to spec-driven development +2. Measure and optimize new processes +3. Share learnings and best practices +4. Consider expanding to other projects + +## Conclusion + +**Migration Feasibility**: [HIGH 🟢 / MEDIUM 🟡 / LOW 🔴] + +**Overall Assessment**: [Summary of readiness and recommended approach] + +**Expected Benefits**: +- Improved software quality and reliability +- Faster development through better requirements +- Reduced rework and defects +- Better compliance with industry standards +- Enhanced team productivity and satisfaction + +**Investment Required**: [X] weeks of effort over [Y] weeks timeline +**Expected ROI**: [Benefits vs. costs analysis] + +**Recommendation**: [PROCEED / PROCEED WITH MODIFICATIONS / DEFER] +``` + +## 🏗️ Architecture Recommendation Engine + +### **1. Architecture Modernization Strategy** + +Based on the analysis above, generate specific recommendations for addressing architectural issues: + +#### **Critical Architecture Fixes (Must Do)** + +**🔴 Circular Dependency Resolution**: +```typescript +// Current Problem: auth.service ↔ user.service ↔ notification.service + +// Recommended Solution: Extract shared dependencies +interface UserEventBus { + publishUserEvent(event: UserEvent): void; + subscribeToUserEvents(handler: EventHandler): void; +} + +// Break circular dependencies with event-driven communication +class AuthService { + constructor(private eventBus: UserEventBus) {} + + async login(credentials: Credentials) { + // ... login logic + this.eventBus.publishUserEvent(new UserLoginEvent(user)); + // No direct dependency on NotificationService + } +} +``` + +**🔴 Layer Violation Fixes**: +```python +# Problem: Controllers directly accessing database +def get_user(user_id): + return db.session.query(User).filter_by(id=user_id).first() # BAD + +# Solution: Introduce repository layer +class UserRepository: + def get_by_id(self, user_id: int) -> Optional[User]: + return db.session.query(User).filter_by(id=user_id).first() + +class UserController: + def __init__(self, user_repository: UserRepository): + self.user_repository = user_repository + + def get_user(self, user_id: int): + return self.user_repository.get_by_id(user_id) # GOOD +``` + +#### **High Priority Architecture Improvements** + +**🟡 God Class Decomposition**: +```java +// Problem: UserService (1,247 lines) doing everything +public class UserService { + // Authentication, profiles, notifications, billing, analytics... +} + +// Solution: Single Responsibility Principle +public class UserAuthenticationService { + public AuthResult authenticate(Credentials credentials) { /* ... */ } +} + +public class UserProfileService { + public UserProfile getProfile(UserId id) { /* ... */ } +} + +public class UserNotificationService { + public void sendNotification(UserId id, Notification notification) { /* ... */ } +} + +// Coordination through facade if needed +public class UserFacade { + private final UserAuthenticationService authService; + private final UserProfileService profileService; + private final UserNotificationService notificationService; +} +``` + +**🟡 Performance Optimization**: +```sql +-- Problem: N+1 Query +SELECT * FROM users; +-- Then for each user: +SELECT * FROM user_profiles WHERE user_id = ?; + +-- Solution: JOIN or preload +SELECT u.*, up.* +FROM users u +LEFT JOIN user_profiles up ON u.id = up.user_id; +``` + +### **2. Migration Strategy Recommendations** + +#### **Strangler Fig Pattern for Legacy Systems**: +```mermaid +graph TD + A[Legacy System] --> B[Facade Layer] + B --> C[New Architecture] + B --> D[Legacy Components] + E[New Requests] --> B + F[Legacy Requests] --> B +``` + +**Implementation Phases**: +1. **Phase 1**: Create facade layer to intercept requests +2. **Phase 2**: Implement new components behind facade +3. **Phase 3**: Gradually migrate functionality from legacy to new +4. **Phase 4**: Remove legacy components when no longer used + +#### **Database Migration Strategy**: +```sql +-- Phase 1: Add new columns alongside old ones +ALTER TABLE users ADD COLUMN email_verified_v2 BOOLEAN; + +-- Phase 2: Dual writes (write to both old and new) +UPDATE users SET + email_verified = ?, + email_verified_v2 = ? +WHERE id = ?; + +-- Phase 3: Migrate existing data +UPDATE users SET email_verified_v2 = email_verified +WHERE email_verified_v2 IS NULL; + +-- Phase 4: Switch reads to new column +-- Phase 5: Drop old column +ALTER TABLE users DROP COLUMN email_verified; +``` + +#### **API Versioning Strategy**: +```typescript +// Problem: Breaking API changes +app.get('/api/users/:id', (req, res) => { + // Changed response format breaks existing clients +}); + +// Solution: API versioning +app.get('/api/v1/users/:id', getLegacyUser); +app.get('/api/v2/users/:id', getNewUser); + +// Or header-based versioning +app.get('/api/users/:id', (req, res) => { + const version = req.headers['api-version'] || 'v1'; + if (version === 'v2') { + return getNewUser(req, res); + } + return getLegacyUser(req, res); +}); +``` + +### **3. Technology Stack Recommendations** + +Based on the architecture analysis, recommend appropriate technologies: + +#### **Microservices vs Modular Monolith**: + +**Choose Microservices IF**: +- ✅ Team size >50 developers +- ✅ Clear domain boundaries identified +- ✅ Independent deployment needed +- ✅ Different scaling requirements per service + +**Choose Modular Monolith IF**: +- ✅ Team size <20 developers +- ✅ Shared data model across domains +- ✅ Strong consistency requirements +- ✅ Simpler deployment preferred + +**Current Recommendation**: Based on [team size] and [complexity], recommend [Microservices/Modular Monolith] + +#### **Communication Patterns**: + +**Synchronous (REST/GraphQL)**: +- ✅ Real-time user interactions +- ✅ Simple request-response patterns +- ❌ High coupling between services + +**Asynchronous (Events/Message Queues)**: +- ✅ Loose coupling between services +- ✅ Better resilience and scalability +- ❌ More complex debugging and testing + +**Recommended Pattern**: Hybrid approach with [specific recommendations based on use cases] + +### **4. Security Architecture Improvements** + +#### **Authentication & Authorization Modernization**: +```typescript +// Problem: Monolithic auth in every service +if (req.user.role !== 'admin') { + return res.status(403).json({ error: 'Forbidden' }); +} + +// Solution: Centralized authorization service +class AuthorizationService { + canAccess(user: User, resource: string, action: string): boolean { + return this.rbac.check(user.roles, resource, action); + } +} + +// Usage in services +if (!authService.canAccess(req.user, 'users', 'read')) { + return res.status(403).json({ error: 'Forbidden' }); +} +``` + +#### **Secret Management Architecture**: +```yaml +# Problem: Secrets in code/config files +database: + password: "hardcoded_password" # BAD + +# Solution: External secret management +database: + password: ${SECRET_DB_PASSWORD} # From HashiCorp Vault, AWS Secrets Manager, etc. +``` + +### **5. Performance Architecture Recommendations** + +#### **Caching Strategy**: +```typescript +// Multi-level caching architecture +class CacheService { + private l1Cache = new Map(); // In-memory + private l2Cache: Redis; // Distributed + + async get(key: string): Promise { + // L1 Cache check + if (this.l1Cache.has(key)) { + return this.l1Cache.get(key); + } + + // L2 Cache check + const value = await this.l2Cache.get(key); + if (value) { + this.l1Cache.set(key, value); + return value; + } + + return null; + } +} +``` + +#### **Database Optimization**: +```sql +-- Add missing indexes based on query analysis +CREATE INDEX idx_users_email ON users(email); +CREATE INDEX idx_orders_user_created ON orders(user_id, created_at); + +-- Optimize frequent queries +EXPLAIN ANALYZE SELECT * FROM orders +WHERE user_id = ? AND status = 'active' +ORDER BY created_at DESC; +``` + +### **6. Monitoring & Observability Architecture** + +#### **Distributed Tracing Setup**: +```typescript +// Add tracing to understand request flows +import { trace } from '@opentelemetry/api'; + +class UserService { + async getUser(id: string) { + const span = trace.getActiveSpan(); + span?.setAttributes({ 'user.id': id }); + + try { + const user = await this.repository.findById(id); + span?.setStatus({ code: SpanStatusCode.OK }); + return user; + } catch (error) { + span?.recordException(error); + span?.setStatus({ code: SpanStatusCode.ERROR }); + throw error; + } + } +} +``` + +#### **Health Check Architecture**: +```typescript +// Comprehensive health checks +class HealthCheckService { + async checkHealth(): Promise { + const checks = await Promise.all([ + this.checkDatabase(), + this.checkRedis(), + this.checkExternalAPIs(), + this.checkFileSystem() + ]); + + return { + status: checks.every(c => c.healthy) ? 'healthy' : 'unhealthy', + checks, + timestamp: new Date().toISOString() + }; + } +} +``` + +### **7. Implementation Roadmap with Effort Estimates** + +#### **Quarter 1: Foundation (3 months)** +**Effort**: 240 hours (3 developers × 20 hours/week × 4 weeks) + +**Week 1-2: Architecture Analysis & Planning** +- [ ] Complete architecture audit (16 hours) +- [ ] Design target architecture (24 hours) +- [ ] Create migration strategy (16 hours) +- [ ] Set up monitoring and metrics (24 hours) + +**Week 3-6: Critical Security Fixes** +- [ ] Fix SQL injection vulnerabilities (32 hours) +- [ ] Implement proper secret management (24 hours) +- [ ] Add authentication/authorization checks (40 hours) +- [ ] Security testing and validation (16 hours) + +**Week 7-12: Core Architecture Improvements** +- [ ] Resolve circular dependencies (48 hours) +- [ ] Fix layer violations (40 hours) +- [ ] Implement repository pattern (32 hours) +- [ ] Add proper error handling (24 hours) + +#### **Quarter 2: Optimization (3 months)** +**Effort**: 180 hours + +**Performance Optimization**: +- [ ] Resolve N+1 query problems (32 hours) +- [ ] Implement caching strategy (40 hours) +- [ ] Database optimization (24 hours) +- [ ] Load testing and tuning (24 hours) + +**Code Quality Improvements**: +- [ ] Refactor God classes (40 hours) +- [ ] Improve test coverage to 80% (32 hours) +- [ ] Remove dead code (16 hours) +- [ ] Code review process improvements (12 hours) + +#### **Success Metrics & KPIs** + +**Technical Metrics**: +- **Architecture Compliance**: Target 90% (Current: [X]%) +- **Code Coverage**: Target 80% (Current: [X]%) +- **Security Score**: Target 95% (Current: [X]%) +- **Performance**: <500ms API response time (Current: [X]ms) +- **Maintainability Index**: Target >70 (Current: [X]) + +**Business Metrics**: +- **Developer Velocity**: 25% improvement in story points/sprint +- **Bug Rate**: 50% reduction in production bugs +- **Time to Market**: 30% faster feature delivery +- **Technical Debt**: Reduce from [X] to [Y] hours + +**Monitoring Dashboard**: +```yaml +# architecture-health-dashboard.yml +metrics: + - name: "Circular Dependencies" + target: 0 + current: "[X]" + trend: "improving" + + - name: "God Classes" + target: 0 + current: "[X]" + trend: "stable" + + - name: "Test Coverage" + target: "80%" + current: "[X]%" + trend: "improving" +``` + +## 🚀 Usage + +### Full Repository Audit: +```bash +/repository-audit.prompt.md Please perform a comprehensive audit of this repository against the spec-driven development template. + +Analyze: +- Repository structure and organization +- Documentation completeness across all phases +- Code quality and test coverage +- Process compliance and automation +- Traceability between artifacts + +Generate migration roadmap with effort estimates. +``` + +### Focused Assessment: +```bash +# Audit specific aspect +/repository-audit.prompt.md Audit our requirements documentation. +How does it compare to ISO 29148 standards? + +# Check specific phase +/repository-audit.prompt.md Assess our architecture documentation completeness. +What C4 diagrams and ADRs are missing? + +# Evaluate process maturity +/repository-audit.prompt.md Evaluate our CI/CD pipeline against spec-driven development best practices. +``` + +### Migration Planning: +```bash +/repository-audit.prompt.md Based on current repository state, create a 3-month migration plan to adopt spec-driven development with realistic effort estimates and risk mitigation. +``` + +## 📈 Audit Automation + +### Automated Checks: +```bash +# Structure analysis +find docs/ -type d | sort + +# Documentation completeness +find docs/ -name "*.md" -exec wc -l {} + + +# Test coverage analysis +npm run test:coverage || pytest --cov || mvn test jacoco:report + +# Security scanning +npm audit --audit-level=high || safety check || snyk test + +# Code quality +npm run lint || flake8 || checkstyle +``` + +### Continuous Monitoring: +- Set up monthly automated audits +- Track compliance score trends +- Monitor migration progress +- Alert on regression in key metrics + +--- + +**Know where you stand, plan where you're going!** 📊 \ No newline at end of file diff --git a/.github/prompts/tdd-compile.prompt.md b/.github/prompts/tdd-compile.prompt.md index e1f8bc5..ae6dffb 100644 --- a/.github/prompts/tdd-compile.prompt.md +++ b/.github/prompts/tdd-compile.prompt.md @@ -1,116 +1,801 @@ --- mode: agent -description: > - Narrow workflow entry point for approved PoKeysHal implementation work. - Routes to TDDDriver. Applicable to C99 sources, async subsystems, HAL exports, - protocol handling, and RT-safe implementation. applyTo: - - "**/*.c" - - "**/*.h" + - "**/*.md" - "**/05-implementation/**/*" + - "**/user-story-*.md" --- -# TDD Compile – PoKeysHal Implementation Workflow +# TDD Compile Prompt (GitHub Issues) -Entry point for implementing an approved GitHub issue through Red-Green-Refactor. -Implementation behavior is owned by the **TDDDriver** agent; invoke it with the issue number. -This prompt defines the required sequence, evidence contract, and routing. +You are a Test-Driven Development (TDD) specialist enforcing **ISO/IEC/IEEE 12207:2017** and **Extreme Programming (XP) best practices**. -## Prepare +## 🎯 Core Workflow: GitHub Issues + TDD Cycle -Before editing any file: +**ALL work tracked through GitHub Issues:** +- **REQ Issues**: Requirements with labels `type:requirement:functional` or `type:requirement:non-functional` +- **TEST Issues**: Test specifications with label `type:test`, linking via `Verifies: #N` +- **Code**: Implements requirements with `Implements: #N` in docstrings +- **PRs**: Reference issues via `Fixes #N` or `Implements #N` -1. Read the issue, its acceptance criteria, and linked architecture decisions. -2. Run the narrowest relevant build or test and record pass/fail. -3. Identify the affected boundary: protocol/parser, async mailbox or scheduler, - PoKeysLib subsystem, HAL export, integration shell, or RT-reachable path. -4. Establish expected behavior from the PoKeys protocol specification, existing - verified behavior, or a recorded HIL observation. Do not invent hardware-facing - expectations. +**TDD Cycle (Red-Green-Refactor):** +``` +1. RED: Write failing test first (references TEST issue #N) + ↓ +2. GREEN: Write minimal code to pass (references REQ issue #N) + ↓ +3. REFACTOR: Improve code while keeping tests green + ↓ +4. PR: Link to TEST/REQ issues, merge when CI passes + ↓ +5. REPEAT for next requirement +``` + +--- + +## 🚨 AI Agent Guardrails + +**CRITICAL TDD Rules:** +- ❌ **No stubs/simulations in PRODUCTIVE code**: Test doubles belong in test code only +- ✅ **Tests ALWAYS come first**: Write failing test before any implementation +- ❌ **No implementation-based assumptions**: Follow TDD cycle strictly +- ✅ **Reference GitHub Issues**: Every test/code file must reference issue numbers +- ❌ **No skipping refactor phase**: Always improve code while keeping tests green + +**Validation Questions**: +1. Did I write the test first and reference the TEST issue (#N)? +2. Does the test fail initially (RED phase)? +3. Does my implementation reference the REQ issue (#N)? +4. Am I following Red-Green-Refactor cycle strictly? +5. Will my PR link to the implementing issue(s)? + +--- + +## 📋 Step 1: Start from GitHub Issues + +### Query Requirement and TEST Issues ```bash -bash test_compile.sh # compile-check baseline -make -f Makefile.noqmake # library build baseline +# Get requirement details +gh issue view 25 --json title,body,labels + +# Get TEST issue(s) for this requirement +gh issue list --label "type:test" --search "Verifies: #25" + +# Example output: +# Issue #50: TEST-AUTH-001: User Login Tests +# - Verifies: #25 (REQ-F-AUTH-001) +# - Test scenarios defined +# - Acceptance criteria listed ``` -Separate pre-existing failures from the new Red result before proceeding. +### Extract Requirements from Issue + +```markdown +**Issue #25**: REQ-F-AUTH-001: User Login + +**Description**: Authenticate users via email and password + +**Acceptance Criteria**: +- Given user has valid credentials +- When user submits login form +- Then user is authenticated and receives JWT token +- And authentication attempt is logged + +**Business Rules**: +- Use bcrypt for password hashing +- JWT token expires in 24 hours +- Rate limit: 5 failed attempts per 15 minutes + +**Verifies**: #20 (StR-003: Security Requirements) +``` + +--- + +## 🔴 Step 2: RED Phase - Write Failing Tests + +### Create Test File with Issue Traceability + +```typescript +/** + * Test Suite for User Authentication + * + * Verifies: #25 (REQ-F-AUTH-001: User Login) + * TEST Issue: #50 (TEST-AUTH-001) + * Traces to: #20 (StR-003: Security Requirements) + * + * Acceptance Criteria (from #25): + * Given user has valid credentials + * When user submits login form + * Then user is authenticated and receives JWT token + */ + +import { describe, it, expect, beforeEach, afterEach } from '@jest/globals'; +import { authenticateUser } from '../src/auth/authenticate'; +import { db } from '../src/db'; +import bcrypt from 'bcrypt'; + +describe('User Authentication (Verifies #25)', () => { + let testUser: any; + + beforeEach(async () => { + // Setup: Create test user + const passwordHash = await bcrypt.hash('password123', 12); + testUser = await db.users.create({ + email: 'test@example.com', + passwordHash, + createdAt: new Date() + }); + }); + + afterEach(async () => { + // Cleanup + await db.users.deleteMany({ email: 'test@example.com' }); + await db.authLogs.deleteMany({ email: 'test@example.com' }); + }); + + /** + * TEST-AUTH-001-01: Happy path authentication + * Verifies: #25 (REQ-F-AUTH-001) + * TEST Issue: #50 + */ + describe('Happy Path (Verifies #25)', () => { + it('should authenticate user with valid credentials', async () => { + // ARRANGE + const email = 'test@example.com'; + const password = 'password123'; + + // ACT + const result = await authenticateUser(email, password); + + // ASSERT + expect(result).toMatchObject({ + authenticated: true, + token: expect.any(String), + expiresIn: 86400 // 24 hours + }); + }); + + it('should return valid JWT token', async () => { + const result = await authenticateUser('test@example.com', 'password123'); + const decoded = jwt.verify(result.token, process.env.JWT_SECRET!); + + expect(decoded).toMatchObject({ + userId: testUser.id, + email: 'test@example.com' + }); + }); + }); + + /** + * TEST-AUTH-001-02: Error cases + * Verifies: #25 (REQ-F-AUTH-001) - error handling + */ + describe('Error Cases (Verifies #25)', () => { + it('should reject invalid password', async () => { + await expect( + authenticateUser('test@example.com', 'wrong-password') + ).rejects.toThrow('Invalid credentials'); + }); + + it('should reject non-existent user', async () => { + await expect( + authenticateUser('nonexistent@example.com', 'password123') + ).rejects.toThrow('Invalid credentials'); + }); + }); + + /** + * TEST-AUTH-001-03: Security requirements + * Verifies: #26 (REQ-NF-SECU-001: Rate limiting) + */ + describe('Security (Verifies #26)', () => { + it('should log authentication attempt', async () => { + await authenticateUser('test@example.com', 'password123'); + + const logs = await db.authLogs.findMany({ + where: { email: 'test@example.com', success: true } + }); + + expect(logs).toHaveLength(1); + }); + + it('should enforce rate limiting (5 attempts per 15 min)', async () => { + // Make 5 failed attempts + for (let i = 0; i < 5; i++) { + try { + await authenticateUser('test@example.com', 'wrong'); + } catch (error) { + // Expected + } + } + + // 6th attempt should be rate limited + await expect( + authenticateUser('test@example.com', 'password123') + ).rejects.toThrow('Too many authentication attempts'); + }); + }); + + /** + * TEST-AUTH-001-04: Edge cases + * Verifies: #25 (REQ-F-AUTH-001) - input validation + */ + describe('Edge Cases (Verifies #25)', () => { + it('should reject empty email', async () => { + await expect( + authenticateUser('', 'password') + ).rejects.toThrow('Email required'); + }); + + it('should reject invalid email format', async () => { + await expect( + authenticateUser('not-an-email', 'password') + ).rejects.toThrow('Invalid email format'); + }); + + it('should handle SQL injection attempts safely', async () => { + const malicious = "' OR '1'='1' --"; + await expect( + authenticateUser(malicious, 'password') + ).rejects.toThrow('Invalid email format'); + }); + }); +}); +``` + +### Run Tests (They Should Fail - RED Phase) + +```bash +# Run tests - they should fail because implementation doesn't exist +npm test -- auth/authenticate.test.ts + +# Expected output: +# ❌ FAIL tests/auth/authenticate.test.ts +# ● User Authentication (Verifies #25) › Happy Path › should authenticate user +# +# Cannot find module '../src/auth/authenticate' +``` + +### Update TEST Issue with Test File Location + +```bash +# Add comment to TEST issue #50 +gh issue comment 50 --body "## Test Implementation + +**Test File**: \`tests/auth/authenticate.test.ts\` +**Status**: ✅ Tests written (RED phase) +**Next**: Implement code to pass tests (GREEN phase) + +**Traceability**: +- Verifies: #25 (REQ-F-AUTH-001) +- All test scenarios implemented +- Ready for implementation" +``` + +--- + +## 🟢 Step 3: GREEN Phase - Minimal Implementation + +### Create Implementation with Issue Traceability + +```typescript +/** + * User authentication module + * + * Implements: #25 (REQ-F-AUTH-001: User Login) + * TEST Issue: #50 (TEST-AUTH-001) + * Traces to: #20 (StR-003: Security Requirements) + * + * See: https://github.com/zarfld/IntelAvbFilter/issues/25 + */ + +import bcrypt from 'bcrypt'; +import jwt from 'jsonwebtoken'; +import { z } from 'zod'; +import { db } from '../db'; +import { logger } from '../logger'; +import { AuthenticationError } from '../errors'; + +// Input validation schema +const AuthInputSchema = z.object({ + email: z.string().email('Invalid email format'), + password: z.string().min(1, 'Password required') +}); + +export interface AuthResult { + authenticated: boolean; + token: string; + expiresIn: number; +} + +/** + * Authenticate user with email and password + * + * @param email - User email address + * @param password - User password (plaintext) + * @returns Authentication result with JWT token + * @throws {AuthenticationError} When credentials are invalid or rate limit exceeded + * + * Implements: #25 (REQ-F-AUTH-001) + * Verifies: #20 (StR-003: Security Requirements) + */ +export async function authenticateUser( + email: string, + password: string +): Promise { + // Validate inputs + const validation = AuthInputSchema.safeParse({ email, password }); + if (!validation.success) { + throw new AuthenticationError(validation.error.errors[0].message, 400); + } + + try { + // Check rate limiting (Implements #26: REQ-NF-SECU-001) + await checkRateLimit(email); + + // Find user by email + const user = await db.users.findUnique({ + where: { email: email.toLowerCase() } + }); + + if (!user) { + await logAuthAttempt(email, false, 'User not found'); + throw new AuthenticationError('Invalid credentials', 401); + } + + // Verify password using bcrypt + const passwordValid = await bcrypt.compare(password, user.passwordHash); + + if (!passwordValid) { + await logAuthAttempt(email, false, 'Invalid password'); + throw new AuthenticationError('Invalid credentials', 401); + } + + // Generate JWT token (24h expiry) + const token = jwt.sign( + { userId: user.id, email: user.email }, + process.env.JWT_SECRET!, + { expiresIn: '24h' } + ); + + // Log successful authentication + await logAuthAttempt(email, true, 'Authentication successful'); + + return { + authenticated: true, + token, + expiresIn: 86400 // 24 hours in seconds + }; + } catch (error) { + logger.error('Authentication error', { email, error }); + throw error; + } +} + +/** + * Check if user has exceeded rate limit + * + * Implements: #26 (REQ-NF-SECU-001: Rate limiting) + */ +async function checkRateLimit(email: string): Promise { + const fifteenMinutesAgo = new Date(Date.now() - 15 * 60 * 1000); + + const recentAttempts = await db.authLogs.count({ + where: { + email, + success: false, + timestamp: { gte: fifteenMinutesAgo } + } + }); + + if (recentAttempts >= 5) { + throw new AuthenticationError( + 'Too many authentication attempts. Try again in 15 minutes.', + 429 + ); + } +} + +/** + * Log authentication attempt + * + * Implements: #27 (REQ-NF-SECU-002: Authentication logging) + */ +async function logAuthAttempt( + email: string, + success: boolean, + reason: string +): Promise { + await db.authLogs.create({ + data: { + email, + success, + reason, + timestamp: new Date() + } + }); +} +``` + +### Run Tests (They Should Pass - GREEN Phase) + +```bash +# Run tests - they should all pass now +npm test -- auth/authenticate.test.ts + +# Expected output: +# ✅ PASS tests/auth/authenticate.test.ts +# User Authentication (Verifies #25) +# Happy Path (Verifies #25) +# ✓ should authenticate user with valid credentials (45ms) +# ✓ should return valid JWT token (32ms) +# Error Cases (Verifies #25) +# ✓ should reject invalid password (28ms) +# ✓ should reject non-existent user (25ms) +# Security (Verifies #26) +# ✓ should log authentication attempt (35ms) +# ✓ should enforce rate limiting (152ms) +# Edge Cases (Verifies #25) +# ✓ should reject empty email (12ms) +# ✓ should reject invalid email format (10ms) +# ✓ should handle SQL injection attempts safely (15ms) +# +# Tests: 9 passed, 9 total +``` + +--- + +## 🔨 Step 4: REFACTOR Phase + +### Improve Code Quality (Keep Tests Green) -## Red +```typescript +/** + * User authentication module (REFACTORED) + * + * Implements: #25 (REQ-F-AUTH-001: User Login) + * TEST Issue: #50 (TEST-AUTH-001) + */ -Write or update a deterministic check before changing production code. +import bcrypt from 'bcrypt'; +import jwt from 'jsonwebtoken'; +import { z } from 'zod'; +import { db } from '../db'; +import { logger } from '../logger'; +import { AuthenticationError } from '../errors'; +import { config } from '../config'; -The Red result must: -- fail on the current implementation; -- fail for the intended missing or defective behavior — not a build or fixture problem; -- carry traceability to the issue or acceptance criterion (`/* Verifies: #N */`). +// Constants +const JWT_EXPIRY = '24h'; +const JWT_EXPIRY_SECONDS = 86400; +const RATE_LIMIT_WINDOW_MINUTES = 15; +const RATE_LIMIT_MAX_ATTEMPTS = 5; -Valid Red checks for PoKeysHal: -- C unit test for parsing, conversion, state transition, or mapping; -- protocol test for command ID, response offset, retry, timeout, or error; -- async mailbox or scheduler regression test; -- HAL export or userspace component check; -- compile or link regression when compilation is the requirement. +// Input validation schema +const AuthInputSchema = z.object({ + email: z.string().trim().toLowerCase().email('Invalid email format'), + password: z.string().min(1, 'Password required') +}); -A missing device, unavailable HIL fixture, or failed preflight is not a valid Red result. -If issue, architecture, protocol specification, or implementation conflict, resolve the -conflict before changing behavior. +export interface AuthResult { + authenticated: boolean; + token: string; + expiresIn: number; +} -## Green +/** + * Authenticate user with email and password + * + * Implements: #25 (REQ-F-AUTH-001) + */ +export async function authenticateUser( + email: string, + password: string +): Promise { + // Validate and normalize inputs + const { email: normalizedEmail, password: validPassword } = validateAuthInput(email, password); + + // Check rate limiting + await enforceRateLimit(normalizedEmail); + + // Authenticate user + const user = await findAndVerifyUser(normalizedEmail, validPassword); + + // Generate token + const token = generateAuthToken(user); + + // Log success + await logAuthAttempt(normalizedEmail, true, 'Authentication successful'); + + return { + authenticated: true, + token, + expiresIn: JWT_EXPIRY_SECONDS + }; +} -Implement the smallest complete change that makes the Red check pass without -weakening or deleting any existing check. +/** + * Validate authentication inputs + */ +function validateAuthInput(email: string, password: string) { + const validation = AuthInputSchema.safeParse({ email, password }); + + if (!validation.success) { + const error = validation.error.errors[0]; + throw new AuthenticationError(error.message, 400); + } + + return validation.data; +} -Preserve: -- C99 compatibility; -- PoKeysLib subsystem boundaries and the async infrastructure / subsystem / - integration-shell separation defined in `c-architecture-realtime.instructions.md`; -- protocol command codes, byte offsets, masks, and response semantics; -- existing HAL names and ABI unless the issue explicitly changes them; -- bounded execution and the absence of dynamic allocation on RT-reachable paths. +/** + * Enforce rate limiting + * Implements: #26 (REQ-NF-SECU-001) + */ +async function enforceRateLimit(email: string): Promise { + const windowStart = new Date(Date.now() - RATE_LIMIT_WINDOW_MINUTES * 60 * 1000); + + const failedAttempts = await db.authLogs.count({ + where: { + email, + success: false, + timestamp: { gte: windowStart } + } + }); + + if (failedAttempts >= RATE_LIMIT_MAX_ATTEMPTS) { + throw new AuthenticationError( + `Too many authentication attempts. Try again in ${RATE_LIMIT_WINDOW_MINUTES} minutes.`, + 429 + ); + } +} -No speculative abstractions, unrelated cleanup, or parallel variants. +/** + * Find user and verify password + */ +async function findAndVerifyUser(email: string, password: string) { + const user = await db.users.findUnique({ + where: { email } + }); + + if (!user) { + await logAuthAttempt(email, false, 'User not found'); + throw new AuthenticationError('Invalid credentials', 401); + } + + const passwordValid = await bcrypt.compare(password, user.passwordHash); + + if (!passwordValid) { + await logAuthAttempt(email, false, 'Invalid password'); + throw new AuthenticationError('Invalid credentials', 401); + } + + return user; +} -## Refactor +/** + * Generate JWT authentication token + */ +function generateAuthToken(user: { id: string; email: string }): string { + return jwt.sign( + { userId: user.id, email: user.email }, + config.jwtSecret, + { expiresIn: JWT_EXPIRY } + ); +} + +/** + * Log authentication attempt + * Implements: #27 (REQ-NF-SECU-002) + */ +async function logAuthAttempt( + email: string, + success: boolean, + reason: string +): Promise { + await db.authLogs.create({ + data: { + email, + success, + reason, + timestamp: new Date() + } + }); +} +``` -After Green: remove local duplication, improve naming, simplify control flow. -Do not introduce additional behavior. Keep all applicable checks green. +### Run Tests Again (Should Still Pass) -## Verify outward +```bash +npm test -- auth/authenticate.test.ts -Run checks narrowest to broadest. Stop at the first failure and diagnose before -proceeding outward. +# ✅ All tests still passing after refactor +``` -1. focused unit or protocol test; -2. affected library or component build (`make -f Makefile.noqmake`); -3. repository compile check (`bash test_compile.sh`); -4. userspace HAL smoke test, when applicable (`halrun -f `); -5. RT-environment validation, when applicable; -6. HIL confirmation for hardware-dependent acceptance criteria — use the **hil-tdd** skill. +--- -## Hardware-dependent behavior +## 📦 Step 5: Create Pull Request with Issue Links -For acceptance criteria that require real hardware, use the **hil-tdd** skill. -Do not duplicate that procedure here. +### Commit Changes with Issue References -HIL status vocabulary is defined in -`.github/skills/hil-tdd/references/result-schema.md`: -`HIL-observed`, `HIL-test-executed`, `HIL-verified`, `RT-validated`, `Timing-validated`. +```bash +# Stage files +git add tests/auth/authenticate.test.ts +git add src/auth/authenticate.ts + +# Commit with issue references +git commit -m "feat(auth): implement user authentication + +Implements: #25 (REQ-F-AUTH-001: User Login) +TEST Issue: #50 (TEST-AUTH-001) +Traces to: #20 (StR-003: Security Requirements) + +Features: +- Email/password authentication +- JWT token generation (24h expiry) +- Rate limiting (5 attempts per 15 min) +- Authentication logging +- Input validation and sanitization + +Tests: +- 9 test scenarios covering happy path, errors, security, edge cases +- All tests passing +- Code coverage: 95%+ + +TDD Cycle: +- RED: Tests written first (all failing) +- GREEN: Minimal implementation (all passing) +- REFACTOR: Improved code quality (all still passing)" + +# Push to branch +git push origin feature/user-authentication +``` -Do not claim `HIL-verified` from a mock, simulator, or userspace-only run. +### Create PR with Issue Links + +```bash +# Create PR via GitHub CLI +gh pr create \ + --title "feat(auth): implement user authentication (#25)" \ + --body "## Description +Implements user authentication functionality using email and password. + +## Related Issues +- **Implements**: #25 (REQ-F-AUTH-001: User Login) +- **Implements**: #26 (REQ-NF-SECU-001: Rate limiting) +- **Implements**: #27 (REQ-NF-SECU-002: Authentication logging) +- **TEST Issue**: #50 (TEST-AUTH-001) +- Traces to: #20 (StR-003: Security Requirements) + +## TDD Workflow +✅ RED: Tests written first (9 scenarios) +✅ GREEN: Implementation passes all tests +✅ REFACTOR: Code quality improved + +## Test Coverage +- **Tests**: 9/9 passing +- **Coverage**: 95%+ (lines), 92%+ (branches) +- **Test File**: \`tests/auth/authenticate.test.ts\` ## Traceability +- All test functions include \`Verifies: #N\` comments +- Implementation includes \`Implements: #N\` comments +- Links to requirement and TEST issues + +## Checklist +- [x] Tests written first (TDD) +- [x] All tests passing +- [x] Code coverage >80% +- [x] Traceability comments added +- [x] No stubs/mocks in production code +- [x] Documentation updated +- [x] PR links to issues" \ + --base master \ + --head feature/user-authentication +``` -- Source: `/* Implements: #N (REQ-F-xxx) */` -- Tests: `/* Verifies: #N */` -- PRs: `Fixes #N` or `Implements #N` +### Update TEST Issue After PR Merge -## Handoff evidence +```bash +# After PR is merged, update TEST issue +gh issue comment 50 --body "## ✅ Implementation Complete + +**PR**: #150 (merged) +**Status**: All tests passing in production + +**Code Files**: +- \`src/auth/authenticate.ts\` - Implementation +- \`tests/auth/authenticate.test.ts\` - Test suite + +**Coverage**: 95%+ lines, 92%+ branches + +**Traceability**: All requirements verified ✅" + +# Close TEST issue if all done +gh issue close 50 --comment "All test scenarios implemented and verified. Closing TEST issue." +``` + +--- + +## ✅ TDD Checklist (Every Implementation) + +**Before Starting**: +- [ ] Requirement issue (#N) exists and is understood +- [ ] TEST issue exists with scenarios defined +- [ ] Acceptance criteria clear + +**RED Phase**: +- [ ] Tests written FIRST (before any implementation) +- [ ] Tests include `Verifies: #N` traceability +- [ ] Tests cover: happy path, errors, edge cases +- [ ] All tests fail initially (no implementation yet) +- [ ] TEST issue updated with test file location + +**GREEN Phase**: +- [ ] Implementation written to pass tests +- [ ] Implementation includes `Implements: #N` traceability +- [ ] All tests now pass +- [ ] Minimal code (no extra features) +- [ ] No stubs/mocks in production code + +**REFACTOR Phase**: +- [ ] Code improved for readability/maintainability +- [ ] All tests still passing after refactor +- [ ] Code coverage >80% +- [ ] No dead code or duplication + +**PR Phase**: +- [ ] Commit messages reference issues +- [ ] PR title includes issue number +- [ ] PR body links to all related issues +- [ ] CI/CD passes (tests, linting, coverage) +- [ ] Code review approved +- [ ] TEST/REQ issues updated after merge + +--- + +## 🚀 Usage + +### Start TDD Workflow for Requirement + +```bash +# Copilot Chat +@workspace Implement requirement #25 using TDD workflow + +# Steps: +# 1. Query issue #25 for requirements +# 2. Find TEST issue #50 +# 3. Write tests first (RED phase) +# 4. Implement code (GREEN phase) +# 5. Refactor (keep tests green) +# 6. Create PR with issue links +``` + +### Generate Tests from TEST Issue + +```bash +@workspace Generate tests for TEST issue #50 + +# Include: +# - Verifies: #25 traceability +# - All test scenarios from issue +# - AAA pattern +# - Acceptance criteria +``` + +### Implement Code from Failing Tests + +```bash +@workspace Implement code to pass tests in tests/auth/authenticate.test.ts + +# Include: +# - Implements: #25 traceability +# - Minimal implementation +# - Pass all tests +``` + +--- -Report exactly: -- files changed and requirement addressed; -- tests added or changed and commands executed with results; -- unavailable checks and why; -- remaining risks; -- precise status from: - **Implemented · Compiled · Tested · HIL-test-executed · HIL-verified · - RT-validated · Timing-validated** +**Remember**: Tests ALWAYS come first! Red → Green → Refactor → PR with issue links! 🔴🟢🔨