@jterrats/open-orchestra 1.0.2 → 1.0.4

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/project-persona-registry-epic.md

@@ -0,0 +1,350 @@
+# Epic: Project persona registry and generated domain personas
+
+Backlog Item ID: PERSONA-REGISTRY-EPIC-20260517
+
+## Epic Story
+
+As a project owner, I want Open Orchestra to register, govern, and activate
+project-specific personas through APIs and UI instead of manual markdown edits,
+so that each project can orchestrate the right domain experts, reviewers, and
+delivery roles for its own context.
+
+## Problem
+
+Open Orchestra ships with software delivery roles, but real projects may need
+domain personas that do not fit a fixed role catalog. A music production project
+may need producers, mastering QA, and rights reviewers. A neural network project
+may need ML researchers, MLOps, data stewards, and AI safety reviewers. A medical
+project may need clinical SMEs, medical reviewers, privacy, compliance, and
+regulatory reviewers.
+
+Those personas should not require users to open or edit markdown files manually.
+They also should not be blindly activated because a generated profile sounds
+plausible. Projects need a registry, generation workflow, governance model, and
+runtime activation rules.
+
+## MVP Outcome
+
+- Local persona registry stored in project workflow state and exportable to
+  version-controlled artifacts.
+- CLI/API operations to list, show, create, update, generate, approve,
+  deactivate, export, and import personas.
+- Generated personas start as drafts and require human approval before runtime
+  activation.
+- Runtime activation uses task signals, phase, required roles, risk level, and
+  persona triggers.
+- Regulated or high-risk personas can advise and review, but cannot approve
+  regulated outcomes unless a human approver is configured.
+- Web console can manage project personas without editing markdown files.
+- Offline-first operation works from packaged baselines and local project
+  context; internet or SaaS enrichment is optional.
+
+## To-Be Outcome
+
+- SaaS-backed persona registry with tenant isolation, versioning, approval
+  workflows, audit trails, quality scores, and reusable persona packs.
+- Domain packs for software, music/audio, ML/AI, healthcare, data, security,
+  operations, education, legal/compliance, and other project types.
+- Optional state-of-the-art refresh pipeline that proposes persona updates from
+  curated references, prompt bank entries, lessons learned, and approved domain
+  packs.
+- Guarded supervisor can detect missing personas from project activity and
+  propose draft personas or capability changes.
+- Runtime scheduler and budget policies constrain generation, enrichment, and
+  multi-agent activation.
+- Chaos and resilience validation proves persona workflows degrade safely when
+  providers, registries, approvals, budgets, or context sources fail.
+
+## Persona Model
+
+Minimum fields:
+
+- `id`
+- `displayName`
+- `roleFamily`
+- `domain`
+- `purpose`
+- `responsibilities`
+- `activationTriggers`
+- `workflowPhases`
+- `requiredCapabilities`
+- `optionalCapabilities`
+- `requiredSkills`
+- `authorityLevel`: advisory, reviewer, approver, executor
+- `approvalConstraints`
+- `evidenceExpectations`
+- `securityConstraints`
+- `regulatoryScope`
+- `riskLevel`
+- `sourcePolicy`: packaged, project, generated, imported, external
+- `version`
+- `status`: draft, active, deprecated, rejected
+- `createdBy`
+- `approvedBy`
+- `provenance`
+
+## Proposed Child Stories
+
+### Story 1: Local Persona Registry API
+
+As a project owner, I want a typed local persona registry API so that personas
+can be managed without editing markdown files manually.
+
+Acceptance criteria:
+
+- Provides CLI/API operations: list, show, create, update, deactivate, approve,
+  reject, export, and import.
+- Persists project personas in workflow state with schema validation and
+  deterministic IDs.
+- Supports versioning and immutable approval provenance.
+- Prevents duplicate active personas with the same project ID and role family.
+- Exports approved personas to a portable version-controlled artifact.
+- Rejects malformed, oversized, conflicting, or partially imported persona data
+  without corrupting the registry.
+- Includes unit tests for create, update, approval, deactivation, import/export,
+  invalid schema, and duplicate prevention.
+
+Suggested size: M.
+
+Suggested owners: Architect, Developer, QA.
+
+### Story 2: Persona Generation Assistant
+
+As a project owner, I want Open Orchestra to generate draft personas from project
+needs and context so that I can define domain roles quickly without starting from
+a blank file.
+
+Acceptance criteria:
+
+- Generates draft personas from a requested role, domain, task context,
+  workflow phase, existing roles, local standards, lessons learned, and approved
+  prompt bank entries.
+- Uses offline packaged baselines first and optional external enrichment only
+  when enabled.
+- Marks generated personas as draft and inactive by default.
+- Records provenance: prompt id, context sources, model/provider when available,
+  generated timestamp, and reviewer requirements.
+- Applies prompt-injection and secret redaction checks to context before
+  generation.
+- Includes chaos/resilience tests for provider timeout, provider unavailable,
+  unsafe context, prompt registry unavailable, and budget exhaustion.
+- Includes tests for draft status, provenance, source filtering, offline mode,
+  and blocked unsafe context.
+
+Suggested size: L.
+
+Suggested owners: Product Owner, Architect, Security, Developer, QA.
+
+### Story 3: Domain Persona Packs
+
+As a project owner, I want reusable domain persona packs so that non-software
+projects can bootstrap relevant expert profiles.
+
+Acceptance criteria:
+
+- Defines packaged baseline packs for software delivery, music/audio, ML/AI,
+  healthcare, data/analytics, security, operations, and compliance.
+- Packs are compact metadata, not long prompt bodies.
+- Each pack declares default personas, capabilities, activation triggers,
+  evidence expectations, and risk constraints.
+- Healthcare and other regulated packs mark expert personas as human-approval
+  required for regulated decisions.
+- Includes tests for pack loading, filtering by domain, and high-risk activation
+  constraints.
+
+Suggested size: M.
+
+Suggested owners: Product Manager, Architect, Compliance/Privacy, QA.
+
+### Story 4: Runtime Persona Activation
+
+As a workflow runtime, I want to activate personas only when a task, phase, risk,
+or required role needs them so that context stays bounded and relevant.
+
+Acceptance criteria:
+
+- Resolves active personas from task signals, required roles, optional roles,
+  phase, paths, domain, risk level, and explicit user request.
+- Does not load every persona for every task.
+- Returns activation rationale and skipped-persona rationale.
+- Integrates with capability and skill resolution without duplicating
+  hardcoded role maps.
+- Blocks unapproved, rejected, deprecated, or policy-ineligible personas.
+- Includes chaos/resilience tests for corrupted registry state, missing
+  approvals, disabled persona packs, and provider-independent offline
+  activation.
+- Includes tests for phase-scoped activation, domain triggers, no-match cases,
+  high-risk human approval, and capability resolution.
+
+Suggested size: M.
+
+Suggested owners: Architect, Developer, QA.
+
+### Story 5: Persona Governance and Safety Gates
+
+As a security and compliance reviewer, I want persona creation and activation to
+respect authority boundaries so that generated personas cannot approve unsafe or
+regulated outcomes.
+
+Acceptance criteria:
+
+- Requires human approval before any generated persona becomes active.
+- Requires explicit human approver mapping for regulated authority levels.
+- Prevents generated medical, legal, financial, privacy, or regulatory personas
+  from issuing final approval unless policy allows a configured human approver.
+- Records audit events for generation, approval, rejection, activation, and
+  deactivation.
+- Adds security review when personas touch secrets, PII, PHI, financial data,
+  regulated decisions, network calls, or external references.
+- Includes chaos/resilience tests for approval race conditions, missing approver
+  mappings, policy engine failure, audit write failure, and denied regulated
+  authority escalation.
+- Includes tests for approval policy, audit events, blocked activation, and
+  unsafe authority escalation.
+
+Suggested size: M.
+
+Suggested owners: Security, Compliance/Privacy, Architect, QA.
+
+### Story 6: Web Console Persona Management
+
+As a human user, I want to manage project personas in the web console so that I
+can review and approve personas without editing local files.
+
+Acceptance criteria:
+
+- Adds a Personas management page or section with list, detail, create,
+  generate, edit draft, approve, reject, deactivate, export, and import flows.
+- Shows persona status, authority level, domain, risk, triggers, capabilities,
+  evidence expectations, and approval state.
+- Provides empty, loading, error, success, and recovery states.
+- Uses tooltips for authority level, regulated scope, activation triggers, and
+  evidence expectations.
+- Includes resilience coverage for API timeout, failed generation, rejected
+  approval, import validation failure, and stale registry data.
+- Includes Playwright coverage for list, create draft, approve, reject, and
+  high-risk warning flows.
+
+Suggested size: L.
+
+Suggested owners: UX/UI Designer, Developer, QA, Technical Writer.
+
+### Story 7: Persona Documentation and User Guide
+
+As a user, I want clear persona registry documentation so that I understand how
+to define domain experts, generated personas, and approval constraints.
+
+Acceptance criteria:
+
+- Documents CLI and API usage for persona registry operations.
+- Explains packaged personas, generated drafts, approval, activation, and
+  regulated-domain limits.
+- Includes examples for software, music/audio, ML/AI, and healthcare projects.
+- Documents offline-first behavior and optional SaaS/external enrichment.
+- Updates the public site docs if persona management becomes user-facing.
+
+Suggested size: S.
+
+Suggested owners: Technical Writer, Product Owner, QA.
+
+## Epic Acceptance Criteria
+
+- Persona registry avoids manual markdown editing for normal persona management.
+- Persona generation produces draft, reviewable personas, not automatically
+  active authorities.
+- Runtime activation is bounded by task need, phase, role, risk, and project
+  domain.
+- Regulated domains require explicit human approval policies.
+- Offline-first mode works without internet access.
+- SaaS/external enrichment is optional and tenant-scoped when enabled.
+- Child stories are independently estimable and testable.
+- Chaos testing validates safe degradation for persona registry, runtime
+  activation, generation, governance, and web console flows.
+
+## Non-Goals
+
+- Replacing built-in delivery roles in the first release.
+- Building a full SaaS registry in the MVP.
+- Allowing generated personas to approve regulated clinical, legal, financial,
+  or compliance outcomes without a configured human approver.
+- Making internet access mandatory for persona generation.
+- Storing raw prompts or sensitive project context by default.
+
+## Risks
+
+- Generated personas may sound authoritative without enough domain validation.
+- Prompt injection from lessons learned, issues, docs, or external references.
+- Secret or sensitive data leakage during persona generation.
+- Context bloat if runtime activation loads too many personas.
+- Tenant and regulatory boundary violations in SaaS mode.
+- Duplicate or conflicting personas if registry ownership is unclear.
+- Workflow degradation if multiple agents generate or activate personas while
+  providers, approval stores, or prompt/context registries are unavailable.
+
+## Chaos And Resilience Testing
+
+Persona features should load the `chaos-resilience-testing` skill for controlled
+failure scenarios where they affect runtime behavior or authority. The goal is
+not random fault injection in the first MVP; it is deterministic chaos-style
+validation that proves the product fails closed, preserves auditability, and
+keeps offline operation usable.
+
+Minimum scenarios:
+
+- provider timeout or unavailable model during persona generation;
+- prompt bank, lessons, or external enrichment source unavailable;
+- malformed, oversized, or partially imported persona registry data;
+- concurrent approval/update attempts for the same persona;
+- missing human approver mapping for regulated authority;
+- budget envelope exhausted before or during generation;
+- policy engine denies activation or fails closed;
+- audit/event write failure during approval or activation;
+- web console API timeout or stale registry response;
+- offline mode with no external network access.
+
+Expected behavior:
+
+- generated personas remain `draft` unless approval succeeds;
+- regulated personas cannot approve final outcomes without configured human
+  authority;
+- runtime activation skips unsafe personas and records the rationale;
+- unavailable optional sources degrade with explicit evidence instead of
+  blocking local workflows;
+- failures produce QA evidence that maps back to the story acceptance criteria.
+
+## Suggested Epic Size
+
+XL for full epic.
+
+MVP slice: L.
+
+Recommended first implementation order:
+
+1. Dynamic UX phase routing for user-facing work
+   (`UX-DYNAMIC-PHASE-ROUTING-20260517`) before the persona web console story.
+2. Local Persona Registry API.
+3. Runtime Persona Activation.
+4. Persona Governance and Safety Gates.
+5. Persona Generation Assistant.
+6. Web Console Persona Management.
+7. Domain Persona Packs.
+8. Documentation and user guide.
+
+## Related Workflow Story
+
+`UX-DYNAMIC-PHASE-ROUTING-20260517` should add dynamic UX routing for
+user-facing tasks before persona management UI is implemented. The current
+workflow can recommend `ux_review` after implementation, but it does not yet
+support a pre-architecture `ux_design` phase or BA/PO validation of UX artifacts
+before architecture.
+
+Expected target sequence for user-facing work:
+
+```txt
+po/ba -> ux_design -> po_validation -> architect -> developer -> qa -> ux_review -> release
+```
+
+The first implementation may keep this advisory when a task or global
+`workflow.phaseSequence` is manually configured, but the phase planner should
+make the recommendation explicit and explain why UX must provide design inputs
+before architecture for UI-heavy work.

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.