/ci-audit

description: Stack-aware CI gap detection — audits a project's GitHub Actions workflows against its declared tech stack and files issues for missing config validation checks
argument-hint: "[--repo <prefix>] [--dry-run]"
install: extras

<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios --> <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

/ci-audit — Stack-Aware CI Gap Detection

> **Skill names**: `{FORGE_SKILL_PREFIX}` is `forgedock:` (plugin install) or empty (`install.sh`), resolved once per run by `commands/work-on.md` § Skill Name Resolution. If the skill is not found under either name, STOP and report "skill not found" — never run the phase inline.

**Input**: $ARGUMENTS

You are the CI hygiene auditor. Given a project's declared tech stack (from `forge.yaml`), determine what config validation tools exist for each stack component and audit whether the project's GitHub Actions workflows include those validation steps. File GitHub issues for any gaps found.

This command enforces ForgeDock's separation-of-concerns principle:

| Layer | What runs | Tokens | Example | |-------|-----------|--------|---------| | **CI (automated)** | Deterministic tool validators | Zero | `traefik validate`, `nginx -t`, `kubectl --dry-run` | | **ForgeDock (autonomous)** | Reasoning about architecture, logic, security | Yes | "Is this timeout chain coherent?", "Does this wiring match the deploy script?" | | **ForgeDock CI hygiene** | Audit that CI has the right checks for the stack | Once | "Project uses Traefik v3 but CI has no `traefik validate` step → file issue" |

Config validation runs in CI (zero tokens). ForgeDock's role is to ensure the right CI checks exist — not to run them itself. <!-- Added: forge#1104 -->

This command is designed to be run:

• **Once after project setup** to establish CI hygiene baseline
• **After stack changes** (adding Traefik, upgrading K8s, adopting Terraform)
• **As part of `/autopilot`** periodic review cycle
• **After a production incident** caused by a structurally invalid config

This is NOT a PR review — it does not approve or block. It creates issues for each CI gap found.

**Agent model policy**: `model: "{DEFAULT_MODEL}"` — resolved from forge.yaml `agents.default_model`, else "sonnet" (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154. **NEVER use plan mode (EnterPlanMode).**

---

Config Preamble

Before executing any phase, read `forge.yaml` to resolve project references:

GH_REPO=$(yq '.project.owner + "/" + .project.repo' forge.yaml 2>/dev/null)
GH_FLAG="-R ${GH_REPO}"
REPO_PATH=$(yq '.paths.root' forge.yaml 2>/dev/null || echo ".")
TECH_STACK=$(yq '.review.tech_stack // ""' forge.yaml 2>/dev/null || echo "")
TOOL_VERSIONS=$(yq '.review.tool_versions // {}' forge.yaml 2>/dev/null || echo '{}')

**Optional `forge.yaml` fields used by this command**:

review:
  tech_stack: "Traefik v3, nginx 1.25, Terraform 1.6, Kubernetes 1.28"  # Free-form stack description
  tool_versions:                                                            # Structured version declarations
    traefik: "3"
    nginx: "1.25"
    terraform: "1.6"
    kubernetes: "1.28"
    docker_compose: "2"

# Optional: override which CI workflows to audit (default: all files in .github/workflows/)
ci_audit:
  workflow_paths:
    - ".github/workflows/ci.yml"
    - ".github/workflows/deploy-production.yml"
  dry_run: false   # When true: print findings without creating issues

If `forge.yaml` is missing: stop and tell the user to run `npx forgedock init` to generate it.

---

Phase 1: Discover Stack Components

1A: Parse declared stack

Extract stack components from `forge.yaml → review.tech_stack` (free-form) and `forge.yaml → review.tool_versions` (structured).

echo "=== Stack from forge.yaml ==="
echo "TECH_STACK: $TECH_STACK"
echo "TOOL_VERSIONS: $TOOL_VERSIONS"

**Parse `TECH_STACK` (free-form text) for known tool names**:

Scan the `TECH_STACK` string for these tool keywords (case-insensitive):

| Keyword pattern | Tool | Validator(s) | |-----------------|------|-------------| | `traefik` | Traefik | `traefik validate`, `traefik healthcheck` | | `nginx` | nginx | `nginx -t`, `nginx -T` | | `kubernetes\|k8s\|kubectl` | Kubernetes | `kubectl apply --dry-run=client`, `kubeval`, `kustomize build \| kubectl apply --dry-run=client` | | `terraform` | Terraform | `terraform validate`, `terraform plan`, `tflint` | | `helm` | Helm | `helm lint`, `helm template \| kubectl apply --dry-run=client` | | `docker.compose\|docker-compose` | Docker Compose | `docker compose config` | | `pydantic\|fastapi` | Python (Pydantic) | `python -c "from app.main import app"` (startup validation) | | `ansible` | Ansible | `ansible-playbook --syntax-check`, `ansible-lint` | | `pulumi` | Pulumi | `pulumi preview --non-interactive` |

**Parse `TOOL_VERSIONS` (structured)** — for each key present, add to the detected components map with its version.

**Version-aware validator selection**:

The correct validator depends on the tool version. Version mismatches (e.g., using Traefik v2 flags on a v3 install) produce misleading results.

| Tool | Version | Preferred validator | Notes | |------|---------|---------------------|-------| | Traefik | v2.x | `traefik validate --configFile=traefik.yml` | v2 flag syntax | | Traefik | v3.x | `traefik validate` (no `--configFile` flag needed in v3) | v3 changed CLI | | nginx | any | `nginx -t -c /etc/nginx/nginx.conf` | Standard across versions | | Terraform | ≥0.13 | `terraform validate` (in-directory) | Requires `terraform init` first | | Terraform | all | `tflint` (linter, catches schema errors `terraform validate` misses) | Complementary | | Kubernetes | any | `kubectl apply --dry-run=client -f k8s/` | Client-side, no cluster needed | | Helm | ≥3.x | `helm lint ./chart` | v3 only (v2 deprecated) | | Docker Compose | v2 | `docker