@jterrats/open-orchestra 1.0.9 → 1.0.10

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.
@@ -164,6 +165,7 @@ orchestra runtime spawn-request --task STORY-001 --role developer --runtime code
 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`,
@@ -183,6 +185,15 @@ 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:
 
@@ -192,29 +203,98 @@ have two supported paths:
 - 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 lifecycle events with
-  dispatcher session ids, applies `runtime watch` completions when expected
-  handoff artifacts appear, resumes paused workflow runs, and continues across
-  later phases until idle or timeout.
+  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, runtime mismatches, unavailable runtimes, manual/unsupported action
-kinds, and tool mismatches. 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.
+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. In workflow auto-consumer mode, use

package/docs/sonar-quality-gates.md

@@ -62,6 +62,35 @@ gate status. If the scanner can upload analysis but the wait step fails with
 `Project not found`, update the `SONAR_TOKEN` permissions or keep
 `SONAR_QUALITY_GATE_WAIT` unset until the token can read the project.
 
+Before scanner execution, CI runs:
+
+```bash
+node bin/orchestra.js sonar preflight \
+  --provider "$SONAR_PROVIDER_RESOLVED" \
+  --project-key jterrats_open-orchestra \
+  --organization jterrats \
+  --host-url "$SONAR_HOST_URL_RESOLVED" \
+  --branch "$BRANCH_NAME"
+```
+
+The preflight validates token authentication, project visibility, quality gate
+API access, issue API access, and security hotspot API access. It redacts the
+token, host URL, and Cloudflare Access service token values from diagnostic
+output. `hotspots` is a warning when unavailable because some Sonar tokens can
+analyze and read issues while hotspot review permissions are managed separately.
+
+Common remediation:
+
+- `auth-invalid`: regenerate `SONAR_TOKEN`; do not paste header names or
+  prefixes into the secret value.
+- `project-not-found`: verify the project key and organization, then grant the
+  token user Browse access on the project.
+- `permission-denied`: grant Execute Analysis for scanner upload and Browse/API
+  access for evidence import. Use a user token when hotspot APIs must be read.
+- `cloudflare-challenge`: use the Cloudflare Access service token proxy, a
+  self-hosted runner with local `SONAR_LOCAL_HOST_URL`, or an Access policy that
+  explicitly allows the CI service token without an interactive challenge.
+
 ## Local SonarQube
 
 Open Orchestra does not own the long-lived local SonarQube containers. The
@@ -179,6 +208,35 @@ For the current laptop setup, use the macOS ARM64 runner package and configure
 the runner with `--labels sonar,local-sonar`. GitHub automatically adds the
 platform labels such as `self-hosted`, `macOS`, and `ARM64`.
 
+Current macOS ARM64 bootstrap:
+
+```bash
+mkdir -p ~/dev/actions-runner-open-orchestra-sonar
+cd ~/dev/actions-runner-open-orchestra-sonar
+curl -L -o actions-runner-osx-arm64.tar.gz <github-runner-osx-arm64-download-url>
+tar xzf actions-runner-osx-arm64.tar.gz
+./config.sh --url https://github.com/jterratsdev/open-orchestra --labels sonar,local-sonar --name open-orchestra-sonar-macos-arm64
+./run.sh
+```
+
+Future Linux runner bootstrap should use the Linux package that matches the host
+architecture, the same `sonar,local-sonar` labels, and a dedicated service
+account. Do not reuse a broad organization runner for Sonar unless the runner
+already has least-privilege filesystem, Docker, and network access.
+
+Service lifecycle:
+
+```bash
+cd ~/dev/actions-runner-open-orchestra-sonar
+./svc.sh install
+./svc.sh start
+./svc.sh status
+./svc.sh stop
+```
+
+Use `./run.sh` for interactive local troubleshooting. Use `svc.sh` only after
+the runner can start, claim a Sonar workflow job, and reach SonarQube locally.
+
 Keep the shared SonarQube stack running locally:
 
 ```bash
@@ -201,6 +259,44 @@ container. In that case either run the runner process on the host, attach the
 runner container to the SonarQube Docker network, or set `SONAR_LOCAL_HOST_URL`
 to the host/network address that reaches SonarQube without Cloudflare.
 
