@jterrats/open-orchestra 1.0.2 → 1.0.3

package/docs/architecture.md

@@ -10,68 +10,72 @@ the project site.
 flowchart LR
   subgraph entry["Entry surfaces"]
     human["Human operator"]
-    agent["Codex / Claude / Cursor"]
-    ide["VS Code control center"]
+    runtime["Agent runtimes"]
+    ide["IDE control center"]
     web["Local web console"]
   end
 
-  subgraph cli["CLI contract"]
-    commands["orchestra commands"]
-    manifest["command manifest"]
-    json["JSON output contracts"]
+  subgraph contract["Runtime and CLI contract"]
+    bootstrap["Runtime bootstrap"]
+    commands["orchestra CLI"]
+    manifest["Command manifest"]
+    api["JSON contracts"]
   end
 
-  subgraph core["Workflow services"]
-    tasks["task registry"]
-    workflow["autonomous workflow"]
-    gates["review gates"]
-    memory["role-scoped memory"]
-    skills["skills and prompts"]
-    release["release readiness"]
+  subgraph workflow["Workflow core"]
+    intake["Task registry"]
+    phases["PM to release phases"]
+    gates["Human review gates"]
+    skills["Skills and memory"]
+    readiness["Release readiness"]
   end
 
-  subgraph state["State and integrations"]
-    files[".agent-workflow files"]
-    providers["model providers"]
-    trackers["tracker adapters / MCP"]
-    evidence["evidence artifacts"]
+  subgraph state["Local state and adapters"]
+    files[".agent-workflow state"]
+    providers["Model providers"]
+    trackers["Tracker adapters"]
+    evidence["Evidence packs"]
+    content["Docs manifest"]
   end
 
-  subgraph outputs["Delivery outputs"]
-    docs["docs and site"]
-    npm["npm package"]
-    tags["release tags"]
-    reports["handoff reports"]
+  subgraph delivery["Delivery outputs"]
+    site["Public site"]
+    package["npm package"]
+    reports["Handoffs and reports"]
+    release["CI release tags"]
   end
 
   human --> commands
-  agent --> commands
-  ide --> commands
-  web --> commands
+  runtime --> bootstrap
+  ide --> api
+  web --> api
+  bootstrap --> commands
   commands --> manifest
-  commands --> json
-  manifest --> workflow
-  json --> workflow
-  workflow --> tasks
-  workflow --> gates
-  workflow --> memory
-  workflow --> skills
-  workflow --> release
-  tasks --> files
+  api --> manifest
+  manifest --> phases
+  phases --> intake
+  phases --> gates
+  phases --> skills
+  phases --> readiness
+  intake --> files
   gates --> evidence
-  memory --> files
   skills --> files
