@jterrats/open-orchestra 1.0.8 → 1.0.10

package/docs/adoption-guide.md

@@ -51,6 +51,15 @@ orchestra review --task STORY-001 --role qa --result approve --findings "Accepta
 orchestra release check --json
 ```
 
+Do not approve workflow gates just because the CLI reached a pause. The
+`po->architect` gate requires user-validated scope, assumptions, non-goals,
+priority, acceptance criteria, and sizing context. The `qa->release` gate
+requires real implementation evidence, exact validation commands, QA findings,
+and BA/PO plus Architect review when business behavior or technical contracts
+changed. If a generated handoff says `Acceptance Criteria: none`, use the
+linked issue or task as the source of truth, record the gap, and block release
+until the missing criteria/evidence are fixed or explicitly risk-accepted.
+
 ## Concepts
 
 Open Orchestra is a local control plane. The parent runtime remains the active
@@ -79,6 +88,9 @@ orchestra workflow gate-approve --run <run-id> --gate "po->architect" --approver
 orchestra workflow run --task TEAM-001 --resume <run-id>
 ```
 
+Quote gate ids in shells so `po->architect` and `qa->release` are passed as
+literal values rather than interpreted as output redirection.
+
 Local-only provider:
 
 ```bash

package/docs/architecture-debt-inventory.md

@@ -0,0 +1,25 @@
+# Architecture Debt Inventory
+
+Open Orchestra includes a report-only architecture debt inventory for spotting files that may need future refactoring.
+
+Run it with:
+
+```sh
+npm run architecture:inventory
+```
+
+For machine-readable output:
+
+```sh
+npm run build
+node scripts/architecture-debt-inventory.js --json
+```
+
+The inventory reports:
+
+- Large files over the configured line threshold.
+- Long functions over the configured function threshold.
+- Command-facing modules that may contain orchestration logic.
+- Module-boundary candidates that mix CLI, filesystem, workflow, and domain concerns.
+
+This slice is intentionally warn-only. It does not fail CI yet because the current repository still needs threshold tuning and incremental refactor stories. Future enforcement slices can promote selected categories to CI failures once the baseline is reviewed.

package/docs/autonomous-workflow.md

@@ -372,8 +372,9 @@ Started autonomous workflow wfrun-... for task FEAT-001 [gates=phase]
 → po (product_owner) task=FEAT-001-po
   ✓ handoff → architect (...)
   ⏸ gate po→architect — review: .agent-workflow/approvals/FEAT-001-gate-po-to-architect-....md
-  Approve: orchestra workflow run --task FEAT-001 --resume wfrun-...
+  Approve: orchestra workflow gate-approve --run wfrun-... --gate "po->architect" --approver <name> --rationale "<text>"
 
+$ orchestra workflow gate-approve --run wfrun-... --gate "po->architect" --approver "product-owner" --rationale "User validated scope, assumptions, non-goals, priority, acceptance criteria, and sizing context"
 $ orchestra workflow run --task FEAT-001 --resume wfrun-...
 Resuming run wfrun-... from phase architect
 → architect (architect) task=FEAT-001-architect
@@ -384,10 +385,17 @@ Resuming run wfrun-... from phase architect
 → qa (qa) task=FEAT-001-qa
   ✓ handoff → release_manager (...)
   ⏸ gate qa→release — review: .agent-workflow/approvals/FEAT-001-gate-qa-to-release-....md
-  Approve: orchestra workflow run --task FEAT-001 --resume wfrun-...
+  Approve: orchestra workflow gate-approve --run wfrun-... --gate "qa->release" --approver <name> --rationale "<text>"
 
+$ orchestra workflow gate-approve --run wfrun-... --gate "qa->release" --approver "release-manager" --rationale "Implementation evidence, QA findings, BA/PO acceptance, and Architect review are recorded"
 $ orchestra workflow run --task FEAT-001 --resume wfrun-...
 Resuming run wfrun-... from phase release
 → release (release_manager) task=FEAT-001-release
 Workflow complete [run=wfrun-...]
 ```
+
+Gate ids should be quoted in shells. If a generated handoff says
+`Acceptance Criteria: none`, do not approve release from that handoff alone.
+Use the linked issue or task as the acceptance source, record the missing
+handoff detail as a review finding, and continue only after the gap is fixed or
+the Product Owner explicitly accepts the risk.

