ai-project-maintainer 0.3.1 → 0.4.1

package/ai-project-maintainer/references/tool-router.md

@@ -1,53 +1,53 @@
-# Tool Router
-
-Use this reference to choose checks dynamically. Run only tools that match the repository and the user's scope.
-
-## Selection Order
-
-1. Inspect the project with `scripts/probe-project.mjs`.
-2. Use installed Codex skills for security review when available.
-3. Use local CLI tools that are already installed.
-4. Use package-manager or containerized tools only when the repo already uses them or the user approves.
-5. Fall back to manual review with explicit coverage gaps.
-
-## Core Routing Table
-
-| Surface | Signals | Primary tools | Notes |
-| --- | --- | --- | --- |
-| Code security | Auth, API routes, serializers, file upload, HTTP clients, SQL construction, crypto | `codex-security`, Semgrep, CodeQL, Open Code Review | Prioritize changed files and dataflow into sinks. |
-| Secrets | `.env`, private keys, token-like config, CI variables, committed credentials | Gitleaks, Trivy secret scan | Do not print secret values. Report only location and type. |
-| Dependencies | Lockfiles, Docker images, SBOM, package manifests | Trivy, OSV-Scanner, native package audit | Separate reachable production risk from dev-only noise. |
-| Database migrations | `migrations/`, `db/migrate`, Prisma, Drizzle, Alembic, Flyway, Liquibase, raw SQL | Squawk, Atlas, Bytebase, pgroll, strong_migrations, gh-ost, pt-online-schema-change | Review lock behavior and rollback before correctness polish. |
-| IaC and cloud | Terraform, CloudFormation, Pulumi, Helm, Kubernetes YAML, Docker Compose | Checkov, Trivy config, Conftest/OPA, Kubescape | Focus on public exposure, IAM, network policy, privileged runtime, and secret mounts. |
-| Containers | Dockerfile, compose, image references, deploy manifests | Trivy image/config, Hadolint, Docker build checks | Check root user, privileged mode, writable filesystem, and unpinned base images. |
-| Kubernetes runtime | K8s manifests, `kubectl` context, incident request | k8sgpt, HolmesGPT, Kubescape, Falco, Cilium/Tetragon | Default to read-only commands. |
-| Web/API DAST | Staging URL explicitly provided by user | OWASP ZAP, Nuclei | Require explicit scope for active scans. Never infer internet targets. |
-| Incident response | Alerts, logs, metrics, traces, rollout history, deploys, migrations | HolmesGPT, OpenSRE, k8sgpt, kubectl, observability CLIs/APIs | Build a timeline before proposing fixes. |
-
-## Command Patterns
-
-Use these as patterns, adapting paths and package managers to the repo.
-
-```bash
-semgrep scan --config auto
-trivy fs --scanners vuln,secret,misconfig .
-gitleaks detect --source . --redact
-checkov -d .
-squawk path/to/migration.sql
-atlas migrate lint --dir "file://migrations"
-kubescape scan
-k8sgpt analyze
-```
-
-Use CodeQL when a CodeQL database or GitHub code scanning setup already exists, or when the user asks for deeper security analysis.
-
-## Missing Tool Handling
-
-When a useful tool is unavailable, write a short gap:
-
-```text
-Unavailable: squawk. Coverage gap: Postgres migration lock-risk linting was not run.
-Smallest next guardrail: add squawk to CI for changed `.sql` migration files.
-```
-
-Do not turn the review into an installation project unless the user asks for setup.
+# Tool Router
+
+Use this reference to choose checks dynamically. Run only tools that match the repository and the user's scope.
+
+## Selection Order
+
+1. Inspect the project with `scripts/probe-project.mjs`.
+2. Use installed Codex skills for security review when available.
+3. Use local CLI tools that are already installed.
+4. Use package-manager or containerized tools only when the repo already uses them or the user approves.
+5. Fall back to manual review with explicit coverage gaps.
+
+## Core Routing Table
+
+| Surface | Signals | Primary tools | Notes |
+| --- | --- | --- | --- |
+| Code security | Auth, API routes, serializers, file upload, HTTP clients, SQL construction, crypto | `codex-security`, Semgrep, CodeQL, Open Code Review | Prioritize changed files and dataflow into sinks. |
+| Secrets | `.env`, private keys, token-like config, CI variables, committed credentials | Gitleaks, Trivy secret scan | Do not print secret values. Report only location and type. |
+| Dependencies | Lockfiles, Docker images, SBOM, package manifests | Trivy, OSV-Scanner, native package audit | Separate reachable production risk from dev-only noise. |
+| Database migrations | `migrations/`, `db/migrate`, Prisma, Drizzle, Alembic, Flyway, Liquibase, raw SQL | Squawk, Atlas, Bytebase, pgroll, strong_migrations, gh-ost, pt-online-schema-change | Review lock behavior and rollback before correctness polish. |
+| IaC and cloud | Terraform, CloudFormation, Pulumi, Helm, Kubernetes YAML, Docker Compose | Checkov, Trivy config, Conftest/OPA, Kubescape | Focus on public exposure, IAM, network policy, privileged runtime, and secret mounts. |
+| Containers | Dockerfile, compose, image references, deploy manifests | Trivy image/config, Hadolint, Docker build checks | Check root user, privileged mode, writable filesystem, and unpinned base images. |
+| Kubernetes runtime | K8s manifests, `kubectl` context, incident request | k8sgpt, HolmesGPT, Kubescape, Falco, Cilium/Tetragon | Default to read-only commands. |
+| Web/API DAST | Staging URL explicitly provided by user | OWASP ZAP, Nuclei | Require explicit scope for active scans. Never infer internet targets. |
+| Incident response | Alerts, logs, metrics, traces, rollout history, deploys, migrations | HolmesGPT, OpenSRE, k8sgpt, kubectl, observability CLIs/APIs | Build a timeline before proposing fixes. |
+
+## Command Patterns
+
+Use these as patterns, adapting paths and package managers to the repo.
+
+```bash
+semgrep scan --config auto
+trivy fs --scanners vuln,secret,misconfig .
+gitleaks detect --source . --redact
+checkov -d .
+squawk path/to/migration.sql
+atlas migrate lint --dir "file://migrations"
+kubescape scan
+k8sgpt analyze
+```
+
+Use CodeQL when a CodeQL database or GitHub code scanning setup already exists, or when the user asks for deeper security analysis.
+
+## Missing Tool Handling
+
+When a useful tool is unavailable, write a short gap:
+
+```text
+Unavailable: squawk. Coverage gap: Postgres migration lock-risk linting was not run.
+Smallest next guardrail: add squawk to CI for changed `.sql` migration files.
+```
+
+Do not turn the review into an installation project unless the user asks for setup.

