ai-project-maintainer 0.4.0 → 0.4.1

package/README.md

@@ -11,7 +11,7 @@
 
 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)
+[See the demo](docs/DEMO.md) · [Before/after case](docs/demo-output/before-after-case.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:
 
@@ -56,6 +56,8 @@ GitHub Actions templates can either use the npm package or clone this repository
 
 This repository includes a runnable sample project at `examples/demo-ai-app`.
 
+![90-second demo storyboard](assets/demo-90s.gif)
+
 ```powershell
 npm test --prefix .\examples\demo-ai-app
 npm run build --prefix .\examples\demo-ai-app
@@ -75,6 +77,12 @@ node .\examples\demo-ai-app\scripts\create-before-state.mjs
 ```
 
 It writes a broken copy under the OS temp directory, where the business tests fail.
+
+More demo material:
+
+- [Before/after case](docs/demo-output/before-after-case.md)
+- [90-second browser demo](docs/demo-output/90-second-demo.html)
+- [Animated SVG storyboard](assets/demo-90s-storyboard.svg)
 
 ## What It Checks
 
@@ -136,11 +144,12 @@ reports/security-report.sarif
 reports/sbom.cdx.json
 ```
 
-Reports include:
-
-- PASS/FAIL summary
-- blockers and warnings
-- production evidence gaps
+Reports include:
+
+- PASS/FAIL summary
+- `overallStatus`: `FAIL`, `PASS_WITH_GAPS`, `PASS_WITH_WARNINGS`, or `PASS`
+- blockers and warnings
+- production evidence gaps
 - user decisions still needed
 - tool versions and commands
 - exception usage
@@ -186,6 +195,7 @@ It is designed for the practical middle ground: a personal developer or small te
 
 - [Demo](docs/DEMO.md)
 - [中文演示](docs/DEMO.zh-CN.md)
+- [Before/after case](docs/demo-output/before-after-case.md)
 - [Security workflow](docs/SECURITY-WORKFLOW.md)
 - [Production audit workflow](docs/PRODUCTION-AUDIT.zh-CN.md)
 - [Intake schema](docs/INTAKE-SCHEMA.zh-CN.md)

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

@@ -1,6 +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
+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

@@ -1,55 +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.
+# 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

@@ -1,60 +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.
+# 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

@@ -1,43 +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.
+# 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

@@ -1,52 +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.
+# 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/security.md

@@ -1,48 +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.
+# 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.