@jterrats/open-orchestra 0.5.5 → 1.0.1

package/docs/orchestra-mvp.md

@@ -145,6 +145,9 @@ orchestra skills render --target codex --task TASK-1
 orchestra protocol render --target codex --task TASK-1
 orchestra workflow render --target codex --task TASK-1
 orchestra runtime brief --task TASK-1 --runtime codex-cli --json
+orchestra runtime delegate-plan --task TASK-1 --runtime claude-cli --roles developer,qa --json
+orchestra runtime sessions --task TASK-1 --json
+orchestra runtime session --session TASK-1:claude-cli --action suspend --json
 ```
 
 Memory hooks are explicit retrieval points for lessons learned and prompt
@@ -153,6 +156,11 @@ registry entries. Bundles are scoped by role (`product_owner`, `architect`,
 tokens, kept and omitted sections, and trimming rationale in both JSON and human
 output.
 
+Runtime delegation sessions are derived from append-only events. Session
+operations record suspend, resume, cancel, or close events for the parent
+runtime and web console to reconcile active work, stale sessions, and handoff
+state without creating a second session store.
+
 Delivery evidence, handoff, and gates:
 
 ```bash
@@ -173,6 +181,42 @@ locks, and missing smoke or rollback evidence. Browser/UI criteria require
 Playwright-style screenshot, trace, or video evidence unless the task has an
 accepted risk.
 
+For `1.0.0` release candidates, the same report includes `gaReadiness`. This is
+the repeatable go/no-go layer for production promotion. A GA-ready workspace
+must have no uncovered acceptance criteria, no blocking reviews, no active
+locks, smoke and rollback evidence, documentation or release notes evidence,
+observability evidence, security and permissions review evidence, package
+provenance evidence, public CLI contract evidence, migration or upgrade
+readiness evidence, and release test matrix evidence. Accepted risks must include
+an owner, a rationale, and a follow-up or expiry signal in the rationale.
+
+The human release check summary reports both the legacy release readiness gaps
+and the number of GA blockers. Use JSON output for the full criterion list:
+
+```bash
+orchestra release check --json
+```
+
+## Config Schema Migrations
+
+Open Orchestra workspace config is versioned through
+`.agent-workflow/config.json`. For pre-1.0 workspaces, inspect migrations before
+writing anything:
+
+```bash
+orchestra config migrate --json
+```
+
+Apply a supported migration only after reviewing the plan:
+
+```bash
+orchestra config migrate --apply --json
+```
+
+Migration apply writes a backup under `.agent-workflow/backups/` before updating
+`config.json`. Newer unsupported schema versions are reported as errors and are
+not modified.
+
 Upgrade dogfooding:
 
 ```bash
@@ -184,17 +228,52 @@ orchestra upgrade --smoke --json
 Stable installs use `npm install -g @jterrats/open-orchestra@latest`; beta
 dogfooding uses `npm install -g @jterrats/open-orchestra@beta` or the exact
 version reported by `orchestra upgrade --beta`. After upgrading, run the smoke
-command shown by the CLI to verify the installed binary and health report.
+command shown by the CLI to verify the installed binary and health report. The
+upgrade output also includes the exact rollback install command for the
+previous version plus `orchestra config migrate --json` as the migration
+compatibility check before accepting the new package.
+Set `SKIP_NETWORK_TESTS=1` in CI jobs that must avoid external network calls;
+package update checks and provider smoke tests honor it, while localhost E2E
+coverage remains available.
 
 Release go/no-go:
 
 - Run `npm run precommit` locally before pushing release changes.
+- Confirm `npm run security:audit` passes or attach an accepted security risk.
+- Confirm `orchestra release check --json` passes the package provenance gate,
+  which runs `npm pack --dry-run --json` and rejects private workflow state,
+  generated prompts, env files, and missing public package entry points.
 - Confirm GitHub Actions CI is green for the latest pushed HEAD.
 - Confirm installed-package dogfooding passes on `ubuntu-latest`,
   `macos-latest`, and `windows-latest`.
 - Confirm `Create release tag`, site publish, and npm publish workflows are
   successful for the intended release commit.
 
+Support diagnostics:
+
+```bash
+orchestra diagnostics bundle --json
+orchestra diagnostics bundle --output support/diagnostics.json --json
+```
+
+The diagnostics bundle is written inside the workspace and includes local
+health, workflow validation, task and lock counts, run failure summaries, and a
+sanitized config summary. It redacts token-like values, email addresses, user
+home paths, and credential fields before writing the JSON artifact so it can be
+attached to an issue or support handoff.
+
+Performance budgets:
+
+```bash
+npm run performance:bench -- --json
+npm run performance:bench -- --tasks 500 --json
+```
+
+The benchmark seeds a synthetic workspace and measures core CLI commands plus
+read-only web API routes against documented millisecond budgets. Use the JSON
+result as release evidence for large-workspace readiness and investigate any
+failed budget before promoting a production release.
+
 Model routing, budget, telemetry, and release:
 
 ```bash
