Project: ai-patchlab

This file captures the Codex/OpenAI workflow for the project. It should stay aligned with CLAUDE.md when both runtimes are present.

About

AI PatchLab is an AI-assisted security remediation toolkit. The MVP focuses on a local Python scanner that accepts a repository path, normalizes security findings from Semgrep, Gitleaks, Trivy, pip-audit, and an opt-in local AI review, and writes JSON plus Markdown reports for remediation planning.

Runtime Parity

• Treat INITIAL.md, PRPs/, ROADMAP.md, DECISIONS.md, README.md, and examples/ as shared sources of truth across runtimes
• If CLAUDE.md exists, keep it aligned with structural, dependency, and workflow changes made through Codex
• Prefer adding Codex behavior in .agents/skills/ instead of changing Claude-specific files unless parity requires it

Project Awareness & Context

• Always read ROADMAP.md at the start of a new conversation to understand the current state
• Check DECISIONS.md for past architectural decisions and context
• Check PRPs/ for active or completed implementation plans
• Read examples/ before implementing new features to match existing patterns
• Check INITIAL.md for the current feature requirements
• Use the status skill at the start of a session for a quick project snapshot

Tech Stack

• Python 3.11+
• Local CLI scanner foundation (Semgrep, Gitleaks, Trivy, pip-audit, opt-in local AI review)
• JSON and Markdown report generation
• Data stack selected for repository analysis workflows
• MySQL 8.0 (aiomysql for async, available but not required in v0.1)
• Playwright (optional extra [scraping], if scraping is needed later)
• Discord webhooks (alerts, optional later)
• Loguru (logging)
• pytest + pytest-asyncio + pytest-mock (testing)
• ruff + black (linting/formatting)
• httpx (async HTTP client)
• pydantic + pydantic-settings + python-dotenv (validation + config)
• Standard-library subprocess for external scanner runners (no remote endpoints)

Key Directories

