@jterrats/open-orchestra 1.0.5 → 1.0.7

package/docs/runtime-adapters.md

@@ -26,6 +26,13 @@ packet:
 
 - `codex-cli`: use the current Codex CLI/session. Tool permissions and shell
   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.
+- `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.
 - `opencode-cli`: use an authenticated OpenCode CLI with its own provider
   config. Orchestra uses the generic instruction target and never copies
   provider keys into workflow artifacts.
@@ -49,6 +56,15 @@ config. Runtime packets keep `directProviderApiAllowed: false`; provider API
 execution only happens in the workflow phase provider layer when policy allows
 it.
 
+Provider-backed phases require explicit opt-in. Connecting a provider with
+`--allow-direct-provider-api` records both the allowed provider and
+`runtimePolicy.delegation.allowDirectProviderApi=true`; without that opt-in,
+workflow phases fail before calling the provider. Successful provider-backed
+phases are recorded as `executor: provider-backed-phase` with provider, model,
+fallbacks, and `directProviderApiAllowed: true`. Runtime-native subagent
+requests remain `directProviderApiAllowed: false`, even when provider routing is
+configured for the same role.
+
 ## Init Modes
 
 Default project init keeps the current compact bootstrap behavior:
@@ -144,12 +160,52 @@ orchestra runtime sessions --task STORY-001 --json
 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 spawn-lifecycle --session STORY-001:manual:developer:codex-cli --status spawned --agent-id <runtime-agent-id> --json
 ```
 
-The matching read API is `/api/runtime/sessions`. Session operations do not kill
-external provider processes directly; they record auditable suspend, resume,
-cancel, or close events so the parent runtime can reconcile claimed work,
-stale sessions, and handoff state without inventing a second source of truth.
+The matching local APIs are `GET /api/runtime/sessions`,
+`POST /api/runtime/spawn-request`, and `POST /api/runtime/spawn-lifecycle`.
+Session operations do not kill external provider processes directly; they
+record auditable suspend, resume, cancel, close, spawned, active, completed,
+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.
+
+## 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`.
+- 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.
+- 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.
+- All runtimes: keep `directProviderApiAllowed=false`, keep child prompts
+  scoped to the request artifact, avoid full transcript transfer, and record a
+  terminal lifecycle event before marking the phase complete.
+
+The current vendor behavior this maps to is:
+
+- Claude Code supports custom subagents with separate context and allows direct
+  subagent invocation from the parent session.
+- Cursor Background Agents run isolated remote agents in parallel and can be
+  launched while the user continues working.
 
 ## Workflow Phase Executors
 
@@ -163,7 +219,14 @@ role/profile with the runtime executor:
   `opencode-cli`, `vscode-agent`, `windsurf-agent`, or `generic-runtime`.
   This controls where the brief or delegation packet is intended to run.
 - **Subagent**: a runtime-native role-scoped execution unit, only available
-  when the selected runtime adapter declares `subagents.runtimeNative: true`.
+  when the selected runtime adapter declares `subagents.runtimeNative: true`
+  and a supported `subagents.spawn.mode`.
+- **Spawn bridge**: the runtime-specific mechanism for creating that child
+  execution. Modes are `unsupported`, `request-only`, `parent-tool`, and
+  `local-process`. `codex-cli` is the first `parent-tool` bridge and renders a
+  `spawn_agent` request for the active Codex parent session; other runtimes can
+  consume the same request artifact without allowing Orchestra to call vendor
+  APIs directly.
 - **Provider**: a direct model/provider route used by provider-backed phase
   prompts. Provider APIs are separate from runtime-native subagents and are
   never used as a silent fallback for runtime delegation.