@@ -359,7 +438,11 @@ The VS Code Control Center scaffold is under `extensions/vscode-open-orchestra`.
 - `orchestra model set-role` configures provider/model routing per role without invoking real model APIs.
 - `orchestra model complete-fake` simulates provider fallback behavior without invoking real model APIs.
 - `orchestra model provenance` records model usage metadata in the append-only event log without storing raw prompts, raw responses, or secrets.
-- `orchestra release check`, `release candidate`, `release tag`, and `release evidence` provide a local release-readiness flow for stable, beta, and other prerelease tags.
+- `orchestra release check`, `release candidate`, `release tag`, and
+  `release evidence` provide a local release-readiness flow for stable, beta,
+  and other prerelease tags. Candidate plans include rollout, rollback,
+  post-release, changelog, and semver-impact sections; release evidence accepts
+  `smoke`, `rollback`, `post-release`, and `release-notes` kinds.
 - `orchestra health --network` can check for a newer published package version and print the exact `npm install -g @jterrats/open-orchestra@<version>` update command when one is available.
 - Package identity is intentionally split: `@jterrats/open-orchestra` is the
   canonical npm package and `orchestra` is the installed CLI binary. Do not use
@@ -381,7 +464,7 @@ Quality signals collected automatically:
 
 ```bash
 # Declare baseline at story start (once per story)
-orchestra estimate --task TASK-1 --sizing m --solo-days 5 --ai-unguided-days 3
+orchestra estimate --task TASK-1 --sizing m --solo-days 5 --ai-unguided-days 3 --ai-guided-days 2
 
 # Per-story benchmark after run completes
 orchestra benchmark --task TASK-1

package/docs/persona-workflows.md

@@ -4,6 +4,36 @@ Use these paths when you want to operate Open Orchestra by role instead of
 learning the full command catalog first. Commands assume the installed CLI form:
 `orchestra`.
 
+## First Visible Value
+
+Goal: complete one local workflow run and preview release readiness before
+learning every role-specific artifact.
+
+Commands:
+
+```bash
+orchestra init
+orchestra health --json
+orchestra task add --id DEMO-001 --title "Ship a governed README update" --owner developer --paths "README.md"
+orchestra workflow run --task DEMO-001 --gates none
+orchestra status
+orchestra release candidate --dry-run --json
+```
+
+Expected artifacts:
+
+- `.agent-workflow/tasks.json` contains `DEMO-001`.
+- `.agent-workflow/workflow-runs.jsonl` contains the completed lifecycle.
+- Release candidate dry-run output shows what is ready and what evidence is
+  still missing.
+
+Recovery:
+
+- Run `orchestra health --json` if local tools are missing.
+- Use `orchestra workflow runs` to find a paused or failed run.
+- Move to the production paths below when the story needs human gates,
+  explicit sizing, command evidence, QA review, and release readiness approval.
+
 ## Product Owner Refinement
 
 Goal: turn a backlog item into a task that is ready for architecture and
@@ -169,6 +199,8 @@ Commands:
 orchestra release check --json
 orchestra release evidence --kind smoke --summary "smoke passed"
 orchestra release evidence --kind rollback --summary "rollback verified"
+orchestra release evidence --kind post-release --summary "post-release smoke passed"
+orchestra release evidence --kind release-notes --summary "release notes published"
 orchestra gate --gate release-readiness --task STORY-001
 orchestra release candidate --version 0.5.0-beta.0 --json
 ```