• fingerprint/ - Web template fingerprinting (v0.1, experimental): seed loader, extractors, indexer CLI, web probe, matchers, scoring, JSON+MD match report. Local-first, single-target probe, probabilistic signal only.
• fingerprint/models.py - Frozen dataclasses (RepoFingerprint, AssetFingerprint, HtmlSignature, MatchResult, MatchSignal) and the canonical band_for_score() helper
• fingerprint/config.py - FingerprintConfig (pydantic-settings, AI_PATCHLAB_FINGERPRINT_ env prefix)
• fingerprint/git_seeds.py - Loader + validator for fingerprint/seeds/repos.json + slug_from_repo_url
• fingerprint/seeds/repos.json - Curated seed list (committed; expand via PR only)
• fingerprint/extractors/ - Pure functions over a cloned repo: favicon.py, static_assets.py, html_signatures.py
• fingerprint/repo_index.py - Clones via scanner.git_source.cloned_repo, runs extractors, writes fingerprint/db/<slug>.json
• fingerprint/run_index.py - CLI: .venv/Scripts/python.exe fingerprint/run_index.py --rebuild / --repo-url <url>
• fingerprint/web_probe.py - Sync httpx.Client probe with robots.txt respect, scheme allowlist, bytes/asset caps
• fingerprint/matchers/ - asset_hash.py, html_regex.py; registered in fingerprint/matchers/__init__.py:MATCHERS
• fingerprint/scoring.py - Bounded weighted score (WEIGHT_VALUES); shared band_for_score helper from models
• fingerprint/run_match.py - CLI: .venv/Scripts/python.exe fingerprint/run_match.py --target <url> -> reports/fingerprint/match_<host>_<UTC>.json + .md
• fingerprint/report.py - JSON + Markdown writer; disclaimer block is mandatory
• fingerprint/db/ - Per-repo fingerprint JSONs (gitignored except .gitkeep)
• reports/fingerprint/ - Generated match reports
• scanner/ - Scanner CLI, finding model, recommendation enrichment, report generation, scanner registry
• scanner/run_scan.py - CLI entry point (.venv/Scripts/python.exe scanner/run_scan.py --repo <path> or --from-git-url <url>)
• scanner/git_source.py - Shallow-clone a public git URL into a temp directory via the cloned_repo context manager; cleanup-on-exit, shell=False, no remote API calls
• scanner/paths.py - rebase_finding_paths(findings, repo_root) rewrites each finding's file (and id when it embeds the same path) to a repo-relative POSIX path so reports survive temp-dir cleanup
• scanner/ignore.py - apply_ignore(findings, patterns) + load_ignore_patterns(path) provide .gitignore-style path suppression (used by the --ignore-file CLI flag). Empty-file findings are never suppressed. DEFAULT_SAMPLE_IGNORE_PATTERNS holds demo/sample/example subtree patterns opted into via --ignore-samples
• scanner/models.py - Normalized Finding dataclass + severity/confidence enums + FINDING_FIELDS
• scanner/recommendations.py - Deterministic keyword-based recommendation enrichment
• scanner/coverage.py - Per-scanner coverage derived from meta findings (ToolCoverage, build_coverage, EXPECTED_TOOLS, is_complete); feeds reports/coverage.json and the report's Scan Coverage block
• scanner/verdict_corpus.py - Corpus validation and aggregation (validate_payload reports every problem in one pass, load_corpus reads corpus/verdicts/)
• scanner/run_verdict_check.py - CLI: --check <verdicts.json> (exit 2 on any problem, required by /daily Phase 4) and --summary (count the whole corpus)
• scanner/run_orphan_check.py - CLI: finds /daily runs that died without recording themselves (a runs_recent entry left in-progress by an earlier day, or reports/<slug>/ output newer than last_run with no post and no run record). Exit 2 on any orphan, required by /daily Phase 0; --write-pause creates .daily-paused, --acknowledge closes the orphans after review
• corpus/verdicts/ - Committed dismissal corpus, one file per scan; the durable half, since reports/ is gitignored
• scanner/verdicts.py - Dismissal records (VerdictRecord, summarize_removed, count_by_reason, load_records) with closed SCANNER_REASON_CODES / CURATION_REASON_CODES vocabularies; feeds reports/verdicts.json and the report's Dismissed section
• scanner/report_markdown.py - Markdown rendering, split out of report.py to stay under the 300-line ceiling (write_markdown_report is still re-exported from scanner.report)
• scanner/confidence.py - Centralized Finding.confidence rules (one function per scanner + confidence_for_meta_finding for shared not-installed / scan-error / etc.)
• scanner/report.py - JSON + Markdown report writers (severity-grouped, "Top Findings" highlight block, patch suggestion blocks); also exposes filter_by_min_severity and select_top_findings
• scanner/config.py - Disabled-by-default AI review configuration loaded from environment / .env (AI_PATCHLAB_*)
• scanner/remediation/ - Deterministic patch suggestion engine (patch_suggestions.py) for known vulnerability patterns
• scanner/scanners/ - Scanner adapters (semgrep.py, gitleaks.py, trivy.py, dependency_scan.py, ai_review.py) plus common.py placeholder helper and __init__.py registry (SCANNERS)
• scanner/tools/ - External scanner process runners (semgrep_runner.py, gitleaks_runner.py, trivy_runner.py, pip_audit_runner.py, ai_review_runner.py)
• reports/ - Generated security reports (security_report.json, security_report.md)
• reports/verdicts.json - Dismissal corpus: one row per rule family removed, with a reason code and a count
• reports/coverage.json - Per-scanner coverage manifest written on every scan (what each tool actually examined, plus a complete flag)
• reports/raw/ - Raw scanner JSON outputs (semgrep.json, gitleaks.json, trivy.json, pip-audit.json, ai-review.json when enabled)
• src/ - Legacy scaffold entry point (kept for template parity)
• src/main.py - Legacy entry point (python -m src.main) - currently a loguru-wired async stub with TODOs
• .github/workflows/ci.yml - CI: ruff + black + pytest on Python 3.11 and 3.13
• reports/disclosures/ - Drafted private disclosure emails awaiting a manual send (gitignored)
• tests/ - pytest tests (one module per scanner: test_scanner_foundation.py, test_semgrep_scanner.py, test_gitleaks_scanner.py, test_trivy_scanner.py, test_dependency_scan.py, test_ai_review.py, test_patch_suggestions.py, test_recommendations.py, test_meta_findings.py, test_confidence_field_rules.py, test_coverage.py, test_verdicts.py, test_verdict_corpus.py, test_orphan_check.py)
• tests/conftest.py - Shared fixtures (mock_db, mock_http_client, mock_discord, test_config, session event_loop)
• examples/ - Reference patterns to read before implementing
• PRPs/ - Active Product Requirements Prompts
• PRPs/done/ - Archived PRPs (2026-05-12-trivy-integration.md, 20260513-phase-3-ai-review-behavior.md)
• PRPs/templates/ - Reusable PRP templates (prp_base.md)
• docs/ - GitHub Pages site (Jekyll, theme cayman): _config.yml, index.md (landing + scan log), scans/ (per-scan write-ups), templates/scan-post.md (template, excluded from publish)
• logs/ - Log files (gitignored except .gitkeep)
• .agents/skills/ - Codex skills for repeatable workflows
• .claude/ - Claude runtime files (commands, agents, pipelines), if present

