Task: Write the DQ artefact guide
Table of Contents
This page documents a task in the Bring every DQ artefact table onto the canonical model story. It captures the goal, current status, acceptance, and any notes or results.
1. Goal
A developer adding a DQ artefact reads one page and follows one way, and can tell a legacy pattern from the canonical one.
2. Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | Bring every DQ artefact table onto the canonical model |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-10-11 |
3. Acceptance
- The page names the canonical way, the pipeline and a checklist.
- The page names each legacy pattern and the task that retires it.
4. Plan
Trace the pipeline in the code (the archetype, the dataset and bundle upserts, the publication workflow, each service's publish handler and SQL function), then write one page that states the one way, with a checklist and the legacy patterns, and point the entity skill at it.
5. Measurements
Every number this task claims about a tree, with the command that produced it
and the commit it was measured at. A number without both is not a measurement,
because a clean-up record describes a tree and trunk moves under a branch: a
consumer count, a gate's component count and a suite's size all change with no
code changing, and the reader of a bare number cannot tell which tree it came
from. Where the raw output matters, put it in an evidence/ file beside the
task and name that file in the Command column.
| What | Value | Command | Commit |
|---|---|---|---|
6. Notes
7. Test Scenarios
Manual QA scenarios (scaffolded via compass add test_scenario)
that verify this task. Link
new ones here as they're created; the scenario doc itself links back
via its "Verifies task" field.
| Scenario | State | Notes |
|---|---|---|
8. PRs
| PR | Title |
|---|---|
| #3190 | [doc] Write the DQ artefact guide |
9. Review
| # | Comment summary | File | Decision | Notes |
|---|---|---|---|---|
| 1 | PR #3190: the undecided group reads as a pattern to avoid | dq_artefacts.org | Accepted | Named Undecided, with a sentence above the table saying DQ-owned models follow the one way. |
| 2 | PR #3190: name the command that regenerates the SQL schema | dq_artefacts.org | Accepted | Step 3 gives the compass codegen command. |
| 3 | PR #3190: say what replace_all does to rows other datasets wrote | dq_artefacts.org | Accepted | The contract says the function states its close scope, and says so in a comment when it is wider than the dataset. |
| 4 | PR #3190: the clock rule sits only in the contract | dq_artefacts.org | No change | The reviewer agrees the checklist covers it. |
10. Result
Shipped DQ artefacts, ordered by the Data storage structure note. It states:
- the one way: the owning model's artefact flag, with
* Artefact columnsonly when the staging shape differs, and no DQ model or stack for the artefact; - the pipeline from the generated table through the hand-written includes and drop script, the seeded dataset, the artefact type, the bundle, the dependencies, the subject and handler, to the publish function and its test;
- the publish function's contract: signature, modes, idempotence, the clock for closing rows, the system-tenant refusal and the entity-writes baseline;
- a checklist, and the four legacy patterns with the task that retires each.
Two facts the code shows and no page said before: the publication orders
datasets by declared dependencies only, not by bundle display order; and the
drop scripts and dq_create.sql includes are written by hand for every
artefact. The compass-codegen-add-entity skill now says to stage an entity
from its own model and links the page.