davidahmann · davidahmann · Sep 22, 2026 · Sep 22, 2026
@@ -1,6 +1,6 @@
 # AGENTS.md: operating Mill safely
 
-Version: 2.7
+Version: 2.8
 
 Status: normative
 
@@ -162,6 +162,13 @@ two-step plan/apply wrapper, never as implicit push authority.
   release authority.
 - Report measured, partial and unavailable usage truthfully. Routine output must
   not expose private emails, commit trailers, raw worker context or logs.
+- If a task declares `budget.maxModelTokens`, check measured input plus output
+  tokens before every later worker call. Missing prior measurements block. This
+  is a between-invocation guard; it is not a hard cap on an in-flight call.
+- Repository review checklists are focused guidance selected from changed paths
+  and risk class. Read them from the immutable review base, bind their digests
+  to the scope, and still inspect the complete diff. They cannot change task
+  authority or acceptance.
 - `stats` and `report` are read-only, redacted local aggregates. `report` uses
   an explicitly declared development-evidence ledger for eligible-change and
   route counts; it does not infer a productivity or customer-value measure from

@@ -4,6 +4,24 @@ All notable changes follow Keep a Changelog and Semantic Versioning.
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-22
+
+### Added
+
+- Add an optional between-invocation model-token allowance with phase-level
+  measured usage for build, repair, and review calls.
+- Select bounded repository review checklists from changed paths and task risk,
+  then bind their base-revision digests into the complete review scope.
+- Use one deterministic local promotion-readiness policy in admitted delivery,
+  merge, and standalone maintainer review.
+
+### Changed
+
+- Record maintainer-review provider usage and checklist focus in its immutable
+  receipt.
+- Retain provider measurements from failed calls when available without
+  estimating missing tokens or currency cost.
+
 ## [0.9.0] - 2026-09-21
 
 ### Added

@@ -25,7 +25,7 @@ GitHub workflow.
 Pin a released version in the repository that will use Mill:
 
 ```sh
-npm i -D -E --ignore-scripts @davidahmann/mill@0.9.0
+npm i -D -E --ignore-scripts @davidahmann/mill@0.10.0
 npx --no-install millctl --version
 ```
 
@@ -101,6 +101,11 @@ npx --no-install millctl --json review \
 The builder cannot edit task authority or the declared controls that certify its
 change. Verification and review bind to the same candidate commit.
 
