Documentation
Every document here has a genre, and the genre determines what it may assert. This is not filing tidiness: mixing genres is how a claim in this repository once reached the README as settled fact and had to be retracted. See the evidence standard.
| Genre | May assert | Changes when |
|---|---|---|
| Governing | What the product is for and what it may never claim | The product's purpose changes |
| Normative | The standard applied to every repository — weights, bands, thresholds | A judgment is deliberately revised |
| Decision | One architectural choice, its context, its consequences | Superseded by a later decision |
| Empirical | What was measured, with pinned inputs and stated limits | New evidence is derived |
| Operational | How to run, configure, and integrate the tool | Behavior changes |
| Generated | Output of a command; never hand-edited | Regenerated |
Where empirical numbers may appear. studies.md is the source of record: every result lives there in full, with its method, controls and limits. Other documents may quote an approved summary sentence verbatim — a governing document that cannot state what the product may claim is not governing anything — and may not restate a result's interpretation in their own words. The approved sentences are listed under Approved summaries and test_docs_links.py compares quotations character for character. It detects sentences carrying an "N of M", a p-value or a "median of N"; it does not detect percentage-only claims, because this repository also writes "92% coverage gate" and "25% of modularity" and no pattern separates those from a study figure. The recognized statistical forms are checked automatically; discovering a new or paraphrased percentage claim is a review responsibility. The canonical wording for the percentage claims that exist is in the approved list so there is something to review against, not because the build enforces it.
Verbatim, not "contains the same numbers": an earlier guard checked whether each figure appeared somewhere in studies.md, which cannot detect a swapped attribution or a different sentence assembled from the same digits. It also only examined blockquotes, so a restatement written as ordinary prose passed unread.
Start here
| Document | Genre | What it settles |
|---|---|---|
| Product intent | Governing | What this is, what it promises, what it must never claim, and the bar each kind of claim must clear. When another document disagrees with this one, this one is right. |
| Architecture | Governing | Layers, dependency rules, invariants and where each is enforced, and the known debt — as the code is today |
| Target architecture | Decision | Where the design is going: analyzer pipeline, pillars, band matrix, work order. Nothing here ships |
| Philosophy | Governing | Why the tool is AI-specific — volume, not pathology |
Decisions
The decision register lists every architectural decision and its status, including the ones not yet made. It also holds the ADR template and the rule for when to write one.
| Document | Status |
|---|---|
| ADR 001 — Evidence and verification | Accepted — status in the register |
| ADR 002 — Null verified grade in CI | Rejected — assumed a CI grade gate that does not exist |
| ADR 003 — Deterministic semantic policy | Proposed — repository semantics without rubric drift |
| ADR 004 — Economic context | Accepted — status in the register. v1 scenario layer; score and grade stay money-free |
| ADR 005 — Insufficient population | Accepted — status in the register. No rate without a denominator that supports one |
| ADR 006 — Analyzer evidence | Accepted — status and remaining gaps in the register. Optional analyzers report measurements, findings, provenance, and coverage; a complete concept set is the primary evidence for the point estimate, and the built-in detectors remain the fallback |
| ADR 007 — Pillars and practice | Accepted — status in the register. Five-pillar taxonomy; practice maturity separate from code condition. The §4 rename was refused, not deferred |
| ADR 008 — Translation and decision | Accepted — status in the register. Tool output to scoring input, the LLM boundary, CLI and MCP |
| ADR 009 — Scan history | Accepted — status in the register. Maintainability is a trend; comparability is checked before any of it is computed |
| ADR 010 — Repository discovery | Accepted — status in the register. What is in this tree and whose code it is, from evidence the repository provides |
| ADR 011 — Three report presentations | Accepted — status in the register. Chat, Markdown file, and one HTML file from one report, plus json for a machine (amended, D201); the host asks, flags win, CI never asks |
| Report contract | Current — the report's producers, consumers, and schema-version policy |
New ADRs are adr-NNN-short-title.md, numbered in order, added to the register, and never edited after acceptance except to record implementation progress or mark them superseded.
The standard, and what has been measured
| Document | Genre | Note |
|---|---|---|
| Maintainability standard | Normative | The rubric, its weights and bands, the calibration method, and the reference corpus. Judgments applied uniformly to every repository; requires no study to be legitimate |
| Studies and measured results | Empirical | Every claim about the world, with pinned inputs, controls and stated limits — the bounded-prompt experiment, the retracted AI-authorship claim, and fix breadth. Licenses nothing beyond the sentence stated with each result |
| Self-audit | Generated | This tool run against this repository, stamped with the source commit that produced it; provenance is the stamp, not a fixed distance from current HEAD |
| FOSS tool inventory | Empirical | Every free quality analyzer this agent could run, which were installed and executed here, and what each one found. Separates proven from listed |
| The analyzer pool | Reference | The 760-tool catalog, its license classification, and the depth and license-policy selectors that narrow it at run time |
Operating the tool
| Document | Covers |
|---|---|
| Chat workflow help | What the agent does, first-run questions and grants, analyzer evidence, and reading the report loop |
| CLI | Commands and flags |
| Machine setup | What a development machine must configure before it commits: identity, signing, the Agent: trailer |
| Config schema | Configuration file |
| Language support | What is parsed, and how well |
| PR and baseline workflows | Incremental adoption |
| Adapters | Ingesting other analyzers |
| External quality tools | Sitting alongside SonarQube and friends |
| IDE and agent integration | Claude Code, Codex, Copilot Chat, Cursor |
| Roadmap | What is planned, and what is deliberately refused |
| Release plan | The ordered work from here to 1.0, with an exit condition per task |
| Migrating to 0.7 | Reference |
| Migrating to 1.0 | Reference |
| Report validation | Fourteen real repositories against a frame written before selection: what the output actually looked like, and the defect it exposed |
Adding a claim to any of these
- Decide its tier — deterministic property, standard, or empirical (definitions).
- Meet that tier's bar. A property needs a test over the real input space; a standard needs to be explicit and uniform; an empirical claim needs pinned inputs and a control.
- Put it in a document of the matching genre.
- If it is empirical and later changes, correct it everywhere it is quoted, naming the correction rather than rewriting silently.