ci: enforce change document declarations

.agents/skills/README.md

@@ -14,7 +14,7 @@ python3 .agents/tooling/generate_skill_mirrors.py
 
 | Skill | Description |
 |-------|-------------|
-| `dev-workflow` | End-to-end feature development: propose, plan, execute, verify, archive |
+| `dev-workflow` | Classify and execute features, enhancements, refactors, optimizations, and bug fixes |
 | `archive` | Archive completed change proposals to `docs/_archive/` |
 | `dtvm-perf-profile` | Performance profiling with hardware counters |
 | `dmir-compiler-analysis` | DMIR compiler analysis and cost model reference |

.agents/skills/dev-workflow/SKILL.md

@@ -1,27 +1,39 @@
 ---
 name: dev-workflow
-description: Feature development workflow. Propose a change, plan implementation, execute with gates, and verify.
+description: Development workflow for features, enhancements, refactors, optimizations, and bug fixes. Classify change-document requirements, plan implementation, execute with gates, and verify.
 ---
 
 # Development Workflow
 
-End-to-end workflow for implementing changes: propose, plan, execute, verify, and optionally archive.
+Use this workflow for implementation work that changes repository behavior or
+development contracts. It covers change-document classification, planning,
+execution, verification, and optional post-merge archiving.
 
 ## Phase A - Propose
 
-1. Determine the change tier:
+1. Classify the change before editing implementation files:
    - **Full**: cross-module, architecture, new capabilities, breaking changes
-   - **Light**: single-module, well-scoped, limited blast radius
+   - **Light**: single-module, well-scoped, limited blast radius, or a bug fix
+     with design implications
+   - **N/A**: only typo-only, comment-only, test-only, or clearly
+     behavior-preserving trivial fixes
 
-2. Create a change document:
+   Any change to runtime semantics, determinism, gas accounting, compiler
+   scheduling, a module contract, or security requires at least a Light
+   document. File count alone never makes such a change exempt.
+
+2. For an exempt change, record a specific `N/A` reason and continue to
+   Phase C. Otherwise, create a change document:
    - Full tier: copy `docs/changes/template.md` to `docs/changes/YYYY-MM-DD-<slug>/README.md`
    - Light tier: copy `docs/changes/template-light.md` to `docs/changes/YYYY-MM-DD-<slug>/README.md`
 
-3. Fill in the document and set status to `Proposed`
+3. Fill in the document and set its status to `Proposed`.
+4. After explicit approval, change the status to `Accepted` before
+   implementation starts.
 
 ## Phase B - Plan
 
-After the change proposal is accepted:
+For changes with an accepted proposal:
 
 1. Consult relevant module specs in `docs/modules/<module>/spec.md`
 2. Identify affected files, contracts, and tests
@@ -38,15 +50,21 @@ Implement with quality gates:
 
 Mark each step complete as you go.
 
-## Phase D - Verify and Archive
+## Phase D - Verify and Handoff
 
 1. Run the full build and test suite
 2. Update affected module specs in `docs/modules/` if contracts changed
-3. Update the change document status to `Implemented`
-4. Optionally use the `archive` skill to move the completed change to `docs/_archive/`
+3. After implementation and required verification are complete, update the
+   change document status to `Implemented`
+4. Before creating a commit or pull request, validate exactly one declaration:
+   - `Change doc: docs/changes/YYYY-MM-DD-<slug>/README.md`
+   - `N/A: <specific reason>`
+5. After merge, use the `archive` skill only when the user explicitly requests
+   archiving
 
 ## Notes
 
-- If the change is a simple bug fix or typo, skip to Phase C directly
 - Always consult module specs before modifying code in unfamiliar areas
 - When code conflicts with specs, code takes precedence, but update specs afterward
+- CI checks that the declaration is present and the referenced path exists.
+  Reviewers decide whether an `N/A` reason satisfies the semantic skip criteria.

.claude/skills/dev-workflow/SKILL.md

@@ -2,7 +2,7 @@
 
 # dev-workflow
 
-**Description**: Feature development workflow. Propose a change, plan implementation, execute with gates, and verify.
+**Description**: Development workflow for features, enhancements, refactors, optimizations, and bug fixes. Classify change-document requirements, plan implementation, execute with gates, and verify.
 
 ## Source of Truth
 

.github/pull_request_template.md

@@ -80,10 +80,25 @@ test cases https://github.com/XXX/pull/44
 benchmark stats: time XXX ms
 -->
 
