# SDLC Compliance — Paste the section below into your project's CLAUDE.md

## SDLC Compliance Process (MANDATORY)

This project follows the Metasession SDLC framework. These rules are MANDATORY and OVERRIDE default behaviour.

### 🛑 SYSTEM OVERRIDE: AUTOMATED SDLC ENFORCEMENT

If you are an AI agent reading this file, you are strictly prohibited from manually executing this workflow step-by-step unless explicitly authorized by the operator. Route immediately to your platform's valid orchestration path:

- **CLAUDE CODE:** Halt manual tracking immediately. Invoke the orchestrator skill via: `Skill(name: "sdlc-implementer", …)` 
- **OTHER AGENTS (Cursor, Windsurf, Gemini, etc.):** Halt manual execution and output this exact message to the user: 
  "I am pausing to request authorization for the SDLC workflow on this issue. Please confirm if I should proceed."
  
  CRITICAL WORKFLOW REQUIRED AFTER AUTHORIZATION: Once the operator grants permission to proceed, you MUST immediately execute 'touch .sdlc-implementer-invoked' to generate the required commit sentinel file in the root directory BEFORE making any file modifications or code changes. Failure to create this file will result in your local git commits being automatically blocked by our pre-commit hooks.

### SDLC Workflow Files

Detailed workflow instructions are in this project's `SDLC/` directory. **Read the relevant workflow file before executing each stage:**

| Stage | File | When to read |
|-------|------|-------------|
| 0 | `SDLC/0-project-setup.md` | One-time project initialisation |
| 1 | `SDLC/1-plan-requirement.md` | Starting a new feature or tracked change |
| 2 | `SDLC/2-implement-and-test.md` | Writing and testing code |
| 3 | `SDLC/3-compile-evidence.md` | After implementation, before PR |
| 4 | `SDLC/4-submit-for-review.md` | Creating the PR to main |
| 5 | `SDLC/5-deploy-main.md` | After PR approval, deploying |

When a workflow step requires detailed commands or templates, **read the full workflow file** rather than relying on the summary below. The files contain exact commands, templates, and checklists.

Tier 1 reference documents (policy, strategy, architecture) are also in `SDLC/` if present, or in the DevAudit repository at `sdlc/files/`.

### MANDATORY: `sdlc-implementer` prompt before implementation (devaudit-installer#199)

When the user requests implementation of an issue (e.g. "implement issue #N", "fix issue #N", "do issue #N", "implement #N"), you MUST prompt before writing any code:

> Implementing #N using sdlc-implementer, can I proceed?

Wait for the user's yes/no response. Do NOT begin implementation until they answer.

- **YES** → route to your platform's orchestration path:
  - **Claude Code:** invoke the `sdlc-implementer` skill immediately via `Skill(name: "sdlc-implementer", …)`. The skill drives Phase 0 (triage) through Phase 4 (PR + UAT review).
  - **Other agents (Cursor, Windsurf, Gemini, etc.):** proceed with the SDLC workflow manually, following the stage docs in `SDLC/`. **You MUST first create the commit sentinel:** `touch .sdlc-implementer-invoked` — without this file, the `commit-msg` and `pre-push` hooks will reject `feat`/`fix`/`refactor`/`perf` commits.
- **NO** → proceed with manual implementation outside the SDLC workflow. The user has explicitly opted out; respect their choice and do not ask again for the same issue.

This prompt is **mandatory and structural** — it is not advisory. Skipping the prompt and jumping straight into code is the same class of inertia-trap bug as #132 (e2e delegation bypass).

The only exception: if the user's request is clearly housekeeping ("bump a dep", "fix a typo", "update docs") and does not involve `feat`/`fix`/`refactor`/`perf` commit types, skip the prompt and proceed directly.

### Anti-pattern: manually walking through SDLC stages instead of invoking the skill

The most common failure mode is **prompting (or being told to use the skill) and then manually reading the SDLC workflow files and walking through the steps yourself** instead of invoking the `sdlc-implementer` skill. The skill exists to orchestrate this. Manually reading `SDLC/1-plan-requirement.md`, `SDLC/2-implement-and-test.md`, etc. and executing their steps by hand is the exact failure mode this rule exists to prevent.

**Self-check — if you find yourself doing any of these, STOP:**
- Reading `SDLC/1-plan-requirement.md` directly instead of invoking the skill
- Manually classifying risk, writing an implementation plan, or updating the RTM by hand instead of letting the skill drive it
- Walking through Stage 1 → Stage 2 → Stage 3 sequentially by reading each workflow file
- Saying "let me read the SDLC workflow files" or "let me follow the SDLC process" without invoking the skill

