honestreview 0.2.0__tar.gz

honestreview-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ash Damle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

honestreview-0.2.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: honestreview
+Version: 0.2.0
+Summary: Review a repo at the granularity its defects actually live at — and never overstate what you checked
+Author: Ash Damle
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ashdamle/honestreview
+Project-URL: Repository, https://github.com/ashdamle/honestreview
+Project-URL: Issues, https://github.com/ashdamle/honestreview/issues
+Keywords: code-review,static-analysis,llm,doctrine,pre-commit,hooks
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: symgrep-codesearch<1,>=0.6
+Requires-Dist: llm-spendguard[anthropic,openai]<1,>=0.11
+Requires-Dist: fastmcp<5,>=2
+Requires-Dist: numpy<3,>=1.24
+Provides-Extra: learn
+Requires-Dist: sentence-transformers<7,>=3; extra == "learn"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# honestreview
+
+Review a repo at the granularity its defects actually live at — and never overstate what you checked.
+
+## Why
+
+A review can only find defects that **fit inside the unit it looks at**.
+
+Measured on one codebase: three waves of four-vendor per-file review, ~500 findings, and it missed 13
+functions copy-pasted between two files, four writers of one settings file (three destructive — one of them
+later destroyed the file), and a producer/consumer pair reading and writing different tables.
+
+None of that was carelessness. The reviewer was shown **one file at a time**, so a two-file defect was never
+in the room, and no amount of care recovers evidence that is not in the context window. When something is
+missed, the first question is *"was it even in the room?"* — not *"why wasn't it noticed?"*
+
+So "I reviewed the repo" means nothing without the axis:
+
+| axis | unit in context | finds | blind to |
+|---|---|---|---|
+| **file** | one file | swallowed exception, wrong branch, unguarded index | anything whose other half is elsewhere |
+| **concept** | every implementation of one job, in full | DRIFT — copies that now disagree, one of them wrong | a concept correctly duplicated |
+| **seam** | every writer + reader of one resource | CONTRACT GAPS — each side correct, the gap wrong | anything that is nowhere |
+| **invariant** | the whole repo vs one claim it makes | **ABSENCE** — a discipline present in NO file | nothing structural |
+| **name** | all definitions sharing a bare name | COLLISION / DUPLICATION / PROTOCOL | — |
+
+**`invariant` is skipped most and matters most: it is the only axis that can find something MISSING.**
+*"There is no backup before any mutation in this repo"* is true, catastrophic, and appears in zero files.
+
+Plus two that cut across all of them: **`silent`** (swallowed failures) and **`unwired`** (capabilities built
+and never connected — worse than a bug, because the code *looks* protected).
+
+## A finding is not a finding until something tried to kill it
+
+Raw multi-vendor review over-calls badly. Measured: **60 "dangerous" silent failures became 26** once
+independent refuters were told to knock each one down and default to refuted when unsure — and **2** after a
+truncation bug in the refuter itself was fixed.
+
+Three states, kept separate:
+
+- **SURVIVED** — attempts to refute it failed. A finding.
+- **REFUTED** — the claim did not hold. Correctly closed.
+- **UNVERIFIED** — the check did not complete. **Neither of the other two.** Collapsing it is how
+  *"2 survived, 7 unverified"* got reported as *"9 survived"*.
+
+## Use
+
+```bash
+pip install honestreview               # pulls symgrep-codesearch + llm-spendguard + fastmcp from PyPI
+pip install "honestreview[learn]"      # + the local sentence-transformers embedder (optional; pulls torch)
+
+# honestreview runs UNDER the spendguard gate, so no axis can ever spend ungated. Arm it once:
+spendguard install-hook --venv <your-venv>     # then `spendguard doctor` must print: ENFORCING HERE: YES
+
+honestreview all <root>                # every axis, cheapest-first — ESTIMATE ONLY
+honestreview all <root> --run          # actually review
+honestreview invariant <root> --run    # the axis that finds what is missing
+honestreview ledger                    # every pass, every verdict, what is still open
+```
+
+Search-by-meaning (the `concept`/`seam` retrieval) runs in symgrep's own process over MCP/HTTP, so honestreview
+needs neither an embedding model nor `veccore`/`fastembed` in its own environment — point it at a running
+`symgrep-mcp` (or set `$SYMGREP_MCP_URL`). The `[learn]` extra is only for the optional local doctrine-learning
+embedder.
+
+**Nothing is spent without `--run`.** Every axis prints a cost and a count first. That is not politeness: a
+review that surprises someone with a bill gets run once and then avoided, and a review nobody runs finds
+nothing.
+
+### As an MCP tool
+
+```bash
+claude mcp add honestreview -- /path/to/venv/bin/honestreview-mcp
+```
+
+This matters more than the CLI. A toolkit you have to remember is used when it *occurs* to someone, and what
+occurs to someone under focus is what they always do — which is how the per-file panel got run three times
+while the cross-file axes, where every missed defect actually was, were never reached.
+
+### As a hook
+
+```bash
+honestreview install-hook              # backs up settings.json first, atomically
+```
+
+Ships a family of PreToolUse hooks — authorship hooks that read source at the moment it is written (led by the
+agentic-decision hook, which blocks a mechanical proxy standing in for a judgement) and behavioral hooks that
+judge a Bash action at the moment it runs. **A code hook's matcher includes `Bash` on purpose** — a
+`Write|Edit`-only hook is blind to heredoc-written source, which is how most agent-authored files are created. Measured: a rule against
+regex-decisions sat in three CLAUDE.md files and was violated repeatedly, because every offending file was
+written through a heredoc. Widening the matcher fixed in one edit what instruction had not fixed in fifty.
+
+See `src/honestreview/hooks/agentic_decisions.md` for what it catches, the rule that fixed its false positives,
+and its two known over-fire shapes.
+
+### As doctrine
+
+```bash
+honestreview doctrine >> CLAUDE.md     # the method, without the tooling
+```
+
+## What it refuses to do
+
+- **Call a pattern's silence a clean bill.** Every report states what it CHECKED and what it did NOT, with a
+  denominator. A fixed list of literal spellings reporting "no wrong price found" is a certificate issued by
+  a check that never asked the question.
+- **Resolve a judgement with a cutoff.** A confidence grade, a cosine score and a vote tally are magnitudes
+  a model produced; the cutoff would be ours. Splits go to an adjudicator that reads the code. Unanimity is
+  not a threshold — it is the absence of disagreement.
+- **Decide meaning with a regex.** Regex parses known shapes. It never classifies.
+
+## Depends on
+
+- **[symgrep-codesearch]** (imported as `symgrep`) — symbol extraction and search-by-meaning. Deliberately not
+  vendored: a second AST layer here would be the exact defect this toolkit detects. Pulls `veccore` transitively.
+- **[llm-spendguard]** (imported as `spendguard`) — the gate. Every call is estimated first, caged, recorded and
+  attributable. The distribution is `llm-spendguard`; the unrelated `spendguard` on PyPI is a different project.
+
+## Tests
+
+```bash
+python tests/test_toolkit_holds_itself_to_it.py
+```
+
+A review toolkit that violates its own doctrine is worse than none — it certifies the defect it contains.
+Every assertion in that file is a rule this package states publicly.
+
+## Docs
+
+- **`INTENT.md`** — the North Star: what the toolkit is *for* and the invariants it commits to (the
+  `intent-alignment` axis reads it to judge the repo against its own purpose).
+- **`docs/ARCHITECTURE.md`** — the HOW: the LOCATE→JUDGE→REFUTE→ACCOUNT pipeline, the two delivery surfaces, and
+  the concurrency architecture (`parallel_judge` + the pinned-vendor matrix fans; spendguard owns concurrency).
+- **`docs/SPENDGUARD_INTEGRATION.md`** — the gate contract: matrix fans, `metered_only`, attribution, and how to
+  run a deep wave review.
+- **`docs/EFFICIENCY.md`** — the measured cost/latency levers (one retired because measurement falsified it).
+- **`DOCTRINE_CATALOG.md`** — every doctrine, by domain (regenerate with `honestreview doctrines --out
+  DOCTRINE_CATALOG.md`); **`docs/DOCTRINE_ROADMAP.md`** — the append-only design log; **`docs/VOCABULARY.md`** —
+  what "square" and "cubed" mean.

