@metasession.co/devaudit-cli 0.1.18 → 0.1.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "DevAudit CLI — installs, syncs, and operates the Metasession SDLC across consumer projects.",
   "type": "module",
   "bin": {
@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.8.2",
-    "@metasession.co/devaudit-plugin-sdk": "^0.1.18",
+    "@metasession.co/devaudit-plugin-sdk": "^0.1.19",
     "commander": "^12.1.0",
     "consola": "^3.2.3",
     "env-paths": "^3.0.0",

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

@@ -338,9 +338,11 @@ EOF
 
 ---
 
-### Step 9: Update Requirements Document (If Applicable)
+### Step 9: Update the Software Requirements Specification (If Applicable)
 
-If the requirement modifies a documented feature, update the requirements document to reflect the intended change.
+If the requirement adds, changes, or removes **observable behaviour**, update the project's Software Requirements Specification (`docs/SRS.md`) — or `docs/REQUIREMENTS.md` if the project has not adopted the SRS — to reflect the intended change. The SRS is the MoSCoW-prioritised, Given/When/Then source that developers and the `e2e-test-engineer` skill derive tests from, so keeping it current is what carries the requirement through into test cases.
+
+Only act if the document exists; do not introduce an SRS on a project that has not adopted one.
 
 ### Step 10: Document AI Use Intent (If Applicable)
 
@@ -361,7 +363,11 @@ For Low risk, the `Co-Authored-By` commit tag is sufficient.
 ### Step 11: Commit
 
 ```bash
-git add compliance/RTM.md compliance/evidence/REQ-XXX docs/REQUIREMENTS.md
+# Stage the RTM + evidence. Add the requirements doc only if you updated it in Step 9
+# — whichever the project uses; staging an unchanged tracked file is a harmless no-op.
+git add compliance/RTM.md compliance/evidence/REQ-XXX
+[ -f docs/SRS.md ] && git add docs/SRS.md
+[ -f docs/REQUIREMENTS.md ] && git add docs/REQUIREMENTS.md
 git commit -m "compliance: [REQ-XXX] define requirement and test scope - [description] [RISK: LOW/MEDIUM/HIGH]
 
 Ref: REQ-XXX

package/sdlc/files/_common/4-submit-for-review.md

@@ -160,6 +160,7 @@ CI runs automatically on this PR. The following gates must pass before merge:
 
 ## Compliance Artifacts
 - [ ] RTM updated with risk level
+- [ ] SRS updated if observable behaviour changed (`docs/SRS.md`, or `docs/REQUIREMENTS.md` if not yet adopted) — or N/A
 - [ ] Test scope addressed (all items in test-scope.md completed)
 - [ ] Implementation plan present and matches implementation (MEDIUM/HIGH risk)
 - [ ] Release ticket created
@@ -201,6 +202,7 @@ CI runs automatically on this PR. The following gates must pass before merge:
 
 **Compliance**
 - [ ] RTM status: TESTED - PENDING SIGN-OFF
+- [ ] SRS updated if observable behaviour changed (or correctly N/A)
 - [ ] Release ticket accurate
 - [ ] Security evidence present and clean
 

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

@@ -38,7 +38,7 @@ If you're not sure whether your change is trivial, treat it as non-trivial (chea
 
 ### Trivial-change walkthrough
 
-A worked end-to-end example for a zero-risk change (a typo, a dependency bump, a README tweak, a CI-config nudge). No requirement, no plan, no evidence pack — but the gates still run and a human still reviews the PR. `sdlc-implementer` is **not** used here.
+A worked end-to-end example for a zero-risk change (a typo, a dependency bump, a README tweak, a CI-config nudge). No requirement, no plan, no evidence pack — but the gates still run and a human still reviews the PR. You can run these steps by hand, or let `sdlc-implementer` drive them: its Phase-0 triage routes a trivial change down exactly this lightweight path and guides it to merge (without the tracked ceremony).
 
 1. **Branch off `develop`.** `git checkout develop && git pull && git checkout -b docs/fix-readme-typo` (or `chore/…`, `ci/…`). A GitHub issue is welcome but not required for a true triviality.
 2. **Make the change, keep it single-purpose.** If it touches `app/` or `lib/` runtime behaviour, it is **not** trivial — stop and run the full SDLC (Stage 1 onward). The commit-type rule below is the backstop.
@@ -57,7 +57,9 @@ The [`sdlc-implementer`](#skills-inventory) skill is the **default way to implem
 > Implement issue #N under the SDLC.
 ```
 
-It runs Phases 1–4 unattended (with a plan-approval pause for HIGH/CRITICAL risk, or always-on via `--require-plan-approval`): classify risk, assign the next `REQ-XXX`, write the implementation plan, update `RTM.md`, implement, delegate all end-to-end / visual test work to [`e2e-test-engineer`](#skills-inventory), run the gates, compile evidence, open the PR, and submit for UAT review on the portal. It then **halts** at the UAT gate. After a reviewer approves on the portal:
+It **triages first** (Phase 0): it reads the issue + labels, classifies the change-type against the [change-workflows](https://github.com/metasession-dev/DevAudit-Installer/blob/main/docs/change-workflows.md) taxonomy, announces a **Workflow Decision** (which path, which gates, which approvals, what's skipped), and routes — only a tracked change continues into the full cycle; housekeeping / trivial / doc-only is announced and handed off to its lighter path. So pointing the skill at an issue no longer defaults to maximum ceremony — it decides the path at pickup.
+
+For a tracked change it then runs Phases 1–4 unattended (with a plan-approval pause for HIGH/CRITICAL risk, or always-on via `--require-plan-approval`): classify risk, assign the next `REQ-XXX`, write the implementation plan, update `RTM.md`, implement, delegate all end-to-end / visual test work to [`e2e-test-engineer`](#skills-inventory), run the gates, compile evidence, open the PR, and submit for UAT review on the portal. It then **halts** at the UAT gate. After a reviewer approves on the portal:
 
 ```text
 > Resume REQ-XXX.
@@ -65,12 +67,13 @@ It runs Phases 1–4 unattended (with a plan-approval pause for HIGH/CRITICAL ri
 
 It runs Phase 5: merge, monitor post-deploy, confirm production smoke evidence, advance the release. If changes are requested at UAT instead of approval, it addresses them and re-submits for UAT re-review. It **refuses** issues that decompose into multiple requirements (split them first).
 
-**When it is NOT used:**
+**Where it routes (the Phase-0 decision):** the skill now makes this call at pickup rather than you discovering mid-PR that you over- (or under-) ceremonied. It still **drives each path to completion** — these are the paths it takes *instead of* the full tracked cycle, not points where it abandons you:
 
-- **Trivial / housekeeping changes** — see the escape hatch above. Docs, formatting, dependency bumps, CI tweaks (`docs:` / `chore:` / `ci:` …) don't need a requirement and don't go through the skill. (Note: `feat` / `fix` / `refactor` / `perf` commits **do** require a `[REQ-XXX]` / `Ref: REQ-XXX` and are rejected by commitlint + `validate-commits.sh` without one.)
-- **Stage-1 planning in isolation, or e2e test work alone** — run the manual walkthrough / invoke `e2e-test-engineer` directly.
-- **Cross-issue refactors** spanning multiple `REQ-XXX` scopes — out of the one-issue contract.
-- **When the orchestration can't apply** (unusual repo state, partial work mid-stream) — fall back to the manual walkthrough below.
+- **Trivial / housekeeping changes** → the skill drives the lightweight escape hatch (above) to merge: branch → all gates locally → `chore:`/`docs:`/`ci:` PR → review → merge. No requirement, no tracked cycle, but it guides every step. Docs, formatting, dependency bumps, CI tweaks (`docs:` / `chore:` / `ci:` …) don't need a requirement. (Note: `feat` / `fix` / `refactor` / `perf` commits **do** require a `[REQ-XXX]` / `Ref: REQ-XXX` and are rejected by commitlint + `validate-commits.sh` without one.)
+- **Compliance-doc-only** → the skill drives a docs push against an **existing** `REQ-XXX` through to merge; no new requirement, no quality gates.
+- **Stage-1 planning in isolation, or e2e test work alone** → run the manual walkthrough / invoke `e2e-test-engineer` directly.
+- **Cross-issue refactors** spanning multiple `REQ-XXX` scopes → out of the one-issue contract; the skill refuses and asks you to split.
+- **When the orchestration can't apply** (unusual repo state, partial work mid-stream) → fall back to the manual walkthrough below.
 
 The manual walkthrough below is the **operational reference** for exactly what the skill does at each stage — and the fallback when the skill isn't the right fit. (For an audience-level walkthrough with sample AI prompts, see the portal's [`implementing-an-sdlc-issue.md`](https://github.com/metasession-dev/devaudit/blob/main/docs/implementing-an-sdlc-issue.md).)
 
@@ -378,7 +381,7 @@ The Metasession SDLC framework includes a set of [Claude Code Skills](https://gi
 | 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, …). |
-| [`sdlc-implementer`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/sdlc/files/_common/skills/sdlc-implementer/SKILL.md) | 1–5 | One-command orchestration (the **default** for a tracked change): `"implement issue #N under the SDLC"` runs Phase 1 (classify risk, write plan, update RTM) → Phase 2 (branch, tests, implement, gates) → Phase 3 (evidence + portal upload) → Phase 4 (PR + request UAT review), halting at the UAT gate. `"resume REQ-XXX"` runs Phase 5 (merge, post-deploy, mark Released), or the change-request loop. **MUST** invoke `e2e-test-engineer` for e2e/visual work; never authors e2e directly. Enforces six compliance constraints (never skip UAT, no self-approval for HIGH/CRITICAL, mandatory plan checkpoint for HIGH/CRITICAL, change-request → UAT re-review, AI disclosure per commit, all portal mutations audit-logged). **Not** used for trivial/housekeeping changes. |
+| [`sdlc-implementer`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/sdlc/files/_common/skills/sdlc-implementer/SKILL.md) | 1–5 | One-command orchestration (the **default** for a tracked change): `"implement issue #N under the SDLC"` runs Phase 1 (classify risk, write plan, update RTM) → Phase 2 (branch, tests, implement, gates) → Phase 3 (evidence + portal upload) → Phase 4 (PR + request UAT review), halting at the UAT gate. `"resume REQ-XXX"` runs Phase 5 (merge, post-deploy, mark Released), or the change-request loop. **MUST** invoke `e2e-test-engineer` for e2e/visual work; never authors e2e directly. Enforces six compliance constraints (never skip UAT, no self-approval for HIGH/CRITICAL, mandatory plan checkpoint for HIGH/CRITICAL, change-request → UAT re-review, AI disclosure per commit, all portal mutations audit-logged). **Triages at pickup (Phase 0)** and routes: tracked → Stages 1–5; trivial/housekeeping/doc-only → a lightweight path it drives to merge without tracked ceremony. |
 
 ### Roadmap
 

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

@@ -1,12 +1,14 @@
 ---
 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.
+description: Take a GitHub issue end-to-end through the Metasession SDLC. Opens with a Workflow Triage step (Phase 0) that classifies the change and routes it — tracked work continues into the full cycle; housekeeping/trivial/doc-only is driven to merge down a lightweight path (same step-by-step guidance, no tracked ceremony). 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.
+Take a single GitHub issue end-to-end through the Metasession SDLC. The skill **triages first** (Phase 0): it classifies the change, announces the path it will take, and routes — only a **tracked** change continues into the full cycle, while housekeeping, trivial, and compliance-doc-only work is driven down its lighter path **to completion** (the skill still guides every step to merge; it just skips the tracked ceremony). For a tracked change, 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 skill is a single entry point that **routes**, not one that always runs heavy. The change-type taxonomy it routes against is the canonical table in [`change-workflows.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/docs/change-workflows.md) (six change-types → commit-type → requirement? → path).
 
 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.
 
@@ -14,6 +16,7 @@ This is an **orchestration skill**. It drives Claude Code's native tools (`gh`,
 
 **In scope**
 
+- Pickup-time **workflow triage** (Phase 0): read the issue + labels, classify the change-type, announce the path, and route — tracked work into Stages 1–5; housekeeping / trivial / compliance-doc-only **driven to merge down the Lightweight path** (same guidance, no tracked ceremony).
 - 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.
@@ -42,11 +45,61 @@ Unit-test and integration-test work stays with this skill until a counterpart un
 
 ## The workflow
 
-Five phases. Phases 1–4 run in one Claude Code session; Phase 5 is invoked separately by the user after UAT.
+A triage step (Phase 0) routes the issue, then up to five phases for tracked work. Phase 0 plus Phases 1–4 run in one Claude Code session; Phase 5 is invoked separately by the user after UAT. The off-ramps from Phase 0 (housekeeping / trivial / doc-only) don't enter Phase 1 — they run the **Lightweight path** (below), which the skill drives to merge.
+
+### Phase 0 — Workflow triage (classify → announce → confirm → route)
+
+Runs **first**, before any `REQ-XXX` is assigned. It decides which of the six change-types in [`change-workflows.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/docs/change-workflows.md) applies and what will — and won't — run. This is what stops every issue defaulting to maximum ceremony.
+
+1. **Fetch.** `gh issue view <N> --json labels,title,body` and read all comments. Read the **labels** as well as the title and body.
+2. **Classify the change-workflow**, inference-first (labels are optional input). Precedence, highest first:
+   1. An explicit `type:*` / `risk:*` label → **authoritative**.
+   2. A conventional-commit prefix in the issue title — `feat` / `fix` / `refactor` / `perf` → **tracked**; `chore` / `ci` / `build` / `test` / `docs` / `compliance` → **housekeeping / doc-only**.
+   3. The issue template — Requirement → tracked; Bug → fix (tracked); Task → housekeeping.
+   4. Body heuristics — acceptance criteria, or risk signals (auth, payments, RBAC, data egress, AI decisioning) → tracked, and raise the risk class.
+
+   Map the result to one of the six paths in `change-workflows.md`.
+3. **Announce a "Workflow Decision" block** (template below): change-type, commit-type, whether a `REQ-XXX` is needed, risk class, which stages/gates run, which approvals the **operator** must perform (UAT four-eyes, Production approval), and what is **skipped**.
+4. **Pause policy — pause-when-it-matters.** Pause for explicit confirmation on **tracked / heavier** paths, or when classification is **ambiguous**; **announce-and-auto-proceed** on trivial / housekeeping. The operator can always reclassify ("treat this as housekeeping" / "this is HIGH risk").
+5. **Route — and stay on to completion.** A route is a choice of *which workflow to drive*, never a hand-off that abandons the operator. Whatever the path, the skill keeps guiding step by step until no further action is required (typically: merged).
+   - **tracked** (feature / bug fix / refactor / perf) → continue into Phase 1 below (full Stages 1–5).
+   - **housekeeping / trivial** → drive the **Lightweight path** below to completion. No `REQ-XXX`, no RTM row, no evidence pack, no portal release approvals — but the skill still branches, runs the gates, opens the PR, and walks the operator through review → merge.
+   - **compliance-doc-only** → drive the same Lightweight path as a docs push (or PR, per the project's flow) referencing the **existing** `REQ-XXX`: no new requirement and no quality-gate ceremony, but driven through to merge.
+6. **Write labels back.** Apply the inferred `type:*` / `risk:*` labels so the issue ends up labelled — `gh label create <label> --force` to ensure the label exists (idempotent; no failure if a label-seeding step never ran), then `gh issue edit <N> --add-label <label>`. Future triage is then a glance.
+
+**"Workflow Decision" announcement template**
+
+> **Workflow decision — #N**
+> - **Change type:** \<Feature | Bug fix | Refactor/Perf | Housekeeping | Trivial | Compliance-doc-only\>
+> - **Commit type:** \<feat | fix | refactor | chore | docs | …\>
+> - **Requirement:** \<REQ-XXX assigned | none\>
+> - **Risk:** \<LOW | MEDIUM | HIGH | CRITICAL\>
+> - **Path:** \<Full SDLC Stages 1–5 | Lightweight (gates → chore PR) | Doc-only push\>
+> - **Gates/evidence:** \<…\>
+> - **Your approvals:** \<UAT four-eyes + Production approval | PR review only\>
+> - **Skipped:** \<…\>
+> Proceed? *(or reclassify)*
+
+Only the **tracked** route continues into Phase 1; the others run the Lightweight path below. The off-ramps are deliberate — dragging housekeeping through tracked-change machinery it doesn't need is exactly the failure mode this step exists to prevent — but they are still **driven to completion**, never dumped as a checklist for the operator to run alone.
+
+### Lightweight path (housekeeping / trivial / compliance-doc-only)
+
+Reached from Phase 0 for non-tracked change-types. The skill drives this end-to-end; the only difference from the tracked cycle is the absence of *ceremony*, not the absence of *guidance*. It pauses only where a human is genuinely required (PR review, merge).
+
+1. **Branch off `develop`** with a housekeeping prefix — `chore/…`, `docs/…`, `ci/…`, `build/…`, `test/…`, or `compliance/…` for a doc-only change against an existing REQ.
+2. **Make the change**, single-purpose. If it turns out to touch runtime behaviour in `app/` / `lib/`, stop and reclassify as tracked — the commit-type rule is the backstop.
+3. **Run all gates locally** (`npm run lint`, `npx tsc --noEmit`, the test suite, `semgrep`, `npm audit` — or the stack-adapter equivalents). Trivial ≠ unverified; never `--no-verify`.
+4. **Commit** with a housekeeping type and **no** `REQ-XXX` — `docs:` / `chore:` / `ci:` / `build:` / `test:` / `revert:` are exempt from the `[REQ-XXX]` rule; a `compliance:` doc-only change references the existing REQ. `Co-Authored-By: Claude` if AI-assisted.
+5. **Push and open the PR.** CI runs the same quality gates; `compliance-validation.yml` finds no `REQ-XXX` and skips artifact validation.
+6. **Report honest status** — wait for CI, name any failing check, fix and re-push. Never announce "ready" while a required check is red.
+7. **Guide review → merge.** A human still reviews the PR (separation of duties). There is **no** portal release approval, no UAT four-eyes, no Production gate, and no close-out. Merge once CI is green and the reviewer approves.
+8. **Done.** A housekeeping push produces at most a bare-date release (`vYYYY.MM.DD`) with no approval gate; a doc-only push attaches its docs to the existing `REQ-XXX` release. No further action required — report completion and stop.
 
 ### Phase 1 — Plan (SDLC stage 1)
 
-1. **Fetch the issue.** `gh issue view <N>` — read the title, body, and all comments.
+Reached only on the **tracked** route from Phase 0 (the issue is already fetched and classified).
+
+1. **Confirm the issue scope.** Re-read the `gh issue view <N>` output from Phase 0 — title, body, all comments — with implementation in mind.
 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.
@@ -179,6 +232,7 @@ Plus one process risk surfaced explicitly in the principles below (rubber-stampi
 
 ## References
 
+- [`change-workflows.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/docs/change-workflows.md) — the canonical change-type taxonomy and the pickup-time **Workflow triage** decision Phase 0 runs against.
 - [`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.