@metasession.co/devaudit-cli 0.1.1 → 0.1.2

package/sdlc/files/_common/implementing-an-sdlc-issue.md

@@ -0,0 +1,413 @@
+# Implementing a GitHub issue under the Metasession SDLC
+
+End-to-end walkthrough for taking a GitHub issue from triage to merged-and-deployed under the Metasession SDLC. Audience: this project's developers and AI coding agents.
+
+> This document is **synced into your repo from DevAudit-Installer** via `devaudit update`. Do not edit this file in place — your edits will be overwritten on the next sync. To propose a change, open a Task issue against [`metasession-dev/DevAudit-Installer`](https://github.com/metasession-dev/DevAudit-Installer) referencing `sdlc/files/_common/implementing-an-sdlc-issue.md`.
+>
+> For the broader DevAudit positioning (three-pillar story, standards coverage, the portal itself), see the [DevAudit portal repo's documentation](https://github.com/metasession-dev/devaudit).
+
+## What you need before you start
+
+| Prerequisite                                                                                    | How to check                                       |
+| ----------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| The project is SDLC-onboarded (has `sdlc-config.json`, `compliance/`, the synced AI rule files) | `devaudit status .` from the project root          |
+| The `devaudit` CLI is installed                                                                 | `devaudit --version` should print `0.1.1` or later |
+| You're authenticated against the portal                                                         | `devaudit auth status`                             |
+| Your `gh` CLI is authenticated against the project's GitHub repo                                | `gh auth status`                                   |
+| Your local checkout is on `develop` (or branched from it) and up-to-date                        | `git status`                                       |
+
+If `devaudit status` reports gaps, see [`DevAudit-Installer/docs/onboarding.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/docs/onboarding.md) to re-sync the framework, then come back here.
+
+## The five stages, at a glance
+
+| Stage                  | Doc (canonical)                                                                                                                                      | What you produce                                                                    |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| 1 — Plan requirement   | [`sdlc/_common/1-plan-requirement.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/sdlc/files/_common/1-plan-requirement.md)     | `compliance/plans/REQ-XXX/implementation-plan.md` + RTM entry + risk classification |
+| 2 — Implement and test | [`sdlc/_common/2-implement-and-test.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/sdlc/files/_common/2-implement-and-test.md) | Code + tests + all gates green locally                                              |
+| 3 — Compile evidence   | [`sdlc/_common/3-compile-evidence.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/sdlc/files/_common/3-compile-evidence.md)     | Evidence uploaded to the portal under REQ-XXX                                       |
+| 4 — Submit for review  | [`sdlc/_common/4-submit-for-review.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/sdlc/files/_common/4-submit-for-review.md)   | PR open against `main` with the gates green and UAT approval requested              |
+| 5 — Deploy to main     | [`sdlc/_common/5-deploy-main.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/sdlc/files/_common/5-deploy-main.md)               | Merge → production deploy → smoke evidence captured → release marked Released       |
+
+The stage-doc files are synced into every consumer project's repo by `devaudit update`; the canonical copies live in DevAudit-Installer (links above).
+
+## Trivial-change escape hatch
+
+For typo fixes, formatting changes, dependency bumps, and other zero-risk chores, **skip stages 1 and 3** and go straight to stage 2 (and a `chore:` PR). The risk threshold for the full ceremony is in [`Test_Policy.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/sdlc/files/_common/Test_Policy.md) §Risk-Based Testing. Even trivial changes must run **all gates locally before pushing** — that's not optional.
+
+If you're not sure whether your change is trivial, treat it as non-trivial (cheaper than discovering mid-PR that an auditor needs evidence).
+
+## Automated mode (`sdlc-implementer` — pending Phase C smoke)
+
+The [`sdlc-implementer`](#skills-inventory) skill has been authored (SKILL.md + 3 references on `main`, validator-clean) but hasn't yet been smoke-tested against `wawagardenbar-app`. Once Phase C completes, this entire walkthrough collapses to:
+
+```text
+> Implement issue #N under the SDLC.
+```
+
+The skill runs phases 1–4 unattended (with a plan-approval pause for HIGH/CRITICAL risk) and surfaces a UAT review waiting for you on the portal. Approve it on the portal, then:
+
+```text
+> Resume REQ-XXX.
+```
+
+The skill completes phase 5: merge, monitor post-deploy, capture production smoke evidence, mark the release Released. If changes are requested at UAT instead of approval, the skill addresses them and re-submits for UAT re-review.
+
+The manual walkthrough below remains the source of truth for what the skill is doing (and the fallback for cases where the skill can't be used). Until the skill ships, follow the walkthrough manually — the sample prompts at the end of this doc are the per-stage stopgap.
+
+---
+
+## End-to-end walkthrough
+
+### 1. Pick up the issue
+
+Either pick an existing issue or open one. Opening one — use the **Requirement** template (see [Issue templates](#issue-templates) below); it forces the SDLC-mandatory fields up front. Existing issues without those fields need the missing fields added as a comment before stage 1.
+
+Skim the issue for:
+
+- **Risk class signals** — does it touch auth, payments, RBAC, evidence storage, audit log, or anything an auditor would ask about? → HIGH/CRITICAL likely.
+- **Acceptance criteria** — does the issue spell them out? If not, you'll derive them in stage 1.
+- **Dependencies** — does it depend on another in-flight issue or a portal API change? Flag in stage 1.
+
+Assign yourself, move the issue to **In Progress** in the project board.
+
+### 2. Stage 1 — Plan the requirement
+
+Goal: a written, reviewable plan before any code lands.
+
+Steps (manual; the [`sdlc-implementer`](#skills-inventory) orchestration skill will run this phase automatically once Phase C smoke completes):
+
+1. **Classify risk** per [`Test_Policy.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/sdlc/files/_common/Test_Policy.md) — LOW, MEDIUM, HIGH, or CRITICAL.
+2. **Pick or assign a REQ-XXX ID.** Inspect `compliance/RTM.md` for existing entries; if this is genuinely new, take the next available number.
+3. **Write `compliance/plans/REQ-XXX/implementation-plan.md`** per the stage-1 template. Sections: context, acceptance criteria, technical approach, security considerations, dependencies, test scope.
+4. **Update `compliance/RTM.md`** with the new entry: REQ-XXX, title, risk class, linked issue, linked test cases (placeholder).
+5. **Post the plan summary** as a comment on the GitHub issue. Stop here. Wait for review before implementing.
+
+For HIGH/CRITICAL risk, the plan must explicitly include:
+
+- **Threat model** — what attackers/abusers could do; what's mitigated; what's accepted
+- **Four-eyes attestation slot** — names the second reviewer who'll sign off pre-merge
+- **Rollback plan** — what reverts the change if production smoke fails
+
+Sample prompt for an AI agent kicking off stage 1: see [`Sample prompts → Stage 1`](#sample-prompts).
+
+### 3. Stage 2 — Implement and test
+
+Goal: code, tests, all gates green locally before pushing.
+
+1. **Branch from `develop`**: `git checkout -b feat/REQ-XXX-short-description`.
+2. **Write failing tests first** per `sdlc/Test_Architecture.md`. The risk class dictates depth:
+   - LOW: unit tests on the changed function(s); no e2e required unless the change touches a user-facing flow.
+   - MEDIUM: unit + integration; e2e for any UI-facing change.
+   - HIGH: unit + integration + e2e for every user-visible path + at least one negative/abuse test.
+   - CRITICAL: HIGH plus targeted security tests (authz bypass attempts, input fuzzing where applicable).
+   - **For any e2e or visual-regression work in this step, invoke the `e2e-test-engineer` skill** — it derives scenarios from the acceptance criteria + diff, reconciles with the existing pack, retires obsolete tests, runs the suite, and files defects for failures. Don't author e2e tests by hand when the skill is shipped. (Once `sdlc-implementer` Phase C smoke completes, it enforces this delegation automatically.)
+3. **Implement the change.** Reference the implementation plan; deviations from the plan must be noted in the plan itself (it's the source of truth, not a one-shot artefact).
+4. **Run all gates locally** before pushing:
+   ```bash
+   npm run lint                    # 0 errors, 0 warnings on changed files
+   npx tsc --noEmit                # 0 errors
+   npx vitest run                  # all pass
+   npx playwright test             # all pass on changed routes
+   semgrep scan --config auto      # 0 high/critical
+   npm audit --audit-level=high    # 0 high/critical
+   ```
+   _(commands shown for Node; Python consumers run `ruff check`, `mypy src/`, `pytest`, etc. — see the consumer's `sdlc-config.json` and stack adapter)_
+5. **Commit with Conventional Commits** + a `Ref: REQ-XXX` trailer + `Co-Authored-By:` if AI-assisted.
+6. **Push to your branch.** This triggers the consumer's CI on `develop` push (if the branch IS develop) or stays branch-local until you open the PR. Most projects use a feature-branch flow — push to feature branch, PR to develop.
+
+If any gate fails: fix the underlying issue. Do **not** use `--no-verify`, `// eslint-disable`, `// @ts-expect-error`, `xfail`, or any other bypass. If a gate is structurally wrong for this change, surface that as a blocker in the issue, don't silently work around it.
+
+### 4. Stage 3 — Compile evidence
+
+Goal: every test result + report + screenshot lands on the portal under REQ-XXX so auditors can verify the change was tested.
+
+1. **Run the full test suite one more time**, this time capturing artefacts:
+   ```bash
+   npm run test:e2e -- --reporter=html        # produces playwright-report/
+   npx vitest run --coverage                  # produces coverage/
+   ```
+2. **Organise artefacts** under `compliance/evidence/REQ-XXX/`. Convention:
+   ```
+   compliance/evidence/REQ-XXX/
+   ├── 2026-MM-DD_e2e-results.json
+   ├── 2026-MM-DD_playwright-report/         # full HTML report
+   ├── 2026-MM-DD_unit-coverage/             # vitest coverage HTML
+   └── 2026-MM-DD_screenshots/*.png          # failing/edge-case shots if applicable
+   ```
+3. **Upload to the portal** via the CLI:
+   ```bash
+   devaudit push <project-slug> REQ-XXX e2e_result compliance/evidence/REQ-XXX/2026-MM-DD_e2e-results.json \
+     --release "v$(date +%Y.%m.%d)" --create-release-if-missing \
+     --environment uat --category testing \
+     --git-sha "$(git rev-parse HEAD)" --branch "$(git rev-parse --abbrev-ref HEAD)"
+   ```
+   Repeat per evidence type (`screenshot`, `test_report`, `audit_log`, `compliance_document`, `manual_upload`).
+4. **Verify uploads** at `https://devaudit.metasession.co/projects/<slug>/requirements/REQ-XXX`. Every entry should render.
+5. **Update `compliance/RTM.md`** with the portal links for each evidence row.
+
+CI also uploads evidence automatically on `develop` push (via the `ci.yml.template` workflow synced from DevAudit-Installer). Manual stage 3 uploads from your laptop are a belt-and-braces complement, mostly useful when you want to attach evidence the automated workflow doesn't produce (manual sign-off PDFs, threat models, etc.).
+
+### 5. Stage 4 — Submit for review
+
+Goal: PR open against `main` with all gates green and the UAT approval requested.
+
+1. **Verify gates one more time** — `gh pr checks` once the PR is open. Required status checks (per branch protection): `Quality Gates`, `Compliance Validation`, `DevAudit Release Approval`. The release-approval check will be **pending** until UAT signs off on the portal; that's expected.
+2. **Open the PR** with `gh pr create --base main --head develop` (or feature → develop → main per the project's branching flow). PR body **must** include the SDLC-mandated fields — see [`pull_request_template.md`](../.github/pull_request_template.md) — pre-filled by GitHub when you open the PR via the UI:
+   - Linked issue (`Closes #N`)
+   - REQ-XXX
+   - Risk class
+   - Evidence portal link
+   - Four-eyes attestation (HIGH/CRITICAL only)
+   - Rollback plan (HIGH/CRITICAL only)
+3. **Add labels** — `awaiting-uat-review` is the canonical "ready for human review" signal. Add `risk:HIGH` or `risk:CRITICAL` where applicable so reviewers can prioritise.
+4. **Wait for UAT approval on the portal.** Reviewer opens `https://devaudit.metasession.co/projects/<slug>/releases/<version>` and clicks Approve (or Request Changes). The `DevAudit Release Approval` check unblocks once approval is granted.
+
+If a reviewer asks for changes:
+
+- Update the implementation plan with the deviation
+- Repeat stages 2 and 3 for the changes
+- Re-request review
+
+### 6. Stage 5 — Merge and deploy
+
+Goal: PR merged → production deploys → smoke evidence captured → release marked Released.
+
+1. **Merge** the PR via `gh pr merge --merge` (preserves audit trail per the SDLC merge-commit convention). Branch protection blocks `--squash` and `--rebase` on SDLC repos.
+2. **Watch the deploy** — `gh run watch` against the `post-deploy-prod.yml` workflow. ~3–5 minutes typically.
+3. **Verify production smoke evidence uploaded.** The post-deploy workflow runs production smoke tests and pushes evidence with `--environment production`. Confirm at `https://devaudit.metasession.co/projects/<slug>/releases/<version>`.
+4. **Mark the release as Released** on the portal once production smoke is green.
+
+If production smoke fails:
+
+- **Do not** mark the release as Released. File a defect issue immediately.
+- Follow the project's incident playbook (rollback or roll-forward per the original plan's rollback section).
+
+---
+
+## Sample prompts
+
+Copy-paste these into Claude Code, Cursor, or any agent with shell access to kick off each stage. The agent should already have `AGENT.md` (portal) or the consumer's `INSTRUCTIONS.md` loaded as the canonical rules file.
+
+> **Replace placeholders.** `{ISSUE_NUMBER}`, `{REQ_ID}`, `{PROJECT_SLUG}`, `{VERSION}` etc. are placeholders — substitute the real values before invoking.
+
+### Stage 1 — Plan the requirement
+
+```text
+I'm picking up GitHub issue #{ISSUE_NUMBER} in this repo. Follow the Metasession SDLC
+stage 1 (plan-requirement) for it:
+
+1. Run `gh issue view {ISSUE_NUMBER}` and read the issue fully, including comments.
+2. Classify the risk per sdlc/Test_Policy.md (LOW / MEDIUM / HIGH / CRITICAL).
+3. Assign a REQ-XXX ID if not already present in compliance/RTM.md (use the next free number).
+4. Create compliance/plans/REQ-XXX/implementation-plan.md per the stage-1 template
+   (context / acceptance criteria / technical approach / security considerations /
+   dependencies / test scope). For HIGH/CRITICAL also include threat model,
+   four-eyes attestation slot, and rollback plan.
+5. Update compliance/RTM.md with the new entry.
+6. Post a plan summary as a comment on issue #{ISSUE_NUMBER}.
+
+STOP after the plan is posted. Do NOT begin implementation.
+
+Reference: AGENT.md (or INSTRUCTIONS.md for consumer repos), and the canonical
+sdlc/_common/1-plan-requirement.md from DevAudit-Installer.
+```
+
+### Stage 2 — Implement and test
+
+```text
+Implement REQ-{REQ_ID} per compliance/plans/REQ-{REQ_ID}/implementation-plan.md.
+Follow SDLC stage 2 (implement-and-test):
+
+1. Branch: `feat/REQ-{REQ_ID}-short-description` off develop.
+2. Write failing tests first per Test_Architecture.md. Risk class is {RISK_CLASS};
+   match the test depth from §Test depth by risk class in the plan.
+3. Implement the change. Any deviation from the plan: note it IN the plan, don't
+   silently diverge.
+4. Run ALL gates locally before pushing. Must all pass:
+   - npm run lint
+   - npx tsc --noEmit
+   - npx vitest run
+   - npx playwright test
+   - semgrep scan --config auto
+   - npm audit --audit-level=high
+5. Conventional commit with `Ref: REQ-{REQ_ID}` trailer and `Co-Authored-By:`
+   line if AI-assisted.
+
+Do NOT use --no-verify, eslint-disable, @ts-expect-error, xfail, or any bypass.
+If a gate is structurally wrong for this change, stop and surface it as a blocker.
+```
+
+### Stage 3 — Compile evidence
+
+```text
+Compile evidence for REQ-{REQ_ID} per SDLC stage 3 (compile-evidence):
+
+1. Run the full test suite capturing artefacts:
+   - npm run test:e2e -- --reporter=html
+   - npx vitest run --coverage
+2. Organise artefacts under compliance/evidence/REQ-{REQ_ID}/ with the date-prefixed
+   naming convention (YYYY-MM-DD_<artefact>).
+3. Upload each artefact to the portal via:
+
+   devaudit push {PROJECT_SLUG} REQ-{REQ_ID} <evidence-type> <file> \
+     --release "v$(date +%Y.%m.%d)" --create-release-if-missing \
+     --environment uat --category testing \
+     --git-sha "$(git rev-parse HEAD)" \
+     --branch "$(git rev-parse --abbrev-ref HEAD)"
+
+   evidence-type is one of: screenshot, e2e_result, test_report, audit_log,
+   compliance_document, manual_upload.
+4. Verify uploads landed at
+   https://devaudit.metasession.co/projects/{PROJECT_SLUG}/requirements/REQ-{REQ_ID}
+5. Update compliance/RTM.md with portal links per evidence row.
+```
+
+### Stage 4 — Submit for review
+
+```text
+Open the PR for REQ-{REQ_ID} per SDLC stage 4 (submit-for-review):
+
+1. Verify the branch is up-to-date with develop and all gates pass locally.
+2. Open the PR with `gh pr create --base main` (or --base develop per project flow).
+   Use the SDLC PR template — body must include:
+     - "Closes #{ISSUE_NUMBER}"
+     - "REQ: REQ-{REQ_ID}"
+     - "Risk: {RISK_CLASS}"
+     - "Evidence: https://devaudit.metasession.co/projects/{PROJECT_SLUG}/requirements/REQ-{REQ_ID}"
+     - For HIGH/CRITICAL: "Four-eyes attestation: <reviewer-username>" and
+       "Rollback plan: <ref to plan §rollback>"
+3. Add labels: `awaiting-uat-review`, `risk:{RISK_CLASS}`.
+4. Confirm `gh pr checks <pr-number>` shows all required statuses passing or
+   pending-on-UAT-approval. STOP and report; do not merge.
+5. Notify the assigned reviewer.
+
+If `gh pr checks` shows ANY required check failing, STOP and surface the failure;
+do not announce the PR as ready.
+```
+
+### Stage 5 — Merge + deploy
+
+```text
+Merge REQ-{REQ_ID} per SDLC stage 5 (deploy-main), then track to production:
+
+1. Confirm `gh pr view <pr-number>` shows UAT-approved status from the portal.
+2. Merge with `gh pr merge <pr-number> --merge` (audit trail; never --squash,
+   never --rebase).
+3. Watch `gh run watch` against the post-deploy-prod.yml workflow.
+4. Verify production smoke evidence uploaded (environment=production) at
+   https://devaudit.metasession.co/projects/{PROJECT_SLUG}/releases/{VERSION}
+5. Mark the release as `Released` on the portal.
+
+If production smoke FAILS:
+- Do NOT mark the release as Released.
+- File a defect issue with title "[INCIDENT] REQ-{REQ_ID} production smoke failed".
+- Page the on-call per the project's incident playbook.
+- Roll back per the implementation plan's rollback section.
+```
+
+---
+
+## Issue templates
+
+The portal repo ships three GitHub issue templates under `.github/ISSUE_TEMPLATE/`. Consuming projects should adopt the same shape — the templates are reproduced in `sdlc/files/_common/github/` in DevAudit-Installer and synced to consumers on `devaudit update`.
+
+| Template                                                 | When to use                                                                                  | Mandatory fields                                                                               |
+| -------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| [Requirement](../.github/ISSUE_TEMPLATE/requirement.yml) | New feature, enhancement, or significant change. Full SDLC stages 1–5.                       | Title (one-line summary), context/why, acceptance criteria, suspected risk class, dependencies |
+| [Bug](../.github/ISSUE_TEMPLATE/bug.yml)                 | Defect in shipped behaviour. Full SDLC if it touches a high-risk surface; otherwise lighter. | Reproduction, expected vs actual, environment, risk class                                      |
+| [Task](../.github/ISSUE_TEMPLATE/task.yml)               | Chores, refactors, docs, dependency bumps. Trivial-change escape hatch — skip stages 1 + 3.  | Title, what + why, definition of done                                                          |
+
+`.github/ISSUE_TEMPLATE/config.yml` disables blank issues; choosing one of the three templates is mandatory.
+
+### How to create an issue from a template
+
+GitHub UI: **New issue** → pick a template. The template's mandatory fields are rendered as form inputs; you cannot submit until they're filled in.
+
+Or via CLI:
+
+```sh
+gh issue create --template requirement.yml --title "Add SAML SSO" \
+  --body "$(cat <<'EOF'
+### Why
+Customers in regulated industries need SAML-based auth.
+
+### Acceptance criteria
+- [ ] SAML 2.0 metadata exchange flow works for Azure AD
+- [ ] User attributes mapped to UserProfile
+- [ ] Failed-auth audit events logged
+
+### Suspected risk class
+HIGH (authentication surface, regulated-industry signal)
+
+### Dependencies
+None
+EOF
+)"
+```
+
+Once the issue exists, you can proceed to stage 1 with one of the [sample prompts](#sample-prompts).
+
+---
+
+## Skills inventory
+
+The Metasession SDLC framework includes a set of [Claude Code Skills](https://github.com/metasession-dev/DevAudit-Installer/blob/main/sdlc/SKILLS.md) — discrete, discoverable agent capabilities each scoped to one slice of the lifecycle. Skills live in `sdlc/files/_common/skills/<name>/` in DevAudit-Installer and are synced to consumers on `devaudit update`.
+
+### Integrated today
+
+| Skill                                                                                                                                       | Stage | Scope                                                                                                                                                                                                                                                                            |
+| ------------------------------------------------------------------------------------------------------------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`e2e-test-engineer`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/sdlc/files/_common/skills/e2e-test-engineer/SKILL.md) | 2     | Bootstrap or maintain e2e + visual regression suites. Derives scenarios from issue/PR diff, reconciles with existing pack, retires obsolete tests (after confirmation), runs the suite, files defects for failures. Framework-agnostic (Playwright, Cypress, WDIO, Selenium, …). |
+
+### Planned
+
+One orchestration skill replaces an earlier roadmap of five atomic skills. The atomic ones (`risk-classifier`, `commit-message-author`, `compliance-evidence-author`, `sast-triager`, `release-ticket-author`) were deprioritised: Claude Code's innate capabilities already cover what each wrapped; the actual value-add is end-to-end orchestration with framework-compliant pauses, not five discoverable helpers a human still has to compose.
+
+| Skill (planned name) | Stage         | Scope it will cover                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| -------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sdlc-implementer`   | All 5 stages  | One-command orchestration: `"implement issue #N under the SDLC"` triggers Phase 1 (classify risk, write plan, update RTM) → Phase 2 (branch, tests, implement, gates) → Phase 3 (evidence capture + portal upload) → Phase 4 (PR open, request UAT review). Halts at Phase 4 with a UAT review waiting for the human on the portal. Resumed by `"resume REQ-XXX"`: if UAT approved → Phase 5 (merge, monitor post-deploy, capture prod smoke evidence, mark Released); if changes requested → re-runs Phase 2 + 3, re-submits for UAT re-review. **MUST invoke** [`e2e-test-engineer`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/sdlc/files/_common/skills/e2e-test-engineer/SKILL.md) for end-to-end and visual-regression test work in Phase 2 — the orchestrator never authors e2e tests directly. Unit-test work stays with the orchestrator until a counterpart unit-test skill ships. Enforces six architectural compliance constraints: never skip UAT gate, never act as UAT approver for HIGH/CRITICAL, plan checkpoint mandatory for HIGH/CRITICAL, change-request loop triggers UAT re-review, AI disclosure on every commit, all portal mutations through audit-logged APIs. Tracked at [`metasession-dev/DevAudit-Installer#29`](https://github.com/metasession-dev/DevAudit-Installer/issues/29). |
+
+After Phase C smoke completes against `wawagardenbar-app`, the skill will appear in every onboarded consumer's `~/.config/devaudit/skills/` on the next `devaudit update`, become discoverable to Claude Code by name (`Skill(name: "sdlc-implementer", …)`), and get a row moved from **Planned** to **Integrated today** above.
+
+### Why skills (vs. just prompts)
+
+Prompts are recipes — useful, but they don't ship. Skills are versioned, testable, discoverable artefacts that:
+
+- Show up in Claude Code's skill picker by trigger phrase (`"add e2e tests for this issue"`, `"classify risk for #123"`, …)
+- Carry their own references (sub-pages under `references/` for deep-dive content the SKILL.md links to rather than inlines)
+- Validate against `skill.schema.json` so the frontmatter is consistent across the catalogue
+- Update centrally — a SKILL.md change in DevAudit-Installer reaches every consumer on next `devaudit update`
+
+The sample prompts in this doc are a stopgap that lets us run the SDLC manually until each skill lands.
+
+---
+
+## Troubleshooting
+
+| Symptom                                              | Likely cause                                     | Fix                                                                                                                                                        |
+| ---------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `devaudit push` returns 401                          | Token expired or wrong account                   | `devaudit auth status` → `devaudit auth login` if needed                                                                                                   |
+| `devaudit push` returns 403                          | Project key missing or wrong                     | Verify `DEVAUDIT_API_KEY` is set; re-issue from the portal `/settings/api-keys` if rotated                                                                 |
+| `gh pr checks` shows `DevAudit Release Approval` red | UAT review not granted or release not registered | Visit `https://devaudit.metasession.co/projects/<slug>/releases/<version>` → request approval; if release missing, `ci.yml` registers it on `develop` push |
+| Production smoke flaky on the same test repeatedly   | Test flake, not a real defect                    | File the flake as a separate issue tagged `flaky-test`; do NOT mark the release failed                                                                     |
+| Forgot to add `Ref: REQ-XXX` to commits              | RTM traceability gap                             | Amend the commit (if local) or add a follow-up commit with the trailer; CI's compliance-validation workflow will flag it on PR                             |
+| Stage 1 plan deviates significantly mid-stage-2      | Implementation discovered a gap in the plan      | Update the plan IN PLACE; note the deviation in a new `## Plan deviation` section. The plan is the source of truth, not a one-shot artefact                |
+
+For anything not covered here, open a `task` issue tagged `sdlc-feedback` against this repo — the portal repo is the central reference and is where the SDLC docs evolve.
+
+---
+
+## See also
+
+- [`AGENT.md`](../AGENT.md) — canonical portal standards
+- [`docs/architecture.md`](./architecture.md) — portal architecture (post-v3)
+- [`docs/ci-integration.md`](./ci-integration.md) — how consumer CI uploads evidence to the portal
+- DevAudit-Installer canonical SDLC docs:
+  - [`sdlc/files/_common/1-plan-requirement.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/sdlc/files/_common/1-plan-requirement.md)
+  - [`sdlc/files/_common/2-implement-and-test.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/sdlc/files/_common/2-implement-and-test.md)
+  - [`sdlc/files/_common/3-compile-evidence.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/sdlc/files/_common/3-compile-evidence.md)
+  - [`sdlc/files/_common/4-submit-for-review.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/sdlc/files/_common/4-submit-for-review.md)
+  - [`sdlc/files/_common/5-deploy-main.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/sdlc/files/_common/5-deploy-main.md)
+  - [`sdlc/files/_common/Test_Policy.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/sdlc/files/_common/Test_Policy.md)
+  - [`sdlc/files/_common/Test_Architecture.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/sdlc/files/_common/Test_Architecture.md)
+  - [`sdlc/SKILLS.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/sdlc/SKILLS.md)

package/sdlc/files/_common/scripts/derive-release-version.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# derive-release-version.sh — Pick the release version for CI uploads from
+# the latest commit's REQ tag, falling back to a bare date.
+#
+# Usage:
+#   VERSION=$(./scripts/derive-release-version.sh)
+#
+# Priority:
+#   1. REQ tag in commit subject: "[REQ-037] feat(kitchen): ..." -> REQ-037
+#   2. Ref in commit body:        "Ref: REQ-037"                 -> REQ-037
+#   3. Fallback:                  bare date                      -> v2026.05.17
+#
+# Multi-REQ commits: first match wins; subject takes priority over body.
+# Output: single line on stdout. Exit 0 in all normal cases.
+#
+# This ties a release record (project_id, version) to the feature the
+# commits belong to, so all CI uploads for one REQ converge on one
+# release container — fixing the fragmentation described in DevAudit #310.
+#
+# Install: cp this file to your project's scripts/ directory && chmod +x scripts/derive-release-version.sh
+
+set -euo pipefail
+
+SUBJECT=$(git log -1 --format='%s' 2>/dev/null || echo '')
+BODY=$(git log -1 --format='%b' 2>/dev/null || echo '')
+
+# 1. Subject: [REQ-XXX]
+if echo "$SUBJECT" | grep -qE '\[REQ-[0-9]+\]'; then
+  echo "$SUBJECT" | grep -oE 'REQ-[0-9]+' | head -1
+  exit 0
+fi
+
+# 2. Body: Ref: REQ-XXX (case-insensitive on "Ref" and "REQ")
+if echo "$BODY" | grep -qiE 'Ref:[[:space:]]*REQ-[0-9]+'; then
+  echo "$BODY" | grep -ioE 'REQ-[0-9]+' | head -1 | tr '[:lower:]' '[:upper:]'
+  exit 0
+fi
+
+# 3. Fallback: bare date in UTC
+echo "v$(date -u +%Y.%m.%d)"

package/sdlc/files/_common/scripts/derive-release-version.test.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# derive-release-version.test.sh — Tests for derive-release-version.sh.
+#
+# Builds a throwaway git repo per case, makes one crafted commit, runs
+# the helper against it, asserts on the exact stdout. Hermetic: runs
+# inside mktemp'd directories that are torn down at the end.
+#
+# Usage:
+#   ./scripts/derive-release-version.test.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HELPER="$SCRIPT_DIR/derive-release-version.sh"
+[ -x "$HELPER" ] || chmod +x "$HELPER"
+
+PASS=0
+FAIL=0
+TODAY="v$(date -u +%Y.%m.%d)"
+
+# Build a fresh git fixture under $1, cd into it, then commit a file
+# with the message passed as $2 (multi-line OK via heredoc-style strings).
+make_fixture() {
+  local dir="$1" msg="$2"
+  rm -rf "$dir"
+  mkdir -p "$dir"
+  cd "$dir"
+  git init -q --initial-branch=main
+  git config user.email "test@example.com"
+  git config user.name "test"
+  echo "x" > f.txt
+  git add f.txt
+  git commit -q -m "$msg"
+}
+
+assert_eq() {
+  local desc="$1" want="$2" got="$3"
+  if [ "$got" = "$want" ]; then
+    echo "  PASS: $desc"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $desc"
+    echo "    want: $want"
+    echo "    got:  $got"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+run_helper() {
+  bash "$HELPER"
+}
+
+WORK=$(mktemp -d)
+trap 'rm -rf "$WORK"' EXIT
+
+echo "=== derive-release-version.sh tests ==="
+
+# Each case: build fixture in its own dir, cd in, run helper, assert.
+# No subshells around the assertion so the PASS/FAIL counters update.
+
+# Case 1: subject tag
+make_fixture "$WORK/c1" "[REQ-037] feat(kitchen): inventory CRUD"
+assert_eq "subject [REQ-037] -> REQ-037" "REQ-037" "$(run_helper)"
+
+# Case 2: body ref
+make_fixture "$WORK/c2" "feat(kitchen): inventory CRUD
+
+Some details.
+
+Ref: REQ-037"
+assert_eq "body Ref: REQ-037 -> REQ-037" "REQ-037" "$(run_helper)"
+
+# Case 3: body lowercase
+make_fixture "$WORK/c3" "chore: misc cleanup
+
+ref: req-037"
+assert_eq "body lowercase ref/req normalised -> REQ-037" "REQ-037" "$(run_helper)"
+
+# Case 4: multi-REQ subject — first wins
+make_fixture "$WORK/c4" "[REQ-037][REQ-038] feat: combined feature"
+assert_eq "subject [REQ-037][REQ-038] -> REQ-037 (first)" "REQ-037" "$(run_helper)"
+
+# Case 5: subject overrides body
+make_fixture "$WORK/c5" "[REQ-037] feat: subject wins
+
+Ref: REQ-099"
+assert_eq "subject overrides body conflict -> REQ-037" "REQ-037" "$(run_helper)"
+
+# Case 6: no tag — fallback to bare date
+make_fixture "$WORK/c6" "chore: bump deps"
+assert_eq "no tag -> bare date $TODAY" "$TODAY" "$(run_helper)"
+
+echo ""
+echo "=== Summary: $PASS pass / $FAIL fail ==="
+
+if [ "$FAIL" -gt 0 ]; then
+  exit 1
+fi