-#### 6. Release note
+#### 6. Change document
+
+<!--
+Keep exactly one declaration below.
+
+For a governed change:
+Change doc: docs/changes/YYYY-MM-DD-<slug>/README.md
+
+Only for typo-only, comment-only, test-only, or clearly behavior-preserving
+trivial fixes, replace the declaration with:
+N/A: <specific reason>
+-->
+
+Change doc:
+
+#### 7. Release note
 
 <!-- compatibility change, improvement, bugfix, and new feature need a release note -->
 
 ```release-note
 None
-```
+```

.github/workflows/commit-lint.yml

@@ -77,4 +77,21 @@ jobs:
                 exit 0
               fi
             fi
-          fi 
+          fi
+
+  change-document:
+    name: Validate Change Document Declaration
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout pull request head
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Test change-document validator
+        run: python3 -m unittest discover -s tools/tests -p 'test_check_change_doc.py'
+
+      - name: Validate pull request declaration
+        run: python3 tools/check_change_doc.py --event-path "$GITHUB_EVENT_PATH"

docs/changes/2026-07-28-enforce-change-document-declaration/README.md

@@ -0,0 +1,89 @@
+# Change: Enforce change-document declarations
+
+- **Status**: Implemented
+- **Date**: 2026-07-28
+- **Tier**: Light
+- **Review**: Pending independent review
+
+## Overview
+
+Require every pull request to declare either the change document that governs
+the work or a concrete reason why no change document is needed. Align the
+project guidance and development workflow on the same exemption criteria and
+status transitions.
+
+## Motivation
+
+The project currently has conflicting entry rules. The agent guide and
+development workflow allow simple bug fixes to skip proposal work, while the
+change-proposal guide requires a Light document for bug fixes with design
+implications. The workflow description also emphasizes features, and neither
+the pull request template nor CI checks the final classification. These gaps
+allow behavior-changing fixes to reach review without a change document.
+
+## Impact
+
+The change affects development-process contracts in the agent guide,
+development workflow, pull request template, and CI. A small Python tool
+validates declarations locally and in GitHub Actions.
+
+The exemption remains explicit and reviewable. Typo-only, comment-only,
+test-only, and clearly behavior-preserving trivial fixes may use `N/A` with a
+specific reason. Changes to runtime semantics, determinism, gas accounting,
+compiler scheduling, module contracts, security, or bug fixes with design
+implications require at least a Light change document.
+
+CI validates the declaration, not the semantic classification. It therefore
+does not infer that every `src/` change needs a document. Reviewers retain
+responsibility for rejecting an invalid exemption.
+
+The declaration accepts exactly one of these forms:
+
+```text
+Change doc: docs/changes/YYYY-MM-DD-<slug>/README.md
+N/A: <specific reason>
+```
+
+For a path declaration, the validator checks the repository-relative naming
+convention and confirms that the file exists at the pull request head. For an
+exemption, it rejects empty and placeholder reasons. The same tool reads a
+literal declaration during local preparation and the pull request event
+payload in CI.
+
+Status transitions have one definition across the project:
+
+- `Proposed` begins when the initial document is ready for review.
+- `Accepted` begins after explicit approval and before implementation starts.
+- `Implemented` begins after implementation and required verification are
+  complete. Merge is not part of this transition, so the document can describe
+  the verified state in the implementation pull request.
+
+## Checklist
+
+- [x] Align the DTVMDotfiles agent-guide SSOT with the project policy
+- [x] Update the development workflow trigger, exemptions, and status mapping
+- [x] Add a pull request declaration and a local/CI validation tool
+- [x] Add automated tests and document the tool contract
+- [x] Regenerate and check skill mirrors
+- [x] Run the relevant build and tests
+
+## Verification
+
+- The validator test suite passes 12 tests covering accepted declarations,
+  rejected placeholders and duplicates, repository path checks, pre-commit
+  worktree handling, and policy wiring.
+- The generated Claude skill mirrors match their `.agents/skills/` sources.
+- The validator accepts both the governing change-document declaration and a
+  specific `N/A` declaration in local mode.
+- The repository format check passes, the GitHub Actions workflow parses as
+  YAML, and `git diff --check` reports no whitespace errors.
+- The CI-derived Release configuration builds `dtvmapi`; the post-change build
+  reports no additional work because no C++ inputs changed.
+- DTVMDotfiles release preflight, release, drift detection, skill-state check,
+  and agent-skill integration test pass.
+
+`dtvm_local_test.sh --auto` selected the conservative multipass evmone unit and
+state-test suites for the mixed tooling and CI paths. Its preflight stopped
+before execution because the local evmone binaries and EEST fixture corpus are
+not installed. No runtime source changed, and this missing environment is
+reported rather than replaced with a different test category.

docs/changes/README.md

@@ -17,11 +17,16 @@ docs/changes/YYYY-MM-DD-<slug>/README.md
 
 | Status | Meaning |
 |--------|---------|
-| **Proposed** | Under review, not yet approved for implementation |
-| **Accepted** | Approved, ready for implementation |
-| **Implemented** | Implementation complete and merged |
+| **Proposed** | Initial document is ready for review; implementation is not approved |
+| **Accepted** | Explicitly approved before implementation starts |
+| **Implemented** | Implementation and required verification are complete; merge is not required for this transition |
 | **Rejected** | Declined with documented rationale |
 
+Set `Proposed` when the initial document is ready for review. Set `Accepted`
+only after explicit approval and before implementation begins. Set
+`Implemented` after the implementation and required build, test, and spec
+updates are complete, before pull request handoff.
+
 ## Tiers
 
 ### Full Tier
@@ -43,6 +48,20 @@ Typical triggers:
 - Bug fixes with design implications
 - Non-breaking enhancements
 
+### When a Change Document Is Not Required
+
+A pull request may declare `N/A` only for:
+
+- typo-only changes;
+- comment-only changes;
+- test-only changes;
+- clearly behavior-preserving trivial fixes.
+
+The declaration must include a specific reason. Changes to runtime semantics,
+determinism, gas accounting, compiler scheduling, module contracts, or security
+require at least a Light document. A bug fix with design implications also
+requires at least a Light document, regardless of file count.
+
 ## Current Proposals
 
 | Date | Name | Status | Tier | Description |
@@ -53,6 +72,7 @@ Typical triggers:
 | 2026-04-14 | [from-raw-pointer-safety-checks](2026-04-14-from-raw-pointer-safety-checks/README.md) | Accepted | Light | Add null/alignment safety checks to `from_raw_pointer` in Rust bindings |
 | 2026-05-13 | [evm-ngram-macro-ops](2026-05-13-evm-ngram-macro-ops/README.md) | Implemented | Full | Initial EVM n-gram macro-op lowering and specialized keccak helpers for multipass JIT |
 | 2026-07-21 | [evm-memory-alias-and-expansion](2026-07-21-evm-memory-alias-and-expansion/README.md) | Implemented | Full | Stronger memory alias proofs, wider precheck/expansion coverage, DSE, load forwarding, grouping, and MCOPY roadmap |
+| 2026-07-28 | [enforce-change-document-declaration](2026-07-28-enforce-change-document-declaration/README.md) | Implemented | Light | Require a change-document path or explicit exemption on every pull request |
 
 Each active proposal lives in its own subdirectory. Browse `docs/changes/*/README.md`
 to see all current proposals, or use:
@@ -65,5 +85,8 @@ ls docs/changes/*/README.md
 
 1. Copy the appropriate template into a new `YYYY-MM-DD-<slug>/` directory
 2. Fill in the change document
