@jterrats/open-orchestra 1.0.1 → 1.0.3

package/docs/diagrams/v14-stress-test/stress-test.svg

@@ -0,0 +1,114 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="760" viewBox="0 0 1280 760" role="img" aria-labelledby="title desc">
+  <title id="title">V14 diagram acceptance stress test</title>
+  <desc id="desc">Stress diagram for generic layout validation of bounded text, connector label lanes, parent containment, and boundary endpoints.</desc>
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto">
+      <path d="M0 0 L10 5 L0 10 z" fill="#475569"/>
+    </marker>
+    <style>
+      .font{font-family:Arial,Helvetica,sans-serif}
+      .title{font-size:26px;font-weight:700;fill:#172033}
+      .subtitle{font-size:13px;fill:#4b596c}
+      .containerA{fill:#f5f9ff;stroke:#91add7;stroke-width:1.5}
+      .containerB{fill:#f7fbf5;stroke:#91bd9b;stroke-width:1.5}
+      .containerC{fill:#fff8f1;stroke:#dfad72;stroke-width:1.5}
+      .card{fill:#fff;stroke:#64748b;stroke-width:1.5}
+      .label{font-size:13px;font-weight:700;fill:#526174;text-transform:uppercase}
+      .cardTitle{font-size:17px;font-weight:700;fill:#1f2a3d}
+      .small{font-size:12px;fill:#445267}
+      .badgeText{font-size:11px;font-weight:700;fill:#fff}
+      .pill{fill:#fff;stroke:#d8dee8;stroke-width:1}
+      .pillText{font-size:12px;fill:#263445}
+      .edge{fill:none;stroke:#475569;stroke-width:2;marker-end:url(#arrow)}
+      .edgeSoft{fill:none;stroke:#64748b;stroke-width:2;stroke-dasharray:7 5;marker-end:url(#arrow)}
+      .note{font-size:12px;fill:#506074}
+    </style>
+  </defs>
+  <rect width="1280" height="760" fill="#fff"/>
+  <g class="font">
+    <text class="title" x="48" y="54">V14 Diagram Acceptance Stress Test</text>
+    <text class="subtitle" x="48" y="78">Source-free visual check for generic diagram layout rules.</text>
+
+    <rect class="containerA" x="62" y="130" width="314" height="438" rx="18"/>
+    <text class="label" x="92" y="164">Input Boundary</text>
+
+    <rect class="card" x="104" y="218" width="228" height="122" rx="12"/>
+    <circle cx="136" cy="252" r="17" fill="#2563eb"/>
+    <text class="badgeText" x="136" y="256" text-anchor="middle">IN</text>
+    <text class="cardTitle" x="168" y="248">Inbound Request</text>
+    <rect class="pill" x="126" y="274" width="178" height="38" rx="6"/>
+    <text class="pillText" x="136" y="290">long bounded chip</text>
+    <text class="pillText" x="136" y="306">wrapped safely</text>
+    <text class="small" x="126" y="330">boundary connector target</text>
+
+    <rect class="card" x="104" y="408" width="228" height="116" rx="12"/>
+    <circle cx="136" cy="442" r="17" fill="#4f46e5"/>
+    <text class="badgeText" x="136" y="446" text-anchor="middle">ID</text>
+    <text class="cardTitle" x="168" y="438">Identity Context</text>
+    <text class="small" x="126" y="472">claims, policy hints</text>
+    <text class="small" x="126" y="492">and trace metadata</text>
+
+    <rect class="containerB" x="470" y="116" width="356" height="520" rx="18"/>
+    <text class="label" x="500" y="150">Processing Region</text>
+
+    <rect class="card" x="520" y="212" width="244" height="124" rx="12"/>
+    <circle cx="552" cy="246" r="17" fill="#059669"/>
+    <text class="badgeText" x="552" y="250" text-anchor="middle">OR</text>
+    <text class="cardTitle" x="584" y="242">Orchestrator</text>
+    <text class="small" x="548" y="276">normalizes requests</text>
+    <text class="small" x="548" y="296">routes by policy</text>
+
+    <rect class="card" x="520" y="430" width="244" height="130" rx="12"/>
+    <circle cx="552" cy="464" r="17" fill="#0ea5e9"/>
+    <text class="badgeText" x="552" y="468" text-anchor="middle">WRK</text>
+    <text class="cardTitle" x="584" y="460">Worker Service</text>
+    <rect class="pill" x="548" y="484" width="186" height="54" rx="6"/>
+    <text class="pillText" x="558" y="501">bounded internal label</text>
+    <text class="pillText" x="558" y="517">wraps before it can</text>
+    <text class="pillText" x="558" y="533">touch nearby routes</text>
+
+    <rect class="containerC" x="918" y="130" width="292" height="438" rx="18"/>
+    <text class="label" x="948" y="164">External Region</text>
+
+    <rect class="card" x="958" y="230" width="210" height="116" rx="12"/>
+    <circle cx="990" cy="264" r="17" fill="#dc2626"/>
+    <text class="badgeText" x="990" y="268" text-anchor="middle">EXT</text>
+    <text class="cardTitle" x="1022" y="260">External System</text>
+    <text class="small" x="980" y="294">contract endpoint</text>
+    <text class="small" x="980" y="314">bounded response</text>
+
+    <rect class="card" x="958" y="418" width="210" height="106" rx="12"/>
+    <circle cx="990" cy="452" r="17" fill="#d97706"/>
+    <text class="badgeText" x="990" y="456" text-anchor="middle">LOG</text>
+    <text class="cardTitle" x="1022" y="448">Telemetry Sink</text>
+    <text class="small" x="980" y="482">events, logs</text>
+    <text class="small" x="980" y="502">metrics</text>
+
+    <path class="edge" d="M376 278 H470"/>
+    <rect class="pill" x="394" y="248" width="126" height="20" rx="4"/>
+    <text class="pillText" x="402" y="262">boundary handoff</text>
+
+    <path class="edge" d="M332 466 H520"/>
+    <rect class="pill" x="360" y="438" width="106" height="20" rx="4"/>
+    <text class="pillText" x="368" y="452">context merge</text>
+
+    <path class="edge" d="M642 336 V430"/>
+    <rect class="pill" x="662" y="374" width="120" height="38" rx="4"/>
+    <text class="pillText" x="670" y="390">multi-line</text>
+    <text class="pillText" x="670" y="406">route label</text>
+
+    <path class="edge" d="M764 274 H918"/>
+    <rect class="pill" x="792" y="218" width="132" height="38" rx="4"/>
+    <text class="pillText" x="800" y="234">clear label lane</text>
+    <text class="pillText" x="800" y="250">above connector</text>
+
+    <path class="edgeSoft" d="M764 496 H958"/>
+    <rect class="pill" x="792" y="512" width="142" height="38" rx="4"/>
+    <text class="pillText" x="800" y="528">async evidence</text>
+    <text class="pillText" x="800" y="544">label below lane</text>
+
+    <rect class="pill" x="520" y="654" width="292" height="54" rx="8"/>
+    <text class="note" x="536" y="675">Long note wraps inside its own bounded shape</text>
+    <text class="note" x="536" y="693">and stays clear of connectors and containers.</text>
+  </g>
+</svg>

package/docs/external-artifact-import-bridge.md

@@ -0,0 +1,56 @@
+# External Artifact Import Bridge
+
+Open Orchestra can import optional external workflow artifacts without making the
+runtime depend on product-specific setup flows.
+
+## Command Surface
+
+This bridge should be exposed through a neutral import command before it becomes
+part of public user documentation.
+
+The expected machine-readable report includes imported, skipped, and conflicted
+profiles, tasks, evidence references, and handoff references.
+
+## Supported Inputs
+
+The importer reads compatible profile, task, evidence, and handoff records from
+the configured source directory. Task records may use either sparse legacy fields
+or enriched delivery fields.
+
+Supported task fields include:
+
+- `id`, `title`, `summary`
+- `owner`, `ownerRole`, `role`, `profile`, `profileId`
+- `backlogItem`, `backlog`
+- `userStory`, `goal`, `scope`
+- `acceptanceCriteria`
+- `definitionOfReady`, `definitionOfDone`
+- `dependencies`, `dependsOn`
+- `risks`, `assumptions`, `paths`, `files`
+- `testStrategy`
+- `contractVersion`
+- `acceptanceStatus`, `acceptedBy`
+- `evidenceIds`, `evidence`
+- `handoffIds`, `handoffs`
+
+## Mapping Rules
+
+Profile role mappings are read from the external profile metadata when present.
+External role IDs are normalized to Orchestra role IDs such as `qa`,
+`developer`, `product_owner`, and `product_manager`. Unknown owner roles are
+treated as conflicts during profile import and fall back to `developer` for
+sparse task records.
+
+Imported tasks preserve external metadata under an implementation-specific
+external reference object. Evidence and handoff IDs are stored as references
+there; the importer does not copy or mutate the original external artifacts.
+
+## Idempotency And Conflicts
+
+Re-running the import does not duplicate tasks. If an existing task has the
+same ID, title, and owner role, the task is reported as skipped. If the ID
+matches but title or owner differs, the importer reports a conflict and leaves
+the existing Orchestra task unchanged.
+
+Each import records an import event with summary counts so the
+story-to-evidence trail remains auditable.

package/docs/{setup-agents-applicability-review.md → external-baseline-applicability-review.md}

@@ -1,25 +1,25 @@
-# setup-agents Applicability Review
+# External Baseline 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.
+Review recent external baseline issues and local engineering 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
+- External baseline issues #198-#211, with emphasis on #211, #209, #208, #205,
+  #204, #203, #202, #201, #200, #199, #198
+- Local developer profile and generated Developer standards from the external baseline
+- Open Orchestra external artifact import bridge and standards rules
 
 ## Applies Directly
 
 ### Visual Post-Write Validation
 
-Source: setup-agents #211 and Open Orchestra #317.
+Source: external baseline #211 and Open Orchestra #317.
 
 This applies directly. Open Orchestra is the orchestrator and should own the
 generic gate contract:
@@ -34,22 +34,21 @@ generic gate contract:
 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
+### External 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.
+Open Orchestra currently imports role aliases from external artifact payloads.
+Core Open Orchestra roles are `product_owner` and `product_manager`. Imported
+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.
+Source: external baseline #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:
+calibration belongs in Open Orchestra so every stack benefits. The useful
+contract is:
 
 - estimates read completed run benchmark data when available
 - output includes historical median and variance
@@ -59,7 +58,7 @@ Salesforce. The useful contract is:
 
 ### Playbook Scaffolding And Playbook Authoring Docs
 
-Sources: setup-agents #204 and #201.
+Sources: external baseline #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
@@ -67,7 +66,7 @@ without reading source. This applies cross-stack.
 
 ### Gate vs Clarify Documentation
 
-Source: setup-agents #202.
+Source: external baseline #202.
 
 Open Orchestra exposes gates, reviews, decisions, and clarification patterns.
 The distinction should be documented in Open Orchestra user docs and runtime
@@ -75,15 +74,15 @@ 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.
+Sources: external baseline #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.
+versus human-approved. This is product documentation.
 
 ### Rules Health / Generated Guidance Freshness
 
-Source: setup-agents #203.
+Source: external baseline #203.
 
 Open Orchestra already generates bootstrap and managed instruction blocks. A
 health surface that reports stale generated guidance, missing playbooks, and
@@ -91,11 +90,11 @@ workflow readiness would apply directly.
 
 ## Applies As A Pattern, Not Literally
 
-### API 66 Salesforce Agent Metadata CI/CD
+### Specialized Metadata CI/CD
 
-Source: setup-agents #209.
+Source: external baseline #209.
 
-The Salesforce metadata details do not belong in Open Orchestra core, but the
+Product-specific metadata details do not belong in Open Orchestra core, but the
 pattern does:
 
 - deployment lanes are not always one generic deploy command
@@ -104,20 +103,19 @@ pattern does:
 - 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.
+playbook checks, not as product-specific deployment logic.
 
 ### Auto-Run Local Rule Generation After Init
 
-Source: setup-agents #208.
+Source: external baseline #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.
+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
+Several reviewed Developer standards are product-specific, but the underlying
 rules are stack-agnostic and should remain or be strengthened in Open Orchestra:
 
 - Read project metadata/config before generating code.
@@ -145,29 +143,28 @@ rules are stack-agnostic and should remain or be strengthened in Open Orchestra:
 
 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.
+without carrying product-specific terminology 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.
+- Product-specific publish or activation commands.
+- Product-specific generated metadata folders.
+- Product-specific UI implementation rules.
+- Product-specific server-side naming and permission idioms as literal rules.
 
-These belong in Salesforce/setup-agents profiles, not Open Orchestra core.
+These belong in product-specific 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.
+2. Fix external 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/{setup-agents-dogfooding-findings.md → external-baseline-dogfooding-findings.md}

@@ -1,7 +1,7 @@
-# Setup Agents Dogfooding Findings
+# External Baseline Dogfooding Findings
 
-This file tracks issues found while using Open Orchestra to coordinate the
-`setup-agents` improvement backlog.
+This file tracks issues found while using Open Orchestra to coordinate an
+external improvement backlog.
 
 ## Finding 1: Concurrent `task add` commands can corrupt `tasks.json`
 
@@ -9,7 +9,7 @@ This file tracks issues found while using Open Orchestra to coordinate the
 - **Status:** fixed in Open Orchestra
 
 - **Date found:** 2026-05-06
-- **Source repo:** `/Users/polux/dev/setup-agents`
+- **Source context:** external local repository
 - **Command pattern:** multiple `node_modules/.bin/orchestra task add ...` commands executed concurrently
 - **Observed behavior:** `.agent-workflow/tasks.json` ended up with trailing partial JSON and subsequent Orchestra commands failed with `Unexpected non-whitespace character after JSON`.
 - **Impact:** users or automation that parallelize CLI calls can corrupt workflow state.
@@ -24,7 +24,7 @@ This file tracks issues found while using Open Orchestra to coordinate the
 - **Status:** fixed in Open Orchestra
 
 - **Date found:** 2026-05-06
-- **Source repo:** `/Users/polux/dev/setup-agents`
+- **Source context:** external local repository
 - **Command pattern:** `orchestra evidence add --type validation ...`
 - **Observed behavior:** the command failed with `type must be one of: command, file, screenshot, trace, video, log, report`.
 - **Impact:** users must know the closed evidence type list before calling the command.
@@ -39,7 +39,7 @@ This file tracks issues found while using Open Orchestra to coordinate the
 - **Status:** fixed in Open Orchestra
 
 - **Date found:** 2026-05-06
-- **Source repo:** `/Users/polux/dev/setup-agents`
+- **Source context:** external local repository
 - **Command pattern:** `orchestra review --task SA-90 --role reviewer --result approve ...`
 - **Observed behavior:** the command failed with `unknown reviewer role: reviewer`.
 - **Impact:** the role catalog and README describe a Reviewer / Critic capability, but the review command does not accept the intuitive `reviewer` role id.
@@ -54,7 +54,7 @@ This file tracks issues found while using Open Orchestra to coordinate the
 - **Status:** fixed in Open Orchestra
 
 - **Date found:** 2026-05-06
-- **Source repo:** `/Users/polux/dev/setup-agents`
+- **Source context:** external local repository
 - **Command pattern:** multiple `node_modules/.bin/orchestra lock claim ...` commands executed concurrently
 - **Observed behavior:** two distinct locks were created with the same id, `lock-1778052846730`, for different paths.
 - **Impact:** `lock release --id <id>` becomes ambiguous and can release the wrong lock or require manual state repair.
@@ -69,7 +69,7 @@ This file tracks issues found while using Open Orchestra to coordinate the
 - **Status:** fixed in Open Orchestra
 
 - **Date found:** 2026-05-06
-- **Source repo:** `/Users/polux/dev/setup-agents`
+- **Source context:** external local repository
 - **Command pattern:** `node_modules/.bin/orchestra init --force`
 - **Observed behavior:** generated `AGENTS.md` and `ORCHESTRA.md` bootstrap blocks recommend commands such as `node bin/orchestra.js health --json` and `node bin/orchestra.js task list --json`.
 - **Impact:** those examples only work inside the Open Orchestra repository layout. When Open Orchestra is installed into another repository as a package or local file install, the consumer repo does not have `bin/orchestra.js`, so agents following the generated bootstrap will run the wrong command.
@@ -84,7 +84,7 @@ This file tracks issues found while using Open Orchestra to coordinate the
 - **Status:** fixed in Open Orchestra
 
 - **Date found:** 2026-05-06
-- **Source repo:** `/Users/polux/dev/open-orchestra`
+- **Source context:** Open Orchestra repository
 - **Command pattern:** multiple `orchestra evidence add ...` commands executed concurrently
 - **Observed behavior:** two distinct `EVIDENCE_ADDED` events pointed to the same artifact file when they were created in the same millisecond.
 - **Impact:** the later evidence write overwrote the earlier evidence content, leaving one event pointing to mismatched artifact content.
@@ -99,3 +99,4 @@ This file tracks issues found while using Open Orchestra to coordinate the
 - JSON state files are written through temporary files and atomic rename to avoid partial JSON on interruption.
 - The lock mechanism is intended for local filesystems. Network filesystems or stale lock directories after a killed process may require manual cleanup if a command times out waiting for a lock.
 - State-mutating Orchestra commands should still prefer explicit task/path locks when multiple agents edit code, because file serialization protects workflow metadata, not source-code merge conflicts.
+

package/docs/multi-agent-orchestrator-backlog.md

@@ -695,7 +695,7 @@ Acceptance criteria:
 - UI supports adding a lesson with required fields.
 - UI supports promoting lessons to a reviewable artifact.
 
-## Epic 18: Setup Agents Feature Harvest
+## Epic 18: External Baseline Feature Harvest
 
 ### Story UPD-001: Detect Stale Generated Instruction Files
 As a maintainer, I want Open Orchestra to detect stale generated instruction files without touching user-authored files so that runtime adapters can be safely refreshed.

package/docs/orchestra-mvp.md

@@ -34,6 +34,14 @@ Generated register files:
 
 Existing register files are preserved unless `orchestra init --force` is used.
 
+Generated runtime guidance uses managed instruction blocks instead of taking
+ownership of complete files. If a project already has `AGENTS.md`, `CLAUDE.md`,
+Cursor rules, or `ORCHESTRA.md`, Open Orchestra appends its marked block and
+preserves user-authored content outside the block. Later refreshes update only
+the matching Open Orchestra block. Manual edits inside a managed block are
+reported as drift and are not overwritten unless `--force` is used; forced
+updates still replace only that block.
+
 ## Skills and Context Loading
 
 Open Orchestra should treat skills as demand-loaded capabilities. Main files such as `AGENTS.md`, `CLAUDE.md`, Cursor rules, and `ORCHESTRA.md` should contain a compact index and activation rules, while detailed procedures live in skill files. See [skill-loading-strategy.md](skill-loading-strategy.md).
@@ -238,6 +246,17 @@ coverage remains available.
 
 Release go/no-go:
 
+- Release tags are CI-owned for normal releases. Humans and local agents should
+  bump `package.json` and `package-lock.json`, commit, and push the release
+  candidate; they should not create or push the release tag locally unless a
+  documented break-glass release decision approves it.
+- The `Create release tag` workflow resolves the tag from `package.json`, checks
+  that it matches `v<package version>`, runs the configured precommit gate, then
+  creates the annotated tag, creates the GitHub Release, and triggers npm
+  publish.
+- If the intended tag already exists remotely, do not move or overwrite it.
+  Bump to the next patch/prerelease version or record an explicit rollback or
+  break-glass decision.
 - 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,

package/docs/persona-workflows.md

@@ -228,6 +228,48 @@ Recovery:
 Related docs: [upgrade dogfooding](orchestra-mvp.md),
 [package naming](package-naming.md), and [release readiness](orchestra-mvp.md).
 
+## Technical Writer Review
+
+Goal: keep public documentation, site copy, command examples, release notes, and
+help content accurate for the intended audience.
+
+Commands:
+
+```bash
+orchestra workflow phase-plan --task STORY-001 --json
+orchestra doc-sync audit --task STORY-001 --json
+orchestra review --task STORY-001 --role technical_writer --result approve \
+  --findings "Docs, links, commands, and generated site content reviewed" \
+  --recommendation "Documentation ready for release"
+```
+
+Expected artifacts:
+
+- Technical Writer review in `.agent-workflow/reviews/`.
+- Documentation diff or link evidence for updated docs, README, changelog,
+  release notes, runbooks, help content, or public site copy.
+- Site QA evidence when generated site content, diagrams, visible copy, or
+  responsive layout changes.
+
+Common blockers:
+
+- Public site copy is hardcoded in React instead of generated from
+  `docs/site-manifest.json`.
+- Command examples were not validated against the CLI, command manifest, or
+  build output.
+- `docs/architecture.md` and `site/public/architecture.mmd` describe different
+  diagrams.
+
+Recovery:
+
+- Update the source markdown or manifest, then run `npm run site:content`.
+- Run `npm run site:build` and capture screenshots for visible site changes.
+- Use `orchestra doc-sync audit --task <id> --json` to find missing
+  documentation coverage.
+
+Related docs: [public site content workflow](site-content-workflow.md),
+[adoption guide](adoption-guide.md), and [release matrix](release-test-matrix.md).
+
 ## Docs Review Checklist
 
 Before release, verify:

package/docs/release-test-matrix.md

@@ -17,6 +17,18 @@ execution summary as release test matrix evidence before running:
 orchestra release check --json
 ```
 
+## Tag And Publish Ownership
+
+For normal releases, the release commit contains the version bump and CI owns
+tag creation. Do not create or push release tags locally. Push the committed
+version bump to `main`; the `Create release tag` workflow validates that the tag
+equals `v<package.json version>`, creates the annotated tag, creates the GitHub
+Release, and triggers `publish-npm.yml`.
+
+If the remote tag already exists, do not move it. Use the next patch or
+prerelease version unless an explicit break-glass release decision documents why
+manual intervention is required.
+
 ## Required Environments
 
 - `ubuntu-latest` with Node `>=22` and npm.
@@ -25,15 +37,15 @@ orchestra release check --json
 
 ## 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 |
+| 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 checks map scenario acceptance criteria to visible UI state, API persistence, artifact attachment, responsive layout, and recovery behavior                 |
+| Installed package init | `npm run test:e2e:init`               | Installed CLI checks map scenario acceptance criteria to stdout, stderr, exit code, filesystem state, JSON contracts, evidence records, and release-readiness outcomes |
+| 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