@jterrats/open-orchestra 1.0.14 → 1.0.16

package/docs/runtime-adapters.md

@@ -62,10 +62,19 @@ Provider-backed phases require explicit opt-in. Connecting a provider with
 `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
+fallbacks, request id, response id, token usage source, cost source, final
+provider/model, and `directProviderApiAllowed: true`. Runtime-native subagent
 requests remain `directProviderApiAllowed: false`, even when provider routing is
 configured for the same role.
 
+Provider-backed phase execution goes through the provider-backed agent wrapper.
+The wrapper resolves `openai`, `anthropic`, `gemini`, `ollama`, `fake`, and
+future providers through the provider registry/factory boundary around
+`ModelProvider`; workflow orchestration should not branch on provider vendors.
+OpenAI/Codex provider models are provider-backed execution. `codex-cli` is a
+runtime-native parent session and never becomes a provider API fallback unless a
+future explicit hybrid policy records that decision as evidence.
+
 ## Init Modes
 
 Default project init keeps the current compact bootstrap behavior:
@@ -129,6 +138,29 @@ orchestra workflow render --target codex --task STORY-001
 Change `--target` to the runtime that is executing the work. The workflow state,
 roles, evidence, reviews, and gates remain runtime-agnostic.
 
+## Codex Recurring Preflight
+
+Codex does not provide a project-native recurring hook that Open Orchestra can
+install for every context compaction, resumed session, interruption, or role
+handoff. The fallback is explicit managed guidance in `AGENTS.md` plus the
+existing pre-run validation command.
+
+Before each new Codex work block, and again after any context shift, run:
+
+```bash
+orchestra health --json
+orchestra task list --json --status pending,blocked,in_progress
+orchestra validate --pre-run --task STORY-001 --json
+```
+
+The JSON report includes `activeOrchestraContext` and `missingActiveContext`.
+When `activeOrchestraContext` is `false`, the current Codex session is missing
+one or more required workflow anchors: task registration, effort estimate, or a
+workflow run for the task. Reload task context and resume or register the
+workflow before editing files. Evidence and review checks still appear in the
+same report, but those are completion/handoff signals rather than active-context
+anchors.
+
 ## Web And VS Code
 
 The local web console exposes workspace classification and supported runtime
@@ -185,6 +217,54 @@ points to the prompt artifact, expected result artifact, ownership paths,
 allowed commands, and lifecycle commands. It does not include secrets or direct
 provider credentials.
 
+## Runtime Spawn Bridge Boundary
+
+Open Orchestra is the runtime delegation control plane, not the owner of hidden
+LLM runtime tools. Core commands normalize the spawn intent, evaluate guardrails,
+write prompt and handoff artifacts, expose parent actions, record lifecycle, and
+resume workflows. The actual native spawn call belongs to a parent-side consumer
+running inside the active runtime session.
+
+The bridge contract has two sides:
+
+- **Control-plane wrapper**: Orchestra emits a runtime-neutral request with task
+  id, run id, phase, role, context bundle, ownership paths, expected output,
+  evidence contract, queue metadata, and lifecycle commands.
+- **Parent-side consumer**: the active Codex, Claude, Cursor, local worker, or
+  other runtime reads the parent action, invokes any native child-agent tool it
+  owns, and records `runtime spawn-lifecycle` with the real child identifier.
+
+A session is only considered actually spawned after a lifecycle event records
+`--status spawned` with a real runtime child id. Parent actions, request
+artifacts, and dispatch guidance are not equivalent to a running subagent.
+
+Adapter capability terms are strict:
+
+- `parent-tool`: a parent runtime can invoke a native tool such as Codex
+  `spawn_agent`, but Orchestra still cannot call that hidden tool from Node.
+- `request-only`: Orchestra can produce the request and lifecycle instructions,
+  while the parent runtime must execute the native tool manually or by following
+  its session prompt.
+- `local-process`: a future explicit local executor can be launched as a child
+  process under Orchestra policy.
+- `unsupported`: no subagent request should be emitted except as an explicit
+  unsupported/fallback result.
+
+For Codex, the intended path is parent-tool mediated: Orchestra renders
+`codex-spawn-agent`, the parent Codex agent consumes the action and calls
+`spawn_agent`, and the returned Codex agent id is recorded through
+`runtime spawn-lifecycle --status spawned`. Until that happens, Codex actions
+remain requested or skipped with manual guidance.
+
+For Claude, the current supported path is request-only or parent-agent mediated.
+Claude Code's parent session can launch Agent/Subagent work, but Orchestra
+cannot invoke that tool directly from its CLI process. Real automation requires
+the parent Claude agent to follow the session instruction to inspect
+`runtime parent-actions` and call the Agent tool, or a future Claude hook/API
+that can trigger the same action. Until such a hook or callback is available and
+verified, automated Claude native execution remains deferred/manual and must not
+claim spawned lifecycle.
+
 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
@@ -200,13 +280,14 @@ 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
+- Verified 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 verified callback correlation ids, applies
-  `runtime watch` completions when expected handoff artifacts appear, resumes
-  paused workflow runs, and continues across later phases until idle or timeout.
+  events only when the adapter has a real runtime child id or verified callback
+  correlation id, 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
@@ -216,14 +297,17 @@ 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`, but it
-records `spawned` and `active` only when the active parent runtime is Claude and
-the native callback capability is explicitly verified. Unsupported Codex, CI,
-non-Claude, or callback-unavailable contexts return fallback guidance and do not
-claim native execution. Orchestra does not call Claude Code, Anthropic APIs, or
+lifecycle commands; the active parent runtime or a verified local bridge
+executes native tools. Codex dispatch cannot invoke `spawn_agent` from the CLI
+process, so `codex-spawn-agent` dispatch returns manual guidance and must not
+record `spawned` until the Codex parent runtime has called `spawn_agent` and
+then runs `runtime spawn-lifecycle --status spawned` with the real returned
+agent id. For Claude, the tested dispatch contract accepts
+`claude-agent-request` with `tool=claude-code-agent`, but it records `spawned`
+and `active` only when the active parent runtime is Claude and the native
+callback capability is explicitly verified. Unsupported Codex, CI, non-Claude,
+or callback-unavailable contexts return fallback guidance and do not claim
+native execution. Orchestra does not call Claude Code, Anthropic APIs, or
 another provider API.
 
 Runtime-native dispatch also enforces delegation capacity before calling parent
