docs: add CLAUDE.md project instructions

Co-Authored-By: Virgil <virgil@lethean.io>

CLAUDE.md

@@ -1,30 +1,88 @@
 # CLAUDE.md
 
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
 ## Project Overview
 
-`core/lint` is a standalone pattern catalog and regex-based code checker. It loads YAML rule definitions and matches them against source files. Zero framework dependencies.
+`core/lint` is a standalone pattern catalog, regex-based code checker, and multi-language QA toolkit. It loads YAML rule definitions and matches them against source files, plus wraps external Go and PHP tooling into structured APIs. Zero framework dependencies — uses `forge.lthn.ai/core/cli` for CLI scaffolding only.
 
 ## Build & Development
 
 ```bash
-core go test
+core go test          # run all tests
-core go qa
+core go test ./pkg/lint/...   # run tests for a specific package
-core build          # produces ./bin/core-lint
+core go qa            # full QA pipeline (vet, lint, test)
+core build            # produces ./bin/core-lint
+```
+
+Run a single test:
+```bash
+go test -run TestMatcherExcludePattern ./pkg/lint/
 ```
 
 ## Architecture
 
-- `catalog/` — YAML rule files (embedded at compile time)
+Three distinct subsystems share this module:
-- `pkg/lint/` — Library: Rule, Catalog, Matcher, Scanner, Report types
+
-- `cmd/core-lint/` — CLI binary using `cli.Main()`
+### 1. Pattern Catalog & Scanner (`pkg/lint/`)
+
+The core lint engine. YAML rules in `catalog/` are embedded at compile time via `//go:embed` in `lint.go` and loaded through `LoadEmbeddedCatalog()`.
+
+**Data flow:** YAML → `ParseRules` → `Catalog` → filter by language/severity → `NewMatcher` (compiles regexes) → `Scanner.ScanDir`/`ScanFile` → `[]Finding` → output as text/JSON/JSONL via `report.go`.
+
+Key types:
+- `Rule` — parsed from YAML, validated with `Validate()`. Only `detection: "regex"` rules are matched; other detection types are stored but skipped by `Matcher`.
+- `Matcher` — holds pre-compiled `regexp.Regexp` for each rule's `pattern` and optional `exclude_pattern`. Matches line-by-line.
+- `Scanner` — walks directory trees, auto-detects language from file extension (`extensionMap`), skips `vendor/node_modules/.git/testdata/.core`.
+- `Finding` — a match result with rule ID, file, line, severity, and fix suggestion.
+
+### 2. Go Dev Toolkit (`pkg/lint/tools.go`, `complexity.go`, `coverage.go`, `vulncheck.go`)
+
+Structured Go APIs wrapping external tools (`go vet`, `govulncheck`, `gocyclo`, `gitleaks`, `git`). The `Toolkit` type executes subprocesses and parses their output into typed structs (`ToolFinding`, `Vulnerability`, `CoverageReport`, `RaceCondition`, etc.).
+
+`complexity.go` provides native AST-based cyclomatic complexity analysis (no external tools needed) via `AnalyseComplexity`.
+
+`coverage.go` provides `CoverageStore` for persisting and comparing coverage snapshots over time, detecting regressions.
+
+`vulncheck.go` parses `govulncheck -json` NDJSON output into `VulnFinding` structs.
+
+### 3. PHP QA Toolchain (`pkg/php/`, `pkg/detect/`, `cmd/qa/`)
+
+Wraps PHP ecosystem tools (Pint, PHPStan/Larastan, Psalm, Rector, Infection, PHPUnit/Pest, composer audit). `pkg/detect/` identifies project type by filesystem markers (go.mod → Go, composer.json → PHP).
+
+`pkg/php/pipeline.go` defines a staged QA pipeline: quick (audit, fmt, stan) → standard (+psalm, test) → full (+rector, infection).
+
+`pkg/php/runner.go` builds `process.RunSpec` entries with dependency ordering (`After` field) for the `core/go-process` runner.
+
+### CLI Entry Points
+
+- `cmd/core-lint/main.go` — `core-lint lint check` and `core-lint lint catalog` commands
+- `cmd/qa/` — `core qa` subcommands registered via `init()` → `cli.RegisterCommands`. Go-focused (watch, review, health, issues, docblock) and PHP-focused (fmt, stan, psalm, audit, security, rector, infection, test).
 
 ## Rule Schema
 
-Each YAML file contains an array of rules with: id, title, severity, languages, tags, pattern (regex), exclude_pattern, fix, example_bad, example_good, detection type.
+Each YAML file in `catalog/` contains an array of rules:
+
+```yaml
+- id: go-sec-001            # unique identifier
+  title: "..."              # human-readable title
+  severity: high            # info | low | medium | high | critical
+  languages: [go]           # file extensions mapped via extensionMap
+  tags: [security]          # free-form tags
+  pattern: 'regex'          # Go regexp syntax
+  exclude_pattern: 'regex'  # optional, skips matching lines/files
+  fix: "..."                # suggested fix text
+  detection: regex          # only "regex" is actively matched
+  auto_fixable: false
+  example_bad: '...'
+  example_good: '...'
+```
+
+Rules are validated on load — `Validate()` checks required fields and compiles regex patterns.
 
 ## Coding Standards
 
-- UK English
+- UK English (e.g. `Analyse`, `Summarise`, `Colour`)
 - All functions have typed params/returns
-- Tests use testify
+- Tests use `testify` (assert/require)
-- License: EUPL-1.2
+- Licence: EUPL-1.2