Golden Dataset
The Acme golden dataset: how to get it onto a local instance or a stage, sign in to it, keep the shared source current, and where the deep-dive docs live.
On this page
Golden Dataset#
The golden dataset is one deterministic fixture, the Acme organization, built from a generator through the real CommandBus rather than hand-edited in a database. It does three jobs: a stable world for the E2E and integration suites, a demo company whose dates always read as "today", and enough real structure (cadences, WSJF scores, lane flow, time entries, audit history) that every report has something to show. Its source of truth is the generator in the main repository (backend/tests/golden/), driven by the ds golden CLI (cli/commands/golden.ts).
This page tells you which verb to run for which job. The full flag list is on the Command Reference; the design and operating guides live in the repository (see Where to learn more).
Fix the generator, never the rows
When golden data looks wrong — a bad value, a missing record, stale rollups — fix it in
backend/tests/golden/and rebuild. The next build truncates and regenerates the Acme org, so a hand edit to the database is silently discarded, and it never reaches the test suites, which build from scratch.
Seed a local Docker instance#
The local stack starts with schema only. Build Acme into the instance you are working in (the primary is main; a pool checkout is wt1 or wt2):
ds worktree cli main migrations run # if the schema is not applied yet
ds worktree cli main golden build # Acme + Cognito logins + a final aggregation recalc
Expect tens of minutes. The §16 assertion gate is skipped automatically on the local stack. On a pool checkout, build once, capture the result as the golden template (ds pool template refresh --from wt1), and ds pool reset <checkout> restores it in seconds from then on.
Seed a cloud stage#
ds golden seeds whatever database the ds wrapper is bound to. Which verb depends on the stage:
| Stage | Use | Why |
|---|---|---|
| Your personal stage | ds golden build, then ds golden cognito if you skipped it |
A scoped rebuild of Acme in place; other data on the stage survives. About 4 minutes against Neon |
| Your personal stage, fast | ds golden push --force-full-reset |
Restores a locally built template with pg_dump/pg_restore. Replaces every row on the stage, so only on a disposable one |
The shared dev stage (or any populated stage) |
ds golden import |
Copies Acme additively from the canonical golden source (GOLDEN_DB_CONNECTION_STRING); nothing else on the stage is touched. Re-run it to refresh |
| A stage whose Acme disappeared | ds golden refresh-stage |
import, then reanchor --to today, then verify, in one idempotent step |
| A stage whose demo dates have drifted | ds golden reanchor |
Shifts the demo's dates by one delta so it reads as today, without rebuilding; operational times (tokens, leases, countdowns) stay put. Every deployed stage also runs a nightly upkeep job (06:23 UTC) that re-dates the internal Acme demo when the stage's keep-current switch is on, set from the staff panel's sandbox page; it is off on production, and off until someone switches it on (I13885) |
| Not sure what state a stage is in | ds golden status |
Read-only: is Acme present, anchored at today, in sync with the source |
If only the follow-up legs failed (usually an expired AWS session), re-run them on their own; both are idempotent:
ds golden cognito # the Demo@123 logins
ds golden aichat # the DynamoDB AI chats
import and push refuse to run unless the checkout, the golden source and the target stage carry the same set of migrations. The usual fix is ds migrations run against your stage, then retry.
Sign in#
The build writes the users and memberships; cognito (run by build unless --skip-cognito) creates the logins. Sign in with the username, not an email, password Demo@123 for every persona:
| Username | Role |
|---|---|
acme.admin |
Admin — the full organization |
alex.rte |
The demo persona (Release Train Engineer) |
acme.owner, acme.member, acme.viewer, acme.scrummaster, acme.rte |
One per role |
On the local Docker stack acme.devstride (Admin) also exists. The Acme organization id is ac3e0000-0000-4000-8000-000000000001.
The safety model#
Golden is structurally unable to wipe a shared database:
- Scoped by default.
build,reset,enrich,reanchorandimporttouch only the Acme org's rows. There is no whole-stage truncate path behind them. - One whole-database verb.
pushdrops and restores the stage'spublicanddrizzleschemas. It requires--force-full-reset, prompts for a typed confirmation at a terminal, and is refused onprodanddev. - A protected-stage guard on every mutating verb.
prod(app.devstride.com) refuses everything.dev(app.devstride.dev, the shared staging stage) allows only the additive verbs:import,reanchor,refresh-stage,aichat,cognito. Any other stage allows everything.
The golden source, and keeping it current#
Every import, every stage refresh and every production training sandbox clones from one canonical golden source database, reached through GOLDEN_DB_CONNECTION_STRING (a shared team credential, kept in .env by ds secrets pull, never committed). It is certified against the checkout's full migration journal, so a migration that lands decertifies it until it is brought forward:
- After a migration, the cheap tier is enough:
ds golden reconcilemigrates the source, re-runs the §16 gate and re-stamps the certification in minutes. The Golden Dataset — Refresh Source workflow does this automatically after every push tomaster, once production is live at that commit. - After a generator change, only a full local rebuild helps (
reconcileexits 42 and the workflow pages the operator): build the template locally withGOLDEN_BUILD_TEMPLATE=1 GOLDEN_SCALE=full, thends golden push --target-db "$GOLDEN_DB_CONNECTION_STRING" --force-full-reset; at release time,ds golden release prepareandpublish(next bullet) do the same for you. No golden build runs in cloud CI. A "generator change" is any edit underbackend/tests/golden/except the coverage map (coverage-map.ts): the map records which tables golden seeds, not how, so a map-only edit — the line every new table must add — leaves the fingerprint unchanged and the release on the cheap path above. - Before a production release,
ds golden release checkis a mandatory local pre-ship gate: the release skill refuses to proceed without a prepared, certified archive for the exact candidate, and publishes it after the deploy is confirmed healthy. A full build is filed under a fingerprint of the generator and the migrations, so a later fix commit that changes neither keeps it, and the release can start that build early, at the release train, when the main checkout is free (ds golden release ahead, underds golden releasein the Command Reference).
The runbooks are Workflow A and B in the repository's docs/golden/stages-and-secrets.md, and the ds-golden-release skill.
Adding a table or a DynamoDB model#
Golden is meant to cover the whole product, so every organization-scoped table and every DynamoDB model needs an entry in the golden coverage map (backend/tests/golden/coverage-map.ts). Mark it seeded once the generator fills it, or notSeeded('<why it stays empty>'). A guard in the regular backend suite (golden-coverage-map.spec.ts, no golden build needed) fails when a new table or model has no entry, and when an entry names one that no longer exists. A new feature therefore cannot reach develop without a golden decision. After a full build, the §16 gate also requires at least one Acme row in every table marked seeded. Adding the entry costs the next release nothing: the coverage map is the one file under backend/tests/golden/ left out of the generator fingerprint, so a release that only adds a table takes the cheap migrate-and-recertify path; a seeded entry whose rows the source lacks is still caught by that §16 check at the next re-certification. The repository's How to change the golden dataset guide walks through the change.
Golden is a local gate, not a cloud one#
Nothing in cloud CI runs the golden suite, and no pull request ever waits on a golden check. The responsibility is the author's: a change under backend/tests/golden/** or cli/commands/golden/** triggers the golden-assertions pre-ship check (pnpm test:suite:ci:golden, the §16 gate) locally before the pull request is marked ready, a generator change triggers the full suite (pnpm test:suite:ci:golden-full, about 28 minutes), and a release runs the full suite when it touches what the suite tests (backend source, the golden suites, the test harness or the dependencies). It runs once per exact version of the code across every machine: a pass is recorded in DevStride against that code (ds verify golden-receipt), and a later run of the same code on any machine reuses it at once. A release runs it on its train snapshot during the train phase, before it holds the release clearance, so the release's own check normally finds the pass waiting. Run them yourself before shipping anything that touches the generator.
Where to learn more#
The repository's docs change with the generator, so they are linked rather than copied:
- User Guide — building, the env flags (
GOLDEN_SCALE,GOLDEN_ANCHOR,GOLDEN_KEEP_TEMPLATE), using the template-clone harness in a test, the §16 assertion gate, extending the dataset. - Stages & Secrets — the three databases, Workflow A (pull golden into your stage) and B (refresh the source), managing the credential.
- README — the doc index, the architecture and persona-tour guides, and the design corpus.
Next Steps#
- Command Reference:
ds golden— every subcommand and flag, including the training-sandbox verbs - Dockerized Worktree Development — the local stack and the checkout pool's instant resets
- Deployment — how the Refresh Source workflow fits the release pipeline