package/docs/claude-adapter-qa-matrix.md

@@ -0,0 +1,56 @@
+# 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 | Issue exists and remains open; no local QA handoff found for this slice | Pending |
+| #435 / `GH-435-CLAUDE-GATE-PRESERVATION` | Safe workflow resume and human gate preservation regression coverage | Issue exists and remains open; no local QA handoff found for this slice | Deferred |
+| #436 / `GH-436-CLAUDE-DOCS-QA-EVIDENCE` | Documentation, QA matrix, release evidence, support-level framing | This document, `docs/runtime-adapters.md`, GH-436 QA handoff | Pending |
+
+## 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. | Planned unit/watch tests | GitHub issue #434 | No local implementation or QA evidence reviewed in this slice. | Pending |
+| #434 | Wrong-task, wrong-role, wrong-runtime, wrong-session, missing, duplicate, and unsafe-path artifacts are rejected or skipped with explicit reasons. | Planned unit/watch tests | GitHub issue #434 | No local implementation or QA evidence reviewed in this slice. | Pending |
+| #434 | `runtime watch` records completed exactly once for a valid spawned or active Claude session. | Planned watch tests | GitHub issue #434 | No local implementation or QA evidence reviewed in this slice. | Pending |
+| #434 | Native immediate completion results follow the same validation rules when supported. | Planned contract tests | GitHub issue #434 | Native immediate completion is not claimed as supported by current evidence. | Pending |
+| #434 | Tests cover artifact validation, duplicate completion prevention, timeout/stale behavior, and safe path handling. | Planned automated tests | GitHub issue #434 | No local implementation or QA evidence reviewed in this slice. | Pending |
+| #435 | Verified completion resumes the paused run to the next safe phase when no human gate is pending. | Planned workflow tests | GitHub issue #435 | No local implementation or QA evidence reviewed in this slice. | Deferred |
+| #435 | `po-to-architect`, `qa-to-release`, and configured human gates remain paused until explicit approval. | Planned workflow tests/manual review | GitHub issue #435 | Dedicated regression evidence is still required before release claim. | Deferred |
+| #435 | Auto-dispatch never records gate approval or skips a gate. | Planned workflow tests | GitHub issue #435 | Dedicated regression evidence is still required before release claim. | Deferred |
+| #435 | Tests cover `gates=none`, `gates=phase`, `gates=all`, multi-phase dispatch until idle, manual fallback recovery, and GH-421 spawn-state messaging. | Planned CLI/workflow tests | GitHub issue #435 | No local implementation or QA evidence reviewed in this slice. | Deferred |
+| #435 | Existing Codex, Cursor, generic, VS Code, Windsurf, and OpenCode behavior is unchanged or covered by regression tests. | Planned regression tests | GitHub issue #435 | Broad cross-runtime regression evidence is still required. | Deferred |
+| #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/` | Handoff records commands and recommended validations. | Pending |
+| #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 | Pending release review for GH-436 | Needs release/product review after documentation QA. | Pending |
+
+## 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`.
+- #434 completion reconciliation hardening remains pending.
+- #435 workflow resume and human gate preservation regression coverage remains
+  deferred until its implementation and QA pass.
+

package/docs/e2e-test-batteries.md

@@ -21,35 +21,36 @@ entry points a user or CI runner actually executes.
 
 ## P0 Release-Blocking Batteries
 
