ai-project-maintainer 0.3.1 → 0.4.1

package/docs/PROMOTION.md

@@ -1,6 +1,19 @@
 # Promotion Kit
 
-Use these posts after the repository has README, license, demo, issue templates, and a release.
+Use this after the repository has npm, CI, Security workflow, demo, license, social preview, and a release.
+
+## Account Boundary
+
+I can prepare posts, screenshots, demos, titles, and issue text. Posting to external communities still needs an account controlled by the maintainer.
+
+You do not need every account on day one. Start with channels you can control:
+
+- GitHub README
+- GitHub Release
+- npm package page
+- direct link to the demo case
+
+When you later create accounts for V2EX, Hacker News, Reddit, X/Twitter, Zhihu, or Juejin, reuse the drafts below.
 
 ## GitHub About
 
@@ -25,6 +38,15 @@ gitleaks
 ai-agents
 ```
 
+## Links To Share
+
+```text
+GitHub: https://github.com/xixifusi1213-gif/ai-project-maintainer
+npm: https://www.npmjs.com/package/ai-project-maintainer
+Release: https://github.com/xixifusi1213-gif/ai-project-maintainer/releases/tag/v0.4.1
+Demo case: https://github.com/xixifusi1213-gif/ai-project-maintainer/blob/main/docs/demo-output/before-after-case.md
+```
+
 ## English Short Post
 
 ```text
@@ -32,9 +54,10 @@ I built AI Project Maintainer: a production-readiness gate for AI-coded projects
 
 AI writes code fast, but shipping safely still needs tests, security checks, release evidence, monitoring gaps, and maintainer decisions.
 
-This tool creates a project profile, generates an audit plan, runs local/CI gates, reports production evidence gaps, and lets Codex fix blockers until the release is defensible.
+The demo shows a broken before state, failing business tests, the fixed after state, a production gate report, and a green GitHub Security workflow.
 
 GitHub: https://github.com/xixifusi1213-gif/ai-project-maintainer
+npm: https://www.npmjs.com/package/ai-project-maintainer
 ```
 
 ## Show HN
@@ -42,7 +65,7 @@ GitHub: https://github.com/xixifusi1213-gif/ai-project-maintainer
 Title:
 
 ```text
-Show HN: AI Project Maintainer – production-readiness gate for AI-coded projects
+Show HN: AI Project Maintainer - production-readiness gate for AI-coded projects
 ```
 
 Body:
@@ -54,7 +77,9 @@ The idea is simple: AI can write code quickly, but the hard part is proving a pr
 
 project profile -> audit plan -> local/CI gate -> evidence report -> AI fixes -> rerun
 
-It wraps common tools like Gitleaks, Trivy, Semgrep, OSV-Scanner, Syft, Grype, actionlint, zizmor, and Checkov, but adds a production audit layer. It reports missing monitoring, release approval, database backup/rollback evidence, and business-flow test gaps as explicit GAP or USER_DECISION items.
+It wraps common tools like Gitleaks, Trivy, Semgrep, OSV-Scanner, Syft, Grype, actionlint, and zizmor, but adds a production audit layer. It reports missing monitoring, release approval, database backup/rollback evidence, and business-flow test gaps as explicit GAP or USER_DECISION items.
+
+The repo dogfoods itself with GitHub CI and a heavier Security workflow. There is also a runnable demo app showing a broken before state, failing business tests, the fixed after state, and the production gate report.
 
 It is account-free by default. External APIs can be added later as optional user-provided evidence sources.
 
@@ -66,31 +91,29 @@ Feedback on the workflow and positioning would be very useful.
 ```text
 我做了一个给 AI coding 项目的生产级半自动维护门禁：AI Project Maintainer。
 
-它不是单纯安全扫描器，而是把项目画像、资源清单、审计计划、CI 门禁、生产证据缺口和 AI 修复串成一条链路。
+AI 写代码很快，但上线前仍然需要业务测试、安全扫描、依赖审计、发布证据、监控告警、回滚策略和维护者判断。
+
+这个工具把流程串成一条可重复链路：
 
-流程是：
 项目画像 -> 审计计划 -> 本地/CI 门禁 -> 证据报告 -> Codex 修阻断项 -> 重新运行
 
-它会明确告诉你：
-- 哪些检查通过了
-- 哪些是阻断项
-- 哪些生产证据缺失
-- 哪些需要项目负责人判断
+现在仓库已经有 npm 包、真实 demo、CI badge、Security workflow，并且 demo 展示了 before 状态测试失败、修复后通过、生产 gate 报告 GAP 的完整闭环。
 
 GitHub: https://github.com/xixifusi1213-gif/ai-project-maintainer