package/docs/release-test-matrix.md

@@ -0,0 +1,42 @@
+# 1.0.0 Release Test Matrix
+
+The release test matrix is the minimum validation surface for a production
+`1.0.0` candidate. It is intentionally explicit so release readiness can attach
+reviewable evidence instead of relying on conversational sign-off.
+
+## Command
+
+```bash
+npm run release:matrix -- --json
+```
+
+Use the JSON output as the release-manager checklist and attach the final
+execution summary as release test matrix evidence before running:
+
+```bash
+orchestra release check --json
+```
+
+## Required Environments
+
+- `ubuntu-latest` with Node `>=22` and npm.
+- `macos-latest` with Node `>=22` and npm.
+- `windows-latest` with Node `>=22` and npm.
+
+## Required Flows
+
+| Flow | Command | Evidence |
+| --- | --- | --- |
+| Source quality gate | `npm run precommit` | lint, typecheck, secret scan, security audit, build, unit tests, workflow validation |
+| Browser E2E | `npm run test:e2e` | Playwright regression coverage for browser workflows |
+| Installed package init | `npm run test:e2e:init` | npm package init, health, task, workflow, evidence, readiness smoke |
+| Public site build | `npm run site:build` | production site build |
+| Release readiness | `orchestra release check --json` | `releaseReadiness` and `gaReadiness` report |
+| Package contents | `npm pack --dry-run --json` | package file list and provenance check |
+| Performance budgets | `npm run performance:bench -- --json` | CLI and web API timings on a synthetic large workspace |
+
+## Network Policy
+
+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.

package/docs/runtime-adapters.md

@@ -20,6 +20,35 @@ Current targets:
   and `.vscode/open-orchestra.md`.
 - `windsurf`: Windsurf rules in `.windsurf/rules/open-orchestra.md`.
 
+Execution adapters are separate from instruction-file targets. They describe
+how an already-authenticated runtime should receive a brief or delegation
+packet:
+
+- `codex-cli`: use the current Codex CLI/session. Tool permissions and shell
+  approvals stay inside Codex; Orchestra renders briefs and packets only.
+- `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.
+- `generic-runtime`: produce portable briefs when the executor has no known
+  invocation or permission model.
+
+Provider-backed model adapters are configured separately from execution
+adapters. `gemini` and `ollama` can be used for workflow phases without making
+them child process runtimes:
+
+```bash
+orchestra model connect --provider gemini --model gemini-2.5-pro \
+  --roles architect,developer --api-key-file ~/.env_jt/gemini
+
+orchestra model connect --provider ollama --model llama3.1 \
+  --roles qa --base-url http://127.0.0.1:11434
+```
+
+Secrets stay in environment variables or local secret files referenced from
+config. Runtime packets keep `directProviderApiAllowed: false`; provider API
+execution only happens in the workflow phase provider layer when policy allows
+it.
+
 ## Init Modes
 
 Default project init keeps the current compact bootstrap behavior:
@@ -34,6 +63,18 @@ Generate only selected runtime files:
 orchestra init --target claude,cursor,windsurf
 ```
 
+Refresh managed runtime blocks and generated instruction files:
+
+```bash
+orchestra refresh --check --json
+orchestra refresh --dry-run
+orchestra refresh --force --target codex
+```
+
+`refresh --check` reports drift without writing. `refresh --dry-run` shows the
+planned changes. `refresh --force` rewrites managed blocks only; user-authored
+content outside generated blocks is preserved.
+
 Advisory mode creates workflow state without root instruction files unless a
 target is explicit:
 
@@ -85,7 +126,79 @@ The API contracts are:
 ```bash
 curl -s http://127.0.0.1:3717/api/workspace/classification
 curl -s http://127.0.0.1:3717/api/runtime/adapters
+curl -s http://127.0.0.1:3717/api/workflow/progress
 ```
 
 These endpoints are intended for VS Code, Cursor-like extensions, and other
 clients that need to show safe next actions without parsing human CLI output.
