@metasession.co/devaudit-cli 0.3.12 → 0.3.13

package/sdlc/files/_common/scripts/render-test-cycles.sh

@@ -0,0 +1,227 @@
+#!/usr/bin/env bash
+# render-test-cycles.sh — Render release test cycles as markdown tables.
+#
+# Usage:
+#   bash scripts/render-test-cycles.sh path/to/release-journey.json
+#
+# Supported inputs:
+#   1. First-class cycle payloads with `.cycles[]`
+#   2. Legacy grouped-evidence payloads with one of:
+#        - `.legacyCycles[]`
+#        - `.testCycleGroups[]`
+#        - `.evidenceGroups[]`
+#
+# Output:
+#   Markdown suitable for inclusion under `## Test Cycles` in
+#   `compliance/evidence/REQ-XXX/test-execution-summary.md`.
+
+set -euo pipefail
+
+INPUT_JSON="${1:-}"
+
+if [ -z "$INPUT_JSON" ] || [ ! -f "$INPUT_JSON" ]; then
+  echo "Usage: $0 <release-journey.json>" >&2
+  exit 2
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "Error: jq is required." >&2
+  exit 1
+fi
+
+stage_label() {
+  case "$1" in
+    1) printf '1 plan' ;;
+    2) printf '2 implement_test' ;;
+    3) printf '3 compile_evidence' ;;
+    4) printf '4 uat_review' ;;
+    5) printf '5 production' ;;
+    *) printf '%s unknown' "${1:-?}" ;;
+  esac
+}
+
+format_date() {
+  local value="$1"
+  if [ -z "$value" ] || [ "$value" = "null" ]; then
+    printf 'Unknown'
+  else
+    printf '%s' "$value" | sed -E 's/T/ /; s/Z$//; s/[.][0-9]+$//'
+  fi
+}
+
+render_first_class_cycles() {
+  echo "| Source Release | SDLC Stage | Cycle | Kind | Outcome | Workflow / Run | Related Evidence | Incident / Remediation | Date |"
+  echo "| --- | --- | --- | --- | --- | --- | --- | --- | --- |"
+
+  declare -A COUNTS=()
+  local rows
+  rows="$(
+    jq -r '
+      (.cycles // [])
+      | sort_by(.sourceRelease // "", .sdlcStage // 0, .startedAt // "", .completedAt // "", .cycleKind // "")
+      | .[]
+      | {
+          sourceRelease: (.sourceRelease // "Unknown"),
+          stageCode: ((.sdlcStage // 0) | tostring),
+          kind: (.cycleKind // "unknown"),
+          outcome: (.outcome // "unknown"),
+          workflow: (
+            if (.workflowUrl // "") != "" then
+              "[" + ((.workflowName // "Workflow")) + "](" + .workflowUrl + ")"
+            else
+              (.workflowName // "Manual")
+            end
+          ),
+          runMeta: (
+            [
+              (if (.externalRunId // "") != "" then "run " + .externalRunId else empty end),
+              (if (.externalRunAttempt // null) != null then "attempt " + (.externalRunAttempt | tostring) else empty end)
+            ]
+            | map(select(length > 0))
+            | join(", ")
+          ),
+          evidence: (
+            (.relatedEvidence // [])
+            | map(.displayName // .fileName // .name // .evidenceType // empty)
+            | map(select(length > 0))
+            | join(", ")
+          ),
+          incident: (
+            [
+              (.incidentReference // empty),
+              (.remediationReference // empty),
+              (.outcomeReason // empty)
+            ]
+            | map(select(length > 0))
+            | join("; ")
+          ),
+          date: (.completedAt // .startedAt // "")
+        }
+      | @base64
+    ' "$INPUT_JSON"
+  )"
+
+  if [ -z "$rows" ]; then
+    echo "| Unknown | Unknown | None | unknown | unknown | No cycle records returned | None | None | Unknown |"
+    echo
+    echo "**Final assessment:** No first-class cycle records were returned by the portal."
+    return 0
+  fi
+
+  while IFS= read -r row_b64; do
+    [ -n "$row_b64" ] || continue
+    local source_release stage_code kind outcome workflow run_meta evidence incident date
+    source_release="$(printf '%s' "$row_b64" | base64 -d | jq -r '.sourceRelease')"
+    stage_code="$(printf '%s' "$row_b64" | base64 -d | jq -r '.stageCode')"
+    kind="$(printf '%s' "$row_b64" | base64 -d | jq -r '.kind')"
+    outcome="$(printf '%s' "$row_b64" | base64 -d | jq -r '.outcome')"
+    workflow="$(printf '%s' "$row_b64" | base64 -d | jq -r '.workflow')"
+    run_meta="$(printf '%s' "$row_b64" | base64 -d | jq -r '.runMeta')"
+    evidence="$(printf '%s' "$row_b64" | base64 -d | jq -r '.evidence')"
+    incident="$(printf '%s' "$row_b64" | base64 -d | jq -r '.incident')"
+    date="$(printf '%s' "$row_b64" | base64 -d | jq -r '.date')"
+    [ -n "$source_release" ] || continue
+    local group_key cycle_ordinal workflow_cell evidence_cell incident_cell
+    group_key="${source_release}|${stage_code}"
+    COUNTS["$group_key"]=$(( ${COUNTS["$group_key"]:-0} + 1 ))
+    cycle_ordinal="#${COUNTS[$group_key]}"
+    workflow_cell="$workflow"
+    if [ -n "$run_meta" ]; then
+      workflow_cell="${workflow_cell} (${run_meta})"
+    fi
+    evidence_cell="${evidence:-None}"
+    incident_cell="${incident:-None}"
+    printf '| %s | %s | %s | %s | %s | %s | %s | %s | %s |\n' \
+      "$source_release" \
+      "$(stage_label "$stage_code")" \
+      "$cycle_ordinal" \
+      "$kind" \
+      "$outcome" \
+      "$workflow_cell" \
+      "$evidence_cell" \
+      "$incident_cell" \
+      "$(format_date "$date")"
+  done <<<"$rows"
+
+  echo
+  echo "**Final assessment:** Stage-scoped cycle numbering is authoritative from first-class portal cycle records."
+}
+
+render_legacy_cycles() {
+  echo "> Legacy portal fallback — first-class cycle records unavailable; grouped by uploaded evidence \`testCycleId\`."
+  echo
+  echo "| Source Release | SDLC Stage | Cycle | Kind | Outcome | Workflow / Run | Related Evidence | Incident / Remediation | Date |"
+  echo "| --- | --- | --- | --- | --- | --- | --- | --- | --- |"
+
+  local rows
+  rows="$(
+    jq -r '
+      (.legacyCycles // .testCycleGroups // .evidenceGroups // [])
+      | .[]
+      | {
+          sourceRelease: (.sourceRelease // "Legacy grouped evidence"),
+          stageLabel: (.sdlcStageLabel // "legacy grouping"),
+          cycleId: (.testCycleId // .cycleId // "unknown"),
+          kind: (.cycleKind // "legacy"),
+          outcome: (.outcome // "unknown"),
+          workflow: (
+            if (.workflowUrl // "") != "" then
+              "[" + ((.workflowName // "Workflow")) + "](" + .workflowUrl + ")"
+            else
+              (.workflowName // "Legacy grouping")
+            end
+          ),
+          evidence: (
+            (.relatedEvidence // .evidence // [])
+            | map(.displayName // .fileName // .name // .evidenceType // .path // empty)
+            | map(select(length > 0))
+            | join(", ")
+          ),
+          incident: (.incidentReference // .notes // "Legacy fallback"),
+          date: (.date // .createdAt // "")
+        }
+      | @base64
+    ' "$INPUT_JSON"
+  )"
+
+  if [ -z "$rows" ]; then
+    echo "| Legacy grouped evidence | legacy grouping | unknown | legacy | unknown | Legacy grouping | None | Legacy fallback | Unknown |"
+    echo
+    echo "**Final assessment:** Legacy fallback used, but no grouped evidence records were returned."
+    return 0
+  fi
+
+  while IFS= read -r row_b64; do
+    [ -n "$row_b64" ] || continue
+    local source_release stage_label_value cycle_id kind outcome workflow evidence incident date
+    source_release="$(printf '%s' "$row_b64" | base64 -d | jq -r '.sourceRelease')"
+    stage_label_value="$(printf '%s' "$row_b64" | base64 -d | jq -r '.stageLabel')"
+    cycle_id="$(printf '%s' "$row_b64" | base64 -d | jq -r '.cycleId')"
+    kind="$(printf '%s' "$row_b64" | base64 -d | jq -r '.kind')"
+    outcome="$(printf '%s' "$row_b64" | base64 -d | jq -r '.outcome')"
+    workflow="$(printf '%s' "$row_b64" | base64 -d | jq -r '.workflow')"
+    evidence="$(printf '%s' "$row_b64" | base64 -d | jq -r '.evidence')"
+    incident="$(printf '%s' "$row_b64" | base64 -d | jq -r '.incident')"
+    date="$(printf '%s' "$row_b64" | base64 -d | jq -r '.date')"
+    [ -n "$cycle_id" ] || continue
+    printf '| %s | %s | %s | %s | %s | %s | %s | %s | %s |\n' \
+      "$source_release" \
+      "$stage_label_value" \
+      "$cycle_id" \
+      "$kind" \
+      "$outcome" \
+      "$workflow" \
+      "${evidence:-None}" \
+      "${incident:-Legacy fallback}" \
+      "$(format_date "$date")"
+  done <<<"$rows"
+
+  echo
+  echo "**Final assessment:** Legacy grouping was used because the portal did not expose first-class cycle records."
+}
+
+if jq -e '((.cycles // []) | length) > 0' "$INPUT_JSON" >/dev/null 2>&1; then
+  render_first_class_cycles
+else
+  render_legacy_cycles
+fi

package/sdlc/files/_common/scripts/render-test-cycles.test.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# render-test-cycles.test.sh — Tests for render-test-cycles.sh.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HELPER="$SCRIPT_DIR/render-test-cycles.sh"
+[ -x "$HELPER" ] || chmod +x "$HELPER"
+
+PASS=0
+FAIL=0
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+assert_contains() {
+  local desc="$1"
+  local needle="$2"
+  local haystack="$3"
+  if printf '%s' "$haystack" | grep -Fq "$needle"; then
+    echo "  PASS: $desc"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $desc"
+    echo "    missing: $needle"
+    echo "$haystack" | sed 's/^/    /'
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "=== render-test-cycles.sh tests ==="
+
+cat > "$WORK/first-class.json" <<'EOF'
+{
+  "cycles": [
+    {
+      "sourceRelease": "REQ-091",
+      "sdlcStage": 2,
+      "cycleKind": "quality_gate",
+      "outcome": "failed",
+      "workflowName": "Quality Gates",
+      "workflowUrl": "https://github.com/example/repo/actions/runs/100",
+      "externalRunId": "100",
+      "externalRunAttempt": 1,
+      "relatedEvidence": [{ "displayName": "quality-gates.json" }],
+      "incidentReference": "#501",
+      "startedAt": "2026-07-15T08:00:00Z",
+      "completedAt": "2026-07-15T08:05:00Z"
+    },
+    {
+      "sourceRelease": "REQ-091",
+      "sdlcStage": 2,
+      "cycleKind": "quality_gate",
+      "outcome": "passed",
+      "workflowName": "Quality Gates",
+      "workflowUrl": "https://github.com/example/repo/actions/runs/101",
+      "externalRunId": "101",
+      "externalRunAttempt": 2,
+      "relatedEvidence": [{ "displayName": "quality-gates-rerun.json" }],
+      "remediationReference": "PR #507",
+      "startedAt": "2026-07-15T09:00:00Z",
+      "completedAt": "2026-07-15T09:07:00Z"
+    },
+    {
+      "sourceRelease": "REQ-090",
+      "sdlcStage": 4,
+      "cycleKind": "uat",
+      "outcome": "passed",
+      "workflowName": "UAT Review",
+      "workflowUrl": "https://portal.example/releases/req-090",
+      "relatedEvidence": [{ "displayName": "uat-checklist.md" }],
+      "startedAt": "2026-07-15T10:00:00Z",
+      "completedAt": "2026-07-15T10:12:00Z"
+    }
+  ]
+}
+EOF
+
+OUTPUT="$(bash "$HELPER" "$WORK/first-class.json")"
+assert_contains "first-class heading rendered" "| Source Release | SDLC Stage | Cycle | Kind | Outcome | Workflow / Run | Related Evidence | Incident / Remediation | Date |" "$OUTPUT"
+assert_contains "stage label rendered" "| REQ-091 | 2 implement_test | #1 | quality_gate | failed | [Quality Gates](https://github.com/example/repo/actions/runs/100) (run 100, attempt 1) | quality-gates.json | #501 | 2026-07-15 08:05:00 |" "$OUTPUT"
+assert_contains "ordinal increments within source release + stage" "| REQ-091 | 2 implement_test | #2 | quality_gate | passed | [Quality Gates](https://github.com/example/repo/actions/runs/101) (run 101, attempt 2) | quality-gates-rerun.json | PR #507 | 2026-07-15 09:07:00 |" "$OUTPUT"
+assert_contains "different release/stage restarts numbering" "| REQ-090 | 4 uat_review | #1 | uat | passed | [UAT Review](https://portal.example/releases/req-090) | uat-checklist.md | None | 2026-07-15 10:12:00 |" "$OUTPUT"
+assert_contains "first-class final assessment rendered" "Stage-scoped cycle numbering is authoritative from first-class portal cycle records." "$OUTPUT"
+
+cat > "$WORK/legacy.json" <<'EOF'
+{
+  "legacyCycles": [
+    {
+      "testCycleId": "287654321",
+      "workflowName": "Legacy E2E",
+      "workflowUrl": "https://github.com/example/repo/actions/runs/287654321",
+      "relatedEvidence": [{ "fileName": "e2e-results.json" }, { "fileName": "screenshot.png" }],
+      "notes": "grouped from uploaded evidence only",
+      "date": "2026-07-14T18:30:00Z"
+    }
+  ]
+}
+EOF
+
+OUTPUT="$(bash "$HELPER" "$WORK/legacy.json")"
+assert_contains "legacy fallback note rendered" "Legacy portal fallback — first-class cycle records unavailable; grouped by uploaded evidence" "$OUTPUT"
+assert_contains "legacy row rendered" "| Legacy grouped evidence | legacy grouping | 287654321 | legacy | unknown | [Legacy E2E](https://github.com/example/repo/actions/runs/287654321) | e2e-results.json, screenshot.png | grouped from uploaded evidence only | 2026-07-14 18:30:00 |" "$OUTPUT"
+assert_contains "legacy final assessment rendered" "Legacy grouping was used because the portal did not expose first-class cycle records." "$OUTPUT"
+
+echo
+echo "=== render-test-cycles.test.sh: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]

package/sdlc/files/_common/scripts/report-test-cycle.sh

@@ -0,0 +1,344 @@
+#!/usr/bin/env bash
+# report-test-cycle.sh — Producer helper for first-class cycle lifecycle events.
+#
+# Usage:
+#   ./scripts/report-test-cycle.sh start|complete [flags...]
+#
+# Required flags:
+#   --project-slug <slug>
+#   --release <version>
+#   --sdlc-stage <1-5>
+#   --environment <ci|uat|production>
+#   --cycle-kind <kind>
+#   --idempotency-key <key>
+#
+# Optional flags:
+#   --provider <name>              Defaults to github_actions
+#   --external-run-id <id>
+#   --external-run-attempt <n>
+#   --external-job-id <id>
+#   --commit-sha <sha>
+#   --branch <name>
+#   --workflow-name <name>
+#   --workflow-url <url>
+#   --started-at <iso8601>         Defaults to current UTC on `start`
+#   --completed-at <iso8601>       Defaults to current UTC on `complete`
+#   --outcome <value>              Terminal outcome for `complete`
+#   --outcome-reason <text>
+#   --incident-reference <text>
+#   --output-file <path>           Writes key=value outputs for callers
+#
+# Output keys:
+#   cycle_supported=true|false
+#   cycle_release_id=<uuid-if-resolved>
+#   cycle_release_version=<exact-version-if-resolved>
+#   cycle_record_id=<uuid-if-created-or-updated>
+#   cycle_idempotency_key=<input-key>
+#   cycle_started_at=<iso8601-if-known>
+#   cycle_completed_at=<iso8601-if-known>
+#   cycle_endpoint=<start|complete|reconcile-if-used>
+
+set -euo pipefail
+
+usage() {
+  echo "Usage: $0 start|complete [flags...]"
+  exit 1
+}
+
+[ "$#" -ge 1 ] || usage
+MODE="$1"
+shift
+
+case "$MODE" in
+  start|complete) ;;
+  *) usage ;;
+esac
+
+PROJECT_SLUG=""
+RELEASE_VERSION=""
+SDLC_STAGE=""
+ENVIRONMENT=""
+CYCLE_KIND=""
+PROVIDER="github_actions"
+EXTERNAL_RUN_ID=""
+EXTERNAL_RUN_ATTEMPT=""
+EXTERNAL_JOB_ID=""
+COMMIT_SHA=""
+BRANCH=""
+WORKFLOW_NAME=""
+WORKFLOW_URL=""
+IDEMPOTENCY_KEY=""
+STARTED_AT=""
+COMPLETED_AT=""
+OUTCOME=""
+OUTCOME_REASON=""
+INCIDENT_REFERENCE=""
+OUTPUT_FILE=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --project-slug) PROJECT_SLUG="$2"; shift 2 ;;
+    --release) RELEASE_VERSION="$2"; shift 2 ;;
+    --sdlc-stage) SDLC_STAGE="$2"; shift 2 ;;
+    --environment) ENVIRONMENT="$2"; shift 2 ;;
+    --cycle-kind) CYCLE_KIND="$2"; shift 2 ;;
+    --provider) PROVIDER="$2"; shift 2 ;;
+    --external-run-id) EXTERNAL_RUN_ID="$2"; shift 2 ;;
+    --external-run-attempt) EXTERNAL_RUN_ATTEMPT="$2"; shift 2 ;;
+    --external-job-id) EXTERNAL_JOB_ID="$2"; shift 2 ;;
+    --commit-sha) COMMIT_SHA="$2"; shift 2 ;;
+    --branch) BRANCH="$2"; shift 2 ;;
+    --workflow-name) WORKFLOW_NAME="$2"; shift 2 ;;
+    --workflow-url) WORKFLOW_URL="$2"; shift 2 ;;
+    --idempotency-key) IDEMPOTENCY_KEY="$2"; shift 2 ;;
+    --started-at) STARTED_AT="$2"; shift 2 ;;
+    --completed-at) COMPLETED_AT="$2"; shift 2 ;;
+    --outcome) OUTCOME="$2"; shift 2 ;;
+    --outcome-reason) OUTCOME_REASON="$2"; shift 2 ;;
+    --incident-reference) INCIDENT_REFERENCE="$2"; shift 2 ;;
+    --output-file) OUTPUT_FILE="$2"; shift 2 ;;
+    *) echo "Unknown option: $1"; exit 1 ;;
+  esac
+done
+
+require_arg() {
+  local value="$1" name="$2"
+  if [ -z "$value" ]; then
+    echo "Error: ${name} is required" >&2
+    exit 1
+  fi
+}
+
+require_arg "$PROJECT_SLUG" "--project-slug"
+require_arg "$RELEASE_VERSION" "--release"
+require_arg "$SDLC_STAGE" "--sdlc-stage"
+require_arg "$ENVIRONMENT" "--environment"
+require_arg "$CYCLE_KIND" "--cycle-kind"
+require_arg "$IDEMPOTENCY_KEY" "--idempotency-key"
+
+if [ -z "${DEVAUDIT_BASE_URL:-}" ]; then
+  echo "Error: DEVAUDIT_BASE_URL environment variable is required" >&2
+  exit 1
+fi
+if [ -z "${DEVAUDIT_API_KEY:-}" ]; then
+  echo "Error: DEVAUDIT_API_KEY environment variable is required" >&2
+  exit 1
+fi
+
+if ! [[ "$SDLC_STAGE" =~ ^[1-5]$ ]]; then
+  echo "Error: --sdlc-stage must be an integer 1-5 (got: $SDLC_STAGE)" >&2
+  exit 1
+fi
+
+case "$ENVIRONMENT" in
+  ci|uat|production) ;;
+  *)
+    echo "Error: --environment must be one of ci, uat, production" >&2
+    exit 1
+    ;;
+esac
+
+if [ "$MODE" = "complete" ] && [ -z "$OUTCOME" ]; then
+  echo "Error: --outcome is required for complete" >&2
+  exit 1
+fi
+
+case "$OUTCOME" in
+  ""|passed|failed|cancelled|skipped|timed_out|action_required|unknown) ;;
+  *)
+    echo "Error: --outcome must be a terminal cycle outcome" >&2
+    exit 1
+    ;;
+esac
+
+iso_now() {
+  date -u +"%Y-%m-%dT%H:%M:%SZ"
+}
+
+[ -n "$STARTED_AT" ] || STARTED_AT="$(iso_now)"
+if [ "$MODE" = "complete" ] && [ -z "$COMPLETED_AT" ]; then
+  COMPLETED_AT="$(iso_now)"
+fi
+
+DEVAUDIT_BASE_URL="${DEVAUDIT_BASE_URL%/}"
+MAX_TIME_SECONDS=${UPLOAD_MAX_TIME_SECONDS:-120}
+CONNECT_TIMEOUT_SECONDS=${UPLOAD_CONNECT_TIMEOUT_SECONDS:-10}
+
+write_output() {
+  local key="$1" value="$2"
+  if [ -n "$OUTPUT_FILE" ]; then
+    printf '%s=%s\n' "$key" "$value" >> "$OUTPUT_FILE"
+  fi
+}
+
+emit_fallback() {
+  local release_id="${1:-}" resolved_version="${2:-}"
+  write_output cycle_supported false
+  write_output cycle_release_id "$release_id"
+  write_output cycle_release_version "$resolved_version"
+  write_output cycle_record_id ""
+  write_output cycle_idempotency_key "$IDEMPOTENCY_KEY"
+  write_output cycle_started_at "$STARTED_AT"
+  write_output cycle_completed_at "$COMPLETED_AT"
+  write_output cycle_endpoint "$MODE"
+}
+
+uri_escape() {
+  jq -rn --arg v "$1" '$v|@uri'
+}
+
+resolve_release_exact() {
+  local encoded_release encoded_slug url body code latest_id latest_version
+  encoded_release=$(uri_escape "$RELEASE_VERSION")
+  encoded_slug=$(uri_escape "$PROJECT_SLUG")
+  url="${DEVAUDIT_BASE_URL}/api/ci/releases/resolve?projectSlug=${encoded_slug}&versionPrefix=${encoded_release}"
+  body=$(mktemp)
+  code=$(curl -sS -o "$body" -w "%{http_code}" \
+    -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
+    --connect-timeout "$CONNECT_TIMEOUT_SECONDS" \
+    --max-time "$MAX_TIME_SECONDS" \
+    "$url")
+  if [ "$code" -lt 200 ] || [ "$code" -ge 300 ]; then
+    echo "::warning::Cycle lifecycle skipped: could not resolve release ${RELEASE_VERSION} (HTTP ${code})." >&2
+    rm -f "$body"
+    emit_fallback "" ""
+    return 1
+  fi
+  latest_id=$(jq -r '.latest.id // empty' "$body" 2>/dev/null || true)
+  latest_version=$(jq -r '.latest.version // empty' "$body" 2>/dev/null || true)
+  rm -f "$body"
+  if [ -z "$latest_id" ] || [ "$latest_version" != "$RELEASE_VERSION" ]; then
+    echo "::warning::Cycle lifecycle skipped: release resolve for ${RELEASE_VERSION} was empty or ambiguous (latest=${latest_version:-none})." >&2
+    emit_fallback "$latest_id" "$latest_version"
+    return 1
+  fi
+  RELEASE_ID="$latest_id"
+  RESOLVED_RELEASE_VERSION="$latest_version"
+  write_output cycle_release_id "$RELEASE_ID"
+  write_output cycle_release_version "$RESOLVED_RELEASE_VERSION"
+  return 0
+}
+
+build_payload() {
+  local mode="$1"
+  if [ -n "$EXTERNAL_RUN_ATTEMPT" ]; then
+    EXTERNAL_RUN_ATTEMPT_JSON="$EXTERNAL_RUN_ATTEMPT"
+  else
+    EXTERNAL_RUN_ATTEMPT_JSON="null"
+  fi
+  jq -n \
+    --argjson schemaVersion 1 \
+    --arg mode "$mode" \
+    --arg sdlcStage "$SDLC_STAGE" \
+    --arg environment "$ENVIRONMENT" \
+    --arg cycleKind "$CYCLE_KIND" \
+    --arg provider "$PROVIDER" \
+    --arg externalRunId "$EXTERNAL_RUN_ID" \
+    --argjson externalRunAttempt "$EXTERNAL_RUN_ATTEMPT_JSON" \
+    --arg externalJobId "$EXTERNAL_JOB_ID" \
+    --arg idempotencyKey "$IDEMPOTENCY_KEY" \
+    --arg startedAt "$STARTED_AT" \
+    --arg completedAt "$COMPLETED_AT" \
+    --arg outcome "$OUTCOME" \
+    --arg outcomeReason "$OUTCOME_REASON" \
+    --arg commitSha "$COMMIT_SHA" \
+    --arg branch "$BRANCH" \
+    --arg workflowName "$WORKFLOW_NAME" \
+    --arg workflowUrl "$WORKFLOW_URL" \
+    --arg incidentReference "$INCIDENT_REFERENCE" \
+    '
+      {
+        schemaVersion: $schemaVersion,
+        sdlcStage: ($sdlcStage | tonumber),
+        environment: $environment,
+        cycleKind: $cycleKind,
+        provider: $provider,
+        externalRunId: ($externalRunId | if . == "" then null else . end),
+        externalRunAttempt: $externalRunAttempt,
+        externalJobId: ($externalJobId | if . == "" then null else . end),
+        idempotencyKey: $idempotencyKey,
+        startedAt: $startedAt,
+        commitSha: ($commitSha | if . == "" then null else . end),
+        branch: ($branch | if . == "" then null else . end),
+        workflowName: ($workflowName | if . == "" then null else . end),
+        workflowUrl: ($workflowUrl | if . == "" then null else . end),
+        incidentReference: ($incidentReference | if . == "" then null else . end)
+      }
+      + (if $mode == "start"
+          then { outcome: "running" }
+          else {
+            completedAt: $completedAt,
+            outcome: $outcome,
+            outcomeReason: ($outcomeReason | if . == "" then null else . end)
+          }
+        end)
+    '
+}
+
+post_cycle_event() {
+  local endpoint="$1" payload="$2" body code
+  body=$(mktemp)
+  code=$(curl -sS -o "$body" -w "%{http_code}" \
+    -X POST \
+    -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
+    -H "Content-Type: application/json" \
+    --connect-timeout "$CONNECT_TIMEOUT_SECONDS" \
+    --max-time "$MAX_TIME_SECONDS" \
+    "${DEVAUDIT_BASE_URL}/api/ci/releases/${RELEASE_ID}/cycles/${endpoint}" \
+    -d "$payload")
+  CYCLE_HTTP_CODE="$code"
+  CYCLE_RESPONSE_BODY_FILE="$body"
+}
+
+handle_unavailable_endpoint() {
+  case "$CYCLE_HTTP_CODE" in
+    404|405|501)
+      echo "::warning::Cycle lifecycle endpoint ${MODE} unavailable on this portal (HTTP ${CYCLE_HTTP_CODE}); continuing in legacy testCycleId mode." >&2
+      emit_fallback "$RELEASE_ID" "$RESOLVED_RELEASE_VERSION"
+      rm -f "$CYCLE_RESPONSE_BODY_FILE"
+      return 0
+      ;;
+  esac
+  return 1
+}
+
+if ! resolve_release_exact; then
+  exit 0
+fi
+
+PAYLOAD="$(build_payload "$MODE")"
+ENDPOINT="$MODE"
+post_cycle_event "$ENDPOINT" "$PAYLOAD"
+
+if [ "$MODE" = "complete" ] && [ "$CYCLE_HTTP_CODE" -eq 400 ]; then
+  if grep -q 'different terminal outcome' "$CYCLE_RESPONSE_BODY_FILE" 2>/dev/null; then
+    ENDPOINT="reconcile"
+    post_cycle_event "$ENDPOINT" "$PAYLOAD"
+  fi
+fi
+
+if [ "$CYCLE_HTTP_CODE" -lt 200 ] || [ "$CYCLE_HTTP_CODE" -ge 300 ]; then
+  if handle_unavailable_endpoint; then
+    exit 0
+  fi
+  BODY_EXCERPT="$(head -c 500 "$CYCLE_RESPONSE_BODY_FILE" 2>/dev/null || true)"
+  rm -f "$CYCLE_RESPONSE_BODY_FILE"
+  echo "Error: cycle ${ENDPOINT} failed for ${RELEASE_VERSION} (HTTP ${CYCLE_HTTP_CODE})${BODY_EXCERPT:+ — ${BODY_EXCERPT}}" >&2
+  exit 1
+fi
+
+CYCLE_RECORD_ID=$(jq -r '.id // empty' "$CYCLE_RESPONSE_BODY_FILE" 2>/dev/null || true)
+rm -f "$CYCLE_RESPONSE_BODY_FILE"
+if [ -z "$CYCLE_RECORD_ID" ]; then
+  echo "Error: cycle ${ENDPOINT} succeeded but response did not include an id" >&2
+  exit 1
+fi
+
+write_output cycle_supported true
+write_output cycle_record_id "$CYCLE_RECORD_ID"
+write_output cycle_idempotency_key "$IDEMPOTENCY_KEY"
+write_output cycle_started_at "$STARTED_AT"
+write_output cycle_completed_at "$COMPLETED_AT"
+write_output cycle_endpoint "$ENDPOINT"
+
+echo "Cycle ${ENDPOINT} recorded for ${RELEASE_VERSION}: ${CYCLE_RECORD_ID}"