-3. Follow the `dev-workflow` skill for implementation
-4. After merging, move the completed change to `docs/_archive/`
+3. Change `Proposed` to `Accepted` after explicit approval and before implementation
+4. Follow the `dev-workflow` skill for implementation
+5. Change `Accepted` to `Implemented` after implementation and verification complete
+6. Before pull request handoff, validate a change-document path or an explicit `N/A` reason
+7. After merging, use the `archive` skill only when archiving is explicitly requested

docs/modules/tools/spec.md

@@ -10,6 +10,8 @@ The tools module provides **development helper scripts**, responsible for:
 - **EVM test tools**: EVM assembly to bytecode, EVM test runner, state root/MPT comparison
 - **Solidity compilation**: Batch compile Solidity contracts to JSON
 - **Static analysis**: Parallel clang-tidy, performance regression checks
+- **Contribution validation**: Change-document declaration checks for local
+  preparation and pull request CI
 - **Debugging aids**: GDB trace, CPU trace collection
 
 This module does not include: Build system (CMake), test framework (gtest/ctest), core runtime logic.
@@ -58,7 +60,21 @@ This module does not include: Build system (CMake), test framework (gtest/ctest)
 | collect_cpu_trace.py | Collect CPU trace data |
 | bug_finder.py | Binary search for `GREEDY_FUNC_IDX_*` range that triggers exception (experimental) |
 
-### 7. Miscellaneous
+### 7. Contribution Validation
+
+`check_change_doc.py` requires exactly one declaration:
+
+- `Change doc: docs/changes/YYYY-MM-DD-<slug>/README.md`
+- `N/A: <specific reason>`
+
+For a change-document path, the tool validates the naming convention and file
+existence at the checked head revision. For an exemption, it rejects empty and
+placeholder reasons. Local callers provide a literal declaration and base
+revision. GitHub Actions provides the pull request event payload. The tool does
+not infer documentation requirements from changed paths; semantic exemption
+review remains a reviewer responsibility.
+
+### 8. Miscellaneous
 
 | Script | Responsibility |
 |--------|----------------|
@@ -76,10 +92,13 @@ This module does not include: Build system (CMake), test framework (gtest/ctest)
 | dtvm | EVM/WASM execution (run_evm_tests, bug_finder) |
 | gdb | Debug tracing |
 | Python 3 | pycryptodome, eth-hash, trie, rlp |
+| Git | Revision and change-document path validation |
 
 ## Invariants and Permissions
 
 - **Read-only preference**: Format scripts default to check; format writes
+- **Contribution checks are read-only**: Declaration validation never modifies
+  the worktree or Git index
 - **Paths**: Project root as working dir; relative paths to `tests/`, `build/`
 - **Idempotent**: easm2bytecode, solc_batch_compile may be run repeatedly