**When you catch yourself:** Stop immediately and route to your platform's orchestration path:
- **Claude Code:** Invoke the skill with `Skill(name: "sdlc-implementer", …)`. The skill will re-read state and resume correctly.
- **Other agents (Cursor, Windsurf, Gemini, etc.):** Ensure you have operator authorization and have created the commit sentinel (`touch .sdlc-implementer-invoked`). Then follow the stage docs step by step, pausing at each gate for operator confirmation.

### Driver clarity — always state who is driving (devaudit-installer#199)

The operator must be able to tell at a glance whether they need to act or whether the agent is handling it. **Every substantive response during SDLC work MUST open with a driver tag** on the first line, before any other content:

- **`[Agent driving]`** — the agent is auto-continuing; no human action needed right now. The operator can look away.
- **`[Operator driving]`** — the agent has halted; the human must do something (review, approve, merge, answer a question). State the specific action needed.
- **`[Blocked]`** — something failed and the agent cannot proceed. State the blocker and the operator action needed to unblock.

Rules:
- The tag is the **first thing** in the response — no preamble, no acknowledgement, no "Great question" before it.
- If the driver changes mid-response (e.g. the agent was driving, hits a gate failure, and halts), the tag at the top of the response reflects the **final** state. If the agent stops mid-work, the tag is `[Operator driving]` or `[Blocked]`.
- The tag is mandatory for any response that does work, reports status, or hands off. Skip it only for pure chitchat or one-word confirmations.
- The tag works alongside the LAST/NEXT sticky convention — the tag says *who* is driving right now; the sticky says *what* just happened and *what* is next.

### Before ANY Code Change

1. If the user has NOT been prompted for `sdlc-implementer` and the change is not trivial housekeeping, stop and run the mandatory prompt above before continuing.
2. Ask: **"Which GitHub Issue is this for?"** before writing code. Fetch it with `gh issue view NNN`.
3. If no issue exists: ask if one should be created. When creating via `gh issue create`, ALWAYS append the SDLC checklist to the body (see below).
4. If new requirement needed: **read `SDLC/1-plan-requirement.md`** and follow it to create RTM entry (with issue reference), evidence directory, and test-scope.md BEFORE implementing.
5. If trivial (typo/formatting): proceed without requirement but use conventional commit format.
6. Verify `develop` branch: `git branch --show-current` — never implement on `main`.

### For ALL Code Changes (including bug fixes)

Even if a change doesn't need a REQ entry:
1. **Review existing tests** that cover the changed code
2. **Update or add tests BEFORE committing**
3. **Run all gates locally** — do not push without verifying no regressions
4. If the change affects financial calculations, user-facing data, or access control — it needs a REQ entry regardless of size

**What needs a REQ entry:** New features → always. Bug fixes affecting financial data, user-facing behaviour, access control → always. Internal logic bug fixes → only if MEDIUM/HIGH risk. Typos, formatting, dependency bumps → never.

### Creating GitHub Issues

When creating an issue via `gh issue create`, ALWAYS append this to the body:
```
## SDLC Checklist
- [ ] Requirement: RTM entry created (or confirmed trivial)
- [ ] Planning: test-scope.md and test-plan.md created (or confirmed trivial)
- [ ] Tests: existing tests reviewed, tests updated/added
- [ ] Gates: all pass locally (tsc, semgrep, audit, playwright)
- [ ] Evidence: compiled and uploaded (if tracked requirement)
```

### Requirement Planning (do this BEFORE coding)

**Read `SDLC/1-plan-requirement.md` for full details.** Summary:

