From 4d2501b44f3e44bdd1777e040372262b2ab053d9 Mon Sep 17 00:00:00 2001 From: Jarvis Jr Hermes Date: Fri, 25 Sep 2026 09:16:02 +0000 Subject: [PATCH] docs: standardize UAT repository workflows --- SKILL.md | 22 ++++++++- references/journey-repository-contract.md | 55 +++++++++++++++++------ 2 files changed, 62 insertions(+), 15 deletions(-) diff --git a/SKILL.md b/SKILL.md index f9f76ed..22ea7c0 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,7 +1,7 @@ --- name: corp-v1-channel-uat description: Use when validating a deployed Corp v1 environment through UAT journeys. -version: 1.0.0 +version: 1.1.0 author: Hermes Agent license: MIT metadata: @@ -50,6 +50,26 @@ If any identity is mutable, missing, or contradictory, record `BLOCKED` rather t 6. Rerun the affected journey set after a verified redeployment. 7. Hand a `UAT_PASSED` or `UAT_FAILED` verdict to Releases without implying release approval. +## Required E2E repository pipeline + +Every project UAT repository uses two Gitea Actions workflows: + +```text +non-default branch push +└── CI / Change Validation + ├── repository validation for every exact pushed commit + └── smoke journeys only when that commit is an open PR head + +merge to the default `test` branch +└── UAT / Integrated Regression + ├── repository validation + ├── smoke journeys + ├── complete regression journeys + └── immutable deployment-tuple evidence +``` + +Use one change workflow for both pre-PR branches and PR heads. A PR-open or PR-reopen event adds the first smoke-bearing run. Do not subscribe that workflow to `pull_request.synchronize`; later branch pushes are the single trigger and classify whether the exact commit is an open PR head. Cancel superseded runs for the same branch. Never run full regression on a PR, and never treat smoke as complete UAT. The integrated workflow runs only for the exact commit pushed to `test`, fails closed when its frozen deployment inputs are missing or unhealthy, and does not deploy or publish application artifacts. + ## UAT verdicts These verdicts are acceptance dimensions; they do not replace the project's canonical Task status: diff --git a/references/journey-repository-contract.md b/references/journey-repository-contract.md index 14542a1..6022a06 100644 --- a/references/journey-repository-contract.md +++ b/references/journey-repository-contract.md @@ -1,29 +1,56 @@ # Journey repository contract -The UAT repository is a standalone pnpm project. It contains no Kubernetes/Helm/Argo CD manifests and no application implementation. +The UAT repository is a standalone pnpm/Playwright project. It contains no Kubernetes, Helm, Argo CD, application implementation, image publication, or deployment logic. -Required baseline: +## Required baseline ```text -journeys/ - smoke/ - regression/ -fixtures/ -helpers/ -playwright.config.ts +applications/functional/ +packages/journeys/ +packages/testing/ +packages/evidence/ +artifacts/.gitkeep package.json pnpm-lock.yaml +pnpm-workspace.yaml Taskfile.yml -.gitea/workflows/validate.yaml +.gitea/workflows/change-validation.yaml +.gitea/workflows/integrated-regression.yaml ``` -Rules: +A smaller standalone repository may keep `journeys/`, `fixtures/`, `helpers/`, and `playwright.config.ts` at the root. The responsibility boundaries and two-workflow contract remain the same. + +## Journey rules - Stable journey IDs appear in test titles and evidence. - `UAT_BASE_URL` is required; no production-looking default is embedded. -- Authentication is loaded from runtime secrets and never persisted in storage-state files committed to Git. +- Authentication is loaded from runtime secrets and never persisted in committed storage-state files. - Retries are explicit and low; a retry cannot turn a flaky first failure into an undisclosed pass. - Failure evidence includes trace and screenshot; video is opt-in when data handling permits it. -- CI validates types, lint, journey discovery, and a non-network contract test. Environment execution is a separately authorized job. -- Taskfile is the human/automation entry point and delegates to package scripts. -- The repository README documents local execution, evidence locations, environment variables by name only, and failure classification. +- Taskfile is the human and automation interface and delegates to package scripts. +- The README documents local execution, evidence locations, environment-variable names, failure classification, and workflow behavior. + +## Gitea Actions contract + +```text +non-default branch push +└── CI / Change Validation + ├── formatting, linting, type checks, contract tests, journey discovery, build when applicable + └── smoke journeys only when the exact commit is an open PR head + +PR opened or reopened +└── CI / Change Validation + ├── the same repository validation + └── smoke journeys + +push to test after merge +└── UAT / Integrated Regression + ├── exact integrated-commit validation + ├── smoke journeys + ├── complete regression journeys + └── deployment-bound evidence validation and upload +``` + +Use one change workflow rather than separate branch and PR workflow files. It subscribes to non-default `push` plus `pull_request` `opened` and `reopened`, but not `synchronize`; later branch pushes are the single trigger. The workflow detects whether the exact pushed commit is an open PR head and conditionally adds smoke. Cancel superseded runs for the same branch and expose one required aggregate result. + +The integrated workflow runs only on `push` to `test`. It requires an exact frozen deployment tuple, healthy synchronized Argo CD state, explicit non-production base URL, and runtime-only authentication when the regression set requires it. Missing or contradictory inputs fail closed. Smoke is not complete UAT, and full regression does not run on a PR. -- 2.54.0