+An optional `budget.maxModelTokens` limits measured input plus output tokens
+across the run. Mill checks the total before each later model call. It blocks
+when prior usage is incomplete or the allowance is spent. The current call can
+still cross the allowance because provider usage arrives after completion.
+
 ### 4. Approve a draft pull request
 
 ```sh
@@ -132,6 +137,11 @@ feedback, missing completion, stale feedback, failed checks, and review drift
 block the applicable phase. Read [review policy](docs/review-policy.md) before
 changing this boundary.
 
+Repositories may also map short review checklists to changed paths in
+`review.checklists`. Mill reads selected checklists from the immutable review
+base, records their digests in the review scope, and still requires review of
+the complete diff.
+
 Attended merge is opt-in. It requires producer-bound checks, strict up-to-date
 branch protection, allowed operator and merger identities, and an exact approval
 plan:
@@ -159,6 +169,9 @@ and [repository settings](docs/repository-settings.md).
   versioned in Git.
 - Each run binds the base, configuration, context, budget, candidate,
   validation, review, and delivery evidence by digest.
+- One promotion preflight applies the same exact-candidate validation and local
+  review rules before draft delivery and merge. The maintainer review script
+  uses the same evaluator before reporting a candidate ready to push.
 - The builder cannot push, merge, deploy, or rewrite its acceptance oracle.
 - GitHub effects are planned, approved, journaled, read back, and reconciled.
 - Native checks remain the repository's source of behavioral evidence.

@@ -15,7 +15,9 @@ bookkeeping, closure, tests, or docs into micro-PRs.
 
 For native maintainer changes outside an admitted run, use the packaged
 [local review script](docs/maintainer-review.md). It records exact-candidate
-validation and independent review without claiming runtime delivery authority.
+validation, selected base-owned review guidance, provider usage, and independent
+review without claiming runtime delivery authority. Its readiness decision uses
+the same local promotion policy as admitted draft delivery and merge.
 
 For each wave:
 

@@ -313,6 +313,12 @@ version `2`, including an approved impact manifest and explicit acceptance,
 invariant, scenario, coverage, and evidence bindings. Do not rewrite an
 in-flight version `1` task: its canonical bytes and digest remain unchanged.
 
+Task-packet version `2` may set `budget.maxModelTokens`. The value covers
+provider-measured input plus output tokens across build, repair, and review.
+Before a later invocation, incomplete prior usage or an exhausted allowance
+blocks. The first call is admitted, and an in-flight call may cross the limit
+because its usage is known only after settlement.
+
 The real-provider canaries use the maintainer's personal Codex and GitHub
 accounts, a pre-pulled digest-pinned image, and an explicitly named disposable
 repository. They may exercise only the wave's approved effects and must preserve

@@ -22,10 +22,16 @@ Use these terms consistently when operating or reviewing Mill.
   but it cannot alter acceptance criteria or approve an action.
 - **Proposal:** structured product input that Mill can inspect and compare with
   sources. It becomes authority only after the repository's approval process.
+- **Promotion preflight:** the deterministic local decision that validation and
+  review are current, exact, and free of blocking findings. GitHub checks,
+  hosted review, approval, and readback remain separate delivery gates.
 - **Repair:** one new candidate built from recorded verification or review
   findings. It must repeat validation and review; it cannot certify itself.
 - **Report:** a redacted, read-only aggregate of local run outcomes and recorded
   usage. It cannot establish customer value or authorize a change.
+- **Review checklist:** bounded repository guidance selected by changed path and
+  risk class from the immutable review base. It focuses the reviewer without
+  narrowing the complete diff or changing acceptance.
 - **Self-hosting:** Mill's own repository using its delivery process. It is an
   operating measure, not proof that every downstream repository is supported.
 - **Task packet:** the versioned, bounded execution authority for one outcome.

@@ -6,6 +6,10 @@ fresh Codex reviewer in read-only mode. P0/P1 findings block; P2/P3 findings
 stay in the receipt as advisory. The operator still decides whether the selected
 validation covers the change.
 
+When the immutable base configures `review.checklists`, the script selects the
+path-matched files from that base and records their digests with the changed
+paths. The reviewer uses them as focus guidance while inspecting the full diff.
+
 Run from a clean repository root, with dependencies already prepared. Supply
 full commit IDs. The base must be an ancestor of the candidate, and the
 candidate must be the current HEAD. Store the receipt outside the repository.
@@ -30,9 +34,10 @@ node /path/to/mill/scripts/maintainer-review.mjs check \
 
 For an installed package, the script is at
 `node_modules/@davidahmann/mill/scripts/maintainer-review.mjs`. Keep the same
-script version for recording and checking a receipt. A changed script, base,
-candidate, tree, or dirty checkout requires fresh evidence. The checker does not
-fetch the provider base; the operator must supply its current exact commit.
+script version for recording and checking a receipt. A changed script,
+promotion-policy helper, base, candidate, tree, checklist scope, or dirty
+checkout requires fresh evidence. The checker does not fetch the provider base;
+the operator must supply its current exact commit.
 
 The validation argument is an argv array, not a shell expression. It executes
 with the operator's environment and authority. Choose the repository's native
@@ -41,6 +46,12 @@ checks, and do not put secrets in command arguments. Each command has a
 evidence creation; rerun the command directly to diagnose it. The receipt stores
 a digest of validation stdout, not raw logs.
 
+The receipt records reviewer input, output, and cache-input tokens only when the
+provider emits usable measurements. Currency cost remains unavailable. Its
+readiness result comes from the same exact-candidate validation and blocking
+review evaluator used before admitted delivery and merge. It does not include
+GitHub checks or hosted review; those remain separate post-push gates.
+
 Codex uses its existing local login. Its process receives no standard GitHub or
 npm token environment variables. Strict configuration and the read-only sandbox
 reduce accidental mutation; they do not isolate a hostile host or remove

@@ -0,0 +1,24 @@
+# Mill 0.10.0
+
+This source candidate reduces repeated review and model work while preserving
+Mill's existing authority and delivery boundaries.
+
+One deterministic promotion policy now checks exact-candidate validation, review
+scope, and blocking findings before admitted draft delivery and merge. The
+standalone maintainer reviewer uses the same policy and records its provider
+usage in the immutable receipt.
+
+Task packets may set an aggregate model-token allowance. Mill records build,
+repair, and review usage separately, including failed calls when the provider
+emits measurements. Before a later model call, it blocks if prior measurements
+are incomplete or measured input plus output tokens have reached the allowance.
+This cannot prevent the current call from crossing the allowance.
+
+Repositories may configure small review checklists by changed path and risk
+class. Selected files are read from the immutable review base and bound to the
+complete-diff scope. They focus one reviewer; they do not narrow the review or
+change acceptance authority.
+
+Publication and npm/GitHub channel pointers are established by the protected
+workflow's final release evidence. This source record grants no new stack,
+model, provider, customer, deployment, or unattended-operation claim.
@@ -12,7 +12,16 @@ millctl --json report
 The run section groups lifecycle and validation facts. Its elapsed time is run
 wall time. It is not a measure of human effort or productivity. Provider usage
 appears only when the provider recorded it; unavailable usage remains `null` or
-`unavailable`.
+`unavailable`. The report separates build, repair, and review calls. A failed
+call is included when the provider emitted complete input and output counts.
+Cache input remains separate and is not added to input tokens again.
+
+A task may set `budget.maxModelTokens` to the allowed sum of measured input and
+output tokens for the run. Mill admits the first call, then checks the recorded
+total before each later call. It blocks when the allowance is spent or any prior
+admitted call lacks complete usage. Providers report usage after a call, so this
+guard cannot stop an in-flight call from crossing the allowance. Mill does not
+estimate missing tokens or currency cost.
 
 The `developmentEvidence` section uses the ledger as its denominator. Each
 record states whether a change was eligible, whether it used Mill or a manual

@@ -22,6 +22,32 @@ policy was frozen for that delivery. Unclassified feedback blocks. An explicit
 required GitHub approval remains required; advisory findings do not turn a
 rejection or missing approval into approval.
 
+## Focus review with repository checklists
+
+`review.checklists` may select short repository-owned files by changed path and
+task risk class:
+
+```yaml
+review:
+  blocking: p0_p1
+  checklists:
+    - id: runtime-state
+      path: policy/review/runtime-state.md
+      pathPatterns: [src/runtime/**, src/contracts/**]
+      riskClasses: [medium, high]
+```
+
+Mill selects no more than eight checklists. Each file is limited to 32 KiB and
+the selected set to 128 KiB. It reads the files from the immutable review base,
+records their paths and digests in the scope, and supplies their contents to the
+reviewer. Changed checklist files take effect on the next admitted base. A
+checklist focuses inspection; it cannot exclude changed files, alter acceptance,
+or authorize delivery.
+
+The maintainer review script applies the base revision's checklist mappings by
+changed path. It has no task risk class, so a maintainer checklist should use a
+path mapping when it must apply to that route.
+
 ## GitHub review modes
 
 `propose.reviewPolicy` has three modes:

@@ -15,7 +15,12 @@ export default tseslint.config(
   ...tseslint.configs.strictTypeChecked,
   ...tseslint.configs.stylisticTypeChecked,
   {
-    files: ["src/**/*.ts", "test/**/*.ts", "vitest.config.ts"],
+    files: [
+      "src/**/*.ts",
+      "test/**/*.ts",
+      "scripts/**/*.d.mts",
+      "vitest.config.ts",
+    ],
     languageOptions: {
       parserOptions: {
         projectService: true,

@@ -3,6 +3,34 @@ repositoryId: 889e67bd-0768-4f73-9e18-286f2fb8b5f3
 trustCeiling: propose
 review:
   blocking: p0_p1
+  checklists:
+    - id: runtime-state
+      path: policy-starters/review-checklists/runtime-state.md
+      pathPatterns: [src/runtime/**, src/contracts/**, schemas/**]
+    - id: tests-authority
+      path: policy-starters/review-checklists/tests-authority.md
+      pathPatterns:
+        [
+          test/**,
+          docs/**,
+          policy-starters/**,
+          AGENTS.md,
+          WORKFLOW.md,
+          mill.yaml,
+        ]
+    - id: delivery-release
+      path: policy-starters/review-checklists/delivery-release.md
+      pathPatterns:
+        [
+          src/runtime/delivery.ts,
+          src/runtime/merge.ts,
+          scripts/**,
+          .github/**,
+          package.json,
+          package-lock.json,
+          docs/release.md,
+          docs/releases/**,
+        ]
 reporting:
   ledgerPath: quality/development-evidence-ledger.yaml
 sensitivePaths: [".env", ".npmrc", ".mill/**"]

@@ -1,6 +1,6 @@
 {
   "name": "@davidahmann/mill",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Local-first software factory for new and existing codebases. Turns approved product intent into tested, reviewed PRs with repo-native evidence and explicit human approval for delivery and merge.",
   "license": "Apache-2.0",
   "author": "David Ahmann",
@@ -15,7 +15,9 @@
     "schemas/",
     "README.md",
     "LICENSE",
-    "scripts/maintainer-review.mjs"
+    "scripts/maintainer-review.mjs",
+    "scripts/promotion-readiness.mjs",
+    "scripts/promotion-readiness.d.mts"
   ],
   "exports": {
     "./schemas/*.json": "./schemas/*.json"

@@ -25,3 +25,8 @@ downstream Mill pin, deliberate. The verified Dependabot DCO exception is not an
 exemption from reviewing manifests, lockfiles and affected behavior. Mill's
 standalone maintainer review script can record that exact-candidate review
 before merge; it does not install a required GitHub check.
+
+`review-checklists/` contains three short focus guides for runtime state, tests
+and authority, and delivery and release work. Copy only the guides that match
+the target repository, then map them in `mill.yaml`. They guide one full-diff
+review; they do not replace repository tests or acceptance criteria.
@@ -0,0 +1,12 @@
+# Delivery and release review
+
+- Bind each remote effect to an exact commit, repository, actor, and prior
+  intent.
+- Check retries, readback, and reconciliation for duplicate or ambiguous
+  effects.
+- Preserve required checks, hosted review, approval expiry, and merge
+  protection.
+- Check that release publication uses the qualified artifact without rebuilding
+  it.
+- Check package version, tag, npm channel, GitHub Release, and retained evidence
+  identity.
@@ -0,0 +1,8 @@
+# Runtime and state review
+
+- Check every state transition and event write for one transactional outcome.
+- Check restart, cancellation, timeout, and ambiguous process-exit paths.
+- Reject authority inferred from mutable worktree state or unbound provider
+  data.
+- Check schema compatibility, migration behavior, and old-record parsing.
+- Check path, process, and concurrency boundaries for fail-open behavior.
@@ -0,0 +1,8 @@
+# Tests and authority review
+
+- Map changed behavior to an independent acceptance or preservation check.
+- Check that tests can fail for the defect they claim to detect.
+- Reject fixtures, mocks, or snapshots that silently replace the real boundary.
+- Check that generated schemas, docs, and examples agree with executable policy.
+- Reject changes that let the builder alter the evidence used to accept its
+  work.
@@ -58,6 +58,11 @@
           "minimum": 1024,
           "maximum": 10000000
         },
+        "maxModelTokens": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100000000
+        },
         "retryCount": { "type": "integer", "minimum": 0, "maximum": 1 }
       },
       "required": ["deadlineSeconds", "maxOutputBytes", "retryCount"],