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).
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.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.
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 |
| 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.
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.
Golden is structurally unable to wipe a shared database:
build, reset, enrich, reanchor and import touch only the Acme org's rows. There is no whole-stage truncate path behind them.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.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.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:
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.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. No golden build runs in cloud CI.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.The runbooks are Workflow A and B in the repository's docs/golden/stages-and-secrets.md, and the ds-golden-release skill.
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. The repository's How to change the golden dataset guide walks through the change.
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 every release runs the full suite once. Run them yourself before shipping anything that touches the generator.
The repository's docs change with the generator, so they are linked rather than copied:
GOLDEN_SCALE, GOLDEN_ANCHOR, GOLDEN_KEEP_TEMPLATE), using the template-clone harness in a test, the §16 assertion gate, extending the dataset.ds golden — every subcommand and flag, including the training-sandbox verbsDockerized Worktree Development
Run isolated, no-AWS DevStride instances at once — one per git worktree, each with its own database and test containers — and share a machine's fixed checkout pool (main, wt1, wt2) with leases, instant resets, client mode and cloud mode.
Deployment
How DevStride actually ships to dev and prod: a merge is the deploy, through Seed. The one deploy command, ds seed deploy, is for a deliberate redeploy.