1. Confirm GitHub Issue `#NNN` exists (create if needed via `gh issue create`).
2. Get next REQ ID: `grep -oP 'REQ-\d+' compliance/RTM.md | sort -t- -k2 -n | tail -1`
3. Classify risk (use issue labels as input): LOW (internal, no auth) / MEDIUM (PII, user-facing, APIs) / HIGH (security, payments, RBAC). AI involvement raises risk by one level.
4. Add to `compliance/RTM.md` Part B: `| REQ-XXX | #NNN | [RISK] | compliance/evidence/REQ-XXX/ | DRAFT | -- | -- |`
5. **MEDIUM/HIGH risk:** Create `compliance/evidence/REQ-XXX/implementation-plan.md` — document approach, files, architecture decisions. **WAIT CHECKPOINT:** Present the plan to the developer. Do NOT proceed until approved.
6. Create `compliance/evidence/REQ-XXX/test-scope.md` with acceptance criteria (derived from the implementation plan for MEDIUM/HIGH).
7. **WAIT CHECKPOINT:** Present the test scope to the developer. Do NOT proceed until confirmed.
8. Create `compliance/evidence/REQ-XXX/test-plan.md` — map acceptance criteria to specific tests, list tests to add/update/remove. Distinguish unit tests (TDD, before implementation) from E2E tests (after implementation).
9. **WAIT CHECKPOINT:** Present the test plan to the developer. Do NOT proceed until confirmed.
10. Create `compliance/evidence/REQ-XXX/ai-use-note.md` if AI is involved.
11. Commit plan: `compliance: [REQ-XXX] define requirement, test scope, and test plan`

### During Implementation

**Read `SDLC/2-implement-and-test.md` for full details.** Summary:

- **Before coding:** Verify ALL exist: `ls compliance/evidence/REQ-XXX/test-scope.md` AND `ls compliance/evidence/REQ-XXX/test-plan.md`. If either is missing, STOP and run planning workflow first. For MEDIUM/HIGH also verify `implementation-plan.md` exists.
- **Phase 1 — Unit tests (TDD):** Write unit tests before implementation. Tests should initially fail. **CHECKPOINT:** Unit test coverage matches test plan.
- **Phase 2 — Implementation:** Write the code. Unit tests should now pass. **CHECKPOINT:** All unit tests green.
- **Phase 3 — E2E tests:** Write E2E tests against the working implementation. **CHECKPOINT:** All E2E tests green.
- **Phase 4 — All gates:** Run full gate suite (TypeScript, SAST, dep audit, all tests, build). **CHECKPOINT:** All gates green, push to develop.
- Every commit: conventional format with `Ref: REQ-XXX` and `Co-Authored-By` for AI.
- Add `@requirement REQ-XXX` JSDoc headers to modified files.
- Log AI prompts in `compliance/evidence/REQ-XXX/ai-prompts.md` for MEDIUM/HIGH risk.

### Before Pushing

Run ALL gates — every one must pass:
```bash
npx tsc --noEmit                    # 0 errors
semgrep scan --config auto src/     # 0 high/critical
npm audit --audit-level=high        # 0 vulnerabilities
npx playwright test                 # all pass
```

**Verify test plan tests are written:** For tracked requirements, check that every test file referenced in `compliance/evidence/REQ-XXX/test-plan.md` exists and passes. If `test-plan.md` lists tests that haven't been written yet, **STOP** — write and run the tests before pushing.

### After Pushing: WAIT — Confirm CI Green

```bash
gh run list --branch develop --limit 1
```

Do NOT proceed to evidence compilation or PR creation until CI is green. If CI fails, fix locally and re-push.

### Evidence Storage Rule

**Markdown stays in git. Binary/JSON evidence goes to DevAudit portal.**

Upload to DevAudit (NEVER commit to git):
- E2E results (JSON), screenshots (PNG/JPG), SAST results (JSON), dependency audit (JSON), unit test output (TXT), test reports (HTML)

```bash
./scripts/upload-evidence.sh [PROJECT_SLUG] REQ-XXX [type] [file]
```

Keep in git (small markdown, needs PR review):
- `compliance/RTM.md`, `test-scope.md`, `security-summary.md`, `ai-use-note.md`, `ai-prompts.md`, release tickets

### After Implementation

**Read `SDLC/3-compile-evidence.md` for full details, including release ticket template.** Summary:

