Glossary & Data Model

Terms, and the "data model" of this feature — which, since it's a CI workflow, means the contracts between the workflow, the off-repo agent, GitHub, and Atlassian.

Terms

Phase — one of prepare, test, retest, fix. The single dispatch input action (.github/workflows/sandbox-qa.yml:33-42). Replaces the old review/plan/test/fix/full-auto actions.

QA gate — a deliberate pause between phases where a human edits the Jira epic or comments on tickets, and the next phase treats those edits/comments as the plan/instructions. See The Human QA Gates.

Sandbox — the per-branch live copy of Dentolize at https://<branch>.sandbox.anastawfik.com, deployed by sandbox.yml. The environment the test/retest phases drive with Playwright.

Rich seed — SEED_MODE=rich: the sandbox is populated with a demo clinic (patients, invoices, insurance, payments) and a roster of role-based logins, so test cases have realistic data. From sandbox-info.env.

Roster — the seeded users (owner, doctor1/2, receptionist1, accountant1, hrmanager1), all sharing one password. A Story's role/preconditions decide which one the agent logs in as.

Epic — the Jira epic [PR #N Quality Review] in the QA project; the QA team's workspace. Holds one Story per test case.

Story — a Jira ticket for one test case: role, preconditions, repro steps, expected result. PASS → Done; FAIL → In Progress + failed label.

Bug ticket — a Jira ticket the test phase files for a confirmed problem that wasn't covered by any Story.

Confluence page — [PR #N] <title> — Quality Review in the Docs space: the readable review plus a "living" results table.

[skip ci] — the marker on fix commits that prevents sandbox.yml from auto-redeploying; the fix phase redeploys the sandbox itself (single-slot runner). Header :19-26.

Foreground run — the agent runs inline in the job (no --detach), so job success means results are published. Contrast sandbox.yml:66, which detaches the docs agent.

Homelab runner — the self-hosted GitHub Actions runner (runs-on: [self-hosted, homelab, dentolize], :55) where these jobs and the sandbox CLI execute.

Data model — the contracts

This feature has no database. Its "schema" is a set of I/O contracts.

Contract A — dispatch input (GitHub → workflow)

action ∈ { prepare, test, retest, fix }   # default: prepare

.github/workflows/sandbox-qa.yml:33-42.

Contract B — agent outputs (sandbox-qa → workflow)

The binary writes KEY=VALUE lines to $GITHUB_OUTPUT (:64). Consumed keys:

Every key is null-guarded; the workflow degrades gracefully if any are absent.

Contract C — PR summary comment (workflow → GitHub)

Idempotent upsert keyed by the hidden marker <!-- sandbox-qa-report --> (:88, :104-114). Exactly one such comment per PR, rewritten each phase. Body shape at :88-102.

Contract D — the QA workspace (agent → Atlassian)

The epic, Stories, Bug tickets, transitions, screenshots, and Confluence page. Not implemented in this repo — produced by qa-agent/atlassian-qa.py and /opt/homelab/sandbox/bin/sandbox-qa. The workflow only links to the epic/page via Contract B. See the honesty notes in Workflow Internals.

Where each thing lives

Related workflows (context, not changed by this PR)

• sandbox.yml — deploys a sandbox on PR open/sync, destroys on close; also kicks off the detached branch-docs agent on PR open (sandbox.yml:58-66).
• sandbox-ops.yml — manual reseed, reset-data, redeploy, destroy, update-docs on a branch's sandbox.

See also

• Overview · Workflow Internals · What Changed