-| Battery | Scope | Command | Minimum Assertions | Evidence |
-| --- | --- | --- | --- | --- |
-| Source quality | Static checks, build, unit tests, workflow validation, secret scan, security audit | `npm run precommit` | exit code 0, no leaks, no audit blockers, workflow valid | command log |
-| Local CLI onboarding | Current source CLI in `/tmp` workspaces | `ORCHESTRA_NODE_SCRIPT=$PWD/bin/orchestra.js npm run test:e2e:init` | `--version`, `init`, `status`, `validate`, first-use task, handoff, evidence, release readiness | stdout/stderr, JSON output, filesystem assertions |
-| Installed CLI onboarding | Installed or packaged CLI in `/tmp` workspaces | `npm run test:e2e:init` after installing the candidate package | same assertions as local CLI onboarding, proving the packaged binary matches source behavior | stdout/stderr, JSON output, filesystem assertions, package version |
-| Browser console | Web console task, cost, provider, delegation, recovery, evidence, workflow, accessibility, artifacts | `npm run test:e2e` | visible state, API persistence, evidence attachment, lifecycle transitions, responsive/keyboard behavior | Playwright report, screenshots/traces on failure |
-| Public site | Documentation/site navigation, docs catalog, architecture viewer, mobile fit | `npm run test:e2e` | navigation order, local docs catalog search, no raw GitHub redirect for docs, mobile content fit | Playwright report |
-| Runtime manual queue | Manual runtime delegation in a `/tmp` workspace | `npm run test:e2e:runtime` | two active sessions, third manual `spawn-request` materializes `queued`, artifact includes lifecycle commands, `runtime sessions` lists queued session | stdout/stderr, JSON output, artifact content |
-| Init refresh environments | Simulated Codex, Claude, Cursor, generic workspaces | `node --test e2e/init-refresh-environments.test.js` | missing runtime guidance files regenerate on `init --force`, user content is preserved, managed blocks are updated only inside managed ranges | filesystem diff assertions |
-| Workflow lifecycle CLI | CLI workflow run, gate, resume, QA failback, release readiness | `node --test e2e/workflow-lifecycle-cli.test.js` | task phases create handoffs, blocked QA routes back, routine gate resumes immediately, release readiness maps acceptance to evidence | JSON output, events, handoffs |
+| Battery                   | Scope                                                                                                | Command                                                             | Minimum Assertions                                                                                                                                     | Evidence                                                           |
+| ------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
+| Source quality            | Static checks, build, unit tests, workflow validation, secret scan, security audit                   | `npm run precommit`                                                 | exit code 0, no leaks, no audit blockers, workflow valid                                                                                               | command log                                                        |
+| Local CLI onboarding      | Current source CLI in `/tmp` workspaces                                                              | `ORCHESTRA_NODE_SCRIPT=$PWD/bin/orchestra.js npm run test:e2e:init` | `--version`, `init`, `status`, `validate`, first-use task, handoff, evidence, release readiness                                                        | stdout/stderr, JSON output, filesystem assertions                  |
+| Installed CLI onboarding  | Installed or packaged CLI in `/tmp` workspaces                                                       | `npm run test:e2e:init` after installing the candidate package      | same assertions as local CLI onboarding, proving the packaged binary matches source behavior                                                           | stdout/stderr, JSON output, filesystem assertions, package version |
+| Browser console           | Web console task, cost, provider, delegation, recovery, evidence, workflow, accessibility, artifacts | `npm run test:e2e`                                                  | visible state, API persistence, evidence attachment, lifecycle transitions, responsive/keyboard behavior                                               | Playwright report, screenshots/traces on failure                   |
+| Public site               | Documentation/site navigation, docs catalog, architecture viewer, mobile fit                         | `npm run test:e2e`                                                  | navigation order, local docs catalog search, no raw GitHub redirect for docs, mobile content fit                                                       | Playwright report                                                  |
+| Runtime manual queue      | Manual runtime delegation in a `/tmp` workspace                                                      | `npm run test:e2e:runtime`                                          | two active sessions, third manual `spawn-request` materializes `queued`, artifact includes lifecycle commands, `runtime sessions` lists queued session | stdout/stderr, JSON output, artifact content                       |
+| Init refresh environments | Simulated Codex, Claude, Cursor, generic workspaces                                                  | `node --test e2e/init-refresh-environments.test.js`                 | missing runtime guidance files regenerate on `init --force`, user content is preserved, managed blocks are updated only inside managed ranges          | filesystem diff assertions                                         |
+| Workflow lifecycle CLI    | CLI workflow run, gate, resume, QA failback, release readiness                                       | `node --test e2e/workflow-lifecycle-cli.test.js`                    | task phases create handoffs, blocked QA routes back, routine gate resumes immediately, release readiness maps acceptance to evidence                   | JSON output, events, handoffs                                      |
 
 ## P1 High-Risk Regression Batteries
 
