ai-project-maintainer 0.3.0

package/docs/INTAKE-SCHEMA.zh-CN.md

@@ -0,0 +1,105 @@
+# Intake 配置说明
+
+`init-audit` 生成的文件用于告诉工具“这个项目是什么、有哪些资源、哪些风险需要重点审”。公开用户不需要提供所有资源，缺失项会作为 `GAP` 写入报告。
+
+## project-profile.yml
+
+```yaml
+schema_version: 1
+project:
+  name: ""
+  type: auto
+  lifecycle: development
+  production: false
+risk:
+  handles_auth: false
+  handles_sensitive_data: false
+  handles_payments: false
+  handles_financial_data: false
+  handles_health_data: false
+  has_database: auto
+  has_deployment: false
+  has_user_generated_content: false
+```
+
+建议：
+
+- `type` 可以保持 `auto`，工具会自动识别 Electron、Web、API、Node 或通用项目。
+- `has_database` 可以保持 `auto`，工具会根据 migration、Prisma、Drizzle、SQL 等文件推断。
+- 涉及登录、权限、支付、财务、隐私数据时，要把对应字段改为 `true`。
+
+## evidence-sources.yml
+
+```yaml
+schema_version: 1
+evidence:
+  github_actions: auto
+  deployment:
+    provider: none
+    has_staging: false
+    has_production: false
+    production_requires_approval: false
+  observability:
+    errors: none
+    logs: none
+    metrics: none
+    alerts: none
+  database:
+    migrations: auto
+    review_tool: none
+    backup_policy: none
+    rollback_plan: none
+```
+
+这里不要写密钥。只写证据类型，例如：
+
+```yaml
+observability:
+  errors: sentry
+  logs: vercel
+  metrics: grafana
+  alerts: email
+```
+
+## business-flows.yml
+
+把核心业务流程写成可审查条目：
+
+```yaml
+business_flows:
+  - id: save-project
+    name: 保存项目
+    criticality: high
+    expected_behavior: 保存后重启应用，数据必须保持一致。
+    tests:
+      - test/save-project.test.mjs
+```
+
+如果没有填写真实流程，报告会给出 `USER_DECISION`。
+
+## risk-policy.yml
+
+默认：
+
+```yaml
+production:
+  block_on_coverage_gaps: false
+  block_on_user_decisions: false
+  require_intake: false
+```
+
+如果你希望生产证据缺口也直接失败：
+
+```yaml
+production:
+  block_on_coverage_gaps: true
+```
+
+## 状态含义
+
+- `PASS`：已检查并通过。
+- `FAIL`：已检查并失败。
+- `WARN`：有风险但默认不阻断。
+- `GAP`：缺少证据，无法判断。
+- `N/A`：该项目不适用。
+- `USER_DECISION`：需要项目负责人判断。

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

@@ -0,0 +1,96 @@
+# Policy 和 Exceptions
+
+## Policy
+
+项目策略文件：
+
+```text
+.ai-maintainer/policy.yml
+```
+
+V2 默认策略面向开源项目维护者：
+
+```yaml
+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
+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
+```
+
+`checks` 支持三个级别：
+
+- `block`：失败会阻断门禁。
+- `warn`：失败或缺失只进入警告和维护分，不阻断。
+- `off`：关闭该检查。
+
+## Exceptions
+
+例外文件：
+
+```text
+.ai-maintainer/exceptions.yml
+```
+
+格式：
+
+```yaml
+exceptions:
+  - id: "example-dev-only-vuln"
+    check: "npm audit"
+    reason: "dev-only transitive dependency, not shipped"
+    expires: "2026-09-01"
+    owner: "repo-owner"
+```
+
+必须包含：
+
+- `id`
+- `check`
+- `reason`
+- `expires`
+- `owner`
+
+## 规则
+
+- 过期例外视为失败。
+- 缺字段例外视为失败。
+- 例外只能降级指定 finding，不能关闭整个工具。
+- 例外使用情况会写入 JSON 和 Markdown 报告。
+
+## 建议
+
+适合例外：
+
+- dev-only 传递依赖漏洞，确认不随产品发布。
+- 明确误报，并有理由和负责人。
+- 上游暂未修复，但有临时缓解措施和短过期时间。
+
+不适合例外：
+
+- 真实 secret 泄露。
+- 生产依赖高危漏洞且没有缓解措施。
+- 测试或构建失败。
+- Electron 危险 IPC 或危险 webPreferences。
+- 严格模式下 Trivy 数据库不可用。

package/docs/PRODUCTION-AUDIT.zh-CN.md