Codex Skills

• ez-project-workflow - Core EzProject operating rules for any coding task
• kickoff - Interview flow that updates INITIAL.md and project docs
• generate-prp - Build a self-contained PRP from a feature spec (with optional Understanding Lock for ambiguous specs)
• execute-prp - Implement a PRP end to end with validation and housekeeping
• fix-issue - Diagnose, fix, test, review, and commit a bug end-to-end
• pipeline - Execute a YAML-defined workflow step by step (feature, bugfix, security, release, custom)
• tdd - Strict Red-Green-Refactor implementation (Iron Law: no production code without an observed-failing test)
• review-code - Review the current diff or target files
• refactor - Analyze code smells and execute selected refactorings with per-change validation
• retrospective - Self-healing retrospective in a fresh context after execute-prp (lite mode) or sprint-wide (no arg)
• next - Read project state and recommend the 1-3 best next actions
• upgrade-status - Compare project to latest template; list features not yet adopted
• status - Produce a compact project status snapshot
• audit-project - Audit runtime docs and project scaffolding
• housekeeping - Sync docs and remove temporary artifacts
• cleanup - Identify dead code via import-graph trace; report and ask before deleting
• security-scan - OWASP top 10 + secrets + vulnerable deps audit
• dependency-check - Vulnerabilities, outdated packages, compatibility audit; optional safe auto-update
• performance - Static hot-path scan + optional runtime profiling
• document - Auto-generate docs from code (API ref, data dict, architecture, modules)
• monitor-setup - Health check endpoint + alerting + uptime tracking adapted to stack
• rollback - Safe git rollback (always revert + stash, never reset --hard)
• create-skill - Scaffold a new Codex skill for the project
• daily - Autonomous daily scan-and-disclose pipeline (status sweep -> candidate discovery -> one scan -> curation -> gated publication). Full-auto per the 2026-05-28 decision; guardrails: 1 scan/day, quality gate on issue/PR filing, strict-norm detection, kill switch .daily-paused

Claude-only commands (no Codex skill mirror)

These Claude slash commands are intentionally not mirrored on the Codex side. Listed in tests/template/test_codex_parity.py as KNOWN_EXCEPTIONS.

• /do (smart-router) - natural-language intent routing requires a Claude-side primitive that Codex doesn't expose; the pattern table at .claude/commands/smart-router.md is Claude-only.
• /idea-to-pr - end-to-end idea -> PR flow requires PR/branching orchestration that's tightly coupled to Claude's tool layer.
• /upgrade-to-project - one-shot MVP -> Project upgrade; the equivalent on the Codex side is to invoke ez-upgrade-project.ps1 directly.

