ai-project-maintainer 0.3.1 → 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,74 +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.
+This demo uses the runnable project in `examples/demo-ai-app`. It does not require any paid account or external API.
 
-## 1. Initialize The Project
+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
-npx ai-project-maintainer init "E:\my-project" --profile oss --ci github
+npm test --prefix .\examples\demo-ai-app
+npm run build --prefix .\examples\demo-ai-app
 ```
 
-This creates the local policy, exceptions file, GitHub Actions workflow, Dependabot config, and report directory.
+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. Create Production Audit Intake
+## 2. Generate A Broken Before State
 
 ```powershell
-npx ai-project-maintainer init-audit "E:\my-project"
+node .\examples\demo-ai-app\scripts\create-before-state.mjs
 ```
 
-This creates:
+The command prints a temporary directory. Run this in that copied project:
 
-```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
+```powershell
+npm test
 ```
 
-These files record project facts and evidence locations. They should not contain tokens, DSNs, passwords, or production secrets.
+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. Generate An Audit Plan
+## 3. Run The Reproducible Demo Gate
 
 ```powershell
-npx ai-project-maintainer audit-plan "E:\my-project" --output reports/audit-plan.json
+node .\examples\demo-ai-app\scripts\run-demo-gate.mjs
 ```
 
-Example output:
+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.
 
-```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.
-```
+Expected result:
 
-The point is not to pretend the project is safe. The point is to make missing production evidence visible.
+```text
+Local Security Gate: PASS_WITH_GAPS
+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).
+`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 Production Gate
+## 4. Run The Real 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:
+After installing scanner CLIs, use the same command a real project would use:
 
-```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.
+```powershell
+npx ai-project-maintainer gate .\examples\demo-ai-app --production --strict --release --output reports/security-report.json
 ```
 
-See [sample report](demo-output/security-report.md).
+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
 

package/docs/DEMO.zh-CN.md

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