package/ai-project-maintainer/scripts/bootstrap-local-tools.ps1

@@ -1,109 +1,109 @@
-param(
-  [string[]]$Tools = @("gitleaks", "trivy", "squawk"),
-  [string]$InstallDir = "$env:USERPROFILE\.codex\security-tools",
-  [switch]$AddToPath
-)
-
-$ErrorActionPreference = "Stop"
-$binDir = Join-Path $InstallDir "bin"
-New-Item -ItemType Directory -Force -Path $binDir | Out-Null
-$requestedTools = @()
-foreach ($item in $Tools) {
-  $requestedTools += ($item -split ',' | ForEach-Object { $_.Trim() } | Where-Object { $_ })
-}
-
-function Write-Step($Message) {
-  Write-Host "==> $Message"
-}
-
-function Test-Command($Name) {
-  $null -ne (Get-Command $Name -ErrorAction SilentlyContinue)
-}
-
-function Get-Asset($Repo, [string[]]$Patterns) {
-  $release = Invoke-RestMethod -Headers @{ "User-Agent" = "ai-project-maintainer" } -Uri "https://api.github.com/repos/$Repo/releases/latest"
-  foreach ($pattern in $Patterns) {
-    $asset = $release.assets | Where-Object { $_.name -match $pattern -and $_.name -match '\.zip$' } | Select-Object -First 1
-    if ($asset) { return $asset }
-  }
-  throw "No Windows zip asset matched $($Patterns -join ', ') for $Repo"
-}
-
-function Install-FromGitHubZip($Name, $Repo, [string[]]$Patterns, $ExeName) {
-  if (Test-Command $ExeName) {
-    Write-Step "$Name already available on PATH"
-    return
-  }
-
-  $asset = Get-Asset -Repo $Repo -Patterns $Patterns
-  $tmp = Join-Path ([System.IO.Path]::GetTempPath()) ("$Name-" + [guid]::NewGuid())
-  $zip = Join-Path $tmp $asset.name
-  New-Item -ItemType Directory -Force -Path $tmp | Out-Null
-
-  Write-Step "Downloading $Name from $Repo ($($asset.name))"
-  Invoke-WebRequest -Headers @{ "User-Agent" = "ai-project-maintainer" } -Uri $asset.browser_download_url -OutFile $zip
-  Expand-Archive -LiteralPath $zip -DestinationPath $tmp -Force
-
-  $exe = Get-ChildItem -Path $tmp -Recurse -File -Filter "$ExeName.exe" | Select-Object -First 1
-  if (-not $exe) { throw "Downloaded $Name but could not find $ExeName.exe in archive" }
-
-  Copy-Item -LiteralPath $exe.FullName -Destination (Join-Path $binDir "$ExeName.exe") -Force
-  Write-Step "Installed $Name to $binDir"
-}
-
-function Install-WithUvTool($Name, $Package, $ExeName) {
-  if (Test-Command $ExeName) {
-    Write-Step "$Name already available on PATH"
-    return
-  }
-  if (-not (Test-Command "uv")) {
-    Write-Warning "uv is not installed; cannot install $Name locally. Install uv, Python, or Docker and rerun."
-    return
-  }
-  Write-Step "Installing $Name with uv tool install $Package"
-  & uv tool install $Package
-  if ($LASTEXITCODE -ne 0) {
-    throw "uv tool install $Package failed with exit code $LASTEXITCODE"
-  }
-}
-
-foreach ($tool in $requestedTools) {
-  try {
-    switch ($tool.ToLowerInvariant()) {
-      "gitleaks" {
-        Install-FromGitHubZip -Name "gitleaks" -Repo "gitleaks/gitleaks" -Patterns @("windows.*x64", "windows.*64") -ExeName "gitleaks"
-      }
-      "trivy" {
-        Install-FromGitHubZip -Name "trivy" -Repo "aquasecurity/trivy" -Patterns @("windows-64bit", "windows.*64") -ExeName "trivy"
-      }
-      "squawk" {
-        Install-FromGitHubZip -Name "squawk" -Repo "sbdchd/squawk" -Patterns @("windows.*x86_64", "windows.*amd64", "windows.*64") -ExeName "squawk"
-      }
-      "semgrep" {
-        Install-WithUvTool -Name "semgrep" -Package "semgrep" -ExeName "semgrep"
-      }
-      "checkov" {
-        Install-WithUvTool -Name "checkov" -Package "checkov" -ExeName "checkov"
-      }
-      default {
-        Write-Warning "Unknown local bootstrap tool '$tool'. Supported: gitleaks, trivy, squawk, semgrep, checkov."
-      }
-    }
-  } catch {
-    Write-Warning "Could not install ${tool}: $($_.Exception.Message)"
-  }
-}
-
-if ($AddToPath) {
-  $current = [Environment]::GetEnvironmentVariable("Path", "User")
-  $parts = $current -split ';' | Where-Object { $_ }
-  if ($parts -notcontains $binDir) {
-    [Environment]::SetEnvironmentVariable("Path", ($parts + $binDir -join ';'), "User")
-    Write-Step "Added $binDir to the user PATH. Restart terminals/Codex to pick it up."
-  } else {
-    Write-Step "$binDir is already in the user PATH"
-  }
-}
-
-Write-Step "Installed tools:"
-Get-ChildItem -File -LiteralPath $binDir | Select-Object Name,Length,LastWriteTime
+param(
+  [string[]]$Tools = @("gitleaks", "trivy", "squawk"),
+  [string]$InstallDir = "$env:USERPROFILE\.codex\security-tools",
+  [switch]$AddToPath
+)
+
+$ErrorActionPreference = "Stop"
+$binDir = Join-Path $InstallDir "bin"
+New-Item -ItemType Directory -Force -Path $binDir | Out-Null
+$requestedTools = @()
+foreach ($item in $Tools) {
+  $requestedTools += ($item -split ',' | ForEach-Object { $_.Trim() } | Where-Object { $_ })
+}
+
+function Write-Step($Message) {
+  Write-Host "==> $Message"
+}
+
+function Test-Command($Name) {
+  $null -ne (Get-Command $Name -ErrorAction SilentlyContinue)
+}
+
+function Get-Asset($Repo, [string[]]$Patterns) {
+  $release = Invoke-RestMethod -Headers @{ "User-Agent" = "ai-project-maintainer" } -Uri "https://api.github.com/repos/$Repo/releases/latest"
+  foreach ($pattern in $Patterns) {
+    $asset = $release.assets | Where-Object { $_.name -match $pattern -and $_.name -match '\.zip$' } | Select-Object -First 1
+    if ($asset) { return $asset }
+  }
+  throw "No Windows zip asset matched $($Patterns -join ', ') for $Repo"
+}
+
+function Install-FromGitHubZip($Name, $Repo, [string[]]$Patterns, $ExeName) {
+  if (Test-Command $ExeName) {
+    Write-Step "$Name already available on PATH"
+    return
+  }
+
+  $asset = Get-Asset -Repo $Repo -Patterns $Patterns
+  $tmp = Join-Path ([System.IO.Path]::GetTempPath()) ("$Name-" + [guid]::NewGuid())
+  $zip = Join-Path $tmp $asset.name
+  New-Item -ItemType Directory -Force -Path $tmp | Out-Null
+
+  Write-Step "Downloading $Name from $Repo ($($asset.name))"
+  Invoke-WebRequest -Headers @{ "User-Agent" = "ai-project-maintainer" } -Uri $asset.browser_download_url -OutFile $zip
+  Expand-Archive -LiteralPath $zip -DestinationPath $tmp -Force
+
+  $exe = Get-ChildItem -Path $tmp -Recurse -File -Filter "$ExeName.exe" | Select-Object -First 1
+  if (-not $exe) { throw "Downloaded $Name but could not find $ExeName.exe in archive" }
+
+  Copy-Item -LiteralPath $exe.FullName -Destination (Join-Path $binDir "$ExeName.exe") -Force
+  Write-Step "Installed $Name to $binDir"
+}
+
+function Install-WithUvTool($Name, $Package, $ExeName) {
+  if (Test-Command $ExeName) {
+    Write-Step "$Name already available on PATH"
+    return
+  }
+  if (-not (Test-Command "uv")) {
+    Write-Warning "uv is not installed; cannot install $Name locally. Install uv, Python, or Docker and rerun."
+    return
+  }
+  Write-Step "Installing $Name with uv tool install $Package"
+  & uv tool install $Package
+  if ($LASTEXITCODE -ne 0) {
+    throw "uv tool install $Package failed with exit code $LASTEXITCODE"
+  }
+}
+
+foreach ($tool in $requestedTools) {
+  try {
+    switch ($tool.ToLowerInvariant()) {
+      "gitleaks" {
+        Install-FromGitHubZip -Name "gitleaks" -Repo "gitleaks/gitleaks" -Patterns @("windows.*x64", "windows.*64") -ExeName "gitleaks"
+      }
+      "trivy" {
+        Install-FromGitHubZip -Name "trivy" -Repo "aquasecurity/trivy" -Patterns @("windows-64bit", "windows.*64") -ExeName "trivy"
+      }
+      "squawk" {
+        Install-FromGitHubZip -Name "squawk" -Repo "sbdchd/squawk" -Patterns @("windows.*x86_64", "windows.*amd64", "windows.*64") -ExeName "squawk"
+      }
+      "semgrep" {
+        Install-WithUvTool -Name "semgrep" -Package "semgrep" -ExeName "semgrep"
+      }
+      "checkov" {
+        Install-WithUvTool -Name "checkov" -Package "checkov" -ExeName "checkov"
+      }
+      default {
+        Write-Warning "Unknown local bootstrap tool '$tool'. Supported: gitleaks, trivy, squawk, semgrep, checkov."
+      }
+    }
+  } catch {
+    Write-Warning "Could not install ${tool}: $($_.Exception.Message)"
+  }
+}
+
+if ($AddToPath) {
+  $current = [Environment]::GetEnvironmentVariable("Path", "User")
+  $parts = $current -split ';' | Where-Object { $_ }
+  if ($parts -notcontains $binDir) {
+    [Environment]::SetEnvironmentVariable("Path", ($parts + $binDir -join ';'), "User")
+    Write-Step "Added $binDir to the user PATH. Restart terminals/Codex to pick it up."
+  } else {
+    Write-Step "$binDir is already in the user PATH"
+  }
+}
+
+Write-Step "Installed tools:"
+Get-ChildItem -File -LiteralPath $binDir | Select-Object Name,Length,LastWriteTime

