ai-project-maintainer 0.4.0 → 0.4.1

package/ai-project-maintainer/scripts/lib/report.mjs

@@ -17,7 +17,7 @@ function gradeForScore(score) {
   return "F";
 }
 
-function buildMaintenanceSummary({ blockers, warnings, coverageGaps, invalidExceptions }) {
+function buildMaintenanceSummary({ blockers, warnings, coverageGaps, invalidExceptions }) {
   const score = Math.max(
     0,
     Math.min(100, 100 - blockers.length * 25 - warnings.length * 3 - coverageGaps.length * 2 - invalidExceptions.length * 20),
@@ -31,10 +31,17 @@ function buildMaintenanceSummary({ blockers, warnings, coverageGaps, invalidExce
       coverageGaps: coverageGaps.length,
       invalidExceptions: invalidExceptions.length,
     },
-  };
-}
-
-export function buildJsonReport({
+  };
+}
+
+function buildOverallStatus({ blockers, warnings, coverageGaps, invalidExceptions, userDecisionCount }) {
+  if (blockers.length || invalidExceptions.length) return "FAIL";
+  if (coverageGaps.length || userDecisionCount > 0) return "PASS_WITH_GAPS";
+  if (warnings.length) return "PASS_WITH_WARNINGS";
+  return "PASS";
+}
+
+export function buildJsonReport({
   root,
   mode,
   probe,
@@ -44,19 +51,26 @@ export function buildJsonReport({
   invalidExceptions = [],
   generatedAt = new Date().toISOString(),
 }) {
-  const blockers = checks.filter((check) => check.blocking);
-  const warnings = checks.filter((check) => !check.blocking && ["fail", "error", "missing", "skipped", "gap", "user_decision"].includes(statusKey(check.status)));
-  const coverageGaps = checks.filter((check) => check.coverageGap || ["missing", "skipped", "gap"].includes(statusKey(check.status)));
-  const exceptionUsage = checks.filter((check) => check.exception).map((check) => ({
-    check: check.name,
-    exception: check.exception,
-  }));
-
-  return {
-    schemaVersion: 1,
-    root,
-    mode,
-    passed: blockers.length === 0 && invalidExceptions.length === 0,
+  const blockers = checks.filter((check) => check.blocking);
+  const warnings = checks.filter((check) => !check.blocking && ["fail", "error", "missing", "skipped", "gap", "user_decision"].includes(statusKey(check.status)));
+  const coverageGaps = checks.filter((check) => check.coverageGap || ["missing", "skipped", "gap"].includes(statusKey(check.status)));
+  const userDecisionCount = checks.filter((check) => statusKey(check.status) === "user_decision").length + (audit?.userDecisions || []).length;
+  const exceptionUsage = checks.filter((check) => check.exception).map((check) => ({
+    check: {
+      checkId: check.checkId || null,
+      name: check.name,
+      group: check.group,
+    },
+    exception: check.exception,
+  }));
+  const overallStatus = buildOverallStatus({ blockers, warnings, coverageGaps, invalidExceptions, userDecisionCount });
+
+  return {
+    schemaVersion: 1,
+    root,
+    mode,
+    overallStatus,
+    passed: blockers.length === 0 && invalidExceptions.length === 0,
     blockerCount: blockers.length + invalidExceptions.length,
     warningCount: warnings.length,
     coverageGapCount: coverageGaps.length,
@@ -76,9 +90,10 @@ export function buildJsonReport({
   };
 }
 
-export function toMarkdown(report) {
-  const lines = [];
-  lines.push(`# Local Security Gate: ${report.passed ? "PASS" : "FAIL"}`);
+export function toMarkdown(report) {
+  const lines = [];
+  const overallStatus = report.overallStatus || (report.passed ? "PASS" : "FAIL");
+  lines.push(`# Local Security Gate: ${overallStatus}`);
   lines.push("");
   lines.push(`Root: ${report.root}`);
   lines.push(`Mode: strict=${Boolean(report.mode?.strict)}, release=${Boolean(report.mode?.release)}, production=${Boolean(report.mode?.production)}`);
@@ -154,20 +169,29 @@ export function toMarkdown(report) {
   }
   lines.push("");
 
-  lines.push("## Exceptions");
-  if (!report.exceptions.used.length && !report.exceptions.invalid.length) lines.push("- None");
-  for (const item of report.exceptions.used) {
-    lines.push(`- ${item.exception.id}: applied to ${item.check}, expires ${item.exception.expires}`);
-  }
+  lines.push("## Exceptions");
+  if (!report.exceptions.used.length && !report.exceptions.invalid.length) lines.push("- None");
+  for (const item of report.exceptions.used) {
+    const checkName = typeof item.check === "string" ? item.check : `${item.check.checkId || item.check.name} (${item.check.group})`;
+    lines.push(`- ${item.exception.id}: applied to ${checkName}, expires ${item.exception.expires}`);
+  }
   for (const item of report.exceptions.invalid) {
     lines.push(`- ${item.id || "(missing id)"}: invalid, ${item.reason}`);
   }
-  lines.push("");
-
-  lines.push("## Next Step");
-  lines.push(report.passed ? "- Gate passed. Keep this command in CI before release." : "- Fix blocking checks or add narrow, owner-approved exceptions, then rerun the gate.");
-  return lines.join("\n");
-}
+  lines.push("");
+
+  lines.push("## Next Step");
+  if (!report.passed) {
+    lines.push("- Fix blocking checks or add narrow, owner-approved exceptions, then rerun the gate.");
+  } else if (overallStatus === "PASS_WITH_GAPS") {
+    lines.push("- No blocking checks failed, but release-readiness gaps or user decisions remain. Fill evidence, accept risk explicitly, or enable block_on_coverage_gaps before release.");
+  } else if (overallStatus === "PASS_WITH_WARNINGS") {
+    lines.push("- Gate has no blockers or release-readiness gaps. Review warnings, then keep this command in CI before release.");
+  } else {
+    lines.push("- Gate passed without blockers, warnings, or release-readiness gaps. Keep this command in CI before release.");
+  }
+  return lines.join("\n");
+}
 
 export function toSarif(report) {
   const rules = new Map();

package/assets/demo-90s-storyboard.svg

@@ -0,0 +1,98 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="720" viewBox="0 0 1280 720" role="img" aria-labelledby="title desc">
+  <title id="title">AI Project Maintainer 90-second demo storyboard</title>
+  <desc id="desc">Animated storyboard showing project profile, broken before state, fixed tests, production gate, evidence report, and security workflow.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" x2="1" y1="0" y2="1">
+      <stop offset="0" stop-color="#0f172a"/>
+      <stop offset="0.55" stop-color="#111827"/>
+      <stop offset="1" stop-color="#0f766e"/>
+    </linearGradient>
+    <style>
+      .label { font: 700 48px system-ui, -apple-system, Segoe UI, sans-serif; fill: #f8fafc; }
+      .subtitle { font: 600 25px system-ui, -apple-system, Segoe UI, sans-serif; fill: #bae6fd; }
+      .body { font: 600 27px ui-monospace, SFMono-Regular, Consolas, monospace; fill: #e5e7eb; }
+      .muted { font: 600 21px system-ui, -apple-system, Segoe UI, sans-serif; fill: #94a3b8; }
+      .pass { fill: #34d399; }
+      .fail { fill: #fb7185; }
+      .gap { fill: #fbbf24; }
+      .panel { opacity: 0; animation: reveal 90s linear infinite; }
+      #s1 { animation-delay: 0s; }
+      #s2 { animation-delay: 15s; }
+      #s3 { animation-delay: 30s; }
+      #s4 { animation-delay: 45s; }
+      #s5 { animation-delay: 60s; }
+      #s6 { animation-delay: 75s; }
+      @keyframes reveal {
+        0%, 15% { opacity: 1; }
+        16%, 100% { opacity: 0; }
+      }
+      .bar { animation: progress 90s linear infinite; transform-origin: 120px 642px; }
+      @keyframes progress {
+        from { transform: scaleX(0); }
+        to { transform: scaleX(1); }
+      }
+    </style>
+  </defs>
+
+  <rect width="1280" height="720" fill="url(#bg)"/>
+  <rect x="72" y="56" width="1136" height="560" rx="28" fill="#111827" opacity="0.93" stroke="#334155" stroke-width="2"/>
+  <text x="120" y="124" class="label">AI Project Maintainer</text>
+  <text x="120" y="168" class="subtitle">90-second production-readiness demo for AI-coded projects</text>
+
+  <g id="s1" class="panel">
+    <text x="120" y="245" class="body">1. Start with project profile</text>
+    <text x="120" y="304" class="body">npx ai-project-maintainer init-audit .\examples\demo-ai-app</text>
+    <text x="120" y="365" class="muted">The maintainer declares project facts, business flows, evidence sources, and risk policy.</text>
+    <rect x="120" y="420" width="210" height="56" rx="12" fill="#0f766e"/>
+    <text x="146" y="456" class="body">PROFILE</text>
+    <rect x="360" y="420" width="210" height="56" rx="12" fill="#1d4ed8"/>
+    <text x="386" y="456" class="body">EVIDENCE</text>
+    <rect x="600" y="420" width="210" height="56" rx="12" fill="#6d28d9"/>
+    <text x="626" y="456" class="body">POLICY</text>
+  </g>
+
+  <g id="s2" class="panel">
+    <text x="120" y="245" class="body">2. Before state: behavior is broken</text>
+    <text x="120" y="304" class="body">node .\examples\demo-ai-app\scripts\create-before-state.mjs</text>
+    <text x="120" y="365" class="body fail">FAIL expensive orders require manual review</text>
+    <text x="120" y="410" class="body fail">FAIL orders cannot release without stock</text>
+    <text x="120" y="470" class="muted">No fake secrets are committed. The bad copy lives only under the OS temp directory.</text>
+  </g>
+
+  <g id="s3" class="panel">
+    <text x="120" y="245" class="body">3. Fix deterministic blockers</text>
+    <text x="120" y="304" class="body">npm test --prefix .\examples\demo-ai-app</text>
+    <text x="120" y="365" class="body pass">PASS checkout quote preserves customer-visible total</text>
+    <text x="120" y="410" class="body pass">PASS expensive orders require manual review</text>
+    <text x="120" y="455" class="body pass">PASS paid order release respects payment, stock, and risk</text>
+  </g>
+
+  <g id="s4" class="panel">
+    <text x="120" y="245" class="body">4. Run production gate</text>
+    <text x="120" y="304" class="body">npx ai-project-maintainer gate . --production --strict --release</text>
+    <text x="120" y="365" class="body pass">PASS tests, build, secrets, dependencies, SAST, CI checks</text>
+    <text x="120" y="410" class="body gap">GAP release approval, monitoring, logs, metrics, alerts</text>
+    <text x="120" y="470" class="muted">Checked failures block. Missing production evidence stays visible by default.</text>
+  </g>
+
+  <g id="s5" class="panel">
+    <text x="120" y="245" class="body">5. Produce evidence report</text>
+    <text x="120" y="304" class="body">reports/security-report.json</text>
+    <text x="120" y="349" class="body">reports/security-report.md</text>
+    <text x="120" y="394" class="body">reports/security-report.sarif</text>
+    <text x="120" y="439" class="body">reports/sbom.cdx.json</text>
+    <text x="120" y="500" class="muted">Codex can fix blockers, rerun, and leave maintainer decisions explicit.</text>
+  </g>
+
+  <g id="s6" class="panel">
+    <text x="120" y="245" class="body">6. Dogfood in GitHub Actions</text>
+    <text x="120" y="304" class="body pass">CI: green</text>
+    <text x="120" y="349" class="body pass">Security: green</text>
+    <text x="120" y="394" class="body">Gitleaks / Trivy / Semgrep / OSV / Syft / Grype / actionlint / zizmor</text>
+    <text x="120" y="470" class="subtitle">Let AI write fast. Make release readiness explicit.</text>
+  </g>
+
+  <rect x="120" y="642" width="1040" height="12" rx="6" fill="#334155"/>
+  <rect class="bar" x="120" y="642" width="1040" height="12" rx="6" fill="#38bdf8"/>
+  <text x="120" y="684" class="muted">project profile -> before failure -> fixed tests -> production gate -> evidence report -> CI security</text>
+</svg>

package/assets/social-preview.svg

@@ -0,0 +1,55 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="640" viewBox="0 0 1280 640" role="img" aria-labelledby="title desc">
+  <title id="title">AI Project Maintainer</title>
+  <desc id="desc">Production-readiness gate for AI-coded projects</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#0f172a"/>
+      <stop offset="58%" stop-color="#111827"/>
+      <stop offset="100%" stop-color="#0f766e"/>
+    </linearGradient>
+    <linearGradient id="accent" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#38bdf8"/>
+      <stop offset="55%" stop-color="#2dd4bf"/>
+      <stop offset="100%" stop-color="#a7f3d0"/>
+    </linearGradient>
+    <marker id="arrow" markerWidth="12" markerHeight="12" refX="9" refY="6" orient="auto" markerUnits="strokeWidth">
+      <path d="M2 2 L10 6 L2 10 Z" fill="#5eead4"/>
+    </marker>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="20" stdDeviation="24" flood-color="#000000" flood-opacity="0.35"/>
+    </filter>
+  </defs>
+  <rect width="1280" height="640" fill="url(#bg)"/>
+  <path d="M0 514 C210 448 322 575 520 501 C768 408 882 521 1280 390 L1280 640 L0 640 Z" fill="#0b1220" opacity="0.52"/>
+  <rect x="72" y="70" width="1136" height="500" rx="34" fill="#0b1020" opacity="0.72" filter="url(#shadow)"/>
+  <rect x="100" y="98" width="1080" height="444" rx="24" fill="#111827" stroke="#334155" stroke-width="2"/>
+
+  <text x="152" y="178" fill="#e5f7ff" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="64" font-weight="800" letter-spacing="0">AI Project Maintainer</text>
+  <text x="154" y="236" fill="#bae6fd" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="33" font-weight="650" letter-spacing="0">Production-readiness gate for AI-coded projects</text>
+  <rect x="154" y="278" width="972" height="4" rx="2" fill="url(#accent)"/>
+
+  <g font-family="Inter, Segoe UI, Arial, sans-serif" font-size="27" font-weight="750" text-anchor="middle">
+    <rect x="154" y="336" width="208" height="76" rx="18" fill="#172554" stroke="#38bdf8" stroke-width="2"/>
+    <text x="258" y="383" fill="#dbeafe">Project profile</text>
+
+    <line x1="386" y1="374" x2="424" y2="374" stroke="#5eead4" stroke-width="4" stroke-linecap="round" marker-end="url(#arrow)"/>
+
+    <rect x="448" y="336" width="178" height="76" rx="18" fill="#134e4a" stroke="#2dd4bf" stroke-width="2"/>
+    <text x="537" y="383" fill="#ccfbf1">Audit plan</text>
+
+    <line x1="650" y1="374" x2="688" y2="374" stroke="#5eead4" stroke-width="4" stroke-linecap="round" marker-end="url(#arrow)"/>
+
+    <rect x="712" y="336" width="150" height="76" rx="18" fill="#1e293b" stroke="#94a3b8" stroke-width="2"/>
+    <text x="787" y="383" fill="#e2e8f0">CI gate</text>
+
+    <line x1="886" y1="374" x2="924" y2="374" stroke="#5eead4" stroke-width="4" stroke-linecap="round" marker-end="url(#arrow)"/>
+
+    <rect x="948" y="336" width="216" height="76" rx="18" fill="#064e3b" stroke="#34d399" stroke-width="2"/>
+    <text x="1056" y="383" fill="#d1fae5">Evidence report</text>
+  </g>
+
+  <g font-family="Inter, Segoe UI, Arial, sans-serif" font-weight="650">
+    <text x="154" y="472" fill="#cbd5e1" font-size="24" letter-spacing="0">PASS / FAIL / WARN / GAP / N/A / USER_DECISION</text>
+    <text x="154" y="510" fill="#94a3b8" font-size="23" letter-spacing="0">Let AI write fast. Make release readiness explicit.</text>
+  </g>
+</svg>

package/docs/DEMO.md

@@ -1,69 +1,76 @@
-# 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:
-
+# 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.
+
+Visual materials:
+
+- [90-second GIF storyboard](../assets/demo-90s.gif)
+- [90-second browser demo](demo-output/90-second-demo.html)
+- [Before/after case](demo-output/before-after-case.md)
+
+## 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
+Local Security Gate: PASS_WITH_GAPS
 Blocking Checks: None
 Coverage Gaps:
 - Production release approval
 - Error monitoring
-- Production logs
-- Production metrics
-- Production alerts
+- 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.
+`PASS_WITH_GAPS` means deterministic blockers are clear, but production evidence still needs to be filled in or explicitly accepted before release.
+
+## 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,69 +1,75 @@
-# 演示：从 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 适合处理确定性的阻断项。维护者仍然负责业务决策、风险接受和生产证据确认。
+# 演示：从 AI 写出的项目到生产审查报告
+
+这个演示使用仓库里的真实项目：`examples/demo-ai-app`。不需要付费账号，也不需要外部 API。
+
+演示素材：
+
+- [90 秒 GIF 故事板](../assets/demo-90s.gif)
+- [90 秒浏览器演示页](demo-output/90-second-demo.html)
+- [before/after 案例](demo-output/before-after-case.md)
+
+## 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_WITH_GAPS
+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/GITHUB-LAUNCH-CHECKLIST.md

@@ -31,17 +31,17 @@ ai-agents
 
 Upload a social preview image in repository settings.
 
-Recommended source:
-
-```text
-assets/social-preview.png
-```
-
-Editable source:
-
-```text
-assets/social-preview.svg
-```
+Recommended source:
+
+```text
+assets/social-preview.png
+```
+
+Editable source:
+
+```text
+assets/social-preview.svg
+```
 
 If GitHub asks for PNG/JPG, export the SVG to PNG at `1280x640`.
 

package/docs/POLICY-AND-EXCEPTIONS.zh-CN.md

@@ -58,7 +58,7 @@ warn_on:
 ```yaml
 exceptions:
   - id: "example-dev-only-vuln"
-    check: "npm audit"
+    check: "package-audit"
     reason: "dev-only transitive dependency, not shipped"
     expires: "2026-09-01"
     owner: "repo-owner"