-| Battery | Scope | Command | Minimum Assertions | Evidence |
-| --- | --- | --- | --- | --- |
-| Multi-squad runtime | Parallel squad delegation with queue and threshold policy | `node --test e2e/runtime-multi-squad.test.js` | independent sessions, non-blocking parent, queued sessions do not fall back to parent, completion order reconciles | JSON output, lifecycle events |
-| Acceptance evidence | CLI, API, browser, and deferred integration evidence | `node --test e2e/acceptance-evidence.test.js` | evidence maps to named acceptance criteria, deferred external validation requires owner and rationale | evidence artifacts |
-| Recovery and repair | Interrupted runs, stale locks, failed provider phases | `node --test e2e/recovery-cli.test.js` plus browser recovery coverage | recovery detects issue, repair requires confirmation, repaired state is observable | JSON output, before/after state |
-| Docs/site content source | Site content generated from docs and manifest | `npm run site:build && npm run test:e2e -- --grep docs` | docs render as human-friendly catalog, no markdown-only dead ends, search works | Playwright report |
-| Security-sensitive operations | File paths, shell execution, web writes, secrets, telemetry redaction | `node --test e2e/security-boundaries.test.js` | path traversal blocked, unsafe writes rejected, secret-like data redacted, no raw stack traces | command/API evidence |
+| Battery                        | Scope                                                                 | Command                                                               | Minimum Assertions                                                                                                                                                     | Evidence                                                     |
+| ------------------------------ | --------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Multi-squad runtime            | Parallel squad delegation with queue and threshold policy             | `node --test e2e/runtime-multi-squad.test.js`                         | independent sessions, non-blocking parent, queued sessions do not fall back to parent, completion order reconciles                                                     | JSON output, lifecycle events                                |
+| Acceptance evidence            | CLI, API, browser, and deferred integration evidence                  | `node --test e2e/acceptance-evidence.test.js`                         | evidence maps to named acceptance criteria, deferred external validation requires owner and rationale                                                                  | evidence artifacts                                           |
+| Recovery and repair            | Interrupted runs, stale locks, failed provider phases                 | `node --test e2e/recovery-cli.test.js` plus browser recovery coverage | recovery detects issue, repair requires confirmation, repaired state is observable                                                                                     | JSON output, before/after state                              |
+| Docs/site content source       | Site content generated from docs and manifest                         | `npm run site:build && npm run test:e2e -- --grep docs`               | docs render as human-friendly catalog, no markdown-only dead ends, search works                                                                                        | Playwright report                                            |
+| Security-sensitive operations  | File paths, shell execution, web writes, secrets, telemetry redaction | `node --test e2e/security-boundaries.test.js`                         | path traversal blocked, unsafe writes rejected, secret-like data redacted, no raw stack traces                                                                         | command/API evidence                                         |
+| Ollama provider-backed runtime | Local OpenAI-compatible Ollama provider route in a `/tmp` workspace   | `npm run test:e2e:runtime:ollama`                                     | `model connect --provider ollama`, provider-backed developer phase, OpenAI-compatible request shape, provider provenance, no runtime subagent credentials in artifacts | stdout/stderr, JSON output, mock provider request, event log |
 
 ## P2 Extended Confidence Batteries
 
-| Battery | Scope | Command | Minimum Assertions | Evidence |
-| --- | --- | --- | --- | --- |
-| Tracker and GitHub sync | Issue import/export and close readiness | opt-in CI job with network credentials | labels, comments, close gate, release readiness, no secret exposure | sanitized logs |
-| Sonar quality loop | Local or remote Sonar import and release gate mapping | configured Sonar workflow or local compose job | insights imported, release readiness reflects quality gate, unavailable token is explicit | artifact import report |
-| Provider-backed delegation | OpenAI, Gemini, Ollama, Claude/Cursor runtime bridges | opt-in provider E2E | budget checks, rate-limit/backpressure, lifecycle events, no direct API when disallowed | redacted provider provenance |
-| Package release dry run | npm package contents and release check | `npm pack --dry-run --json && orchestra release check --json` | generated/private state excluded, version/tag policy valid, release readiness complete | package list, release report |
+| Battery                    | Scope                                                 | Command                                                       | Minimum Assertions                                                                        | Evidence                     |
+| -------------------------- | ----------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------- |
+| Tracker and GitHub sync    | Issue import/export and close readiness               | opt-in CI job with network credentials                        | labels, comments, close gate, release readiness, no secret exposure                       | sanitized logs               |
+| Sonar quality loop         | Local or remote Sonar import and release gate mapping | configured Sonar workflow or local compose job                | insights imported, release readiness reflects quality gate, unavailable token is explicit | artifact import report       |
+| Provider-backed delegation | OpenAI, Gemini, Ollama, Claude/Cursor runtime bridges | opt-in provider E2E                                           | budget checks, rate-limit/backpressure, lifecycle events, no direct API when disallowed   | redacted provider provenance |
+| Package release dry run    | npm package contents and release check                | `npm pack --dry-run --json && orchestra release check --json` | generated/private state excluded, version/tag policy valid, release readiness complete    | package list, release report |
 
 ## Required `/tmp` Fixture Patterns
 