+`/api/runtime/adapters` and `orchestra runtime adapters --json` expose both
+instruction-file targets and nested execution adapters. Execution adapters
+include tool permission policy metadata so clients can distinguish
+runtime-managed, brief-only, read-only, and opt-in autonomous execution models.
+
+Runtime delegation operations are event-derived:
+
+```bash
+orchestra runtime sessions --json
+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
+```
+
+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.
+
+Cursor canvas sync is intentionally runtime-specific:
+
+```bash
+orchestra cursor canvas status --json
+orchestra cursor canvas sync --dry-run --json
+orchestra cursor canvas clean --json
+```
+
+Use it only when Cursor canvas artifacts should be copied into the workspace for
+review. Other runtimes should use `runtime brief`, `runtime delegate-plan`, and
+managed bootstrap files instead.
+
+## Invocation Planning
+
+Direct CLI execution is intentionally disabled. Orchestra can render a typed
+invocation plan so callers can inspect the command shape before any future
+executor is enabled:
+
+- `claude-cli` with `gates=phase` or `gates=all` plans
+  `claude --print <prompt> --allowedTools Read Glob Grep`.
+- `claude-cli` with `gates=none` plans
+  `claude --print <prompt> --allow-dangerously-skip-permissions`.
+- `codex-cli`, `opencode-cli`, IDE runtimes, and generic runtimes remain
+  runtime-managed or brief-only, so the plan has no command to execute.
+
+Every invocation plan reports `directExecutionEnabled: false` and
+`canExecute: false`; the contract is for policy review, UI display, and future
+executor hardening, not for spawning tools today.
+
+## Dependency Remediation
+
+Missing tools should be handled as runtime setup problems, not hidden fallback
+behavior:
+
+- Missing Codex CLI: install or authenticate Codex, then rerender the brief with
+  `orchestra runtime brief --task <id> --runtime codex-cli`.
+- Missing OpenCode CLI: install OpenCode and configure its provider credentials
+  in OpenCode, then use `--runtime opencode-cli`.
+- Missing Gemini credentials: set `GEMINI_API_KEY` or configure
+  `--api-key-file` through `orchestra model connect`.
+- Missing Ollama server: start Ollama locally or set the configured base URL to
+  the reachable OpenAI-compatible endpoint.
+
+The stable inspection commands are:
+
+```bash
+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 model providers --json
+```

package/docs/runtime-llm-flow.md

