# Story To Release Traceability

Open Orchestra keeps delivery traceability in `.agent-workflow/`. The goal is
to connect a backlog story to technical work, verification evidence, reviews,
and release readiness without relying on chat history.

## Product Owner Refinement

Start with a task that has a backlog item, goal, scope, acceptance criteria,
risks, and test strategy:

```bash
orchestra task add --id STORY-1 --title "..." --owner product_owner --backlog HU-1 --acceptance "criterion one,criterion two"
orchestra task update --id STORY-1 --goal "..." --scope "..." --risks "..." --test-strategy "..."
orchestra readiness --task STORY-1
```

The task record is the story anchor. Keep acceptance criteria user-visible and
avoid hiding product requirements in handoff notes.

## Developer Delivery

Before implementation, the developer reads the context bundle and records
material decisions:

```bash
orchestra context --task STORY-1 --json
orchestra decision add --task STORY-1 --owner developer --title "..." --context "..." --decision "..." --consequences "..."
```

Implementation evidence belongs on the task:

```bash
orchestra evidence add --task STORY-1 --role developer --type command --summary "unit tests passed" --command "npm test" --exit-code 0
```

## QA Verification

QA verifies acceptance criteria, regression areas, edge cases, and data setup.
Each acceptance criterion must map to evidence that proves an observable
outcome. For CLI work, assert exit code, stdout/stderr, generated files,
workflow events, or final state. For web work, assert visible user-facing state.
For API, data, DB, storage, or integration work, assert response contracts,
persisted state, side effects, sandbox/mock/contract/webhook/event/log outcomes,
or record a deferred validation with owner and rationale.
Browser automation should use Playwright evidence when the behavior is
user-facing:

```bash
orchestra playwright plan --task STORY-1
orchestra qa coverage --task STORY-1 --json
orchestra playwright evidence --task STORY-1 --kind trace --path test-results/story-1.zip --summary "acceptance flow trace"
orchestra review --task STORY-1 --role qa --result approve --findings "..." --recommendation "..."
```

Developer-to-QA handoff should include touched files, commands, known gaps, and
recommended Playwright, CLI, shell, API, integration, workflow, mobile, desktop,
data, or generated-artifact coverage. `qa coverage` maps each acceptance
criterion to `covered`, `weak`, `missing`, `deferred`, or `blocked`
using task paths, project scripts, and existing evidence; release readiness and
the `qa-release` gate surface unresolved QA automation gaps before promotion.

Generated artifacts are a first-class QA surface. When rules, skills, runtime
guidance, Markdown files, MDC files, or managed bootstrap blocks change,
evidence must assert generated paths, managed metadata, target-specific content,
refresh/drift behavior, user-content preservation, and absence of wrong-target
content. CLI evidence must assert exit code, stdout, stderr, generated
files/events, and final state. Integration evidence must include receiver-side
sandbox/mock/contract/webhook/event/log validation or an explicit deferred owner
and rationale.

Evidence summaries should name the acceptance criterion they cover or say
"covers all acceptance criteria" when a single artifact proves the full story.
Smoke and regression checks that do not map to a criterion are still useful, but
they do not count as acceptance coverage.

## Advisory Conversion

Advisory mode stores portable planning artifacts under
`.agent-workflow/advisory/`. Convert `project-task.json` into a real project
task only after the target repository and scope are confirmed.

Setup-agents imports preserve external references under
`task.externalRefs.setupAgents`, including evidence IDs, handoff IDs, acceptance
status, and contract version.

## Release Readiness

Release readiness composes task readiness, architecture, QA, risk, evidence,
handoffs, reviews, and locks:

```bash
orchestra gate --gate release-readiness --task STORY-1
orchestra release check --json
orchestra release candidate --version <version> --json
```

The release manager should only accept unresolved risks when they are recorded
as explicit reviews, decisions, or release evidence.

## Generated Reference Separation

Generated runtime files such as `AGENTS.md`, `ORCHESTRA.md`, and runtime adapter
blocks guide agents. Delivery truth remains in `.agent-workflow/` artifacts:

- `tasks.json` for backlog and ownership state.
- `decisions/` for why choices were made.
- `handoffs/` for role-to-role transfer.
- `evidence/` for command, file, screenshot, trace, video, log, or report proof.
- `reviews/` for approvals, blocks, and accepted risks.
- `releases/` for release candidate and rollback evidence.

Do not treat generated prompt text as delivery evidence unless it is explicitly
attached through `orchestra evidence add`.