@metasession.co/devaudit-cli 0.1.1 → 0.1.2

package/sdlc/files/_common/1-plan-requirement.md

@@ -0,0 +1,381 @@
+---
+description: Define a new requirement in the RTM, classify risk, create implementation plan, generate test scope, and prepare for implementation
+---
+
+# Plan Requirement
+
+**Pipeline Stage:** 1 of 5
+**Next:** `2-implement-and-test.md`
+**References:** Test Policy (`sdlc/files/Test_Policy.md` in DevAudit) (risk classification, AI governance), Test Strategy (risk matrix, testing depth, AI documentation)
+
+---
+
+## When to Use
+
+- New features, enhancements, or significant changes
+- **Bug fixes that affect financial calculations, user-facing data, or access control**
+- Work that needs formal traceability (security, payments, RBAC, data handling)
+- Any change a stakeholder or auditor might ask "was this tested?"
+
+**Skip this workflow** for trivial changes (typo fixes, formatting, dependency bumps) — go straight to `2-implement-and-test.md`.
+
+**Even for trivial changes:** review existing tests for impact and run all gates locally before pushing.
+
+## Steps
+
+### Step 1: Identify the GitHub Issue
+
+Every tracked change starts from a GitHub Issue. The issue provides the *what* and *why*; the RTM provides the compliance audit trail.
+
+- If the user references an issue number (e.g., `#123`): fetch its title, description, and labels using `gh issue view 123`.
+- If the user describes work without an issue: ask **"Is there a GitHub Issue for this, or should we create one?"**
+  - To create one: `gh issue create --title "[title]" --body "[description]" --label "[labels]"`
+- Use issue labels to inform risk classification in Step 3 (e.g., `security`, `user-facing`, `internal`).
+
+### Step 2: Determine the Next Requirement ID
+
+```bash
+grep -oP 'REQ-\d+' compliance/RTM.md | sort -t- -k2 -n | tail -1
+```
+
+The next ID is one higher (e.g., if the last is REQ-007, use REQ-008).
+
+### Step 3: Classify Risk Level
+
+| Risk Level | Criteria |
+|---|---|
+| **Low** | Internal tools, no regulated data, no auth changes |
+| **Medium** | Touches PII, user-facing features, API changes, new dependencies |
+| **High** | Security, payments, RBAC, data handling, authentication |
+
+AI involvement raises risk by one level when touching Medium or High categories. See Test Policy for the full risk matrix.
+
+### Step 4: Add Entry to RTM
+
+Open `compliance/RTM.md`, Part B. The issue provides full context; the RTM is a traceability index, not a content store.
+
+```markdown
+| REQ-XXX | #NNN | [LOW/MEDIUM/HIGH] | compliance/evidence/REQ-XXX/ | DRAFT | -- | -- |
+```
+
+The auditor reads one row and follows the links: Issue for context and rationale, evidence directory for test artifacts, PR for code changes.
+
+### Step 5: Create Evidence Directory
+
+```bash
+mkdir -p compliance/evidence/REQ-XXX
+```
+
+### Step 6: Implementation Plan (MEDIUM/HIGH Risk — Required)
+
+For MEDIUM and HIGH risk requirements, create an implementation plan before defining test scope. The implementation plan defines *what code changes are needed* — the test scope is then derived from it.
+
+**Skip this step** for LOW risk requirements — proceed directly to Step 7.
+
+**6a. Explore the codebase:**
+- Understand existing patterns, models, services, and API routes relevant to the change
+- Identify files that will be created, modified, or affected
+
+**6b. Create the implementation plan:**
+
+Create `compliance/evidence/REQ-XXX/implementation-plan.md`:
+
+```markdown
+# Implementation Plan — REQ-XXX
+
+**Requirement:** REQ-XXX
+**GitHub Issue:** #NNN
+**Risk Level:** [MEDIUM / HIGH]
+**Date:** [YYYY-MM-DD]
+
+## Approach
+[1-3 sentences describing the overall approach]
+
+## Files to Create
+- `path/to/new-file.ts` — [purpose]
+
+## Files to Modify
+- `path/to/existing-file.ts` — [what changes and why]
+
+## Architecture Decisions
+- [Key decision 1 and rationale]
+- [Key decision 2 and rationale]
+
+## Dependencies
+- [New packages needed, or "None"]
+
+## Risks / Considerations
+- [Anything that could go wrong or needs special attention]
+
+## Post-Deploy Actions
+- [Data migrations, backfill scripts, schema changes — or "None"]
+- [If any: create script in `scripts/`, document exact command and target environment]
+```
+
+### WAIT CHECKPOINT: Implementation Plan Review
+
+**Present the implementation plan to the developer.** Summarize:
+- Approach and rationale
+- Files to create/modify
+- Architecture decisions
+- Risks and dependencies
+
+**Do NOT proceed** until the developer explicitly approves the plan. If the developer requests changes, update `implementation-plan.md` and re-present. For HIGH risk, this review is especially important — it's cheaper to change the plan than to refactor the code.
+
+**6c. Commit the plan:**
+
+```bash
+git add compliance/evidence/REQ-XXX/implementation-plan.md
+git commit -m "chore(compliance): [REQ-XXX] implementation plan
+
+Ref: REQ-XXX
+
+Co-Authored-By: [AI tool tag]"
+```
+
+---
+
+### Step 7: Generate Test Scope
+
+Create a test scope document proportional to the assessed risk level. For MEDIUM/HIGH risk, this is derived from the implementation plan — you now know what code is changing and can define what tests are needed.
+
+This must exist **before implementation begins** — it is the evidence that testing was planned, not retroactively documented.
+
+The AI generates this based on the risk classification, the implementation plan (if applicable), and the Test Strategy's risk-based testing depth matrix.
+
+**For LOW risk:**
+
+```bash
+cat > compliance/evidence/REQ-XXX/test-scope.md << 'EOF'
+# Test Scope — REQ-XXX
+
+**Risk Level:** LOW
+**Requirement:** [Brief description]
+**GitHub Issue:** #NNN
+**Date:** [YYYY-MM-DD]
+
+## Test Approach
+
+Standard gates apply. No additional testing beyond universal exit criteria.
+
+- TypeScript compilation: 0 errors
+- SAST scan: 0 high/critical findings
+- Dependency audit: 0 high/critical vulnerabilities
+- E2E suite: all pass
+- CI independent verification: all PR checks pass
+- Human code review via PR
+
+## Acceptance Criteria
+
+- [x] [Criterion 1 — what "done" looks like]
+- [x] [Criterion 2]
+EOF
+```
+
+**For MEDIUM risk:**
+
+```bash
+cat > compliance/evidence/REQ-XXX/test-scope.md << 'EOF'
+# Test Scope — REQ-XXX
+
+**Risk Level:** MEDIUM
+**Requirement:** [Brief description]
+**GitHub Issue:** #NNN
+**Date:** [YYYY-MM-DD]
+
+## Test Approach
+
+Standard gates plus targeted verification.
+
+**Universal gates (mandatory — verified locally AND in CI):**
+- TypeScript compilation: 0 errors
+- SAST scan: 0 high/critical findings
+- Dependency audit: 0 high/critical vulnerabilities
+- E2E suite: all pass (full suite local, unauthenticated subset in CI)
+- Human code review via PR
+
+**Additional testing required by risk level:**
+- [ ] Access control: [which endpoints/roles need verification]
+- [ ] Audit logging: [which actions must produce log entries]
+- [ ] Dependency review: [if new packages, verify real/current/no CVEs]
+- [ ] [Any other area-specific testing]
+
+## Validation Approach
+
+How we confirm this meets the business requirement:
+- [e.g., "Verify public page displays new content correctly"]
+- [e.g., "Confirm edits are visible to users within expected time"]
+
+## Acceptance Criteria
+
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] All additional testing items above pass
+EOF
+```
+
+**For HIGH risk:**
+
+```bash
+cat > compliance/evidence/REQ-XXX/test-scope.md << 'EOF'
+# Test Scope — REQ-XXX
+
+**Risk Level:** HIGH
+**Requirement:** [Brief description]
+**GitHub Issue:** #NNN
+**Date:** [YYYY-MM-DD]
+
+## Test Approach
+
+Full verification and validation per Test Strategy high-risk requirements.
+
+**Universal gates (mandatory — verified locally AND in CI):**
+- TypeScript compilation: 0 errors
+- SAST scan: 0 high/critical findings
+- Dependency audit: 0 high/critical vulnerabilities
+- E2E suite: all pass
+- Human code review via PR
+
+**Security testing (mandatory for HIGH):**
+- [ ] Access control: [specific endpoints, roles, expected behaviors]
+- [ ] Audit logging: [specific actions that must produce entries]
+- [ ] Input validation: [boundary/injection testing needed]
+- [ ] Error handling: [verify no sensitive data in error responses]
+
+**Additional high-risk testing:**
+- [ ] Independent review: [who will provide secondary review]
+- [ ] Penetration testing consideration: [warranted? justification]
+- [ ] Performance impact: [load/performance concerns]
+- [ ] Regression scope: [areas needing manual verification beyond E2E]
+
+## Validation Approach
+
+How we confirm this meets the business requirement:
+- [Specific user workflow to test end-to-end]
+- [Business rule to validate]
+- [Stakeholder sign-off needed? From whom?]
+
+## AI Involvement (if applicable)
+
+- AI tool: [tool name / none]
+- Code categories AI will generate: [list]
+- Elevated review required for: [security-sensitive files]
+- Regeneration protocol: [will any components be regenerated?]
+
+## Acceptance Criteria
+
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] All security testing items pass
+- [ ] All validation items confirmed
+- [ ] Independent review completed (if required)
+EOF
+```
+
+### WAIT CHECKPOINT: Test Scope Review
+
+**Present the test scope to the developer.** Summarize:
+- Risk classification and rationale
+- Test approach (which additional testing applies)
+- Acceptance criteria
+
+**Do NOT proceed** until the developer confirms the test scope is complete and correct. If the developer requests changes, update `test-scope.md` and re-present.
+
+---
+
+### Step 8: Create Test Plan
+
+Create a test plan that maps acceptance criteria to specific tests. This documents what tests to add, update, or remove — evidence that testing was planned, not ad hoc.
+
+The test plan is proportional to risk. For LOW risk, a brief plan is sufficient. For MEDIUM/HIGH, include non-functional testing and test data requirements.
+
+```bash
+cat > compliance/evidence/REQ-XXX/test-plan.md << 'EOF'
+# Test Plan — REQ-XXX
+
+**Requirement:** REQ-XXX
+**Risk Level:** [LOW / MEDIUM / HIGH]
+**GitHub Issue:** #NNN
+**Date:** [YYYY-MM-DD]
+
+## Tests to Add
+- [ ] `e2e/[spec-file].spec.ts` — [what it tests]
+- [ ] `__tests__/[test-file].test.ts` — [what it tests]
+
+## Tests to Update
+- [ ] `e2e/[existing-spec].spec.ts` — [what changes and why]
+
+## Tests to Remove
+- [ ] `e2e/[obsolete-spec].spec.ts` — [justification for removal]
+- [or "None"]
+
+## Functional Test Mapping
+| Acceptance Criterion | Test File | Test Name |
+|---------------------|-----------|-----------|
+| [From test-scope.md] | [spec file] | [test name] |
+
+## Non-Functional Tests (MEDIUM/HIGH)
+- [ ] Security: [access control, input validation tests needed]
+- [ ] Performance: [load/performance concerns]
+- [ ] Accessibility: [if applicable]
+- [or "Standard gates sufficient for LOW risk"]
+
+## Test Data Requirements
+- [Database seeding needed?]
+- [Test fixtures to create?]
+- [or "Existing test data sufficient"]
+EOF
+```
+
+### WAIT CHECKPOINT: Test Plan Review
+
+**Present the test plan to the developer.** Summarize:
+- Tests to add, update, and remove
+- How acceptance criteria map to specific tests
+- Any non-functional testing required
+
+**Do NOT proceed** until the developer confirms the test plan is complete and correct. If the developer requests changes, update `test-plan.md` and re-present.
+
+---
+
+### Step 9: Update Requirements Document (If Applicable)
+
+If the requirement modifies a documented feature, update the requirements document to reflect the intended change.
+
+### Step 10: Document AI Use Intent (If Applicable)
+
+If AI will generate code (Medium/High risk):
+
+```bash
+cat > compliance/evidence/REQ-XXX/ai-use-note.md << 'EOF'
+# AI Use Record — REQ-XXX
+
+**AI Tool:** [tool name]
+**Planned AI Use:** [implementation / test generation / both / none]
+**Risk Classification Impact:** [note if risk was raised due to AI involvement]
+EOF
+```
+
+For Low risk, the `Co-Authored-By` commit tag is sufficient.
+
+### Step 11: Commit
+
+```bash
+git add compliance/RTM.md compliance/evidence/REQ-XXX docs/REQUIREMENTS.md
+git commit -m "compliance: [REQ-XXX] define requirement and test scope - [description] [RISK: LOW/MEDIUM/HIGH]
+
+Ref: REQ-XXX
+Closes: #NNN"
+```
+
+## Output
+
+- GitHub Issue `#NNN` identified or created as the origin of the change
+- REQ-XXX in RTM with `DRAFT`, risk classification, and issue reference
+- Implementation plan (MEDIUM/HIGH risk — approved by developer before test scope)
+- Evidence directory with test scope and test plan (derived from implementation plan)
+- AI use note (if applicable)
+
+## Next Step
+
+Proceed to `2-implement-and-test.md`. Refer back to `test-scope.md` during implementation.