@@ -98,6 +98,10 @@ Anthropic Messages API, `gemini` for the Gemini `generateContent` API, or
 
 ```bash
 orchestra model providers --json
+orchestra model profile set --name local-fast --provider fake --model fake-model --roles developer,qa --activate
+orchestra model profile list --json
+orchestra model profile smoke --name local-fast --json
+orchestra workflow run --task STORY-001 --profile local-fast --gates phase
 orchestra model set-role --role qa --provider fake --model fake-model
 orchestra model connect --provider gemini --model gemini-3-pro-preview --roles qa,reviewer_critic --api-key-file /absolute/path/to/gemini-key --allow-direct-provider-api
 OPENAI_API_KEY=... orchestra model set-role --role architect --provider openai --model gpt-5.2
@@ -116,6 +120,15 @@ in one idempotent config update. This is provider-agnostic: `--provider`,
 routing. Project-specific choices such as "Codex for developer and Gemini for
 QA" belong in the consuming workspace config, not in Open Orchestra defaults.
 
+Use named provider runtime profiles when a workspace needs repeatable routing
+presets such as `local-fast`, `premium-review`, `offline`, or `regulated`.
+`model profile set` stores role routing, fallback chains, and required
+environment variable names without storing secrets. `model profile apply`
+updates active role routing deterministically, and `workflow run --profile`
+applies the profile before execution and records command evidence on the task.
+`model profile smoke` performs local configuration checks and reports missing
+secrets or policy failures with sanitized messages.
+
 The OpenAI adapter reads `OPENAI_API_KEY` from the environment and optionally
 `OPENAI_BASE_URL` for an HTTPS-compatible endpoint. API keys must not be stored
 in workflow config, evidence, docs, or committed files.

package/docs/setup-agents-applicability-review.md

@@ -0,0 +1,173 @@
+# setup-agents Applicability Review
+
+Date: 2026-05-14
+
+## Scope
+
+Review new `setup-agents` issues and local setup-agents standards to decide what
+should be adopted by Open Orchestra.
+
+Sources reviewed:
+
+- Open Orchestra issue #317
+- setup-agents issues #198-#211, with emphasis on #211, #209, #208, #205, #204,
+  #203, #202, #201, #200, #199, #198
+- Local setup-agents developer profile and generated Developer standards
+- Open Orchestra `setup-agents import` bridge and standards rules
+
+## Applies Directly
+
+### Visual Post-Write Validation
+
+Source: setup-agents #211 and Open Orchestra #317.
+
+This applies directly. Open Orchestra is the orchestrator and should own the
+generic gate contract:
+
+- external visual write manifest from agents or MCP integrations
+- export/snapshot evidence
+- fresh fetch of target state
+- duplicate, overlap, fallback-text, orphan, and bounds assertions
+- remediation loop where safe
+- blocking gate when non-remediable defects remain
+
+The Lucid-specific assertions belong in adapters or skills, but the gate type,
+evidence attachment, and workflow blocking behavior belong in Open Orchestra.
+
+### setup-agents Import Role Mapping
+
+Open Orchestra currently maps setup-agents `po` and `pm` aliases to `po` and
+`pm` in `src/setup-agents-import.ts`. Core Open Orchestra roles are
+`product_owner` and `product_manager`. Imported setup-agents tasks should map
+aliases to canonical role IDs.
+
+This is a bug-sized Open Orchestra fix.
+
+### Workflow Benchmark Feedback Into Estimates
+
+Source: setup-agents #205.
+
+Open Orchestra already has estimates and benchmark concepts. Historical
+calibration belongs in Open Orchestra so every stack benefits, not only
+Salesforce. The useful contract is:
+
+- estimates read completed run benchmark data when available
+- output includes historical median and variance
+- warning when historical estimates deviate materially
+- `--ignore-history` bypass
+- JSON output exposes calibration fields
+
+### Playbook Scaffolding And Playbook Authoring Docs
+
+Sources: setup-agents #204 and #201.
+
+Open Orchestra has phase playbooks and task-scoped workflow rendering. A
+scaffold command would reduce friction for teams adapting phases by stack
+without reading source. This applies cross-stack.
+
+### Gate vs Clarify Documentation
+
+Source: setup-agents #202.
+
+Open Orchestra exposes gates, reviews, decisions, and clarification patterns.
+The distinction should be documented in Open Orchestra user docs and runtime
+bootstrap copy because agents otherwise use phase gates for mid-phase questions.
+
+### Workflow Phase Matrix / End-to-End Workflow Narrative
+
+Sources: setup-agents #200 and #199.
+
+Open Orchestra should document its PM -> PO -> Architect -> Developer -> QA ->
+Release sequence, gates, evidence, review checkpoints, and what is autonomous
+versus human-approved. This is product documentation, not setup-agents-specific.
+
+### Rules Health / Generated Guidance Freshness
+
+Source: setup-agents #203.
+
+Open Orchestra already generates bootstrap and managed instruction blocks. A
+health surface that reports stale generated guidance, missing playbooks, and
+workflow readiness would apply directly.
+
+## Applies As A Pattern, Not Literally
+
+### API 66 Salesforce Agent Metadata CI/CD
+
+Source: setup-agents #209.
+
+The Salesforce metadata details do not belong in Open Orchestra core, but the
+pattern does:
+
+- deployment lanes are not always one generic deploy command
+- some artifacts require publish/activate flows
+- generated or managed artifacts may need ignore rules
+- dependency prechecks should run before deploy
+
+Open Orchestra should represent this as stack-specific release lanes or release
+playbook checks, not as Salesforce API 66 logic.
+
+### Auto-Run Local Rule Generation After Init
+
+Source: setup-agents #208.
+
+The exact `sf setup-agents init -> local` behavior is setup-agents-specific.
+For Open Orchestra, the applicable concept is first-run completeness: after
+`orchestra init`, users should exit with usable runtime instructions, workflow
+files, and a clear next command without a hidden second step.
+
+## Developer Standards To Generalize
+
+Several setup-agents Developer standards are Apex-specific, but the underlying
+rules are stack-agnostic and should remain or be strengthened in Open Orchestra:
+
+- Read project metadata/config before generating code.
+- Infer naming and layering from existing code.
+- Default to least privilege / safe execution context.
+- Never query or mutate data inside loops; batch or bulk operations.
+- Keep entry points thin; delegate business logic to services/handlers.
+- Scan for existing exception/logging patterns before adding new ones.
+- Prefer existing data access patterns over inventing a new repository/selector.
+- Handle 1..N records/requests, not only the happy-path singleton.
+- Use centralized test data builders/factories.
+- Include async tests that flush queued work.
+- Use user/permission-specific test contexts for authorization-sensitive logic.
+- Avoid fixed async patterns; choose queues, jobs, events, or schedulers based on
+  ordering, retry, observability, and failure semantics.
+- Use named external integrations/configured clients; never hardcode endpoints,
+  tokens, credentials, or command strings.
+- Validate response status before processing external responses.
+- Keep user-facing strings configurable/localizable where the product needs it.
+- Run static analysis before handoff.
+- Deploy/validate the changed production artifact before relying on tests that
+  exercise it.
+- Every sub-agent handoff should include project conventions, data access
+  strategy, test strategy, and known constraints.
+
+These already overlap with current Open Orchestra rules. The main gap is making
+some of them more explicit for Java, .NET, TypeScript, and Python examples
+without carrying Apex names into stack-agnostic docs.
+
+Adopted in Open Orchestra via `rules/development-engineering.mdc`, with examples
+for Java/Spring, .NET, TypeScript/Node, and Python.
+
+## Does Not Apply To Core
+
+- Salesforce-specific API 66 commands such as `sf agent publish
+  authoring-bundle`.
+- Salesforce-only metadata folders such as `genAiPlannerBundles/`.
+- LWC/SLDS/LDS-specific UI implementation rules.
+- Apex trigger handler naming, `with sharing`, SOQL/DML, PSG test setup, and
+  Custom Labels as literal rules.
+
+These belong in Salesforce/setup-agents profiles, not Open Orchestra core.
+
+## Recommended Open Orchestra Backlog
+
+1. Implement visual validation gate contract and evidence attachment.
+2. Fix setup-agents import role aliases to canonical Open Orchestra roles.
+3. Add benchmark-calibrated estimates.
+4. Add playbook scaffold command and authoring docs.
+5. Add Gate vs Clarify docs and workflow phase matrix.
+6. Add rules/playbook health to `orchestra health` or a dedicated status view.
+7. Add stack-agnostic Developer standards examples for Java, .NET, TypeScript,
+   and Python.

package/docs/skill-loading-strategy.md

@@ -97,6 +97,7 @@ Primary MD files should stay bounded:
 - `orchestra skills validate` validates canonical skills against portable `manifest.json` and `SKILL.md` files.
 - `orchestra sources list` exposes the source-of-truth catalog.
 - `orchestra lessons list/add/promote` manages local agent learning and promotes repeated lessons into reviewable artifacts.
+- `orchestra doc-sync audit [--task <id>] [--strict]` checks changed documentation, changelog, architecture, diagram, and public-site surfaces for prompt registry coverage and suggests `lessons assist` when repeated documentation rework should become a reusable lesson.
 
 The CLI render path is the universal fallback for environments without native skill support.
 

package/docs/source-of-truth-and-agent-learning.md

@@ -78,6 +78,20 @@ Do not record a lesson for:
 4. If reusable, append one JSONL entry with root cause, fix, prevention, and verification.
 5. If the same lesson appears repeatedly, promote it into the relevant skill or project rule.
 
+## Memory Governance
+
+Local memory is useful only while it stays bounded, current, and safe to load
+into future agent context. Use `orchestra memory governance` to inspect active,
+archived, stale, and sensitive lessons. Use `orchestra lessons prune --dry-run`
+before applying retention cleanup, then run without `--dry-run` to archive stale
+or overflow lessons.
+
+Use `orchestra lessons archive --id <lesson-id>` when a lesson is superseded but
+still useful as audit history. Use `orchestra lessons redact --id <lesson-id>`
+when a stored lesson contains token-like or secret-shaped values. Use
+`orchestra lessons delete --id <lesson-id>` only when the record should be
+removed from local memory entirely.
+
 ## Relationship to Skills
 
 Skills should declare which source groups they use and which lessons are relevant. The orchestrator should load lessons only for the selected skills and current operation, not the full historical log.

package/docs/traceability-flow.md

@@ -42,12 +42,16 @@ user-facing:
 
 ```bash
 orchestra playwright plan --task STORY-1