honestreview-0.2.0/README.md

@@ -0,0 +1,139 @@
+# honestreview
+
+Review a repo at the granularity its defects actually live at — and never overstate what you checked.
+
+## Why
+
+A review can only find defects that **fit inside the unit it looks at**.
+
+Measured on one codebase: three waves of four-vendor per-file review, ~500 findings, and it missed 13
+functions copy-pasted between two files, four writers of one settings file (three destructive — one of them
+later destroyed the file), and a producer/consumer pair reading and writing different tables.
+
+None of that was carelessness. The reviewer was shown **one file at a time**, so a two-file defect was never
+in the room, and no amount of care recovers evidence that is not in the context window. When something is
+missed, the first question is *"was it even in the room?"* — not *"why wasn't it noticed?"*
+
+So "I reviewed the repo" means nothing without the axis:
+
+| axis | unit in context | finds | blind to |
+|---|---|---|---|
+| **file** | one file | swallowed exception, wrong branch, unguarded index | anything whose other half is elsewhere |
+| **concept** | every implementation of one job, in full | DRIFT — copies that now disagree, one of them wrong | a concept correctly duplicated |
+| **seam** | every writer + reader of one resource | CONTRACT GAPS — each side correct, the gap wrong | anything that is nowhere |
+| **invariant** | the whole repo vs one claim it makes | **ABSENCE** — a discipline present in NO file | nothing structural |
+| **name** | all definitions sharing a bare name | COLLISION / DUPLICATION / PROTOCOL | — |
+
+**`invariant` is skipped most and matters most: it is the only axis that can find something MISSING.**
+*"There is no backup before any mutation in this repo"* is true, catastrophic, and appears in zero files.
+
+Plus two that cut across all of them: **`silent`** (swallowed failures) and **`unwired`** (capabilities built
+and never connected — worse than a bug, because the code *looks* protected).
+
+## A finding is not a finding until something tried to kill it
+
+Raw multi-vendor review over-calls badly. Measured: **60 "dangerous" silent failures became 26** once
+independent refuters were told to knock each one down and default to refuted when unsure — and **2** after a
+truncation bug in the refuter itself was fixed.
+
+Three states, kept separate:
+
+- **SURVIVED** — attempts to refute it failed. A finding.
+- **REFUTED** — the claim did not hold. Correctly closed.
+- **UNVERIFIED** — the check did not complete. **Neither of the other two.** Collapsing it is how
+  *"2 survived, 7 unverified"* got reported as *"9 survived"*.
+
+## Use
+
+```bash
+pip install honestreview               # pulls symgrep-codesearch + llm-spendguard + fastmcp from PyPI
+pip install "honestreview[learn]"      # + the local sentence-transformers embedder (optional; pulls torch)
+
+# honestreview runs UNDER the spendguard gate, so no axis can ever spend ungated. Arm it once:
+spendguard install-hook --venv <your-venv>     # then `spendguard doctor` must print: ENFORCING HERE: YES
+
+honestreview all <root>                # every axis, cheapest-first — ESTIMATE ONLY
+honestreview all <root> --run          # actually review
+honestreview invariant <root> --run    # the axis that finds what is missing
+honestreview ledger                    # every pass, every verdict, what is still open
+```
+
+Search-by-meaning (the `concept`/`seam` retrieval) runs in symgrep's own process over MCP/HTTP, so honestreview
+needs neither an embedding model nor `veccore`/`fastembed` in its own environment — point it at a running
+`symgrep-mcp` (or set `$SYMGREP_MCP_URL`). The `[learn]` extra is only for the optional local doctrine-learning
+embedder.
+
+**Nothing is spent without `--run`.** Every axis prints a cost and a count first. That is not politeness: a
+review that surprises someone with a bill gets run once and then avoided, and a review nobody runs finds
+nothing.
+
+### As an MCP tool
+
+```bash
+claude mcp add honestreview -- /path/to/venv/bin/honestreview-mcp
+```
+
+This matters more than the CLI. A toolkit you have to remember is used when it *occurs* to someone, and what
+occurs to someone under focus is what they always do — which is how the per-file panel got run three times
+while the cross-file axes, where every missed defect actually was, were never reached.
+
+### As a hook
+
+```bash
+honestreview install-hook              # backs up settings.json first, atomically
+```
+
+Ships a family of PreToolUse hooks — authorship hooks that read source at the moment it is written (led by the
+agentic-decision hook, which blocks a mechanical proxy standing in for a judgement) and behavioral hooks that
+judge a Bash action at the moment it runs. **A code hook's matcher includes `Bash` on purpose** — a
+`Write|Edit`-only hook is blind to heredoc-written source, which is how most agent-authored files are created. Measured: a rule against
+regex-decisions sat in three CLAUDE.md files and was violated repeatedly, because every offending file was
+written through a heredoc. Widening the matcher fixed in one edit what instruction had not fixed in fifty.
+
+See `src/honestreview/hooks/agentic_decisions.md` for what it catches, the rule that fixed its false positives,
+and its two known over-fire shapes.
+
+### As doctrine
+
+```bash
+honestreview doctrine >> CLAUDE.md     # the method, without the tooling
+```
+
+## What it refuses to do
+
+- **Call a pattern's silence a clean bill.** Every report states what it CHECKED and what it did NOT, with a
+  denominator. A fixed list of literal spellings reporting "no wrong price found" is a certificate issued by
+  a check that never asked the question.
+- **Resolve a judgement with a cutoff.** A confidence grade, a cosine score and a vote tally are magnitudes
+  a model produced; the cutoff would be ours. Splits go to an adjudicator that reads the code. Unanimity is
+  not a threshold — it is the absence of disagreement.
+- **Decide meaning with a regex.** Regex parses known shapes. It never classifies.
+
+## Depends on
+
+- **[symgrep-codesearch]** (imported as `symgrep`) — symbol extraction and search-by-meaning. Deliberately not
+  vendored: a second AST layer here would be the exact defect this toolkit detects. Pulls `veccore` transitively.
+- **[llm-spendguard]** (imported as `spendguard`) — the gate. Every call is estimated first, caged, recorded and
+  attributable. The distribution is `llm-spendguard`; the unrelated `spendguard` on PyPI is a different project.
+
+## Tests
+
+```bash
+python tests/test_toolkit_holds_itself_to_it.py
+```
+
+A review toolkit that violates its own doctrine is worse than none — it certifies the defect it contains.
+Every assertion in that file is a rule this package states publicly.
+
+## Docs
+
+- **`INTENT.md`** — the North Star: what the toolkit is *for* and the invariants it commits to (the
+  `intent-alignment` axis reads it to judge the repo against its own purpose).
+- **`docs/ARCHITECTURE.md`** — the HOW: the LOCATE→JUDGE→REFUTE→ACCOUNT pipeline, the two delivery surfaces, and
+  the concurrency architecture (`parallel_judge` + the pinned-vendor matrix fans; spendguard owns concurrency).
+- **`docs/SPENDGUARD_INTEGRATION.md`** — the gate contract: matrix fans, `metered_only`, attribution, and how to
+  run a deep wave review.
+- **`docs/EFFICIENCY.md`** — the measured cost/latency levers (one retired because measurement falsified it).
+- **`DOCTRINE_CATALOG.md`** — every doctrine, by domain (regenerate with `honestreview doctrines --out
+  DOCTRINE_CATALOG.md`); **`docs/DOCTRINE_ROADMAP.md`** — the append-only design log; **`docs/VOCABULARY.md`** —
+  what "square" and "cubed" mean.

