@jterrats/open-orchestra 1.0.6 → 1.0.7

package/docs/generated-artifact-api-catalog.md

@@ -0,0 +1,366 @@
+# Generated Artifact API Catalog
+
+Open Orchestra keeps the human-facing flow small: use `orchestra init` to create
+or repair a workspace, and use `orchestra refresh` to reconcile managed
+generated artifacts after initialization.
+
+The lower-level commands in this catalog remain available as APIs for tests,
+automation, integrations, and advanced troubleshooting. They should not be the
+first commands shown to new users.
+
+## API Tags
+
+- `system`: manages generated files, instruction blocks, manifests, or runtime
+  bootstrap artifacts.
+- `process`: derives workflow, phase, skill, or playbook guidance from task
+  state.
+- `experience`: renders runtime-specific output for an agent, IDE, web console,
+  or other user-facing integration.
+
+## Safety Contract
+
+Generated artifact APIs must preserve user-authored content outside managed
+Open Orchestra blocks. `--check` and `--dry-run` must not write files. `--force`
+may replace managed blocks, but it must not overwrite unrelated project
+instructions.
+
+Prefer these top-level commands for normal use:
+
+```bash
+orchestra init --check
+orchestra init --force --target codex,claude
+orchestra refresh --check --json
+orchestra refresh --force --runtime-artifacts
+```
+
+## APIs
+
+### `runtime bootstrap`
+
+Tags: `system`, `experience`
+
+Renders or upserts runtime bootstrap instructions for a specific agent target.
+Use it when an integration needs a single target file instead of the full
+workspace initialization flow.
+
+```bash
+orchestra runtime bootstrap --target codex --file AGENTS.md --check --json
+orchestra runtime bootstrap --target claude --file CLAUDE.md --force
+```
+
+Representative JSON result:
+
+```json
+{
+  "mode": "check",
+  "target": "codex",
+  "file": "AGENTS.md",
+  "status": "unchanged",
+  "managedBlock": "runtime-bootstrap",
+  "changed": false,
+  "blocked": false
+}
+```
+
+### `instructions apply`
+
+Tags: `system`
+
+Applies an instruction manifest that may contain multiple managed blocks. Use it
+for tests and bulk reconciliation, not for first-run onboarding.
+
+```bash
+orchestra instructions apply --manifest .agent-workflow/instructions.json --check --json
+```
+
+Representative manifest payload:
+
+```json
+{
+  "version": 1,
+  "entries": [
+    {
+      "file": "AGENTS.md",
+      "blockId": "runtime-bootstrap",
+      "target": "codex",
+      "contentFile": ".agent-workflow/generated/codex-bootstrap.md"
+    }
+  ]
+}
+```
+
+### `instructions block`
+
+Tags: `system`
+
+Upserts one managed instruction block into one file. Use it for focused
+automation when the caller already knows the exact block and target file.
+
+```bash
+orchestra instructions block \
+  --file AGENTS.md \
+  --block runtime-bootstrap \
+  --content-file .agent-workflow/generated/codex-bootstrap.md \
+  --target codex \
+  --dry-run \
+  --json
+```
+
+Representative JSON result:
+
+```json
+{
+  "file": "AGENTS.md",
+  "blockId": "runtime-bootstrap",
+  "target": "codex",
+  "mode": "dry-run",
+  "status": "changed",
+  "changed": true
+}
+```
+
+### `instructions imports`
+
+Tags: `system`
+
+Resolves imported instruction fragments from a registry entry. Use it when a
+runtime or installer needs to preview composed instructions before writing a
+managed block.
+
+```bash
+orchestra instructions imports \
+  --registry .agent-workflow/instruction-registry.json \
+  --entry codex-runtime-bootstrap \
+  --target codex \
+  --json
+```
+
+Representative JSON result:
+
+```json
+{
+  "entry": "codex-runtime-bootstrap",
+  "target": "codex",
+  "imports": [
+    {
+      "id": "workflow-required",
+      "source": "runtime-bootstrap"
+    }
+  ],
+  "content": "Use Open Orchestra as the local control plane..."
+}
+```
+
+### `instructions stale`
+
+Tags: `system`
+
+Detects stale managed instruction blocks by comparing embedded content hashes
+with current generated content.
+
+```bash
+orchestra instructions stale --manifest .agent-workflow/instructions.json --json
+```
+
+Representative JSON result:
+
+```json
+{
+  "stale": [
+    {
+      "file": "CLAUDE.md",
+      "blockId": "runtime-bootstrap",
+      "target": "claude",
+      "expectedHash": "abc123",
+      "actualHash": "def456"
+    }
+  ]
+}
+```
+
+### `protocol render`
+
+Tags: `process`, `experience`
+
+Renders subagent collaboration protocol text without writing files.
+
+```bash
+orchestra protocol render --target codex --task STORY-001 --json
+```
+
+Representative JSON result:
+
+```json
+{
+  "target": "codex",
+  "task": "STORY-001",
+  "sections": [
+    "delegation boundaries",
+    "handoff requirements",
+    "lifecycle commands"
+  ],
+  "content": "Use runtime-native subagents only when the parent runtime supports them..."
+}
+```
+
+### `protocol block`
+
+Tags: `system`, `process`, `experience`
+
+Upserts the rendered subagent protocol into a runtime instruction file.
+
+```bash
+orchestra protocol block --file AGENTS.md --target codex --task STORY-001 --check --json
+```
+
+Representative JSON result:
+
+```json
+{
+  "file": "AGENTS.md",
+  "blockId": "subagent-protocol",
+  "target": "codex",
+  "task": "STORY-001",
+  "status": "unchanged"
+}
+```
+
+### `skills plan`
+
+Tags: `process`
+
+Selects task-scoped skills from role, phase, paths, risks, and acceptance
+criteria. This is a planning API; it does not write runtime files.
+
+```bash
+orchestra skills plan --task STORY-001 --json
+```
+
+Representative JSON result:
+
+```json
+{
+  "task": "STORY-001",
+  "selectedSkills": [
+    {
+      "id": "qa-evidence",
+      "reason": "acceptance criteria require observable CLI evidence"
+    }
+  ]
+}
+```
+
+### `skills advise`
+
+Tags: `process`, `experience`
+
+Selects skills from an advisory prompt without requiring a registered task.
+Use it for advisory mode, discovery, and integrations that have not created a
+workflow task yet.
+
+```bash
+orchestra skills advise \
+  --prompt "Generate a release-ready Playwright plan for the web console" \
+  --role qa \
+  --phase qa \
+  --json
+```
+
+Representative JSON result:
+
+```json
+{
+  "role": "qa",
+  "phase": "qa",
+  "selectedSkills": [
+    {
+      "id": "qa-evidence",
+      "activation": "Playwright evidence and acceptance coverage"
+    }
+  ]
+}
+```
+
+### `skills render`
+
+Tags: `process`, `experience`
+
+Renders selected skills into target-specific text for Codex, Claude, Cursor,
+VS Code, Windsurf, or generic runtimes.
+
+```bash
+orchestra skills render --target codex --task STORY-001 --json
+orchestra skills render --target cursor --skills qa-evidence,diagram-export
+```
+
+Representative JSON result:
+
+```json
+{
+  "target": "codex",
+  "task": "STORY-001",
+  "skills": [
+    {
+      "id": "qa-evidence",
+      "title": "QA Evidence Pack"
+    }
+  ],
+  "content": "When validating QA evidence, map every assertion to acceptance criteria..."
+}
+```
+
+### `workflow render`
+
+Tags: `process`, `experience`
+
+Renders workflow phase guidance, optionally scoped to a runtime and phase.
+
+```bash
+orchestra workflow render --task STORY-001 --target claude --phase developer --json
+```
+
+Representative JSON result:
+
+```json
+{
+  "task": "STORY-001",
+  "target": "claude",
+  "phase": "developer",
+  "loadedPlaybooks": [
+    "developer"
+  ],
+  "content": "Implement domain/model changes before command entry points..."
+}
+```
+
+### `playbooks scaffold`
+
+Tags: `system`, `process`
+
+Creates missing phase playbook stubs. It should preserve existing playbooks and
+is best used during project setup or repository maintenance.
+
+```bash
+orchestra playbooks scaffold --phase developer,qa --dry-run --json
+```
+
+Representative JSON result:
+
+```json
+{
+  "mode": "dry-run",
+  "created": [
+    ".agent-workflow/playbooks/developer.md",
+    ".agent-workflow/playbooks/qa.md"
+  ],
+  "unchanged": []
+}
+```
+
+## Documentation Guidance
+
+- Public onboarding should mention only `init` and `refresh` for generated
+  artifact management.
+- Reference docs may link to this catalog for advanced automation and testing.
+- API examples should remain representative and avoid depending on local user
+  paths, secrets, or generated IDs.

