@metasession.co/devaudit-cli 0.1.0 → 0.1.2

package/sdlc/files/_common/skills/sdlc-implementer/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: sdlc-implementer
+description: Take a GitHub issue end-to-end through the Metasession SDLC. Use when the user wants to implement a single GitHub issue as a complete SDLC cycle — Phase 1 (classify risk, write implementation plan, update RTM) through Phase 4 (open PR, request UAT review on the portal), then halt; and Phase 5 (merge, post-deploy smoke evidence, mark Released, or change-request loop) on resume. Trigger phrases — "implement issue #N under the SDLC", "run the SDLC for issue #N", "automate REQ-XXX from issue to release", "do the SDLC stages for [issue]". Resume phrase — "resume REQ-XXX". MUST delegate end-to-end and visual-regression test work to the e2e-test-engineer skill in Phase 2; never authors e2e tests directly. Do NOT use for partial work — for stage-1 planning only, run the manual walkthrough; for test work alone, invoke e2e-test-engineer directly.
+tags: [sdlc, orchestration, compliance, automation]
+---
+
+# SDLC implementer
+
+Take a single GitHub issue end-to-end through the Metasession SDLC. One command runs Phase 1 through Phase 4 unattended (with a plan-approval pause for HIGH/CRITICAL risk); the human enters the loop at the UAT review gate on the portal. On resume, the skill runs Phase 5 — merge, post-deploy smoke evidence, mark the release Released, or address change-requests and re-submit for UAT re-review.
+
+This is an **orchestration skill**. It drives Claude Code's native tools (`gh`, shell, the `devaudit` CLI, the portal API) through the framework's existing stage docs, and it **MUST invoke the [`e2e-test-engineer`](../e2e-test-engineer/SKILL.md) skill** for any end-to-end or visual-regression test work in Phase 2. It does not author e2e tests directly.
+
+## Scope
+
+**In scope**
+
+- Taking one GitHub issue from triage to merged-and-deployed, under the project's existing SDLC framework.
+- Risk classification per [`Test_Policy.md`](../../Test_Policy.md) §Risk-Based Testing.
+- Authoring `compliance/plans/REQ-XXX/implementation-plan.md` per the stage-1 template.
+- Updating `compliance/RTM.md`.
+- Implementation, unit/integration tests, quality gates.
+- Evidence capture and upload to the portal via `devaudit push`.
+- PR opening, UAT review request, change-request loop, merge, post-deploy verification, release finalisation.
+
+**Out of scope**
+
+- Issues that decompose into multiple requirements — refuse at Phase 1 and ask the user to split.
+- Stage-1 planning in isolation — run the manual walkthrough instead.
+- E2E or visual-regression test work in isolation — invoke `e2e-test-engineer` directly.
+- Cross-issue refactors that touch multiple REQ-XXX scopes — these are out of the one-issue contract.
+- Onboarding a new consumer — that's `devaudit install`, a different command entirely.
+
+## Sub-skill invocation contract
+
+The orchestrator MUST invoke `e2e-test-engineer` for end-to-end and visual-regression test work in Phase 2. This is a hard contract:
+
+- Never author e2e tests directly.
+- Never transcribe `e2e-test-engineer`'s six-phase workflow into this skill's body.
+- Call via the standard Claude Code Skill mechanism (`Skill(name: "e2e-test-engineer", …)`).
+
+Unit-test and integration-test work stays with this skill until a counterpart unit-test skill ships. The full sub-skill call graph lives at [`references/call-graph.md`](./references/call-graph.md).
+
+## The workflow
+
+Five phases. Phases 1–4 run in one Claude Code session; Phase 5 is invoked separately by the user after UAT.
+
+### Phase 1 — Plan (SDLC stage 1)
+
+1. **Fetch the issue.** `gh issue view <N>` — read the title, body, and all comments.
+2. **Classify risk** per `Test_Policy.md` §Risk-Based Testing. Emit a one-paragraph rationale citing the signals you used (auth surface, financial calc, data egress, RBAC, AI decisioning, etc.).
+3. **Assign REQ-XXX.** Inspect `compliance/RTM.md` for existing entries; take the next free number. If the issue references an existing REQ, use that instead.
+4. **Detect over-scoping.** If the issue spans clearly distinct deliverables (e.g. "build SAML SSO + reorganise the admin dashboard + migrate from Postgres 14 to 16"), halt with a clear message asking the user to split the issue into separate ones. Do not proceed past Phase 1.
+5. **Write the implementation plan.** Create `compliance/plans/REQ-XXX/implementation-plan.md` per the stage-1 template (sections: context, acceptance criteria, technical approach, security considerations, dependencies, test scope). For HIGH/CRITICAL also include: threat model (against STRIDE categories applicable to the touched surfaces), four-eyes attestation slot, rollback plan.
+6. **Update `compliance/RTM.md`** with the new entry: REQ-XXX, title, risk class, linked issue, linked test cases (placeholder).
+7. **Post plan summary as an issue comment.** Format: TL;DR; Risk class + signals; Acceptance criteria; Technical approach (one paragraph); Dependencies; Test scope.
+8. **Checkpoint** — pause for human approval **iff** risk class is HIGH or CRITICAL. LOW and MEDIUM pass through to Phase 2 automatically. The checkpoint can be forced on for all classes via the `--require-plan-approval` flag (or `DEVAUDIT_REQUIRE_PLAN_APPROVAL=1` env var) for orgs that want it always-on.
+
+### Phase 2 — Implement and test (SDLC stage 2)
+
+1. **Branch off `develop`.** `git checkout -b feat/REQ-XXX-<slug>`. The slug is a kebab-case fragment of the issue title (max 6 words).
+2. **Write failing tests first** per [`Test_Architecture.md`](../../Test_Architecture.md). Depth scales with risk class:
+   - 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).
+3. **For any e2e or visual-regression test work in this step, invoke `e2e-test-engineer`** — do not author e2e tests directly. The orchestrator passes the implementation plan + the diff so far to the e2e-test-engineer skill, which derives scenarios, reconciles with the existing pack, and runs the suite.
+4. **Implement against the plan.** Reference `compliance/plans/REQ-XXX/implementation-plan.md` as you go. Any deviation from the plan must be noted in the plan itself under a `## Plan deviation` section — never silently diverge.
+5. **Run all gates locally** before pushing:
+   - `npm run lint` (or stack-adapter equivalent)
+   - `npx tsc --noEmit` (or stack-adapter equivalent)
+   - `npx vitest run` (unit/integration)
+   - `npx playwright test` (e2e — delegated to `e2e-test-engineer`)
+   - `semgrep scan --config auto`
+   - `npm audit --audit-level=high` (or stack-adapter equivalent)
+6. **On gate failure**, iterate up to N=3 attempts. Each iteration: read the failure output, propose a fix, apply, re-run. On exhausted attempts, halt with the full failure output and surface to the human — never use `--no-verify`, `eslint-disable`, `@ts-expect-error`, `xfail`, or any other bypass.
+7. **Commit** using Conventional Commits with `Ref: REQ-XXX` trailer and `Co-Authored-By: Claude` trailer. One commit per logical step; never amend a commit that's already been pushed.
+8. **Push** to the feature branch. No PR yet — that happens in Phase 4.
+
+### Phase 3 — Compile evidence (SDLC stage 3)
+
+1. **Re-run the full test pack** with artefact capture:
+   - `npm run test:e2e -- --reporter=html` (produces `playwright-report/`)
+   - `npx vitest run --coverage` (produces `coverage/`)
+2. **Organise artefacts** under `compliance/evidence/REQ-XXX/` with date-prefixed naming:
+   ```
+   compliance/evidence/REQ-XXX/
+   ├── YYYY-MM-DD_e2e-results.json
+   ├── YYYY-MM-DD_playwright-report/
+   ├── YYYY-MM-DD_unit-coverage/
+   └── YYYY-MM-DD_screenshots/*.png
+   ```
+3. **Upload each artefact to the portal**:
+   ```bash
+   devaudit push <project-slug> REQ-XXX <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 types: `screenshot`, `e2e_result`, `test_report`, `audit_log`, `compliance_document`, `manual_upload`.
+4. **Verify uploads landed.** `gh api` or `curl` against `https://devaudit.metasession.co/projects/<slug>/requirements/REQ-XXX/evidence` should show every artefact.
+5. **Update `compliance/RTM.md`** with portal links for each evidence row.
+
+### Phase 4 — Submit for UAT review (SDLC stage 4)
+
+1. **Open the PR.** `gh pr create --base main --head <branch>`. PR body per the SDLC PR template (see [`.github/pull_request_template.md`](../../../../../.github/pull_request_template.md)):
+   - Closes #N
+   - REQ-XXX
+   - Risk: <class>
+   - Evidence: `https://devaudit.metasession.co/projects/<slug>/requirements/REQ-XXX`
+   - For HIGH/CRITICAL: Four-eyes attestation: `@<reviewer-username>`
+   - For HIGH/CRITICAL: Rollback plan: reference to `compliance/plans/REQ-XXX/implementation-plan.md` §Rollback
+   - Test plan
+   - SDLC checklist
+2. **Verify the UAT reviewer ≠ skill-trigger user** for HIGH/CRITICAL. If they match, halt with a configuration error: "HIGH/CRITICAL risk requires an independent UAT reviewer; the configured reviewer matches the trigger user — fix the four-eyes attestation slot in the implementation plan and re-run."
+3. **Apply labels** — `awaiting-uat-review`, `risk:<class>`.
+4. **Comment on the issue**: "Implementation complete. PR #M opened. Evidence on portal: <link>. UAT review requested. Resume with `resume REQ-XXX` once UAT approval is granted on the portal."
+5. **Hard stop.** Phase 4 ends here. Do not proceed to merge; the human's next action is reviewing on the portal.
+
+### Phase 5 — Finalise or change-request loop (SDLC stage 5)
+
+Invoked separately by the user after UAT activity on the portal. Trigger: "resume REQ-XXX", "REQ-XXX UAT done", or just re-firing the skill on the same issue.
+
+1. **Read portal state.** `curl` `https://devaudit.metasession.co/api/projects/<slug>/releases/<version>` and inspect the approval status.
+
+2. **Branch on state:**
+
+   - **UAT approved** → run stage 5:
+     - `gh pr merge <M> --merge` (merge commit; `--squash` and `--rebase` are blocked by branch protection on SDLC repos and would break the audit trail).
+     - Watch `post-deploy-prod.yml` via `gh run watch` — block until the workflow reaches a terminal state.
+     - Verify production smoke evidence uploaded (`--environment production`) at `https://devaudit.metasession.co/projects/<slug>/releases/<version>`.
+     - Mark release as `Released` via portal API: `PATCH /releases/<version>` with `{"status": "released"}`.
+     - Comment on the issue: "Released. Production smoke evidence: <link>."
+     - Close the issue.
+     - If production smoke fails: do NOT mark as Released. File an `[INCIDENT]` defect issue, page the on-call per the project's incident playbook, follow the rollback plan from the implementation plan.
+
+   - **Changes requested** → run change-request loop:
+     - Fetch change-request comments from the PR (`gh pr view <M> --comments`) and from the portal release page.
+     - Add a new `## Change-request iteration N` section to `compliance/plans/REQ-XXX/implementation-plan.md` describing what changed and why.
+     - Re-run Phase 2 (implement + test) for the requested changes — same delegation to `e2e-test-engineer` for any e2e work.
+     - Re-run Phase 3 (evidence) for the new/changed artefacts only; existing evidence stays.
+     - Push to the same branch (no force-push). The PR auto-updates.
+     - Re-request UAT review on the portal: `POST /api/projects/<slug>/releases/<version>/approval-requests`.
+     - Comment on the issue: "Change requests addressed in commits <SHAs>. UAT re-review requested."
+     - Hard stop again. The portal's release-approval state has reset; UAT must explicitly re-approve.
+
+   - **Still pending UAT (no approval, no change-request)** → report "UAT review still pending on the portal at <link>" and stop. Do not act.
+
+## Compliance constraints
+
+Hard rules — the skill's SKILL.md fails review if any of these are violated. Audited against ISO 29119, ISO 27001, SOC 2, GDPR, and the EU AI Act; details in [`references/compliance-constraints.md`](./references/compliance-constraints.md).
+
+1. **Never skip the UAT review gate** for any risk class. The portal enforces this server-side via `check-release-approval.yml`; do not attempt to merge with that check still red.
+2. **For HIGH/CRITICAL, the skill MUST NOT act as the UAT approver.** Check at Phase 4 that the configured UAT reviewer differs from the skill-trigger user; halt with a configuration error otherwise. (SOC 2 CC8 — segregation of duties.)
+3. **Plan checkpoint mandatory for HIGH/CRITICAL.** LOW/MEDIUM pass through Phase 1 automatically; HIGH/CRITICAL pause for human plan approval before code is written.
+4. **Change-request loop triggers full UAT re-review.** The portal's release-approval state resets when new commits land on the PR — respect it. Surface a "UAT re-review needed" comment; never rely on prior approval covering subsequent changes.
+5. **AI involvement disclosed on every commit** via `Co-Authored-By: Claude`. (ISO 27001 disclosure norms + EU AI Act Art. 13 transparency.)
+6. **All portal mutations through audit-logged APIs.** Use `devaudit push` and the standard portal-API endpoints — never a private back-channel.
+
+Plus one process risk surfaced explicitly in the principles below (rubber-stamping at UAT). Not enforceable architecturally — the UAT reviewer is the load-bearing human.
+
+## Principles
+
+**The UAT reviewer is the load-bearing human.** This skill makes it easy to produce many releases per day. The control regime depends on the UAT reviewer actually reading what they're approving. If the human approves without reviewing, the controls are formally satisfied but substantively broken — auditors will notice. Where possible, the UAT reviewer should be a different human from the skill-trigger user (mandatory for HIGH/CRITICAL).
+
+**Never bypass a gate to ship faster.** No `--no-verify`. No `eslint-disable`. No `@ts-expect-error`. No `xfail`. No "we'll fix it in the next PR." If a gate is structurally wrong for this change, halt and surface the blocker — fix the gate, not the bypass.
+
+**The implementation plan is the source of truth, not a one-shot artefact.** When implementation deviates from the plan (and it will), update the plan in place under a `## Plan deviation` section. The plan documents intent + reality; the RTM, the evidence, and the PR all reference it.
+
+**Never close the issue until Phase 5 completes.** An issue closed at Phase 4 (PR opened) loses its tie to the release outcome. Closure is the signal that the change is Released; don't generate that signal prematurely.
+
+**Never mark a release as Released without verifying production smoke evidence on the portal.** "The post-deploy workflow ran" is not the same as "production smoke evidence is on the portal." Verify the artefact landed before flipping the status.
+
+**Confirm before destructive operations.** Force-pushing, branch deletion, tag deletion, `git reset --hard`, modifying CI/CD pipelines — all need explicit user sign-off when they arise mid-skill. The cost of confirming is a sentence; the cost of getting it wrong is real.
+
+**Issue too big? Refuse at Phase 1.** If the issue spans multiple distinct deliverables, the right answer is "split this issue" — not "sub-divide into multiple REQs silently". Halt at Phase 1 with the proposed split for the user to confirm.
+
+**Ambiguity is a question, not a guess.** If the issue is unclear about scope, acceptance criteria, or which subsystem is affected, ask. Implementing on guesses is worse than no implementation — it encodes the misunderstanding into evidence and the audit trail.
+
+## References
+
+- [`references/compliance-constraints.md`](./references/compliance-constraints.md) — the six architectural constraints + the process risk, audited per framework.
+- [`references/call-graph.md`](./references/call-graph.md) — sub-skill invocation map; what `sdlc-implementer` calls and when.
+- [`references/change-request-loop.md`](./references/change-request-loop.md) — Phase 5 change-request flow in detail, including portal-state semantics.
+- [`../e2e-test-engineer/SKILL.md`](../e2e-test-engineer/SKILL.md) — the test-work sub-skill this orchestrator delegates to.
+- [`SKILLS.md`](../../../../SKILLS.md) — skill contract and conventions for the framework.
+- Portal: `docs/implementing-an-sdlc-issue.md` — the user-facing walkthrough this skill automates. (Lives in the portal repo, currently private; the synced framework copy at `sdlc/files/_common/implementing-an-sdlc-issue.md` is the consumer-visible equivalent.)
+- Portal: `docs/standards-coverage.md` — which SDLC artefacts satisfy which compliance clauses. (Same: portal repo, currently private.)
+- [`metasession-dev/DevAudit-Installer#29`](https://github.com/metasession-dev/DevAudit-Installer/issues/29) — the umbrella issue tracking this skill's delivery.

package/sdlc/files/_common/skills/sdlc-implementer/references/call-graph.md

@@ -0,0 +1,64 @@
+# Sub-skill call graph
+
+The `sdlc-implementer` skill is an orchestrator. It calls into other shipped skills rather than re-implementing their procedures. This document is the authoritative map of when and why each sub-skill is invoked.
+
+## Skills `sdlc-implementer` invokes today
+
+### `e2e-test-engineer` — Phase 2 (Implement and test)
+
+**When**: Any time Phase 2's test-writing step needs end-to-end or visual-regression tests. The risk-class depth table (LOW / MEDIUM / HIGH / CRITICAL) determines whether e2e tests are needed; whenever they are, `e2e-test-engineer` writes them.
+
+**Invocation**: `Skill(name: "e2e-test-engineer", input: { issue: "#N", req: "REQ-XXX", plan_path: "compliance/plans/REQ-XXX/implementation-plan.md", diff: <branch diff> })`.
+
+**Hard contract** (per [`SKILL.md`](../SKILL.md) §Sub-skill invocation contract):
+
+- The orchestrator never authors e2e tests directly.
+- The orchestrator never transcribes `e2e-test-engineer`'s six-phase workflow into its own body.
+- SKILL.md review for `sdlc-implementer` fails if e2e test-authoring logic is inlined.
+
+**Why hard-contract**: `e2e-test-engineer` exists, works, and has been smoke-tested. Re-implementing its scenario-derivation logic inside an orchestrator would (a) drift over time, (b) double the maintenance burden, (c) miss the orchestrator-skill-pattern intended for the framework.
+
+**What `sdlc-implementer` retains responsibility for in Phase 2**:
+
+- Branching off `develop`.
+- Risk-class-based depth selection (deciding _whether_ e2e is needed at all).
+- Unit + integration test writing (these stay with the orchestrator until a counterpart unit-test skill ships).
+- Running all gates (the orchestrator owns the gate execution; `e2e-test-engineer` may have already run the e2e portion).
+- Iterating on gate failures up to N=3 attempts.
+- Committing.
+- Pushing.
+
+## Skills `sdlc-implementer` does NOT invoke
+
+These were previously planned as atomic skills but were deprioritised. The orchestrator handles their slice directly, without calling out:
+
+| Deprecated atomic skill        | What the orchestrator does instead                                                                                                       |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `risk-classifier`              | Phase 1 step 2 — orchestrator reads `Test_Policy.md` directly and classifies risk, emitting the signals it used.                          |
+| `commit-message-author`        | Phase 2 step 7 — orchestrator generates the Conventional Commits message from the staged diff + branch name + RTM entry.                  |
+| `compliance-evidence-author`   | Phase 3 — orchestrator drives the test pack, organises artefacts, uploads via `devaudit push`, updates the RTM.                           |
+| `sast-triager`                 | Phase 2 step 5 — `semgrep` runs as one of the gates; the orchestrator surfaces findings to the human at Phase 1 plan or halts in Phase 2. |
+| `release-ticket-author`        | Phase 4 step 1 — orchestrator drafts the PR body directly from the SDLC PR template + plan.                                               |
+
+If any of these surface in production as repeated pain (per [`SKILLS.md` §When to make a skill vs. when to keep something in a stage doc](../../../../SKILLS.md#when-to-make-a-skill-vs-when-to-keep-something-in-a-stage-doc)), they may be lifted into atomic skills later. The orchestrator would then delegate to them — same pattern as it does today for `e2e-test-engineer`.
+
+## Skills the orchestrator may invoke once they exist
+
+Future expansion. Not committed; listed so the call graph is forward-readable.
+
+- **`unit-test-engineer`** (planned via real-need driver) — would take over Phase 2's unit/integration test writing. The orchestrator's Phase 2 step 2 would invoke this skill the same way it invokes `e2e-test-engineer` today.
+- **`incident-responder`** (planned via real-need driver) — would handle the "production smoke failed in Phase 5" branch. Today the orchestrator falls back to filing an `[INCIDENT]` issue + paging on-call per the project's playbook.
+
+When/if these ship, the call graph in this file gets updated alongside the orchestrator's SKILL.md.
+
+## Skills that invoke `sdlc-implementer`
+
+None. The orchestrator is a top-level entry point — it's invoked directly by the user ("implement issue #N under the SDLC") and runs the framework's stages. It is not designed to be a sub-skill of another orchestrator.
+
+## Invocation discipline
+
+Three rules every orchestrator → sub-skill call should follow:
+
+1. **Pass the minimum context the sub-skill needs.** `e2e-test-engineer` needs the implementation plan + diff; it does not need the orchestrator's full state. Over-passing context bloats the sub-skill's working memory and slows it down.
+2. **Trust the sub-skill's return contract.** If `e2e-test-engineer` says it added 3 tests and they all pass, the orchestrator does not re-verify the assertion. The sub-skill is the authority for its slice.
+3. **Surface sub-skill failures to the human at the orchestrator level.** If `e2e-test-engineer` halts because the project's test framework can't be detected, that's an orchestrator-level halt — the user sees one clear "I couldn't proceed because…" message, not a stack of nested skill output.

package/sdlc/files/_common/skills/sdlc-implementer/references/change-request-loop.md

@@ -0,0 +1,192 @@
+# Phase 5 — change-request loop in detail
+
+When UAT review at Phase 4 ends in "changes requested" instead of "approved", `sdlc-implementer` enters the change-request loop. This document is the long-form spec for that loop, the portal-state semantics it relies on, and the discipline that keeps re-iterations compliant.
+
+The happy path (UAT approved → Phase 5 merge + finalise) is covered in [`SKILL.md` §Phase 5 — Finalise or change-request loop](../SKILL.md#phase-5--finalise-or-change-request-loop). This file goes deeper on the change-request branch.
+
+## Portal-state semantics
+
+The portal's release-approval state machine for a release tied to REQ-XXX:
+
+```
+draft
+  └─→ uat_review (CI registers the release on develop push)
+        ├─→ uat_approved (reviewer clicks Approve on the portal)
+        ├─→ uat_changes_requested (reviewer clicks Request Changes, leaves comments)
+        └─→ uat_rejected (rare — reviewer marks the release fundamentally broken)
+              ↑
+              └─ on new commits to the linked PR branch, state resets to uat_review
+```
+
+Critical: **state resets to `uat_review` on new commits**. This is server-side, not skill-side — the portal watches the branch SHA and clears the approval state when the SHA advances after a `changes_requested` event. The skill must not work around this.
+
+## The change-request loop
+
+When the user runs `> Resume REQ-XXX` and the portal state is `uat_changes_requested`, the skill executes:
+
+### Step 1 — Fetch the change-request comments
+
+Two sources to read:
+
+1. **PR comments** — `gh pr view <M> --comments --json comments,reviews --jq '.comments[].body, .reviews[].body'`. Includes line-level review comments and top-level discussion.
+2. **Portal release-page comments** — `curl https://devaudit.metasession.co/api/projects/<slug>/releases/<version>/comments`. Includes any comments the UAT reviewer left on the release card itself.
+
+Both sources matter: PR comments are usually code-level; portal comments are usually about-the-release-as-a-whole.
+
+### Step 2 — Categorise the requested changes
+
+For each requested change, mark it as one of:
+
+- **Must address** — the reviewer is asking for a specific code/test/doc change.
+- **Question** — the reviewer is asking for clarification, not asking for a code change.
+- **Out of scope** — the reviewer is asking for something this REQ doesn't intend to deliver.
+
+For Questions: post a reply on the PR or portal explaining; do NOT change code.
+For Out-of-scope items: post a reply proposing a follow-up issue; do NOT silently expand REQ-XXX.
+For Must-address items: collect into a delta-plan section.
+
+### Step 3 — Add a delta-plan section to the implementation plan
+
+Append a new section to `compliance/plans/REQ-XXX/implementation-plan.md`:
+
+```markdown
+## Change-request iteration N
+
+**Reviewer**: @<username>
+**Requested**: <YYYY-MM-DD>
+**Iteration**: N
+
+### Requested changes
+
+- [ ] <bullet per Must-address item, with link to the comment that prompted it>
+
+### Approach
+
+<one-paragraph technical approach for addressing the items>
+
+### Test scope delta
+
+<which existing tests need updates, which new tests are needed, whether the change touches any new acceptance criteria>
+
+### Plan deviations
+
+<if the change reveals the original plan was wrong about something, note it here>
+```
+
+This section is append-only — never rewrite a prior iteration's delta-plan section.
+
+### Step 4 — Re-run Phase 2 (Implement and test)
+
+For the Must-address items only:
+
+- Make the code changes
+- Update existing tests or add new ones — **delegating any e2e/visual-regression test work to `e2e-test-engineer`** (the sub-skill invocation contract still applies in iteration N).
+- Re-run all gates locally; gate-failure iteration cap (N=3 attempts) applies per gate.
+- Commit with `Ref: REQ-XXX` + `Co-Authored-By: Claude` + a body that calls out the change-request iteration:
+
+```
+fix(REQ-XXX): address UAT iteration N — <one-line summary>
+
+Iteration N change-request items:
+- <bullet, link to comment>
+- <bullet, link to comment>
+
+Ref: REQ-XXX
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+### Step 5 — Re-run Phase 3 (Compile evidence) — partial
+
+Re-run the test suite that the change affected. Capture new artefacts:
+
+- New e2e results
+- New unit coverage (if unit tests changed)
+- New screenshots (if UI behaviour changed)
+
+Upload via `devaudit push` **with `--iteration N`** so the portal records this evidence as iteration-tagged:
+
+```bash
+devaudit push <slug> REQ-XXX <type> <file> \
+  --release "<version>" \
+  --environment uat --category testing \
+  --iteration N \
+  --git-sha "$(git rev-parse HEAD)"
+```
+
+(If the `--iteration` flag doesn't exist on the consumer's `devaudit` CLI version, fall back to encoding the iteration into the filename: `compliance/evidence/REQ-XXX/YYYY-MM-DD_iter-N_<artefact>`. The portal renders it the same way.)
+
+**Existing evidence stays.** Iteration N adds; it does not replace. The audit trail wants to see what each iteration's evidence looked like.
+
+### Step 6 — Push to the same branch
+
+`git push` — no `--force`. The PR auto-updates.
+
+The portal's release-approval state automatically resets to `uat_review` on the new SHA. Do not call the portal API to re-trigger this; the state machine handles it.
+
+### Step 7 — Re-request UAT review explicitly
+
+Even though state has reset, the reviewer needs notification. Two actions:
+
+1. **Portal API**: `POST https://devaudit.metasession.co/api/projects/<slug>/releases/<version>/approval-requests` with `{"iteration": N, "summary": "Change-request iteration N addressed"}`. This notifies the reviewer on their portal dashboard.
+2. **PR comment**: post a summary comment on the PR linking to the new commits and the iteration-N evidence on the portal:
+
+```
+Change-request iteration N addressed in <SHA>..<SHA>.
+
+Items addressed:
+- <bullet, link to original comment>
+- <bullet, link to original comment>
+
+Updated evidence: https://devaudit.metasession.co/projects/<slug>/requirements/REQ-XXX (filter by iteration N)
+
+@<reviewer-username> — UAT re-review requested.
+```
+
+### Step 8 — Hard stop
+
+The skill halts. The human's next move is reviewing the iteration N changes on the portal. The skill does NOT advance to merge.
+
+## Iteration discipline
+
+A few rules that keep iteration N+1 distinguishable from iteration N:
+
+- **One iteration per UAT cycle**, not one per commit. If the reviewer asks for three changes, address all three in iteration N, push once, request re-review once. Don't fire iteration boundaries per commit.
+- **Cap at 5 iterations** as a heuristic. If a REQ goes through 5+ iterations without converging, the original plan was probably wrong — halt and ask the user whether to abandon the REQ, split it, or restart from a fresh plan.
+- **Never rewrite the original plan's body** in response to iteration feedback. Use the delta-plan sections; the original plan stays as a historical record of what was first proposed.
+- **Iteration commits are still SDLC-conformant.** Conventional Commits format, `Ref: REQ-XXX`, `Co-Authored-By: Claude`, all gates green locally. No exceptions because "it's just a fix to the previous iteration."
+
+## If the change-request is fundamentally a different REQ
+
+Sometimes a reviewer's change-request is so large it constitutes a new requirement, not an iteration on this one. Examples:
+
+- Reviewer asks for an entire new acceptance criterion that wasn't in the original issue.
+- Reviewer asks for a refactor of a subsystem the REQ doesn't touch.
+- Reviewer asks for backwards-compatibility for a deprecated path the REQ removes.
+
+In these cases:
+
+1. Halt with a clear message: "This change-request expands scope beyond REQ-XXX as originally planned. Recommend filing a separate issue for <subject> and addressing only the in-scope items in iteration N of this REQ."
+2. Wait for the user to confirm the split.
+3. Address only the in-scope items in iteration N; the user opens the separate issue, which becomes a new `sdlc-implementer` invocation.
+
+The principle: REQ-XXX has a defined scope at Phase 1. Iterations refine within scope. Iterations are not scope-creep windows.
+
+## If the change-request is a rejection
+
+If the portal state is `uat_rejected` (not `uat_changes_requested`), the reviewer has marked the release fundamentally broken. The skill should:
+
+1. Halt the change-request loop. Do not attempt to address.
+2. Post on the issue: "UAT rejected this release. Awaiting user direction — options are to (a) close the PR and re-plan from scratch, (b) escalate the rejection to a different reviewer, or (c) appeal the rejection with new context."
+3. Wait for the user to decide. The skill does not unilaterally reopen, force-merge, or escalate.
+
+## Summary
+
+The change-request loop preserves the controls a one-shot approval cycle would skip. Every iteration:
+
+- Documents what the reviewer asked for.
+- Documents what was changed and why.
+- Captures fresh evidence tagged by iteration.
+- Triggers an explicit UAT re-review on the portal.
+- Maintains the full audit trail.
+
+By doing so, even REQs that take five iterations to land have the same compliance posture as REQs that pass UAT on the first try.

package/sdlc/files/_common/skills/sdlc-implementer/references/compliance-constraints.md

@@ -0,0 +1,81 @@
+# Compliance constraints (per framework)
+
+The `sdlc-implementer` skill was audited against the five compliance frameworks DevAudit is designed to support. No framework breaks structurally; six architectural constraints + one process risk preserve the controls each framework expects. This document is the long-form audit.
+
+The constraints are enforced in `SKILL.md` and in the smoke pass. Where applicable, the portal itself enforces them server-side as a defence-in-depth measure.
+
+## The six architectural constraints
+
+### 1. Never skip the UAT review gate
+
+| | |
+|---|---|
+| **What** | The skill must not attempt to merge a PR while the `DevAudit Release Approval` check is red. |
+| **Why (framework)** | ISO 27001 A.8.32 (Change management); SOC 2 CC8 (Change management); EU AI Act Art. 14 (Human oversight). The UAT gate is the load-bearing human-oversight checkpoint. |
+| **Enforcement** | Portal-side via `check-release-approval.yml` workflow status check + branch protection. Skill-side: never call `gh pr merge` until the check is green. |
+| **Failure mode if violated** | Merge bypasses human review entirely. Auditor's question "did a human approve this change?" cannot be answered with evidence. |
+
+### 2. For HIGH/CRITICAL, never act as the UAT approver
+
+| | |
+|---|---|
+| **What** | The skill must verify at Phase 4 that the configured UAT reviewer (in `compliance/plans/REQ-XXX/implementation-plan.md` §Four-eyes attestation slot) differs from the skill-trigger user. If they match, halt. |
+| **Why (framework)** | SOC 2 CC8.1 — segregation of duties; ISO 27001 A.5.15 (Access control — duty segregation). The change-author cannot also be the change-approver for higher-risk work. |
+| **Enforcement** | Portal-side: the release-approval API rejects self-approval for MEDIUM/HIGH/CRITICAL risk classes. Skill-side: refuses to open the PR if the configured reviewer matches the trigger user. |
+| **Failure mode if violated** | One human approves their own work. The four-eyes principle is paper-only. |
+
+### 3. Plan checkpoint mandatory for HIGH/CRITICAL
+
+| | |
+|---|---|
+| **What** | At Phase 1 step 8, the skill pauses for human approval of the plan **iff** risk class is HIGH or CRITICAL. LOW/MEDIUM pass through automatically. Can be forced on for all classes via `--require-plan-approval` flag or `DEVAUDIT_REQUIRE_PLAN_APPROVAL=1` env var. |
+| **Why (framework)** | EU AI Act Art. 14 (Human oversight for high-risk AI systems); SOC 2 CC3 (Risk assessment requires human judgement); ISO 29119 §6 (Test management — planning is a documented human step). For HIGH/CRITICAL work the plan IS the design — human review must precede code. |
+| **Enforcement** | Skill-side. Phase 1 explicitly halts and waits for the human's "go" before Phase 2. |
+| **Failure mode if violated** | Code is written + tests are designed + evidence is captured for a HIGH/CRITICAL change without a single human-checkpointed plan. Auditor cannot evidence the design step. |
+
+### 4. Change-request loop triggers full UAT re-review
+
+| | |
+|---|---|
+| **What** | When new commits land on a PR after a UAT change-request, the portal's release-approval state resets. The skill respects the reset, surfaces a "UAT re-review needed" comment, and never assumes the prior approval still covers the new changes. |
+| **Why (framework)** | ISO 27001 A.14.2.4 (Restrictions on changes to software packages — each change goes through controls); SOC 2 CC8.1 (Each change requires approval). Treating "approval given once, all subsequent commits inherit it" would make UAT a one-shot rubber-stamp. |
+| **Enforcement** | Portal-side: the release-approval state machine resets on new commits to the linked branch. Skill-side: re-requests review explicitly via the portal API after each change-request iteration. |
+| **Failure mode if violated** | Drive-by changes ship under cover of an old approval. The audit trail shows "approved once" — but the approved diff is not the diff that shipped. |
+
+### 5. AI involvement disclosed on every commit
+
+| | |
+|---|---|
+| **What** | Every commit the skill creates carries a `Co-Authored-By: Claude <noreply@anthropic.com>` trailer (or equivalent for the specific Claude model in use). |
+| **Why (framework)** | ISO 27001 — transparency norms; EU AI Act Art. 13 (Transparency and provision of information to deployers); GDPR Art. 22 (data subjects' right to know about automated decisions, where applicable). When an auditor traces a commit, the AI involvement must be visible. |
+| **Enforcement** | Skill-side. Every `git commit` call includes the trailer. CI's `compliance-validation.yml` workflow can be configured to grep for `Co-Authored-By` on PRs labelled with the AI-touched marker; this is optional but recommended. |
+| **Failure mode if violated** | AI-generated code is indistinguishable from human-authored code in the audit trail. Future-proofing against tightening AI-disclosure regulations breaks. |
+
+### 6. All portal mutations through audit-logged APIs
+
+| | |
+|---|---|
+| **What** | The skill calls `devaudit push` and the standard portal HTTP APIs — never a database back-channel, never a service-role-key-equivalent that bypasses the audit log. |
+| **Why (framework)** | ISO 27001 A.12.4 (Logging and monitoring); SOC 2 CC4 + CC7 (Monitoring activities + system operations). Every action that affects compliance state must produce an audit-log entry attributable to a human identity (the user whose PAT is in `DEVAUDIT_USER_TOKEN`). |
+| **Enforcement** | Skill-side. All portal interaction goes through `devaudit push` or `curl`/`gh api` against the documented REST endpoints. |
+| **Failure mode if violated** | Compliance-affecting actions land on the portal with no audit-log trail. Auditor's "who did this?" question is unanswerable. |
+
+## The one process risk
+
+### 7. Rubber-stamping at UAT
+
+| | |
+|---|---|
+| **What** | If the UAT reviewer approves without actually reading the change, the controls are formally satisfied but substantively hollow. |
+| **Why (framework)** | SOC 2 CC4.1 (Monitoring activities — the entity should detect this via its own QA sampling). Not enforced by any control mechanism; relies on human discipline. |
+| **Enforcement** | Not architectural. Mitigations: the SKILL.md's Principles section names the UAT reviewer as "the load-bearing human"; the portal's UAT-review UI intentionally adds friction (no one-click approve from email); org policy should random-sample approvals for QA. |
+| **Failure mode if violated** | Auditors detect approval velocity that doesn't match human reading time. Spot-checks reveal approvals on changes the approver couldn't articulate. Trust erodes. |
+
+## What's NOT a compliance break
+
+Audited and cleared:
+
+- **Audit log attribution** (ISO 27001 A.12.4): Actions flow through the user's tokens (`DEVAUDIT_USER_TOKEN`, `GH_TOKEN`); commits carry `Co-Authored-By`; UAT approval is a genuine human act recorded on the portal. The auditor's question "did this human review this?" is answered by the UAT-approval event on the portal, not by the commit signature.
+- **GDPR Art. 22** (Automated decisions about data subjects): Doesn't apply. The skill makes technical decisions, not decisions about people. If the issue being implemented IS Art. 22 work (an algorithm that decides about data subjects), the implementation plan captures DPA/DPIA requirements at Phase 1 — same as today.
+- **EU AI Act high-risk classification of the skill itself**: The skill is a productivity tool, not high-risk under Annex III. Art. 14 (Human oversight) is satisfied by the HIGH/CRITICAL plan checkpoint + the always-on UAT gate.
+- **ISO 29119 test adequacy**: Human at UAT reviews test scope. Same caveat as #7 above — depends on UAT reviewer paying attention.