package/ai-project-maintainer/scripts/ci-smoke-gate.mjs

@@ -1,26 +1,26 @@
-#!/usr/bin/env node
-import path from "node:path";
-import { runLocalGate } from "./run-local-gate.mjs";
-
-const projectRoot = path.resolve(process.argv[2] || process.cwd());
-const outputPath = process.argv[3] || "reports/security-report.json";
-
-const report = runLocalGate(projectRoot, {
-  noTests: true,
-  outputPath,
-  writeReports: true,
-  runnerOptions: {
-    envPath: "",
-  },
-});
-
-const summary = {
-  status: report.passed ? "PASS" : "FAIL",
-  blockers: report.summary?.blockers ?? 0,
-  warnings: report.summary?.warnings ?? 0,
-  coverageGaps: report.summary?.coverageGaps ?? 0,
-  outputPath,
-};
-
-console.log(JSON.stringify(summary, null, 2));
-process.exit(report.passed ? 0 : 1);
+#!/usr/bin/env node
+import path from "node:path";
+import { runLocalGate } from "./run-local-gate.mjs";
+
+const projectRoot = path.resolve(process.argv[2] || process.cwd());
+const outputPath = process.argv[3] || "reports/security-report.json";
+
+const report = runLocalGate(projectRoot, {
+  noTests: true,
+  outputPath,
+  writeReports: true,
+  runnerOptions: {
+    envPath: "",
+  },
+});
+
+const summary = {
+  status: report.passed ? "PASS" : "FAIL",
+  blockers: report.summary?.blockers ?? 0,
+  warnings: report.summary?.warnings ?? 0,
+  coverageGaps: report.summary?.coverageGaps ?? 0,
+  outputPath,
+};
+
+console.log(JSON.stringify(summary, null, 2));
+process.exit(report.passed ? 0 : 1);

