appsec 0.1.0__tar.gz

appsec-0.1.0/.claude/skills/cicd/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: cicd
+description: >
+  appsec's CI/CD lane, layered on `agex pr`. Delegates lint / open /
+  read / reply / delta to agex; adds two steward extensions — `status`
+  (SonarCloud quality gate + hotspots + unresolved-thread tally) and
+  `await` (read --wait + status with non-zero exit on Sonar ERROR or
+  unresolved threads). Use when: creating PRs in appsec, handling
+  review feedback, polling CI status, or the user says "create PR",
+  "review comments", "address feedback", "resolve threads". Renamed
+  from `pr-review` in steward 0.7.0; rebased on agex in 0.12.0.
+  Vendored from steward; see docs/skill-sources.md for divergence notes.
+---
+
+# CI/CD — Steward edition
+
+`agex pr` (in `agentculture/agex-cli`) is the upstream for the
+five core PR-lifecycle verbs — `lint`, `open`, `read`, `reply`,
+`delta`. Steward used to vendor parallel scripts for each; in 0.12.0
+those vendored copies were dropped in favor of delegating to `agex`.
+What's left in this skill is **the steward-specific gating layer**:
+
+- `status` — SonarCloud quality gate, OPEN issues, hotspots, deploy
+  preview URL, unresolved-inline-thread tally.
+- `await` — composes `agex pr read --wait` with `status` and gates on
+  Sonar `ERROR` / unresolved threads. The single command to run after
+  pushing a fix when you want "wake me when this PR is triage-able."
+
+Those two are the steward unique surface today. They're filed as a
+feature ask upstream
+([agex-cli#41](https://github.com/agentculture/agex-cli/issues/41));
+once they land they migrate out of this skill.
+
+The workflow is encapsulated in `scripts/workflow.sh` — follow that
+(or call `agex pr` directly).
+
+## Prerequisites
+
+Hard requirements: `agex` (>=0.1), `gh` (GitHub CLI), `jq`, `bash`,
+`python3` (stdlib only), `curl` (used by `pr-status.sh`).
+
+Install agex once:
+
+```bash
+uv tool install agex-cli   # or: pip install --user agex-cli
+```
+
+Soft requirement: `PyYAML` is needed **only for suffix mode** of the
+sibling `agent-config` skill, where it parses Culture's server
+manifest. Every `cicd` script works without it; suffix mode prints a
+clear install hint when invoked without it.
+
+Per-machine paths (sibling-project layout) live in
+`.claude/skills.local.yaml`; see the committed `.example` for the
+schema. `agex pr delta` reads the same file.
+
+## How to run
+
+`scripts/workflow.sh` is the entry point. Subcommands:
+
+| Command | What it does |
+|---------|--------------|
+| `workflow.sh lint` | `agex pr lint --exit-on-violation` — portability + alignment-trigger check. |
+| `workflow.sh open [gh-flags]` | `agex pr open --delayed-read`. Creates the PR, then polls 180s for an initial briefing. `--title TITLE` required; body via `--body-file PATH` or stdin. |
+| `workflow.sh read [PR] [--wait N]` | `agex pr read`. One-shot briefing (CI checks, SonarCloud gate + new issues, all comments, next-step footer). Pass `--wait N` to poll up to N seconds for required reviewers. |
+| `workflow.sh reply <PR>` | `agex pr reply <PR>` — batch JSONL replies (stdin) + thread resolve. agex auto-signs from `culture.yaml`. |
+| `workflow.sh delta` | `agex pr delta` — sibling alignment dump. |
+| `workflow.sh status <PR>` | **Steward extension.** `pr-status.sh` — Sonar gate, OPEN issues, hotspots, unresolved-thread breakdown, deploy preview URL. Authoritative gate for `await`. |
+| `workflow.sh await <PR>` | **Steward extension.** `agex pr read --wait` then `status`. Exits non-zero on Sonar ERROR or unresolved threads. Tunables: `STEWARD_PR_AWAIT_WAIT` (default 1800s passed to `--wait`), `STEWARD_PR_AWAIT_SECONDS` (legacy fixed pre-sleep, deprecated). |
+| `workflow.sh help` | Print the list. |
+
+You can also call `agex pr <verb>` directly — `workflow.sh` is a
+typing-saver around the same verbs. The steward `status` and `await`
+extensions only have shell entry points.
+
+The vendored single-comment helper `pr-reply.sh` (plus its
+`_resolve-nick.sh` dependency) is still shipped — pinned by
+`tests/test_pr_reply_signature.py` and `tests/test_resolve_nick.py`,
+and useful when a one-off reply doesn't merit batch JSONL. It is not
+called by `workflow.sh` anymore. The vendored `portability-lint.sh`
+is also still shipped — `steward doctor`'s portability check runs it
+directly against target repos. Both are scheduled for follow-up
+migration to agex.
+
+## Long waits (background polling)
+
+`agex pr read --wait N` polls in-session for up to N seconds. The
+Anthropic prompt cache has a 5-minute TTL; sleeping past it burns
+context every cache miss. Two ways to drive the wait:
+
+- **Synchronous** — `workflow.sh await <PR>` after `gh pr create` /
+  `workflow.sh open`. Fine when readiness is expected within ~5
+  minutes.
+- **Asynchronous** — for longer waits, run `agex pr read --wait NNN`
+  inside a background subagent (Agent tool, `run_in_background: true`)
+  so the main session only pays the cache cost when readiness fires.
+  The subagent's only job is to invoke `agex pr read --wait` and echo
+  its headline back. The parent triages with `workflow.sh await`
+  when the notification arrives. The user can interrupt with
+  TaskStop.
+
+This pattern was originally borrowed from sibling repo
+[`agentculture/cfafi`](https://github.com/agentculture/cfafi)'s `poll`
+skill. The async guidance is also filed upstream
+([agex-cli#41](https://github.com/agentculture/agex-cli/issues/41)).
+
+## Conventions
+
+`agex pr` emits a **"Next step:"** footer at the end of every command
+that names the right next verb (the same chain `agex learn cicd`
+documents) — follow that rather than memorizing an order. `workflow.sh
+help` mirrors the verb table when you need the steward-flavored
+extensions (`status`, `await`) on top.
+
+Branch naming: `fix/<desc>`, `feat/<desc>`, `docs/<desc>`,
+`skill/<name>`. PR / comment signature: `- <nick> (Claude)`, where
+`<nick>` is resolved by `agex` from the agent's own `culture.yaml`
+(first agent's `suffix`), falling back to the git-repo basename. agex
+auto-appends the signature on `pr open` and `pr reply` only when the
+body isn't already signed.
+
+## Triage rules
+
+For every comment, decide **FIX** or **PUSHBACK** with reasoning.
+
+Default to **FIX** for: portability complaints (always valid for
+Steward — recurring bug class), test or doc requests, style nits
+aligned with workspace conventions.
+
+Default to **PUSHBACK** for: architecture opinions that conflict with
+workspace `CLAUDE.md` or the all-backends rule; greenfield
+false-positives (e.g. "add tests" before there's any source — defer
+to a later PR, don't refuse).
+
+### Alignment-delta rule
+
+If the PR touches `CLAUDE.md`, `culture.yaml`, or anything under
+`.claude/skills/`, run `workflow.sh delta` **before** declaring FIX or
+PUSHBACK on each comment. Note any sibling that needs a follow-up PR
+and mention it in your reply.
+
+## Greenfield-aware steps
+
+The lint and the workflow script are always-on. Stack-specific steps
+are conditional and currently no-op (greenfield repo):
+
+```bash
+[ -d tests ] && [ -f pyproject.toml ] && uv run pytest tests/ -x -q
+[ -f pyproject.toml ] && bump_version_per_project_convention   # see project README
+[ -f .markdownlint-cli2.yaml ] && markdownlint-cli2 "$(git diff --name-only --cached '*.md')"
+```
+
+Revisit each line as the corresponding stack element actually lands.
+A `pr lint --extra=tests,version,markdown` ask is filed upstream
+([agex-cli#41](https://github.com/agentculture/agex-cli/issues/41)).
+
+## Reply etiquette
+
+Every comment must get a reply — no silent fixes. `agex pr reply`
+includes thread-resolve by default. Reference the review-comment IDs
+in the fix-up commit message.
+
+The `status` extension queries SonarCloud directly (it predates the
+upstream Sonar integration in `agex pr read`). Both surfaces are
+trustworthy — `agex pr read` for display in the briefing, `status` for
+the gate. Steward isn't yet a registered mesh agent, so the
+post-merge IRC ping that Culture's `pr-review` includes is still
+skipped — that returns when Steward joins the mesh.

appsec-0.1.0/.claude/skills/cicd/scripts/_resolve-nick.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Resolve the agent's nick for GitHub message signing.
+# Order: first agent's `suffix` in <repo-root>/culture.yaml,
+# then basename of the git repo root.
+# Prints the nick to stdout. Always exits 0 — pr-reply.sh needs *some*
+# nick to sign with — but if a culture.yaml exists and we couldn't
+# extract a suffix from it, emits a stderr warning so a misconfigured
+# manifest doesn't silently mask itself behind the basename fallback.
+
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [[ -z "$repo_root" ]]; then
+    repo_root="$PWD"
+fi
+
+manifest="$repo_root/culture.yaml"
+
+if [[ -f "$manifest" ]]; then
+    if ! command -v python3 >/dev/null 2>&1; then
+        echo "_resolve-nick: python3 not found; cannot parse $manifest, falling back to repo basename" >&2
+    else
+        nick="$(python3 - "$manifest" <<'PY' 2>/dev/null || true
+import re, sys
+path = sys.argv[1]
+with open(path, encoding="utf-8") as f:
+    for raw in f:
+        line = raw.rstrip("\n")
+        m = re.match(r"^[\s-]*\s*suffix:\s*(\S+)", line)
+        if m:
+            print(m.group(1).strip("'\""))
+            break
+PY
+)"
+        if [[ -n "$nick" ]]; then
+            printf '%s\n' "$nick"
+            exit 0
+        fi
+        echo "_resolve-nick: $manifest exists but no suffix could be parsed; falling back to repo basename" >&2
+    fi
+fi
+
+basename "$repo_root"

appsec-0.1.0/.claude/skills/cicd/scripts/portability-lint.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# Portability lint: catch path leaks and per-user config dependencies in
+# committed docs/configs before they ship in a PR. Steward's recurring bug
+# class.
+#
+# Usage: portability-lint.sh [--all]
+#   default: lint files modified vs HEAD (staged + unstaged)
+#   --all:   lint all tracked files
+#
+# Exits 0 if clean, 1 if any leak is found.
+
+set -euo pipefail
+
+mode="${1:-diff}"
+case "$mode" in
+    --all) files=$(git ls-files -- ':(exclude)*.lock') ;;
+    diff|--diff) files=$(git diff --diff-filter=AMR --name-only HEAD -- ':(exclude)*.lock') ;;
+    *) echo "Usage: $(basename "$0") [--all]" >&2; exit 2 ;;
+esac
+
+[ -z "$files" ] && { echo "(no files to check)"; exit 0; }
+
+# ----- Check 1: hard-coded /home/<user>/... paths -----
+hits1=$(echo "$files" | xargs -r grep -nE '/home/[a-z][a-z0-9_-]+/' 2>/dev/null || true)
+
+# ----- Check 2: per-user dotfile *config* refs in committed docs/configs -----
+# Carve-outs (allowed, NOT flagged):
+#   - ~/.claude/skills/<x>/scripts/   vendored tool calls
+#   - ~/.culture/                     Culture mesh data this skill is supposed to read
+md_yaml=$(echo "$files" | grep -E '\.(md|ya?ml|toml|json|jsonc)$' || true)
+if [ -n "$md_yaml" ]; then
+    hits2=$(echo "$md_yaml" | xargs -r grep -nE '~/\.[A-Za-z]' 2>/dev/null \
+        | grep -vE '~/\.claude/skills/[^[:space:]"]+/scripts/' \
+        | grep -vE '~/\.culture/' \
+        || true)
+else
+    hits2=""
+fi
+
+fail=0
+if [ -n "$hits1" ]; then
+    echo "❌ Hard-coded /home/<user>/ paths:"
+    echo "$hits1" | sed 's/^/    /'
+    echo "   Fix: use ../sibling, repo URL, or \$WORKSPACE/sibling instead."
+    fail=1
+fi
+if [ -n "$hits2" ]; then
+    [ "$fail" -eq 1 ] && echo
+    echo "❌ Per-user ~/.<dotfile> config refs in committed doc/config:"
+    echo "$hits2" | sed 's/^/    /'
+    echo "   Allowed carve-outs: ~/.claude/skills/.../scripts/ (tool calls), ~/.culture/ (mesh data)."
+    echo "   Otherwise: commit a repo-local config or document a portable lookup."
+    fail=1
+fi
+
+[ "$fail" -eq 0 ] && echo "✓ portability lint clean ($(echo "$files" | wc -l | tr -d ' ') files checked)"
+exit $fail

appsec-0.1.0/.claude/skills/cicd/scripts/pr-reply.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Reply to a PR review comment, optionally resolve its thread.
+# Usage: pr-reply.sh [--repo OWNER/REPO] [--resolve] PR_NUMBER COMMENT_ID "body"
+
+REPO=""
+RESOLVE=false
+PRINT_BODY=false
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2 ;;
+        --resolve) RESOLVE=true; shift ;;
+        --print-body) PRINT_BODY=true; shift ;;
+        *) break ;;
+    esac
+done
+
+PR_NUMBER="${1:?Usage: pr-reply.sh [--repo OWNER/REPO] [--resolve] [--print-body] PR_NUMBER COMMENT_ID \"body\"}"
+COMMENT_ID="${2:?Missing COMMENT_ID}"
+BODY="${3:?Missing reply body}"
+
+if [[ "$PRINT_BODY" != true && -z "$REPO" ]]; then
+    REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
+fi
+
+# Sign with the agent's nick. Resolved per invocation so siblings that
+# vendor this skill pick up their own culture.yaml suffix automatically.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+NICK="$("$SCRIPT_DIR/_resolve-nick.sh")"
+SIG="- ${NICK} (Claude)"
+if ! printf '%s' "$BODY" | grep -qFx -- "$SIG"; then
+    BODY="${BODY}
+
+${SIG}"
+fi
+
+if [[ "$PRINT_BODY" == true ]]; then
+    printf '%s\n' "$BODY"
+    exit 0
+fi
+
+# Post reply
+REPLY_URL=$(gh api "repos/$REPO/pulls/$PR_NUMBER/comments/$COMMENT_ID/replies" \
+    -f body="$BODY" \
+    --jq '.html_url')
+echo "Replied: $REPLY_URL"
+
+# Resolve thread if requested
+if [[ "$RESOLVE" == true ]]; then
+    # Find the thread ID for this comment
+    THREAD_ID=$(gh api graphql -f query="
+    {
+      repository(owner: \"${REPO%%/*}\", name: \"${REPO##*/}\") {
+        pullRequest(number: $PR_NUMBER) {
+          reviewThreads(first: 100) {
+            nodes {
+              id
+              comments(first: 100) {
+                nodes { databaseId }
+              }
+            }
+          }
+        }
+      }
+    }" --jq ".data.repository.pullRequest.reviewThreads.nodes[] | select(any(.comments.nodes[]; .databaseId == $COMMENT_ID)) | .id")
+
+    if [[ -n "$THREAD_ID" ]]; then
+        RESOLVED=$(gh api graphql -f query="
+          mutation { resolveReviewThread(input: {threadId: \"$THREAD_ID\"}) { thread { isResolved } } }
+        " --jq '.data.resolveReviewThread.thread.isResolved')
+        echo "Resolved: $RESOLVED (thread $THREAD_ID)"
+    else
+        echo "Warning: could not find thread for comment $COMMENT_ID"
+    fi
+fi

appsec-0.1.0/.claude/skills/cicd/scripts/pr-status.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+# pr-status.sh — one-shot status overview for a Steward PR.
+#
+# Combines five things review feedback usually scatters across:
+#   1. PR state (open / merged / closed) + branch + author
+#   2. CI checks (build / lint / unit / sonarcloud / cf-pages / etc.)
+#   3. Review-bot pipeline status (Copilot, qodo, SonarCloud, Cloudflare)
+#   4. SonarCloud quality gate + open-issue count
+#   5. Inline-thread resolved-vs-unresolved tally
+#
+# Usage: scripts/pr-status.sh [--repo OWNER/REPO] [--sonar-key KEY] PR_NUMBER
+#
+# Defaults:
+#   --repo           auto-detected via `gh repo view`
+#   --sonar-key      derived from repo as `<owner>_<name>` (SonarCloud convention)
+#
+# Requires: gh, jq, curl, python3.
+
+set -euo pipefail
+
+REPO=""
+SONAR_KEY=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2 ;;
+        --sonar-key) SONAR_KEY="$2"; shift 2 ;;
+        *) break ;;
+    esac
+done
+
+PR_NUMBER="${1:?Usage: pr-status.sh [--repo OWNER/REPO] [--sonar-key KEY] PR_NUMBER}"
+
+if [[ -z "$REPO" ]]; then
+    REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
+fi
+# Sonar key precedence: explicit --sonar-key flag > SONAR_PROJECT_KEY env >
+# `<owner>_<repo>` derivation. Mirrors pr-comments.sh so SKILL.md's claim
+# that the env var works for both scripts is true.
+if [[ -z "$SONAR_KEY" ]]; then
+    SONAR_KEY="${SONAR_PROJECT_KEY:-${REPO%%/*}_${REPO##*/}}"
+fi
+
+# ── 1. PR header ──────────────────────────────────────────────────────────
+# appsec-divergence: pass --repo "$REPO" (upstream omits it — agentculture/steward#34)
+PR_JSON=$(gh pr view "$PR_NUMBER" --repo "$REPO" --json \
+    number,title,state,isDraft,mergedAt,mergedBy,baseRefName,headRefName,author,url)
+
+echo "════════════════════════════════════════════════════════════════════"
+echo "$PR_JSON" | jq -r '
+    "PR #\(.number) — \(.title)",
+    "  \(.url)",
+    "  Author:  \(.author.login)",
+    "  Branch:  \(.headRefName)  →  \(.baseRefName)",
+    "  State:   \(if .state == "MERGED" then "MERGED at \(.mergedAt) by \(.mergedBy.login)" elif .state == "OPEN" and .isDraft then "OPEN (draft)" else .state end)"
+'
+echo "════════════════════════════════════════════════════════════════════"
+
+# ── 2. CI checks ──────────────────────────────────────────────────────────
+echo
+echo "── CI checks ─────────────────────────────────────────────────────────"
+# `gh pr checks` exits non-zero when checks are still pending/failing.
+# We don't care about its exit code here; capture and pretty-print.
+# appsec-divergence: pass --repo "$REPO" (upstream omits it — agentculture/steward#34)
+CHECKS=$(gh pr checks "$PR_NUMBER" --repo "$REPO" 2>/dev/null || true)
+if [[ -z "$CHECKS" ]]; then
+    echo "  (no checks reported)"
+else
+    echo "$CHECKS" | awk -F'\t' '
+        {
+            name  = $1
+            state = $2
+            dur   = $3
+            sym   = "?"
+            if (state == "pass")            sym = "✅"
+            else if (state == "fail")       sym = "❌"
+            else if (state == "skipping")   sym = "⏭"
+            else if (state == "pending"  || state == "queued"   || state == "in_progress") sym = "…"
+            printf "  %s %-22s %-10s %s\n", sym, name, state, dur
+        }
+    '
+fi
+
+# ── 3. Review bots & comment pipeline ────────────────────────────────────
+echo
+echo "── Review pipeline ───────────────────────────────────────────────────"
+
+# Inline-thread tally via GraphQL (resolved vs unresolved).
+THREADS_JSON=$(gh api graphql -f query="
+{
+  repository(owner: \"${REPO%%/*}\", name: \"${REPO##*/}\") {
+    pullRequest(number: $PR_NUMBER) {
+      reviewThreads(first: 100) {
+        nodes { id isResolved comments(first: 1) { nodes { author { login } } } }
+      }
+    }
+  }
+}" --jq '.data.repository.pullRequest.reviewThreads.nodes')
+
+INLINE_TOTAL=$(echo "$THREADS_JSON" | jq 'length')
+INLINE_RESOLVED=$(echo "$THREADS_JSON" | jq '[.[] | select(.isResolved)] | length')
+INLINE_PENDING=$((INLINE_TOTAL - INLINE_RESOLVED))
+
+# Per-bot inline counts.
+COPILOT_INLINE=$(echo "$THREADS_JSON" | jq '[.[] | select((.comments.nodes[0].author.login // "") | startswith("Copilot"))] | length')
+QODO_INLINE=$(echo "$THREADS_JSON" | jq '[.[] | select((.comments.nodes[0].author.login // "") | startswith("qodo"))] | length')
+
+# Issue-level comments (qodo summary, sonarcloud quality-gate body, cf-pages preview, etc.).
+# Skip --paginate to avoid array concatenation; per_page=100 covers typical PRs.
+ISSUE=$(gh api "repos/$REPO/issues/$PR_NUMBER/comments?per_page=100")
+QODO_ISSUE=$(echo "$ISSUE" | jq '[.[] | select((.user.login // "") | startswith("qodo"))] | length')
+SONARQUBE_ISSUE=$(echo "$ISSUE" | jq '[.[] | select((.user.login // "") | startswith("sonarqubecloud"))] | length')
+CFPAGES_ISSUE=$(echo "$ISSUE" | jq '[.[] | select((.user.login // "") | test("cloudflare"))] | length')
+COPILOT_TOPLEVEL=$(gh api "repos/$REPO/pulls/$PR_NUMBER/reviews?per_page=100" \
+    | jq '[.[] | select((.user.login // "") | startswith("copilot")) | select((.body // "") != "")] | length')
+
+# Cloudflare deploy URL hidden in issue-comment bodies (look for pages.dev).
+CF_URL=$(echo "$ISSUE" | jq -r '[.[].body // "" | scan("https?://[a-z0-9.-]+\\.pages\\.dev[^\\s)\"<]*")] | first // ""')
+
+printf "  %-12s %s\n"  "Copilot"     "$([[ "$COPILOT_TOPLEVEL" -gt 0 || "$COPILOT_INLINE" -gt 0 ]] && echo "✅ overview×$COPILOT_TOPLEVEL, inline×$COPILOT_INLINE" || echo "— no posts yet")"
+printf "  %-12s %s\n"  "qodo"        "$([[ "$QODO_ISSUE" -gt 0 || "$QODO_INLINE" -gt 0 ]] && echo "✅ summary×$QODO_ISSUE, inline×$QODO_INLINE" || echo "— no posts yet")"
+printf "  %-12s %s\n"  "Cloudflare"  "$([[ -n "$CF_URL" ]] && echo "✅ $CF_URL" || ([[ "$CFPAGES_ISSUE" -gt 0 ]] && echo "✅ ($CFPAGES_ISSUE comments)" || echo "— no deploy preview"))"
+
+# ── 4. SonarCloud quality gate + open issues ─────────────────────────────
+SONAR_QG=$(curl -s "https://sonarcloud.io/api/qualitygates/project_status?projectKey=${SONAR_KEY}&pullRequest=${PR_NUMBER}")
+SONAR_QG_STATUS=$(echo "$SONAR_QG" | jq -r '.projectStatus.status // "UNKNOWN"')
+SONAR_OPEN=$(curl -s "https://sonarcloud.io/api/issues/search?componentKeys=${SONAR_KEY}&pullRequest=${PR_NUMBER}&statuses=OPEN,CONFIRMED&ps=1" \
+    | jq -r '.total // 0')
+SONAR_HOTSPOTS=$(curl -s "https://sonarcloud.io/api/hotspots/search?projectKey=${SONAR_KEY}&pullRequest=${PR_NUMBER}&status=TO_REVIEW&ps=1" \
+    | jq -r '.paging.total // 0')
+
+case "$SONAR_QG_STATUS" in
+    OK)    SONAR_SYM="✅" ;;
+    ERROR) SONAR_SYM="❌" ;;
+    WARN)  SONAR_SYM="⚠ " ;;
+    *)     SONAR_SYM="?" ;;
+esac
+printf "  %-12s %s Quality Gate %s, %d OPEN issue(s), %d hotspot(s)\n" \
+    "SonarCloud" "$SONAR_SYM" "$SONAR_QG_STATUS" "$SONAR_OPEN" "$SONAR_HOTSPOTS"
+
+# When SonarCloud has OPEN issues, list them — saves a follow-up curl.
+if [[ "$SONAR_OPEN" != "0" ]]; then
+    echo
+    echo "  SonarCloud OPEN issues:"
+    curl -s "https://sonarcloud.io/api/issues/search?componentKeys=${SONAR_KEY}&pullRequest=${PR_NUMBER}&statuses=OPEN,CONFIRMED&ps=20" \
+        | jq -r '.issues[] | "    • [\(.rule)] \(.component | sub("^[^:]+:"; ""))(:\(.line // "?")) (\(.severity)) — \(.message)"'
+fi
+
+# ── 5. Tally + summary ────────────────────────────────────────────────────
+echo
+echo "── Inline threads ────────────────────────────────────────────────────"
+printf "  Total: %d   Resolved: %d   Unresolved: %d\n" \
+    "$INLINE_TOTAL" "$INLINE_RESOLVED" "$INLINE_PENDING"
+
+if [[ "$INLINE_PENDING" -gt 0 ]]; then
+    echo
+    echo "  Unresolved threads:"
+    echo "$THREADS_JSON" | jq -r '
+        .[] | select(.isResolved == false) |
+        "    • \(.comments.nodes[0].author.login): thread \(.id)"
+    '
+fi
+
+echo
+echo "(For full comment bodies: agex pr read --agent claude-code $PR_NUMBER)"

appsec-0.1.0/.claude/skills/cicd/scripts/workflow.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Steward cicd workflow — thin layer over `agex pr` plus two steward
+# extensions (`status`, `await`) for SonarCloud gating and triage flow.
+#
+# Subcommands:
+#   lint                   `agex pr lint --exit-on-violation`. Same rules
+#                          steward used to vendor in portability-lint.sh
+#                          (which still ships for `steward doctor`).
+#   open  [gh-pr flags]    `agex pr open --delayed-read "$@"`. Creates the
+#                          PR, then polls 180s for an initial briefing.
+#                          Body via --body-file PATH or stdin; --title is
+#                          required.
+#   read  [PR] [--wait N]  `agex pr read "$@"`. One-shot briefing today;
+#                          pass --wait N to poll for reviewer readiness.
+#                          Covers what create-pr-and-wait / pr-comments /
+#                          wait-and-check / poll-readiness used to do.
+#   reply <PR>             `agex pr reply <PR>` (JSONL on stdin). agex
+#                          auto-signs from culture.yaml; same JSONL
+#                          shape as the old pr-batch.sh.
+#   delta                  `agex pr delta`. Sibling alignment dump.
+#
+#   status <PR>            Steward extension: pr-status.sh — SonarCloud
+#                          gate, OPEN issues, hotspots, unresolved
+#                          inline-thread tally, deploy-preview URL.
+#                          Source of truth for the `await` gate.
+#   await  <PR>            Steward extension: `read --wait` for the
+#                          briefing, then `status` for the gate. Exits
+#                          non-zero on SonarCloud ERROR or unresolved
+#                          threads. Tunables:
+#                            STEWARD_PR_AWAIT_WAIT (default 1800)
+#                              — seconds passed to `read --wait`.
+#                            STEWARD_PR_AWAIT_SECONDS (legacy)
+#                              — fixed pre-sleep, deprecated.
+#
+#   help                   print this message
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# agex's `--agent` flag accepts only claude-code|codex|copilot|acp. The
+# workspace culture.yaml convention is `backend: claude`, so we always
+# pass --agent explicitly to insulate steward from that naming gap.
+# Override via STEWARD_AGEX_AGENT if you're running under codex/copilot/acp.
+AGEX_AGENT="${STEWARD_AGEX_AGENT:-claude-code}"
+
+require_agex() {
+    if ! command -v agex >/dev/null 2>&1; then
+        echo "✗ agex not on PATH. Install agex-cli (>=0.1)." >&2
+        echo "  uv tool install agex-cli  # or pip install agex-cli" >&2
+        exit 2
+    fi
+}
+
+cmd="${1:-help}"
+shift || true
+
+case "$cmd" in
+    lint)
+        require_agex
+        exec agex pr lint --agent "$AGEX_AGENT" --exit-on-violation "$@"
+        ;;
+    open)
+        require_agex
+        exec agex pr open --agent "$AGEX_AGENT" --delayed-read "$@"
+        ;;
+    read)
+        require_agex
+        exec agex pr read --agent "$AGEX_AGENT" "$@"
+        ;;
+    reply)
+        require_agex
+        PR="${1:?Usage: workflow.sh reply <PR>  (JSONL on stdin)}"
+        exec agex pr reply --agent "$AGEX_AGENT" "$PR"
+        ;;
+    delta)
+        require_agex
+        exec agex pr delta --agent "$AGEX_AGENT" "$@"
+        ;;
+    status)
+        PR="${1:?Usage: workflow.sh status <PR>}"
+        exec bash "$SCRIPT_DIR/pr-status.sh" "$PR"
+        ;;
+    await)
+        require_agex
+        PR="${1:?Usage: workflow.sh await <PR>}"
+
+        # Legacy fixed-sleep escape hatch.
+        if [ -n "${STEWARD_PR_AWAIT_SECONDS:-}" ]; then
+            echo "warning: STEWARD_PR_AWAIT_SECONDS is deprecated; prefer STEWARD_PR_AWAIT_WAIT." >&2
+            echo "→ sleeping ${STEWARD_PR_AWAIT_SECONDS}s (legacy fixed-sleep) before agex pr read …" >&2
+            sleep "$STEWARD_PR_AWAIT_SECONDS"
+            WAIT_ARGS=()
+        else
+            WAIT="${STEWARD_PR_AWAIT_WAIT:-1800}"
+            WAIT_ARGS=(--wait "$WAIT")
+        fi
+
+        # 1. agex pr read --wait — readiness loop + briefing.
+        # Capture rc from the command itself (not from the negated test —
+        # `if ! cmd; then rc=$?` would store the if-test status, always 0
+        # in the failure branch, masking the real exit code).
+        echo "── agex pr read ──────────────────────────────────────────────────────" >&2
+        if agex pr read --agent "$AGEX_AGENT" "$PR" "${WAIT_ARGS[@]}"; then
+            READ_RC=0
+        else
+            READ_RC=$?
+        fi
+        if [ "$READ_RC" -ne 0 ]; then
+            echo "✗ agex pr read failed (exit $READ_RC)" >&2
+            exit "$READ_RC"
+        fi
+
+        # 2. pr-status.sh — authoritative gate (Sonar QG, unresolved threads).
+        echo >&2
+        echo "── pr-status ─────────────────────────────────────────────────────────" >&2
+        if STATUS_OUT=$(bash "$SCRIPT_DIR/pr-status.sh" "$PR" 2>&1); then
+            STATUS_RC=0
+        else
+            STATUS_RC=$?
+        fi
+        printf '%s\n' "$STATUS_OUT"
+        if [ "$STATUS_RC" -ne 0 ]; then
+            echo >&2
+            echo "✗ pr-status.sh failed (exit $STATUS_RC) — cannot determine PR state" >&2
+            exit "$STATUS_RC"
+        fi
+
+        # 3. Gate. Markers in pr-status.sh output:
+        #     "Quality Gate ERROR"          → Sonar fail
+        #     "Unresolved: N" with N>0      → unresolved threads
+        SONAR_FAIL=0
+        UNRESOLVED=0
+        if printf '%s\n' "$STATUS_OUT" | grep -qE 'Quality Gate ERROR'; then
+            SONAR_FAIL=1
+        fi
+        if PENDING=$(printf '%s\n' "$STATUS_OUT" | grep -oE 'Unresolved:[[:space:]]+[0-9]+' | grep -oE '[0-9]+$' | head -1); then
+            [ -n "${PENDING:-}" ] && [ "$PENDING" -gt 0 ] && UNRESOLVED=1
+        fi
+        if [ "$SONAR_FAIL" -eq 1 ] || [ "$UNRESOLVED" -eq 1 ]; then
+            echo >&2
+            [ "$SONAR_FAIL" -eq 1 ] && echo "✗ SonarCloud quality gate ERROR" >&2
+            [ "$UNRESOLVED" -eq 1 ] && echo "✗ ${PENDING} unresolved review thread(s)" >&2
+            exit 1
+        fi
+        echo >&2
+        echo "✓ no SonarCloud ERROR, no unresolved threads" >&2
+        ;;
+    help|--help|-h)
+        sed -n '4,38p' "${BASH_SOURCE[0]}" | sed 's/^# *//'
+        ;;
+    *)
+        echo "unknown subcommand: $cmd" >&2
+        echo "run '$(basename "$0") help' for usage." >&2
+        exit 2
+        ;;
+esac