@metasession.co/devaudit-cli 0.1.20 → 0.1.22

package/package.json

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

package/scripts/upload-evidence.sh

@@ -17,6 +17,15 @@
 #   --category <cat>            Evidence category: ci_pipeline, local_dev,
 #                               planning, test_report, security_scan,
 #                               release_artifact
+#   --release-title <text>      Human title for the release row (e.g. the
+#                               release-ticket H1). Forwarded as
+#                               `releaseTitle`; the portal no-clobbers
+#                               existing non-null values.
+#   --change-type <type>        Conventional-commit prefix (feat / fix /
+#                               refactor / perf / chore / docs / ci /
+#                               build / test / compliance / revert) for
+#                               the release row. Unknown values are
+#                               silently dropped server-side.
 #
 # Required environment variables:
 #   DEVAUDIT_BASE_URL  e.g. https://meta-comply-production.up.railway.app
@@ -54,6 +63,8 @@ RELEASE_VERSION=""
 CREATE_RELEASE_IF_MISSING=false
 ENVIRONMENT=""
 EVIDENCE_CATEGORY=""
+RELEASE_TITLE=""
+CHANGE_TYPE=""
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
@@ -64,6 +75,11 @@ while [ "$#" -gt 0 ]; do
     --create-release-if-missing) CREATE_RELEASE_IF_MISSING=true; shift ;;
     --environment) ENVIRONMENT="$2"; shift 2 ;;
     --category) EVIDENCE_CATEGORY="$2"; shift 2 ;;
+    # Descriptive title + conventional-commit change type passed through to
+    # the portal's findOrCreateRelease no-clobber backfill. Both optional;
+    # unknown change-type values are dropped server-side, not 400'd.
+    --release-title) RELEASE_TITLE="$2"; shift 2 ;;
+    --change-type) CHANGE_TYPE="$2"; shift 2 ;;
     *) echo "Unknown option: $1"; exit 1 ;;
   esac
 done
@@ -163,6 +179,8 @@ for FILE in "${FILES[@]}"; do
   [ -n "$BRANCH" ] && CURL_ARGS+=(-F "releaseBranch=${BRANCH}")
   [ -n "$ENVIRONMENT" ] && CURL_ARGS+=(-F "environment=${ENVIRONMENT}")
   [ -n "$EVIDENCE_CATEGORY" ] && CURL_ARGS+=(-F "evidenceCategory=${EVIDENCE_CATEGORY}")
+  [ -n "$RELEASE_TITLE" ] && CURL_ARGS+=(-F "releaseTitle=${RELEASE_TITLE}")
+  [ -n "$CHANGE_TYPE" ] && CURL_ARGS+=(-F "changeType=${CHANGE_TYPE}")
 
   ATTEMPT=1
   BACKOFF=$INITIAL_BACKOFF_SECONDS

package/sdlc/files/ci/check-release-approval.yml.template

@@ -70,8 +70,18 @@ jobs:
           esac
           # Bootstrap probe (#301): project may not exist in DevAudit yet —
           # the first compliance-evidence.yml run auto-creates it. A 404 here
-          # means we're on the introducing PR; pass with a notice. 401/403
+          # means we're on the introducing PR; pass with a warning. 401/403
           # means the API key is invalid → fail (not bootstrap).
+          #
+          # Defense in depth (#74): if /api/ci/projects/<slug> 404s we
+          # cross-check against /api/ci/releases/resolve — a known-good
+          # read endpoint scoped to the same project. If THAT returns 2xx
+          # the project clearly exists, and the projects-endpoint 404 is a
+          # portal-side bug. Failing closed beats silently passing the
+          # four-eyes gate. The original "GET /api/ci/projects/<slug>"
+          # endpoint didn't exist on the portal before metasession-dev/
+          # devaudit#NN, so this exact false-positive was the universal
+          # state of the gate across every consumer.
           PROJ_CODE=$(curl -s -o /dev/null -w "%{http_code}" -m 10 \
             -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
             "${BASE%/}/api/ci/projects/${PROJECT_SLUG}" || echo "000")