+orchestra qa coverage --task STORY-1 --json
 orchestra playwright evidence --task STORY-1 --kind trace --path test-results/story-1.zip --summary "acceptance flow trace"
 orchestra review --task STORY-1 --role qa --result approve --findings "..." --recommendation "..."
 ```
 
 Developer-to-QA handoff should include touched files, commands, known gaps, and
-recommended Playwright coverage.
+recommended Playwright, CLI, shell, or API coverage. `qa coverage` maps each
+acceptance criterion to `covered`, `planned`, `skipped`, or `gap` using task
+paths, project scripts, and existing evidence; release readiness surfaces
+unresolved QA automation gaps before promotion.
 
 ## Advisory Conversion
 

package/docs/tracker-adapter-contract.md

@@ -4,6 +4,7 @@ Open Orchestra currently ships a GitHub-oriented tracker command:
 
 ```bash
 orchestra github sync --issue <number> --task <id> --comment --json
+orchestra tracker sync --tracker jira --remote PROJ-123 --issue-file jira-123.json --json
 ```
 
 The product contract is broader than GitHub CLI. A runtime may use `gh` when it
@@ -23,7 +24,9 @@ custom issue system.
 ## Common Adapter Shape
 
 Every tracker adapter should provide the same normalized fields to Open
-Orchestra:
+Orchestra. Runtime MCP skills, Jira/GitLab/Bitbucket CLIs, or custom bridge
+scripts should write this shape to a workspace-local JSON file and pass it to
+`orchestra tracker sync --issue-file <file>`:
 
 | Field | Meaning |
 | --- | --- |
@@ -42,6 +45,12 @@ Writes should support comment, status update, close, and accepted-risk note when
 the provider allows them. Missing write support should be reported as a transport
 capability gap, not treated as successful sync.
 
+The generic sync command maps the normalized issue into local task fields,
+detects existing-link conflicts before writing, and records local evidence when
+the sync is applied. Live remote reads and writes remain adapter-owned; the CLI
+does not fabricate Jira, GitLab, Bitbucket, or MCP calls when no adapter runner
+is available.
+
 ## MCP Fallback Requirements
 
 MCP tracker tools must:

package/docs/web-console-qa.md

@@ -0,0 +1,35 @@
+# Web Console QA Notes
+
+The web console is a local browser surface for workflow operations. It is not a
+replacement for the CLI; it consumes the same JSON contracts and should remain
+usable when a user needs to inspect state, create tasks, attach evidence, run or
+resume workflows, and review release readiness.
+
+## 1.0.0 Browser Support
+
+- Chromium is the release-blocking automated browser for 1.0.0 E2E coverage.
+- Desktop smoke uses the default Playwright viewport.
+- Mobile smoke uses a narrow viewport and must not create horizontal overflow.
+- Keyboard-only operation must reach refresh, task creation, evidence,
+  Playwright evidence, workflow start, gate approval, resume, and cancel
+  controls.
+
+## Required States
+
+- Loading: the status line announces `Loading workflow`.
+- Success: the status line announces `Workflow loaded`.
+- Empty: operational panels render friendly empty states when no matching data
+  exists.
+- Error: failed API calls render recoverable copy without raw stack traces.
+
+## Release Evidence
+
+Run:
+
+```bash
+npm run test:e2e -- e2e/web-console.spec.js
+```
+
+Attach the command result as QA evidence before release readiness. If a browser
+failure is accepted temporarily, record the affected viewport, failed action,
+user impact, owner, and expiry as review or release evidence.