ai-project-maintainer 0.3.1 → 0.4.1

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

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

package/examples/demo-ai-app/.ai-maintainer/business-flows.yml

@@ -0,0 +1,14 @@
+schema_version: 1
+business_flows:
+  - id: "checkout-quote"
+    name: "Customer checkout quote"
+    criticality: "high"
+    expected_behavior: "A customer-visible total must include the selected shipping cost exactly once."
+    tests:
+      - "test/order-risk.test.mjs"
+  - id: "order-release"
+    name: "Paid order release"
+    criticality: "high"
+    expected_behavior: "An order can be released only when payment, stock, and risk checks all pass."
+    tests:
+      - "test/order-risk.test.mjs"

package/examples/demo-ai-app/.ai-maintainer/db-migration-policy.yml

@@ -0,0 +1,6 @@
+schema_version: 1
+database:
+  changes_use_migrations: false
+  destructive_changes_require_review: true
+  backup_before_production_migration: false
+  rollback_or_forward_fix_required: false

package/examples/demo-ai-app/.ai-maintainer/evidence-sources.yml

@@ -0,0 +1,18 @@
+schema_version: 1
+evidence:
+  github_actions: "present"
+  deployment:
+    provider: "demo"
+    has_staging: true
+    has_production: true
+    production_requires_approval: false
+  observability:
+    errors: "none"
+    logs: "none"
+    metrics: "none"
+    alerts: "none"
+  database:
+    migrations: "none"
+    review_tool: "none"
+    backup_policy: "none"
+    rollback_plan: "none"

package/examples/demo-ai-app/.ai-maintainer/exceptions.yml

@@ -0,0 +1 @@
+exceptions: []

package/examples/demo-ai-app/.ai-maintainer/incident-runbook.md

@@ -0,0 +1,11 @@
+# Incident Runbook
+
+## First Response
+
+- Stop new releases.
+- Check checkout quote and order release tests.
+- Decide whether to rollback the latest release.
+
+## Missing Evidence
+
+- Production monitoring is intentionally missing in the demo so the audit report shows GAP items.

package/examples/demo-ai-app/.ai-maintainer/observability-checklist.yml

@@ -0,0 +1,7 @@
+schema_version: 1
+observability:
+  error_monitoring: false
+  structured_logs: false
+  metrics: false
+  alerts: false
+  release_tracking: false

package/examples/demo-ai-app/.ai-maintainer/policy.yml

@@ -0,0 +1,27 @@
+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
+  package-audit: 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

package/examples/demo-ai-app/.ai-maintainer/project-profile.yml

@@ -0,0 +1,15 @@
+schema_version: 1
+project:
+  name: demo-ai-app
+  type: node
+  lifecycle: production-candidate
+  production: true
+risk:
+  handles_auth: false
+  handles_sensitive_data: false
+  handles_payments: false
+  handles_financial_data: false
+  handles_health_data: false
+  has_database: false
+  has_deployment: true
+  has_user_generated_content: false

package/examples/demo-ai-app/.ai-maintainer/release-checklist.yml

@@ -0,0 +1,7 @@
+schema_version: 1
+release:
+  has_staging: true
+  has_smoke_tests: true
+  has_manual_approval: false
+  has_rollback_plan: false
+  has_versioned_artifacts: true

package/examples/demo-ai-app/.ai-maintainer/risk-policy.yml

@@ -0,0 +1,5 @@
+schema_version: 1
+production:
+  block_on_coverage_gaps: false
+  block_on_user_decisions: false
+  require_intake: true

package/examples/demo-ai-app/.ai-maintainer/threat-model.md

@@ -0,0 +1,18 @@
+# Threat Model
+
+## Assets
+
+- Order totals
+- Payment status
+- Release decisions
+
+## Trust Boundaries
+
+- Browser or API client input
+- Order risk calculation
+- Release approval process
+
+## User Decisions
+
+- Confirm whether manual review threshold matches real business risk.
+- Confirm who can override a release hold.

package/examples/demo-ai-app/README.md

@@ -0,0 +1,38 @@
+# Demo AI App
+
+This is a small healthy Node.js project used by AI Project Maintainer demos.
+
+It has:
+
+- business-critical tests
+- a build script
+- production audit intake files
+- intentional production evidence gaps for monitoring, alerts, approval, and rollback
+
+## 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
+```
+
+The demo gate uses temporary scanner shims so the sample report is reproducible on machines that do not have Gitleaks, Trivy, Semgrep, and other scanners installed yet.
+
+## Generate The Broken Before State
+
+```powershell
+node .\examples\demo-ai-app\scripts\create-before-state.mjs
+```
+
+The command prints a temporary directory. Run `npm test` in that copied project to see the business tests fail. Nothing bad is committed into this repository; the failing state exists only under the OS temp directory.
+
+## Run The Real Gate
+
+When scanner CLIs are installed, run 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 expected result is PASS with visible GAP items for missing production evidence.

package/examples/demo-ai-app/package-lock.json

@@ -0,0 +1,15 @@
+{
+  "name": "demo-ai-app",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "demo-ai-app",
+      "version": "0.1.0",
+      "engines": {
+        "node": ">=20"
+      }
+    }
+  }
+}

package/examples/demo-ai-app/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "demo-ai-app",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Runnable demo project for AI Project Maintainer.",
+  "scripts": {
+    "test": "node --test",
+    "build": "node scripts/build.mjs",
+    "demo:before": "node scripts/create-before-state.mjs",
+    "demo:gate": "node scripts/run-demo-gate.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/examples/demo-ai-app/scripts/build.mjs

@@ -0,0 +1,18 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const outDir = path.join(root, "dist");
+
+fs.mkdirSync(outDir, { recursive: true });
+fs.writeFileSync(
+  path.join(outDir, "build-manifest.json"),
+  `${JSON.stringify({
+    app: "demo-ai-app",
+    builtAt: new Date().toISOString(),
+    entrypoints: ["src/order-risk.js"],
+  }, null, 2)}\n`,
+);
+
+console.log(`Demo build manifest written to ${path.relative(root, outDir)}`);