@@ -80,9 +90,34 @@ jobs:
               echo "DevAudit project '${PROJECT_SLUG}' confirmed (HTTP ${PROJ_CODE})"
               ;;
             404)
-              echo "::notice::DevAudit project '${PROJECT_SLUG}' does not exist yet (HTTP 404) — bootstrap mode. Gate passes. The project will be auto-created by the first compliance-evidence.yml run; enforcement kicks in on the next PR after that."
-              echo "BOOTSTRAP_MODE=true" >> "$GITHUB_ENV"
-              exit 0
+              # Cross-check: does the project actually exist? versionPrefix=v
+              # matches every release version shape (REQ-XXX, vYYYY.MM.DD,
+              # vX.Y.Z) — we don't care about the body, only whether the
+              # endpoint authorises the project. Endpoint returns 200 even
+              # when no releases match the prefix (just with latest: null).
+              CROSS_CODE=$(curl -s -o /dev/null -w "%{http_code}" -m 10 \
+                -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
+                "${BASE%/}/api/ci/releases/resolve?projectSlug=${PROJECT_SLUG}&versionPrefix=v" \
+                || echo "000")
+              case "$CROSS_CODE" in
+                2*)
+                  echo "::error::Portal /api/ci/projects/${PROJECT_SLUG} returned 404 but releases/resolve confirms the project exists (HTTP ${CROSS_CODE}). This is a portal-side issue (missing or broken endpoint), not a bootstrap. Failing closed to avoid silently bypassing the four-eyes gate. Triage at metasession-dev/devaudit (and/or DevAudit-Installer#75)."
+                  exit 1
+                  ;;
+                404)
+                  echo "::warning::DevAudit project '${PROJECT_SLUG}' does not exist yet (HTTP 404 from both /api/ci/projects and /api/ci/releases/resolve) — bootstrap mode. Gate passes. The project will be auto-created by the first compliance-evidence.yml run; enforcement kicks in on the next PR after that."
+                  echo "BOOTSTRAP_MODE=true" >> "$GITHUB_ENV"
+                  exit 0
+                  ;;
+                401|403)
+                  echo "::error::DevAudit returned HTTP ${CROSS_CODE} for releases/resolve on project '${PROJECT_SLUG}' (cross-check after the projects endpoint 404'd) — API key is invalid or lacks access. Verify DEVAUDIT_API_KEY belongs to the right project."
+                  exit 1
+                  ;;
+                *)
+                  echo "::error::Cross-check endpoint /api/ci/releases/resolve returned unexpected HTTP ${CROSS_CODE} after the projects endpoint 404'd. Investigate before retrying."
+                  exit 1
+                  ;;
+              esac
               ;;
             401|403)
               echo "::error::DevAudit returned HTTP ${PROJ_CODE} for project '${PROJECT_SLUG}' — API key is invalid or lacks access. Verify DEVAUDIT_API_KEY belongs to the right project."

package/sdlc/files/ci/ci.yml.template

@@ -212,20 +212,64 @@ jobs:
             --git-sha ${{ github.sha }} --branch ${{ github.ref_name }} || true
 
       - name: Sync known requirements from RTM
+        env:
+          GH_TOKEN: ${{ github.token }}
         run: |
