ai-project-maintainer 0.3.0 → 0.4.0

package/README.md

@@ -1,9 +1,11 @@
 # 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)
+![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)
+[![npm](https://img.shields.io/npm/v/ai-project-maintainer.svg)](https://www.npmjs.com/package/ai-project-maintainer)
 [![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)
+[![Security](https://github.com/xixifusi1213-gif/ai-project-maintainer/actions/workflows/security.yml/badge.svg)](https://github.com/xixifusi1213-gif/ai-project-maintainer/actions/workflows/security.yml)
 
 **A production-readiness gate for AI-coded projects.**
 
@@ -30,11 +32,13 @@ AI coding makes it easy to ship code that looks complete but quietly misses prod
 
 `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
+## The 3-Minute Flow
+
+Requires Node.js 20+.
+
+```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"
@@ -43,10 +47,34 @@ npx ai-project-maintainer init-audit "E:\my-project"
 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.
+npx ai-project-maintainer gate "E:\my-project" --production --strict --release --output reports/security-report.json
+```
+
+GitHub Actions templates can either use the npm package or clone this repository directly.
+
+## Real Demo
+
+This repository includes a runnable sample project at `examples/demo-ai-app`.
+
+```powershell
+npm test --prefix .\examples\demo-ai-app
+npm run build --prefix .\examples\demo-ai-app
+node .\examples\demo-ai-app\scripts\run-demo-gate.mjs
+```
+
+The demo shows the intended workflow:
+
+- healthy business tests and release build pass
+- Gitleaks, Trivy, Semgrep, OSV, Syft, Grype, Scorecard, and CI checks are represented in the report
+- production-readiness gaps remain visible for release approval, monitoring, logs, metrics, and alerts
+
+To see the "before" state without committing unsafe fixtures:
+
+```powershell
+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.
 
 ## What It Checks
 
@@ -156,9 +184,10 @@ It is designed for the practical middle ground: a personal developer or small te
 
 ## Documentation
 
-- [Demo](docs/DEMO.md)
-- [中文演示](docs/DEMO.zh-CN.md)
-- [Production audit workflow](docs/PRODUCTION-AUDIT.zh-CN.md)
+- [Demo](docs/DEMO.md)
+- [中文演示](docs/DEMO.zh-CN.md)
+- [Security workflow](docs/SECURITY-WORKFLOW.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)

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

@@ -132,9 +132,9 @@ jobs:
             cat reports/security-report.md >> "$GITHUB_STEP_SUMMARY"
           fi
 
-      - name: Upload SARIF to code scanning
-        if: always()
-        uses: github/codeql-action/upload-sarif@v3
+      - name: Upload SARIF to code scanning
+        if: always()
+        uses: github/codeql-action/upload-sarif@v4
         with:
           sarif_file: reports/security-report.sarif
         continue-on-error: true

package/docs/DEMO.md

@@ -1,81 +1,69 @@
-# Demo: From AI-Coded Repo to Production Audit Report
-
-This demo shows the core workflow without requiring any paid account or external API.
-
-## 1. Initialize The Project
-
-```powershell
-npx ai-project-maintainer init "E:\my-project" --profile oss --ci github
-```
-
-This creates the local policy, exceptions file, GitHub Actions workflow, Dependabot config, and report directory.
-
-## 2. Create Production Audit Intake
-
-```powershell
-npx ai-project-maintainer init-audit "E:\my-project"
-```
-
-This creates:
-
-```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
-```
-
-These files record project facts and evidence locations. They should not contain tokens, DSNs, passwords, or production secrets.
-
-## 3. Generate An Audit Plan
-
-```powershell
-npx ai-project-maintainer audit-plan "E:\my-project" --output reports/audit-plan.json
-```
-
-Example output:
-
-```text
-PASS          Production audit intake is present.
-USER_DECISION Critical business flows must be declared.
-GAP           No GitHub Actions workflow evidence detected.
-GAP           No production release approval evidence declared.
-GAP           Error monitoring evidence is missing.
-N/A           No database surface detected or declared.
-```
-
-The point is not to pretend the project is safe. The point is to make missing production evidence visible.
-
-## 4. Run The Production Gate
-
-```powershell
-npx ai-project-maintainer gate "E:\my-project" --production --strict --release --output reports/security-report.json
-```
-
-The report combines deterministic scanner output with production-readiness evidence:
-
-```text
-PASS gitleaks secret scan
-PASS trivy filesystem scan
-PASS semgrep static scan
-GAP  Error monitoring evidence is missing.
-GAP  Production logs evidence is missing.
-USER_DECISION Critical business flows must be declared.
-```
-
-See [sample report](demo-output/security-report.md).
-
-## 5. Let Codex Fix Blockers
-
-Ask Codex:
-
-```text
-$ai-project-maintainer run the production gate for this project, fix blockers, and rerun until it passes.
-```
-
-Codex can handle deterministic blockers. The maintainer still owns business decisions such as critical flows, accepted risks, and production evidence.
+# Demo: From AI-Coded Repo to Production Audit Report
+
+This demo uses the runnable project in `examples/demo-ai-app`. It does not require any paid account or external API.
+
+## 1. Run The Healthy Demo App
+
+```powershell
+npm test --prefix .\examples\demo-ai-app
+npm run build --prefix .\examples\demo-ai-app
+```
+
+The app is intentionally small: it quotes orders and decides whether paid orders can be released. The tests protect the business behavior that must not break.
+
+## 2. Generate A Broken Before State
+
+```powershell
+node .\examples\demo-ai-app\scripts\create-before-state.mjs
+```
+
+The command prints a temporary directory. Run this in that copied project:
+
+```powershell
+npm test
+```
+
+You should see the business tests fail. This is the "AI-coded project looks complete, but behavior is broken" stage. The broken copy is created under the OS temp directory, so the repository does not commit fake secrets or intentionally bad source files.
+
+## 3. Run The Reproducible Demo Gate
+
+```powershell
+node .\examples\demo-ai-app\scripts\run-demo-gate.mjs
+```
+
+This script runs the real AI Project Maintainer gate with temporary scanner shims, so the sample report is stable even on a machine that has not installed Gitleaks, Trivy, Semgrep, OSV-Scanner, Syft, Grype, actionlint, zizmor, or Scorecard yet.
+
+Expected result:
+
+```text
+Local Security Gate: PASS
+Blocking Checks: None
+Coverage Gaps:
+- Production release approval
+- Error monitoring
+- Production logs
+- Production metrics
+- Production alerts
+```
+
+See the generated-style [sample report](demo-output/security-report.md).
+
+## 4. Run The Real Gate
+
+After installing scanner CLIs, use the same command a real project would use:
+
+```powershell
+npx ai-project-maintainer gate .\examples\demo-ai-app --production --strict --release --output reports/security-report.json
+```
+
+The point is not to pretend the project is perfect. The point is to make the checked failures and missing production evidence explicit before release.
+
+## 5. Let Codex Fix Blockers
+
+Ask Codex:
+
+```text
+$ai-project-maintainer run the production gate for this project, fix blockers, and rerun until it passes.
+```
+
+Codex can handle deterministic blockers. The maintainer still owns business decisions such as critical flows, accepted risks, and production evidence.

package/docs/DEMO.zh-CN.md

@@ -1,81 +1,69 @@
-# 演示：从 AI coding 项目到生产审查报告
-
-这个 demo 不需要付费账号，也不需要外部 API。
-
-## 1. 初始化项目门禁
-
-```powershell
-npx ai-project-maintainer init "E:\我的项目" --profile oss --ci github
-```
-
-这会生成本地策略、例外文件、GitHub Actions、Dependabot 配置和报告目录。
-
-## 2. 生成生产审查画像
-
-```powershell
-npx ai-project-maintainer init-audit "E:\我的项目"
-```
-
-这会生成：
-
-```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
-```
-
-这些文件只记录项目事实和证据来源，不应该写 token、DSN、密码或生产 secret。
-
-## 3. 生成审计计划
-
-```powershell
-npx ai-project-maintainer audit-plan "E:\我的项目" --output reports/audit-plan.json
-```
-
-示例输出：
-
-```text
-PASS          生产审查画像已存在。
-USER_DECISION 需要项目负责人声明核心业务流程。
-GAP           没有 GitHub Actions 证据。
-GAP           没有生产发布审批证据。
-GAP           缺少错误监控证据。
-N/A           没有检测到数据库。
-```
-
-重点不是假装项目安全，而是把“缺少哪些生产证据”明确写出来。
-
-## 4. 运行生产级门禁
-
-```powershell
-npx ai-project-maintainer gate "E:\我的项目" --production --strict --release --output reports/security-report.json
-```
-
-报告会把确定性扫描结果和生产准备度证据合在一起：
-
-```text
-PASS gitleaks secret scan
-PASS trivy filesystem scan
-PASS semgrep static scan
-GAP  缺少错误监控证据。
-GAP  缺少生产日志证据。
-USER_DECISION 需要声明核心业务流程。
-```
-
-查看 [示例报告](demo-output/security-report.md)。
-
-## 5. 让 Codex 修阻断项
-
-对 Codex 说：
-
-```text
-$ai-project-maintainer 对这个项目运行生产级门禁，修复阻断项，然后重新运行直到通过。
-```
-
-Codex 可以处理确定性的阻断项。项目负责人仍然负责核心业务流程、风险接受和生产证据判断。
+# 演示：从 AI 写出的项目到生产审查报告
+
+这个演示使用仓库里的真实项目：`examples/demo-ai-app`。不需要付费账号，也不需要外部 API。
+
+## 1. 跑健康态项目
+
+```powershell
+npm test --prefix .\examples\demo-ai-app
+npm run build --prefix .\examples\demo-ai-app
+```
+
+这个项目很小：它负责订单报价和订单释放判断。测试覆盖的是不能被 AI 修改坏的核心业务行为。
+
+## 2. 生成坏掉的 before 状态
+
+```powershell
+node .\examples\demo-ai-app\scripts\create-before-state.mjs
+```
+
+命令会输出一个临时目录。进入那个复制出来的项目后运行：
+
+```powershell
+npm test
+```
+
+你会看到业务测试失败。这代表“AI 写出来看起来完整，但关键行为已经坏了”的阶段。坏代码只存在于系统临时目录，仓库不会提交假 secret 或故意脆弱的源码。
+
+## 3. 跑可复现的 demo gate
+
+```powershell
+node .\examples\demo-ai-app\scripts\run-demo-gate.mjs
+```
+
+这个脚本会运行真实的 AI Project Maintainer gate，但会临时创建扫描器 mock，所以即使本机还没安装 Gitleaks、Trivy、Semgrep、OSV-Scanner、Syft、Grype、actionlint、zizmor、Scorecard，也能稳定生成示例报告。
+
+预期结果：
+
+```text
+Local Security Gate: PASS
+Blocking Checks: None
+Coverage Gaps:
+- Production release approval
+- Error monitoring
+- Production logs
+- Production metrics
+- Production alerts
+```
+
+示例报告见：[sample report](demo-output/security-report.md)。
+
+## 4. 跑真实 gate
+
+安装扫描器 CLI 后，可以用真实项目同款命令：
+
+```powershell
+npx ai-project-maintainer gate .\examples\demo-ai-app --production --strict --release --output reports/security-report.json
+```
+
+这个工具不是为了假装项目完美，而是把已经检查失败的项和缺少的生产证据在发布前明确展示出来。
+
+## 5. 让 Codex 修阻断项
+
+可以这样要求 Codex：
+
+```text
+$ai-project-maintainer run the production gate for this project, fix blockers, and rerun until it passes.
+```
+
+Codex 适合处理确定性的阻断项。维护者仍然负责业务决策、风险接受和生产证据确认。

package/docs/SECURITY-WORKFLOW.md

@@ -0,0 +1,61 @@
+# Heavy Security Workflow
+
+`v0.4.0` adds `.github/workflows/security.yml` so the repository dogfoods a heavier security gate.
+
+## When It Runs
+
+- pull requests to `main`
+- pushes to `main`
+- weekly scheduled run
+- manual `workflow_dispatch`
+
+## Blocking Checks
+
+The first version blocks on high-confidence failures:
+
+- `npm test`
+- `npm run check`
+- `npm pack --dry-run`
+- AI Project Maintainer production gate
+- Gitleaks findings through the production gate
+- Trivy high/critical findings through the production gate
+- Semgrep blocking findings through the production gate
+- actionlint failures through the production gate
+
+## Advisory Evidence
+
+The workflow also captures extra evidence and uploads it as an artifact:
+
+- raw Gitleaks JSON
+- raw Trivy JSON
+- Semgrep SARIF
+- OSV-Scanner text output
+- Syft CycloneDX SBOM
+- Grype JSON
+- actionlint output
+- zizmor output
+- OpenSSF Scorecard JSON
+- AI Project Maintainer JSON, Markdown, SARIF, and SBOM reports
+
+Some advisory steps use `continue-on-error: true` because early public projects often need one or two runs to tune scanner baselines. The production gate remains the release decision.
+
+## Why Not Block Everything Immediately
+
+This project is a public tool, so a permanently red workflow hurts trust as much as missing checks. The v0.4.0 policy is:
+
+```text
+high-confidence release risk -> block
+optional ecosystem signal -> report first
+```
+
+Once the workflow has a stable baseline, optional checks can be promoted from warning to blocking in `.ai-maintainer/policy.yml`.
+
+## Local Equivalent
+
+The closest local command is:
+
+```powershell
+node .\ai-project-maintainer\scripts\run-local-gate.mjs . --production --strict --release --output reports/security-report.json
+```
+
+Install scanner CLIs first, or use `node .\ai-project-maintainer\scripts\doctor.mjs` to see what is missing.

package/docs/UPGRADE-ROADMAP.zh-CN.md

@@ -1,47 +1,58 @@
-# 升级路线图
-
-## V2：开源维护者专业半自动平台
-
-当前目标：
-
-- 提供 npm/npx CLI。
-- 保留 Codex skill 和旧 Node 脚本兼容。
-- 使用插件化检查注册表。
-- 使用 `yaml@2.9.0` 解析真实 YAML 配置。
-- 生成 GitHub Actions、Dependabot、pre-commit 起步配置。
-- 生成 JSON、Markdown、SARIF、SBOM 报告。
-- 提供开源维护分。
-
-V2 仍然免账号优先，不依赖 Bytebase、云、K8s、Sentry 或 Grafana。
-
-## V2 后续增强
-
-优先增强：
-
-- GitHub Action 独立发布，减少 workflow 中的安装成本。
-- OpenSSF Scorecard 更细粒度解析。
-- MegaLinter profile 配置模板。
-- pre-commit 官方 hook 模板。
-- SARIF 更精确定位到文件和行。
-- 报告转 GitHub PR comment。
-
-## V3：平台证据接入
-
-可选接入：
-
-- Bytebase：SQL Review、审批流、发布状态。
-- Sentry/Grafana/Loki/Datadog：发布后错误率、日志、trace 和事故时间线。
-- 云平台：IAM、网络、安全组、公开入口。
-- Kubernetes：RBAC、NetworkPolicy、PodSecurity、镜像和运行时风险。
-
-这些能力需要账号或只读 token，所以不作为 V2 硬依赖。
-
-## 不做
-
-默认不做：
-
-- 自动修改生产数据库。
-- 主动攻击公网目标。
-- 自动承担发布责任。
-- 把扫描器二进制提交进仓库。
-- 用 AI 替代维护者的最终判断。
+# 升级路线图
+
+## v0.4.0：真实 demo 项目和重型安全 workflow
+
+本阶段目标是把项目可信度从“有说明、有轻量 CI”提升到“陌生人能直接跑 demo，并且仓库自己跑重型安全证据链”。
+
+已完成目标：
+
+- 新增可复现的 `examples/demo-ai-app`，展示健康项目、坏掉的 before 状态、生产审查报告。
+- 新增独立 `.github/workflows/security.yml`，安装并运行 Gitleaks、Trivy、Semgrep、OSV-Scanner、Syft、Grype、actionlint、zizmor、OpenSSF Scorecard 等安全工具。
+- README 增加 Security badge 和 Real Demo 入口。
+- Demo 文档改成基于真实项目，而不是纯文本示例。
+
+阻断策略：
+
+- 高置信风险阻断：测试、build、secret、Trivy high/critical、Semgrep blocking、actionlint、production gate。
+- 可选生态信号先记录证据：OSV、Syft、Grype、zizmor、Scorecard。
+
+后续还可以补：
+
+- 90 秒 GIF/视频，演示 `before -> gate -> fix -> pass`。
+- GitHub PR comment，把报告摘要直接写到 PR。
+- 把稳定的可选检查逐步提升为阻断项。
+
+## V2：开源维护者专业半自动平台
+
+当前目标：
+
+- 提供 npm/npx CLI。
+- 保留 Codex skill 和旧 Node 脚本兼容。
+- 使用插件化检查注册表。
+- 使用 `yaml@2.9.0` 解析真实 YAML 配置。
+- 生成 GitHub Actions、Dependabot、pre-commit 起步配置。
+- 生成 JSON、Markdown、SARIF、SBOM 报告。
+- 提供开源维护分。
+
+V2 仍然免账号优先，不依赖 Bytebase、云、K8s、Sentry 或 Grafana。
+
+## V3：平台证据接入
+
+可选接入：
+
+- Bytebase：SQL Review、审批流、发布状态。
+- Sentry/Grafana/Loki/Datadog：发布后错误率、日志、trace 和事故时间线。
+- 云平台：IAM、网络、安全组、公开入口。
+- Kubernetes：RBAC、NetworkPolicy、PodSecurity、镜像和运行时风险。
+
+这些能力需要账号或只读 token，所以不作为默认硬依赖。
+
+## 不做
+
+默认不做：
+
+- 自动修改生产数据库。
+- 主动攻击公网目标。
+- 自动承担发布责任。
+- 把扫描器二进制提交进仓库。
+- 用 AI 替代维护者的最终判断。

package/docs/demo-output/security-report.md

@@ -1,57 +1,64 @@
-# Local Security Gate: PASS
-
-Root: `example/ai-coded-project`
-Mode: strict=true, release=true, production=true
-Open Source Maintenance Score: 82/100 (B)
-
-## Blocking Checks
-
-- None
-
-## Warnings
-
-- production audit: Critical business flows: USER_DECISION. The maintainer must declare the business flows that must not break.
-- production audit: Error monitoring: GAP. Error monitoring evidence is missing.
-- production audit: Production release approval: GAP. No production deployment approval evidence declared.
-
-## Coverage Gaps
-
-- Error monitoring: Error monitoring evidence is missing. Recommendation: declare Sentry, OpenTelemetry, or another error source in `.ai-maintainer/evidence-sources.yml`.
-- Production logs: Production logs evidence is missing. Recommendation: declare log evidence before relying on production recovery.
-- Production alerts: Production alerts evidence is missing. Recommendation: declare alert routing before release.
-- Business flow tests: Critical flows are not linked to automated tests.
-
-## Production Audit
-
-Project Type: web
-Database: true
-CI: true
-
-### Plan
-
-- PASS Production audit intake: Project profile and evidence templates are present.
-- USER_DECISION Critical business flows: The maintainer must declare the business flows that must not break.
-- GAP Error monitoring: Error monitoring evidence is missing.
-- GAP Production release approval: No production deployment approval evidence declared.
-- PASS CI security review: GitHub Actions workflow evidence detected.
-- GAP Database backup evidence: Database backup evidence is missing.
-
-### User Decisions
-
-- Critical business flows: Confirm the business flows that must not break.
-- Business flow tests: Confirm which automated tests prove those flows.
-
-## Tools
-
-- node: v24.x
-- git: git version 2.x
-- gitleaks: available
-- trivy: available
-- semgrep: available
-
-## Next Step
-
-- Fill `business-flows.yml` with real flows.
-- Add or document error monitoring.
-- Add production release approval evidence.
-- Rerun `gate --production --strict --release`.
+# Local Security Gate: PASS
+
+Root: `examples/demo-ai-app`
+Mode: strict=true, release=true, production=true
+Open Source Maintenance Score: 75/100 (B)
+
+## Blocking Checks
+
+- None
+
+## Warnings
+
+- production audit: Production release approval: GAP. Production deployment exists without approval evidence.
+- production audit: Error monitoring: GAP. Error monitoring evidence is missing.
+- production audit: Production logs: GAP. Production logs evidence is missing.
+- production audit: Production metrics: GAP. Production metrics evidence is missing.
+- production audit: Production alerts: GAP. Production alerts evidence is missing.
+
+## Coverage Gaps
+
+- Production release approval: use GitHub Environments or document the approval gate.
+- Error monitoring: declare Sentry, OpenTelemetry, or another error source.
+- Production logs: declare log evidence before relying on production recovery.
+- Production metrics: declare release and service health metrics.
+- Production alerts: declare alert routing before release.
+
+## Production Audit
+
+Project Type: node
+Database: false
+CI: true
+
+### Plan
+
+- PASS Production audit intake: project profile and evidence templates are present.
+- PASS Critical business flows: 2 critical flows declared.
+- PASS Business flow tests: 2 test references declared.
+- N/A Electron security review: no Electron surface detected.
+- PASS CI security review: CI workflow evidence detected.
+- GAP Production release approval: production deployment exists without approval evidence.
+- GAP Error monitoring: error monitoring evidence is missing.
+- GAP Production logs: production logs evidence is missing.
+- GAP Production metrics: production metrics evidence is missing.
+- GAP Production alerts: production alerts evidence is missing.
+- N/A Database migration review: no database surface detected or declared.
+
+## Checks Run
+
+- package test: pass
+- release build: pass
+- npm production audit: pass
+- gitleaks secret scan: pass
+- trivy filesystem scan: pass
+- osv-scanner dependency scan: pass
+- semgrep static scan: pass
+- syft SBOM: pass
+- grype vulnerability scan: pass
+- OpenSSF Scorecard: pass
+- production audit evidence checks: GAP items reported but not blocking by default
+
+## Next Step
+
+- Add real release approval, monitoring, logs, metrics, and alerts evidence.
+- Rerun `gate --production --strict --release`.

package/examples/demo-ai-app/.ai-maintainer/business-flows.yml

@@ -0,0 +1,14 @@
+schema_version: 1
+business_flows:
+  - id: "checkout-quote"
+    name: "Customer checkout quote"
+    criticality: "high"
+    expected_behavior: "A customer-visible total must include the selected shipping cost exactly once."
+    tests:
+      - "test/order-risk.test.mjs"
+  - id: "order-release"
+    name: "Paid order release"
+    criticality: "high"
+    expected_behavior: "An order can be released only when payment, stock, and risk checks all pass."
+    tests:
+      - "test/order-risk.test.mjs"

package/examples/demo-ai-app/.ai-maintainer/db-migration-policy.yml

@@ -0,0 +1,6 @@
+schema_version: 1
+database:
+  changes_use_migrations: false
+  destructive_changes_require_review: true
+  backup_before_production_migration: false
+  rollback_or_forward_fix_required: false

package/examples/demo-ai-app/.ai-maintainer/evidence-sources.yml

@@ -0,0 +1,18 @@
+schema_version: 1
+evidence:
+  github_actions: "present"
+  deployment:
+    provider: "demo"
+    has_staging: true
+    has_production: true
+    production_requires_approval: false
+  observability:
+    errors: "none"
+    logs: "none"
+    metrics: "none"
+    alerts: "none"
+  database:
+    migrations: "none"
+    review_tool: "none"
+    backup_policy: "none"
+    rollback_plan: "none"

package/examples/demo-ai-app/.ai-maintainer/exceptions.yml

@@ -0,0 +1 @@
+exceptions: []

package/examples/demo-ai-app/.ai-maintainer/incident-runbook.md

@@ -0,0 +1,11 @@
+# Incident Runbook
+
+## First Response
+
+- Stop new releases.
+- Check checkout quote and order release tests.
+- Decide whether to rollback the latest release.
+
+## Missing Evidence
+
+- Production monitoring is intentionally missing in the demo so the audit report shows GAP items.

package/examples/demo-ai-app/.ai-maintainer/observability-checklist.yml

@@ -0,0 +1,7 @@
+schema_version: 1
+observability:
+  error_monitoring: false
+  structured_logs: false
+  metrics: false
+  alerts: false
+  release_tracking: false

package/examples/demo-ai-app/.ai-maintainer/policy.yml

@@ -0,0 +1,27 @@
+profile: oss
+mode: strict
+checks:
+  gitleaks: block
+  trivy: block
+  semgrep: block
+  osv-scanner: warn
+  syft: warn
+  grype: warn
+  actionlint: block
+  zizmor: warn
+  checkov: warn
+  trivy-config: warn
+  scorecard: warn
+  megalinter: warn
+  pre-commit: warn
+  package-audit: warn
+fail_on:
+  tests: true
+  secrets: true
+  dependency_high_or_critical: true
+  semgrep_blocking: true
+  trivy_unavailable: true
+  electron_dangerous_settings: true
+  ci_security_high: true
+warn_on:
+  missing_optional_tools: true

package/examples/demo-ai-app/.ai-maintainer/project-profile.yml

@@ -0,0 +1,15 @@
+schema_version: 1
+project:
+  name: demo-ai-app
+  type: node
+  lifecycle: production-candidate
+  production: true
+risk:
+  handles_auth: false
+  handles_sensitive_data: false
+  handles_payments: false
+  handles_financial_data: false
+  handles_health_data: false
+  has_database: false
+  has_deployment: true
+  has_user_generated_content: false

package/examples/demo-ai-app/.ai-maintainer/release-checklist.yml

@@ -0,0 +1,7 @@
+schema_version: 1
+release:
+  has_staging: true
+  has_smoke_tests: true
+  has_manual_approval: false
+  has_rollback_plan: false
+  has_versioned_artifacts: true

package/examples/demo-ai-app/.ai-maintainer/risk-policy.yml

@@ -0,0 +1,5 @@
+schema_version: 1
+production:
+  block_on_coverage_gaps: false
+  block_on_user_decisions: false
+  require_intake: true

package/examples/demo-ai-app/.ai-maintainer/threat-model.md

@@ -0,0 +1,18 @@
+# Threat Model
+
+## Assets
+
+- Order totals
+- Payment status
+- Release decisions
+
+## Trust Boundaries
+
+- Browser or API client input
+- Order risk calculation
+- Release approval process
+
+## User Decisions
+
+- Confirm whether manual review threshold matches real business risk.
+- Confirm who can override a release hold.

package/examples/demo-ai-app/README.md

@@ -0,0 +1,38 @@
+# Demo AI App
+
+This is a small healthy Node.js project used by AI Project Maintainer demos.
+
+It has:
+
+- business-critical tests
+- a build script
+- production audit intake files
+- intentional production evidence gaps for monitoring, alerts, approval, and rollback
+
+## Run The Healthy Project
+
+```powershell
+npm test --prefix .\examples\demo-ai-app
+npm run build --prefix .\examples\demo-ai-app
+node .\examples\demo-ai-app\scripts\run-demo-gate.mjs
+```
+
+The demo gate uses temporary scanner shims so the sample report is reproducible on machines that do not have Gitleaks, Trivy, Semgrep, and other scanners installed yet.
+
+## Generate The Broken Before State
+
+```powershell
+node .\examples\demo-ai-app\scripts\create-before-state.mjs
+```
+
+The command prints a temporary directory. Run `npm test` in that copied project to see the business tests fail. Nothing bad is committed into this repository; the failing state exists only under the OS temp directory.
+
+## Run The Real Gate
+
+When scanner CLIs are installed, run the same command a real project would use:
+
+```powershell
+npx ai-project-maintainer gate .\examples\demo-ai-app --production --strict --release --output reports/security-report.json
+```
+
+The expected result is PASS with visible GAP items for missing production evidence.

package/examples/demo-ai-app/package-lock.json

@@ -0,0 +1,15 @@
+{
+  "name": "demo-ai-app",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "demo-ai-app",
+      "version": "0.1.0",
+      "engines": {
+        "node": ">=20"
+      }
+    }
+  }
+}

package/examples/demo-ai-app/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "demo-ai-app",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Runnable demo project for AI Project Maintainer.",
+  "scripts": {
+    "test": "node --test",
+    "build": "node scripts/build.mjs",
+    "demo:before": "node scripts/create-before-state.mjs",
+    "demo:gate": "node scripts/run-demo-gate.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/examples/demo-ai-app/scripts/build.mjs

@@ -0,0 +1,18 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const outDir = path.join(root, "dist");
+
+fs.mkdirSync(outDir, { recursive: true });
+fs.writeFileSync(
+  path.join(outDir, "build-manifest.json"),
+  `${JSON.stringify({
+    app: "demo-ai-app",
+    builtAt: new Date().toISOString(),
+    entrypoints: ["src/order-risk.js"],
+  }, null, 2)}\n`,
+);
+
+console.log(`Demo build manifest written to ${path.relative(root, outDir)}`);

package/examples/demo-ai-app/scripts/create-before-state.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ignored = new Set(["node_modules", "dist", "reports"]);
+
+function normalizeForCompare(value) {
+  return path.resolve(value).toLowerCase();
+}
+
+function assertInsideTemp(destination) {
+  const tempRoot = normalizeForCompare(fs.realpathSync(os.tmpdir()));
+  const resolved = normalizeForCompare(destination);
+  if (resolved !== tempRoot && !resolved.startsWith(`${tempRoot}${path.sep}`)) {
+    throw new Error(`Refusing to write demo before-state outside the OS temp directory: ${destination}`);
+  }
+}
+
+function copyDirectory(source, destination) {
+  fs.mkdirSync(destination, { recursive: true });
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    if (ignored.has(entry.name)) continue;
+    const from = path.join(source, entry.name);
+    const to = path.join(destination, entry.name);
+    if (entry.isDirectory()) copyDirectory(from, to);
+    else if (entry.isFile()) fs.copyFileSync(from, to);
+  }
+}
+
+function readOutputArg(args) {
+  const index = args.indexOf("--output");
+  if (index !== -1) return args[index + 1];
+  const inline = args.find((arg) => arg.startsWith("--output="));
+  return inline ? inline.slice("--output=".length) : null;
+}
+
+export function createBeforeState({ outputPath = null } = {}) {
+  const demoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+  const destination = path.resolve(outputPath || path.join(os.tmpdir(), `apm-demo-before-${Date.now()}`));
+  assertInsideTemp(destination);
+
+  fs.rmSync(destination, { recursive: true, force: true });
+  copyDirectory(demoRoot, destination);
+
+  fs.writeFileSync(
+    path.join(destination, "src", "order-risk.js"),
+    `const shippingRates = {
+  standard: 499,
+  expedited: 1299,
+};
+
+export function quoteOrder({ subtotalCents, shippingTier }) {
+  if (!Number.isInteger(subtotalCents) || subtotalCents < 0) {
+    throw new TypeError("subtotalCents must be a non-negative integer");
+  }
+
+  if (!Object.hasOwn(shippingRates, shippingTier)) {
+    throw new RangeError(\`unsupported shipping tier: \${shippingTier}\`);
+  }
+
+  const shippingCents = shippingRates[shippingTier];
+  const totalCents = subtotalCents + shippingCents;
+
+  return {
+    subtotalCents,
+    shippingCents,
+    totalCents,
+    needsManualReview: false,
+  };
+}
+
+export function canReleaseOrder({ paid, flagged }) {
+  return Boolean(paid && !flagged);
+}
+`,
+  );
+
+  return { destination };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const result = createBeforeState({ outputPath: readOutputArg(process.argv.slice(2)) });
+  console.log(JSON.stringify(result, null, 2));
+}

package/examples/demo-ai-app/scripts/run-demo-gate.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { runLocalGate } from "../../../ai-project-maintainer/scripts/run-local-gate.mjs";
+import { toMarkdown } from "../../../ai-project-maintainer/scripts/lib/report.mjs";
+
+function writeMockTool(toolsDir) {
+  const scriptPath = path.join(toolsDir, "mock-tool.mjs");
+  fs.writeFileSync(
+    scriptPath,
+    `#!/usr/bin/env node
+import fs from "node:fs";
+
+const [, , tool, ...args] = process.argv;
+if (args.includes("--version")) {
+  console.log(\`\${tool} demo 0.0.0\`);
+  process.exit(0);
+}
+
+if (tool === "syft") {
+  const outputArg = args.find((arg) => arg.startsWith("cyclonedx-json="));
+  if (outputArg) {
+    fs.writeFileSync(outputArg.slice("cyclonedx-json=".length), JSON.stringify({
+      bomFormat: "CycloneDX",
+      specVersion: "1.5",
+      version: 1,
+      metadata: { component: { type: "application", name: "demo-ai-app" } },
+      components: [],
+    }, null, 2));
+  }
+}
+
+if (tool === "scorecard") {
+  console.log(JSON.stringify({ score: 8.5, checks: [] }));
+}
+
+process.exit(0);
+`,
+  );
+
+  const tools = [
+    "actionlint",
+    "checkov",
+    "gitleaks",
+    "grype",
+    "mega-linter-runner",
+    "osv-scanner",
+    "pre-commit",
+    "scorecard",
+    "semgrep",
+    "squawk",
+    "syft",
+    "trivy",
+    "zizmor",
+  ];
+
+  for (const tool of tools) {
+    if (process.platform === "win32") {
+      fs.writeFileSync(path.join(toolsDir, `${tool}.cmd`), `@echo off\r\nnode "%~dp0mock-tool.mjs" ${tool} %*\r\n`);
+    } else {
+      const shim = path.join(toolsDir, tool);
+      fs.writeFileSync(shim, `#!/usr/bin/env sh\nnode "$(dirname "$0")/mock-tool.mjs" ${tool} "$@"\n`);
+      fs.chmodSync(shim, 0o755);
+    }
+  }
+}
+
+export function runDemoGate({ outputPath = null } = {}) {
+  const demoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+  const reportsDir = path.join(demoRoot, "reports");
+  const toolsDir = fs.mkdtempSync(path.join(os.tmpdir(), "apm-demo-tools-"));
+  writeMockTool(toolsDir);
+
+  const report = runLocalGate(demoRoot, {
+    strict: true,
+    release: true,
+    production: true,
+    outputPath: outputPath || path.join(reportsDir, "security-report.json"),
+    writeReports: true,
+    runnerOptions: {
+      envPath: `${toolsDir}${path.delimiter}${process.env.PATH || ""}`,
+    },
+  });
+
+  return { report, toolsDir };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const { report } = runDemoGate();
+  console.log(toMarkdown(report));
+  process.exit(report.passed ? 0 : 1);
+}

package/examples/demo-ai-app/src/order-risk.js

@@ -0,0 +1,28 @@
+const shippingRates = {
+  standard: 499,
+  expedited: 1299,
+};
+
+export function quoteOrder({ subtotalCents, shippingTier }) {
+  if (!Number.isInteger(subtotalCents) || subtotalCents < 0) {
+    throw new TypeError("subtotalCents must be a non-negative integer");
+  }
+
+  if (!Object.hasOwn(shippingRates, shippingTier)) {
+    throw new RangeError(`unsupported shipping tier: ${shippingTier}`);
+  }
+
+  const shippingCents = shippingRates[shippingTier];
+  const totalCents = subtotalCents + shippingCents;
+
+  return {
+    subtotalCents,
+    shippingCents,
+    totalCents,
+    needsManualReview: totalCents >= 100000,
+  };
+}
+
+export function canReleaseOrder({ paid, flagged, stockAvailable }) {
+  return Boolean(paid && stockAvailable && !flagged);
+}

package/examples/demo-ai-app/test/order-risk.test.mjs

@@ -0,0 +1,24 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { canReleaseOrder, quoteOrder } from "../src/order-risk.js";
+
+test("checkout quote preserves the customer-visible total", () => {
+  assert.deepEqual(quoteOrder({ subtotalCents: 2500, shippingTier: "standard" }), {
+    subtotalCents: 2500,
+    shippingCents: 499,
+    totalCents: 2999,
+    needsManualReview: false,
+  });
+});
+
+test("expensive orders require manual review before release", () => {
+  assert.equal(quoteOrder({ subtotalCents: 99600, shippingTier: "standard" }).needsManualReview, true);
+});
+
+test("orders are released only when payment, stock, and risk checks all pass", () => {
+  assert.equal(canReleaseOrder({ paid: true, stockAvailable: true, flagged: false }), true);
+  assert.equal(canReleaseOrder({ paid: false, stockAvailable: true, flagged: false }), false);
+  assert.equal(canReleaseOrder({ paid: true, stockAvailable: false, flagged: false }), false);
+  assert.equal(canReleaseOrder({ paid: true, stockAvailable: true, flagged: true }), false);
+});

package/package.json

@@ -1,13 +1,44 @@
 {
-  "name": "ai-project-maintainer",
-  "version": "0.3.0",
-  "description": "Production-readiness audit and CI gate for AI-coded projects.",
-  "type": "module",
-  "files": [
-    "ai-project-maintainer/",
-    "docs/",
-    "README.md"
-  ],
+  "name": "ai-project-maintainer",
+  "version": "0.4.0",
+  "description": "Production-readiness audit and CI gate for AI-coded projects.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xixifusi1213-gif/ai-project-maintainer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/xixifusi1213-gif/ai-project-maintainer/issues"
+  },
+  "homepage": "https://github.com/xixifusi1213-gif/ai-project-maintainer#readme",
+  "keywords": [
+    "ai-coding",
+    "devsecops",
+    "security",
+    "production-readiness",
+    "github-actions",
+    "semgrep",
+    "trivy",
+    "gitleaks",
+    "codex",
+    "ai-agents"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "ai-project-maintainer/",
+    "examples/demo-ai-app/.ai-maintainer/",
+    "examples/demo-ai-app/package.json",
+    "examples/demo-ai-app/package-lock.json",
+    "examples/demo-ai-app/README.md",
+    "examples/demo-ai-app/scripts/",
+    "examples/demo-ai-app/src/",
+    "examples/demo-ai-app/test/",
+    "docs/",
+    "README.md"
+  ],
   "bin": {
     "ai-project-maintainer": "ai-project-maintainer/scripts/cli.mjs"
   },