Release & UAT Evidence
Detailed evidence for the release lifecycle — the stabilization-and-acceptance
stage each release goes through once the phases in its scope have sealed. This
engagement has one release per phase’s UAT round: P1 (Phase 1’s round, run while
Phase 2 is built) and P2 (the final round). The compact summary state lives in
.forge/tracker.yaml under the top-level releases: list and uat_issues:
collection; this directory holds the detail the tracker points at.
This mirrors the established split: tracker is the control plane (status, gates,
what’s blocking), evidence files are the data plane (what was tested, what came
back, the proof). See .claude/rules/tracker.md → “Release & UAT Lifecycle”
for the lifecycle vocabulary, the three ASK-enforced gates (entry / handover /
sign-off), and the UAT-issue triage routing.
Per-release layout
Every release’s evidence lives under .forge/release/<id>/ (<id> = the
release’s id in releases:, e.g. P1):
.forge/release/
├── README.md # this file
├── _TEMPLATE-cycle-plan.md # copy → <id>/RC-n-plan.md / <id>/UC-n-plan.md
├── _TEMPLATE-cycle-report.md # copy → <id>/RC-n-report.md / <id>/UC-n-report.md
├── _TEMPLATE-uat-issues.md # copy → <id>/uat-issues.md (one per release)
└── P1/ # one directory per release id (P1, P2)
├── RC-1-plan.md # regression cycle plan
├── RC-1-report.md # regression cycle report
├── UC-1-plan.md # UAT cycle plan
├── UC-1-report.md # UAT cycle report (written when the cycle completes)
├── uat-issues.md # prose home for this release's UAT issues (UAT-NNN sections)
└── evidence/
├── RC-1/
│ ├── FLOW-001.md # per-flow evidence (operator, env, steps, result)
│ └── FLOW-002.md
└── UC-1/
└── FLOW-003.md
Conventions
- Cycle ids:
RC-n(regression, internal) andUC-n(UAT, client-executed) — distinct fromUAT-NNNissue ids to avoid visual collision. Both are numbered across the engagement, not restarted per release, soP2’s first cycles followP1’s last. The tracker’sreleases[].cycles[].plan/.reportfields point at the matching files here. - One
uat-issues.mdper release, joined to the tracker’suat_issues:collection byid(thebugs.mdprose-home pattern). Structured metadata (kind, status, bug_ref, blocking, …) stays in the tracker; prose lives here. - Evidence is mandatory for claims. Every cycle marked
passedand everymanual/exploratoryflow markedpassedmust point at an evidence file underevidence/<cycle-id>/. No self-approved “all flows validated” — same doctrine as the gate-evidence rule. Automatede2eflows may cite the test run / report instead of a hand-written evidence file. - Archive on sign-off. When a release is
signed-off, its<id>/directory is retained as the historical record (it does not get deleted); the next phase’s release opens its own<id>/directory.
What does NOT live here
- Structured release/cycle/issue state →
.forge/tracker.yaml(releases:,uat_issues:). - Routed defects → the
bugs:collection +.forge/bugs.md(a UAT defect keeps abug_reflink; its fix detail lives inbugs.md, not here). - Per-feature/per-wave test counts → the existing
.forge/plans/<ticket>/<ticket>-test-stats.jsonland*-test-report.md(regression cycles reference these, they do not regenerate them).