docs: an agent-tuned ADR policy, a lean template and every ADR converted

.quality-baseline.json

@@ -15,7 +15,7 @@
       "verb": "make typecheck"
     },
     "markdownlint": {
-      "count": 680,
+      "count": 647,
       "what": "markdownlint-cli2 issues over every tracked Markdown file (the DOCS_LINT_PATHS ratchet is a subset and clean)",
       "command": "git ls-files -z '*.md' | xargs -0 npx markdownlint-cli2@<pin>",
       "verb": "make docs-lint"

AGENTS.md

@@ -113,7 +113,9 @@ reports, commit messages, pull request descriptions and docs.
 | `artefacts/` | Scratch notes and plans. The folder is tracked, its contents are git-ignored. | Off-limits. Do not read, search or list it unless a human gives you a file path. |
 
 Decisions (ADRs) live beside the component they govern (root ADR 0001). The root index,
-`docs/architecture/adrs/README.md`, lists all of them.
+`docs/architecture/adrs/README.md`, lists all of them. **Every ADR you add, change or delete follows
+`docs/ADR_POLICY.md`.** Git is the archive, so an ADR states only the current decision. Overwrite a changed
+decision in place. Delete a superseded one, and never refer to it again.
 
 A folder with no files yet is not written yet; the docs page that describes it says `Planned`.
 
@@ -147,6 +149,7 @@ A change is done when all of this holds:
 - A change can alter a public interface, observable behaviour, the architecture or a decision. Then update the
   affected documentation and the decision records in the same change set. When you fill in a page marked `Planned`,
   remove that note and update the doc router.
+- An ADR you added or changed follows `docs/ADR_POLICY.md` and has its row in the ADR index.
 - Python files carry the SPDX header `AGPL-3.0-or-later` and the copyright line. Documentation, schemas and published
   outputs are `GFDL-1.3-only`. The zones are in `docs/reference/licensing.md`.
 - Commits follow Conventional Commits, one logical change each, so any one can be reverted alone.
@@ -160,7 +163,7 @@ A change is done when all of this holds:
   `docs/how-to/contribute-a-change.md`.
 - How to write for people: `docs/COMMUNICATION_RULES.md`.
 - Documentation index, style guide and decisions of record: `docs/README.md`, `docs/STYLE_GUIDE.md`,
-  `docs/architecture/adrs/README.md`.
+  `docs/architecture/adrs/README.md`. The ADR rules: `docs/ADR_POLICY.md`.
 - Requirements: `spec/README.md`, and `spec/readiness-requirements.md`.
 - What an audit checks and what an implement run changes, for a reader: `docs/reference/audit-master.md` and
   `docs/reference/implement-master.md`.

CONTRIBUTING.md

@@ -85,7 +85,7 @@
 
 ## Local hooks
 
 [`lefthook.yml`](lefthook.yml) stops a commit on `dev` or `main`. It also runs the format check on staged Python,
 `make docs-lint` on staged Markdown, `make workflow-lint` on staged `.github/` files, the spell check on staged
 files, a secrets scan and the Conventional Commits check (`dev/commit_lint.py`) before a commit lands. Install it
 once per clone with `lefthook install` ([lefthook.dev](https://lefthook.dev)). Hooks do not replace the gate.
@@ -112,7 +112,7 @@
 - One logical change per commit, so any one can be reverted alone.
 - Work that follows a build roadmap or track carries a `Roadmap-Step: <step id>` trailer (for example `S4.6`,
   `IR07.3` or `MR02`).
 - The pull request template lists what a reviewer expects: gates green, tests for new code (a new engine check has a
   fixture that fails exactly that check), and the documentation and decision records updated in the same change.
 
 ## Licence zones
@@ -126,7 +126,7 @@
 Write in plain language ([`docs/COMMUNICATION_RULES.md`](docs/COMMUNICATION_RULES.md)). Follow
 [`docs/STYLE_GUIDE.md`](docs/STYLE_GUIDE.md). Start at the documentation index,
 [`docs/README.md`](docs/README.md). A page describes what exists; a feature that is only planned is marked
-`Planned`. Decisions go in an ADR ([index](docs/architecture/adrs/README.md)).
+`Planned`. Decisions go in an ADR ([index](docs/architecture/adrs/README.md), [policy](docs/ADR_POLICY.md)).
 
 ## Reporting an engine defect
 

Makefile

@@ -69,7 +69,7 @@ COVERAGE_DATA := $(CURDIR)/dev/dist/coverage/.coverage
 # The Markdown that `docs-lint` holds to zero violations. A ratchet: a path joins once it is clean, and the list
 # only grows. Everything else is reported by `docs-lint-all` and never fails.
 DOCS_LINT_PATHS := 'implement/SKILL.md' 'implement/state.md' 'implement/playbooks/*.md' 'implement/prompts/*.md' \
-	'docs/README.md' 'docs/STYLE_GUIDE.md' 'docs/architecture/**/*.md' 'docs/reference/branch-protection.md' 'docs/reference/dev-tooling.md' 'docs/reference/audit-master.md' 'docs/reference/implement-master.md' 'docs/how-to/contribute-a-change.md' 'docs/how-to/set-up-agent-tools.md' 'docs/COMMUNICATION_RULES.md' 'CONTRIBUTING.md' 'CHANGELOG.md' 'RELEASE_PROCESS.md' 'SECURITY.md' \
+	'docs/README.md' 'docs/STYLE_GUIDE.md' 'docs/architecture/**/*.md' 'docs/reference/branch-protection.md' 'docs/reference/dev-tooling.md' 'docs/reference/audit-master.md' 'docs/reference/implement-master.md' 'docs/how-to/contribute-a-change.md' 'docs/how-to/set-up-agent-tools.md' 'docs/COMMUNICATION_RULES.md' 'docs/ADR_POLICY.md' 'docs/templates/adr-template.md' 'CONTRIBUTING.md' 'CHANGELOG.md' 'RELEASE_PROCESS.md' 'SECURITY.md' \
 	'docs/explanation/user-overview/03-trust-and-safety.md' 'docs/explanation/contributor-deep-dive/04-stack-profiles.md' 'docs/explanation/contributor-deep-dive/05-evaluation.md' 'docs/how-to/add-a-stack-profile.md' 'docs/reference/harness-notes.md' \
 	'audit/engine/docs/how-to/read-the-report.md' 'docs/reference/versions.md' 'docs/how-to/implement-an-audit-report.md' \
 	'docs/how-to/resume-an-interrupted-run.md' 'docs/glossary.md' 'AGENTS.md' 'audit/prompts/talking-to-the-user.md' \

audit/AGENTS.md

@@ -43,6 +43,7 @@ To audit a repository, follow [`SKILL.md`](SKILL.md). The rest of this file is f
 - The tool design: the
   [Tool Contract](../docs/explanation/contributor-deep-dive/01-tool-contract.md) page.
 - All decisions: the root index, [`docs/architecture/adrs/README.md`](../docs/architecture/adrs/README.md).
+- How to add, change or delete an ADR: [`docs/ADR_POLICY.md`](../docs/ADR_POLICY.md).
 
 ## Test this folder
 

audit/docs/architecture/adrs/0001-tools-import-engine.md

@@ -1,44 +1,33 @@
 # 0001. Tools Import the Engine in Process
 
-* **Status:** Accepted
-* **Date:** 2026-10-10
-* **Last reviewed:** 2026-11-07
-* **Deciders:** [@nistapp]
-
-> **Paths updated (v0.3, 2026-11-07):** the decision stands. The text keeps the paths of its date:
-> `brownfield-recipes/tools/` is now `audit/tools/`, and `deterministic-audit/` is now `audit/engine/`.
-> The "Moved" table in the root [`CHANGELOG.md`](../../../../CHANGELOG.md) maps every old path.
-
----
-
 ## Context
 
-The recipes' tools and the deterministic engine are both standard-library Python, and the tools need the engine in two ways. `tools/engine.py` must run it from any working directory with one command. Later tools need pieces of it rather than a whole run: the validator wants the engine's secret-redaction patterns (S2.2), and the facts tool wants its file inventory (S2.7).
+The recipes' tools and the deterministic engine are both standard-library Python, and the tools need the engine in two ways. `tools/engine.py` must run it from any working directory with one command. Other tools need pieces of it rather than a whole run: the validator wants the engine's secret-redaction patterns, and the facts tool wants its file inventory.
 
 Four constraints bind the choice:
 
 - One copy of each module. A second copy of the engine's code would drift from the first.
-- No install step. A fresh clone must run `python3 brownfield-recipes/tools/<tool>.py` at once, because an audit starts on a machine where nothing is set up.
+- No install step. A fresh clone must run `python3 audit/tools/<tool>.py` at once, because an audit starts on a machine where nothing is set up.
 - The engine's behaviour and tests do not change for the sake of the tools.
 - Standard library only, in both.
 
-The engine is a package named `audit` in [`deterministic-audit/`](../../../engine/audit/__init__.py). Its entry point, [`main(argv)`](../../../engine/audit/__main__.py), takes the arguments explicitly and returns the exit code, which [ADR-0005 of the engine](../../../engine/docs/architecture/adrs/0005-module-layout-and-zipapp-distribution.md) keeps stable.
+The engine is a package named `audit` in [`audit/engine/`](../../../engine/audit/__init__.py). Its entry point, [`main(argv)`](../../../engine/audit/__main__.py), takes the arguments explicitly and returns the exit code, which [ADR-0005 of the engine](../../../engine/docs/architecture/adrs/0005-module-layout-and-zipapp-distribution.md) keeps stable.
 
 ## Decision
 
-A tool imports the engine in process. [`load_engine`](../../../tools/engine.py#L57-L66) puts `deterministic-audit/` on `sys.path`, resolved from the location of `engine.py`, and imports `audit.__main__`. It then refuses to go on if the `audit` package it got did not come from that folder, so a different package called `audit` that happens to be installed cannot be run in its place.
+A tool imports the engine in process. [`load_engine`](../../../tools/engine.py#L57-L66) puts `audit/engine/` on `sys.path`, resolved from the location of `engine.py`, and imports `audit.__main__`. It then refuses to go on if the `audit` package it got did not come from that folder, so a different package called `audit` that happens to be installed cannot be run in its place.
 
 - [`tools/engine.py`](../../../tools/engine.py) calls the engine's `main(argv)` through [`run_engine`](../../../tools/engine.py#L69-L83), with its stdout and stderr captured, so the launcher's own stdout stays a single envelope.
 - A tool that needs engine internals calls `engine.load_engine()` first and imports from `audit` after it, so that the path and the guard are always the same.
 - The engine never imports from `tools/`. The dependency runs one way.
 - `tools/_common.py` does not import the engine. A tool that needs only the contract does not pay for the engine.
 
 ## Alternatives Considered
 
-| Alternative | Why it was rejected |
+| Alternative | Why it is rejected |
 |---|---|
 | Run the engine as a subprocess (`python3 -m audit`) | It isolates the engine's module-level state and gives clean exit codes. But it cannot hand over internals, so the validator and the facts tool would need a second mechanism beside it. Two mechanisms for one engine is worse than one. |
-| A shared `common/` package that both depend on (the design plan's fallback) | Nothing needs it: the import works, and a shared package would move engine code that has no reason to move. |
+| A shared `common/` package that both depend on | Nothing needs it: the import works, and a shared package would move engine code that has no reason to move. |
 | Install the engine, or run the `dist/audit.pyz` build | Both add a step before the first audit. The zipapp also needs a build and goes stale against the source. |
 | Copy the engine's modules into `tools/` | Two copies drift. |
 

audit/engine/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
 > **Adapted from:** the greenfield (`greenfield/`) `AGENTS.md` template v1.1.0, retargeted from npm/TypeScript
 > to this stdlib-only Python project.
 > **Purpose:** This file governs how AI coding agents (Antigravity, Claude Code, Gemini CLI, opencode, etc.)
 > work inside this repository.
@@ -11,7 +11,7 @@
 
 ## 1. Project Overview
 
 `python-agentic-audit` is a **read-only agentic-readiness scanner for existing repositories**. It is the
 brownfield half of the agentic-readiness toolchain: `python-agentic-bootstrap` proves a new project *starts*
 ready; this audit measures how far an existing repository is from the same bar and reports an ordered backlog.
 It is also the deterministic engine of the brownfield recipes in `audit/` and `implement/` ([README](../README.md)).
@@ -74,7 +74,7 @@
    verb is named in `--allow-probe`. There is no default probe.
 3. **No third-party dependency.** `audit/` and `build.py` import from the standard library only. A data file
    cannot ship inside a `.pyz` via `Path(__file__)` — that is why `variants.py` is code, and it stays code.
 4. **The framework is normative.** Where this tool's docs and
    the framework (the root of this repository, [README](../../README.md)) disagree, **the framework wins and this tool has a defect**.
    Resolve it here, never by weakening the tool.
 5. **Findings carry evidence.** No verdict without the evidence that produced it. `UNKNOWN` is used when
@@ -156,7 +156,7 @@
   annotations`. No untyped pass-through.
 - **No third-party imports** anywhere in `audit/` or `build.py`. If a capability needs a library, it does not
   ship in v1.
 - **Determinism is a requirement, not a nicety:** sort traversal and check evaluation; never use wall-clock
   time inside a verdict; derive finding ids from `check id + path`, never from a counter.
 - **Scope-contract docstrings:** modules that define a pipeline stage state their responsibility and failure
   behaviour in the module docstring, matching `docs/architecture/contributor-deep-dive/01-scan-engine-and-tiering.md`.
@@ -171,13 +171,13 @@
 ## 6. Testing Standards
 
 - **Framework:** stdlib `unittest` (import from `unittest`, not `pytest`).
 - **Location:** a check pack's tests go in its package, `tests/packs/<pack>/` (`agt`, `cmd`, `exec`, `tool`, ...);
   cross-pack and pipeline tests (the fixture matrix, scan, report, CLI) and the `support` helpers stay in `tests/`;
   fixtures under `tests/fixtures/`. A test module name is unique across the suite (CI's shards find a module by
   name). Keep each folder at 50 files or fewer: the self-audit's `NAV-03` reads a larger one as a catch-all.
 - **Fixtures:** one directory per check id, each a minimal repository that fails **exactly one** check.
   The catalogue's § Adding a Check makes this a merge requirement: **no fixture, no check.**
 - **Positive fixture:** a freshly generated `python-agentic-bootstrap` scaffold, **generated in the test run,
   never vendored**. If a scaffold ever fails this audit, one of the two tools is wrong — that is a defect to
   fix, not a false positive to tune away. Its scaffolder lives in a sibling repository, so the test fails
   loudly without it, except when `CI=true`, where it skips and says why.
@@ -216,10 +216,9 @@
 - **Doc router:** `docs/architecture/README.md` is the entry point and the ADR index.
 - **Categories (Diátaxis):** tutorial, how-to, reference, explanation; architecture material lives under
   `docs/architecture/`.
-- **ADRs:** `docs/architecture/adrs/NNNN-short-title.md`, created from
-  [`../docs/templates/adr-template.md`](../../docs/templates/adr-template.md), indexed in `docs/architecture/README.md`. Revise in place — there is no
-  `Superseded` or `Deprecated` status, no tombstones, and a retired sequence number is never reused.
+- **ADRs:** `docs/architecture/adrs/NNNN-short-title.md`, indexed in `docs/architecture/README.md`. Read
+  [`../docs/ADR_POLICY.md`](../../docs/ADR_POLICY.md) before you add, change or delete one.
 - **Definition of done:** when a change alters a public interface, observable behaviour, architecture, a
   check's semantics, or an ADR, update the affected documentation pages, their source line anchors, and the
   ADR index **in the same change set**. Pure internal refactors with no documentation impact are exempt.
 - **No restating the framework:** the framework at the root of this repository ([README](../../README.md)) is
@@ -255,7 +254,7 @@
 9. ❌ **Do not** restate the shared style guide (`../docs/STYLE_GUIDE.md`) or the readiness framework — link to them.
 10. ❌ **Do not** document a check as implemented while it is only in the catalogue.
 11. ❌ **Do not** merge a check without its one-defect fixture (no fixture, no check).
-12. ❌ **Do not** reuse a retired ADR number, or leave a `Superseded` / `Deprecated` tombstone.
+12. ❌ **Do not** add, change or delete an ADR without following [`../docs/ADR_POLICY.md`](../../docs/ADR_POLICY.md).
 13. ❌ **Do not** weaken, `.skip`, or comment out a failing test to get green (the CI skip in §6 is the one exception).
 14. ❌ **Do not** push, `git init`, or commit unless KC asks or your session's instructions say to commit.
 15. ❌ **Do not** verify work with an ad-hoc command; use the sanctioned surface in §3.1.

audit/engine/docs/architecture/README.md

@@ -12,17 +12,17 @@
 
 ## ADR Index
 
-| # | Title | Status | Date |
-|---|---|---|---|
-| [0001](adrs/0001-report-not-a-gate.md) | The Audit Reports; It Does Not Gate | Accepted | 2026-09-28 |
-| [0002](adrs/0002-read-only-and-tier-c-opt-in.md) | Read-Only by Default; Tier-C Probes Are Opt-In | Accepted | 2026-09-28 |
-| [0003](adrs/0003-component-depth-declared-depth-1.md) | Component Depth: Declared Components, Depth 1 | Accepted | 2026-09-28 |
-| [0004](adrs/0004-no-llm-in-v1.md) | No LLM Calls in v1 | Accepted | 2026-09-28 |
-| [0005](adrs/0005-module-layout-and-zipapp-distribution.md) | Module Layout and Zipapp Distribution | Accepted | 2026-09-28 |
-| [0006](adrs/0006-private-check-helpers-and-ignore-engine.md) | Private Check Helpers and the Ignore Engine | Accepted | 2026-09-28 |
-| [0007](adrs/0007-json-report-render-contract.md) | The JSON Report Is the Render Contract; the Markdown Is a Template Over It | Accepted | 2026-09-30 |
-| [0008](adrs/0008-what-counts-as-the-repository.md) | What Counts as the Repository | Accepted | 2026-11-05 |
-| [0009](adrs/0009-nested-ignore-files-and-negation.md) | Nested Ignore Files and Negation | Accepted | 2026-11-05 |
+| # | Title | Summary |
+|---|---|---|
+| [0001](adrs/0001-report-not-a-gate.md) | The Audit Reports; It Does Not Gate | A completed scan exits 0 whatever it finds; `--fail-on` exists but is off by default. |
+| [0002](adrs/0002-read-only-and-tier-c-opt-in.md) | Read-Only by Default; Tier-C Probes Are Opt-In | The engine never writes to or installs into the target; Tier-C probes run only on explicit request. |
+| [0003](adrs/0003-component-depth-declared-depth-1.md) | Component Depth: Declared Components, Depth 1 | Only components a build manifest declares are scored, and only at depth 1. |
+| [0004](adrs/0004-no-llm-in-v1.md) | No LLM Calls in v1 | The engine is deterministic and standard-library only, with no model calls. |
+| [0005](adrs/0005-module-layout-and-zipapp-distribution.md) | Module Layout and Zipapp Distribution | The package tree is the source; a zipapp is the distributable; nothing needs installing. |
+| [0006](adrs/0006-private-check-helpers-and-ignore-engine.md) | Private Check Helpers and the Ignore Engine | Checks share two private helpers, `audit/ignore.py` and `rules/checks/_common.py`; no new stage or pack. |
+| [0007](adrs/0007-json-report-render-contract.md) | The JSON Report Is the Render Contract; the Markdown Is a Template Over It | The JSON report (schema v2) is the contract; the Markdown report is a code template over it. |
+| [0008](adrs/0008-what-counts-as-the-repository.md) | What Counts as the Repository | Runners rank depth first; templates, examples and fixtures are set aside, and the report lists them. |
+| [0009](adrs/0009-nested-ignore-files-and-negation.md) | Nested Ignore Files and Negation | Four checks use a scoped matcher that honours nested `.gitignore` files and negation; the walk is unchanged. |
 
 ## Key Documents
 
@@ -61,7 +61,8 @@
 | [Wire the ratchet into CI](../how-to/wire-the-ratchet-into-ci.md) | Fail only on regression, never on the first scan | Published (design) |
 
 > [!TIP]
-> When adding a new ADR, assign the next sequence number and add a row to the index table above before merging.
+> Before you add, change or delete an ADR, read [`ADR_POLICY.md`](../../../../docs/ADR_POLICY.md). Add its row to this
+> table and to the root index in the same change.
 
 ## Framework Dependencies
 

audit/engine/docs/architecture/adrs/0001-report-not-a-gate.md

@@ -1,12 +1,5 @@
 # 0001. The Audit Reports; It Does Not Gate
 
-* **Status:** Accepted
-* **Date:** 2026-09-28
-* **Last reviewed:** 2026-09-28
-* **Deciders:** [@nistapp]
-
----
-
 ## Context
 
 The tool exists to tell a team what to improve so that AI coding agents can work effectively in an existing
@@ -24,8 +17,6 @@
 unverifiable properties into one pass/fail number would manufacture exactly the false confidence the framework
 warns about.
 
----
-
 ## Decision
 
 The audit **reports and never gates**:
@@ -33,12 +24,12 @@
 1. A completed scan exits `0` regardless of what it found.
 2. `--fail-on <severity>` exists but is unset by default, and is documented as the wrong default for brownfield
    adoption.
 3. Regression detection is a **ratchet**: `--baseline <report.json>` exits `2` only when a finding is present
    that was absent from an accepted baseline. A repository that was never ready is not failing anything; a
    repository that stopped being ready is.
 4. **Phase and severity are separate axes.** Phase is provenance (which framework requirement); severity is the
    work queue (blocker / degrader / cosmetic).
 5. Every report prints an **unattested list** and never counts `UNKNOWN` as a pass, so the score cannot be read
    as a guarantee.
 6. Nothing outside Phase 1 enters the score. Phases 2–4 signals and repository hygiene are reported and left
    numberless.
@@ -46,20 +37,16 @@
 Implemented by the exit-code and scoring stages in `audit/evaluate.py` (`AuditResult.exit_code`); see
 [The Readiness Model](../user-overview/02-the-readiness-model.md) § 8.
 
----
-
 ## Alternatives Considered
 
-| Alternative | Why it was rejected |
+| Alternative | Why it is rejected |
 |---|---|
 | Fail the build on any Phase-1 gap (a true gate) | Unfixable in one change set; the predictable outcome is a disabled check, which is worse than no check. |
 | No exit-code signalling at all — report only, always `0` | Removes the ratchet, and with it the only reason to re-run the audit after the first engagement. Debt would regress invisibly. |
 | Fail on a score threshold (e.g. "below 80% fails") | A weighted score hides *which* property regressed. A diff of findings says what changed; a threshold says only that something did. |
 | A pull-request comment bot only, no machine-readable output | Same report, but it withholds the JSON that the remediation pass consumes and makes regression diffing impossible. |
 | Count `UNKNOWN` as a pass so the score stays clean | Converts missing evidence into apparent quality — the precise defect the framework calls false confidence (R8). |
 
----
-
 ## Consequences
 
 ### Positive
@@ -76,13 +63,3 @@
   will ask for the gate anyway, and the correct answer is the repository's own `check` verb, not this tool.
 * Severity is a judgement encoded in the rule packs; a mis-severity finding is a defect that only human review
   catches.
-
----
-
-## Lifecycle — Living, Current-State ADRs
-
-* **This ADR MUST describe only the shipped, current design.** There is no `Deprecated`, `Superseded`, or `Rejected` status.
-* **Decision changed?** Overwrite the body, keep the file and its number, and fold the reversal into *Alternatives Considered*.
-* **Decision no longer relevant?** Delete the file, retire its number forever, and update every inbound reference plus the index table in `docs/architecture/README.md` in the same change set.
-
-See the [style guide](../../../../../docs/STYLE_GUIDE.md) § ADR Lifecycle for the canonical rules.