The change map
For a given kind of change, every layer it touches and the check that proves it landed.
Most mistakes in CCC are not wrong code. They are a layer nobody remembered, failing silently. This page is the map from a task to its layers.
AGENTS.md holds the authoritative checklists. This page organises them by the task you actually have.
Adding a page
| Layer | Why it fails silently if skipped |
|---|---|
| The page controller | |
| Its data endpoint | The table renders empty with no error if its shape is wrong |
| Its template | |
| A guarded navigation entry | The page works and nobody can find it |
| Re-run the installer | The page returns unauthorised, because the permission matrix is built from disk |
A page that renders a chart, an iframe or disk-based documentation may have no data endpoint. Follow the nearest existing page of that kind.
Check: load it, find it in the navigation, confirm the table fills, and confirm a user without the permission gets the unauthorised template.
Adding a source or a job
| Layer | Why it fails silently if skipped |
|---|---|
| The job file | |
| Its schedule line | It never runs, and nothing reports that |
| Its entry in the cron inventory | It runs unswitchable, and nothing says so |
| Queued by a reset job, if it consumes a queue | The worker runs with nothing to do |
| A healthcheck, if its output matters | It fails quietly forever |
| Switch it on | A new step arrives switched off, by design |
Check: run it once by hand; confirm the batch moves todo to in progress to finished; confirm its healthcheck is green.
Adding a classification
| Layer | Note |
|---|---|
| The classify model | |
| The table schema | |
| The dictionary description | Otherwise the column has no meaning anywhere |
| The list getter and the template header | A star selection can expose a classification field in JSON; the visible table still needs an explicit template header |
| The rule-filter blacklist | A new column becomes a rule filter automatically. Decide whether it should be one |
Check: read a real row back. A finished batch is not evidence that a row was written.
Changing anything money-shaped
Read contribution margin and calculation rules first. Then consider:
- does this change the sign convention anywhere
- does it affect both realised and expected margin, or only one
- does it require recalculation, and over what window
Check: take one order, compute its margin by hand from its impacts, and compare.
Changing anything customer-shaped
Read customer matching and sequence and life first.
Grouping is transitive and rebuilt rather than patched, so a change here moves historic figures. Say so to whoever consumes them.
Check: a synthetic group with a known shape, before and after.
A schema change
Schema goes into the installer as a clean-install description. It is not a migration: existing tables fail silently when the statement runs again.
Migrating an existing environment is done by hand, and the statements go in the pull request description. Apply the migration before deploying code that names the new column, or that transaction type silently stops importing.
Some tables are not in the installer at all; they are created by the job that fills them, and a change to one of those goes there.
Related
- Verification
- Architecture
- Documentation maintenance, because a change here may owe a documentation update in the same change
Evidence
Every checklist here condenses AGENTS.md: flow steps 6, 7 and 8, and the What fails silently table. Basis: code-checked against the current implementation. AGENTS.md is the authority; this page is a routing aid and must be corrected when it drifts.
- Type
development - Status
active - Updated
2026-09-14 - Created
2026-09-13