1. Confirm CI is green before compiling evidence: `gh run list --branch develop --limit 1`
2. Generate `compliance/evidence/REQ-XXX/test-execution-summary.md` — gate results, test changes, coverage against test plan, links to evidence in DevAudit
3. Upload binary/JSON evidence to DevAudit portal
4. Create `compliance/evidence/REQ-XXX/security-summary.md` (in git)
5. Update RTM status to `TESTED - PENDING SIGN-OFF`
6. Create `compliance/pending-releases/RELEASE-TICKET-REQ-XXX.md` (use template from workflow file). If the change requires post-deploy actions (data migrations, backfill scripts), document them in the release ticket's Post-Deploy Actions section with exact commands
7. Commit compliance markdown locally (do NOT push yet — batch with UAT results):
```bash
git add compliance/RTM.md compliance/pending-releases/RELEASE-TICKET-REQ-XXX.md \
  compliance/evidence/REQ-XXX/test-scope.md \
  compliance/evidence/REQ-XXX/test-plan.md \
  compliance/evidence/REQ-XXX/test-execution-summary.md \
  compliance/evidence/REQ-XXX/security-summary.md \
  compliance/evidence/REQ-XXX/ai-use-note.md
git commit -m "compliance: [REQ-XXX] evidence compiled - awaiting review"
```
8. **WAIT CHECKPOINT:** Confirm CI + UAT deployment complete before UAT verification. Do NOT test against a stale deployment.
9. **Verify on UAT** (if configured) — health check, smoke test, feature verification. Record in `security-summary.md`. Commit locally. Do NOT create a PR until UAT is green.
10. **Push all compliance commits** in a single push: `git push origin develop`
11. **Verify release in DevAudit** — CI auto-creates releases and links evidence. Check that a release exists with the current version (date-based: `v{YYYY}.{MM}.{DD}` or `v{YYYY}.{MM}.{DD}.{N}` for multiple releases on the same day) and evidence is linked.

### Pre-Flight Checklist (Before Creating PR)

**Do NOT create the PR until ready to merge.** Every push to `develop` while a PR is open triggers duplicate CI runs. The PR is the merge request, not the development workspace.

Before creating a PR, verify ALL of the following:
- [ ] All development and iteration is complete
- [ ] CI green on develop (not stale): `gh run list --branch develop --limit 1`
- [ ] Working tree clean: `git status`
- [ ] UAT verification passed (if configured)
- [ ] DevAudit UAT approval granted
- [ ] For tracked requirements: test-scope.md complete, implementation-plan.md exists (MEDIUM/HIGH), RTM is `TESTED - PENDING SIGN-OFF`, release ticket created, evidence uploaded

If any item fails, resolve it before proceeding. Read `SDLC/4-submit-for-review.md` for full PR creation steps.

### Status Reporting (MANDATORY before handing off)

Before describing a PR as "awaiting review", "waiting on reviewers", "ready to merge", "Stage 4/5 requires human action", or any other happy-path language, you MUST:

1. Run `gh pr checks <PR>` and capture the full output, and `gh pr view <PR> --json mergeable,mergeStateStatus` for GitHub's own mergeability signal.
2. If ANY required check is `fail` or `pending`, do NOT use happy-path language. Instead report:
   - Each failing check by name, with its error (from `gh run view <RUN> --log-failed` if needed)
   - Each pending check by name
   - The concrete fix you are about to apply, or a specific question for the developer
3. If `mergeStateStatus` is anything other than `CLEAN` or `BLOCKED` (blocked only by required-reviewer approval), treat it as an open issue and investigate before claiming "ready".
4. If `gh` itself fails (auth, rate limit, network): report "status unknown — gh call failed", never assume green.
5. Only when every required check is `pass` AND the PR is mergeable may you say "awaiting review" or "awaiting approval".

**Why this rule exists:** A summary like "awaiting UAT + 2 reviewers" reads to the developer as "nothing to do but approve." If a required check is red, that summary is a lie by omission — the PR cannot merge regardless of what the reviewer does, and the reviewer wastes time (or worse, ships bad state) on the basis of that false signal.

This rule applies any time you summarise PR state in chat, not only at the final handoff.

### Review Policy (Risk-Tiered)

- **LOW risk:** CI provides independent verification. Self-merge is permitted after all CI checks pass.
- **MEDIUM/HIGH risk:** A second human reviewer MUST approve before merge. Self-merge is NOT permitted.

### Rules (NEVER break these)

- NEVER code without a GitHub Issue and requirement entry for tracked changes
- NEVER push without all four gates passing
- NEVER self-merge a MEDIUM or HIGH risk PR — a second human reviewer MUST approve
- NEVER use `--no-verify` to skip hooks
- NEVER commit secrets (.env, credentials, API keys)
- NEVER commit binary/JSON evidence to git — upload to DevAudit instead
- NEVER create a PR to main without UAT verification passing first (if UAT configured)
- NEVER push directly to main — always develop → PR → main
- NEVER skip Co-Authored-By when AI generates code
- NEVER proceed past a WAIT CHECKPOINT without developer confirmation
- NEVER describe a PR as "awaiting review" or "ready to merge" without first running `gh pr checks <PR>` and confirming every required check is `pass`
- ALWAYS commit compliance markdown to git (RTM, test-scope, implementation-plan, security-summary, release tickets)
- ALWAYS use merge commits (not squash) for develop → main