honestreview-0.2.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["setuptools>=77"]                 # >=77: PEP 639 SPDX license expression + license-files
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "honestreview"
+dynamic = ["version"]                          # SOURCE OF TRUTH: honestreview.__version__ (never a second copy here)
+description = "Review a repo at the granularity its defects actually live at — and never overstate what you checked"
+readme = "README.md"
+requires-python = ">=3.11"                      # symgrep-codesearch (a hard dep) requires >=3.11; Python 3.9/3.10 EOL-track
+license = "MIT"                                 # PEP 639 SPDX expression (no trove License:: classifier alongside it)
+license-files = ["LICENSE"]
+authors = [{ name = "Ash Damle" }]
+keywords = ["code-review", "static-analysis", "llm", "doctrine", "pre-commit", "hooks"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+]
+
+# HARD DEPENDENCIES — none vendored.
+#   symgrep-codesearch — symbol extraction and search (import name `symgrep`). A second AST layer here would be the
+#                        exact defect this toolkit detects; it pulls veccore transitively (do NOT declare veccore).
+#   llm-spendguard     — the spend gate (import name `spendguard`). Every axis calls models; going through the gate
+#                        means estimate-first, caged, recorded, attributable. Declared WITH the [openai,anthropic]
+#                        extras on purpose: the gate enforces by PATCHING a provider SDK, and axis modules call
+#                        spendguard.require() at IMPORT (fail-closed — it raises if no SDK is patched), so at least one
+#                        SDK must be present at RUNTIME, not just in dev; the panel also makes metered calls to both
+#                        vendors. Bare `llm-spendguard` pulls no SDK (its deps are empty), which would raise at import.
+#                        NOTE: the distribution is `llm-spendguard`, NOT the unrelated `spendguard` PyPI package.
+#   fastmcp            — the MCP server surface (honestreview-mcp). A stdlib JSON-RPC fallback exists, but fastmcp is
+#                        the supported path, so it is a hard dep.
+#   numpy              — vector math for the semantic index (concept/near-dup axes).
+dependencies = [
+    "symgrep-codesearch>=0.6,<1",
+    "llm-spendguard[openai,anthropic]>=0.11,<1",
+    "fastmcp>=2,<5",
+    "numpy>=1.24,<3",
+]
+
+[project.optional-dependencies]
+# learn: the LOCAL sentence-transformers embedder (learn/embed.py). Opt-in because it pulls torch (~2 GB); the
+# primary semantic path is symgrep-over-MCP + gated API embeddings, which need neither torch nor this extra.
+learn = ["sentence-transformers>=3,<7"]
+# dev/test: the RUNTIME deps already pull the provider SDKs (llm-spendguard[openai,anthropic]) that the armed gate
+# patches and that the axis modules' import-time spendguard.require() needs — so dev only adds the test runner.
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/ashdamle/honestreview"
+Repository = "https://github.com/ashdamle/honestreview"
+Issues = "https://github.com/ashdamle/honestreview/issues"
+
+[project.scripts]
+honestreview = "honestreview.cli:main"
+honestreview-mcp = "honestreview.mcp_server:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "honestreview.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+# Runtime data files read from the installed package (never .py): the doctrine texts, the coding-family rule files
+# (coding_router reads families/<family>.md), and the shipped hook definitions (dispatch globs hooks/*.json).
+honestreview = ["doctrine/*.md", "families/*.md", "hooks/*.json", "hooks/*.md", "hooks/drafts/*.json"]