package/sdlc/files/_common/2-implement-and-test.md

@@ -0,0 +1,276 @@
+---
+description: Implement changes on develop, run all local gates (tests + security scans), commit with compliance-aware conventions
+---
+
+# Implement & Test
+
+**Pipeline Stage:** 2 of 5
+**Previous:** `1-plan-requirement.md` (if tracked) or start here for untracked changes
+**Next:** `3-compile-evidence.md`
+**References:** Test Strategy (`sdlc/files/Test_Strategy.md` in DevAudit) (security gates, AI methodology), Test Architecture (tooling), Test Plan (exit criteria)
+
+---
+
+## Prerequisites
+
+- On the `develop` branch
+- Dev server starts
+- Database running locally
+- Playwright browsers installed
+- Test data seeded
+- Semgrep installed
+
+## Steps
+
+### Step 0: Validate Planning Artifacts (Tracked Requirements)
+
+Before writing any code, verify that the planning stage is complete:
+
+```bash
+# For tracked requirements — ALL planning artifacts MUST exist
+ls compliance/evidence/REQ-XXX/test-scope.md
+ls compliance/evidence/REQ-XXX/test-plan.md
+grep 'REQ-XXX' compliance/RTM.md
+```
+
+**If any file does not exist:** STOP. Run `1-plan-requirement.md` first. Do NOT proceed to implementation without a committed test scope and test plan.
+
+For MEDIUM/HIGH risk, also verify:
+```bash
+# Implementation plan must exist (created during planning stage)
+ls compliance/evidence/REQ-XXX/implementation-plan.md
+```
+
+---
+
+### Step 1: Verify Branch
+
+```bash
+git branch --show-current
+# Must output: develop
+```
+
+If not: `git checkout develop && git pull origin develop`
+
+### Step 2: Unit Tests (TDD)
+
+Write or update unit tests **before** implementing the code. You know the expected interfaces and behaviour from the implementation plan and test plan.
+
+**2a. Review the test plan:**
+```bash
+cat compliance/evidence/REQ-XXX/test-plan.md
+```
+
+**2b. Write unit tests** listed in the "Tests to Add" section:
+- New business logic → unit tests for services, utilities, validators
+- New API endpoints → auth enforcement tests, response format tests
+- Tests should initially **fail** (the implementation doesn't exist yet)
+
+**2c. Update existing unit tests** listed in the "Tests to Update" section:
+- API response shape changed? → Update assertions
+- Business logic changed? → Update unit test expectations
+
+**2d. Remove obsolete tests** listed in the "Tests to Remove" section (if any). Each removal must have a justification in the test plan.
+
+### WAIT CHECKPOINT: Unit Test Coverage
+
+Verify the unit tests cover the test plan:
+```bash
+cat compliance/evidence/REQ-XXX/test-plan.md
+# Check: have all unit test items in "Tests to Add" been implemented?
+# Check: have all unit test items in "Tests to Update" been addressed?
+```
+
+**Do NOT proceed** until unit test coverage matches the test plan. Tests are expected to fail at this point — that's correct (TDD).
+
+### Step 3: Implement the Change
+
+Write your code. For tracked requirements, add JSDoc headers:
+
+```typescript
+/**
+ * @requirement REQ-XXX - Brief description
+ */
+```
+
+**If AI is generating code (Medium/High risk):**
+
+```bash
+echo "Prompt summary: [what you asked AI to generate]" >> compliance/evidence/REQ-XXX/ai-prompts.md
+echo "Files generated: [list]" >> compliance/evidence/REQ-XXX/ai-prompts.md
+echo "Date: $(date -I)" >> compliance/evidence/REQ-XXX/ai-prompts.md
+```
+
+**If AI regenerates a component** (from scratch, not incremental edit):
+
+```bash
+echo "REGENERATION: [component] regenerated on $(date -I). Full retest required." >> compliance/evidence/REQ-XXX/ai-prompts.md
+```
+
+Per Test Strategy: regeneration triggers full retest.
+
+**MEDIUM/HIGH risk — AI prompt logging checkpoint:** Before committing AI-generated code, verify that `ai-prompts.md` has been updated with the prompt summary and files generated. If missing, create it now — this is a required artifact for MEDIUM/HIGH risk requirements with AI involvement.
+
+### WAIT CHECKPOINT: Unit Tests Green
+
+All unit tests must pass before proceeding:
+```bash
+npm test
+```
+
+**Do NOT proceed** until all unit tests are green.
+
+### Step 4: E2E Tests
+
+Write or update E2E tests **after** implementation. E2E tests need working UI/API to test against — writing Playwright tests against routes and selectors that don't exist is impractical.
+
+> **Skill available:** invoke the **`e2e-test-engineer`** skill for this step (at `.claude/skills/e2e-test-engineer/SKILL.md`). It derives scenarios from the requirement's acceptance criteria, reconciles with the existing test pack (flags obsoletes — but never deletes without confirmation), runs the suite, and files defects for failures or missed ACs. Framework-agnostic (Playwright, Cypress, pytest-playwright, etc.) and tracker-agnostic (GitHub, Linear, Jira, etc.). For projects with no e2e suite yet, the skill also covers bootstrapping one. See [`sdlc/SKILLS.md`](../sdlc/SKILLS.md) for the full list of available skills.
+
+**4a. Review the test plan for E2E items:**
+```bash
+cat compliance/evidence/REQ-XXX/test-plan.md
+```
+
+**4b. Add new E2E tests** listed in the "Tests to Add" section:
+- New pages → route protection tests (unauthenticated redirect)
+- New user flows → Playwright tests for critical paths
+- UI components changed? → Update selectors and expected content
+
+**4c. Update existing E2E tests** listed in the "Tests to Update" section:
+- New routes added? → Add them to route protection test arrays
+- UI flow changed? → Update selectors and assertions
+
+**4d. Remove obsolete E2E tests** listed in the "Tests to Remove" section (if any).
+
+### WAIT CHECKPOINT: E2E Tests Green
+
+All E2E tests must pass:
+```bash
+npx playwright test
+```
+
+**Do NOT proceed** until all E2E tests are green.
+
+### Step 5: Stage Selectively
+
+```bash
+git diff --name-only
+git add src/path/to/file.ts
+
+# Safety check — no secrets staged
+git diff --cached --name-only | grep -iE '\.env|secret|credential|\.auth|\.pem'
+# Must return nothing
+```
+
+### Step 6: Commit
+
+```bash
+git commit -m "$(cat <<'EOF'
+type(scope): description
+
+- Key change 1
+- Key change 2
+
+Ref: REQ-XXX
+
+Co-Authored-By: [AI Tool Name] <noreply@provider.com>
+EOF
+)"
+```
+
+Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `compliance`, `security`
+
+### Step 7: Run All Local Gates (Mandatory)
+
+#### Gate 1: TypeScript
+```bash
+npx tsc --noEmit
+```
+
+#### Gate 2: Security (SAST + Dependencies)
+```bash
+semgrep scan --config auto [SOURCE_DIR]/ --severity ERROR --severity WARNING
+npm audit --audit-level=high
+```
+
+If new dependencies added:
+```bash
+git diff origin/main -- package.json package-lock.json | grep '^\+'
+npm audit
+# Verify: real packages? Current versions? No CVEs? AI hallucinations?
+```
+
+#### Gate 3: E2E Tests
+```bash
+npx playwright test
+```
+
+#### Exit Criteria
+
+| Gate | Threshold |
+|---|---|
+| TypeScript | 0 errors |
+| SAST (high/critical) | 0 findings |
+| Dependencies (high/critical) | 0 vulnerabilities |
+| E2E tests | All pass |
+| Severity-1 defects | 0 open |
+
+For Medium/High risk, also verify access control and audit log tests pass (see Test Plan and test-scope.md).
+
+**If SAST finds issues:**
+```bash
+echo "SAST finding: [rule-id] in [file] — [fixed/false-positive: reason]" >> compliance/evidence/REQ-XXX/sast-review.md
+```
+
+### Step 8: Push
+
+```bash
+git push origin develop
+```
+
+If rejected:
+```bash
+git pull --rebase origin develop
+# Re-run ALL local gates after rebase
+git push origin develop
+```
+
+Pushing to `develop` triggers the full CI pipeline (TypeScript, SAST, dependency audit, E2E, build). All gate results are automatically uploaded to DevAudit tagged with the release version and `environment=uat`. The develop branch auto-deploys to the UAT environment (Railway staging). UAT will be formally reviewed and approved in DevAudit before a PR to main can be created.
+
+### WAIT CHECKPOINT: Confirm CI Green
+
+After pushing, wait for CI to complete before proceeding:
+
+```bash
+gh run list --branch develop --limit 1
+# Or watch in real time:
+gh run watch
+```
+
+**Do NOT proceed** until CI is green. If CI fails, diagnose the failure, fix locally, re-run all local gates, and push again. Do not push repeatedly hoping CI will pass — fix the root cause.
+
+### Step 9: Update Evidence
+
+```bash
+git status compliance/evidence/
+git add compliance/evidence/
+git commit -m "compliance: update test evidence"
+git push origin develop
+```
+
+## Iteration
+
+Repeat Steps 3-9. Every commit must leave all local gates green. Step 2 (implementation plan) is done once per requirement. Each push triggers full CI and auto-deploys to UAT.
+
+## Output
+
+- Code committed and pushed on `develop`
+- All CI gates passing (TypeScript, SAST, dep audit, E2E, build)
+- Evidence auto-uploaded to DevAudit (environment=uat)
+- AI use documented (if applicable)
+- UAT auto-deployed with latest changes
+
+## Next Step
+
+- **Tracked requirement:** `3-compile-evidence.md`
+- **Untracked change:** `4-submit-for-review.md`