@@ -238,14 +322,37 @@ or gates from flooding the parent runtime at once while still allowing
 background work to continue as capacity becomes available.
 
 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.
+`watcher` object with adapter id, detection mode, support level, supported
+completion signals, fallback behavior, and the reason a native callback is
+unavailable. `codex-cli`, `claude-cli`, and `cursor-cli` reconcile completion
+through observable runtime notifications, explicit lifecycle events, child
+self-report commands, and bounded expected-artifact inspection. `generic-runtime`,
+unknown runtime ids, and runtimes without declared callbacks use the same safe
+artifact fallback directly. Event-driven callbacks should only be used when the
+selected watcher adapter declares native support; otherwise `runtime watch`
+requires a safe handoff artifact or a recorded runtime notification before it
+marks a session terminal.
+
+Runtime notifications are provider-neutral. A parent runtime, local integration,
+web callback, or child agent that cannot directly run `runtime spawn-lifecycle`
+can record an observable signal with:
+
+```bash
+orchestra runtime notification --session <session-id> --status completed --artifact <expected-handoff.md> --agent-id <runtime-child-id>
+```
+
+The watcher still validates task id, phase, role, runtime, session id, and the
+expected handoff artifact before applying completion. A notification without the
+expected artifact stays waiting; a mismatched or unsafe artifact is skipped with
+an explicit reason. Failed notifications record failed lifecycle state and do not
+auto-resume the workflow.
+For spawned or active sessions, expected handoff validation runs before timeout
+evaluation. A stale session that already produced the valid expected handoff is
+completed, while stale sessions without a valid completion artifact can still be
+marked timed out.
+Requested sessions are also reconciled from a valid expected handoff artifact.
+This covers parent runtimes that produce the handoff but cannot self-report the
+intermediate spawned lifecycle event.
 
 ## Claude Adapter Support Level
 
@@ -321,7 +428,10 @@ They need a precise packet and lifecycle hooks:
   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.
+  detached unless the parent is blocked. The child prompt must write the
+  expected handoff and self-report completion with `runtime spawn-lifecycle`; if
+  the runtime cannot execute commands, it must emit a runtime notification that
+  can be reconciled by `runtime watch`.
 - 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.
@@ -350,12 +460,13 @@ role/profile with the runtime executor:
 - **Subagent**: a runtime-native role-scoped execution unit, only available
   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
+- **Spawn bridge**: the runtime-specific mechanism for requesting 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.
+  `local-process`. `codex-cli` renders a `spawn_agent` request for the active
+  Codex parent session, but the parent Codex agent must call the tool and record
+  the returned id. `claude-cli` is request-only or parent-agent mediated until a
+  reliable hook/API/callback is available. 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.

package/docs/security-env-vars.md

