# Claude Adapter QA Matrix

This matrix covers the GH-422 child stories for Claude runtime adapter support.
It records only local contract evidence and documentation evidence. It does not
claim real Claude Code native execution or Anthropic/provider API execution.

## Evidence Summary

| Story | Scope | Evidence | Status |
| --- | --- | --- | --- |
| #432 / `GH-432-CLAUDE-ADAPTER-CONTRACT` | Claude action eligibility, skip reasons, alias policy, non-regression docs | QA handoff, release handoff, `npm run build`, `node --test test/runtime-adapters.test.js` with 51 passing tests, `git diff --check` | Pass |
| #433 / `GH-433-CLAUDE-DISPATCH-BRIDGE` | Dispatch bridge boundary, spawned/active lifecycle recording, idempotency, fallback guidance | QA handoff, release handoff, `npm run build`, `node --test test/runtime-adapters.test.js` with 54 passing tests, `git diff --check` | Pass |
| #434 / `GH-434-CLAUDE-COMPLETION-RECONCILIATION` | Strict completion validation by task, phase, role, runtime, session, and expected artifact | `runtime watch` validation tests in `test/runtime-adapters.test.js`; `npm run build`; `node --test test/runtime-adapters.test.js` with 58 passing tests | Pass |
| #435 / `GH-435-CLAUDE-GATE-PRESERVATION` | Safe workflow resume and human gate preservation regression coverage | `npm run build`; `node --test test/autonomous-workflow-cli.test.js`; `node --test test/runtime-adapters.test.js` with 59 passing tests | Pass |
| #436 / `GH-436-CLAUDE-DOCS-QA-EVIDENCE` | Documentation, QA matrix, release evidence, support-level framing | This document, `docs/runtime-adapters.md`, GH-436 QA/release handoffs, and follow-up #434/#435 evidence updates | Pass |
| #439 / `GH-439-CLAUDE-NATIVE-CALLBACK-BRIDGE` | Native callback bridge contract, fallback truthfulness, lifecycle validation | Local contract tests in `test/runtime-adapters.test.js`; `docs/runtime-adapters.md`; this matrix | In progress |

## Acceptance Criteria Matrix