package/docs/release-test-matrix.md

@@ -43,7 +43,7 @@ manual intervention is required.
 | Secret scanning gate   | `npm run secret-scan`                 | Gitleaks scan with `.gitleaks.toml` when the binary is installed; lightweight fallback for offline local development                                                   |
 | Duplicate-code gate    | `npm run duplicates`                  | jscpd duplicate-code report with generated/runtime outputs excluded and collection-standards follow-up for duplicated domain lists                                     |
 | Task split guard       | `node --test test/task-split-assessment.test.js` | PO/BA functional oversize, Architect technical complexity, routine small-task non-blocking behavior, and markdown evidence rendering                                    |
-| Sonar quality gate     | GitHub Actions: `Sonar`               | conditional quality gate for duplication, bugs, code smells, maintainability, coverage readiness, and security hotspots when `SONAR_TOKEN` is configured              |
+| Sonar quality gate     | GitHub Actions: `Sonar` or local SonarQube import | conditional quality gate for duplication, bugs, code smells, maintainability, coverage readiness, and security hotspots when a Sonar provider is configured           |
 | Browser E2E            | `npm run test:e2e`                    | Playwright checks map scenario acceptance criteria to visible UI state, API persistence, artifact attachment, responsive layout, and recovery behavior                 |
 | Installed package init | `npm run test:e2e:init`               | Installed CLI checks map scenario acceptance criteria to stdout, stderr, exit code, filesystem state, JSON contracts, evidence records, and release-readiness outcomes |
 | Public site build      | `npm run site:build`                  | production site build                                                                                                                                                  |
