{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/logo.svg\" alt=\"brooks-lint\" width=\"200\">\n</p>\n\n<h1 align=\"center\">brooks-lint</h1>\n\n<p align=\"center\">\n  <strong>AI code reviews grounded in twelve classic engineering books.<br>\n  Consistent. Traceable. Actionable.</strong>\n</p>\n\n<p align=\"center\">\n  <strong>English</strong> ·\n  <a href=\"README.zh-CN.md\">简体中文</a> ·\n  <a href=\"README.zh-TW.md\">繁體中文</a> ·\n  <a href=\"README.ja.md\">日本語</a> ·\n  <a href=\"README.ko.md\">한국어</a> ·\n  <a href=\"README.es.md\">Español</a>\n</p>\n\n<p align=\"center\">\n  <a href=\"#quick-start\">Quick Start</a> •\n  <a href=\"#the-six-decay-risks\">The Six Decay Risks</a> •\n  <a href=\"#what-it-looks-like\">What It Looks Like</a> •\n  <a href=\"#benchmark\">Benchmark</a> •\n  <a href=\"#installation\">Installation</a>\n</p>\n\n<p align=\"center\">\n  <img src=\"https://img.shields.io/badge/version-1.5.0-blue.svg\" alt=\"Version\">\n  <img src=\"https://img.shields.io/badge/license-MIT-green.svg\" alt=\"MIT License\">\n  <img src=\"https://img.shields.io/badge/Claude_Code-Plugin-blueviolet.svg\" alt=\"Claude Code Plugin\">\n  <img src=\"https://img.shields.io/badge/Codex_CLI-Skill-orange.svg\" alt=\"Codex CLI Skill\">\n  <img src=\"https://img.shields.io/github/stars/hyhmrright/brooks-lint?style=social\" alt=\"GitHub Stars\">\n</p>\n\n<p align=\"center\">\n  <a href=\"https://trendshift.io/repositories/47738\" target=\"_blank\"><img src=\"https://trendshift.io/api/badge/trendshift/repositories/47738/daily?language=JavaScript\" alt=\"#2 JavaScript Repository of the Day | Trendshift\" style=\"width: 250px; height: 55px;\" width=\"250\" height=\"55\"/></a>\n</p>\n\n<p align=\"center\">\n  <img src=\"assets/banner-en.svg\" alt=\"Your code → 12 classics → 12 decay risks → cited findings\" width=\"900\">\n</p>\n\n<p align=\"center\">\n  <a href=\"https://hyhmrright.github.io/brooks-lint/\"><img src=\"assets/demo.gif\" alt=\"brooks-lint reviewing code: a /brooks-review command produces a 28/100 health score and cited Symptom → Source → Consequence → Remedy findings\" width=\"820\"></a>\n</p>\n\n<p align=\"center\">\n  <strong><a href=\"https://hyhmrright.github.io/brooks-lint/\">→ Visit the website</a></strong>\n</p>\n\n---\n\n> *\"The bearing of a child takes nine months, no matter how many women are assigned.\"*\n> — Frederick Brooks, *The Mythical Man-Month* (1975)\n\n**50 years later, Brooks was still right — and so were McConnell, Fowler, Martin, Hunt & Thomas, Evans, Ousterhout, Winters, Meszaros, Osherove, Feathers, and the Google Testing team.**\n\nMost code quality tools count lines and cyclomatic complexity. **brooks-lint** goes deeper — it diagnoses your code against six decay risk dimensions synthesized from twelve classic engineering books, producing structured findings with book citations, severity labels, and concrete remedies every time.\n\nFor the full source-to-skill mapping, including exceptions and false-positive guards, see\n[`skills/_shared/source-coverage.md`](skills/_shared/source-coverage.md).\n\n## Quick Start\n\n```bash\n# Claude Code\n/plugin marketplace add hyhmrright/brooks-lint\n/plugin install brooks-lint@brooks-lint-marketplace\n\n# Any other Agent Skills platform — Cursor · Codex · Gemini · Copilot · Windsurf · OpenCode · Kiro · Bob …\ncurl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- <platform>\n```\n\nThen just ask (\"review this PR\", \"audit the architecture\"), or run one of the six commands —\n`/brooks-review`, `/brooks-audit`, `/brooks-debt`, `/brooks-test`, `/brooks-health`, `/brooks-sweep`\n([what each one does](#slash-commands)).\n\nEvery finding comes back as **Symptom → Source → Consequence → Remedy** with a book citation and a\n0–100 Health Score. Full install options (10 more platforms) and CI/CD setup are [below](#installation).\n\n## The Twelve Books\n\n| Book | Author | Contributes to |\n|------|--------|----------------|\n| *The Mythical Man-Month* (1975) | Frederick P. Brooks Jr. | R2, R4, R5 |\n| *Code Complete* (1993, 2nd ed. 2004) | Steve McConnell | R1, R4 |\n| *Refactoring* (1999, 2nd ed. 2018) | Martin Fowler | R1, R2, R3, R4, R6 |\n| *Clean Architecture* (2017) | Robert C. Martin | R2, R5 |\n| *The Pragmatic Programmer* (1999, 20th Anniv. 2019) | Andrew Hunt & David Thomas | R2, R3, R4, R5, T2, T3 |\n| *Domain-Driven Design* (2003) | Eric Evans | R1, R3, R6 |\n| *A Philosophy of Software Design* (2018) | John Ousterhout | R1, R4 |\n| *Software Engineering at Google* (2020) | Winters, Manshreck & Wright | R2, R5 |\n| *The Art of Unit Testing* (2009, 3rd ed. 2023) | Roy Osherove | T1, T2, T4, T5 |\n| *How Google Tests Software* (2012) | Whittaker, Arbon & Carollo | T5, T6 |\n| *Working Effectively with Legacy Code* (2004) | Michael Feathers | T4, T5, T6 |\n| *xUnit Test Patterns* (2007) | Gerard Meszaros | T1, T2, T3, T4 |\n\n## The Six Decay Risks\n\nbrooks-lint evaluates your code across **six production-code decay risks** and **six test-suite decay risks** synthesized from twelve classic engineering books:\n\n| Decay Risk | Diagnostic Question | Sources |\n|------------|---------------------|---------|\n| 🧠 Cognitive Overload | How much mental effort to understand this? | Code Complete, Refactoring, DDD, Philosophy of SD |\n| 🔗 Change Propagation | How many unrelated things break on one change? | Refactoring, Clean Architecture, Pragmatic, SE@Google |\n| 📋 Knowledge Duplication | Is the same decision expressed in multiple places? | Pragmatic, Refactoring, DDD |\n| 🌀 Accidental Complexity | Is the code more complex than the problem? | Refactoring, Code Complete, Brooks, Philosophy of SD |\n| 🏗️ Dependency Disorder | Do dependencies flow in a consistent direction? | Clean Architecture, Brooks, Pragmatic, SE@Google |\n| 🗺️ Domain Model Distortion | Does the code faithfully represent the domain? | DDD, Refactoring |\n\n> Philosophy of SD = *A Philosophy of Software Design* (Ousterhout) · SE@Google = *Software Engineering at Google* (Winters et al.)\n\n## What It Looks Like\n\nGiven this code:\n\n```python\nclass UserService:\n    def update_profile(self, user_id, name, email, avatar_url):\n        user = self.db.query(f\"SELECT * FROM users WHERE id = {user_id}\")\n        user['email'] = email\n        ...\n        if user['email'] != email:   # always False — silent bug\n            self.smtp.send(...)\n        points = user['login_count'] * 10 + 500\n        self.db.execute(f\"UPDATE loyalty SET points={points} WHERE user_id={user_id}\")\n```\n\nbrooks-lint produces:\n\n---\n\n**Health Score: 28/100**\n\n*This method concentrates four unrelated business responsibilities into a single function, contains a logic bug that silently suppresses email change notifications, and is wide open to SQL injection.*\n\n### 🔴 Change Propagation — Single Method Changes for Four Unrelated Business Reasons\n**Symptom:** `update_profile` performs profile field updates, email change notifications, loyalty points recalculation, and cache invalidation all in one method body.\n**Source:** Fowler — *Refactoring* — Divergent Change; Hunt & Thomas — *The Pragmatic Programmer* — Orthogonality\n**Consequence:** Any change to the loyalty formula risks breaking email notifications and vice versa. Every edit carries regression risk across four unrelated domains simultaneously.\n**Remedy:** Extract `NotificationService`, `LoyaltyService`, and `UserCacheInvalidator`. `UserService.update_profile` should orchestrate by calling each — it should hold no implementation logic itself.\n\n### 🔴 Domain Model Distortion — Silent Logic Bug: Email Notification Never Fires\n**Symptom:** `user['email'] = email` overwrites the old value before `if user['email'] != email` — the condition is always `False`. The notification is dead code.\n**Source:** McConnell — *Code Complete* — Ch. 17: Unusual Control Structures\n**Consequence:** Users are never notified when their email address changes. Silent data integrity failure — the system appears functional while violating a business rule.\n**Remedy:** Capture `old_email = user['email']` before any mutation. Compare against `old_email`, not `user['email']`.\n\n*(+ 6 more findings including SQL injection, dependency disorder, magic numbers)*\n\n### Architecture Audit with Dependency Graph\n\nIn Mode 2 (Architecture Audit), brooks-lint generates a **Mermaid dependency graph** at the top of the report. Modules are color-coded by severity: red = Critical findings, yellow = Warning, green = clean.\n\n```mermaid\ngraph TD\n    subgraph src/api\n        AuthController\n        UserController\n    end\n    subgraph src/domain\n        UserService\n        OrderService\n    end\n    subgraph src/infra\n        Database\n        EmailClient\n    end\n\n    AuthController --> UserService\n    UserController --> UserService\n    UserController --> OrderService\n    OrderService --> UserService\n    OrderService --> EmailClient\n    UserService --> Database\n    EmailClient -.->|circular| OrderService\n\n    classDef critical fill:#ff6b6b,stroke:#c92a2a,color:#fff\n    classDef warning fill:#ffd43b,stroke:#e67700\n    classDef clean fill:#51cf66,stroke:#2b8a3e,color:#fff\n\n    class OrderService,EmailClient critical\n    class AuthController warning\n    class UserService,UserController,Database clean\n```\n\nThe graph renders natively in GitHub, Notion, and other Markdown environments — no extra tools needed.\n\n## See More Examples\n\nThe [Full Gallery](docs/gallery.md) has real brooks-lint output across Python, TypeScript, Go, and Java — including PR reviews, architecture audits with Mermaid dependency graphs, tech debt assessments, and test quality reviews.\n\nNew to the decay risks? The [**Decay Risk Field Guide**](https://hyhmrright.github.io/brooks-lint/guide.html) explains all six — diagnostic question, signature symptoms, source books, and remedy for each.\n\n---\n\n## Benchmark\n\nTested across 3 real-world scenarios (PR review, architecture audit, tech debt assessment):\n\n| Criterion | brooks-lint | Claude alone |\n|-----------|:-----------:|:------------:|\n| Structured findings (Symptom → Source → Consequence → Remedy) | ✅ 100% | ❌ 0% |\n| Book citations per finding | ✅ 100% | ❌ 0% |\n| Severity labels (🔴/🟡/🟢) | ✅ 100% | ❌ 0% |\n| Health Score (0–100) | ✅ 100% | ❌ 0% |\n| Detects Change Propagation | ✅ 100% | ✅ 100% |\n| **Overall pass rate** | **94%** | **16%** |\n\nThe gap isn't what Claude *can* find — it's what it *consistently* finds, with traceable evidence and actionable remedies every time.\n\n### Reproducible benchmarks\n\nThe table above is illustrative. These numbers are **deterministic and you can reproduce them locally**:\n\n**Parser fidelity** — SARIF export and the CI gates depend on parsing the model's Markdown report correctly. Against a **frozen corpus of 30 real, model-generated reports** spanning all six modes (`evals/benchmark-corpus.json`), each paired with an **independently graded** finding inventory (a separate model pass, spot-checked by hand), the shipped parser scores — run `npm run benchmark`:\n\n| Metric (n = 30, frozen corpus) | Result |\n|---|:---:|\n| Exact severity-count match (parser vs. graded truth) | 30 / 30 |\n| Risk-code precision / recall | 100% / 100% (56 finding-level codes, 0 FP / 0 FN) |\n| Valid SARIF 2.1.0 emitted | 30 / 30 |\n\nBecause the parser is deterministic and the corpus is frozen, `npm run benchmark` gives everyone the same result, and `npm test` guards it as a regression. The corpus deliberately includes 9 false-positive / tradeoff reports (e.g. a ports-and-adapters design that *looks* like a dependency cycle) that must stay clean.\n\n**Scoring determinism** — for a fixed finding set (2 Critical / 3 Warning / 1 Suggestion), the strictness presets produce exactly the scores their `common.md` table predicts: strict **34**, balanced **54**, legacy-friendly **74** — and only `legacy-friendly` leads with the top-three fixes.\n\n**Model quality** — whether the model finds the *right* risks on real code is measured by the **57-scenario eval suite** (`evals/evals.json`): `npm run evals` (structural) and `npm run evals:live` (live, needs `ANTHROPIC_API_KEY`).\n\n> Scope & honesty: the parser numbers are deterministic and exactly reproducible. The strictness and eval-suite figures are single-run live measurements against the model and vary slightly run to run. The parser benchmark measures report-parsing fidelity (does the tooling read every finding the report states?), not whether a given finding is \"correct.\" The severity-count match is the fully independent signal; risk-code agreement also reflects the shared canonical name→code legend.\n\n## How It Compares\n\n| | brooks-lint | ESLint / Pylint | GitHub Copilot Review | Plain Claude |\n|---|:---:|:---:|:---:|:---:|\n| Detects syntax & style issues | — | ✅ | ✅ | ~ |\n| Structured diagnosis chain | ✅ | ❌ | ❌ | ❌ |\n| Traces findings to classic books | ✅ | ❌ | ❌ | ❌ |\n| Consistent severity labels | ✅ | ✅ | ~ | ❌ |\n| Architecture-level insights | ✅ | ❌ | ~ | ~ |\n| Domain model analysis | ✅ | ❌ | ❌ | ~ |\n| Zero config, no plugins to install | ✅ | ❌ | ✅ | ✅ |\n| Works with any language | ✅ | ❌ | ✅ | ✅ |\n\n> `~` = occasionally / inconsistently\n\n**brooks-lint doesn't replace your linter.** It catches what linters can't: architectural drift, knowledge silos, and domain model distortion — the problems that slow teams down for months before anyone notices.\n\n## Installation\n\n### Claude Code (recommended)\n\n```bash\n/plugin marketplace add hyhmrright/brooks-lint\n/plugin install brooks-lint@brooks-lint-marketplace\n```\n\nShort-form commands (`/brooks-review`) are auto-installed on first session start — or run\n`bash hooks/session-start` yourself. To skip the marketplace:\n`mkdir -p ~/.claude/skills/brooks-lint && cp -r skills/* ~/.claude/skills/brooks-lint/`.\n\n### Gemini CLI · Codex CLI\n\n```bash\n/extensions install https://github.com/hyhmrright/brooks-lint   # Gemini CLI\n```\n```\nInstall the brooks-lint skill from hyhmrright/brooks-lint       # ask inside a Codex session\n```\n\nOr use the installer below: `./scripts/install.sh gemini` / `./scripts/install.sh codex`.\n\n### Every other platform — OpenCode · Cursor · Windsurf · Antigravity · pi · Copilot · Kiro · Factory Droid · DeepSeek Harness · IBM Bob\n\nbrooks-lint ships as standard [Agent Skills](https://agentskills.io). **Any agent that loads Agent\nSkills runs all six modes with no conversion** — one command installs them:\n\n```bash\n# pick your platform; --project installs into the current repo instead of your global config\ncurl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- <platform>\n#   <platform> = opencode · cursor · windsurf · antigravity · pi · kiro · copilot · droid · dsh · gemini · codex · claude · bob · agents\n```\n\nThe installer copies the skills **flat** into the right folder, so the shared framework\n(`../_shared/`) always resolves — you can't get the layout wrong. Then just ask (\"review this PR\",\n\"audit the architecture\") and the matching skill auto-triggers from its `description`.\n\n| Platform | Installs into | Also reads | Guide |\n|---|---|---|---|\n| OpenCode | `~/.config/opencode/skills` | `~/.claude/skills`, `AGENTS.md` | [setup](docs/opencode-setup.md) |\n| Cursor (2.4+) | `~/.cursor/skills` | `.agents/skills`, `AGENTS.md` | [setup](docs/cursor-setup.md) |\n| Windsurf (Cascade) | `~/.codeium/windsurf/skills` | `AGENTS.md` | [setup](docs/windsurf-setup.md) |\n| Antigravity (Google) | `.agent/skills` (`--project`) | `AGENTS.md`, `GEMINI.md` | [setup](docs/antigravity-setup.md) |\n| pi (earendil-works) | `~/.pi/agent/skills` | — | [setup](docs/pi-setup.md) |\n| GitHub Copilot | `.github/skills` (`--project`) | `.claude/skills`, `AGENTS.md` | [setup](docs/copilot-setup.md) |\n| Kiro (AWS) | `~/.kiro/skills` | `AGENTS.md` | [setup](docs/kiro-setup.md) |\n| Factory Droid | `~/.factory/skills` | `AGENTS.md` | [setup](docs/factory-droid-setup.md) |\n| DeepSeek Harness (`dsh`) | `~/.dsh/skills` | `~/.agents/skills`, `AGENTS.md` | [setup](docs/dsh-setup.md) |\n| IBM Bob (`bob`) | `~/.bob/skills` | `AGENTS.md` | [setup](docs/bob-setup.md) |\n\nKiro, Factory Droid, and DeepSeek Harness also auto-register `/brooks-review`. New to skills, or\nusing an agent not listed? See **[docs/getting-started.md](docs/getting-started.md)**.\n\n> **🧪 Verification status.** Claude Code, Gemini CLI, and Codex CLI are maintainer-verified. The\n> ten platforms above are documented from each tool's official skill spec and verified at the\n> file-layout level (the installer is tested), but not yet run end-to-end by the maintainer on every\n> platform. Tried one — working **or** broken?\n> [Open an issue](https://github.com/hyhmrright/brooks-lint/issues/new) with the platform, version,\n> and what you saw. Another Agent-Skills agent? It almost certainly works the same way — tell us and\n> we'll add it.\n\n## Slash Commands\n\n| Command | What it does |\n|---------|--------------|\n| `/brooks-review` | Paste a diff or point the AI at changed files. Diagnoses each of the six decay risks in Symptom → Source → Consequence → Remedy format. |\n| `/brooks-audit` | Maps module dependencies (with a Mermaid graph), identifies circular dependencies, and checks Conway's Law alignment. |\n| `/brooks-debt` | Classifies debt across the six decay risks, scores each finding by Pain × Spread, and produces a repayment roadmap with Critical / Scheduled / Monitored tiers. |\n| `/brooks-test` | Audits the suite against six test-space decay risks — Test Obscurity, Test Brittleness, Test Duplication, Mock Abuse, Coverage Illusion, Architecture Mismatch. |\n| `/brooks-health` | Abbreviated scans across all four quality dimensions → one weighted composite Health Score. Use it before a release or when onboarding a team. |\n| `/brooks-sweep` | Unified scan across R1–R6, T1–T6, and architecture, then applies fixes: safe changes auto-applied, multi-file changes confirmed, architectural decisions flagged as manual. Outputs a Fix Log and score delta. |\n\n**Syntax by platform.** Claude Code also accepts the namespaced form\n`/brooks-lint:brooks-review` — short forms are auto-installed on first session start by the\nsession-start hook. Codex CLI uses `$brooks-review`. Gemini CLI uses the table as written.\nOpenCode, Cursor, Antigravity, pi, and DeepSeek Harness invoke Agent Skills from each skill's\n`description`, so just ask (\"review this PR\", \"where's our worst tech debt?\"); for explicit\ninvocation use the platform's own syntax (pi registers each skill as `/skill:brooks-review`; dsh\ntakes the table as written, from its `/` menu or typed inline). On every platform the\nskills also trigger automatically when you discuss code quality, architecture, or test health.\n\n> PR reviews include a lightweight Step 7 Quick Test Check automatically (skipped for docs-only\n> diffs). For a full test audit, run `/brooks-test`; for a deep dive on any single dimension,\n> use that dimension's own skill rather than `/brooks-health`.\n\n## Configuration\n\nPlace a `.brooks-lint.yaml` in your project root to customize review behavior:\n\n```yaml\nversion: 1\n\nstrictness: balanced   # strict | balanced (default) | legacy-friendly — softer scoring for legacy code\n\ndisable:\n  - T5   # skip coverage metrics check — we don't enforce coverage\n\nseverity:\n  R1: suggestion   # downgrade Cognitive Overload findings for this domain\n\nignore:\n  - \"**/*.generated.*\"\n  - \"**/vendor/**\"\n\n# custom_risks:   # define project-specific Cx codes — see skills/_shared/custom-risks-guide.md\n# suppress:       # downgrade specific findings by risk + path (e.g. accepted legacy debt)\n```\n\nCopy [`.brooks-lint.example.yaml`](.brooks-lint.example.yaml) as a starting point.\nAll settings are optional — omit the file entirely for default behavior.\n\n| Setting | Description |\n|---------|-------------|\n| `strictness` | Scoring preset: `strict`, `balanced` (default), or `legacy-friendly` (lighter deductions, leads with top fixes) |\n| `disable` | Risk codes to skip (`R1`–`R6`, `T1`–`T6`) |\n| `severity` | Override severity tier (`critical` / `warning` / `suggestion`) |\n| `ignore` | Glob patterns for files to exclude |\n| `focus` | Evaluate only these risk codes (cannot combine with `disable`) |\n| `custom_risks` | Define project-specific risk codes (`C1`, `C2`, …) — see [`custom-risks-guide.md`](skills/_shared/custom-risks-guide.md) |\n| `suppress` | Downgrade specific findings by risk + path (optional `expires:` date) |\n\n---\n\n## Why These Books, Why Now?\n\n> *\"The complexity of software is an essential property, not an accidental one.\"*\n> — Frederick Brooks\n\nAI can help you write code faster, but it can't tell you whether you're building a cathedral or a\ntar pit — and the decay risks these authors identified only get sharper as generation gets cheaper.\nAdding an AI assistant doesn't fix cognitive overload or domain model distortion; generating more\ncode increases change propagation and knowledge duplication; moving faster makes accidental\ncomplexity and dependency disorder more dangerous.\n\n## Project Structure\n\nEvery skill is one `SKILL.md` (trigger + process skeleton) plus its own guide:\n\n```\nbrooks-lint/\n├── .claude-plugin/ · .codex-plugin/  # plugin metadata per platform\n├── skills/\n│   ├── _shared/          # common.md (Iron Law, config, report template, Health Score)\n│   │                     # source-coverage.md · decay-risks.md (R1–R6)\n│   │                     # test-decay-risks.md (T1–T6) · remedy-guide.md · custom-risks-guide.md\n│   ├── brooks-review/    # Mode 1: PR Review          → pr-review-guide.md\n│   ├── brooks-audit/     # Mode 2: Architecture Audit → architecture-guide.md, onboarding-guide.md\n│   ├── brooks-debt/      # Mode 3: Tech Debt          → debt-guide.md\n│   ├── brooks-test/      # Mode 4: Test Quality       → test-guide.md\n│   ├── brooks-health/    # Mode 5: Health Dashboard   → health-guide.md\n│   └── brooks-sweep/     # Mode 6: Full Sweep         → sweep-guide.md\n├── hooks/                # SessionStart hook\n├── commands/             # short-form command wrappers (auto-installed by the hook)\n├── evals/                # 57-scenario eval suite + frozen parser-fidelity corpus\n└── assets/               # logo, banner, demo\n```\n\n## CI/CD Integration\n\nAutomate brooks-lint on every PR using the GitHub Action:\n\n```yaml\n# .github/workflows/brooks-lint.yml\nname: Brooks-Lint PR Review\non:\n  pull_request:\n    types: [opened, synchronize, reopened]\n\njobs:\n  brooks-lint:\n    runs-on: ubuntu-latest\n    permissions:\n      pull-requests: write\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n      - uses: hyhmrright/brooks-lint/.github/actions/brooks-lint@v1.4.3\n        with:\n          mode: review\n          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}\n          fail-below: 70\n```\n\nSee [`docs/github-action-example.yml`](docs/github-action-example.yml) for the full template.\n\nThe action posts the review as a PR comment and optionally fails the check if the Health Score drops below a threshold. If `.brooks-lint-history.json` is committed to your repo, the comment also includes a trend delta (e.g., \"85 → 82 (−3) over last 3 runs\").\n\n**Quality gates and Code Scanning.** Beyond `fail-below`, the action exposes:\n\n```yaml\n        with:\n          mode: review\n          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}\n          fail-on: critical            # fail on any Critical finding (none | warning | critical)\n          fail-on-regression: true     # fail if the Health Score dropped vs the last run\n          sarif-file: brooks-lint.sarif  # also upload findings to GitHub Code Scanning\n```\n\n`fail-on-regression` reads `.brooks-lint-history.json`, so commit that file to enforce \"no new regressions\". Setting `sarif-file` makes findings appear inline on the PR's **Files changed** tab and requires `security-events: write` permission on the job.\n\n**Custom API endpoint.** `api-base-url` points the action at any Anthropic-compatible `/v1/messages` endpoint — a self-hosted proxy, an LLM gateway, a regional mirror — instead of `api.anthropic.com`. Pass that endpoint's key as `anthropic-api-key` and the model id it expects as `model`:\n\n```yaml\n        with:\n          mode: review\n          api-base-url: https://your-gateway.example.com\n          anthropic-api-key: ${{ secrets.GATEWAY_API_KEY }}\n          model: gateway-model-id\n```\n\nbrooks-lint sends your diff to whatever host you name here, so only point it at one you trust with your source. Running `scripts/ci-review.mjs` yourself needs no flag at all — the Anthropic SDK reads `ANTHROPIC_BASE_URL` directly.\n\n**Cost:** ~$0.05–0.15 per PR run depending on diff size and model. Recommend running on `pull_request` events only.\n\n## Roadmap\n\n**Current state (v1.4):** 12-book foundation, 6 production decay risks (R1–R6) + 6 test decay\nrisks (T1–T6), 6 skills, CI quality gates, SARIF output for GitHub Code Scanning, strictness\npresets, and a reproducible parser-fidelity benchmark.\n\n<details><summary>Milestones v0.2 → v1.4</summary>\n\n- **v0.2–v0.4**: Plugin infrastructure, six-book framework, decay risk dimensions, benchmark suite\n- **v0.5–v0.7**: Test Quality Review, Mermaid dependency graph, `.brooks-lint.yaml`, 10-book expansion\n- **v0.8–v0.9**: Independent skill architecture; step validation, auto-diff scope, `/brooks-health`, trend tracking, triage mode, `--fix` remedies, GitHub Action\n- **v1.0–v1.2**: Eval automation, custom `Cx` risk codes, Full Sweep skill, `npm run bump` version propagation\n- **v1.3**: Codex marketplace metadata, one-command multi-platform installer, localized READMEs + landing site\n- **v1.4**: SARIF output, CI severity + regression gates, strictness presets, 57-scenario eval suite, `npm run benchmark`\n</details>\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). The most valuable contributions right now are new eval\ntest cases and improved decay-risk symptom patterns. Run `/brooks-review` on your own PR — we\nreview contributions with the tool we're building.\n\n## License\n\nMIT License — see [LICENSE](LICENSE) for details.\n\n## Acknowledgments\n\nThis project stands on the shoulders of twelve giants — see [The Twelve Books](#the-twelve-books)\nabove for the full list with editions. The decay risks encoded in this tool are our synthesis of\ntheir ideas, applied to modern code quality assessment.\n\n---\n\n## Star History\n\n[![Star History](assets/star-history.svg)](https://github.com/hyhmrright/brooks-lint/stargazers)\n\n---\n\n<p align=\"center\">\n  <strong>⭐ If this tool helped you see your codebase differently, give it a star!</strong>\n</p>\n",
  "bytes": 26339,
  "sha": "7f5bdac4f400eb5ea3667f7b7460d5908f7c89099744fcace9536cf856a5ba9f",
  "repo_slug": "hyhmrright/brooks-lint",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_hyhmrright_brooks_lint_c65ac271/readme"
}