ai-project-maintainer 0.4.0 → 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

@@ -1,61 +1,63 @@
-# 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
-
+# 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.
 
-## 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.
+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,58 +1,58 @@
-# 升级路线图
-
-## 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 替代维护者的最终判断。
+# 升级路线图
+
+## 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/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
+```