@@ -0,0 +1,89 @@
+# 生产级半自动审查流程
+
+这个流程面向个人开发者和 AI 协作维护生产级项目。目标不是证明项目绝对安全，而是把专业审查拆成可执行的证据链：
+
+```text
+项目画像 -> 资源清单 -> 审计计划 -> 门禁检查 -> AI 修复 -> 用户审批
+```
+
+## 1. 生成审查画像
+
+```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 或云凭证。
+
+## 2. 生成审计计划
+
+```powershell
+npx ai-project-maintainer audit-plan "E:\我的项目" --output reports/audit-plan.json
+```
+
+审计计划会说明：
+
+- 哪些检查适用于当前项目。
+- 哪些检查不适用，标记为 `N/A`。
+- 哪些证据缺失，标记为 `GAP`。
+- 哪些事项必须由项目负责人判断，标记为 `USER_DECISION`。
+
+## 3. 执行生产门禁
+
+```powershell
+npx ai-project-maintainer gate "E:\我的项目" --production --strict --release --output reports/security-report.json
+```
+
+生产门禁会继续运行原有安全门禁，并额外加入生产准备度证据：
+
+- 核心业务流程和测试覆盖。
+- CI 和发布审批。
+- 错误监控、日志、指标、告警。
+- 数据库迁移、备份、回滚或 forward-fix。
+- Electron IPC、preload、文件权限和更新机制。
+
+## 4. 如何理解结果
+
+- `PASS`：已检查并通过。
+- `FAIL`：已检查并失败。
+- `WARN`：有风险但默认不阻断。
+- `GAP`：缺少证据，无法判断。
+- `N/A`：该项目不适用。
+- `USER_DECISION`：需要项目负责人判断。
+
+默认情况下，`GAP` 不阻断；它代表“证据不足”，不是“安全”。如果你要把生产证据缺口作为硬门禁，设置：
+
+```yaml
+production:
+  block_on_coverage_gaps: true
+```
+
+## 5. 用户和 AI 的分工
+
+用户负责：
+
+- 定义核心业务流程。
+- 判断哪些风险不能接受。
+- 提供只读证据来源或说明。
+- 审批发布和例外。
+
+AI/Codex 负责：
+
+- 读取画像和审计计划。
+- 执行检查。
+- 修复阻断项。
+- 重新运行门禁。
+- 把缺口写成报告和下一步清单。

package/docs/PROMOTION.md

@@ -0,0 +1,116 @@
+# Promotion Kit
+
+Use these posts after the repository has README, license, demo, issue templates, and a release.
+
+## GitHub About
+
+Description:
+
+```text
+Production-readiness audit and CI gate for AI-coded projects.
+```
+
+Topics:
+
+```text
+ai-coding
+devsecops
+security
+production-readiness
+codex
+github-actions
+semgrep
+trivy
+gitleaks
+ai-agents
+```
+
+## English Short Post
+
+```text
+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.
+
+GitHub: https://github.com/xixifusi1213-gif/ai-project-maintainer
+```
+
+## Show HN
+
+Title:
+
+```text
+Show HN: AI Project Maintainer – production-readiness gate for AI-coded projects
+```
+
+Body:
+
+```text
+I built a local/CI gate for AI-coded projects.
+
+The idea is simple: AI can write code quickly, but the hard part is proving a project is ready enough to ship. This tool turns that into a repeatable loop:
+
+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 is account-free by default. External APIs can be added later as optional user-provided evidence sources.
+
+Feedback on the workflow and positioning would be very useful.
+```
+
+## Chinese Short Post
+
+```text
+我做了一个给 AI coding 项目的生产级半自动维护门禁：AI Project Maintainer。
+
+它不是单纯安全扫描器，而是把项目画像、资源清单、审计计划、CI 门禁、生产证据缺口和 AI 修复串成一条链路。
+
+流程是：
+项目画像 -> 审计计划 -> 本地/CI 门禁 -> 证据报告 -> Codex 修阻断项 -> 重新运行
+
+它会明确告诉你：
+- 哪些检查通过了
+- 哪些是阻断项
+- 哪些生产证据缺失
+- 哪些需要项目负责人判断
+
+GitHub: https://github.com/xixifusi1213-gif/ai-project-maintainer
+```
+
+## V2EX / Zhihu Outline
+
+```text
+标题：我做了一个给 AI coding 项目的生产级半自动维护门禁
+
+1. 背景：AI 写代码变快后，维护、测试、安全和生产证据成了新瓶颈。
+2. 问题：个人开发者没有安全团队、SRE、DBA，但仍然要对上线负责。
+3. 方案：把项目画像、审计计划、本地/CI 门禁和生产证据缺口串起来。
+4. Demo：展示 init-audit、audit-plan、gate --production 的输出。
+5. 边界：不是绝对安全，不替代最终人工审计，不托管用户数据。
+6. 反馈：希望大家提真实项目场景、缺失检查、误报和改进方向。
+```
+
+## Reddit Targets
+
+- `r/SideProject`
+- `r/programming`
+- `r/github`
+- `r/LocalLLaMA`
+
+Suggested title:
+
+```text
+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.

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

@@ -0,0 +1,47 @@
+# 升级路线图
+
+## 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 替代维护者的最终判断。

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

