@metasession.co/devaudit-cli 0.1.12 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "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.12",
+    "@metasession.co/devaudit-plugin-sdk": "^0.1.14",
     "commander": "^12.1.0",
     "consola": "^3.2.3",
     "env-paths": "^3.0.0",

package/sdlc/files/_common/5-deploy-main.md

@@ -151,6 +151,15 @@ If the smoke results look wrong or a manual verification fails, click **Reject**
 
 ### Step 6: Finalize Compliance (Tracked Requirements Only)
 
+> **Automated path (preferred).** Run the synced helper instead of doing this by hand — it flips the ticket Status → `RELEASED` (+ backlinks the release PR and records the sign-off), flips the matching `RTM.md` row, and `git mv`s the ticket to `approved-releases/`, then stages the changes for you to commit:
+>
+> ```bash
+> ./scripts/close-out-release.sh REQ-XXX --release-pr <release-PR-#>
+> git add -A && git commit -m "docs(compliance): close out REQ-XXX release ticket (RELEASED)" && git push origin develop
+> ```
+>
+> It is **idempotent** (a no-op if already closed out) and, when `DEVAUDIT_API_KEY` + `DEVAUDIT_BASE_URL` are set, **refuses** unless the portal reports the release as `released` (so you can't flip the local tree ahead of the Production approval). The `close-out-release.yml` workflow runs the same script automatically when the portal marks a release released (and is `workflow_dispatch`-able for catch-up). The manual steps below are the fallback / reference for what the script does.
+
 ```bash
 mv compliance/pending-releases/RELEASE-TICKET-REQ-XXX.md compliance/approved-releases/
 ```

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

@@ -36,23 +36,30 @@ For typo fixes, formatting changes, dependency bumps, and other zero-risk chores
 
 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)
+## Default mode: the `sdlc-implementer` skill
 