-  workflow --> providers
-  workflow --> trackers
-  release --> docs
-  release --> npm
-  release --> tags
+  phases --> providers
+  phases --> trackers
+  readiness --> evidence
+  content --> site
+  readiness --> site
+  readiness --> package
+  readiness --> release
   evidence --> reports
 ```
 
 The site renders the same source from
 [`site/public/architecture.mmd`](../site/public/architecture.mmd) through the
 React + Vite public site with pan, zoom, reset, and fullscreen controls.
+The documentation and served Mermaid source must be updated together. See
+[Public Site Content Workflow](site-content-workflow.md) for the generated
+content contract and diagram QA expectations.
 
 ## How To Read It
 
@@ -97,6 +101,8 @@ React + Vite public site with pan, zoom, reset, and fullscreen controls.
 ## Related Docs
 
 - [MVP guide](orchestra-mvp.md)
+- [Advisory supervisor architecture](advisory-supervisor-architecture.md)
 - [Persona workflows](persona-workflows.md)
 - [Runtime adapters](runtime-adapters.md)
+- [Public site content workflow](site-content-workflow.md)
 - [Traceability flow](traceability-flow.md)

package/docs/autonomous-workflow.md

@@ -34,7 +34,7 @@ PM → PO [gate] → Architect [sizing gate] → Developer → QA [gate] → Rel
 | Phase       | Role            | Output                                                               | Human checkpoint                                          |
 | ----------- | --------------- | -------------------------------------------------------------------- | --------------------------------------------------------- |
 | `pm`        | product_manager | Product framing, trade-offs, sequencing, and success metrics         | None by default                                           |
-| `po`        | product_owner   | Refined scope, acceptance criteria, assumptions, and release value   | `po→architect` when `--gates phase` or `--gates all`      |
+| `po`        | product_owner   | User-validated scope, definitions, acceptance criteria, assumptions, non-goals, priority, and release value | `po→architect` when `--gates phase` or `--gates all`      |
 | `architect` | architect       | Technical approach, affected boundaries, sizing decision, and risks  | Architect sizing gate is always required                  |
 | `developer` | developer       | Code/docs changes, implementation notes, and Developer to QA handoff | Optional clarification to PO or Architect                 |
 | `qa`        | qa              | Test plan, validation evidence, gaps, and QA recommendation          | `qa→release` when `--gates phase` or `--gates all`        |
@@ -64,7 +64,7 @@ the active role from continuing safely.
 
 | Situation                                                           | Use           | Why                                                                   |
 | ------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------- |
-| PO acceptance criteria need human confirmation before design starts | Gate          | This is a planned phase boundary                                      |
+| PO/BA stories, definitions, acceptance criteria, or assumptions need user confirmation before design starts | Gate          | This is a planned phase boundary                                      |
 | QA evidence is complete but release risk needs sign-off             | Gate          | This determines whether Release may proceed                           |
 | Developer needs to know whether empty input is valid                | Clarification | The active phase is blocked by a product or architecture question     |
 | QA finds ambiguous expected behavior while writing tests            | Clarification | The answer should unblock QA without inventing a new phase boundary   |

package/docs/backlog/ac-evidence-bugfix-stories-20260517.md

@@ -0,0 +1,76 @@
+# AC Evidence Bugfix Stories
+
+Date: 2026-05-17
+Source task: AC-EVIDENCE-BACKFILL-20260517
+
+These bugfix stories come from the reconciled acceptance-criteria evidence batch.
+They are current failures, not historical superseded criteria.
+
+## BUG-DOCS-GENERATED-SITE-AC-20260517
+
+Title: Fix docs adoption test after generated site content migration
+
+As a product user evaluating first-run onboarding, I want the public site,
+README, and adoption docs to consistently prove the first visible value path so
+that documentation tests validate the real source of rendered content.
+
+Acceptance criteria:
+
+- `node --test test/docs-adoption.test.js` passes.
+- The test validates `First visible value` in the generated site content source
+  or rendered site output instead of requiring literal copy in `site/src/App.jsx`.
+- README, adoption guide, core command surface, and site content still point to
+  `orchestra workflow run --task DEMO-001 --gates none`.
+- The governed production path remains documented.
+
+## BUG-SITE-ARCH-DIAGRAM-RENDER-20260517
+
+Title: Fix project site architecture diagram render
+
+As a site visitor, I want the architecture viewer to render its SVG on desktop
+and mobile so that the product architecture can be inspected visually.
+
+Acceptance criteria:
+
+- `npm run site:build` passes.
+- `npm run test:e2e -- e2e/project-site.spec.js` passes.
+- `[data-architecture-diagram] svg` becomes visible on desktop and mobile.
+- Architecture controls remain interactive: zoom, pan, reset, node drag, and
+  group drag.
+- No console or page errors are emitted during diagram render.
+
+## BUG-WEB-OPS-READINESS-COPY-20260517
+
+Title: Restore release readiness state in task detail
+
+As an operator using the web console, I want task detail to show release
+readiness state consistently so that I can understand whether a task is ready or
+what remains unresolved.
+
+Acceptance criteria:
+
+- `npm run test:e2e -- e2e/web-console.spec.js` passes the WEB-OPS scenario.
+- Task detail for `OPS-E2E` shows an explicit positive release readiness state
+  or the E2E is updated to assert the current accepted copy.
+- Task detail still shows acceptance criteria, Definition of Ready, Definition
+  of Done, handoffs, reviews, and evidence.
+- Negative readiness state for `COST-E2E` still surfaces missing backlog item
+  and release-readiness remediation.
+
+## BUG-WEB-LIFECYCLE-BLOCK-GATE-20260517
+
+Title: Restore web lifecycle block gate control after request changes
+
+As a release reviewer using the web console, I want to approve, request changes,
+or block a workflow gate from the same lifecycle surface so that gate decisions
+remain auditable and actionable.
+
+Acceptance criteria:
+
+- `npm run test:e2e -- e2e/web-console.spec.js` passes the WEB-LIFECYCLE scenario.
+- After a `Request Changes` decision, the gate decision surface still exposes a
+  valid block path or the workflow state transition intentionally removes block
+  and the test documents the accepted behavior.
+- Gate history records `changes`, `block`, and `approve` decisions when those
+  actions are available.
+- Resume continues from the approved gate and completes the lifecycle.

package/docs/backlog/dev-best-practices-hardening-story.md

@@ -0,0 +1,69 @@
+# Story: Harden developer best practices for module boundaries and god-file prevention
+
+Backlog Item ID: DEV-BEST-PRACTICES-HARDENING
+
+## User Story
+
+As a technical lead, I want Open Orchestra developer guidance to enforce
+pre-write god-file checks and clean module boundaries, so that new code follows
+domain/model/service/adapters separation and command files stay nearly
+logicless.
+
+## Background
+
+As the project grows, large command and service files can accumulate parsing,
+business rules, storage access, formatting, and integration orchestration in the
+same place. This increases regression risk and makes agent-generated changes
+harder to review.
+
+Developer standards should force agents to check file size and responsibility
+before writing code. If a change would grow a god file or add business logic to
+an adapter, the agent should create or reuse the correct domain/model/service
+module instead.
+
+## Acceptance Criteria
+
+- Developer rules require a pre-write file-size and responsibility check before
+  adding code to an existing file.
+- Rules define god-file risk thresholds and require extraction when a change
+  would materially increase a large or multi-responsibility file.
+- Rules define expected boundaries:
+  - `model/types`: data contracts and narrow public types;
+  - `domain`: pure invariants, policy, and business decisions;
+  - `service/use-case`: orchestration of workflows and dependencies;
+  - `commands`: CLI adapter for parsing input, calling services, formatting
+    output, and converting errors;
+  - `web/api`: HTTP/UI adapter behavior;
+  - `storage/repository`: persistence and file I/O.
+- Command modules are documented as logicless adapters and must not contain deep
+  business rules, multi-step workflow policy, direct persistence logic, or
+  duplicated hardcoded collections when a domain/service source of truth exists.
+- Review guidance requires reviewers to flag command/service files that are
+  growing without a boundary decision.
+- QA or static validation includes a lightweight check or documented checklist
+  for large files, new exports, and adapter logic creep.
+- Existing collection standards are referenced so repeated hardcoded values are
+  extracted into typed/configurable sources of truth.
+
+## Non-Goals
+
+- Refactoring every existing large file in one change.
+- Blocking emergency hotfixes when a follow-up debt task is explicitly created.
+- Introducing a heavy architecture framework.
+
+## Suggested Implementation
+
+- Add or update a focused rule file for module boundaries and god-file
+  prevention.
+- Reference the rule from developer-facing standards and relevant skills.
+- Add a checklist to code review/QA standards.
+- Add a small validation command or test only if it can be low-noise and
+  maintainable.
+
+## T-Shirt Size
+
+S
+
+## Suggested Owners
+
+Architect, Developer, QA.

package/docs/backlog/docs-public-internal-package-hygiene-story.md

@@ -0,0 +1,62 @@
+# Story: Classify docs and tighten package documentation contents
+
+Backlog Item ID: DOCS-PUBLIC-INTERNAL-PACKAGE-HYGIENE
+
+## User Story
+
+As a release manager, I want documentation classified as public, internal,
+backlog, experiment, or package-required so that the public site and npm package
+ship only the documentation intended for users while internal planning artifacts
+remain available in the repository.
+
+## Background
+
+The public site does not currently render all files under `docs/`; it links to a
+small subset and serves its own `site/public/architecture.mmd`. The npm package,
+however, includes the full `docs/` tree through `package.json.files`. As
+backlog, prompt-bank experiments, diagram experiments, and internal dogfooding
+notes grow, package contents can become noisy.
+
+Before final release, Open Orchestra should define which docs are:
+
+- public user documentation;
+- public package documentation;
+- internal product/backlog material;
+- experiment/provenance artifacts;
+- site-only assets.
+
+## Acceptance Criteria
+
+- Inventory all files under `docs/` and classify each as public, internal,
+  backlog, experiment, diagram artifact, or package-required.
+- Identify which docs are linked from README.
+- Identify which docs are linked from the public site.
+- Identify which docs are required by runtime/package behavior.
+- Decide whether `package.json.files` should include all docs or a narrower
+  allowlist.
+- If narrowing package contents, update `package.json.files` and validate with
+  `npm pack --dry-run`.
+- Preserve repository traceability for internal/backlog/experiment docs even if
+  they are excluded from npm.
+- Document the classification policy so future docs land in the right location.
+
+## Non-Goals
+
+- Redesigning the public site.
+- Deleting historical evidence or backlog without an explicit archive decision.
+- Moving docs into a SaaS registry.
+
+## Suggested Implementation
+
+- Add a docs classification manifest or policy document.
+- Optionally reorganize directories only when links can be updated safely.
+- Update `package.json.files` if package hygiene requires it.
+- Run `npm pack --dry-run` and verify expected docs are included/excluded.
+
+## T-Shirt Size
+
+S
+
+## Suggested Owners
+
+Technical Writer, Release Manager, Product Owner.

package/docs/backlog/prompt-bank-registry-epic.md

@@ -0,0 +1,159 @@
+# Epic: Offline-first prompt bank registry and reference API
+
+Backlog Item ID: PROMPT-BANK-REGISTRY-EPIC
+
+## Epic Story
+
+As a platform owner, I want Open Orchestra to maintain a versioned prompt bank
+that works offline from the repository and can optionally sync categorized
+references from an external bucket/API, so that agents can retrieve high-quality
+prompt guidance on demand without bloating skills or requiring internet access
+for core operation.
+
+## Relationship
+
+Parent/related epic: #333 Advisory supervisor for local findings and guarded
+GitHub worker.
+
+This epic complements the advisory/SaaS direction. The advisory supervisor can
+produce findings that improve prompt bank entries, while the prompt bank
+registry provides curated guidance that agents can retrieve safely during local
+or SaaS-backed execution.
+
+## Problem
+
+Skills should stay compact and role-scoped. If every diagram, QA, security,
+architecture, or workflow reference is embedded directly into skills, agent
+context becomes expensive and hard to govern. If references live only in a SaaS
+or bucket, local/offline operation breaks.
+
+Open Orchestra needs a hybrid model:
+
+- a small canonical prompt bank in the repo for offline execution;
+- external categorized references for richer examples and reusable patterns;
+- an API/retrieval layer that returns only the minimum relevant guidance;
+- guardrails that prevent raw prompt injection, secrets, or source-specific
+  content from becoming reusable rules.
+
+## MVP Outcome
+
+- Local prompt bank manifest stored in the repo and packaged with the CLI.
+- Prompt bank entries categorized by role, phase, skill, artifact type, runtime,
+  safety level, and offline eligibility.
+- Retrieval command/API that resolves prompt entries by task intent, role, phase,
+  and runtime signals.
+- Skills load compact baseline rules first and request prompt bank references
+  only when task context needs them.
+- External bucket/API contract documented but optional.
+- Offline mode uses local prompt bank only and degrades clearly when an external
+  reference is unavailable.
+
+## To-Be Outcome
+
+- SaaS-backed prompt registry with tenant/project categorization, quality
+  scoring, usage telemetry, approval workflows, and API-based retrieval.
+- Bucket-backed prompt artifacts with signed manifests, checksums, versioning,
+  retention policy, and safe caching.
+- Advisory supervisor can propose prompt bank improvements as classified
+  findings, but human approval is required before promotion.
+- Registry supports cross-runtime references for Codex, Claude, Cursor, Copilot,
+  generic agents, and local model runners.
+
+## Proposed Child Stories
+
+### Story 1: Local Prompt Bank Manifest
+
+As an agent runtime, I want a local manifest of prompt bank entries so that I can
+retrieve approved guidance without internet access.
+
+Acceptance criteria:
+
+- Defines entry schema with id, title, category, role, phase, skill, runtime,
+  artifact type, tags, version, source-free flag, safety level, checksum, and
+  path.
+- Includes initial categories for diagrams, QA evidence, advisory findings,
+  security review, story mapping, and runtime coordination.
+- Excludes source-specific PDF text, business labels, secrets, and raw user
+  prompts from reusable entries.
+- Includes tests for schema validation and manifest loading.
+
+### Story 2: Prompt Bank Retrieval API
+
+As a skill loader, I want to retrieve prompt bank entries by runtime need so that
+skills stay small and context is loaded on demand.
+
+Acceptance criteria:
+
+- Provides CLI/API retrieval by role, phase, task intent, skill id, runtime, and
+  tags.
+- Returns summaries first and full content only when requested.
+- Enforces max entry count and max token/character budget.
+- Supports offline-only mode.
+- Emits evidence showing which entries were consulted.
+
+### Story 3: External Bucket/API Contract
+
+As a platform operator, I want an external prompt registry contract so that rich
+references can be stored outside the package without making the package depend
+on SaaS.
+
+Acceptance criteria:
+
+- Documents bucket layout, manifest format, checksums, signed URLs or equivalent
+  access strategy, cache policy, and fallback behavior.
+- Defines API endpoints for search, resolve, fetch, health, and version checks.
+- Requires tenant/project scoping for SaaS mode.
+- Requires redaction and prompt-injection checks before storing or serving
+  entries.
+
+### Story 4: Prompt Promotion Workflow
+
+As a maintainer, I want prompt bank changes to go through review so that weak or
+unsafe prompt guidance is not promoted automatically.
+
+Acceptance criteria:
+
+- Advisory findings can propose prompt entries but cannot promote them directly.
+- Promotion requires classification, safety review, owner approval, and
+  validation evidence.
+- Records provenance: source task, finding id, reviewer, reason, version, and
+  superseded entries.
+- Supports deprecation and rollback of prompt entries.
+
+## Acceptance Criteria
+
+- Epic documents offline-first and SaaS-ready architecture for prompt bank
+  retrieval.
+- Local prompt bank remains the source of truth for core operation.
+- External bucket/API is optional and never required for baseline skills.
+- Prompt entries are categorized and retrievable by role, phase, skill, runtime,
+  artifact type, tags, and safety level.
+- Retrieval is bounded to avoid context bloat.
+- Source-specific text, secrets, raw user prompts, and prompt-injection content
+  are excluded or blocked from reusable prompt entries.
+- Advisory supervisor integration is defined without allowing automatic
+  promotion.
+- Child stories are independently executable.
+
+## Non-Goals
+
+- Full SaaS implementation in the first story.
+- Storing raw prompts/responses by default.
+- Replacing existing skills with a remote-only prompt system.
+- Making internet access mandatory for local workflows.
+
+## Risks
+
+- Context bloat if retrieval is not aggressively bounded.
+- Prompt injection through external registry entries.
+- Secret leakage from raw prompts, lessons learned, or generated artifacts.
+- Drift between local prompt bank and external registry.
+- SaaS dependency creeping into offline workflows.
+
+## T-Shirt Size
+
+L
+
+## Suggested Owners
+
+Product Owner, Architect, Security, Developer, QA.

package/docs/backlog/site-docs-manifest-story.md

@@ -0,0 +1,56 @@
+# Story: Public site consumes documentation manifest instead of hardcoded copy
+
+Backlog Item ID: SITE-DOCS-MANIFEST
+
+Parent: #340
+
+## User Story
+
+As a documentation maintainer, I want the public site to render content from
+versioned documentation or a docs manifest instead of duplicating copy in React
+components, so that the site, README, and docs stay aligned with less manual
+maintenance.
+
+## Background
+
+The public site currently keeps much of its product copy and section metadata in
+`site/src/App.jsx`. That creates duplicate maintenance when docs change. The
+site should use documentation as the source of truth where possible, while React
+components own layout, interaction, and visual presentation.
+
+## Acceptance Criteria
+
+- Defines a public docs manifest or equivalent content source for site sections.
+- Site content for quickstart, command surface, runtime adapters, release
+  readiness, architecture, and docs links is derived from versioned docs or
+  manifest entries instead of duplicated hardcoded copy.
+- `site/src/App.jsx` keeps layout/component logic and no longer owns long-form
+  documentation copy.
+- Site build fails or reports a clear validation error when the manifest points
+  to a missing doc.
+- README/docs/site links stay consistent after the migration.
+- Public site still builds with `npm run site:build`.
+- The implementation avoids runtime network calls; content should be bundled at
+  build time or served from local static assets.
+
+## Non-Goals
+
+- Building a full CMS.
+- Rendering every internal or backlog doc on the public site.
+- Redesigning the whole landing page.
+
+## Suggested Implementation
+
+- Create a manifest such as `docs/site-manifest.json` or
+  `site/src/site-content.js` generated from docs.
+- Prefer Markdown/frontmatter or a small typed JSON schema for section metadata.
+- Add a validation script for manifest paths.
+- Keep public/internal classification aligned with #340.
+
+## T-Shirt Size
+
+S
+
+## Suggested Owners
+
+Technical Writer, UX/UI Designer, Developer.

package/docs/dev-team-specialist-role-profiles.md

@@ -159,7 +159,7 @@ Expected evidence:
 
 ## Prompt Registry Integration
 
-The setup-agents prompt registry pattern is now part of Open Orchestra as a stack-agnostic `.generated-prompts/` scaffold. Specialist roles should use it as follows:
+The prompt registry pattern is now part of Open Orchestra as a stack-agnostic `.generated-prompts/` scaffold. Specialist roles should use it as follows:
 
 - Tech Lead reads `code.md`, `services.md`, and `docs.md` before coordinating implementation plans.
 - SDET reads `tests.md` before adding Playwright or regression coverage.