@@ -0,0 +1,57 @@
+# 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`.

package/docs/superpowers/plans/2026-06-29-ci-dogfooding.md

@@ -0,0 +1,200 @@
+# CI Dogfooding Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a real GitHub Actions CI gate so the repository dogfoods its own tests, syntax checks, package validation, and local safety gate.
+
+**Architecture:** Use a single GitHub Actions workflow at `.github/workflows/ci.yml` that runs on pushes and pull requests to `main`. Keep the first version account-free and deterministic: install npm dependencies with `npm ci`, run Node tests and syntax checks, validate npm package contents, run `doctor` without Trivy DB as a non-blocking tool probe, and run a local gate smoke test that generates reports while treating external scanners as unavailable on day one.
+
+**Tech Stack:** GitHub Actions, Node.js 20 and 22, npm, existing Node scripts in `ai-project-maintainer/scripts`.
+
+---
+
+### Task 1: Add GitHub Actions CI Workflow
+
+**Files:**
+- Create: `.github/workflows/ci.yml`
+- Create: `ai-project-maintainer/scripts/ci-smoke-gate.mjs`
+
+- [ ] **Step 1: Create the workflow file**
+
+Use this workflow content:
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Node ${{ matrix.node-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version:
+          - 20
+          - 22
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+      - name: Check script syntax
+        run: npm run check
+
+      - name: Validate package contents
+        run: npm pack --dry-run
+
+      - name: Probe local tool availability
+        continue-on-error: true
+        run: node ai-project-maintainer/scripts/doctor.mjs --no-trivy-db
+
+      - name: Run local gate smoke test
+        run: node ai-project-maintainer/scripts/ci-smoke-gate.mjs . reports/security-report.json
+
+      - name: Upload gate reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: security-reports-node-${{ matrix.node-version }}
+          path: reports/
+          if-no-files-found: ignore
+```
+
+- [ ] **Step 2: Validate workflow can be parsed as YAML**
+
+Run:
+
+```powershell
+node -e "import('yaml').then(({parse})=>{const fs=require('node:fs'); parse(fs.readFileSync('.github/workflows/ci.yml','utf8')); console.log('workflow yaml ok')})"
+```
+
+Expected: `workflow yaml ok`
+
+### Task 2: Update README Trust Signals
+
+**Files:**
+- Modify: `README.md`
+
+- [ ] **Step 1: Replace the static CI badge**
+
+Replace:
+
+```markdown
+![CI ready](https://img.shields.io/badge/CI-GitHub%20Actions-24292f)
+```
+
+With:
+
+```markdown
+[![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)
+```
+
+- [ ] **Step 2: Fix the README demo link separator**
+
+Replace the corrupted link separator line with:
+
+```markdown
+[See the demo](docs/DEMO.md) · [中文演示](docs/DEMO.zh-CN.md) · [Production audit docs](docs/PRODUCTION-AUDIT.zh-CN.md)
+```
+
+### Task 3: Verify Locally
+
+**Files:**
+- No additional files.
+
+- [ ] **Step 1: Run tests**
+
+Run:
+
+```powershell
+npm test
+```
+
+Expected: all tests pass.
+
+- [ ] **Step 2: Run syntax checks**
+
+Run:
+
+```powershell
+npm run check
+```
+
+Expected: syntax check passes.
+
+- [ ] **Step 3: Validate package contents**
+
+Run:
+
+```powershell
+npm pack --dry-run
+```
+
+Expected: npm reports package `ai-project-maintainer@0.3.0` without errors.
+
+- [ ] **Step 4: Run CI-equivalent local checks**
+
+Run:
+
+```powershell
+node ai-project-maintainer/scripts/doctor.mjs --no-trivy-db
+node ai-project-maintainer/scripts/ci-smoke-gate.mjs . reports/security-report.json
+```
+
+Expected: commands exit successfully and reports are generated.
+
+### Task 4: Publish
+
+**Files:**
+- Commit: `.github/workflows/ci.yml`, `README.md`, `ai-project-maintainer/scripts/ci-smoke-gate.mjs`, `docs/superpowers/plans/2026-06-29-ci-dogfooding.md`
+
+- [ ] **Step 1: Commit changes**
+
+Run:
+
+```powershell
+git add .github/workflows/ci.yml README.md ai-project-maintainer/scripts/ci-smoke-gate.mjs docs/superpowers/plans/2026-06-29-ci-dogfooding.md
+git commit -m "Add CI dogfooding workflow"
+```
+
+- [ ] **Step 2: Push to GitHub**
+
+Run:
+
+```powershell
+git push origin HEAD:main
+```
+
+- [ ] **Step 3: Check workflow registration**
+
+Run:
+
+```powershell
+gh workflow list --repo xixifusi1213-gif/ai-project-maintainer
+```
+
+Expected: workflow list includes `CI`.