-          if [ -f "compliance/RTM.md" ]; then
-            REQS=$(grep -oP 'REQ-\d+' compliance/RTM.md | sort -t- -k2 -n -u)
-            if [ -n "$REQS" ]; then
-              JSON_ARRAY=$(echo "$REQS" | jq -R -s -c 'split("\n") | map(select(length > 0))')
-              HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
-                -X PATCH "${BASE}/api/ci/projects/{{PROJECT_SLUG}}/known-requirements" \
-                -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
-                -H "Content-Type: application/json" \
-                -d "{\"requirements\": ${JSON_ARRAY}}")
-              echo "known_requirements sync: HTTP ${HTTP_CODE}"
-              echo "Synced $(echo "$REQS" | wc -w) requirements from RTM.md"
+          if [ ! -f "compliance/RTM.md" ]; then exit 0; fi
+
+          # Per REQ row in RTM we look up: title (release-ticket H1, else the
+          # linked issue's title via `gh`), and risk_class (the first LOW /
+          # MEDIUM / HIGH / CRITICAL token in the row). Both are optional —
+          # the portal renders gracefully with nulls. The portal endpoint
+          # accepts either a bare string[] (legacy) or rich rows.
+          REQS_JSON='[]'
+          while IFS= read -r REQ; do
+            [ -z "$REQ" ] && continue
+            ROW=$(grep -m1 -E "^\| ${REQ} " compliance/RTM.md || true)
+            TITLE=""
+            # Title: release-ticket H1 first (pending then approved)
+            for FILE in "compliance/pending-releases/RELEASE-TICKET-${REQ}.md" \
+                        "compliance/approved-releases/RELEASE-TICKET-${REQ}.md"; do
+              if [ -f "$FILE" ]; then
+                TITLE=$(grep -m1 '^# ' "$FILE" \
+                  | sed -E 's/^# *(REQ-[0-9]+)?[[:space:]]*[—:-]?[[:space:]]*//')
+                break
+              fi
+            done
+            # Title fallback: first issue # found anywhere in the row
+            if [ -z "$TITLE" ] && [ -n "$ROW" ]; then
+              ISSUE_NUM=$(echo "$ROW" | grep -oE '#[0-9]+' | head -1 | tr -d '#')
+              if [ -n "$ISSUE_NUM" ]; then
+                TITLE=$(gh issue view "$ISSUE_NUM" --json title --jq .title 2>/dev/null || true)
+              fi
+            fi
+            # Risk: first LOW/MEDIUM/HIGH/CRITICAL token in the row
+            RISK=""
+            if [ -n "$ROW" ]; then
+              RISK=$(echo "$ROW" | grep -ioE '\b(LOW|MEDIUM|HIGH|CRITICAL)\b' | head -1 \
+                | tr 'a-z' 'A-Z')
             fi
+            REQS_JSON=$(echo "$REQS_JSON" | jq \
+              --arg id "$REQ" --arg title "$TITLE" --arg risk "$RISK" \
+              '. + [{
+                id: $id,
+                title: (if $title == "" then null else $title end),
+                riskClass: (if $risk == "" then null else $risk end)
+              }]')
+          done < <(grep -oE 'REQ-[0-9]+' compliance/RTM.md | sort -t- -k2 -n -u)
+
+          COUNT=$(echo "$REQS_JSON" | jq length)
+          if [ "$COUNT" = "0" ]; then
+            echo "No REQ-XXX rows in RTM.md — skipping sync"
+            exit 0
           fi
+          HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
+            -X PATCH "${BASE}/api/ci/projects/{{PROJECT_SLUG}}/known-requirements" \
+            -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
+            -H "Content-Type: application/json" \
+            -d "{\"requirements\": ${REQS_JSON}}")
+          echo "known_requirements sync: HTTP ${HTTP_CODE}"
+          echo "Synced ${COUNT} requirements from RTM.md (titles + risk_class)"
 
   # ──────────────────────────────────────────────
   # Upload Evidence to DevAudit (after gates pass)
@@ -357,6 +401,20 @@ jobs:
             echo "Uploading ${#SHOTS[@]} evidence screenshot(s) for: ${SHOT_REQS[*]}"
             SHOT_TMP="$(mktemp -d)"
             for REQ in "${SHOT_REQS[@]}"; do
