@metasession.co/devaudit-cli 0.3.27 → 0.3.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.3.27",
+  "version": "0.3.29",
   "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.3.27",
+    "@metasession.co/devaudit-plugin-sdk": "^0.3.29",
     "ajv": "^8.20.0",
     "commander": "^12.1.0",
     "consola": "^3.2.3",

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

@@ -34,6 +34,10 @@
 
 set -euo pipefail
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=markdown-table.sh
+source "$SCRIPT_DIR/markdown-table.sh"
+
 REQ_ID="${1:-}"
 RELEASE_PR=""
 shift || true
@@ -89,21 +93,14 @@ find_release_ticket_file() {
 update_rtm_status() {
   local req_id="$1"
   local target_status="$2"
-  local tmp_file
+  local tmp_file status_col
   tmp_file="$(mktemp)"
-  if [ -f "$RTM" ] && grep -qE "^\| ${req_id} " "$RTM"; then
-    awk -v req="$req_id" -v target_status="$target_status" '
-      BEGIN { FS="|"; OFS="|"; statuscol=0 }
+  status_col="$(markdown_table_column_index_for_row \
+    "$RTM" "$req_id" Status REQ-ID/ID Status 2>/dev/null || true)"
+  if [ -n "$status_col" ]; then
+    awk -v req="$req_id" -v target_status="$target_status" -v statuscol="$status_col" '
+      BEGIN { FS="|"; OFS="|" }
       /\\\|/ { gsub(/\\\|/, "\001", $0) }
-      {
-        cand=0; idseen=0
-        for (i=1; i<=NF; i++) {
-          c=$i; gsub(/^[[:space:]]+|[[:space:]]+$/, "", c)
-          if (c=="Status") cand=i
-          if (c=="ID" || c=="REQ-ID" || c=="REQ ID" || c ~ /^Requirement/) idseen=1
-        }
-        if (cand>0 && idseen) statuscol=cand
-      }
       $0 ~ ("^\\| " req " ") && statuscol>0 {
         cell=$statuscol
         note=""

package/sdlc/files/_common/scripts/evaluate-npm-audit.sh

@@ -39,6 +39,7 @@ done
 python3 - "$AUDIT_PATH" "$LOCK_PATH" "$EXCEPTIONS_PATH" "$OUTPUT_PATH" <<'PY'
 import json
 import os
+import re
 import sys
 from datetime import date
 
@@ -144,8 +145,11 @@ for index, item in enumerate(exceptions, start=1):
         fail(f"exception {index} approvedAt cannot be in the future")
     if expires_at <= today:
         fail(f"exception {index} is expired on {item['expiresAt']}")
-    if not item["remediationIssue"].startswith("https://github.com/"):
-        fail(f"exception {index} remediationIssue must be a GitHub issue URL")
+    if re.fullmatch(r"https://github\.com/[^/]+/[^/]+/issues/[1-9][0-9]*", item["remediationIssue"]) is None:
+        fail(f"exception {index} remediationIssue must be an exact GitHub issue URL")
+    controls = item.get("compensatingControls")
+    if controls is not None and (not isinstance(controls, str) or not controls.strip()):
+        fail(f"exception {index} compensatingControls must be a non-empty string when present")
     key = (item["advisoryId"], item["dependencyPath"])
     if key in seen_exception_keys:
         fail(f"duplicate exception for {item['advisoryId']} at {item['dependencyPath']}")
@@ -157,75 +161,108 @@ accepted = []
 unresolved = []
 seen_advisories = set()
 
-for finding_name, finding in audit["vulnerabilities"].items():
+vulnerabilities = audit["vulnerabilities"]
+
+
+def concrete_advisories(finding_name, trail=()):
+    if finding_name in trail:
+        fail(f"audit vulnerability graph contains a cycle: {' -> '.join((*trail, finding_name))}")
+    finding = vulnerabilities.get(finding_name)
     if not isinstance(finding, dict):
-        fail(f"audit vulnerability {finding_name} must be an object")
+        fail(f"audit vulnerability {finding_name} is missing or is not an object")
     via = finding.get("via", [])
     if not isinstance(via, list):
         fail(f"audit vulnerability {finding_name} has invalid via data")
-    advisory_objects = [
-        item for item in via
-        if isinstance(item, dict) and item.get("severity") in ("high", "critical")
-    ]
-    if finding.get("severity") in ("high", "critical") and not advisory_objects:
-        fail(f"high/critical audit vulnerability {finding_name} has no resolvable advisory object")
-
-    nodes = finding.get("nodes", [])
-    if advisory_objects and (not isinstance(nodes, list) or not nodes):
-        fail(f"audit vulnerability {finding_name} has no installed package-lock node")
-
-    for advisory in advisory_objects:
-        package = advisory.get("dependency") or finding_name
-        advisory_range = advisory.get("range")
-        if not isinstance(package, str) or not package:
-            fail(f"advisory in {finding_name} has no package name")
-        if not isinstance(advisory_range, str) or not advisory_range:
-            fail(f"advisory {advisory_id(advisory)} has no vulnerable range")
-        identifier = advisory_id(advisory)
-        for node_path in nodes:
-            if not isinstance(node_path, str):
-                fail(f"advisory {identifier} has invalid package-lock node")
-            node = packages.get(node_path)
-            if not isinstance(node, dict) or not isinstance(node.get("version"), str):
-                fail(f"cannot resolve installed version for {node_path}")
-            if package_name_from_path(node_path) != package:
-                fail(f"audit package {package} does not match package-lock node {node_path}")
-            version = node["version"]
-            introduced_by = introducer_for(node_path, packages)
-            decision_key = (identifier, node_path)
-            if decision_key in seen_advisories:
-                continue
-            seen_advisories.add(decision_key)
-            context = {
-                "advisoryId": identifier,
-                "severity": advisory["severity"],
-                "package": package,
-                "vulnerableRange": advisory_range,
-                "vulnerableVersion": version,
-                "dependencyPath": node_path,
-                "introducedBy": introduced_by,
+
+    resolved = []
+    for index, item in enumerate(via):
+        if isinstance(item, str):
+            if item not in vulnerabilities:
+                fail(f"audit vulnerability {finding_name} references missing vulnerability {item}")
+            resolved.extend(concrete_advisories(item, (*trail, finding_name)))
+        elif isinstance(item, dict):
+            if item.get("severity") in ("high", "critical"):
+                resolved.append((finding_name, index, item))
+        else:
+            fail(f"audit vulnerability {finding_name} has invalid via entry")
+    return resolved
+
+
+advisory_sources = {}
+for finding_name, finding in vulnerabilities.items():
+    if not isinstance(finding, dict):
+        fail(f"audit vulnerability {finding_name} must be an object")
+    resolved = concrete_advisories(finding_name)
+    if finding.get("severity") in ("high", "critical") and not resolved:
+        fail(f"high/critical audit vulnerability {finding_name} has no reachable advisory object")
+    for source_name, source_index, advisory in resolved:
+        advisory_sources.setdefault((source_name, source_index), {
+            "advisory": advisory,
+            "affectedFindings": set(),
+        })["affectedFindings"].add(finding_name)
+
+for (source_name, _source_index), source in advisory_sources.items():
+    advisory = source["advisory"]
+    source_finding = vulnerabilities[source_name]
+    nodes = source_finding.get("nodes", [])
+    if not isinstance(nodes, list) or not nodes:
+        fail(f"audit vulnerability {source_name} has no installed package-lock node")
+
+    package = advisory.get("dependency") or source_name
+    advisory_range = advisory.get("range")
+    if not isinstance(package, str) or not package:
+        fail(f"advisory in {source_name} has no package name")
+    if not isinstance(advisory_range, str) or not advisory_range:
+        fail(f"advisory {advisory_id(advisory)} has no vulnerable range")
+    identifier = advisory_id(advisory)
+    for node_path in nodes:
+        if not isinstance(node_path, str):
+            fail(f"advisory {identifier} has invalid package-lock node")
+        node = packages.get(node_path)
+        if not isinstance(node, dict) or not isinstance(node.get("version"), str):
+            fail(f"cannot resolve installed version for {node_path}")
+        if package_name_from_path(node_path) != package:
+            fail(f"audit package {package} does not match package-lock node {node_path}")
+        version = node["version"]
+        introduced_by = introducer_for(node_path, packages)
+        decision_key = (identifier, node_path)
+        if decision_key in seen_advisories:
+            continue
+        seen_advisories.add(decision_key)
+        context = {
+            "advisoryId": identifier,
+            "severity": advisory["severity"],
+            "package": package,
+            "vulnerableRange": advisory_range,
+            "vulnerableVersion": version,
+            "dependencyPath": node_path,
+            "introducedBy": introduced_by,
+            "affectedFindings": sorted(source["affectedFindings"]),
+        }
+        match = next((item for item in validated_exceptions if all(
+            item[field] == context[field]
+            for field in ("advisoryId", "package", "vulnerableRange", "vulnerableVersion", "dependencyPath", "introducedBy")
+        )), None)
+        if match is None:
+            unresolved.append(context)
+            print(
+                f"Unaccepted {context['severity']} risk: {identifier} "
+                f"({package}@{version} at {node_path})",
+                file=sys.stderr,
+            )
+        else:
+            acceptance = {
+                field: match[field]
+                for field in ("approvedAt", "expiresAt", "approvedBy", "reason", "remediationIssue")
             }
-            match = next((item for item in validated_exceptions if all(
-                item[field] == context[field]
-                for field in ("advisoryId", "package", "vulnerableRange", "vulnerableVersion", "dependencyPath", "introducedBy")
-            )), None)
-            if match is None:
-                unresolved.append(context)
-                print(
-                    f"Unaccepted {context['severity']} risk: {identifier} "
-                    f"({package}@{version} at {node_path})",
-                    file=sys.stderr,
-                )
-            else:
-                accepted.append({**context, "acceptance": {
-                    field: match[field]
-                    for field in ("approvedAt", "expiresAt", "approvedBy", "reason", "remediationIssue")
-                }})
-                print(
-                    f"Accepted temporary risk: {identifier} ({package}@{version}) "
-                    f"until {match['expiresAt']} by {match['approvedBy']}; "
-                    f"remediation {match['remediationIssue']}",
-                )
+            if "compensatingControls" in match:
+                acceptance["compensatingControls"] = match["compensatingControls"]
+            accepted.append({**context, "acceptance": acceptance})
+            print(
+                f"Accepted temporary risk: {identifier} ({package}@{version}) "
+                f"until {match['expiresAt']} by {match['approvedBy']}; "
+                f"remediation {match['remediationIssue']}",
+            )
 
 result = {
     "schemaVersion": 1,

package/sdlc/files/_common/scripts/evaluate-npm-audit.test.sh

@@ -7,6 +7,9 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 HELPER="$SCRIPT_DIR/evaluate-npm-audit.sh"
 WORK="$(mktemp -d)"
 trap 'rm -rf "$WORK"' EXIT
+APPROVED_AT="$(date -u -d 'yesterday' +%Y-%m-%d)"
+EXPIRES_AT="$(date -u -d '+30 days' +%Y-%m-%d)"
+EXPIRED_AT="$(date -u -d 'yesterday' +%Y-%m-%d)"
 
 mkdir -p "$WORK/compliance/security"
 
@@ -37,6 +40,47 @@ write_empty_audit() {
   printf '{"vulnerabilities":{}}\n' > "$WORK/dependency-audit.json"
 }
 
+write_meta_audit() {
+  cat > "$WORK/dependency-audit.json" <<'JSON'
+{
+  "vulnerabilities": {
+    "eslint": {
+      "name": "eslint",
+      "severity": "high",
+      "via": ["@eslint/eslintrc"],
+      "nodes": ["node_modules/eslint"]
+    },
+    "@eslint/eslintrc": {
+      "name": "@eslint/eslintrc",
+      "severity": "high",
+      "via": ["minimatch"],
+      "nodes": ["node_modules/@eslint/eslintrc"]
+    },
+    "minimatch": {
+      "name": "minimatch",
+      "severity": "high",
+      "via": ["brace-expansion"],
+      "nodes": ["node_modules/@eslint/eslintrc/node_modules/minimatch"]
+    },
+    "brace-expansion": {
+      "name": "brace-expansion",
+      "severity": "high",
+      "via": [
+        {
+          "name": "brace-expansion",
+          "dependency": "brace-expansion",
+          "url": "https://github.com/advisories/GHSA-meta-chain",
+          "severity": "high",
+          "range": "<=5.0.7"
+        }
+      ],
+      "nodes": ["node_modules/@eslint/eslintrc/node_modules/brace-expansion"]
+    }
+  }
+}
+JSON
+}
+
 write_lock() {
   cat > "$WORK/package-lock.json" <<'JSON'
 {
@@ -50,6 +94,21 @@ write_lock() {
 JSON
 }
 
+write_meta_lock() {
+  cat > "$WORK/package-lock.json" <<'JSON'
+{
+  "lockfileVersion": 3,
+  "packages": {
+    "": {"name": "fixture"},
+    "node_modules/eslint": {"version": "9.0.0"},
+    "node_modules/@eslint/eslintrc": {"version": "3.0.0"},
+    "node_modules/@eslint/eslintrc/node_modules/minimatch": {"version": "9.0.0"},
+    "node_modules/@eslint/eslintrc/node_modules/brace-expansion": {"version": "2.0.1"}
+  }
+}
+JSON
+}
+
 write_exception() {
   cat > "$WORK/compliance/security/accepted-vulnerabilities.json" <<'JSON'
 {
@@ -66,11 +125,16 @@ write_exception() {
       "expiresAt": "2026-12-31",
       "approvedBy": "reviewer@example.test",
       "reason": "Fixture acceptance while the introducing dependency awaits an upstream repair.",
-      "remediationIssue": "https://github.com/example/repo/issues/1"
+      "remediationIssue": "https://github.com/example/repo/issues/1",
+      "compensatingControls": "Monitor upstream releases and retain the unaffected root package."
     }
   ]
 }
 JSON
+  jq --arg approved "$APPROVED_AT" --arg expires "$EXPIRES_AT" \
+    '.exceptions[0].approvedAt = $approved | .exceptions[0].expiresAt = $expires' \
+    "$WORK/compliance/security/accepted-vulnerabilities.json" > "$WORK/changed.json"
+  mv "$WORK/changed.json" "$WORK/compliance/security/accepted-vulnerabilities.json"
 }
 
 run_helper() {
@@ -107,7 +171,7 @@ jq -e '.summary.accepted == 0 and .summary.unresolved == 0' "$WORK/dependency-ri
 write_audit
 write_exception
 expect_success
-jq -e '.summary.accepted == 1 and .summary.unresolved == 0 and .accepted[0].acceptance.remediationIssue == "https://github.com/example/repo/issues/1"' \
+jq -e '.summary.accepted == 1 and .summary.unresolved == 0 and .accepted[0].acceptance.remediationIssue == "https://github.com/example/repo/issues/1" and (.accepted[0].acceptance.compensatingControls | length > 0)' \
   "$WORK/dependency-risk-evaluation.json" >/dev/null
 
 jq '.exceptions[0].advisoryId = "GHSA-wrong"' "$WORK/compliance/security/accepted-vulnerabilities.json" > "$WORK/changed.json"
@@ -140,7 +204,7 @@ expect_failure
 
 write_exception
 write_audit
-jq '.exceptions[0].expiresAt = "2026-01-01"' "$WORK/compliance/security/accepted-vulnerabilities.json" > "$WORK/changed.json"
+jq --arg expired "$EXPIRED_AT" '.exceptions[0].expiresAt = $expired' "$WORK/compliance/security/accepted-vulnerabilities.json" > "$WORK/changed.json"
 mv "$WORK/changed.json" "$WORK/compliance/security/accepted-vulnerabilities.json"
 expect_failure
 
@@ -150,6 +214,18 @@ jq '.exceptions[0].expiresAt = "not-a-date"' "$WORK/compliance/security/accepted
 mv "$WORK/changed.json" "$WORK/compliance/security/accepted-vulnerabilities.json"
 expect_failure
 
+write_exception
+write_audit
+jq '.exceptions[0].remediationIssue = "https://github.com/example/repo"' "$WORK/compliance/security/accepted-vulnerabilities.json" > "$WORK/changed.json"
+mv "$WORK/changed.json" "$WORK/compliance/security/accepted-vulnerabilities.json"
+expect_failure
+
+write_exception
+write_audit
+jq '.exceptions[0].compensatingControls = []' "$WORK/compliance/security/accepted-vulnerabilities.json" > "$WORK/changed.json"
+mv "$WORK/changed.json" "$WORK/compliance/security/accepted-vulnerabilities.json"
+expect_failure
+
 write_exception
 write_audit
 jq 'del(.exceptions[0].approvedAt)' "$WORK/compliance/security/accepted-vulnerabilities.json" > "$WORK/changed.json"
@@ -173,4 +249,33 @@ write_exception
 printf '{not-json}\n' > "$WORK/compliance/security/accepted-vulnerabilities.json"
 expect_failure
 
+write_meta_audit
+write_meta_lock
+rm -f "$WORK/compliance/security/accepted-vulnerabilities.json"
+expect_failure
+jq -e '
+  .summary.unresolved == 1 and
+  .unresolved[0].advisoryId == "GHSA-meta-chain" and
+  .unresolved[0].dependencyPath == "node_modules/@eslint/eslintrc/node_modules/brace-expansion" and
+  .unresolved[0].affectedFindings == ["@eslint/eslintrc", "brace-expansion", "eslint", "minimatch"]
+' "$WORK/dependency-risk-evaluation.json" >/dev/null
+
+write_meta_audit
+jq '.vulnerabilities.minimatch.via = ["missing-package"]' \
+  "$WORK/dependency-audit.json" > "$WORK/changed.json"
+mv "$WORK/changed.json" "$WORK/dependency-audit.json"
+expect_failure
+
+write_meta_audit
+jq '.vulnerabilities["brace-expansion"].via = ["eslint"]' \
+  "$WORK/dependency-audit.json" > "$WORK/changed.json"
+mv "$WORK/changed.json" "$WORK/dependency-audit.json"
+expect_failure
+
+write_meta_audit
+jq '.vulnerabilities["brace-expansion"].via = []' \
+  "$WORK/dependency-audit.json" > "$WORK/changed.json"
+mv "$WORK/changed.json" "$WORK/dependency-audit.json"
+expect_failure
+
 echo "evaluate-npm-audit: PASS"

package/sdlc/files/_common/scripts/markdown-table.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# Context-aware helpers for simple GitHub-flavoured Markdown tables.
+
+markdown_table_cell() {
+  local file="$1"
+  local key_value="$2"
+  local target_header="$3"
+  shift 3
+  local required_headers=("$@")
+
+  [ -f "$file" ] || return 1
+  awk \
+    -v key_value="$key_value" \
+    -v target_header="$target_header" \
+    -v required_headers="$(IFS=,; printf '%s' "${required_headers[*]}")" '
+      function clean(value) {
+        gsub(/^[[:space:]]+|[[:space:]]+$/, "", value)
+        gsub(/\001/, "\\|", value)
+        return value
+      }
+      function split_row(line, cells,    protected) {
+        protected=line
+        gsub(/\\\|/, "\001", protected)
+        return split(protected, cells, "|")
+      }
+      function header_matches(name, required,    options, count, i) {
+        count=split(required, options, "/")
+        for (i=1; i<=count; i++) {
+          if (tolower(name) == tolower(options[i])) return 1
+        }
+        return 0
+      }
+      BEGIN {
+        required_count=split(required_headers, required, ",")
+        active=0
+      }
+      /^\|/ {
+        count=split_row($0, cells)
+        candidate_target=0
+        candidate_key=0
+        matched=0
+        for (i=2; i<count; i++) {
+          name=clean(cells[i])
+          if (tolower(name) == tolower(target_header)) candidate_target=i
+          for (r=1; r<=required_count; r++) {
+            if (header_matches(name, required[r])) matched++
+          }
+          if (header_matches(name, required[1])) candidate_key=i
+        }
+        if (candidate_target && candidate_key && matched >= required_count) {
+          active=1
+          target_index=candidate_target
+          key_index=candidate_key
+          next
+        }
+        if (active && key_index && target_index && clean(cells[key_index]) == key_value) {
+          print clean(cells[target_index])
+          found=1
+          exit 0
+        }
+        next
+      }
+      { active=0; key_index=0; target_index=0 }
+      END { if (!found) exit 1 }
+    ' "$file"
+}
+
+markdown_table_column_index_for_row() {
+  local file="$1"
+  local key_value="$2"
+  local target_header="$3"
+  shift 3
+  local required_headers=("$@")
+
+  [ -f "$file" ] || return 1
+  awk \
+    -v key_value="$key_value" \
+    -v target_header="$target_header" \
+    -v required_headers="$(IFS=,; printf '%s' "${required_headers[*]}")" '
+      function clean(value) {
+        gsub(/^[[:space:]]+|[[:space:]]+$/, "", value)
+        return value
+      }
+      function split_row(line, cells,    protected) {
+        protected=line
+        gsub(/\\\|/, "\001", protected)
+        return split(protected, cells, "|")
+      }
+      function header_matches(name, required,    options, count, i) {
+        count=split(required, options, "/")
+        for (i=1; i<=count; i++) {
+          if (tolower(name) == tolower(options[i])) return 1
+        }
+        return 0
+      }
+      BEGIN { required_count=split(required_headers, required, ","); active=0 }
+      /^\|/ {
+        count=split_row($0, cells)
+        candidate_target=0
+        candidate_key=0
+        matched=0
+        for (i=2; i<count; i++) {
+          name=clean(cells[i])
+          if (tolower(name) == tolower(target_header)) candidate_target=i
+          for (r=1; r<=required_count; r++) {
+            if (header_matches(name, required[r])) matched++
+          }
+          if (header_matches(name, required[1])) candidate_key=i
+        }
+        if (candidate_target && candidate_key && matched >= required_count) {
+          active=1
+          target_index=candidate_target
+          key_index=candidate_key
+          next
+        }
+        if (active && clean(cells[key_index]) == key_value) {
+          print target_index
+          found=1
+          exit 0
+        }
+        next
+      }
+      { active=0 }
+      END { if (!found) exit 1 }
+    ' "$file"
+}

package/sdlc/files/_common/scripts/markdown-table.test.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=markdown-table.sh
+source "$SCRIPT_DIR/markdown-table.sh"
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+cat > "$WORK/RTM.md" <<'MARKDOWN'
+| Status | Description |
+| --- | --- |
+| Draft | This is not the requirements table |
+
+| REQ-ID | Issue | Risk | Evidence | Status |
+| --- | --- | --- | --- | --- |
+| REQ-100 | #100 | HIGH | report.md | TESTED - PENDING SIGN-OFF (note \| retained) |
+MARKDOWN
+
+[ "$(markdown_table_cell "$WORK/RTM.md" REQ-100 Status REQ-ID/ID Status)" = \
+  'TESTED - PENDING SIGN-OFF (note \| retained)' ]
+[ "$(markdown_table_cell "$WORK/RTM.md" REQ-100 Risk REQ-ID/ID Risk)" = "HIGH" ]
+[ "$(markdown_table_column_index_for_row "$WORK/RTM.md" REQ-100 Status REQ-ID/ID Status)" = "5" ]
+
+if markdown_table_cell "$WORK/RTM.md" REQ-404 Status REQ-ID/ID Status >/dev/null; then
+  echo "missing row unexpectedly matched" >&2
+  exit 1
+fi
+
+if markdown_table_cell "$WORK/RTM.md" Draft Status REQ-ID/ID Status >/dev/null; then
+  echo "legend row unexpectedly matched" >&2
+  exit 1
+fi
+
+echo "markdown table tests passed"

package/sdlc/files/_common/scripts/validate-compliance-artifacts.sh

@@ -12,6 +12,10 @@
 
 set -euo pipefail
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=markdown-table.sh
+source "$SCRIPT_DIR/markdown-table.sh"
+
 BASE_BRANCH="${1:-origin/main}"
 EXIT_CODE=0
 
@@ -53,6 +57,7 @@ find_first_match() {
   local match=""
   match=$(compgen -G "$pattern" | head -1 || true)
   [ -n "$match" ] && printf '%s' "$match"
+  return 0
 }
 
 require_bundled_fields() {
@@ -81,7 +86,9 @@ for REQ in $REQUIREMENTS; do
   # The `| $REQ ` pattern (leading pipe + trailing space) matches the
   # markdown table row used in RTM, so a substring elsewhere doesn't
   # accidentally satisfy it.
-  if ! grep -q "| $REQ " compliance/RTM.md 2>/dev/null; then
+  RTM_STATUS="$(markdown_table_cell \
+    compliance/RTM.md "$REQ" Status REQ-ID/ID Status 2>/dev/null || true)"
+  if [ -z "$RTM_STATUS" ]; then
     echo "  INFO: $REQ is referenced in commits but has no RTM row — skipping (forward-reference, not a tracked requirement for this release)"
     continue
   fi
@@ -187,12 +194,12 @@ for REQ in $REQUIREMENTS; do
   # by a successor (e.g. REQ-030 superseded by REQ-031). Without this
   # branch every PR with a commit referencing a SUPERSEDED REQ blocks
   # CI (#232).
-  if grep -q "$REQ" compliance/RTM.md 2>/dev/null; then
-    if grep "$REQ" compliance/RTM.md | grep -q "TESTED - PENDING SIGN-OFF"; then
+  if [ -n "$RTM_STATUS" ]; then
+    if printf '%s' "$RTM_STATUS" | grep -q "TESTED - PENDING SIGN-OFF"; then
       echo "  OK: RTM status is TESTED - PENDING SIGN-OFF"
-    elif grep "$REQ" compliance/RTM.md | grep -q "APPROVED"; then
+    elif printf '%s' "$RTM_STATUS" | grep -q "APPROVED"; then
       echo "  OK: RTM status is APPROVED"
-    elif grep "$REQ" compliance/RTM.md | grep -q "SUPERSEDED"; then
+    elif printf '%s' "$RTM_STATUS" | grep -q "SUPERSEDED"; then
       echo "  OK: RTM status is SUPERSEDED"
     else
       echo "  WARNING: RTM entry exists but status is not TESTED - PENDING SIGN-OFF"
@@ -371,7 +378,9 @@ for REQ in $REQUIREMENTS; do
   fi
 
   # Check implementation-plan.md for MEDIUM/HIGH risk (check RTM for risk level)
-  if grep "$REQ" compliance/RTM.md 2>/dev/null | grep -qiE 'MEDIUM|HIGH'; then
+  RTM_RISK="$(markdown_table_cell \
+    compliance/RTM.md "$REQ" Risk REQ-ID/ID Risk 2>/dev/null || true)"
+  if printf '%s' "$RTM_RISK" | grep -qiE 'MEDIUM|HIGH'; then
     if [ ! -f "compliance/evidence/$REQ/implementation-plan.md" ]; then
       echo "  ERROR: Implementation plan missing for MEDIUM/HIGH risk: compliance/evidence/$REQ/implementation-plan.md"
       EXIT_CODE=1

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

@@ -341,7 +341,7 @@ Reached from Phase 0 for non-tracked change-types. The skill drives this end-to-
    - **Post-merge-only CI (older generated workflows — `push: branches: [<integration>]` with no `pull_request:` trigger)** — say so explicitly in the LAST/NEXT sticky: _"no PR-time checks will fire; review + merge is the gate; CI runs post-merge on `$INTEGRATION_BRANCH`."_ Don't poll the PR for checks that won't arrive. The post-merge run (CI Pipeline + Compliance Evidence Upload on the integration branch) is the actual gate; address it via fix-forward if it fails.
 
    Either way, never bypass a gate (no `--no-verify`, no `--admin` merge of a red required check); the only difference is **where** you wait for the gate to fire — before merge vs. after merge.
-8. **Guide review -> merge.** A human still reviews the PR. Merge only after all required checks are terminal green on the current PR head SHA; queued, running, stale, cancelled, unexpectedly skipped, or failed checks are not green. There is no portal release approval, UAT four-eyes, Production gate, or standalone close-out on the normal lightweight path.
+8. **Guide review -> merge.** A human still reviews the PR. Merge only after all required checks are terminal green on the current PR head SHA; queued, running, stale, cancelled, unexpectedly skipped, or failed checks are not green. If GitHub leaves a stale projection, use the repository's **Recover Required Checks** workflow: dry-run first, then apply only to rerun a resolvable completed Actions run on the same SHA. When GitHub never created the required suite, push an auditable empty commit to the PR branch and verify the new SHA; never fabricate status or bypass protection. There is no portal release approval, UAT four-eyes, Production gate, or standalone close-out on the normal lightweight path.
 9. **Record the correct release meaning.** A housekeeping push produces at most a bare-date release (`vYYYY.MM.DD`) that is integration/history, not an active approval by default. It waits on `$INTEGRATION_BRANCH` until a later tracked release explicitly absorbs it through the required bundled-changes markdown/JSON manifest and portal lineage. Never infer that an unrelated hotfix or mandatory back-merge belongs to the only pending REQ. A submitted REQ bundle is frozen approval scope; changing it returns that REQ to evidence compilation and UAT resubmission. A doc-only push attaches documents to the existing `REQ-XXX` release.
 10. **Standalone exception.** Only when housekeeping cannot reasonably wait for the next tracked release may the skill prepare a standalone promotion. It must state `Standalone housekeeping promotion` and why in the release PR, add `compliance/standalone-housekeeping/STANDALONE-HOUSEKEEPING-vYYYY.MM.DD.json` with `schemaVersion: 1`, the exact derived bare-date version, `releaseMode: standalone_housekeeping`, and a specific reason. It must obtain terminal-green CI and PR review. The installed release-scope check validates the declaration before merge; post-deploy uploads it as release-ticket evidence and changes the portal row to standalone housekeeping. Use portal approval only if project policy explicitly opts in. If the installed workflow cannot implement that policy, halt and keep the change on the normal integration path.