-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:
+The [`sdlc-implementer`](#skills-inventory) skill is the **default way to implement a tracked change** — it is shipped and synced into this repo at `.claude/skills/sdlc-implementer/`. Give it one GitHub issue and the whole walkthrough below 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:
+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:
 
 ```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.
+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).
 
-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.
+**When it is NOT used:**
+
+- **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.
+
+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).)
 
 ---
 

package/sdlc/files/_common/scripts/close-out-release.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# close-out-release.sh — Reconcile the local compliance tree after a release
+# is marked `released` on the DevAudit portal.
+#
+# For one requirement it: flips the release ticket Status -> RELEASED (backlinks
+# the release PR + records the sign-off), flips the matching compliance/RTM.md
+# row -> RELEASED, and moves the ticket from compliance/pending-releases/ to
+# compliance/approved-releases/. It stages the changes but does NOT commit — the
+# caller (the close-out workflow, or a human) commits/opens the PR.
+#
+# Usage:
+#   ./scripts/close-out-release.sh <REQ-ID> [--release-pr <url-or-number>]
+#
+# Example:
+#   ./scripts/close-out-release.sh REQ-046 --release-pr 138
+#
+# Optional environment (portal safety check — recommended in CI):
+#   DEVAUDIT_API_KEY  + DEVAUDIT_BASE_URL  — when both are set, the script
+#     confirms the portal reports the release as `released` before flipping
+#     anything, refusing otherwise (prevents local "RELEASED" while the portal
+#     is still at prod_review). When unset, it warns and proceeds (manual mode).
+#
+# Idempotent: if the ticket is already in approved-releases/ with Status
+# RELEASED (and the RTM row already RELEASED), it exits 0 as a no-op.
+
+set -euo pipefail
+
+REQ_ID="${1:-}"
+RELEASE_PR=""
+shift || true
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --release-pr) RELEASE_PR="${2:-}"; shift 2 ;;
+    *) echo "Unknown option: $1" >&2; exit 2 ;;
+  esac
+done
+
+if ! printf '%s' "$REQ_ID" | grep -qE '^REQ-[0-9]{3,}$'; then
+  echo "Usage: $0 <REQ-ID> [--release-pr <url-or-number>]   (REQ-ID like REQ-046)" >&2
+  exit 2
+fi
+
+PENDING="compliance/pending-releases/RELEASE-TICKET-${REQ_ID}.md"
+APPROVED_DIR="compliance/approved-releases"
+APPROVED="${APPROVED_DIR}/RELEASE-TICKET-${REQ_ID}.md"
+RTM="compliance/RTM.md"
+TODAY="$(date +%Y-%m-%d)"
+
+# ── Optional portal safety check ─────────────────────────────────────────────
+if [ -n "${DEVAUDIT_API_KEY:-}" ] && [ -n "${DEVAUDIT_BASE_URL:-}" ]; then
+  BASE="${DEVAUDIT_BASE_URL%/}"
+  SLUG="$(jq -r '.devaudit.project_slug // .project_slug // empty' sdlc-config.json 2>/dev/null || true)"
+  STATUS="$(curl -s -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
+    "${BASE}/api/ci/releases/resolve?projectSlug=${SLUG}&versionPrefix=${REQ_ID}" 2>/dev/null \
+    | jq -r '.latest.status // empty' 2>/dev/null || true)"
+  if [ -n "$STATUS" ] && [ "$STATUS" != "released" ]; then
+    echo "::error::Portal reports ${REQ_ID} as '${STATUS}', not 'released'. Refusing to close out." >&2
+    exit 1
+  fi
+  [ "$STATUS" = "released" ] && echo "Portal confirms ${REQ_ID} is released."
+else
+  echo "::warning::DEVAUDIT_API_KEY/DEVAUDIT_BASE_URL not set — skipping portal status check (manual mode)."
+fi
+
+# ── Idempotency ──────────────────────────────────────────────────────────────
+if [ ! -f "$PENDING" ] && [ -f "$APPROVED" ]; then
+  if grep -qE '^\*\*Status:\*\*[[:space:]]*RELEASED' "$APPROVED"; then
+    echo "${REQ_ID} already closed out (ticket in approved-releases/, Status RELEASED) — no-op."
+    exit 0
+  fi
+fi
+if [ ! -f "$PENDING" ] && [ ! -f "$APPROVED" ]; then
+  echo "::error::No RELEASE-TICKET-${REQ_ID}.md in pending-releases/ or approved-releases/." >&2
+  exit 1
+fi
+
+# ── Move ticket pending -> approved (if still pending) ───────────────────────
+mkdir -p "$APPROVED_DIR"
+if [ -f "$PENDING" ]; then
+  git mv "$PENDING" "$APPROVED" 2>/dev/null || mv "$PENDING" "$APPROVED"
+  echo "Moved ticket -> ${APPROVED}"
+fi
+
+# ── Flip ticket Status + backlink + sign-off (edit AFTER the move, then stage —
+#    avoids leaving content edits unstaged behind a rename) ────────────────────
+TMP="$(mktemp)"
+SIGN_OFF="**Sign-off (dual-actor):** UAT approved + Production approved on the DevAudit portal (\`released\`); post-deploy production smoke evidence captured. Closed out ${TODAY}."
+PR_LINE=""
+if [ -n "$RELEASE_PR" ]; then
+  case "$RELEASE_PR" in
+    http*) PR_LINE="**Release PR:** ${RELEASE_PR}" ;;
+    *)     PR_LINE="**Release PR:** #${RELEASE_PR}" ;;
+  esac
+fi
+awk -v signoff="$SIGN_OFF" -v prline="$PR_LINE" '
+  BEGIN { status_done=0; signoff_added=0 }
+  # Flip the first Status line.
+  /^\*\*Status:\*\*/ && status_done==0 { print "**Status:** RELEASED"; status_done=1; next }
+  # Replace a placeholder Release PR line if present and a PR was supplied.
+  /^\*\*Release PR:\*\*/ && prline!="" { print prline; next }
+  { print }
+  # After the DevAudit Release line, append the sign-off (once) if not already present.
+  /^\*\*DevAudit Release:\*\*/ && signoff_added==0 {
+    print signoff; signoff_added=1
+  }
+' "$APPROVED" > "$TMP"
+# Only add a Release PR line if there was no existing one to replace.
+if [ -n "$PR_LINE" ] && ! grep -qE '^\*\*Release PR:\*\*' "$TMP"; then
+  awk -v prline="$PR_LINE" '
+    /^\*\*DevAudit Release:\*\*/ { print prline }
+    { print }
+  ' "$TMP" > "${TMP}.2" && mv "${TMP}.2" "$TMP"
+fi
+mv "$TMP" "$APPROVED"
+git add "$APPROVED" 2>/dev/null || true
+echo "Ticket Status -> RELEASED."
+
+# ── Flip the RTM row -> RELEASED (preserve any parenthetical note) ───────────
+if [ -f "$RTM" ] && grep -qE "^\| ${REQ_ID} " "$RTM"; then
+  awk -v req="$REQ_ID" '
+    BEGIN { FS="|"; OFS="|"; statuscol=0 }
+    # Locate the "Status" column from the first header row that has one.
+    statuscol==0 {
+      for (i=1; i<=NF; i++) { c=$i; gsub(/^[[:space:]]+|[[:space:]]+$/, "", c); if (c=="Status") statuscol=i }
+    }
+    $0 ~ ("^\\| " req " ") && statuscol>0 {
+      cell=$statuscol
+      note=""
+      if (match(cell, /\(/)) note=substr(cell, RSTART)   # preserve any " (requirement note)"
+      gsub(/^[[:space:]]+|[[:space:]]+$/, "", note)
+      $statuscol = (note != "" ? " RELEASED " note " " : " RELEASED ")
+      print; next
+    }
+    { print }
+  ' "$RTM" > "$TMP" && mv "$TMP" "$RTM"
+  git add "$RTM" 2>/dev/null || true
+  echo "RTM row ${REQ_ID} -> RELEASED."
+else
+  echo "::warning::No RTM row for ${REQ_ID} in ${RTM} — skipped RTM flip."
+  rm -f "$TMP"
+fi
+
+echo "Close-out staged for ${REQ_ID}. Commit + open a PR to develop to land it."

package/sdlc/files/ci/close-out-release.yml.template

@@ -0,0 +1,96 @@
+# Release close-out — reconcile the local compliance tree after a release is
+# marked `released` on the DevAudit portal.
+#
+# Generated by `devaudit install` / `devaudit update` from sdlc-config.json.
+# Do not edit manually — re-run the CLI (`devaudit update`) to regenerate.
+#
+# Triggers:
+#   - repository_dispatch (type: release-closed) — sent by the DevAudit portal
+#     when it advances a release to `released`. client_payload: { release,
+#     release_pr }.
+#   - workflow_dispatch — manual catch-up for an already-released requirement.
+#
+# It runs scripts/close-out-release.sh for the requirement (flip ticket +
+# RTM, move ticket to approved-releases/), then opens a PR to develop. The
+# script is idempotent, so a no-op produces no PR.
+
+name: Release Close-out
+
+on:
+  workflow_dispatch:
+    inputs:
+      release:
+        description: 'REQ-XXX to close out (e.g. REQ-046)'
+        required: true
+      release_pr:
+        description: 'Release PR number or URL to backlink (optional)'
+        required: false
+  repository_dispatch:
+    types: [release-closed]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  close-out:
+    name: Close out release
+    runs-on: {{RUNNER}}
+    env:
+      GH_TOKEN: ${{ github.token }}
+      DEVAUDIT_API_KEY: ${{ secrets.DEVAUDIT_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: develop
+          fetch-depth: 0
+
+      - name: Resolve inputs
+        id: in
+        run: |
+          REQ="${{ github.event.inputs.release }}${{ github.event.client_payload.release }}"
+          PR="${{ github.event.inputs.release_pr }}${{ github.event.client_payload.release_pr }}"
+          if ! printf '%s' "$REQ" | grep -qE '^REQ-[0-9]{3,}$'; then
+            echo "::error::No valid REQ-XXX supplied (inputs.release / client_payload.release)."
+            exit 1
+          fi
+          echo "req=${REQ}" >> "$GITHUB_OUTPUT"
+          echo "pr=${PR}" >> "$GITHUB_OUTPUT"
+          # Portal base URL for the safety check (read from sdlc-config.json).
+          BASE=$(jq -r '.devaudit.base_url // empty' sdlc-config.json 2>/dev/null || true)
+          echo "DEVAUDIT_BASE_URL=${BASE%/}" >> "$GITHUB_ENV"
+
+      - name: Run close-out
+        id: closeout
+        run: |
+          chmod +x scripts/close-out-release.sh 2>/dev/null || true
+          ARGS="${{ steps.in.outputs.req }}"
+          [ -n "${{ steps.in.outputs.pr }}" ] && ARGS="${ARGS} --release-pr ${{ steps.in.outputs.pr }}"
+          bash scripts/close-out-release.sh ${ARGS}
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            echo "Nothing to close out (idempotent no-op) — no PR opened."
+          fi
+
+      - name: Open close-out PR
+        if: steps.closeout.outputs.changed == 'true'
+        run: |
+          REQ="${{ steps.in.outputs.req }}"
+          BRANCH="chore/close-out-${REQ}"
+          git config user.name "devaudit-bot"
+          git config user.email "devaudit-bot@users.noreply.github.com"
+          git checkout -b "$BRANCH"
+          git add -A
+          git commit -m "docs(compliance): close out ${REQ} release ticket (RELEASED)
+
+          Automated reconciliation after the DevAudit portal marked ${REQ} released.
+          Ticket Status -> RELEASED + moved to approved-releases/; RTM row -> RELEASED.
+
+          Ref: ${REQ}"
+          git push -u origin "$BRANCH" --force-with-lease
+          gh pr create --base develop --head "$BRANCH" \
+            --title "docs(compliance): close out ${REQ} release ticket (RELEASED)" \
+            --body "Automated close-out — the DevAudit portal marked **${REQ}** \`released\`. This moves the ticket to \`approved-releases/\`, flips its Status and the RTM row to \`RELEASED\`. Review + merge to develop, then promote to main." \
+            || echo "::warning::PR may already exist for ${BRANCH}."