@@ -0,0 +1,41 @@
+# Security Environment Variable Manifest
+
+This manifest documents environment variable names that are referenced by local
+security-sensitive automation and runtime detection. It intentionally records
+names only; secret values must stay in the caller environment, CI secret store,
+or local secret files.
+
+## Local Runtime And Tooling
+
+- `ANTHROPIC_API_KEY_FILE`: optional Anthropic credential file path.
+- `CLAUDE_CODE`: Claude Code runtime marker.
+- `CLAUDECODE`: Claude Code runtime marker.
+- `CODEX_SANDBOX`: Codex runtime marker.
+- `CODEX_THREAD_ID`: Codex runtime marker.
+- `CURSOR_AGENT`: Cursor runtime marker.
+- `CURSOR_TRACE_ID`: Cursor runtime marker.
+- `OLLAMA_API_KEY_FILE`: optional Ollama credential file path.
+- `OPENAI_API_KEY_FILE`: optional OpenAI credential file path.
+- `OPEN_ORCHESTRA_CLAUDE_NATIVE_CALLBACK`: local Claude native callback marker.
+- `OPEN_ORCHESTRA_CLAUDE_NATIVE_CHILD_ID`: Claude native child id marker.
+- `ORCHESTRA_GITLEAKS_BIN`: optional absolute gitleaks binary override.
+- `ORCHESTRA_SECRET_SCAN_FORCE_FALLBACK`: forces fallback secret scanning.
+- `ORCHESTRA_SKIP_UPDATE_CHECK`: disables package update checks.
+- `ORCHESTRA_UPDATE_CHECK_CACHE_DIR`: package update check cache directory.
+- `ORCHESTRA_WORKFLOW_HEARTBEAT_MS`: workflow heartbeat interval override.
+
+## CI And Release Automation
+
+- `CF_ACCESS_PROXY_LISTEN_HOST`: local Cloudflare Access proxy host.
+- `CF_ACCESS_PROXY_LISTEN_PORT`: local Cloudflare Access proxy port.
+- `CLOUDFLARE_ACCOUNT_ID`: Cloudflare account identifier from CI secrets.
+- `CLOUDFLARE_API_TOKEN`: Cloudflare deployment token from CI secrets.
+- `GH_TOKEN`: GitHub CLI token provided by GitHub Actions.
+- `GITHUB_HEAD_REF`: GitHub Actions pull request source branch.
+- `GITHUB_REPOSITORY`: GitHub Actions repository slug.
+- `GITLEAKS_ASSET`: temporary gitleaks release asset name in CI.
+- `GITLEAKS_VERSION`: pinned gitleaks release version in CI.
+- `NPM_USER`: npm authenticated username captured during release validation.
+- `NPM_VERSION`: npm package version captured during release validation.
+- `PKG_VERSION`: package version used by release tag creation.
+- `PRERELEASE_FLAG`: release tag prerelease marker.

package/docs/sonar-quality-gates.md

@@ -18,6 +18,28 @@ Supported provider modes:
   regulated tenants, private codebases, or repositories where hosted LOC limits
   and external API permissions are a concern.
 