@@ -176,7 +239,7 @@ orchestra workflow run --task STORY-001 --phase-execution subagents
 orchestra workflow run --task STORY-001 --phase-execution single-agent
 ```
 
-`auto` uses runtime-native subagent packets when the selected runtime supports
+`auto` uses runtime spawn request artifacts when the selected runtime supports
 them and delegation guardrails allow the spawn; otherwise it records a
 parent-agent fallback reason. `subagents` requires runtime-native support and
 fails fast if the runtime cannot satisfy it. `single-agent` forces the parent
@@ -192,8 +255,11 @@ workflow after capacity is released.
 
 Each phase stores executor provenance in the workflow run and handoff:
 execution mode, executor type, phase, role, runtime id, delegation packet path
-when one was rendered, session id when available, fallback reason, and
-`directProviderApiAllowed=false`.
+or spawn request path when one was rendered, session id when available,
+fallback reason, and `directProviderApiAllowed=false`. Spawn request artifacts
+include the phase, role, session id, parent tool name when applicable, prompt
+artifact, expected result artifact, ownership paths, queue status, and the
+guardrail evaluation so the parent runtime can prove what was delegated.
 
 Cursor canvas sync is intentionally runtime-specific:
 
@@ -244,5 +310,7 @@ The stable inspection commands are:
 orchestra runtime adapters --json
 orchestra runtime brief --task <id> --runtime codex-cli --json
 orchestra runtime delegate-plan --task <id> --runtime opencode-cli --roles qa --json
+orchestra runtime spawn-request --task <id> --role developer --runtime codex-cli --json
+orchestra runtime spawn-lifecycle --session <id> --status completed --agent-id <id> --json
 orchestra model providers --json
 ```

package/docs/site-manifest.json