package/ai-project-maintainer/scripts/init-project.mjs

@@ -34,7 +34,7 @@ warn_on:
 
 const exceptionsTemplate = `exceptions:
   - id: "example-dev-only-vuln"
-    check: "npm audit"
+    check: "package-audit"
     reason: "dev-only transitive dependency, not shipped"
     expires: "2026-09-01"
     owner: "repo-owner"
@@ -91,20 +91,32 @@ jobs:
             npm install
           fi
 
-      - name: Install security scanners
-        shell: bash
-        run: |
-          set -euo pipefail
-          mkdir -p "$HOME/.local/bin"
-          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
-          echo "$HOME/go/bin" >> "$GITHUB_PATH"
-          python -m pip install --user semgrep zizmor checkov
-          go install github.com/gitleaks/gitleaks/v8@latest
-          go install github.com/google/osv-scanner/cmd/osv-scanner@latest
-          go install github.com/rhysd/actionlint/cmd/actionlint@latest
-          go install github.com/anchore/syft/cmd/syft@latest
-          go install github.com/anchore/grype/cmd/grype@latest
-          curl -sSfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b "$HOME/.local/bin"
+      - name: Install security scanners
+        shell: bash
+        env:
+          GITLEAKS_VERSION: v8.30.0
+          TRIVY_VERSION: v0.71.2
+          SEMGREP_VERSION: 1.168.0
+          ZIZMOR_VERSION: 1.26.1
+          OSV_SCANNER_VERSION: v2.4.0
+          ACTIONLINT_VERSION: v1.7.12
+          SYFT_VERSION: v1.46.0
+          GRYPE_VERSION: v0.111.1
+          CHECKOV_VERSION: 3.3.2
+          SCORECARD_VERSION: v5.3.0
+        run: |
+          set -euo pipefail
+          mkdir -p "$HOME/.local/bin"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+          echo "$HOME/go/bin" >> "$GITHUB_PATH"
+          python -m pip install --user "semgrep==$SEMGREP_VERSION" "zizmor==$ZIZMOR_VERSION" "checkov==$CHECKOV_VERSION"
+          go install "github.com/zricethezav/gitleaks/v8@$GITLEAKS_VERSION"
+          go install "github.com/google/osv-scanner/v2/cmd/osv-scanner@$OSV_SCANNER_VERSION"
+          go install "github.com/rhysd/actionlint/cmd/actionlint@$ACTIONLINT_VERSION"
+          go install "github.com/anchore/syft/cmd/syft@$SYFT_VERSION"
+          go install "github.com/anchore/grype/cmd/grype@$GRYPE_VERSION"
+          go install "github.com/ossf/scorecard/v5@$SCORECARD_VERSION"
+          curl -sSfL "https://raw.githubusercontent.com/aquasecurity/trivy/$TRIVY_VERSION/contrib/install.sh" | sh -s -- -b "$HOME/.local/bin" "$TRIVY_VERSION"
 
       - name: Checkout AI Project Maintainer
         shell: bash
@@ -134,7 +146,7 @@ jobs:
 
       - name: Upload SARIF to code scanning
         if: always()
-        uses: github/codeql-action/upload-sarif@v3
+        uses: github/codeql-action/upload-sarif@v4
         with:
           sarif_file: reports/security-report.sarif
         continue-on-error: true

package/ai-project-maintainer/scripts/lib/check-registry.mjs

@@ -1,7 +1,7 @@
-import {
-  runCiSecurityChecks,
-  runDatabaseChecks,
-  runElectronChecks,
+import {
+  runActionlintChecks,
+  runDatabaseChecks,
+  runElectronChecks,
   runGrypeChecks,
   runIacChecks,
   runMegaLinterChecks,
@@ -12,9 +12,10 @@ import {
   runScorecardChecks,
   runSecretChecks,
   runSyftChecks,
-  runTestChecks,
-  runTrivyFilesystemChecks,
-} from "./checks.mjs";
+  runTestChecks,
+  runTrivyFilesystemChecks,
+  runZizmorChecks,
+} from "./checks.mjs";
 
 const builtinCheckRegistry = [
   { id: "tests", group: "tests", title: "Project tests and release scripts", requiredTools: ["npm", "pnpm", "yarn", "bun"], detect: (project) => Boolean(project.packageJson), run: ({ project, options }) => runTestChecks(project, options), defaultLevel: "block" },
@@ -25,8 +26,8 @@ const builtinCheckRegistry = [
   { id: "semgrep", group: "sast", title: "Semgrep static scan", requiredTools: ["semgrep"], detect: () => true, run: ({ project, options }) => runSastChecks(project, options), defaultLevel: "block" },
   { id: "syft", group: "supply-chain", title: "Syft SBOM", requiredTools: ["syft"], detect: () => true, run: ({ project, options }) => runSyftChecks(project, options), defaultLevel: "warn" },
   { id: "grype", group: "supply-chain", title: "Grype vulnerability scan", requiredTools: ["grype"], detect: () => true, run: ({ project, options }) => runGrypeChecks(project, options), defaultLevel: "warn" },
-  { id: "actionlint", group: "ci-security", title: "actionlint workflow lint", requiredTools: ["actionlint"], detect: (project) => (project.riskSurfaces?.ci || []).length > 0, run: ({ project, options }) => runCiSecurityChecks(project, options).filter((check) => check.checkId === "actionlint"), defaultLevel: "block" },
-  { id: "zizmor", group: "ci-security", title: "zizmor workflow security", requiredTools: ["zizmor"], detect: (project) => (project.riskSurfaces?.ci || []).length > 0, run: ({ project, options }) => runCiSecurityChecks(project, options).filter((check) => check.checkId === "zizmor"), defaultLevel: "warn" },
+  { id: "actionlint", group: "ci-security", title: "actionlint workflow lint", requiredTools: ["actionlint"], detect: (project) => (project.riskSurfaces?.ci || []).length > 0, run: ({ project, options }) => runActionlintChecks(project, options), defaultLevel: "block" },
+  { id: "zizmor", group: "ci-security", title: "zizmor workflow security", requiredTools: ["zizmor"], detect: (project) => (project.riskSurfaces?.ci || []).length > 0, run: ({ project, options }) => runZizmorChecks(project, options), defaultLevel: "warn" },
   { id: "checkov", group: "iac", title: "Checkov IaC scan", requiredTools: ["checkov"], detect: (project) => (project.riskSurfaces?.infra || []).length > 0, run: ({ project, options }) => runIacChecks(project, options).filter((check) => check.checkId === "checkov" || check.checkId === "trivy-config"), defaultLevel: "warn" },
   { id: "electron", group: "electron", title: "Electron baseline", requiredTools: [], detect: (project) => Boolean(project.electron?.detected), run: ({ project }) => runElectronChecks(project), defaultLevel: "block" },
   { id: "database", group: "database", title: "Database migration review", requiredTools: ["squawk"], detect: (project) => (project.riskSurfaces?.database || []).length > 0, run: ({ project, options }) => runDatabaseChecks(project, options), defaultLevel: "block" },

package/ai-project-maintainer/scripts/lib/checks.mjs

@@ -191,16 +191,28 @@ export function runGrypeChecks(project, options = {}) {
   ];
 }
 
-export function runCiSecurityChecks(project, options = {}) {
-  if (!(project.riskSurfaces?.ci || []).length) return [];
-  const runner = options.runnerOptions || {};
-  const actionlint = runCommand("actionlint", [], { ...runner, cwd: project.root, timeoutMs: 5 * 60 * 1000 });
-  const zizmor = runCommand("zizmor", [".github/workflows"], { ...runner, cwd: project.root, timeoutMs: 5 * 60 * 1000 });
-  return [
-    makeCheck("actionlint workflow lint", "ci-security", actionlint, actionlint.status === "fail", "GitHub Actions workflow syntax and common mistakes must be fixed.", { checkId: "actionlint" }),
-    makeCheck("zizmor workflow security", "ci-security", zizmor, zizmor.status === "fail", "High-risk GitHub Actions patterns must be fixed.", { checkId: "zizmor" }),
-  ];
-}
+export function runCiSecurityChecks(project, options = {}) {
+  if (!(project.riskSurfaces?.ci || []).length) return [];
+  return [...runActionlintChecks(project, options), ...runZizmorChecks(project, options)];
+}
+
+export function runActionlintChecks(project, options = {}) {
+  if (!(project.riskSurfaces?.ci || []).length) return [];
+  const runner = options.runnerOptions || {};
+  const actionlint = runCommand("actionlint", [], { ...runner, cwd: project.root, timeoutMs: 5 * 60 * 1000 });
+  return [
+    makeCheck("actionlint workflow lint", "ci-security", actionlint, actionlint.status === "fail", "GitHub Actions workflow syntax and common mistakes must be fixed.", { checkId: "actionlint" }),
+  ];
+}
+
+export function runZizmorChecks(project, options = {}) {
+  if (!(project.riskSurfaces?.ci || []).length) return [];
+  const runner = options.runnerOptions || {};
+  const zizmor = runCommand("zizmor", [".github/workflows"], { ...runner, cwd: project.root, timeoutMs: 5 * 60 * 1000 });
+  return [
+    makeCheck("zizmor workflow security", "ci-security", zizmor, zizmor.status === "fail", "High-risk GitHub Actions patterns must be fixed.", { checkId: "zizmor" }),
+  ];
+}
 
 export function runIacChecks(project, options = {}) {
   if (!(project.riskSurfaces?.infra || []).length) return [];

package/ai-project-maintainer/scripts/lib/command-runner.mjs

@@ -78,9 +78,23 @@ function spawnTarget(resolved, args) {
   };
 }
 
-export function runCommand(command, commandArgs = [], options = {}) {
-  const resolved = commandPath(command, options);
-  const commandText = [command, ...commandArgs].join(" ");
+export function runCommand(command, commandArgs = [], options = {}) {
+  if (typeof options.commandRunner === "function") {
+    const started = Date.now();
+    const commandText = [command, ...commandArgs].join(" ");
+    const result = options.commandRunner(command, commandArgs, options) || {};
+    return {
+      status: result.status || (result.code === 0 ? "pass" : "fail"),
+      command: result.command || commandText,
+      stdout: tail(result.stdout),
+      stderr: tail(result.stderr || result.error?.message || ""),
+      code: result.code ?? null,
+      durationMs: result.durationMs ?? Date.now() - started,
+    };
+  }
+
+  const resolved = commandPath(command, options);
+  const commandText = [command, ...commandArgs].join(" ");
   if (!resolved) {
     return {
       status: "missing",

package/ai-project-maintainer/scripts/lib/policy.mjs

@@ -101,10 +101,12 @@ export function validateExceptions(exceptions, now = new Date()) {
   return { valid, invalid };
 }
 
-function matchesException(check, exception) {
-  const target = String(exception.check || "").toLowerCase();
-  return target === String(check.name || "").toLowerCase() || target === String(check.group || "").toLowerCase();
-}
+function matchesException(check, exception) {
+  const target = String(exception.check || "").toLowerCase();
+  return [check.checkId, check.name, check.group]
+    .map((value) => String(value || "").toLowerCase())
+    .includes(target);
+}
 
 function policyKeyForCheck(check) {
   if (check.group === "tests") return "tests";