| Story | Acceptance Criterion | Evidence Type | Evidence | Result | Status |
| --- | --- | --- | --- | --- | --- |
| #432 | Claude runtime action eligibility is defined for runtime, action kind, tool name, session status, safety state, and runtime filter. | Unit/contract | `.agent-workflow/handoffs/GH-432-CLAUDE-ADAPTER-CONTRACT-wfrun-1779347910261-ecc68e-qa-qa-runtime-handoff.md`; `node --test test/runtime-adapters.test.js` | QA reports dispatchable primary Claude action and checked eligibility fields. | Pass |
| #432 | Skip reasons are machine-readable and human-readable for queued, suspended, terminal, stale or unsafe, runtime mismatch, tool mismatch, unsupported runtime, unavailable native tool, and manual request. | Unit/CLI contract | GH-432 QA handoff; GH-432 developer evidence | QA reports stable reason codes and readable messages for required skipped conditions. | Pass |
| #432 | Tool alias policy documents primary `claude-code-agent` and whether `Task` is supported or deferred. | Documentation/unit | `docs/runtime-adapters.md`; GH-432 QA handoff | `claude-code-agent` is primary; `Task` is deferred/manual and skipped as `tool-mismatch`. | Pass |
| #432 | Tests cover dispatchable and non-dispatchable Claude actions without changing Codex or Cursor behavior. | Regression/unit | GH-432 QA handoff; `node --test test/runtime-adapters.test.js` with 51 passing tests | Focused runtime adapter tests passed; Codex/Cursor behavior reviewed in the same suite. | Pass |
| #432 | `docs/runtime-adapters.md` reflects only the tested support level. | Documentation review | GH-432 QA handoff; current runtime adapter docs | Docs avoid native Claude/provider API claims for GH-432. | Pass |
| #433 | Eligible `claude-agent-request` actions can be dispatched through a focused Claude bridge service or equivalent adapter boundary. | Code review/CLI unit | `.agent-workflow/handoffs/GH-433-CLAUDE-DISPATCH-BRIDGE-wfrun-1779349624692-f04dbc-qa-qa-runtime-handoff.md`; `node --test test/runtime-adapters.test.js` | QA reports dispatch result is `dispatched` through the adapter boundary. | Pass |
| #433 | Dispatch records spawned and active lifecycle states with a stable child identifier or deterministic fallback label. | CLI unit/event review | GH-433 QA handoff | QA reports one spawned event, one active heartbeat, and `claude-code-agent:<session>` fallback label coverage. | Pass |
| #433 | Repeated dispatch is idempotent and never creates duplicate lifecycle events for the same session. | CLI unit | GH-433 QA handoff | QA reports repeated dispatch keeps one spawned and one active event. | Pass |
| #433 | Unavailable or unsupported native tool paths return explicit fallback guidance and manual lifecycle commands. | CLI unit/code review | GH-433 QA handoff | QA reports skipped result includes prompt artifact, expected result artifact, and manual spawned command. | Pass |
| #433 | Tests cover successful dispatch, unavailable tool fallback, repeated dispatch idempotency, runtime mismatch, and guardrail rejection. | Automated tests | GH-433 QA handoff; `node --test test/runtime-adapters.test.js` with 54 passing tests | Required scenarios mapped to deterministic tests. | Pass |
| #434 | Completion validation checks task id, phase, role, runtime, session id, and expected result artifact path. | Watch/contract tests | `test/runtime-adapters.test.js`; `src/runtime-completion-validation.ts` | `runtime watch` validates completion against structured spawn/session metadata before recording completed. | Pass |
| #434 | Wrong-task, wrong-role, wrong-runtime, wrong-session, missing, duplicate, and unsafe-path artifacts are rejected or skipped with explicit reasons. | Watch/negative tests | `runtime watch rejects Claude completion metadata mismatches`; existing unsafe/missing/duplicate watch coverage | Mismatches are skipped with explicit reasons; unsafe paths do not create completed lifecycle events. | Pass |
| #434 | `runtime watch` records completed exactly once for a valid spawned or active Claude session. | Watch test | `runtime watch completes a valid Claude session once` | Two watch passes produce one completed lifecycle event for the Claude session. | Pass |
| #434 | Native immediate completion results follow the same validation rules when supported. | Watch/contract test | `runtime watch validates Claude native immediate completion results`; `src/runtime-completion-validation.ts` | Immediate `completionResult` payloads resolve through the same expected-artifact and artifact-metadata validator. | Pass |
| #434 | Tests cover artifact validation, duplicate completion prevention, timeout/stale behavior, and safe path handling. | Automated tests | `node --test test/runtime-adapters.test.js` with 58 passing tests | Focused runtime adapter suite covers artifact metadata validation, duplicate ignored reasons, immediate completion payloads, and existing timeout/stale/unsafe-path behavior. | Pass |
| #435 | Verified completion resumes the paused run to the next safe phase when no human gate is pending. | Runtime lifecycle tests | `runtime watch completes spawned sessions once and auto-resumes workflow`; `runtime lifecycle completion can opt out of auto-resume` | Runtime completion resumes safe non-gated work and keeps opt-out behavior. | Pass |
| #435 | `po-to-architect`, `qa-to-release`, and configured human gates remain paused until explicit approval. | Workflow CLI tests | `workflow resume holds human gates until explicit approval` | Resume now holds unapproved gates and advances only after `workflow gate-approve`. | Pass |
| #435 | Auto-dispatch never records gate approval or skips a gate. | Runtime lifecycle tests | `runtime lifecycle auto-resume does not approve human gates` | Runtime lifecycle auto-resume leaves paused work unapproved and emits no `AUTONOMOUS_GATE_APPROVED` event. | Pass |
| #435 | Tests cover `gates=none`, `gates=phase`, `gates=all`, multi-phase dispatch until idle, manual fallback recovery, and GH-421 spawn-state messaging. | CLI/runtime regression tests | `test/autonomous-workflow-cli.test.js`; `test/runtime-adapters.test.js` | Existing runtime suite covers multi-pass dispatch, queued/pending messaging, manual recovery guidance, and gate modes; #435 adds stricter unapproved-gate hold coverage. | Pass |
| #435 | Existing Codex, Cursor, generic, VS Code, Windsurf, and OpenCode behavior is unchanged or covered by regression tests. | Runtime regression tests | `test/runtime-adapters.test.js` | Runtime adapter catalog and cross-runtime parent action tests still pass. | Pass |
| #436 | Runtime adapter docs document Claude dispatch support, alias policy, fallback behavior, manual recovery commands, guardrails, and gate preservation. | Documentation review | `docs/runtime-adapters.md` | Updated in this slice. | Pass |
| #436 | QA matrix maps each GH-422 child story acceptance criterion to unit, workflow, CLI, or manual evidence. | Documentation | This file | Matrix records Pass/Pending/Deferred by criterion and evidence type. | Pass |
| #436 | Release evidence includes exact commands, pass/fail results, unsupported CI/manual verification notes, and unresolved risks. | QA handoff/evidence | GH-436 handoff under `.agent-workflow/handoffs/`; #434/#435 QA evidence and release-readiness checks | Handoffs and evidence record exact commands, pass/fail results, known unsupported Claude callback/provider claims, and residual real-transport risk. | Pass |
| #436 | Documentation does not claim native Claude execution beyond tested behavior. | Documentation review | `docs/runtime-adapters.md`; this file | Docs frame support as parent-runtime contract plus manual/runtime-owned launch. | Pass |
| #436 | Product/release review records go/no-go based on evidence and known limitations. | Review artifact | `.agent-workflow/reviews/GH-436-CLAUDE-DOCS-QA-EVIDENCE-release_manager-review.md`; #435 release-readiness gate | Release review records go with known limitations; #435 follow-up gate preservation now passes. | Pass |
| #439 | Claude parent-runtime adapter can hand off only when a supported Claude parent runtime and native callback capability are explicitly verified. | Unit/contract | `runtime parent-actions dispatches eligible Claude requests with stable lifecycle`; `runtime parent-actions returns truthful Claude native fallback outside Claude parent runtime` | Local tests simulate the verified callback contract and verify unsupported parent runtimes skip without lifecycle writes. | In progress |
| #439 | Adapter captures a native child identifier or verified callback result and records spawned and active without manual lifecycle commands. | Unit/contract | `test/runtime-adapters.test.js` Claude native dispatch test | Simulated verified bridge records one spawned event and one active heartbeat with the supplied native child id. | In progress |
| #439 | Completion reconciliation validates task id, phase, role, runtime, session id, and expected artifact before completion. | Watch/contract tests | Existing #434 watch tests in `test/runtime-adapters.test.js` | Completion still flows through the expected handoff metadata and safe path validators. | Pass |
| #439 | Unsupported environments return fallback guidance without claiming native execution. | Unit/contract/docs | `runtime parent-actions returns truthful Claude native fallback outside Claude parent runtime`; `docs/runtime-adapters.md` | Codex/non-Claude context returns skipped fallback guidance and records no spawned lifecycle event. | In progress |
| #439 | Documentation separates tested local contract, real Claude runtime proof, and unsupported CI/non-Claude contexts. | Documentation | `docs/runtime-adapters.md`; this matrix | Docs label local simulation and unsupported contexts; real Claude runtime proof remains manual QA. | In progress |

## Unsupported Or Deferred Claims

- No evidence in this slice proves that Orchestra can call Claude Code native
  Agent/Subagent tools from CI or from a non-Claude parent runtime.
- No evidence proves direct Anthropic or provider API execution for runtime
  delegation; runtime-native artifacts keep `directProviderApiAllowed=false`.
- Native immediate Claude completion is covered when represented as a
  `completionResult` payload; real callback transport remains future adapter
  work.
- #435 workflow resume and human gate preservation regression coverage now
  passes locally; real Claude Code callback transport remains outside this
  local contract matrix.
- #439 adds a truthful native callback bridge contract: non-Claude and
  callback-unavailable environments skip without lifecycle writes. Real Claude
  Code Agent/Subagent proof still requires manual QA from a Claude parent
  runtime that exposes the native callback capability.