Story: Keep the nightly include-cleaner out of generated files
Table of Contents
This page documents a story in Sprint 27. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
1. Goal
Every include fix from the nightly run lands in the layer that owns the file: hand-crafted sources directly, generated sources through their templates.
2. Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 27 |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-10-07 |
3. Acceptance
- The changes in PR #2738 are classified as generated or hand-crafted, with the method recorded.
- The nightly fixer leaves generated files alone and reports them instead.
- The sound hand-crafted fixes land and the unsound suggestions are dropped.
4. Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Scaffold story: Keep the nightly include-cleaner out of generated files | DONE | 2026-10-07 | 2026-10-07 | Story scaffolding rides this task: documents, sprint wiring, and the scaffold PR. Close it before merging that PR. |
| Separate the nightly include fixes by layer and guard generated files | DONE | 2026-10-07 | 2026-10-07 | Classify the run's files by the codegen marker, apply the hand-crafted fixes, drop the suggestions that name implementation headers, and make check_includes.sh skip generated files. |
5. Decisions
- The classification is the codegen's own marker, not the file name or
path. Every output carries
AUTO-GENERATED FILE - DO NOT EDIT MANUALLY, andcheck_component_drift.pyindependently confirms that applying the whole run leaves the refdata generated tree clean. File naming would have mis-classified several files:asset_class_service.cppis hand-written whileasset_class_code_service.cppis generated. - The fixer skips generated files rather than formatting them and failing
the drift gate later. A generated file's includes belong to its archetype
in
library/templates/ores.*.org, so the script names the skipped files and the fix goes to the template, the tangle and the regeneration. - Implementation-header suggestions are refused. clang-tidy names the
header that defines a symbol even when a public header forwards to it, so
<bits/chrono.h>,<boost/asio/impl/co_spawn.hpp>and the_implrunner headers are dropped in favour of their public equivalents.
6. Out of scope
7. Result
The nightly run's changes are classified by the codegen's own marker, applied where they are hand-crafted, and refused where they name an implementation header. The fixer now skips generated files and names them, so a generated file's includes are fixed in its archetype instead of in output the next regeneration overwrites. Landed with PR #2739.