@@ -57,10 +57,14 @@ The default release matrix is offline-friendly. Provider and tracker tests that
 need network access must honor `SKIP_NETWORK_TESTS` and report skipped status
 instead of failing offline CI.
 
-Sonar is conditional because it requires `SONAR_TOKEN`. When configured, a
-failing Sonar quality gate blocks release on new-code quality. When unavailable
-or offline, release evidence must state that Sonar was skipped and attach the
-local quality gates that ran instead.
+Sonar is conditional because it requires a configured provider and token.
+SonarCloud automatic runs should be intentionally enabled with
+`SONAR_CLOUD_ENABLED=true`; private or large repositories can use local or
+self-hosted SonarQube instead. When configured, a failing Sonar quality gate
+blocks release on new-code quality after findings are triaged as fix-required,
+accepted risk, false positive, tool limitation, or deferred debt. When
+unavailable or offline, release evidence must state that Sonar was skipped and
+attach the local quality gates that ran instead.
 
 The duplicate-code gate is local and CI-friendly after dependencies are
 installed. When it reports copied domain lists, command matrices, providers,

package/docs/runtime-adapters.md

@@ -56,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:
@@ -163,6 +172,14 @@ 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.
@@ -173,6 +190,9 @@ They need a precise packet and lifecycle hooks:
   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.

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.6",
+  "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`