+### Self-Hosted Runner Health Check
+
+Before relying on CI, validate the local runner and SonarQube path from the same
+machine that runs the GitHub Actions runner:
+
+```bash
+gh variable list --repo jterratsdev/open-orchestra
+gh api repos/jterratsdev/open-orchestra/actions/runners --jq '.runners[] | {name, status, busy, labels: [.labels[].name]}'
+npm run sonar:preflight:local
+```
+
+Expected result:
+
+- `SONAR_RUNNER` is `self-hosted`.
+- A runner is `online` with `self-hosted`, `sonar`, and `local-sonar` labels.
+- Sonar authentication returns `{"valid":true}`.
+- `npm run sonar:preflight:local` passes `auth`, `project`, `qualityGate`, and
+  `issues`; `hotspots` may warn when the token lacks hotspot read access.
+
+If the runner is online but jobs stay queued, verify the workflow labels match
+the runner labels exactly. If Sonar preflight fails, fix the token/project
+permissions before rerunning the workflow.
+
+### Current Workflow Warning Triage
+
+- Node 20 action warning: non-blocking today. Track upstream action upgrades and
+  update actions when GitHub publishes Node 24-compatible major versions.
+- GPG keyserver warning from the Sonar scanner action: non-blocking when scanner
+  setup and analysis complete. Prefer self-hosted runner network allowlisting or
+  a pinned scanner cache before treating it as release-blocking.
+- Cache or tar warnings: non-blocking unless scanner dependencies fail to
+  restore and analysis cannot start. Rebuild the runner cache or rerun the job
+  before changing project code.
+
+These warnings should be captured as CI annotations, but they do not override a
+passing Sonar workflow unless the scanner, import, or final quality gate step
+fails.
+
 Sonar reads TypeScript through `tsconfig.sonar.json`, a standalone analyzer
 config that mirrors the build compiler options but lowers only the analyzer
 target to `ES2022`. Keep the main build target unchanged unless runtime support
@@ -239,6 +335,17 @@ Recommended minimum quality gate for new code:
 - Coverage reported from `coverage/lcov.info` for source files on every Sonar
   run.
 
+The Orchestra Sonar import stores unresolved issues and Sonar security hotspots
+in the uploaded `sonar-insights` artifact. When the gate fails only on
+`new_security_hotspots_reviewed`, review the hotspot list in SonarQube, mark
+each hotspot as safe, fixed, or accepted with rationale, then rerun the Sonar
+workflow. Do not bypass this gate from code unless the Product Owner explicitly
+accepts the security risk.
+If the artifact includes `securityHotspotsUnavailableReason`, the configured
+`SONAR_TOKEN` can read the quality gate and issues but cannot read the hotspots
+API. Grant the token Browse plus security hotspot review/read permissions in
+SonarQube before using the artifact as release evidence.
+
 ## Coverage Publishing
 
 The Sonar workflow runs `npm run test:coverage` before analysis. That command

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jterrats/open-orchestra",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "type": "module",
   "workspaces": [
     "extensions/vscode-open-orchestra",
@@ -30,6 +30,7 @@
     "performance:bench": "npm run build && node scripts/performance-benchmark.js",
     "precommit": "npm run lint && npm run typecheck && npm run secret-scan && npm run security:audit && npm test && npm run validate:workflow",
     "prepack": "npm run build",
+    "sonar:preflight:local": "node bin/orchestra.js sonar preflight --provider sonarqube-local --project-key jterrats_open-orchestra --host-url ${SONAR_HOST_URL:-http://localhost:9001}",
     "sonar:scan:local": "sonar-scanner -Dsonar.host.url=${SONAR_HOST_URL:-http://localhost:9001}",
     "hooks:install": "git config core.hooksPath .githooks",
     "build:web": "npm run build:web:legacy && npm run build:web:react",

package/rules/delivery-quality-gates.mdc

@@ -18,6 +18,8 @@ Development work is not complete when code compiles. Every implementation must m
 ## QA Gate
 
 - QA receives the Developer handoff before release approval.
+- Workflow gate approval is not a status shortcut. `po→architect` can be approved only when the issue/task has user-validated scope, non-goals, assumptions, priority, acceptance criteria, and sizing context. `qa→release` can be approved only after real implementation evidence, QA findings, BA/PO acceptance, and Architect review when technical contracts changed.
+- Generated handoffs with `Acceptance Criteria: none` are incomplete for release purposes. Pull the criteria from the linked GitHub issue or Orchestra task, record a review finding, and block release until the criteria/evidence gap is fixed or explicitly risk-accepted by the Product Owner.
 - QA must produce a test plan covering acceptance criteria, regression areas, edge cases, data setup, and environment assumptions.
 - QA must block test planning when acceptance criteria are fragmented, non-verifiable, or only role/phase headings. Return those findings to PO/BA before release evidence is generated.
 - QA plans must include an AC-to-evidence matrix with expected observable result, actual result, artifact/command, and pass/fail/deferred status for each acceptance criterion.