安全审计

Brownfield Import Compatibility (FEAT-018):

When auditing a project bootstrapped via vp-crystallize --brownfield:

• If docs/brainstorm/ exists and contains only session-brownfield-import.md (no session-*.md greenfield files):
  • Valid brownfield import — do NOT flag as missing brainstorm session.
  • Verify session-brownfield-import.md contains a ## Scan Report section with a YAML block.
    • If YAML block absent → flag LOW severity: "Brownfield stub missing Scan Report content."
  • If .viepilot/TRACKER.md contains ## Brownfield Import section → brownfield metadata confirmed; no further brainstorm check needed.
• If docs/brainstorm/ is completely absent → flag MEDIUM severity: "No brainstorm session or brownfield stub found — run /vp-crystallize or /vp-crystallize --brownfield."

Tier 1 — ViePilot State Consistency (all projects):

• .viepilot/TRACKER.md current state vs .viepilot/phases/*/PHASE-STATE.md
• .viepilot/ROADMAP.md phase status vs PHASE-STATE.md
• .viepilot/HANDOFF.json vs TRACKER.md (resume-state consistency)
• Git tags vp-p{N}-complete vs completed phases in PHASE-STATE.md

Tier 2 — Project Documentation Drift (all projects):

• README.md version vs package.json / pom.xml / pyproject.toml
• CHANGELOG.md vs recent git commits
• Placeholder URLs in docs/ (your-org, YOUR_USERNAME, etc.)
• New features (from recent phases) without documentation
• ARCHITECTURE.md diagram applicability matrix consistency:
  • required diagrams must have Mermaid content
  • optional diagrams may be omitted/merged with explicit note
  • N/A diagrams must have rationale line
• ENH-022 (recommended check): when a diagram type is required (or optional with a real Mermaid block) and crystallize policy applies, verify .viepilot/architecture/<type>.mermaid exists and that Diagram source lines in ARCHITECTURE.md match; for N/A, sidecar file should be absent (no empty stubs)

Tier 3 — Stack Best Practices + Code Quality (all projects, for each detected stack):

• Detect relevant stacks from context/project manifests
• Match code patterns against stack-specific Do/Don't + anti-patterns
• Severity findings: critical / high / medium / low with file/module mapping
• Fallback research using WebSearch + WebFetch when stack cache is missing/weak
• Generate guardrails/checklist output for vp-auto reuse during preflight

Tier 4 — Framework Integrity (only when viepilot framework repo is detected):

• Auto-detect: skills/vp-*/SKILL.md present → this is the viepilot framework repo
• ARCHITECTURE.md counts vs actual skills/, workflows/, CLI
• README.md viepilot-specific badges (version, skills-N, workflows-N)
• docs/skills-reference.md sections vs skills/ directory
• Silent by default (ENH-049): Tier 4 output is suppressed when all checks pass (✅) or when the check is skipped (non-framework repo). Output only appears when issues (⚠️) are found. Non-framework repos: Tier 4 skipped silently with no message.

Output:

• Report by 4 tiers, each tier with its own status
• Auto-fix option per tier
• Suggestions for complex gaps
• vp-auto-compatible guardrails contract per stack

Agent({ subagent_type: "file-scanner-agent",
  description: "file-scanner-agent: scan state files for stale phase refs",
  prompt: "patterns: [\".viepilot/phases/*/PHASE-STATE.md\"]. keywords: [\"in_progress\", \"planned\"]. context: Find phases with stale in_progress or planned status."
})

# TRACKER.md vs PHASE-STATE.md
# ROADMAP.md vs PHASE-STATE.md
# HANDOFF.json vs TRACKER.md
# Git tags vs completed phases

Agent({ subagent_type: "file-scanner-agent",
  description: "file-scanner-agent: scan docs for stale refs and placeholder URLs",
  prompt: "patterns: [\"docs/**/*.md\", \"README.md\", \"CHANGELOG.md\"]. keywords: [\"your-org\", \"YOUR_USERNAME\", \"TODO\", \"placeholder\"]. context: Find stale placeholder refs and docs drift."
})

# Detect version: package.json / pom.xml / pyproject.toml
# README.md version mention
# CHANGELOG.md vs recent commits
# Placeholder URLs in docs/
# ARCHITECTURE.md diagram matrix consistency (required|optional|N/A)

# detect stack(s), load cache summary first
# if missing/weak cache -> run WebSearch/WebFetch fallback
# emit severity findings + guardrails contract for vp-auto

When --visual is passed:
1. Resolve base URL: --browser <url> → config.json audit.baseUrl → http://localhost:3000
2. Dispatch browser-audit-agent:
   Agent({ subagent_type: "browser-audit-agent",
     description: "browser-audit-agent: audit running dev server",
     prompt: `op: audit_routes. baseUrl: ${baseUrl}. projectRoot: ${projectRoot}` })
3. On success: call writeAuditReport(result, projectRoot) → lib/audit/browser-runner.cjs
4. Report path shown to user: .viepilot/audit/visual-report-{timestamp}.md
5. On agent-browser not installed: show prerequisite message, skip browser audit (non-blocking)

After audit_routes: optionally run accessibility_check on same routes:
   Agent({ subagent_type: "browser-audit-agent",
     prompt: `op: accessibility_check. baseUrl: ${baseUrl}. routes: ${JSON.stringify(routes)}. projectRoot: ${projectRoot}` })

Baseline management:
- --visual first run: saves screenshots to .viepilot/audit/baselines/{slug}.png
- Subsequent runs: compares current vs baseline (visual_check op)
- --update-baseline: forces baseline refresh (passes updateBaseline: true to agent)

Phase 2 complete!

⚠️ Audit found 2 issues:
   Tier 1: ROADMAP.md phase 2 not marked ✅
   Tier 2: README.md version not updated

Fix now? (y/n)