honestreview-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

honestreview-0.2.0/src/honestreview/__init__.py

@@ -0,0 +1,85 @@
+"""honestreview — review a repo at the granularity its defects actually live at, and never overstate what
+you checked.
+
+THE TWO IDEAS, both learned by getting them wrong.
+
+1. THE UNIT OF REVIEW MUST MATCH THE UNIT OF THE DEFECT.
+   Three waves of a four-vendor review over one codebase produced ~500 findings and missed 13 functions
+   copy-pasted between two files, four writers of the same settings file (three of them destructive), and a
+   producer/consumer pair writing and reading different tables. Not carelessness — the reviewer was shown
+   ONE FILE at a time, so a two-file defect was never in the room. No amount of care recovers evidence that
+   is not in the context window. Change the unit instead:
+
+     FILE       one file                          local defects: a swallowed exception, a wrong branch
+     CONCEPT    every implementation of one job   DRIFT — copies that disagree, one of them now wrong
+     SEAM       every writer + reader of one      CONTRACT GAPS — each side correct, the gap wrong
+                resource
+     INVARIANT  the repo vs one claim it makes    ABSENCE — a discipline present in NO file
+     NAME       all definitions sharing a name    COLLISION vs DUPLICATION vs PROTOCOL
+
+   INVARIANT is the one that gets skipped and matters most: it is the only axis that can find something
+   MISSING. "There is no backup before any mutation in this repo" is true, catastrophic, and appears in
+   zero files, so the other axes can look forever and never see it.
+
+2. A FINDING IS NOT A FINDING UNTIL SOMETHING TRIED TO KILL IT.
+   Raw multi-vendor review over-calls badly — measured: 60 "dangerous" silent failures became 26 after
+   independent refuters were told to knock each one down, and 2 after the truncation bug in the refuter was
+   fixed. So every axis feeds validation, and the states stay separate: SURVIVED, REFUTED, and UNVERIFIED,
+   where UNVERIFIED means the check did not complete and is neither of the other two. Collapsing it is how
+   "2 survived, 7 unverified" got reported as "9 survived".
+
+WHAT THIS REFUSES TO DO
+  · call a mechanical pattern's silence a clean bill — every report states what it checked and what it
+    did not, with a denominator
+  · resolve a judgement with a hand-picked cutoff — a confidence grade, a cosine score, a vote tally are
+    all magnitudes a model produced; the CUTOFF would be ours, and that is the bound this rule exists to
+    stop. Splits go to an adjudicator that reads the code.
+  · decide meaning with a regex. Regex parses known shapes; it never classifies.
+
+Depends on symgrep for symbol extraction (deliberately not vendored — a second AST layer is the exact
+defect this toolkit detects) and on llm-spendguard for the gate, so every call is estimated first, caged,
+and recorded.
+"""
+
+__version__ = "0.2.0"
+
+AXES = ("file", "concept", "seam", "invariant", "name",
+        # DURABILITY cluster (doctrine/DURABILITY.md): make loss loud — nothing irreplaceable (progress, data,
+        # a finding) may vanish without a warning, a count, a backup, and a named gap.
+        "chunking", "durability", "mutable-proxy",
+        # RAW PROVENANCE (doctrine/RAW_PROVENANCE.md): raw source is backed up to a durable store ON ARRIVAL,
+        # with a manifest, before any extraction or teardown — never raw-only on ephemeral disk.
+        "raw-provenance",
+        # DECOUPLING cluster: a cross-boundary contract must have a single named home. literal-contract finds
+        # the WRITE-side inline literal that lets producer and consumer drift silently (complements seam).
+        "literal-contract",
+        # SOURCE-OF-TRUTH: one fact has one writer. source-of-truth finds a field assigned by 2+ functions —
+        # competing writers that can silently disagree (the upstream cause of a value no reader can trust).
+        "source-of-truth",
+        # PORTS-ADAPTERS: the domain depends on ports, not concrete infra. ports-adapters finds domain logic
+        # that imports an ORM/HTTP-client/driver/SDK directly. Repo-agnostic (import-based, not path-based).
+        "ports-adapters",
+        # INTERFACE INFORMATIVENESS / No-silent-failure: state-collapse finds a function returning the same
+        # falsy sentinel from an error path AND a non-error path, so a caller cannot tell error from absence.
+        "state-collapse",
+        # CALIBRATION-GATE (doctrine/CALIBRATION_GATE.md): a raw model score (cosine/logit/posterior) consumed
+        # AS a probability — softmax(sim) read as P, a marginalization weighted by an un-calibrated score —
+        # with no fitted temperature/Platt/isotonic and no reported ECE. Soft evidence needs calibrated weights.
+        "calibration-gate",
+        # INTENT-ALIGNMENT (doctrine/INTENT_ALIGNMENT.md): the META axis — derive THIS repo's own invariants from
+        # its intent docs (README/ARCHITECTURE/DOCTRINE/CLAUDE.md) and judge the repo against them. Enforces the
+        # repo's stated purpose, not just generic taste. On-demand; two agentic stages (extract, judge).
+        "intent-alignment",
+        # DATA-REVIEW (doctrine/MODEL_PARSIMONY.md): the whole-MODEL panel — aggregate every data-model type across
+        # the repo's source and judge the model as a whole (parsimony: which types do not earn their place against
+        # the rest; contract: loose-typed boundary fields). The cross-file half the per-file data hooks are blind to.
+        "data-review")
+
+# The BASE review dimensions — the review ENGINE's mechanics (a file, a seam between two files, a named
+# invariant). These are documented by their module docstrings and the tool description, and are NOT adoptable as a
+# standalone doctrine/<NAME>.md. EVERY OTHER axis IS a named doctrine and MUST carry a doctrine md that declares
+# `enforced_by: axis:<name>` — the ADR<->migration invariant in tests/test_toolkit_holds_itself_to_it.py enforces
+# exactly this partition, so an axis cannot be added without either a doctrine md or a deliberate, reviewed entry
+# here. (`name` is NOT foundational — it is the NAMING doctrine's axis; `concept` is NOT foundational — it is
+# CANONICAL_IMPLEMENTATION's review-time axis, the capability-duplication detector.)
+FOUNDATIONAL_AXES = ("file", "seam", "invariant")