+### Community Branch and PR Decoration Option
+
+SonarQube Community Edition does not include the same branch analysis and pull
+request decoration capabilities as paid editions. If those capabilities are
+needed in a private local or self-hosted Community setup, evaluate
+[`mc1arke/sonarqube-community-branch-plugin`](https://github.com/mc1arke/sonarqube-community-branch-plugin)
+as an optional infrastructure add-on.
+
+Use this only as an explicitly accepted operational dependency:
+
+- It is not maintained or supported by SonarSource.
+- Plugin compatibility follows the SonarQube major/minor version; pin the image
+  or plugin release to the running SonarQube version.
+- Migration from Community Edition plus this plugin to commercial SonarQube
+  editions has no guaranteed official upgrade path.
+- SaaS or regulated-tenant usage requires a separate security, supportability,
+  upgrade, backup, and rollback review before adoption.
+
+For low-cost local dogfooding, prefer the plugin's published Docker image or a
+separate shared SonarQube infrastructure repository instead of coupling plugin
+installation to this product repository.
+
 Required GitHub secret when the GitHub Actions workflow is enabled:
 
 - `SONAR_TOKEN`: token for SonarQube Cloud or SonarQube Server.
@@ -394,7 +416,7 @@ rules, and Orchestra review gates.
 
 Until Sonar directives are adopted, architecture violations are enforced through:
 
-- repo standards in `AGENTS.md` and `rules/*.mdc`;
+- repo standards in `AGENTS.md` and neutral rule sources selected by Orchestra;
 - architecture gate decisions and ADR-style records;
 - code review against domain boundaries;
 - tests that protect command contracts, workflow behavior, and generated

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jterrats/open-orchestra",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "type": "module",
   "workspaces": [
     "extensions/vscode-open-orchestra",
@@ -17,13 +17,15 @@
     "test:coverage": "npm run build && c8 --reporter=lcov --reports-dir coverage --exclude \"test/**\" --exclude \"e2e/**\" --exclude \"extensions/**/test/**\" --exclude \"dist/assets/**\" --exclude \"dist/web-console/**\" node --test test/**/*.js extensions/**/*.test.cjs",
     "test:e2e": "npm run build && npm run site:build && playwright test",
     "test:e2e:init": "node --test e2e/init-onboarding.test.js e2e/runtime-instruction-flow.test.js",
-    "test:e2e:runtime": "node --test e2e/runtime-manual-queue.test.js",
+    "test:e2e:runtime": "node --test e2e/runtime-manual-queue.test.js e2e/runtime-multi-squad.test.js",
+    "test:e2e:security": "npm run build && node --test e2e/security-boundaries.test.js",
     "test:e2e:runtime:ollama": "npm run build && node --test e2e/runtime-ollama-provider.test.js",
     "lint": "eslint . && prettier --check \"{bin,e2e,scripts,test,src}/**/*.js\" \"{site,web-console}/src/**/*.{css,js,jsx}\" \"{site,web-console}/*.{html,js,json}\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.{js,json}\"",
     "format": "prettier --write \"{bin,e2e,scripts,test,src}/**/*.js\" \"{site,web-console}/src/**/*.{css,js,jsx}\" \"{site,web-console}/*.{html,js,json}\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.{js,json}\"",
     "secret-scan": "node scripts/secret-scan.js",
     "security:audit": "node scripts/security-audit.js",
     "architecture:inventory": "npm run build && node scripts/architecture-debt-inventory.js",
+    "context:pack:bench": "npm run build && node scripts/context-pack-benchmark.js --report-dir docs/reports",
     "duplicates": "jscpd --config .jscpd.json",
     "validate:workflow": "node scripts/validate-workflow.js",
     "release:matrix": "node scripts/release-test-matrix.js",

package/rules/development/semantic-code.md

@@ -0,0 +1,28 @@
+# Semantic Code
+
+Code must be readable by intent before it is explained by comments.
+
+## Naming
+
+- Use domain language for modules, functions, variables, types, and test names.
+- Prefer names that reveal purpose and observable behavior, such as `validateReleaseGateEvidence`, not vague names such as `processData`.
+- Boolean names must make the predicate clear: `isReady`, `hasEvidence`, `canRetry`, `shouldBlockRelease`.
+
+## Structure
+
+- Keep entry points thin. Move decisions and business rules into focused domain, service, or policy modules.
+- Extract helpers when a reader needs comments to understand a block of code.
+- Avoid generic containers in public APIs when narrow types or explicit models can describe the contract.
+- Avoid hardcoded command lists, statuses, roles, labels, or fixture values when a typed registry or catalog can be the source of truth.
+
+## Comments
+
+- Comments explain why, trade-offs, invariants, or external constraints.
+- Do not add comments that restate what the code already says.
+- If a function needs line-by-line comments to be understandable, refactor the names, types, or helper boundaries.
+
+## Review Checklist
+
+- A reviewer can identify the domain intent from names and file boundaries without tracing every line.
+- New code follows the existing project vocabulary and layering.
+- Tests read like behavior specifications and use meaningful scenario names.

package/rules/diagram-quality.mdc

@@ -25,6 +25,8 @@
 - Validate annotation target clarity; annotation arrows must visibly land on the element or line they describe, and annotation text must not obscure the target.
 - For diagrams without a source reference, create a diagram contract before drawing and validate the render against that contract before handoff.
 - Source-free diagrams still require a pixel-perfect pass against their own contract before delivery: no text overflow, no clipped containers, no floating or buried connector endpoints, no unintended overlaps, no hidden arrowheads, and no incoherent whitespace.
+- For deterministic SVG pipeline work, treat the typed diagram model as the source of truth. Layout, SVG rendering, validation findings, icon references, and final deliverables must be reproducible from model input without LLM-selected absolute coordinates.
+- Icon references in deterministic diagrams should use semantic purpose plus Iconify id, resolved from a cacheable source. Tests must not require network access to fetch icons.
 - For source-free diagrams, iterate after the first render until container sizes, line routing, connector anchors, label positions, and visual balance are correct. Do not deliver an unreviewed first render.
 - For every post-render correction, re-run the full diagram review rather than checking only the edited area. A diagram passes only when the whole canvas still satisfies container containment, label clearance, connector routing, z-order, and whitespace rules.
 - A regenerated diagram must materially change geometry for the finding it claims to fix. If two versions preserve the same collision, overflow, endpoint gap, or unnecessary route bend, change the layout strategy instead of only re-rendering.