Common Commands

# Dev
.venv/Scripts/python.exe scanner/run_scan.py --repo "C:\path\to\repo"
.venv/Scripts/python.exe scanner/run_scan.py --repo "." --reports-dir reports
python -m src.main
.venv/Scripts/python.exe -m pytest tests/ -v
.venv/Scripts/python.exe -m pytest tests/ -v -k "test_name"

# Lint & Format
.venv/Scripts/ruff.exe check scanner src/ tests/ fingerprint/
.venv/Scripts/ruff.exe check scanner src/ tests/ fingerprint/ --fix
.venv/Scripts/python.exe -m black scanner src/ tests/ fingerprint/

# Web template fingerprinting (experimental)
.venv/Scripts/python.exe fingerprint/run_index.py --rebuild                      # Rebuild local DB from seed list
.venv/Scripts/python.exe fingerprint/run_match.py --target https://example.com   # Probe a single live URL

# Setup
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pip install -e ".[scraping]"   # Optional Playwright extra
cp .env.example .env

# External scanners (install separately, must be on PATH)
semgrep --version
gitleaks version
trivy --version
.venv/Scripts/python.exe -m pip install pip-audit && pip-audit --version

# Optional AI review (disabled by default - see scanner/config.py)
export AI_PATCHLAB_AI_REVIEW_ENABLED=true
export AI_PATCHLAB_AI_REVIEW_PROVIDER=local_command
export AI_PATCHLAB_AI_REVIEW_COMMAND=/path/to/ai-review-wrapper

MCP Servers

• memory - Session persistence when configured
• mysql - Direct database access through MCP when MYSQL_DSN is configured

Coding Standards

Python

• Type hints REQUIRED on all functions
• Google-style docstrings on public functions
• Max ~300 lines per file (note: scanner/remediation/patch_suggestions.py is ~280 lines)
• English identifiers; French comments are fine
• Use async/await where appropriate; the scanner core is synchronous on purpose because it shells out via subprocess.run
• Use loguru, never print() in production code (exception: scanner/run_scan.py prints report paths to stdout as the CLI surface)
• Config via .env / AI_PATCHLAB_* env vars; never hardcode secrets
• Use pathlib.Path for filesystem paths
• Use pydantic for env-loaded config; use @dataclass(frozen=True) for internal normalized records (Finding, *Result)
• External scanner subprocesses MUST use shell=False and an explicit argv list

Scanner adapter contract

