ai-project-maintainer 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xixifusi1213-gif
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# AI Project Maintainer
+
+![AI coding](https://img.shields.io/badge/built%20for-AI%20coding-111827)
+![Production audit](https://img.shields.io/badge/gate-production%20audit-0f766e)
+![Account free](https://img.shields.io/badge/default-account%20free-2563eb)
+[![CI](https://github.com/xixifusi1213-gif/ai-project-maintainer/actions/workflows/ci.yml/badge.svg)](https://github.com/xixifusi1213-gif/ai-project-maintainer/actions/workflows/ci.yml)
+
+**A production-readiness gate for AI-coded projects.**
+
+AI can generate code fast. This tool helps you keep the project maintainable after that: collect project evidence, plan the audit, run deterministic gates, let Codex fix blockers, and rerun until the release is defensible.
+
+[See the demo](docs/DEMO.md) · [中文演示](docs/DEMO.zh-CN.md) · [Production audit docs](docs/PRODUCTION-AUDIT.zh-CN.md)
+
+It is not another scanner wrapper. It turns AI coding maintenance into a repeatable loop:
+
+```text
+project profile -> audit plan -> local/CI gate -> evidence report -> AI fixes -> rerun
+```
+
+## Why This Exists
+
+AI coding makes it easy to ship code that looks complete but quietly misses production basics:
+
+- no business-flow tests
+- no secret/dependency/security gate
+- no database migration review
+- no release approval or rollback evidence
+- no monitoring/logging/alerting proof
+- no clear owner-approved exceptions
+
+`ai-project-maintainer` makes those gaps visible before they become production surprises.
+
+## The 3-Minute Flow
+
+```powershell
+# 1. Add local and CI guardrails
+npx ai-project-maintainer init "E:\my-project" --profile oss --ci github
+
+# 2. Create the production audit intake templates
+npx ai-project-maintainer init-audit "E:\my-project"
+
+# 3. Generate the project-specific audit plan
+npx ai-project-maintainer audit-plan "E:\my-project" --output reports/audit-plan.json
+
+# 4. Run the production gate
+npx ai-project-maintainer gate "E:\my-project" --production --strict --release --output reports/security-report.json
+```
+
+No npm publication is required for GitHub Actions. The generated workflow clones this repository and runs the Node scripts directly.
+
+## What It Checks
+
+| Area | Evidence produced |
+| --- | --- |
+| Tests and release scripts | test/E2E/build/dist failures |
+| Secrets | Gitleaks findings |
+| Dependencies | npm/pnpm/yarn audit, Trivy, OSV-Scanner |
+| Static security | Semgrep blocking findings |
+| Supply chain | Syft SBOM, Grype scan |
+| CI security | actionlint, zizmor |
+| IaC | Checkov, Trivy config |
+| Electron apps | dangerous webPreferences, preload/IPC/file-read risks |
+| Database projects | migration, backup, rollback, review-tool gaps |
+| Production readiness | monitoring, logs, metrics, alerts, release approval, incident runbook |
+
+## Production Audit, Not Just Scanning
+
+V3 adds an intake-driven audit layer:
+
+```text
+.ai-maintainer/project-profile.yml
+.ai-maintainer/evidence-sources.yml
+.ai-maintainer/business-flows.yml
+.ai-maintainer/risk-policy.yml
+.ai-maintainer/threat-model.md
+.ai-maintainer/release-checklist.yml
+.ai-maintainer/incident-runbook.md
+.ai-maintainer/db-migration-policy.yml
+.ai-maintainer/observability-checklist.yml
+```
+
+The user supplies business facts and evidence locations. The tool decides which checks apply and labels every item clearly:
+
+```text
+PASS           checked and OK
+FAIL           checked and failed
+WARN           risky but not blocking by default
+GAP            missing evidence
+N/A            not applicable to this project
+USER_DECISION  maintainer judgment required
+```
+
+By default, `GAP` is reported but does not fail the gate. To make missing production evidence a hard release blocker:
+
+```yaml
+production:
+  block_on_coverage_gaps: true
+```
+
+## Reports
+
+Each run writes:
+
+```text
+reports/security-report.json
+reports/security-report.md
+reports/security-report.sarif
+reports/sbom.cdx.json
+```
+
+Reports include:
+
+- PASS/FAIL summary
+- blockers and warnings
+- production evidence gaps
+- user decisions still needed
+- tool versions and commands
+- exception usage
+- SARIF for GitHub Code Scanning
+- open source maintenance score
+
+## Use With Codex
+
+Install as a Codex skill:
+
+```powershell
+git clone https://github.com/xixifusi1213-gif/ai-project-maintainer.git
+cd .\ai-project-maintainer
+Copy-Item -Recurse .\ai-project-maintainer "$env:USERPROFILE\.codex\skills\ai-project-maintainer"
+```
+
+Then ask Codex:
+
+```text
+$ai-project-maintainer generate a production audit plan for this project, run the production gate, fix blockers, and rerun until it passes.
+```
+
+## Source Checkout Commands
+
+If you are using the repository directly instead of npm:
+
+```powershell
+node .\ai-project-maintainer\scripts\doctor.mjs
+node .\ai-project-maintainer\scripts\init-project.mjs "E:\my-project" --profile oss --ci github
+node .\ai-project-maintainer\scripts\init-audit.mjs "E:\my-project"
+node .\ai-project-maintainer\scripts\audit-plan.mjs "E:\my-project" --output reports/audit-plan.json
+node .\ai-project-maintainer\scripts\run-local-gate.mjs "E:\my-project" --production --strict --release --output reports/security-report.json
+node .\ai-project-maintainer\scripts\report-summary.mjs "E:\my-project\reports\security-report.json"
+```
+
+## What This Is Not
+
+This tool does not prove absolute security, replace human risk ownership, or eliminate final audits for high-stakes systems.
+
+It is designed for the practical middle ground: a personal developer or small team using AI coding, with enough process to maintain a serious project without manually checking every item from scratch.
+
+## Documentation
+
+- [Demo](docs/DEMO.md)
+- [中文演示](docs/DEMO.zh-CN.md)
+- [Production audit workflow](docs/PRODUCTION-AUDIT.zh-CN.md)
+- [Intake schema](docs/INTAKE-SCHEMA.zh-CN.md)
+- [Install guide](docs/INSTALL.zh-CN.md)
+- [GitHub Actions guide](docs/CI-GITHUB-ACTIONS.zh-CN.md)
+- [Policy and exceptions](docs/POLICY-AND-EXCEPTIONS.zh-CN.md)
+- [Promotion kit](docs/PROMOTION.md)
+
+## Development
+
+```powershell
+npm install
+npm test
+npm run check
+npm pack --dry-run
+```

package/ai-project-maintainer/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: ai-project-maintainer
+description: Orchestrates local and CI safety gates for AI-coded projects across tests, application code, Electron desktop risk, database migrations, network/cloud/IaC security, secrets, dependency risk, Kubernetes, and production incident triage. Use when asked to make a reusable security gate, review or maintain an AI coding project, reduce manual checks, audit PRs or diffs, inspect database or network security risks, set up CI/CD guardrails, download local security tools, or investigate production incidents.
+---
+
+# AI Project Maintainer
+
+## Operating Rules
+
+- Treat AI-generated code as untrusted until checked by deterministic tools, tests, and targeted review.
+- Start with repository orientation before running broad scans: inspect git status, recent diffs, project layout, lockfiles, migration files, infra files, and CI config.
+- Prefer evidence-producing checks over generic advice. Every finding should include the file or command evidence, risk, fix, and verification.
+- Default to account-free local gates. Require accounts only for platform evidence: Bytebase projects, cloud/Kubernetes runtime state, staging DAST targets, or observability/incident systems.
+- Use specialized installed skills when they match: `codex-security:security-diff-scan` for diffs, `codex-security:security-scan` for broader security review, and `codex-security:fix-finding` only after a finding is validated.
+- Do not run destructive actions, production writes, schema changes, exploit payloads, or internet-facing active scans without explicit user approval and a named scope.
+- If a tool is not installed, continue with available checks and report the smallest useful tool gap instead of blocking the review.
+
+## Quick Start
+
+1. Check the local environment with `node <this-skill>/scripts/doctor.mjs` or `npx ai-project-maintainer doctor`.
+2. Initialize a project with `node <this-skill>/scripts/init-project.mjs <repo> --profile oss --ci github` or `npx ai-project-maintainer init <repo> --profile oss --ci github`.
+3. For production-oriented review, initialize intake with `node <this-skill>/scripts/init-audit.mjs <repo>` or `npx ai-project-maintainer init-audit <repo>`.
+4. Generate the audit plan with `node <this-skill>/scripts/audit-plan.mjs <repo> --output reports/audit-plan.json` or `npx ai-project-maintainer audit-plan <repo> --output reports/audit-plan.json`.
+5. For a reusable local safety gate, run `node <this-skill>/scripts/run-local-gate.mjs <repo> --strict --release --output reports/security-report.json` or `npx ai-project-maintainer gate <repo> --strict --release --output reports/security-report.json`.
+6. For production evidence review, run `node <this-skill>/scripts/run-local-gate.mjs <repo> --production --strict --release --output reports/security-report.json` or `npx ai-project-maintainer gate <repo> --production --strict --release --output reports/security-report.json`.
+7. Summarize an existing report with `node <this-skill>/scripts/report-summary.mjs <repo>/reports/security-report.json` or `npx ai-project-maintainer summary <repo>/reports/security-report.json`.
+8. If required local tools are missing on Windows, run `powershell -ExecutionPolicy Bypass -File <this-skill>/scripts/bootstrap-local-tools.ps1 -Tools gitleaks,trivy,semgrep,checkov`.
+9. Run `node <this-skill>/scripts/probe-project.mjs <repo>` when you only need classification and tool availability.
+10. Read only the relevant references:
+   - Local account-free gate: `references/local-gate.md`
+   - Database and migrations: `references/database.md`
+   - Electron desktop apps: `references/electron-desktop.md`
+   - Code, network, cloud, IaC, dependency, and secret security: `references/security.md`
+   - Production incidents and SRE triage: `references/incident-response.md`
+   - CI/CD guardrails and maintenance automation: `references/ci-guardrails.md`
+   - Tool selection details: `references/tool-router.md`
+11. Build a short execution plan from the detected risk surfaces and the audit plan.
+12. Run the least invasive checks first, then deeper checks only where evidence points.
+13. Return findings first, ordered by severity, with commands/tests already run.
+
+## Modes
+
+- **PR or diff review**: Review changed files first. Route changed migrations to database checks, changed infra to IaC/network checks, changed auth/API code to security checks, and changed deploy files to incident-risk checks.
+- **Local safety gate**: Run `run-local-gate.mjs` in strict mode. Use this as the default reusable gate for personal projects before release.
+- **Repository baseline**: Establish current risk posture across secrets, dependencies, static analysis, migrations, IaC, containers, and CI gates.
+- **Electron desktop review**: Inspect preload IPC, BrowserWindow webPreferences, file-system permissions, update trust, navigation controls, shell opening, and multi-window data consistency.
+- **Database migration review**: Focus on lock risk, backfill safety, rollback, compatibility windows, and online migration tools.
+- **Network or cloud security review**: Focus on exposed services, auth boundaries, IAM, CORS, SSRF, TLS, Kubernetes policies, and IaC drift.
+- **Production incident triage**: Stay read-only. Build a timeline from deploys, migrations, metrics, logs, traces, Kubernetes events, and alerts.
+- **Guardrail setup**: Add or propose CI checks only after identifying the repo's package manager, CI provider, and deployment path.
+- **Production audit readiness**: If `.ai-maintainer/project-profile.yml` is missing, run `init-audit` and ask the maintainer to fill business and evidence facts. Then run `audit-plan`, followed by `gate --production`. Treat `GAP` as missing evidence, not proof of safety.
+
+## Output Contract
+
+Use this structure unless the user asks otherwise:
+
+1. Findings: severity `P0` to `P3`, evidence, impact, concrete fix, and verification.
+2. Checks run: commands or skills used and whether they passed, failed, or were unavailable.
+3. Coverage gaps: important areas not checked and why.
+4. Next guardrails: the smallest durable automation that would prevent recurrence.
+
+For incidents, replace "Findings" with "Current assessment" and include timeline, blast radius, suspected trigger, mitigation options, and rollback safety notes.

package/ai-project-maintainer/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "AI Project Maintainer"
+  short_description: "Reusable local and CI safety gates for AI-coded projects."
+  default_prompt: "Use $ai-project-maintainer to run a strict local safety gate for this project and explain any blockers."
+policy:
+  allow_implicit_invocation: true

package/ai-project-maintainer/references/ci-guardrails.md

@@ -0,0 +1,55 @@
+# CI Guardrails
+
+Use this reference when the user wants durable automation instead of repeated manual review.
+
+## Principle
+
+Guardrails should be small, fast, and relevant to the repo. Add blocking checks for high-confidence failures and non-blocking reports for noisy scanners until tuned.
+
+## Minimum Useful Stack
+
+For most repos:
+
+- Secret scan: Gitleaks or Trivy secret scan.
+- Dependency and image scan: Trivy or native package audit.
+- Static app security: Semgrep auto rules and repo tests.
+- IaC/cloud scan when infra files exist: Checkov or Trivy config.
+- Database migration lint when migrations exist: Squawk/Atlas/strong_migrations/gh-ost/pt-online-schema-change depending on database.
+
+## PR Gates
+
+Block PRs for:
+
+- Committed secrets.
+- Critical reachable dependency vulnerabilities in production code.
+- Unsafe database migrations likely to lock or rewrite hot tables.
+- Public exposure or privilege escalation in IaC/Kubernetes.
+- Failing tests or type checks in changed service boundaries.
+
+Warn but do not block initially for:
+
+- Low-confidence SAST findings.
+- Dev-only vulnerabilities.
+- Legacy baseline issues unrelated to the PR.
+
+## Deployment Gates
+
+Before production deploy:
+
+- Confirm migrations have a rollback or forward-fix plan.
+- Confirm schema/app compatibility for rolling deploys.
+- Confirm images are scanned and signed if the org uses signing.
+- Confirm observability exists for the changed path: logs, metrics, traces, and alerts.
+- Confirm feature flags or rollback commands for high-risk releases.
+
+## Incident Feedback Loop
+
+After every incident, add one guardrail that would have detected or prevented it:
+
+- Migration lint or staging dry run for DB incidents.
+- Synthetic checks or SLO alerts for user-visible breakage.
+- Policy-as-code for cloud/network misconfigurations.
+- Regression tests for the failed path.
+- Runbook automation for known remediation.
+
+Do not add broad tools just to add tools. Tie each new check to a risk surfaced by the project.

package/ai-project-maintainer/references/database.md

@@ -0,0 +1,60 @@
+# Database Review
+
+Use this reference when the repo has SQL files, ORM migrations, schema definitions, migration tools, or the user mentions database risk.
+
+## Review Goals
+
+- Prevent downtime from locks, table rewrites, long transactions, blocking backfills, and incompatible app/schema deploy order.
+- Preserve rollback options and data integrity.
+- Separate migration safety from application query correctness.
+
+## High-Risk Migration Patterns
+
+Flag and verify these patterns:
+
+- Adding `NOT NULL` columns with defaults on large existing tables.
+- Creating non-concurrent indexes on hot Postgres tables.
+- Dropping, renaming, or changing types of columns used by deployed code.
+- Large backfills inside a schema migration transaction.
+- Adding foreign keys or constraints without staged validation.
+- Rewriting large tables with `ALTER TABLE` operations.
+- Deleting data during deploy instead of after a compatibility window.
+- Mixing app logic changes and irreversible schema/data changes in one deploy.
+- Missing rollback, down migration, or forward-only recovery plan.
+
+## PostgreSQL Routing
+
+- Use Squawk for raw SQL or Postgres migration linting.
+- Use Atlas for schema diff and migration lint when Atlas config or migration dirs exist.
+- Use pgroll when zero-downtime, expand/contract, or rollback-safe Postgres migrations are needed.
+- In Rails, use `strong_migrations` patterns when `db/migrate` exists.
+
+Prefer staged changes:
+
+1. Expand schema compatibly.
+2. Deploy code that reads/writes both old and new shape if needed.
+3. Backfill in small batches outside the deploy transaction.
+4. Validate constraints concurrently or in staged form.
+5. Contract after old code is gone.
+
+## MySQL Routing
+
+- Use gh-ost or Percona `pt-online-schema-change` for online schema changes on large tables.
+- Watch for metadata locks, long-running transactions, replication lag, and unsafe DDL.
+- Require a rollback or forward-fix plan for destructive changes.
+
+## ORM-Specific Checks
+
+- Prisma/Drizzle/TypeORM/Knex: inspect generated SQL, not only the migration source.
+- Django/Alembic/Flyway/Liquibase: verify transaction behavior, lock behavior, and migration ordering.
+- Rails: check `strong_migrations` compatibility and avoid data backfills inside migration files.
+
+## Output Shape
+
+For each migration risk, report:
+
+- Affected table or migration file.
+- Lock/rewrite/compatibility risk.
+- Safer migration sequence.
+- Tool coverage used or missing.
+- Verification: local migration test, shadow DB diff, staging dry run, or CI lint.

package/ai-project-maintainer/references/electron-desktop.md

@@ -0,0 +1,43 @@
+# Electron Desktop Review
+
+Use this reference when `electron` appears in dependencies, `BrowserWindow` is used, or files such as `main.js`, `preload.js`, or `renderer.js` exist.
+
+## Blockers
+
+Block release for:
+
+- `nodeIntegration: true` in renderer windows.
+- `contextIsolation: false`.
+- `webSecurity: false` or `allowRunningInsecureContent: true`.
+- IPC APIs that read, write, delete, execute, or open arbitrary caller-supplied paths.
+- Preload APIs that expose broad filesystem, shell, child process, or network capabilities without per-operation authorization.
+- Auto-update flows that trust a remote hash from the same mutable location as the update metadata.
+
+## Review Checklist
+
+- Main process owns privileged actions. Renderers request narrow operations.
+- File import/export paths come from a main-process dialog or a short-lived path token created by the main process.
+- IPC validates sender frame/origin, input schema, allowed path roots, and operation intent.
+- `shell.openExternal` only opens validated `https:` URLs from allowlisted domains.
+- Navigation and new-window handlers deny untrusted destinations.
+- Preload exposes small, named commands instead of raw filesystem or shell primitives.
+- Updates are signed or verified with a trust root not controlled by the update metadata source.
+- Multi-window writes use revision checks, merge-by-scope, or conflict rejection in the main process.
+
+## Useful Tests
+
+- Renderer cannot read an arbitrary local file through import IPC.
+- Renderer cannot write outside approved export locations.
+- Main process rejects IPC from unexpected sender frames where feasible.
+- Two windows saving stale snapshots cannot overwrite newer data without conflict detection.
+- Update metadata without valid integrity/signature fails closed.
+
+## Output Standard
+
+For Electron findings, include:
+
+- Exact exposed API or `BrowserWindow` setting.
+- Attack precondition such as XSS, malicious import data, or compromised update metadata.
+- Privilege gained by renderer code.
+- Main-process authorization fix.
+- Regression test to prove the privilege path is closed.

package/ai-project-maintainer/references/incident-response.md

@@ -0,0 +1,52 @@
+# Incident Response
+
+Use this reference when the user reports an outage, degraded service, suspicious production behavior, alert storm, data issue, or asks for SRE/root-cause help.
+
+## Safety Rules
+
+- Stay read-only unless the user explicitly asks for a mitigation and confirms the target environment.
+- Preserve evidence before cleanup.
+- Prefer reversible mitigations: rollback, traffic shift, feature flag disable, rate limit, queue pause, or read-only mode.
+- Do not run destructive database, Kubernetes, or cloud commands as part of diagnosis.
+
+## Triage Flow
+
+1. Define the incident window, affected service, symptoms, and customer impact.
+2. Build a timeline: deploys, config changes, database migrations, infra changes, traffic changes, alerts, and dependency events.
+3. Check blast radius: which regions, tenants, endpoints, queues, jobs, or database tables are affected.
+4. Correlate signals: logs, metrics, traces, Kubernetes events, rollout history, error budgets, and saturation metrics.
+5. Identify likely trigger and immediate mitigation.
+6. Record follow-up guardrails that would have caught the issue before production.
+
+## Tool Routing
+
+- Kubernetes: use `kubectl` read-only commands, k8sgpt, Kubescape, or HolmesGPT.
+- Observability: query Prometheus/Grafana/Loki/ELK/Jaeger/Datadog/Sentry only when credentials or tools are already available.
+- AI SRE: use HolmesGPT or OpenSRE to correlate logs, metrics, traces, and runbooks when configured.
+- Database incidents: read `database.md` and look for recent migrations, locks, slow queries, deadlocks, replication lag, and connection pool exhaustion.
+- Network incidents: read `security.md` and inspect ingress, DNS, certificates, firewall/security-group changes, service mesh, and egress policy.
+
+## Useful Read-Only Commands
+
+Adapt to the cluster and namespace:
+
+```bash
+kubectl get pods,deploy,svc,ingress -A
+kubectl get events -A --sort-by=.lastTimestamp
+kubectl rollout history deployment/<name> -n <namespace>
+kubectl logs deployment/<name> -n <namespace> --since=30m
+k8sgpt analyze
+holmes ask "What changed before this alert and what is the most likely root cause?"
+```
+
+## Incident Output
+
+Return:
+
+- Current assessment and confidence.
+- Timeline with concrete timestamps where available.
+- Blast radius.
+- Most likely trigger and competing hypotheses.
+- Immediate mitigation options with rollback risk.
+- Evidence still needed.
+- Preventive guardrails for CI, deploy, monitoring, or database migration.

package/ai-project-maintainer/references/local-gate.md

@@ -0,0 +1,117 @@
+# Local Safety Gate
+
+Use this reference when the user wants an account-free reusable gate for personal projects.
+
+## What Works Without Accounts
+
+These checks can run fully locally when the CLI tools are installed:
+
+- Project tests: package-manager scripts such as `test`, `test:e2e`, `build`, and `dist`.
+- Dependency audit: `npm audit --omit=dev` and equivalent package-manager audits where available.
+- Secret scan: Gitleaks or Trivy secret scanner.
+- Filesystem vulnerability/config scan: Trivy.
+- Static app scan: Semgrep, when installed or available through Docker/WSL/Python tooling.
+- IaC scan: Checkov or Trivy config scan.
+- SQL migration lint: Squawk, Atlas, or framework-specific migration tests.
+- Electron baseline: local pattern checks plus manual review of IPC and update paths.
+
+Accounts are optional. They are only needed for platform-backed evidence: Bytebase SQL review workflows, cloud IAM state, Kubernetes live cluster state, staging DAST, or incident observability.
+
+## Default Gate Command
+
+Check the current machine first:
+
+```bash
+node <skill>/scripts/doctor.mjs
+```
+
+Initialize a project once:
+
+```bash
+node <skill>/scripts/init-project.mjs <repo>
+```
+
+Run this for release decisions:
+
+```bash
+node <skill>/scripts/run-local-gate.mjs <repo> --strict --release --output reports/security-report.json
+```
+
+Use non-strict mode during adoption:
+
+```bash
+node <skill>/scripts/run-local-gate.mjs <repo>
+```
+
+Strict mode treats missing relevant tools as failures. Non-strict mode reports missing tools as coverage gaps.
+
+Summarize a saved report:
+
+```bash
+node <skill>/scripts/report-summary.mjs <repo>/reports/security-report.json
+```
+
+## Adoption Loop
+
+1. Run the gate.
+2. Fix blocking findings.
+3. Re-run until pass.
+4. Add project-specific tests for any bug class found manually.
+5. Promote stable checks into CI.
+
+## Blocking Standard
+
+Block release for:
+
+- Failing tests, E2E, build, or release packaging.
+- Committed secrets or high-confidence secret scan findings.
+- High or critical production dependency vulnerabilities without a documented exception.
+- Electron `nodeIntegration: true`, `contextIsolation: false`, `webSecurity: false`, or unrestricted IPC file/system access.
+- Unsafe database migrations: likely lock/table rewrite, destructive incompatible change, or missing rollback for risky schema changes.
+- IaC/Kubernetes settings that expose admin surfaces, plaintext secrets, privileged containers, broad IAM, or public ingress without controls.
+
+Warn, tune, or document exceptions for:
+
+- Dev-only vulnerabilities.
+- Low-confidence static-analysis findings.
+- Historical baseline issues outside the current change.
+- Missing tools during the first adoption pass.
+
+## Local Tool Bootstrap
+
+On Windows, the bundled bootstrap script can download account-free CLI binaries where GitHub release assets are available:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File <skill>\scripts\bootstrap-local-tools.ps1 -Tools gitleaks,trivy,squawk
+```
+
+If `uv` is available, the same script can try Python-tool installs:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File <skill>\scripts\bootstrap-local-tools.ps1 -Tools semgrep,checkov
+```
+
+If Semgrep or Checkov cannot install on the current Windows environment, keep them as coverage gaps and rely on Codex security review plus project tests until Python, Docker, or WSL is ready.
+
+## Policy And Exceptions
+
+Project policy lives in:
+
+```text
+.ai-maintainer/policy.yml
+.ai-maintainer/exceptions.yml
+```
+
+Exceptions must include `id`, `check`, `reason`, `expires`, and `owner`. Expired or incomplete exceptions are blocking failures. Exceptions only downgrade the matching finding, not an entire tool category.
+
+## Trivy Database Availability
+
+Trivy needs a vulnerability database on first run. The gate uses GHCR first:
+
+```powershell
+$env:TRIVY_DB_REPOSITORY="ghcr.io/aquasecurity/trivy-db:2"
+$env:TRIVY_JAVA_DB_REPOSITORY="ghcr.io/aquasecurity/trivy-java-db:1"
+$env:TRIVY_TIMEOUT="90s"
+```
+
+If the database cannot download, strict mode must fail because dependency and image vulnerability coverage is unavailable. Re-run from a network that can reach the configured OCI registry, or set those environment variables to an internal mirror.

package/ai-project-maintainer/references/security.md

@@ -0,0 +1,48 @@
+# Security Review
+
+Use this reference for application, network, cloud, IaC, dependency, container, and secret security checks.
+
+## AI-Coding Risk Hotspots
+
+AI-generated code commonly introduces plausible-looking but unsafe shortcuts. Prioritize:
+
+- Auth bypasses, missing authorization checks, tenant isolation mistakes, and IDOR.
+- Overbroad CORS, public debug endpoints, permissive admin routes, and missing CSRF protections.
+- SSRF through user-controlled URLs, webhooks, image fetchers, importers, or proxy endpoints.
+- SQL/NoSQL injection from string-built queries or unsafe ORM escape hatches.
+- Unsafe file upload, path traversal, zip extraction, and untrusted document parsing.
+- Disabled TLS verification, weak JWT validation, hardcoded secrets, and secret logging.
+- Excessive IAM permissions, public buckets, open security groups, and unauthenticated internal services.
+- Docker/Kubernetes privileged mode, hostPath mounts, root containers, and exposed dashboards.
+
+## Check Sequence
+
+1. Secrets: run Gitleaks or Trivy secret scan first; never display secret values.
+2. Dependencies and images: run Trivy or equivalent package audit and separate production/runtime findings from dev-only noise.
+3. Static analysis: run Semgrep auto rules, CodeQL if configured, and any repo-native lint/security tests.
+4. IaC and cloud config: run Checkov, Trivy config, Conftest/OPA, or Kubescape depending on files present.
+5. Targeted manual review: inspect auth boundaries, request validation, dataflow into dangerous sinks, and changed deploy/network files.
+6. DAST: use ZAP or Nuclei only for an explicitly scoped local/staging target.
+
+## Network and Cloud Review
+
+For Terraform, Helm, Kubernetes, Docker Compose, or cloud config, identify:
+
+- Internet-exposed ingress/load balancers and whether auth/TLS/WAF is present.
+- Security group or firewall rules with `0.0.0.0/0` or overly broad ports.
+- IAM wildcard actions/resources and cross-account trust.
+- Lack of Kubernetes NetworkPolicy in multi-tenant or internet-facing namespaces.
+- Secret material in manifests, env vars, logs, or image layers.
+- Missing resource limits, health checks, pod disruption budgets, or rollout safety.
+
+## Finding Standard
+
+Report only actionable findings. Each security finding needs:
+
+- Asset or code path affected.
+- Attack path or failure mode.
+- Exploit preconditions.
+- Concrete fix.
+- Verification command, test, or policy.
+
+Mark speculative concerns as coverage gaps, not findings.