+              # Per-REQ release metadata for the portal (no-clobbered on existing rows):
+              # release title from the pending ticket's H1; change type from the
+              # latest commit that references the REQ.
+              REQ_TITLE=""
+              if [ -f "compliance/pending-releases/RELEASE-TICKET-${REQ}.md" ]; then
+                REQ_TITLE=$(grep -m1 '^# ' "compliance/pending-releases/RELEASE-TICKET-${REQ}.md" \
+                  | sed -E 's/^# *(REQ-[0-9]+)?[[:space:]]*[—:-]?[[:space:]]*//')
+              fi
+              REQ_CT=$(git log --grep "\[${REQ}\]\|Ref: ${REQ}" --pretty=%s -1 2>/dev/null \
+                | grep -oE '^(feat|fix|refactor|perf|chore|docs|ci|build|test|compliance|revert)' \
+                | head -1 || true)
+              REQ_META=()
+              [ -n "$REQ_TITLE" ] && REQ_META+=(--release-title "$REQ_TITLE")
+              [ -n "$REQ_CT" ] && REQ_META+=(--change-type "$REQ_CT")
               for PNG in "${SHOTS[@]}"; do
                 # The folder is the (SRS) requirement id, the basename is the AC
                 # slug (ACn-…). Upload as <srs-req>-<slug>.png so the reviewer can
@@ -367,6 +425,7 @@ jobs:
                 bash scripts/upload-evidence.sh \
                   {{PROJECT_SLUG}} "$REQ" screenshot "$NAMED" \
                   --category test_report ${FLAGS} --release "$REQ" \
+                  "${REQ_META[@]}" \
                   || echo "::warning::evidence screenshot upload failed: ${PNG} -> ${REQ}"
               done
             done

package/sdlc/files/ci/compliance-evidence.yml.template

@@ -110,16 +110,47 @@ jobs:
           FLAGS="${FLAGS} --create-release-if-missing --environment uat"
           DERIVED_RELEASE="${{ steps.version.outputs.version }}"
 
+          # Derive change_type for the bare-date (housekeeping) DERIVED_RELEASE:
+          # the prefix of the most recent commit's subject. No-op for tracked
+          # releases — they get per-REQ derivation in the loop below.
+          DERIVED_CT=$(git log -1 --pretty=%s 2>/dev/null \
+            | grep -oE '^(feat|fix|refactor|perf|chore|docs|ci|build|test|compliance|revert)' \
+            | head -1 || true)
+          DERIVED_META=()
+          [ -n "$DERIVED_CT" ] && DERIVED_META+=(--change-type "$DERIVED_CT")
+
           # Upload compliance docs (planning category)
           for DOC in compliance/RTM.md compliance/test-plan.md compliance/test-cases.md compliance/test-summary-report.md; do
             if [ -f "$DOC" ]; then
               echo "Uploading: $(basename "$DOC")"
               bash scripts/upload-evidence.sh \
                 {{PROJECT_SLUG}} _compliance-docs compliance_document "$DOC" \
-                --category planning ${FLAGS} --release "${DERIVED_RELEASE}" || echo "Warning: Failed to upload $(basename "$DOC")"
+                --category planning ${FLAGS} --release "${DERIVED_RELEASE}" \
+                "${DERIVED_META[@]}" \
+                || echo "Warning: Failed to upload $(basename "$DOC")"
             fi
           done
 