• Each scanner in scanner/scanners/ exposes one scan_<name>(repo_path: Path, reports_dir: Path) -> list[Finding] function and is registered in scanner/scanners/__init__.py:SCANNERS
• Scanners must never raise on a missing or failing external tool - emit a normalized info finding instead so the report still completes
• Each adapter pipes its findings through apply_patch_suggestions(enrich_findings(...)) before returning
• Any finding built with confidence_for_meta_finding(...) must also set is_meta=True so --min-severity cannot drop it
• Each external tool runner lives in scanner/tools/<tool>_runner.py, returns a frozen *Result dataclass, writes raw JSON to reports/raw/<tool>.json, and uses subprocess.run(..., shell=False, check=False) with captured stdout/stderr
• Do not call subprocesses directly from scanner/scanners/* - go through the runner module
• Every suppression step in run_scan records what it removed via summarize_removed(before, after, reason_code) - a narrower report must never shrink its own numbers silently (ADR-016)
• reason_code values are a closed vocabulary in scanner/verdicts.py; add a code to the module rather than inventing one at a call site, or the corpus stops being countable
• Curation rows are hand-written JSON, so the dataclass never runs on them - /daily Phase 4 MUST get exit 0 from scanner/run_verdict_check.py --check before publishing (ADR-017). rule is required on every row; verdict takes one of five values and the sentence goes in detail
• confirmed-real is first-party only; an upstream dependency merely behind a fixed version is dependency-currency
• Coverage is derived from the raw collect_findings output before apply_ignore (scanner/run_scan.py) - --ignore-file does not exempt meta findings, so deriving it later would let a path pattern hide the fact that a tool never ran
• Adding a scanner to SCANNERS requires adding its Finding.tool value to scanner/coverage.py:EXPECTED_TOOLS; tests/test_coverage.py::TestRegistryDrift fails until you do
• Finding.confidence values come from scanner/confidence.py - never inline confidence="high" / "medium" / "low" in a scanner adapter; add or reuse a rule function instead

Fingerprint adapter contract

• Extractors in fingerprint/extractors/ are pure functions over a cloned repo path (and the active FingerprintConfig). No subprocess, no network, no raise on missing files.
• Matchers in fingerprint/matchers/ take (RepoFingerprint, TargetSnapshot) and return list[MatchSignal]. Registered in fingerprint/matchers/__init__.py:MATCHERS. A mismatch is the empty list.
• The indexer (fingerprint/repo_index.py:index_seed) is the only place that performs a git clone; it goes through scanner.git_source.cloned_repo.
• The web probe (fingerprint/web_probe.py:fetch_target) is the only place that makes outbound HTTP requests. Scheme allowlist: http/https. Honours robots.txt and hard byte/asset caps.
• The match CLI (fingerprint/run_match.py) always exits 0 (partial-result discipline). Empty DB, unreachable target, bad scheme, robots-disallowed all still produce a valid report.
• The Markdown report ALWAYS includes the DISCLAIMER block and never uses attribution words ("confirmed", "proven", "stolen", "copied") - tested in tests/test_fingerprint_report.py.
• Score banding goes through band_for_score() in fingerprint/models.py - single source of truth used by validator and writer.
• The seed list fingerprint/seeds/repos.json is curated. Adding a new entry is a human PR - never auto-discover via the GitHub API.

Database Conventions

• MySQL tables in snake_case
• Always include id, created_at, and updated_at
• Index frequently queried columns
• Append migrations to docs/schema.sql with a dated comment (file not yet created - docs/ is empty)
• Use parameterized queries only

Error Handling

• Wrap external calls in try/except
• Log errors with context using loguru
• Use retries with backoff for network calls when needed
• Never silently suppress errors
• Use custom exception classes for domain-specific failures
• Scanner runners catch OSError and subprocess.TimeoutExpired, write a safe empty raw JSON, and return a structured *Result instead of propagating

Testing

• Use pytest for all tests (pytest-asyncio mode is auto per pyproject.toml)
• Mock external calls (API, DB, subprocess) in unit tests
• Cover critical calculation and workflow paths
• Use pytest-asyncio for async tests
• Available markers: slow, integration
• Each scanner adapter has a dedicated tests/test_<scanner>.py module

Git Workflow

• Create a branch per feature
• Use descriptive English commit messages
• Format commits as type: description
• Never commit directly to main
• Run validation before committing

Roadmap Management

• Always check ROADMAP.md first
• Progression: [ ] todo -> [-] in progress -> [x] done
• Add a YYYY/MM/DD timestamp when status changes
• Update ROADMAP.md after completing each meaningful task

Architecture Decisions

• Log architectural decisions in DECISIONS.md
• Check existing ADRs before making structural changes
• Record date, decision, context, and consequences
• Current ADRs of record: ADR-001 scaffold, ADR-002 data stack, ADR-003 placeholder adapters, ADR-004 Gitleaks, ADR-005 Semgrep, ADR-006 recommendation enrichment, ADR-007 patch suggestions, ADR-008 Trivy, ADR-009 pip-audit, ADR-010 disabled-by-default AI review boundary, ADR-011 centralized scanner confidence rules, ADR-012 probabilistic web template fingerprinting boundary, ADR-013 meta findings exempt from severity filtering, ADR-014 field-derived confidence tiers, ADR-015 coverage is a report artifact, ADR-016 dismissals recorded as counted rule families, ADR-017 a closed vocabulary needs a closer

Known Gotchas

• Do not tag scan posts by keyword inference. A classifier over post bodies was built and rejected 2026-09-18: validated against 9 posts of known ground truth it gave klavis 6 finding classes where the real finding was dependency CVEs, and got 3 of 9 project families wrong (OpenBiliClaw as "developer tooling", tracecat as "MCP server"). Post bodies discuss false positives and credited defences at length, so matching them tags a clean scan with the class it dismissed. On a site whose whole argument is that pattern-matching produces plausible-but-wrong results, publishing plausible-but-wrong tags is self-refuting. Grouping pages are generated from the curated index table instead — hand-maintained, verified data
• Roughly half of scan targets land on a disclosure channel the pipeline cannot use. Measured 2026-09-18: 14 disclosures went through an autonomous channel (GitHub private vulnerability reporting, or a public issue), 12 needed a human to send an email or a DM. Every pipeline stoppage in the project's history came from the human-gated half — a six-report backlog (25 days, 4 scans lost) and one undeliverable High (33 days, 3 scans lost). /daily guardrail 9 now makes channel viability a target-SELECTION criterion, tiered on queue depth, and guardrail 8 defines unreachable as the only way to close a report that no channel can carry. The tiering is deliberate: PVR-enabled repos skew mature and commercially backed, so a permanent preference would bias the series away from the small projects that most need review
• A headless /daily that dies leaves no trace unless the run recorded itself first. From 2026-09-25 to 2026-10-03 seven runs scanned a repo and then ended in curation on a model safety stop (the log ends API Error: ... safeguards flagged this session ... Details: [cyber]), before Phase 6 wrote any state. last_run stayed stale, the one-scan-per-day rule never fired, seven scans were lost and nothing was published; the pipeline was paused on 2026-10-04. The fix is a run record opened at target pick plus scanner/run_orphan_check.py in Phase 0. The safety stop itself is platform-side: this repo can detect it, not prevent it. The scheduled wrapper lives OUTSIDE the repo (%USERPROFILE%\ai-patchlab-daily\run-daily.ps1, Task Scheduler task ai-patchlab-daily, 09:00) and writes UTF-16 logs to logs\daily_<date>_<time>.log beside it (read them with encoding='utf-16'; cat shows spaced-out text). Until 2026-10-13 it always exited 0, so Task Scheduler showed success for dead runs; it now exits 1 when Claude fails and 3 when the run ended with .daily-paused present
• Semgrep is a Python program on the shared user-site interpreter, not a standalone binary like gitleaks/trivy. Anything that breaks that interpreter breaks Semgrep too — a pydantic downgrade on 2026-08-20 made semgrep --version raise ImportError and every scan would have silently lost 52% of its coverage. The project .venv does NOT protect it. Check semgrep --version before trusting a scan; repair with python -m pip install --user --upgrade "pydantic>=2.11" "httpx>=0.27"
• ALWAYS run through .venv (.venv/Scripts/python.exe on Windows). The project ran three months off the shared user-site; on 2026-08-20 an unrelated pip install downgraded pydantic to 1.x and httpx to 0.21 and every import broke, hours after a scan had passed
• Meta findings survive --min-severity but are NOT yet exempt from --ignore-file suppression
• Semgrep coverage comes from the errors array, never paths.skipped - skipped has been empty on every series run where rules timed out. scan_semgrep emits semgrep-partial-coverage naming each rule -> file pair that did not run
• ai-patchlab and 2026-05-12 are template placeholders replaced during scaffolding
• aiomysql pools must be closed explicitly with await db.disconnect() in finally
• Playwright networkidle can time out on SPAs; use domcontentloaded when needed
• Discord webhooks: 30 messages/minute rate limit per webhook
• pydantic-settings: .env variables are case-insensitive by default
• MCP MySQL DSNs require URL-encoding for special characters in passwords
• cPanel MySQL DB and user names are prefixed (e.g. cpaneluser_dbname) - don't forget the prefix
• AI review must remain disabled by default and local-first. Never add a default remote provider, default endpoint, default model, or default token variable. Any future remote/paid provider requires explicit configuration and a new ADR.
• Scanner subprocess invocations MUST use shell=False and an explicit argv list - shell=True is the exact anti-pattern the patch engine warns about (see scanner/remediation/patch_suggestions.py:SUBPROCESS_SHELL_SUGGESTION)
• Semgrep on Windows: when not on PATH, the runner falls back to Path.home() / AppData/Roaming/Python/Python313/Scripts/semgrep.exe (see scanner/tools/semgrep_runner.py:PIP_USER_SEMGREP_PATH). The Python minor version is hardcoded - if the user installs under a different Python version, the runner will silently skip Semgrep until the constant is updated
• Semgrep UTF-8 output (Windows, 2026-06-11 fix): Semgrep writes its --output JSON via Python's default codec (cp1252 on Windows). A repo with non-Latin-1 source (Chinese/Japanese/Korean/emoji) crashes Semgrep mid-write with UnicodeEncodeError, leaving a 0-byte report + exit 2. _build_semgrep_env forces PYTHONUTF8=1 + PYTHONIOENCODING=utf-8; scan_semgrep treats an empty report as a semgrep-scan-error. The scan-error is info severity, so --min-severity medium still filters it (RESOLVED 2026-08-21: meta findings carry is_meta=True and are exempt from --min-severity)
• All external scanners are optional - if a tool is missing, the adapter emits a normalized info finding (semgrep-not-installed, gitleaks-not-installed, trivy-not-installed, pip-audit-not-installed, ai-review-disabled) instead of failing
• pip-audit input resolution order: root requirements*.txt first, then pylock.*.toml (with --locked), then pyproject.toml
• AI review timeouts default to 120s (AI_PATCHLAB_AI_REVIEW_TIMEOUT_SECONDS); on timeout the runner writes [] to reports/raw/ai-review.json and emits a normalized error finding so the report still completes
• Fingerprint web probe respects robots.txt. urllib.robotparser splits the live user-agent on / before matching, so a robots.txt block for ai-patchlab-fingerprint/0.1 is matched as ai-patchlab-fingerprint (drop the version when authoring rules)
• Fingerprint matching is a SIGNAL, not an attribution. The Markdown report keeps the DISCLAIMER block and never claims a match is "confirmed", "proven", "stolen", or "copied" - blocked by a regression test
• The fingerprint CLI accepts exactly one --target per invocation. No --targets-file flag exists by design - multi-target scanning requires a new ADR
• Fingerprinting must not add DOM-parser dependencies (beautifulsoup4, lxml) or browser stacks (playwright, selenium). v0.1 stays on re + hashlib + httpx only

Important Rules

• Keep things simple - MVP first
• Read examples/ before inventing new patterns
• Validate each step before moving on
• Do not over-engineer
• Log meaningful architecture decisions in DECISIONS.md

Self-Healing Layer (AI-layer evolution)

When an implementation is painful, fix the underlying AI layer - not just the code. The AI layer is CLAUDE.md, AGENTS.md, examples/, .claude/commands/, .claude/agents/, .claude/pipelines/, .agents/skills/, PRP templates.

• Never review the implementer's work in the same context that produced it (writer is biased about its own output)
• After execute-prp, in a NEW session, run the retrospective skill with the PRP name (lite mode) to surface AI-layer drift and propose concrete file edits
• Apply the proposed edits only after the user approves
• Periodically run retrospective with no argument for a broader sprint review

Automatic Housekeeping

• After any feature or fix, update ROADMAP.md
• After structural changes, update AGENTS.md
• If CLAUDE.md exists, update the matching sections there too
• If new setup steps or commands were added, update README.md
• After completing a PRP, move it to PRPs/done/ with a date prefix
• Delete scratch files and obvious temporary artifacts when done
• Never leave documentation out of sync with the code