chore(release): promote dev to main

.coveragerc

@@ -5,6 +5,7 @@ include =
     */audit/engine/audit/*
     */audit/tools/*
     */implement/tools/*
+    */implement/playbooks/templates/*
 omit =
     */tests/*
 

.github/workflows/ci.yml

@@ -36,7 +36,7 @@ jobs:
   # suite of `test` has no job here. The steps that are cheap share one job, because each job pays about 15 s of
   # setup. Python 3.11 runs every step; Python 3.14 runs the runtime code: the suites and the schema cross-check.
   static:
-    name: static (format, typecheck, rules, recipe lint, masters, workflow lint, spell)
+    name: static (format, typecheck, rules, recipe lint, ADR lint, masters, workflow lint, spell)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -53,7 +53,7 @@ jobs:
         with:
           go-version-file: dev/tools/actionlint/go.mod
           cache-dependency-path: dev/tools/actionlint/go.sum
-      - run: make format-check typecheck verify-rules recipe-lint masters-check workflow-lint spell
+      - run: make format-check typecheck verify-rules recipe-lint adr-lint masters-check eval-expected-check workflow-lint spell
 
   crosscheck:
     name: crosscheck (Python ${{ matrix.python }})
@@ -126,9 +126,10 @@ jobs:
           version-file: dev/tools/pyproject.toml
       - run: make test-dev
 
-  # Every suite on the newest Python, in parts with one shard of each sharded suite (`make test-part`;
-  # TEST_PART_<i> in the Makefile). Each part runs its targets at once, as `make test` runs its suites, so this job also proves the
-  # parallel run on every pull request. The nightly workflow runs the unsharded `make test`.
+  # Every suite on the newest Python, in parts with one shard of each suite in TEST_SHARDED_SUITES, the dev checks
+  # included (`make test-part`; TEST_PART_<i> in the Makefile). Each part runs its targets at once, as `make test` runs
+  # its suites, so this job also proves the parallel run on every pull request. The nightly workflow runs the
+  # unsharded `make test`.
   test-py314:
     name: test (part ${{ matrix.shard }}, Python 3.14)
     runs-on: ubuntu-latest

.quality-baseline.json

@@ -15,7 +15,7 @@
       "verb": "make typecheck"
     },
     "markdownlint": {
-      "count": 680,
+      "count": 646,
       "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

@@ -27,10 +27,11 @@ make setup          # check the prerequisites (Python 3.11+, uv, git, Go); nothi
 make format         # rewrite formatting in place
 make format:check   # read-only: formatting and lint rules (alias: make format-check)
 make lint           # read-only lint
-make typecheck      # mypy, strict, on audit/tools, implement/tools and dev, and the engine's build.py
+make typecheck      # mypy, strict: audit/tools, implement/tools, the playbook templates, dev, the engine build.py
 make test           # the engine's, the audit tools', the implement tools' and the dev checks' suites (at once on Linux)
 make check          # THE gate: format:check, typecheck, test, the engine's --verify-rules, the schema
-                    # cross-check, recipe-lint, masters-check, workflow-lint (actionlint, zizmor, check-jsonschema), spell (typos)
+                    # cross-check, recipe-lint, adr-lint, masters-check, eval-expected-check, workflow-lint (actionlint,
+                    # zizmor, check-jsonschema), spell (typos)
 make security       # secrets scan, then the dependency audit (osv-scanner; needs Go and the network)
 make commit-lint    # Conventional Commits subjects on this branch (RANGE=origin/dev..HEAD); CI runs it on each PR
 make update-masters # regenerate docs/reference/audit-master.md and implement-master.md (check runs masters-check)
@@ -112,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`.
 
@@ -146,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.
@@ -159,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
 

LICENSE-TEMPLATES

@@ -0,0 +1,16 @@
+MIT No Attribution
+
+Copyright 2026 K. C. Ramakrishna
+
+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.
+
+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.

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' \
@@ -88,7 +88,7 @@ ENGINE := audit/engine
 # Mypy covers the recipe tools, the dev-only checks and the engine's build script. The engine's own code joins
 # later, through a ratchet. The find picks up every Python file under audit/tools, implement/tools and
 # dev, tests included, except the toy repositories under testdata/ (eval data).
-TYPED_SOURCES := $(shell find audit/tools implement/tools dev -name '*.py' -not -path '*/testdata/*' -not -path '*/dist/*' 2>/dev/null | sort) $(ENGINE)/build.py
+TYPED_SOURCES := $(shell find audit/tools implement/tools implement/playbooks/templates dev -name '*.py' -not -path '*/testdata/*' -not -path '*/dist/*' 2>/dev/null | sort) $(ENGINE)/build.py
 
 .DEFAULT_GOAL := help
 
@@ -107,13 +107,13 @@ endif
 ifndef TEST_SUITES_SUBMAKE
 .NOTPARALLEL:
 endif
-.PHONY: help setup format format-check format\:check lint typecheck test $(TEST_SUITES) test-engine-shard test-audit-tools-shard test-part coverage coverage-engine coverage-engine-shard coverage-audit-tools-shard coverage-part coverage-audit-tools coverage-implement-tools coverage-combine verify-rules crosscheck recipe-lint masters-check update-masters check security security-secrets security-deps update-secrets-baseline self-audit update-audit-baseline validate-skills docs-lint docs-lint-all docs-prose docs-mermaid changelog-fix workflow-lint commit-lint spell spell-fix
+.PHONY: help setup format format-check format\:check lint typecheck test $(TEST_SUITES) test-engine-shard test-audit-tools-shard test-dev-shard test-part coverage coverage-engine coverage-engine-shard coverage-audit-tools-shard coverage-part coverage-audit-tools coverage-implement-tools coverage-combine verify-rules crosscheck recipe-lint adr-lint masters-check eval-expected-check update-masters check security security-secrets security-deps update-secrets-baseline self-audit update-audit-baseline validate-skills docs-lint docs-lint-all docs-prose docs-mermaid changelog-fix workflow-lint commit-lint spell spell-fix
 
 help:
 	@echo "verbs: format  format:check (format-check)  lint  typecheck  test  check  security"
 	@echo "parts: test-engine  test-audit-tools  test-implement-tools  test-dev  coverage-engine  coverage-audit-tools  coverage-implement-tools  coverage-combine"
 	@echo "ci:    test-part SHARD=<i>  coverage-part SHARD=<i>  coverage-combine SHARDED=1  (and test-<suite>-shard, coverage-<suite>-shard)"
-	@echo "extra: setup (checks prerequisites, installs nothing)  coverage  self-audit  update-audit-baseline  verify-rules  crosscheck  recipe-lint  masters-check  update-masters  workflow-lint  commit-lint  spell  spell-fix  update-secrets-baseline  validate-skills"
+	@echo "extra: setup (checks prerequisites, installs nothing)  coverage  self-audit  update-audit-baseline  verify-rules  crosscheck  recipe-lint  adr-lint  masters-check  eval-expected-check  update-masters  workflow-lint  commit-lint  spell  spell-fix  update-secrets-baseline  validate-skills"
 	@echo "docs:  docs-lint  docs-lint-all  docs-prose [FILES=...]  docs-mermaid FILES=...  changelog-fix"
 
 # There is nothing to install into the project: the runtime code is standard-library Python and the dev tools run
@@ -161,9 +161,12 @@ test-dev:
 # CI splits the slow suites (SHARDED_SUITES) into TEST_SHARDS parts that run in separate jobs; SHARD=<i> picks one
 # (1 to TEST_SHARDS). dev/test_shard.py finds the modules at run time and balances them by
 # dev/test_shard_weights.json; every module is in exactly one shard, and a shard that selects no test fails. `test`
-# and `coverage` never shard.
+# and `coverage` never shard. TEST_SHARDED_SUITES are the suites that test-part shards: SHARDED_SUITES, plus the dev
+# checks, which coverage.py does not measure. The dev checks are sharded only in the Python 3.14 parts, where the whole
+# suite set the length of the run (76-97 s, against 60 s or less for every other job; measured 2026-11-10).
 TEST_SHARDS := 2
 SHARDED_SUITES := engine audit-tools
+TEST_SHARDED_SUITES := engine audit-tools dev
 test_shard = $(CURDIR)/dev/test_shard.py --suite $(1) --shard $(SHARD)/$(TEST_SHARDS)
 require_shard = @test -n "$(SHARD)" || { echo "$@: set SHARD to a number from 1 to $(TEST_SHARDS)" >&2; exit 1; }
 
@@ -175,15 +178,19 @@ test-audit-tools-shard:
 	$(require_shard)
 	$(PYTHON) $(call test_shard,audit-tools)
 
-# Every suite of `test` in TEST_SHARDS parts, for CI's Python 3.14 jobs: part <i> is shard <i> of each sharded suite
-# plus the targets in TEST_PART_<i>, run at once as `test` runs its suites. test-dev takes about as long as an engine
-# shard, so it shares a part with no other whole suite. dev/tests/test_ci_parity.py fails when the parts leave out a
-# suite of `test`.
-TEST_PART_1 := test-implement-tools verify-rules
-TEST_PART_2 := test-dev
+test-dev-shard:
+	$(require_shard)
+	$(PYTHON) $(call test_shard,dev)
+
+# Every suite of `test` in TEST_SHARDS parts, for CI's Python 3.14 jobs: part <i> is shard <i> of each suite in
+# TEST_SHARDED_SUITES plus the targets in TEST_PART_<i>, run at once as `test` runs its suites. The dev checks' first
+# shard is test_implement_eval alone (about 40 s), so the small whole targets go with the second.
+# dev/tests/test_ci_parity.py fails when the parts leave out a suite of `test`.
+TEST_PART_1 :=
+TEST_PART_2 := test-implement-tools verify-rules
 test-part:
 	$(require_shard)
-	$(MAKE) --no-print-directory TEST_SUITES_SUBMAKE=1 $(TEST_JOBS) $(SHARDED_SUITES:%=test-%-shard) $(TEST_PART_$(SHARD))
+	$(MAKE) --no-print-directory TEST_SUITES_SUBMAKE=1 $(TEST_JOBS) $(TEST_SHARDED_SUITES:%=test-%-shard) $(TEST_PART_$(SHARD))
 
 # Runs the engine's suite and the tools' suites under coverage.py and fails when the total drops below the floor in
 # .coveragerc (`fail_under`). Not part of `check`; needs uv. Each coverage-<suite> writes its own data file
@@ -285,6 +292,10 @@ crosscheck:
 recipe-lint:
 	$(PYTHON) dev/recipe_lint.py .
 
+# Every ADR follows docs/ADR_POLICY.md: no lifecycle fields or tombstones, the four sections, a row in the root index.
+adr-lint:
+	$(PYTHON) dev/adr_lint.py .
+
 # The audit and implement master lists (docs/reference/*-master.md) are generated from the catalogue, the check files
 # and the playbooks. masters-check fails when either page is stale; update-masters rewrites them.
 masters-check:
@@ -293,6 +304,12 @@ masters-check:
 update-masters:
 	$(PYTHON) dev/build_masters.py --write
 
+# The eval-expected files (dev/eval/expected/fixtures/) are generated from the engine's fixture matrix by running the
+# engine on each fixture (a few seconds). eval-expected-check fails when one is stale; run the script without --check
+# to rewrite them.
+eval-expected-check:
+	$(PYTHON) dev/eval/generate_fixture_expected.py --check
+
 # Lints the GitHub Actions workflows and checks .github/dependabot.yml. All three tools run offline.
 # Read-only: report each misspelling with its file and line. `make spell-fix` writes the suggested fixes; review them.
 spell:
@@ -313,7 +330,7 @@ RANGE ?= origin/dev..HEAD
 commit-lint:
 	$(PYTHON) dev/commit_lint.py --range $(RANGE)
 
-check: format-check typecheck test verify-rules crosscheck recipe-lint masters-check workflow-lint spell
+check: format-check typecheck test verify-rules crosscheck recipe-lint adr-lint masters-check eval-expected-check workflow-lint spell
 
 # No third-party runtime dependencies exist to audit, so the gate is a secrets scan. The baseline
 # lists the deliberate key-shaped strings in the fixtures and tests; a new hit fails the scan.

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