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, reanchor and import touch only the Acme org's rows. There is no whole-stage truncate path behind them.
  • One whole-database verb. push drops and restores the stage's public and drizzle schemas. It requires --force-full-reset, prompts for a typed confirmation at a terminal, and is refused on prod and dev.
  • 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 reconcile migrates 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 to master, once production is live at that commit.
  • After a generator change, only a full local rebuild helps (reconcile exits 42 and the workflow pages the operator): build the template locally with GOLDEN_BUILD_TEMPLATE=1 GOLDEN_SCALE=full, then ds golden push --target-db "$GOLDEN_DB_CONNECTION_STRING" --force-full-reset; at release time, ds golden release prepare and publish (next bullet) do the same for you. No golden build runs in cloud CI. A "generator change" is any edit under backend/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 check is 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, under ds golden release in 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#

Powered by DevStride