@@ -83,6 +84,16 @@ the packaging/install path is wrong.
 5. Add focused security and acceptance-evidence E2E only where unit tests cannot
    prove the user-visible contract.
 
+## Opt-In Provider Runtime Batteries
+
+Provider-backed runtime batteries are not part of default CI because they may
+need local services or paid credentials. They must still be deterministic enough
+to run on a developer machine. `npm run test:e2e:runtime:ollama` uses a local
+OpenAI-compatible mock endpoint by default to prove the Ollama adapter contract,
+workflow provenance, and no-secret behavior without requiring a real Ollama
+daemon. A separate real-model smoke can be run with `ORCHESTRA_OLLAMA_SMOKE=1`
+when validating a local model installation.
+
 ## Definition Of Done
 
 An E2E battery is complete only when it has:

package/docs/orchestra-mvp.md

@@ -109,6 +109,14 @@ when release readiness passes. If release readiness is blocked, closure
 requires `--accepted-risk <text>`. `--dry-run --json` prints planned commands
 without writing local tasks, comments, or issue state.
 
+GitHub comment payloads are file-backed. Generated commands use
+`gh issue comment --body-file <payload-file>` for new comments and
+`gh api --input <payload-json-file>` for comment updates instead of embedding
+multiline markdown after `--body` or `-f body=...`. Agents should keep this
+pattern for any copied or derived command: write markdown or JSON payload bytes
+to a temporary file, pass the file path as an argv value, and avoid logging the
+payload contents when command execution fails.
+
 The transport boundary is intentionally tracker-agnostic. The local CLI can
 execute `gh` because it is a child process with stable arguments. MCP-backed
 trackers such as GitHub MCP, Jira, Bitbucket, GitLab, or a custom work tracker
@@ -267,6 +275,19 @@ Release go/no-go:
   `macos-latest`, and `windows-latest`.
 - Confirm `Create release tag`, site publish, and npm publish workflows are
   successful for the intended release commit.
+- Confirm the npm publish workflow authenticates with either a maintainer
+  `NPM_TOKEN` that has read-write access plus CI 2FA bypass for
+  `@jterrats/open-orchestra`, or npm Trusted Publishing/OIDC configured with
+  organization/user `jterratsdev`, repository `open-orchestra`, workflow
+  filename `publish-npm.yml`, and no environment. If npm returns `404 Not Found`
+  during publish for an existing scoped package, treat it as a token or scope
+  permission failure until proven otherwise; do not print token values in logs
+  or evidence. If `npm whoami` returns `E401 Unauthorized`, regenerate the
+  GitHub Actions `NPM_TOKEN` secret from the npm maintainer account before
+  rerunning publish. If `npm publish` returns `EOTP`, the token is valid but
+  cannot bypass 2FA; switch to a granular token with bypass 2FA enabled or run
+  `publish-npm.yml` with `auth_mode=trusted` after configuring npm Trusted
+  Publishing for the package.
 
 Support diagnostics:
 

package/docs/release-test-matrix.md

@@ -35,6 +35,28 @@ If the remote tag already exists, do not move it. Use the next patch or
 prerelease version unless an explicit break-glass release decision documents why
 manual intervention is required.
 
+The npm publish workflow supports two authentication modes:
+
+- `auth_mode=token`: requires `NPM_TOKEN` from an npm account with read-write
+  access to `@jterrats/open-orchestra` and CI publish permission that can bypass
+  2FA.
+- `auth_mode=trusted`: uses npm Trusted Publishing/OIDC. Configure the package
+  in npm with organization/user `jterratsdev`, repository `open-orchestra`,
+  workflow filename `publish-npm.yml`, and no environment before running this
+  mode.
+
+A `404 Not Found` response on `PUT
+https://registry.npmjs.org/@jterrats%2fopen-orchestra` for an existing scoped
+package usually means the token is missing, was generated by a user that is not
+a package maintainer, or lacks publish permission for the scope. `EOTP` means
+the token is accepted but cannot bypass 2FA for CI publishing; use a granular
+token with bypass 2FA enabled or switch to Trusted Publishing. The workflow
+validates `npm whoami` and scoped package access before token-based publishing
+so permission failures are visible without exposing the token.
+If the preflight fails at `npm whoami` with `E401 Unauthorized`, regenerate
+`NPM_TOKEN` from the npm maintainer account and store the raw token value as a
+GitHub Actions secret.
+
 ## Required Environments
 
 - `ubuntu-latest` with Node `>=22` and npm.

