@jterrats/open-orchestra 0.5.7 → 1.0.1

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/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.

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@jterrats/open-orchestra",
-  "version": "0.5.7",
+  "version": "1.0.1",
   "type": "module",
   "workspaces": [
-    "site"
+    "site",
+    "web-console"
   ],
   "bin": {
     "orchestra": "bin/orchestra.js"
@@ -14,14 +15,19 @@
     "test": "npm run build && 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",
-    "lint": "eslint . && prettier --check \"{bin,e2e,scripts,test,src}/**/*.js\" \"site/src/**/*.{css,js,jsx}\" \"site/*.{html,js,json}\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.{js,json}\"",
-    "format": "prettier --write \"{bin,e2e,scripts,test,src}/**/*.js\" \"site/src/**/*.{css,js,jsx}\" \"site/*.{html,js,json}\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.{js,json}\"",
+    "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",
     "validate:workflow": "node scripts/validate-workflow.js",
-    "precommit": "npm run lint && npm run typecheck && npm run secret-scan && npm test && npm run validate:workflow",
+    "release:matrix": "node scripts/release-test-matrix.js",
+    "performance:bench": "npm run build && node scripts/performance-benchmark.js",
+    "precommit": "npm run lint && npm run typecheck && npm run secret-scan && npm run security:audit && npm test && npm run validate:workflow",
     "prepack": "npm run build",
     "hooks:install": "git config core.hooksPath .githooks",
-    "build:web": "esbuild src/web-console-client.js --bundle --format=esm --platform=browser --target=es2022 --outfile=dist/assets/web-console.js",
+    "build:web": "npm run build:web:legacy && npm run build:web:react",
+    "build:web:legacy": "esbuild src/web-console-client.js --bundle --format=esm --platform=browser --target=es2022 --outfile=dist/assets/web-console.js",
+    "build:web:react": "npm --workspace @jterrats/open-orchestra-web-console run build",
     "site:build": "npm --workspace @jterrats/open-orchestra-site run build",
     "site:dev": "npm --workspace @jterrats/open-orchestra-site run dev -- --host 127.0.0.1"
   },

package/rules/development-engineering.mdc

@@ -0,0 +1,66 @@
+---
+description: Stack-agnostic developer implementation standards across common application stacks
+alwaysApply: true
+---
+
+# Development Engineering
+
+Developer work must start from the existing project shape, preserve the local architecture, and leave verifiable evidence that the changed production artifact works.
+
+## Project Context First
+- Read the project manifest, build files, framework config, and existing module boundaries before generating code.
+- Infer naming, layering, dependency direction, error style, logging style, and test conventions from nearby code.
+- Do not introduce a new framework pattern, repository style, package layout, or dependency injection approach without a recorded architecture decision.
+- Keep framework-specific adapters at the boundary. Domain and service code should remain portable where the product permits it.
+
+## Entry Points And Layers
+- Controllers, routes, commands, triggers, handlers, jobs, and webhooks must stay thin.
+- Delegate business rules to services or domain modules, and delegate I/O to repositories, clients, gateways, or data-access modules.
+- Keep request parsing, authorization, validation, orchestration, and persistence responsibilities separate enough that each can be tested directly.
+- Public APIs and CLI commands must define request, response, errors, pagination, compatibility, and idempotency before implementation.
+
+## Bulk And Batch Safety
+- Implement for 1..N records, requests, files, events, or messages. Do not special-case only the happy-path singleton.
+- Avoid unbounded data reads, writes, queries, or network calls inside loops. Prefer set-based reads, bulk writes, batching, pagination, or bounded concurrency.
+- Make transaction boundaries explicit and keep them as small as correctness allows.
+- Add regression coverage for multi-item input when the code can receive lists, streams, queues, or batched requests.
+
+## Data Access
+- Reuse the existing data-access pattern before adding a new repository, selector, ORM helper, query builder, or gateway abstraction.
+- Model query shape from real access patterns, including filters, sort order, pagination, indexes, locking, and authorization scope.
+- Keep data ownership explicit. Unrelated modules should not write directly to another bounded context without a service, event, or contract.
+- Validate migrations, generated artifacts, or deployed metadata before relying on tests that exercise them.
+
+## Errors And Logging
+- Scan for the existing exception and logging framework before adding try/catch blocks or new error types.
+- Convert operational errors to user-safe messages at the boundary. Propagate or fail fast on programmer errors.
+- Include useful context in logs: operation name, stable IDs, duration, retry count, and external system name when relevant.
+- Never swallow errors with empty catches or generic success fallbacks.
+
+## External Integrations
+- Use configured clients, named endpoints, and typed configuration. Never hardcode endpoints, tokens, credentials, shell commands, or timeouts.
+- Validate URLs before outbound calls, validate response status before parsing, and handle non-2xx responses explicitly.
+- Define timeouts, retries, backoff, idempotency keys, circuit breaking, and observability for integrations with side effects or production impact.
+- Keep provider-specific request and response mapping in adapters so product logic does not depend on one vendor shape.
+
+## Async Workflows
+- Choose queues, jobs, events, schedulers, or workflow engines based on ordering, retry, observability, latency, and partial-failure semantics.
+- Async payloads should carry stable IDs and versioned schemas, not large mutable snapshots unless snapshots are required for correctness.
+- Define retry policy, dead-letter handling, compensation or forward-fix behavior, and user-visible recovery for critical work.
+- Tests for async code must flush or drain queued work using the framework-supported pattern.
+
+## Testing
+- Use centralized builders, factories, fixtures, or test data helpers instead of copy-pasted setup blocks.
+- Authorization-sensitive logic needs tests under representative user, role, permission, tenant, or policy contexts.
+- Add tests for bulk input, empty input, partial failure, retries, authorization denial, and malformed external responses when applicable.
+- Run static analysis before handoff and include exact commands, results, known gaps, and suggested QA coverage in the handoff.
+
+## Stack Examples
+- Java/Spring: keep controllers thin, place rules in services, use repositories for data access, define `@Transactional` boundaries deliberately, and use Testcontainers or slice tests for persistence contracts.
+- .NET: keep controllers or minimal APIs thin, place rules in application services, pass `CancellationToken`, centralize typed options, and test EF Core query behavior with realistic providers when query translation matters.
+- TypeScript/Node: route or CLI handlers should call services, services should call typed repositories or clients, config should be validated at startup, and integration tests should cover pagination, async drains, and external status handling.
+- Python: endpoint or command functions should call services, services should call repositories or clients, use pytest fixtures/builders for setup, validate settings at startup, and test migrations or ORM queries when schema behavior changes.
+
+## Handoff
+- Handoffs must state the active project conventions, data-access strategy, test strategy, changed artifacts, validation commands, known constraints, and remaining risks.
+- When a task touches security, data, async workflows, external integrations, or infrastructure, include the related review outcome before release approval.