+          # Helper: emit a `--release-title …` `--change-type …` pair for a given
+          # REQ, derived from its pending release-ticket H1 and the most recent
+          # commit attributed to that REQ. Empty pair when neither is available.
+          req_meta_args() {
+            local REQ="$1"; local TITLE=""; local CT=""
+            for FILE in "compliance/pending-releases/RELEASE-TICKET-${REQ}.md" \
+                        "compliance/approved-releases/RELEASE-TICKET-${REQ}.md"; do
+              if [ -f "$FILE" ]; then
+                TITLE=$(grep -m1 '^# ' "$FILE" \
+                  | sed -E 's/^# *(REQ-[0-9]+)?[[:space:]]*[—:-]?[[:space:]]*//')
+                break
+              fi
+            done
+            CT=$(git log --grep "\[${REQ}\]\|Ref: ${REQ}" --pretty=%s -1 2>/dev/null \
+              | grep -oE '^(feat|fix|refactor|perf|chore|docs|ci|build|test|compliance|revert)' \
+              | head -1 || true)
+            [ -n "$TITLE" ] && printf -- '--release-title %q ' "$TITLE"
+            [ -n "$CT" ] && printf -- '--change-type %q ' "$CT"
+          }
+
           # Upload release tickets (pending only)
           if [ -d "compliance/pending-releases" ]; then
             for TICKET in compliance/pending-releases/*.md; do
@@ -130,14 +161,18 @@ jobs:
               case "$TICKET_BASE" in
                 RELEASE-TICKET-REQ-*)
                   TICKET_REQ="${TICKET_BASE#RELEASE-TICKET-}"
-                  TICKET_OWNER="$TICKET_REQ"; TICKET_RELEASE="$TICKET_REQ" ;;
+                  TICKET_OWNER="$TICKET_REQ"; TICKET_RELEASE="$TICKET_REQ"
+                  TICKET_META_ARGS=$(req_meta_args "$TICKET_REQ") ;;
                 *)
-                  TICKET_OWNER="_compliance-docs"; TICKET_RELEASE="$DERIVED_RELEASE" ;;
+                  TICKET_OWNER="_compliance-docs"; TICKET_RELEASE="$DERIVED_RELEASE"
+                  TICKET_META_ARGS="" ;;
               esac
               echo "Uploading: $(basename "$TICKET") -> release ${TICKET_RELEASE}"
-              bash scripts/upload-evidence.sh \
-                {{PROJECT_SLUG}} "${TICKET_OWNER}" compliance_document "$TICKET" \
-                --category release_artifact ${FLAGS} --release "${TICKET_RELEASE}" || echo "Warning: Failed to upload $(basename "$TICKET")"
+              eval "bash scripts/upload-evidence.sh \
+                {{PROJECT_SLUG}} \"${TICKET_OWNER}\" compliance_document \"$TICKET\" \
+                --category release_artifact ${FLAGS} --release \"${TICKET_RELEASE}\" \
+                ${TICKET_META_ARGS}" \
+                || echo "Warning: Failed to upload $(basename "$TICKET")"
             done
           fi
 
@@ -165,12 +200,15 @@ jobs:
                 echo "Warning: pending ticket for ${REQ_ID} but no ${REQ_DIR} on disk"
                 continue
               fi
+              REQ_META_ARGS=$(req_meta_args "$REQ_ID")
               for ARTIFACT in "$REQ_DIR"*.md; do
                 [ -f "$ARTIFACT" ] || continue
                 echo "Uploading: ${REQ_ID}/$(basename "$ARTIFACT")"
-                bash scripts/upload-evidence.sh \
-                  {{PROJECT_SLUG}} "${REQ_ID}" compliance_document "$ARTIFACT" \
-                  --category planning ${FLAGS} --release "${REQ_ID}" || echo "Warning: Failed to upload $(basename "$ARTIFACT")"
+                eval "bash scripts/upload-evidence.sh \
+                  {{PROJECT_SLUG}} \"${REQ_ID}\" compliance_document \"$ARTIFACT\" \
+                  --category planning ${FLAGS} --release \"${REQ_ID}\" \
+                  ${REQ_META_ARGS}" \
+                  || echo "Warning: Failed to upload $(basename "$ARTIFACT")"
               done
             done
           fi

package/sdlc/files/ci/python/ci.yml.template

@@ -196,20 +196,61 @@ jobs:
             --git-sha ${{ github.sha }} --branch ${{ github.ref_name }} || true
 
       - name: Sync known requirements from RTM
+        env:
+          GH_TOKEN: ${{ github.token }}
         run: |
-          if [ -f "compliance/RTM.md" ]; then
-            REQS=$(grep -oP 'REQ-\d+' compliance/RTM.md | sort -t- -k2 -n -u)
-            if [ -n "$REQS" ]; then
-              JSON_ARRAY=$(echo "$REQS" | jq -R -s -c 'split("\n") | map(select(length > 0))')
-              HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
-                -X PATCH "${BASE}/api/ci/projects/{{PROJECT_SLUG}}/known-requirements" \
-                -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
-                -H "Content-Type: application/json" \
-                -d "{\"requirements\": ${JSON_ARRAY}}")
-              echo "known_requirements sync: HTTP ${HTTP_CODE}"
-              echo "Synced $(echo "$REQS" | wc -w) requirements from RTM.md"
+          if [ ! -f "compliance/RTM.md" ]; then exit 0; fi
+
+          # Per REQ row in RTM we look up: title (release-ticket H1, else the
+          # linked issue's title via `gh`), and risk_class (the first LOW /
+          # MEDIUM / HIGH / CRITICAL token in the row). Both are optional —
+          # the portal renders gracefully with nulls. The portal endpoint
+          # accepts either a bare string[] (legacy) or rich rows.
+          REQS_JSON='[]'
+          while IFS= read -r REQ; do
+            [ -z "$REQ" ] && continue
+            ROW=$(grep -m1 -E "^\| ${REQ} " compliance/RTM.md || true)
+            TITLE=""
+            for FILE in "compliance/pending-releases/RELEASE-TICKET-${REQ}.md" \
+                        "compliance/approved-releases/RELEASE-TICKET-${REQ}.md"; do
+              if [ -f "$FILE" ]; then
+                TITLE=$(grep -m1 '^# ' "$FILE" \
+                  | sed -E 's/^# *(REQ-[0-9]+)?[[:space:]]*[—:-]?[[:space:]]*//')
+                break
+              fi
+            done
+            if [ -z "$TITLE" ] && [ -n "$ROW" ]; then
+              ISSUE_NUM=$(echo "$ROW" | grep -oE '#[0-9]+' | head -1 | tr -d '#')
+              if [ -n "$ISSUE_NUM" ]; then
+                TITLE=$(gh issue view "$ISSUE_NUM" --json title --jq .title 2>/dev/null || true)
+              fi
+            fi
+            RISK=""
+            if [ -n "$ROW" ]; then
+              RISK=$(echo "$ROW" | grep -ioE '\b(LOW|MEDIUM|HIGH|CRITICAL)\b' | head -1 \
+                | tr 'a-z' 'A-Z')
             fi
+            REQS_JSON=$(echo "$REQS_JSON" | jq \
+              --arg id "$REQ" --arg title "$TITLE" --arg risk "$RISK" \
+              '. + [{
+                id: $id,
+                title: (if $title == "" then null else $title end),
+                riskClass: (if $risk == "" then null else $risk end)
+              }]')
+          done < <(grep -oE 'REQ-[0-9]+' compliance/RTM.md | sort -t- -k2 -n -u)
+
+          COUNT=$(echo "$REQS_JSON" | jq length)
+          if [ "$COUNT" = "0" ]; then
+            echo "No REQ-XXX rows in RTM.md — skipping sync"
+            exit 0
           fi
+          HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
+            -X PATCH "${BASE}/api/ci/projects/{{PROJECT_SLUG}}/known-requirements" \
+            -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
+            -H "Content-Type: application/json" \
+            -d "{\"requirements\": ${REQS_JSON}}")
+          echo "known_requirements sync: HTTP ${HTTP_CODE}"
+          echo "Synced ${COUNT} requirements from RTM.md (titles + risk_class)"
 
   upload-evidence:
     name: Upload Evidence