package/docs/runtime-adapters.md

@@ -28,8 +28,9 @@ packet:
   approvals stay inside Codex; Orchestra renders briefs and packets only.
 - `claude-cli`: use the current Claude Code session. Orchestra renders the
   packet and the Claude parent launches it with the native Agent/Subagent tool
-  when available; `Task` is treated as a legacy alias if that is what the
-  runtime exposes.
+  when available. The tested auto-dispatch eligibility contract recognizes
+  `claude-code-agent` as the primary tool; `Task` is documented as a deferred
+  legacy/manual alias and is skipped as `tool-mismatch` by auto-dispatch.
 - `cursor-cli`: use the current Cursor runtime. Orchestra renders the packet
   and the Cursor parent launches it as a Background Agent so the current chat
   remains usable while the child works.
@@ -161,7 +162,10 @@ orchestra runtime session --session STORY-001:claude-cli --action suspend --json
 orchestra runtime session --session STORY-001:claude-cli --action resume --json
 orchestra runtime session --session STORY-001:claude-cli --action cancel --json
 orchestra runtime spawn-request --task STORY-001 --role developer --runtime codex-cli --json
+orchestra runtime parent-actions --task STORY-001 --json
+orchestra runtime parent-actions --task STORY-001 --dispatch --until-idle --runtime codex-cli --timeout 5m --idle-timeout 10s --json
 orchestra runtime spawn-lifecycle --session STORY-001:manual:developer:codex-cli --status spawned --agent-id <runtime-agent-id> --json