@@ -140,6 +140,7 @@
   "reference": {
     "links": [
       { "title": "Command contracts", "source": "docs/command-contracts.md", "heading": "Command Contracts" },
+      { "title": "Generated artifact APIs", "source": "docs/generated-artifact-api-catalog.md", "heading": "Generated Artifact API Catalog" },
       { "title": "Runtime LLM flow", "source": "docs/runtime-llm-flow.md", "heading": "Runtime LLM Flow" },
       { "title": "Tracker adapter contract", "source": "docs/tracker-adapter-contract.md", "heading": "Tracker Adapter Contract" },
       { "title": "Source of truth and learning", "source": "docs/source-of-truth-and-agent-learning.md", "heading": "Source of Truth and Agent Learning" }

package/docs/sonar-quality-gates.md

@@ -8,18 +8,39 @@ does not replace secret scanning or runtime policy enforcement.
 The repository includes `sonar-project.properties` and a dedicated GitHub
 Actions workflow at `.github/workflows/sonar.yml`.
 
-Required GitHub secret:
+Supported provider modes:
+
+- `sonarcloud`: hosted SonarQube Cloud. Best for quick setup and public or
+  small repositories where hosted analysis is acceptable.
+- `sonarqube-local`: local SonarQube for development and private-repo
+  dogfooding. The default local host is `http://localhost:9000`.
+- `sonarqube-self-hosted`: organization-managed SonarQube Server. Use this for
+  regulated tenants, private codebases, or repositories where hosted LOC limits
+  and external API permissions are a concern.
+
+Required GitHub secret when the GitHub Actions workflow is enabled:
 
 - `SONAR_TOKEN`: token for SonarQube Cloud or SonarQube Server.
 
 Optional GitHub secret:
 
-- `SONAR_HOST_URL`: required only for self-hosted SonarQube Server. Leave unset
-  for SonarQube Cloud.
+- `SONAR_HOST_URL`: required for self-hosted SonarQube Server. Leave unset for
+  SonarQube Cloud, or set `http://localhost:9000` only for local commands.
+
+Optional GitHub variables:
+
+- `SONAR_PROVIDER`: `sonarcloud`, `sonarqube-local`, or
+  `sonarqube-self-hosted`. GitHub-hosted runners normally use `sonarcloud` or a
+  reachable self-hosted server; local SonarQube is intended for local commands.
+- `SONAR_CLOUD_ENABLED`: set to `true` to run SonarCloud automatically on push
+  and pull request events. When unset, SonarCloud runs only through manual
+  `workflow_dispatch`.
+- `SONAR_QUALITY_GATE_WAIT`: set to `true` to fail the workflow when the remote
+  quality gate fails.
 
 The workflow skips analysis when `SONAR_TOKEN` is not configured. This keeps
-forks and offline development usable while making Sonar a CI quality gate for
-configured environments.
+forks and offline development usable. For private repositories, keep
+`SONAR_CLOUD_ENABLED` unset unless hosted analysis is intentionally approved.
 
 The workflow supports remote quality gate enforcement when the repository
 variable `SONAR_QUALITY_GATE_WAIT=true` is configured. In that mode the scanner
@@ -32,6 +53,59 @@ 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.
 
+## Local SonarQube
+
+Open Orchestra includes `docker-compose.sonar.yml` for local SonarQube
+dogfooding:
+
+```bash
+docker compose -f docker-compose.sonar.yml up -d
+```
+
+Open `http://localhost:9000`, complete the SonarQube first-run setup, create a
+project key, and generate a project token. Then run scanner/import commands
+against the local host. Example import after analysis is available:
+
+```bash
+SONAR_TOKEN=<local-token> node bin/orchestra.js sonar import \
+  --provider sonarqube-local \
+  --host-url http://localhost:9000 \
+  --project-key open-orchestra \
+  --branch main \
+  --task GH-368-LOCAL-SONARQUBE-PROVIDER \
+  --json
+```
+
+HTTP is accepted only for `sonarqube-local` on localhost. Self-hosted and cloud
+hosts must use HTTPS.
+
+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
+changes; the Sonar-specific file exists because SonarQube 9.9 analyzers reject
+newer TypeScript targets such as `ES2023`, including when they appear in an
+extended config.
+
+Do not commit local SonarQube data, tokens, database volumes, or exported source
+snippets.
+
+## Finding Triage
+
+Sonar findings are not automatic fixes. Before remediation, classify each
+finding as one of:
+
+- `fix-required`: confirmed defect or maintainability issue that should be
+  corrected now.
+- `accepted-risk`: real finding accepted for a documented reason, owner, and
+  review date.
+- `false-positive`: analyzer cannot model the actual behavior.
+- `tool-limitation`: edition, language, generated-code, or framework limitation.
+- `deferred-debt`: valid issue intentionally scheduled for a later task.
+
+ESLint suppressions and similar static-analysis exceptions must not be removed
+blindly. Validate whether the suppression is still required, can be narrowed,
+should be fixed, or must be accepted with linked rationale.
+
 Recommended minimum quality gate for new code:
 
 - 0 new blocker or critical issues.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jterrats/open-orchestra",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "type": "module",
   "workspaces": [
     "extensions/vscode-open-orchestra",

package/skills/audio-video-transcription/SKILL.md

@@ -0,0 +1,129 @@
+# Audio/Video Transcription Evidence
+
+Transcribe workflow-local audio and video artifacts into reviewable evidence
+without leaking media, secrets, or regulated data.
+
+## When To Load
+
+- Trigger: `transcription`
+- Trigger: `transcribe`
+- Trigger: `transcript`
+- Trigger: `audio`
+- Trigger: `video`
+- Trigger: `recording`
+- Trigger: `demo recording`
+- Trigger: `sprint review`
+- Trigger: `interview`
+- Trigger: `discovery call`
+- Trigger: `support call`
+- Trigger: `meeting recording`
+- Trigger: `voice note`
+- Trigger: `subtitle`
+- Trigger: `vtt`
+- Trigger: `srt`
+
+## Operating Rules
+
+1. Treat media as sensitive by default. Do not send audio, video, or raw
+   transcript text to an external provider unless an explicit policy opt-in
+   allows that provider and the task evidence requires it.
+2. Prefer local/offline engines for first pass transcription. If no approved
+   local engine is available, record a degraded evidence note instead of
+   silently uploading media elsewhere.
+3. Validate the source artifact before processing:
+   - path must be workflow-local or an approved evidence artifact reference;
+   - file must be readable and inside configured size/duration limits;
+   - format/codec support must be known or explicitly marked degraded.
+4. Record provenance for every transcript:
+   - source artifact or workflow-local path;
+   - source hash;
+   - duration and detected language when available;
+   - engine/provider/model;
+   - actor, task id, timestamp, and command/API route;
+   - consent, retention, and tenant/regulatory notes when supplied.
+5. Redact before persistence. Remove or mask secrets, API keys, tokens,
+   credentials, configured PII, health/financial/legal identifiers, and other
+   regulated markers from transcript artifacts and summaries.
+6. Keep outputs compact and structured:
+   - Markdown report for humans;
+   - JSON for tools and evidence linking;
+   - VTT/SRT only when timestamp confidence is adequate;
+   - raw transcripts should be stored as files, not pasted into handoffs.
+7. Extract workflow findings from transcript content:
+   - decisions;
+   - risks;
+   - action items;
+   - acceptance-criteria candidates;
+   - defects or support issues;
+   - lesson-learned candidates;
+   - unresolved questions.
+8. QA evidence must map transcript findings to acceptance criteria and timestamp
+   ranges. A transcript alone is not proof unless the relevant behavior or
+   decision is referenced with observable evidence.
+
+## Failure Modes
+
+Fail closed or produce degraded evidence for:
+
+- missing `ffmpeg` or local transcription engine;
+- unsupported codec or corrupted media;
+- oversized file or excessive duration;
+- provider policy blocks external transcription;
+- unreadable or non-workflow-local artifact path;
+- redaction engine failure;
+- partial transcript or low timestamp confidence;
+- missing consent/retention requirements in regulated contexts.
+
+## Transcript Evidence Template
+
+```md
+# Transcript Evidence
+
+Task:
+Source artifact:
+Source hash:
+Duration:
+Language:
+Engine/provider/model:
+Actor:
+Generated at:
+Consent/retention:
+Redaction policy:
+
+## Acceptance Criteria Mapping
+
+| AC | Timestamp | Evidence | Result | Notes |
+| -- | --------- | -------- | ------ | ----- |
+
+## Decisions
+
+| Timestamp | Decision | Owner | Follow-up |
+| --------- | -------- | ----- | --------- |
+
+## Risks / Defects
+
+| Timestamp | Finding | Severity | Evidence | Owner |
+| --------- | ------- | -------- | -------- | ----- |
+
+## Action Items
+
+| Timestamp | Action | Owner | Due |
+| --------- | ------ | ----- | --- |
+
+## Lesson Candidates
+
+| Timestamp | Lesson candidate | Prevention |
+| --------- | ---------------- | ---------- |
+
+## Gaps
+
+| Gap | Owner | Rationale |
+| --- | ----- | --------- |
+```
+
+## Evidence
+
+- `file`
+- `video`
+- `log`
+- `report`

package/skills/audio-video-transcription/manifest.json

@@ -0,0 +1,61 @@
+{
+  "id": "audio-video-transcription",
+  "name": "Audio/Video Transcription Evidence",
+  "summary": "Transcribe audio and video artifacts into privacy-safe evidence with timestamps, provenance, redaction, and workflow findings.",
+  "triggers": [
+    "transcription",
+    "transcribe",
+    "transcript",
+    "audio",
+    "video",
+    "recording",
+    "demo recording",
+    "sprint review",
+    "interview",
+    "discovery call",
+    "support call",
+    "meeting recording",
+    "voice note",
+    "subtitle",
+    "vtt",
+    "srt"
+  ],
+  "roles": [
+    "business_analyst",
+    "product_owner",
+    "product_manager",
+    "qa",
+    "sdet",
+    "ux_researcher_accessibility",
+    "support_customer_success",
+    "technical_writer",
+    "developer",
+    "architect",
+    "security",
+    "compliance_privacy"
+  ],
+  "capabilities": [
+    "transcription-evidence",
+    "media-evidence",
+    "privacy-redaction",
+    "acceptance-coverage",
+    "lesson-capture"
+  ],
+  "riskAreas": [
+    "quality",
+    "privacy",
+    "security",
+    "compliance",
+    "governance",
+    "release"
+  ],
+  "sourceGroups": [
+    "quality-security",
+    "product-backlog",
+    "agent-memory",
+    "user-research"
+  ],
+  "evidence": ["file", "video", "log", "report"],
+  "loadBudget": "normal",
+  "entry": "skills/audio-video-transcription/SKILL.md"
+}