+npm: https://www.npmjs.com/package/ai-project-maintainer
 ```
 
-## V2EX / Zhihu Outline
+## V2EX / Zhihu / Juejin Outline
 
 ```text
 标题：我做了一个给 AI coding 项目的生产级半自动维护门禁
 
-1. 背景：AI 写代码变快后，维护、测试、安全和生产证据成了新瓶颈。
+1. 背景：AI 写代码变快后，维护、测试、安全和生产证据成了新的瓶颈。
 2. 问题：个人开发者没有安全团队、SRE、DBA，但仍然要对上线负责。
 3. 方案：把项目画像、审计计划、本地/CI 门禁和生产证据缺口串起来。
-4. Demo：展示 init-audit、audit-plan、gate --production 的输出。
+4. Demo：展示 broken before state、业务测试失败、修复后通过、gate --production 报告。
 5. 边界：不是绝对安全，不替代最终人工审计，不托管用户数据。
-6. 反馈：希望大家提真实项目场景、缺失检查、误报和改进方向。
+6. 想要反馈：真实项目场景、缺失检查、误报、文档可读性、定位是否清楚。
 ```
 
 ## Reddit Targets
@@ -98,6 +121,7 @@ GitHub: https://github.com/xixifusi1213-gif/ai-project-maintainer
 - `r/SideProject`
 - `r/programming`
 - `r/github`
+- `r/devops`
 - `r/LocalLLaMA`
 
 Suggested title:
@@ -108,9 +132,13 @@ I built a production-readiness gate for AI-coded projects
 
 ## Launch Checklist
 
-- [ ] GitHub About description updated.
-- [ ] Topics added.
-- [ ] Social preview uploaded from `assets/social-preview.svg` or a PNG export.
-- [ ] `v0.3.0` release created.
-- [ ] Demo link works.
-- [ ] README first screen explains the value in under 10 seconds.
+- [x] GitHub About description updated.
+- [x] Topics added.
+- [x] Social preview uploaded.
+- [x] npm package published.
+- [x] CI badge is green.
+- [x] Security badge is green.
+- [x] Real demo link works.
+- [x] Before/after case exists.
+- [x] 90-second GIF exported from `docs/demo-output/90-second-demo.html`.
+- [ ] First external post published by the maintainer.

package/docs/SECURITY-WORKFLOW.md

@@ -0,0 +1,63 @@
+# Heavy Security Workflow
+
+`v0.4.1` keeps `.github/workflows/security.yml` as the repository's heavier dogfooding gate and pins scanner versions for more reproducible CI runs.
+
+## 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.
+
+Scanner installers are pinned by environment variables in the workflow. Update those variables deliberately instead of relying on `@latest`.
+
+## 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.1 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,18 +1,30 @@
-# 升级路线图
-
-## v0.4.0：真实案例和重型安全 CI
-
-下一阶段优先增强：
-
-- 新增可复现的 `examples/demo-ai-app`，展示 `FAIL/GAP -> 修复 -> PASS` 的完整闭环。
-- 新增独立 `security.yml`，安装并运行 Gitleaks、Trivy、Semgrep 等真实阻断型扫描。
-- 制作 90 秒 GIF/视频，演示项目画像、审计计划、CI 门禁、证据报告和 AI 修复循环。
-
-`v0.3.1` 只做可信发布补强，不新增重型扫描能力。
-
-## V2：开源维护者专业半自动平台
-
-当前目标：
+# 升级路线图
+
+## 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 脚本兼容。
@@ -24,17 +36,6 @@
 
 V2 仍然免账号优先，不依赖 Bytebase、云、K8s、Sentry 或 Grafana。
 
-## V2 后续增强
-
-优先增强：
-
-- GitHub Action 独立发布，减少 workflow 中的安装成本。
-- OpenSSF Scorecard 更细粒度解析。
-- MegaLinter profile 配置模板。
-- pre-commit 官方 hook 模板。
-- SARIF 更精确定位到文件和行。
-- 报告转 GitHub PR comment。
-
 ## V3：平台证据接入
 
 可选接入：
@@ -44,7 +45,7 @@ V2 仍然免账号优先，不依赖 Bytebase、云、K8s、Sentry 或 Grafana
 - 云平台：IAM、网络、安全组、公开入口。
 - Kubernetes：RBAC、NetworkPolicy、PodSecurity、镜像和运行时风险。
 
-这些能力需要账号或只读 token，所以不作为 V2 硬依赖。
+这些能力需要账号或只读 token，所以不作为默认硬依赖。
 
 ## 不做
 

package/docs/demo-output/90-second-demo.html

@@ -0,0 +1,187 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>AI Project Maintainer 90-second demo</title>
+    <style>
+      :root {
+        color-scheme: dark;
+        font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+        background: #0f172a;
+        color: #f8fafc;
+      }
+
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: grid;
+        place-items: center;
+        background:
+          radial-gradient(circle at 82% 18%, rgba(20, 184, 166, 0.28), transparent 28rem),
+          linear-gradient(135deg, #0f172a 0%, #111827 52%, #134e4a 100%);
+      }
+
+      main {
+        width: min(1120px, calc(100vw - 56px));
+        aspect-ratio: 16 / 9;
+        position: relative;
+        overflow: hidden;
+        border: 1px solid #334155;
+        border-radius: 24px;
+        background: rgba(17, 24, 39, 0.93);
+        box-shadow: 0 30px 80px rgba(0, 0, 0, 0.36);
+      }
+
+      header {
+        position: absolute;
+        inset: 48px 64px auto;
+      }
+
+      h1 {
+        margin: 0 0 10px;
+        font-size: 48px;
+        letter-spacing: 0;
+      }
+
+      .subtitle {
+        margin: 0;
+        color: #bae6fd;
+        font-size: 24px;
+        font-weight: 700;
+      }
+
+      .slide {
+        position: absolute;
+        inset: 190px 64px 90px;
+        opacity: 0;
+        animation: show 90s linear infinite;
+      }
+
+      .slide:nth-of-type(1) { animation-delay: 0s; }
+      .slide:nth-of-type(2) { animation-delay: 15s; }
+      .slide:nth-of-type(3) { animation-delay: 30s; }
+      .slide:nth-of-type(4) { animation-delay: 45s; }
+      .slide:nth-of-type(5) { animation-delay: 60s; }
+      .slide:nth-of-type(6) { animation-delay: 75s; }
+
+      @keyframes show {
+        0%, 15% { opacity: 1; transform: translateY(0); }
+        16%, 100% { opacity: 0; transform: translateY(18px); }
+      }
+
+      h2 {
+        margin: 0 0 28px;
+        font-size: 34px;
+      }
+
+      code, .terminal {
+        font-family: "Cascadia Code", "SFMono-Regular", Consolas, monospace;
+      }
+
+      .terminal {
+        padding: 24px;
+        border: 1px solid #475569;
+        border-radius: 16px;
+        background: #020617;
+        color: #e5e7eb;
+        font-size: 22px;
+        line-height: 1.6;
+      }
+
+      .pass { color: #34d399; }
+      .fail { color: #fb7185; }
+      .gap { color: #fbbf24; }
+      .muted { color: #94a3b8; }
+
+      .progress {
+        position: absolute;
+        left: 64px;
+        right: 64px;
+        bottom: 44px;
+        height: 12px;
+        border-radius: 999px;
+        background: #334155;
+        overflow: hidden;
+      }
+
+      .progress::before {
+        content: "";
+        display: block;
+        height: 100%;
+        background: #38bdf8;
+        transform-origin: left;
+        animation: progress 90s linear infinite;
+      }
+
+      @keyframes progress {
+        from { transform: scaleX(0); }
+        to { transform: scaleX(1); }
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <header>
+        <h1>AI Project Maintainer</h1>
+        <p class="subtitle">90-second production-readiness demo for AI-coded projects</p>
+      </header>
+
+      <section class="slide">
+        <h2>1. Start with project profile</h2>
+        <div class="terminal">
+          npx ai-project-maintainer init-audit .\examples\demo-ai-app<br />
+          <span class="muted">project facts -> business flows -> evidence sources -> risk policy</span>
+        </div>
+      </section>
+
+      <section class="slide">
+        <h2>2. Before state: behavior is broken</h2>
+        <div class="terminal">
+          node .\examples\demo-ai-app\scripts\create-before-state.mjs<br />
+          <span class="fail">FAIL</span> expensive orders require manual review<br />
+          <span class="fail">FAIL</span> orders cannot release without stock
+        </div>
+      </section>
+
+      <section class="slide">
+        <h2>3. Fix deterministic blockers</h2>
+        <div class="terminal">
+          npm test --prefix .\examples\demo-ai-app<br />
+          <span class="pass">PASS</span> checkout quote preserves customer-visible total<br />
+          <span class="pass">PASS</span> order release respects payment, stock, and risk
+        </div>
+      </section>
+
+      <section class="slide">
+        <h2>4. Run production gate</h2>
+        <div class="terminal">
+          npx ai-project-maintainer gate . --production --strict --release<br />
+          <span class="pass">PASS</span> tests, build, secrets, dependencies, SAST, CI<br />
+          <span class="gap">GAP</span> approval, monitoring, logs, metrics, alerts
+        </div>
+      </section>
+
+      <section class="slide">
+        <h2>5. Produce evidence report</h2>
+        <div class="terminal">
+          reports/security-report.json<br />
+          reports/security-report.md<br />
+          reports/security-report.sarif<br />
+          reports/sbom.cdx.json
+        </div>
+      </section>
+
+      <section class="slide">
+        <h2>6. Dogfood in GitHub Actions</h2>
+        <div class="terminal">
+          <span class="pass">CI: green</span><br />
+          <span class="pass">Security: green</span><br />
+          <span class="muted">Gitleaks / Trivy / Semgrep / OSV / Syft / Grype / actionlint / zizmor</span>
+        </div>
+      </section>
+
+      <div class="progress" aria-hidden="true"></div>
+    </main>
+  </body>
+</html>

package/docs/demo-output/before-after-case.md

@@ -0,0 +1,91 @@
+# Before/After Case: Demo AI App
+
+This case uses the real runnable project in `examples/demo-ai-app`.
+
+It is intentionally small, but it exercises the complete maintenance loop:
+
+```text
+broken behavior -> test failure -> fixed behavior -> production gate -> evidence gaps -> CI security workflow
+```
+
+## Project
+
+`examples/demo-ai-app` is a Node.js order-risk module with two business-critical rules:
+
+- customer-visible totals must include shipping exactly once
+- an order can be released only when payment, stock, and risk checks all pass
+
+## Before
+
+Generate a broken copy outside the repository:
+
+```powershell
+node .\examples\demo-ai-app\scripts\create-before-state.mjs
+```
+
+Run tests inside the printed temp directory:
+
+```powershell
+npm test
+```
+
+Expected failures:
+
+```text
+FAIL expensive orders require manual review before release
+FAIL orders are released only when payment, stock, and risk checks all pass
+```
+
+This shows the exact problem the tool is meant to catch: AI-coded changes can look plausible while breaking release-critical behavior.
+
+## After
+
+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
+```
+
+Expected result:
+
+```text
+Local Security Gate: PASS_WITH_GAPS
+Blocking Checks: None
+Open Source Maintenance Score: 75/100 (B)
+```
+
+The gate still reports production evidence gaps:
+
+```text
+GAP Production release approval
+GAP Error monitoring
+GAP Production logs
+GAP Production metrics
+GAP Production alerts
+```
+
+That distinction is the core value:
+
+- checked failures block release
+- missing production evidence is visible
+- maintainers keep ownership of business decisions
+- Codex can fix deterministic blockers and rerun the gate
+
+## GitHub Evidence
+
+The repository dogfoods the workflow:
+
+- CI workflow: tests, syntax checks, package validation, smoke gate
+- Security workflow: Gitleaks, Trivy, Semgrep, OSV-Scanner, Syft, Grype, actionlint, zizmor, OpenSSF Scorecard, production gate
+
+Use this case when posting about the project:
+
+```text
+I built a production-readiness gate for AI-coded projects.
+
+The demo shows a broken AI-coded before state, failing business tests, the fixed after state, a production gate report, and a green GitHub Security workflow.
+
+GitHub: https://github.com/xixifusi1213-gif/ai-project-maintainer
+```

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

@@ -1,8 +1,8 @@
-# Local Security Gate: PASS
+# Local Security Gate: PASS_WITH_GAPS
 
-Root: `example/ai-coded-project`
+Root: `examples/demo-ai-app`
 Mode: strict=true, release=true, production=true
-Open Source Maintenance Score: 82/100 (B)
+Open Source Maintenance Score: 75/100 (B)
 
 ## Blocking Checks
 
@@ -10,48 +10,56 @@ Open Source Maintenance Score: 82/100 (B)
 
 ## Warnings
 
-- production audit: Critical business flows: USER_DECISION. The maintainer must declare the business flows that must not break.
+- 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 release approval: GAP. No production deployment approval evidence declared.
+- 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
 
-- 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 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: web
-Database: true
+Project Type: node
+Database: false
 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`.
+- 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
+
+- No blocking checks failed, but release-readiness gaps remain.
+- Add real release approval, monitoring, logs, metrics, and alerts evidence, or explicitly accept those gaps before release.
+- Rerun `gate --production --strict --release`.