+orchestra runtime watch --task STORY-001 --once --json
 ```
 
 The matching local APIs are `GET /api/runtime/sessions`,
@@ -172,27 +176,131 @@ failed, or timed-out events so the parent runtime can reconcile claimed work,
 spawned agent ids, stale sessions, and handoff state without inventing a second
 source of truth.
 
-Spawn request JSON includes `parentRuntimeAction`, a structured instruction for
-the active parent runtime. Codex receives `kind=codex-spawn-agent` with
-`tool=spawn_agent`; Claude receives `kind=claude-agent-request` with
-`tool=claude-code-agent`; Cursor receives `kind=cursor-background-agent` with
-`tool=cursor-background-agent`. The action points to the prompt artifact,
-expected result artifact, ownership paths, allowed commands, and lifecycle
-commands. It does not include secrets or direct provider credentials.
+Spawn request JSON and `runtime parent-actions` include `parentRuntimeAction`, a
+structured instruction for the active parent runtime. Codex receives
+`kind=codex-spawn-agent` with `tool=spawn_agent`; Claude receives
+`kind=claude-agent-request` with `tool=claude-code-agent`; Cursor receives
+`kind=cursor-background-agent` with `tool=cursor-background-agent`. The action
+points to the prompt artifact, expected result artifact, ownership paths,
+allowed commands, and lifecycle commands. It does not include secrets or direct
+provider credentials.
+
+Pending parent actions also include structured `eligibility` metadata. The
+metadata records the checked runtime, action kind, tool name, session status,
+runtime filter when supplied, and safety state. Dispatchable actions report
+`status=dispatchable`; skipped actions include machine-readable reason codes
+and operator-readable messages. Current skip codes are `already-dispatched`,
+`queued`, `suspended`, `terminal`, `stale-or-unsafe`, `runtime-mismatch`,
+`tool-mismatch`, `unsupported-runtime`, `unavailable-native-tool`, and
+`manual-request`.
+
+When `workflow run` pauses with a pending parent runtime action, parent agents
+have two supported paths:
+
+- Manual inspection: run `runtime parent-actions --task <id> --json`, inspect
+  each requested action, call the active runtime's native tool, then record
+  `runtime spawn-lifecycle` with the returned child id.
+- Auto-dispatch: run
+  `runtime parent-actions --task <id> --dispatch --until-idle --runtime <runtime-id>`.
+  The dispatcher repeatedly inspects pending parent actions, dispatches only
+  safe actions for the active runtime, records spawned and active lifecycle
+  events with stable runtime child ids or deterministic fallback labels, applies
+  `runtime watch` completions when expected handoff artifacts appear, resumes
+  paused workflow runs, and continues across later phases until idle or timeout.
+
+The auto-dispatch loop is bounded by `--timeout`, `--idle-timeout`, and
+`--interval`, so it never polls forever. It skips queued actions, suspended
+sessions, terminal sessions, stale or unsafe actions, runtime mismatches,
+already-dispatched sessions, unsupported runtimes, unavailable native tools,
+manual requests, and tool mismatches. Skipped actions include fallback guidance
+with the prompt artifact, expected result artifact, and manual lifecycle
+commands so a human parent runtime can safely continue without provider API
+access. This keeps the boundary explicit: Orchestra emits auditable actions and
+lifecycle commands; the active parent runtime executes native tools such as
+Codex `spawn_agent`, and the dispatcher only consumes actions that are safe for
+the runtime declared on the command line. For Claude, the tested dispatch
+contract accepts `claude-agent-request` with `tool=claude-code-agent`, records
+`spawned` and `active` lifecycle states with a deterministic
+`claude-code-agent:<session>` label when no native child id is available, and
+remains idempotent across repeated dispatch attempts. Orchestra does not call
+Claude Code, Anthropic APIs, or another provider API.
+
+Runtime lifecycle watching is adapter-driven. Each inspected session reports a
+`watcher` object with adapter id, detection mode, support level, fallback
+behavior, and the reason a native callback is unavailable. `codex-cli`,
+`claude-cli`, and `cursor-cli` currently reconcile completion through explicit
+parent lifecycle events and then fall back to bounded artifact inspection.
+`generic-runtime`, unknown runtime ids, and runtimes without declared callbacks
+use the same artifact fallback directly. Event-driven callbacks should only be
+used when the selected watcher adapter declares native support; otherwise
+`runtime watch` performs bounded inspection of the expected handoff artifact.
+
+## Claude Adapter Support Level
+
+Claude support is currently a parent-runtime dispatch and lifecycle contract,
+not proof that Orchestra can invoke Claude Code or Anthropic APIs by itself.
+The tested local behavior covers:
+
+- Dispatch support: eligible `claude-agent-request` actions for `claude-cli`
+  with `tool=claude-code-agent` can be consumed by
+  `runtime parent-actions --dispatch --runtime claude-cli`. The dispatch path
+  records `spawned` and `active` lifecycle state with a stable child identifier
+  or deterministic `claude-code-agent:<session>` fallback label.
+- Alias policy: `claude-code-agent` is the only auto-dispatchable Claude tool
+  name in the tested contract. `Task` is a legacy/manual alias and is skipped
+  as `tool-mismatch`; accepting it in auto-dispatch requires new tests and
+  documentation.
+- Fallback behavior: skipped, unsupported, unsafe, stale, queued, suspended,
+  terminal, mismatched, or unavailable actions return structured eligibility
+  metadata, fallback guidance, prompt artifact, expected result artifact, and
+  manual lifecycle commands. Fallback never runs the phase in the parent agent
+  silently and never switches to direct provider APIs.
+- Guardrails: dispatch is bounded by runtime guardrails, runtime filters,
+  session status, safety state, action kind, tool name, and stale-session
+  checks. It preserves `directProviderApiAllowed=false` for runtime-native
+  delegation artifacts.
+- Completion reconciliation: current tested support relies on explicit
+  lifecycle events and bounded expected-artifact inspection. GH-434 tracks
+  stricter validation of task id, phase, role, runtime, session id, and safe
+  expected artifact path before a Claude session is marked complete.
+- Gate preservation: auto-dispatch must not approve or skip human gates. GH-435
+  tracks the dedicated regression suite for safe workflow resume across
+  `gates=none`, `gates=phase`, `gates=all`, multi-phase dispatch, and manual
+  fallback recovery.
+
+Manual recovery for a skipped or unavailable Claude action:
+
+```bash
+orchestra runtime parent-actions --task <id> --json
+orchestra runtime spawn-request --task <id> --role <role> --runtime claude-cli --json
+orchestra runtime spawn-lifecycle --session <session-id> --status spawned --agent-id <claude-child-id-or-label> --json
+orchestra runtime spawn-lifecycle --session <session-id> --status active --agent-id <claude-child-id-or-label> --json
+orchestra runtime watch --task <id> --once --json
+orchestra workflow run --task <id> --resume <run-id>
+```
+
+Only run the lifecycle commands after the parent Claude Code session has
+actually launched or taken ownership of the rendered prompt artifact. If no
+child id is returned by the runtime, use a stable operator label and keep the
+expected handoff artifact path from the spawn request.
 
 ## Native Background Agent Notes
 
 Claude Code and Cursor do not need Orchestra to call vendor APIs directly.
 They need a precise packet and lifecycle hooks:
 
-- Claude Code: render `runtime spawn-request`, then launch the packet from the
-  parent Claude session with the native Agent/Subagent tool. If the local
-  Claude runtime exposes `Task` as the tool name, treat it as the compatible
-  legacy alias. Record the returned child id or role label through
-  `runtime spawn-lifecycle`.
+- Claude Code: render `runtime spawn-request`, then manually launch the packet
+  from the parent Claude session with the native Agent/Subagent tool. The
+  primary tested tool name is `claude-code-agent`. `Task` is deferred as a
+  legacy/manual alias and is not auto-dispatchable in GH-432; auto-dispatch
+  reports it as `tool-mismatch`. Record the returned child id or role label
+  through `runtime spawn-lifecycle`.
 - Codex: render `runtime spawn-request`, read `parentRuntimeAction`, and call
   the parent `spawn_agent` tool with the prompt artifact as the role-scoped
-  assignment. Keep the child detached unless the parent is blocked.
+  assignment. In workflow auto-consumer mode, use
+  `runtime parent-actions --dispatch --until-idle --runtime codex-cli` to
+  discover and consume safe actions after the run pauses. Keep the child
+  detached unless the parent is blocked.
 - Cursor: render `runtime spawn-request`, then launch it as a Cursor Background
   Agent. Background work should stay detached from the current chat and report
   lifecycle state back to Orchestra before the workflow is resumed.
@@ -245,6 +353,22 @@ parent-agent fallback reason. `subagents` requires runtime-native support and
 fails fast if the runtime cannot satisfy it. `single-agent` forces the parent
 agent path and records that choice in phase provenance.
 
+When no task or role executor is configured and the default executor is
+`generic-runtime`, `auto` and strict `subagents` mode infer the active runtime
+from `OPEN_ORCHESTRA_ACTIVE_RUNTIME`, known parent-runtime environment markers,
+or managed runtime bootstrap files. Codex maps to `codex-cli`, Claude maps to
+`claude-cli`, Cursor maps to `cursor-cli`, Windsurf maps to `windsurf-agent`,
+and VS Code maps to `vscode-agent`.
+
+Explicit selections always take precedence in this order: `--runtime`, task
+override, role override, then `runtimePolicy.defaults.executor`. Automatic
+inference never rewrites `.agent-workflow/config.json`; it only affects the
+current planning decision. Set `workflow.phaseExecutionMode` to `single-agent`
+or configure `runtimePolicy.defaults.executor` to override inference for
+deterministic local or CI runs. If `OPEN_ORCHESTRA_ACTIVE_RUNTIME` names an
+unknown runtime, workflow planning fails with supported values and the same
+override options instead of requiring hidden config edits.
+
 Subagent spawning is fully asynchronous by default. A spawn request returns the
 `sessionId`, request artifact, prompt artifact, expected result artifact, status,
 next lifecycle commands, and quality warnings, then the parent agent should
@@ -331,3 +455,19 @@ orchestra runtime sessions --task <id> --json
 orchestra runtime spawn-lifecycle --session <id> --status completed --agent-id <id> --json
 orchestra model providers --json
 ```
+
+## Ollama E2E
+
+The Ollama adapter has an opt-in E2E battery that runs in a temporary workspace
+and uses a local OpenAI-compatible endpoint controlled by the test:
+
+```bash
+npm run test:e2e:runtime:ollama
+```
+
+The test configures `model connect --provider ollama`, runs a developer phase
+through provider-backed execution, validates the request body sent to
+`/v1/chat/completions`, and checks model provenance events. It intentionally
+does not require a real Ollama daemon, so default CI and local development do
+not degrade when Ollama is unavailable. Use `ORCHESTRA_OLLAMA_SMOKE=1` for a
+separate real-model smoke check.