arbiter-score 0.6.0__tar.gz

arbiter_score-0.6.0/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to Arbiter
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Setup
+
+```bash
+git clone https://github.com/hummbl-dev/arbiter.git
+cd arbiter
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[test]"
+PYTHONPATH=src python -m pytest tests/ -v
+```
+
+## Pull Requests
+
+- Branch from `main`
+- Keep PRs focused — one fix or feature per PR
+- All tests must pass before merge
+- Use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages
+
+## Developer Certificate of Origin (DCO)
+
+All contributions require a `Signed-off-by` line in each commit message, certifying that you have the right to submit the work under this project's license.
+
+```
+feat: add new analyzer for shellcheck
+
+Signed-off-by: Your Name <your.email@example.com>
+```
+
+Add it automatically with `git commit -s`.
+
+By signing off, you agree to the [Developer Certificate of Origin](https://developercertificate.org/):
+
+> I certify that (a) this contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or (b) it is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications; or (c) it was provided to me by someone who certified (a) or (b) and I have not modified it.
+
+## Reporting Issues
+
+Open an issue on GitHub. Include steps to reproduce, expected vs actual behavior, and your Python version.
+
+## Code Style
+
+- Python 3.11+
+- Lint with [ruff](https://docs.astral.sh/ruff/)
+- No third-party runtime dependencies in `src/arbiter/` (stdlib only)
+- Test dependencies (pytest, etc.) go in `[test]` extras

arbiter_score-0.6.0/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 HUMMBL, LLC
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

arbiter_score-0.6.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include LICENSE
+include README.md
+include ROADMAP.md
+include CONTRIBUTING.md
+recursive-include src/arbiter *.py
+recursive-include benchmarks *.json
+recursive-include examples *.yml *.md

arbiter_score-0.6.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: arbiter-score
+Version: 0.6.0
+Summary: Deterministic, polyglot code quality scoring with governance integration
+Author-email: Reuben Bowlby <reuben@hummbl.io>
+License: Apache-2.0
+Project-URL: Homepage, https://hummbl.io/audit
+Project-URL: Repository, https://github.com/hummbl-dev/arbiter
+Project-URL: Documentation, https://github.com/hummbl-dev/arbiter#readme
+Project-URL: Changelog, https://github.com/hummbl-dev/arbiter/releases
+Project-URL: Issues, https://github.com/hummbl-dev/arbiter/issues
+Keywords: code-quality,linting,scoring,governance,arbiter,hummbl
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: analyzers
+Requires-Dist: ruff>=0.4.0; extra == "analyzers"
+Requires-Dist: radon>=6.0.1; extra == "analyzers"
+Requires-Dist: vulture>=2.16; extra == "analyzers"
+Requires-Dist: bandit>=1.9.4; extra == "analyzers"
+Provides-Extra: test
+Requires-Dist: pytest>=9.0.3; extra == "test"
+Provides-Extra: all
+Requires-Dist: ruff>=0.4.0; extra == "all"
+Requires-Dist: radon>=6.0.1; extra == "all"
+Requires-Dist: vulture>=2.16; extra == "all"
+Requires-Dist: bandit>=1.9.4; extra == "all"
+Requires-Dist: pytest>=9.0.3; extra == "all"
+Dynamic: license-file
+
+# Arbiter
+
+[![CI](https://github.com/hummbl-dev/arbiter/actions/workflows/ci.yml/badge.svg)](https://github.com/hummbl-dev/arbiter/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/arbiter)](https://pypi.org/project/arbiter/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+[![Dependencies](https://img.shields.io/badge/core_deps-stdlib_only-brightgreen)]()
+
+**Agent-aware code quality scoring for multi-agent codebases.**
+
+In 2026, code is written by fleets of AI agents. Arbiter knows *who* wrote each line -- human or AI -- and scores quality accordingly.
+
+## Install
+
+```bash
+pip install arbiter                  # core (stdlib only)
+pip install "arbiter[analyzers]"     # + ruff, radon, vulture, bandit
+
+# Or from source
+git clone https://github.com/hummbl-dev/arbiter.git && cd arbiter
+pip install -e ".[analyzers]"
+```
+
+## Usage
+
+```bash
+# Quick score -- no persistence, instant feedback
+arbiter score /path/to/repo
+
+# Full analysis with per-commit agent attribution
+arbiter analyze /path/to/repo
+
+# Agent leaderboard -- who writes the best code?
+arbiter agents
+
+# Start the dashboard (single HTML file, no build step)
+arbiter serve --port 8080
+```
+
+## What It Scores
+
+Arbiter wraps tools you already trust and combines them into a deterministic composite score:
+
+| Analyzer | Tool | Weight | What It Finds |
+|----------|------|--------|---------------|
+| Lint | ruff | 35% | Style violations, import errors, bugbear patterns |
+| Security | bandit | 30% | Hardcoded secrets, shell injection, dangerous patterns |
+| Complexity | radon | 35% | Cyclomatic complexity (grade A-F per function) |
+| Dead Code | vulture | penalty | Unused functions, imports, variables |
+| Duplication | AST hash | penalty | Near-duplicate function bodies |
+| Semgrep | semgrep | opt-in | Custom rule enforcement (enable via config) |
+
+**Scoring:** `100 - (penalty / LOC) * normalization`. Grades: A (90+) | B (80+) | C (70+) | D (60+) | F (<60).
+
+## What Makes Arbiter Different
+
+| Feature | Traditional Tools | Arbiter |
+|---------|------------------|---------|
+| Agent attribution | None | First-class: tracks Claude, Codex, Gemini, Copilot, humans |
+| Per-commit scoring | Repo-wide only | Scores each commit's changed files individually |
+| Diff analysis | N/A | Score only what changed in a PR/branch |
+| Agent-specific gates | N/A | Different quality thresholds per agent trust tier |
+| Dashboard | SaaS login | Single HTML file with per-agent timelines and fleet view |
+| Dependencies | Heavy | Analysis tools only; core is stdlib Python |
+
+## CLI Reference
+
+```bash
+arbiter analyze <repo>                     # Full analysis + per-commit scoring + persist
+arbiter score <repo> [--json] [--exclude]  # Quick score (no persist)
+arbiter diff <repo> [--base main] [--json] # Score changed files vs base branch
+arbiter agents                             # Agent leaderboard
+arbiter trend [--days 30]                  # Quality trend
+arbiter worst [--limit 20]                 # Worst files
+arbiter commits [--agent claude]           # Recent commits with scores
+arbiter audit-fleet <directory>            # Audit all repos in a directory
+arbiter triage                             # Auto-classify repos: green/yellow/red/archive
+arbiter fix <repo> [--dry-run]             # Auto-fix ruff findings + before/after score
+arbiter serve [--port 8080]                # API + dashboard
+```
+
+## Tests
+
+```bash
+pip install ".[test]"
+PYTHONPATH=src python -m pytest tests/ -v    # 78 tests, <7 seconds
+```
+
+## Quality Gate
+
+Arbiter grades itself on every push and PR. The CI runs `arbiter score .` and fails if the score drops below **90 (A grade)**.
+
+```bash
+# Run the same check locally
+arbiter score . --fail-under 90
+
+# Score only your changed files against main
+arbiter diff . --base main --fail-under 80
+```
+
+## Requirements
+
+- Python 3.11+
+- git (for historian)
+- Optional: ruff, radon, vulture, bandit (install via `[analyzers]` extra)
+
+## HUMMBL Ecosystem
+
+Part of the [HUMMBL](https://github.com/hummbl-dev) cognitive AI architecture:
+
+- [hummbl-governance](https://github.com/hummbl-dev/hummbl-governance) -- Governance primitives that Arbiter scores against
+- [base120](https://github.com/hummbl-dev/base120) -- 120 mental models for structured reasoning
+- [mcp-server](https://github.com/hummbl-dev/mcp-server) -- MCP server for AI agent integration
+
+Learn more at [hummbl.io](https://hummbl.io).
+
+## License
+
+Apache 2.0 -- see [LICENSE](LICENSE).
+
+---
+
+Built by [HUMMBL LLC](https://hummbl.io) from production experience coordinating Claude, Codex, Gemini, and human engineers on a 14,000+ test codebase.

arbiter_score-0.6.0/README.md

@@ -0,0 +1,123 @@
+# Arbiter
+
+[![CI](https://github.com/hummbl-dev/arbiter/actions/workflows/ci.yml/badge.svg)](https://github.com/hummbl-dev/arbiter/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/arbiter)](https://pypi.org/project/arbiter/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+[![Dependencies](https://img.shields.io/badge/core_deps-stdlib_only-brightgreen)]()
+
+**Agent-aware code quality scoring for multi-agent codebases.**
+
+In 2026, code is written by fleets of AI agents. Arbiter knows *who* wrote each line -- human or AI -- and scores quality accordingly.
+
+## Install
+
+```bash
+pip install arbiter                  # core (stdlib only)
+pip install "arbiter[analyzers]"     # + ruff, radon, vulture, bandit
+
+# Or from source
+git clone https://github.com/hummbl-dev/arbiter.git && cd arbiter
+pip install -e ".[analyzers]"
+```
+
+## Usage
+
+```bash
+# Quick score -- no persistence, instant feedback
+arbiter score /path/to/repo
+
+# Full analysis with per-commit agent attribution
+arbiter analyze /path/to/repo
+
+# Agent leaderboard -- who writes the best code?
+arbiter agents
+
+# Start the dashboard (single HTML file, no build step)
+arbiter serve --port 8080
+```
+
+## What It Scores
+
+Arbiter wraps tools you already trust and combines them into a deterministic composite score:
+
+| Analyzer | Tool | Weight | What It Finds |
+|----------|------|--------|---------------|
+| Lint | ruff | 35% | Style violations, import errors, bugbear patterns |
+| Security | bandit | 30% | Hardcoded secrets, shell injection, dangerous patterns |
+| Complexity | radon | 35% | Cyclomatic complexity (grade A-F per function) |
+| Dead Code | vulture | penalty | Unused functions, imports, variables |
+| Duplication | AST hash | penalty | Near-duplicate function bodies |
+| Semgrep | semgrep | opt-in | Custom rule enforcement (enable via config) |
+
+**Scoring:** `100 - (penalty / LOC) * normalization`. Grades: A (90+) | B (80+) | C (70+) | D (60+) | F (<60).
+
+## What Makes Arbiter Different
+
+| Feature | Traditional Tools | Arbiter |
+|---------|------------------|---------|
+| Agent attribution | None | First-class: tracks Claude, Codex, Gemini, Copilot, humans |
+| Per-commit scoring | Repo-wide only | Scores each commit's changed files individually |
+| Diff analysis | N/A | Score only what changed in a PR/branch |
+| Agent-specific gates | N/A | Different quality thresholds per agent trust tier |
+| Dashboard | SaaS login | Single HTML file with per-agent timelines and fleet view |
+| Dependencies | Heavy | Analysis tools only; core is stdlib Python |
+
+## CLI Reference
+
+```bash
+arbiter analyze <repo>                     # Full analysis + per-commit scoring + persist
+arbiter score <repo> [--json] [--exclude]  # Quick score (no persist)
+arbiter diff <repo> [--base main] [--json] # Score changed files vs base branch
+arbiter agents                             # Agent leaderboard
+arbiter trend [--days 30]                  # Quality trend
+arbiter worst [--limit 20]                 # Worst files
+arbiter commits [--agent claude]           # Recent commits with scores
+arbiter audit-fleet <directory>            # Audit all repos in a directory
+arbiter triage                             # Auto-classify repos: green/yellow/red/archive
+arbiter fix <repo> [--dry-run]             # Auto-fix ruff findings + before/after score
+arbiter serve [--port 8080]                # API + dashboard
+```
+
+## Tests
+
+```bash
+pip install ".[test]"
+PYTHONPATH=src python -m pytest tests/ -v    # 78 tests, <7 seconds
+```
+
+## Quality Gate
+
+Arbiter grades itself on every push and PR. The CI runs `arbiter score .` and fails if the score drops below **90 (A grade)**.
+
+```bash
+# Run the same check locally
+arbiter score . --fail-under 90
+
+# Score only your changed files against main
+arbiter diff . --base main --fail-under 80
+```
+
+## Requirements
+
+- Python 3.11+
+- git (for historian)
+- Optional: ruff, radon, vulture, bandit (install via `[analyzers]` extra)
+
+## HUMMBL Ecosystem
+
+Part of the [HUMMBL](https://github.com/hummbl-dev) cognitive AI architecture:
+
+- [hummbl-governance](https://github.com/hummbl-dev/hummbl-governance) -- Governance primitives that Arbiter scores against
+- [base120](https://github.com/hummbl-dev/base120) -- 120 mental models for structured reasoning
+- [mcp-server](https://github.com/hummbl-dev/mcp-server) -- MCP server for AI agent integration
+
+Learn more at [hummbl.io](https://hummbl.io).
+
+## License
+
+Apache 2.0 -- see [LICENSE](LICENSE).
+
+---
+
+Built by [HUMMBL LLC](https://hummbl.io) from production experience coordinating Claude, Codex, Gemini, and human engineers on a 14,000+ test codebase.

arbiter_score-0.6.0/ROADMAP.md

@@ -0,0 +1,94 @@
+# Arbiter Roadmap
+
+Deterministic, transparent, decomposable code quality scoring — expanding from Python-first to polyglot, from CLI to platform.
+
+**Current state** (v0.3.0): 22 CLI subcommands, 6 analyzers, 273 tests, 8 PRs shipped, 6 OSS contributions tracked. Python-only scoring with noise filtering, fleet audit, HTML/PDF reports, weekly leaderboard automation, and a contribution tracker.
+
+---
+
+## Phase 1: Contribution Engine (Q2 2026)
+
+*Turn Arbiter from a scorer into an OSS contribution machine.*
+
+| Feature | Description | Status |
+|---------|-------------|--------|
+| `arbiter contribute` | One-command contribution pipeline: scan repo → find fixable findings → prepare branch → generate PR description → record in tracker | **Done** (#34) |
+| `arbiter watch` | Monitor upstream PR status via GitHub API — auto-update contribution tracker when PRs merge/close | **Done** (#29) |
+| `arbiter badge` | Generate SVG badge ("Arbiter Score: 96 A") for README.md — instant visibility for scored repos | **Done** (#32) |
+| CI quality gate template | GitHub Action template: `arbiter diff --fail-under 80` as a PR check — the enterprise on-ramp | **Done** (#30) |
+| `.arbiter.yml` config | Per-repo configuration: custom weights, excluded paths, rule overrides, noise threshold defaults | **Done** (#31) |
+| Benchmark dataset | Curated 100-repo reference set with pinned scores — regression testing for Arbiter itself | **Done** (#33) |
+
+## Phase 2: Polyglot Expansion (Q3 2026)
+
+*Score any repo, not just Python.*
+
+| Feature | Description | Tool | Status |
+|---------|-------------|------|--------|
+| Shell analyzer | Parse shellcheck JSON output → findings | shellcheck | **Done** (#36) |
+| JavaScript/TypeScript analyzer | Parse eslint JSON output → findings | eslint | **Done** (#40) |
+| Go analyzer | Parse golangci-lint JSON output → findings | golangci-lint | **Done** (#40) |
+| Rust analyzer | Parse clippy JSON output → findings | clippy | **Done** (#40) |
+| Language detection | Auto-detect primary languages, select applicable analyzers, report coverage | stdlib | **Done** (#40) |
+| Polyglot scoring weights | Adjust dimension weights per language (e.g., Rust security weight higher) | — | **Done** (#41) |
+
+## Phase 3: Intelligence Layer (Q3-Q4 2026)
+
+*Go from "what's wrong" to "what to do about it."*
+
+| Feature | Description | Status |
+|---------|-------------|--------|
+| `arbiter suggest` | AI-powered: rank findings by impact, suggest the 3 highest-ROI fixes | Planned |
+| `arbiter explain` | Natural language explanation of a score: why it's C, what would make it B | Planned |
+| Custom rule profiles | "Enterprise", "startup", "OSS maintainer" presets with different weights and thresholds | Planned |
+| Historical scoring | Weekly snapshots → trend graphs. "Your code improved from C to B this quarter" | Planned |
+| Team attribution | Who introduced which findings? Quality by contributor — agent leaderboard generalized to humans | Planned |
+| Dependency scoring | Score a repo's dependencies: maintained? CVEs? license conflicts? Last release date? | Planned |
+
+## Phase 4: Governance Integration (Q4 2026)
+
+*Connect Arbiter to HUMMBL's governance stack.*
+
+| Feature | Description | Status |
+|---------|-------------|--------|
+| Governance scoring dimension | Score repos on governance maturity: CONTRIBUTING.md, LICENSE, SECURITY.md, DCO, CoC | Planned |
+| VERUM-aligned audit trail | Every score is an append-only signed record — provable governance for enterprise | Planned |
+| Certified Adapter scoring | Score third-party adapters against HUMMBL certification criteria | Planned |
+| Compliance report mapping | Map Arbiter findings to NIST CSF / ISO 27001 / SOC 2 controls | Planned |
+| `arbiter certify` | Full certification workflow: score + governance + audit trail → certification decision | Planned |
+
+## Phase 5: Platform (2027)
+
+*Arbiter as a service.*
+
+| Feature | Description | Status |
+|---------|-------------|--------|
+| Arbiter Cloud | Hosted scoring API — score any public repo via REST endpoint | Planned |
+| GitHub App | Install on org → automatic PR quality checks on every push | Planned |
+| Dashboard | Web UI showing fleet scores, trends, team leaderboard, contribution tracker | Planned |
+| Webhook integration | Post score changes to Slack, Discord, email | Planned |
+| Public leaderboard | hummbl.io/leaderboard — weekly ranking of top OSS repos by quality | Planned |
+| PyPI package | `pip install arbiter-score` — the OSS distribution | Planned |
+
+---
+
+## Shipped (v0.1–v0.3)
+
+| Version | Date | Features |
+|---------|------|----------|
+| v0.1 | 2026-03 | Core scoring engine, ruff + bandit + radon analyzers, SQLite persistence, agent attribution |
+| v0.2 | 2026-04 | Fleet audit, triage, auto-fix, HTML/PDF reports, improvement loop (gaps), artifact scorers |
+| v0.3 | 2026-04-18 | `github-top`, `score-url`, `compare`, `leaderboard`, `contributions`, weekly Action, noise-threshold, CONTRIBUTING.md with DCO |
+| v0.4 | 2026-04-18 | Phase 1 (badge, watch, config, CI gate, contribute, benchmark) + Phase 2 (shellcheck, eslint, golangci-lint, clippy, lang-detect, polyglot weights). 19 PRs, 427 tests, 6 languages. |
+
+## Design Principles
+
+1. **Deterministic** — same code always produces the same score. No LLM in the scoring path.
+2. **Transparent** — every score decomposes into dimensions, every dimension into findings, every finding into a file:line.
+3. **Stdlib-only core** — analyzers call external tools via subprocess, but Arbiter itself has zero runtime dependencies.
+4. **Append-only tracking** — contribution ledger and gap tracker are JSONL, never mutated in place.
+5. **Polyglot by design** — the `Analyzer` interface is language-agnostic. Adding a language = one new analyzer class.
+
+---
+
+*Powered by [HUMMBL](https://hummbl.io) — governed AI for enterprise.*