@jterrats/open-orchestra 0.1.0 → 0.3.0

package/docs/open-orchestra-dogfooding-findings.md

@@ -0,0 +1,66 @@
+# Open Orchestra Dogfooding Findings
+
+This file records what Open Orchestra contributed while building Open Orchestra
+itself, plus issues found by using the CLI as the local control plane.
+
+## What Helped
+
+- **Backlog alignment:** GitHub issues, local `.agent-workflow/tasks.json`, and
+  semantic commits stayed tied to backlog IDs such as `ROLE-003`, `WFLOW-001`,
+  and `BUG-087`.
+- **Explicit delegation:** `orchestra delegation decide` made role selection
+  visible before implementation, including write scopes and expected outputs.
+- **Evidence discipline:** fixes were closed with command evidence,
+  reviewer records, and `npm run precommit` results instead of relying on a
+  prose claim.
+- **Bug discovery:** concurrent state writes exposed real bugs in task and lock
+  mutation safety. Those became tracked fixes instead of one-off manual repairs.
+- **Context control:** skills, source-of-truth, lessons, protocols, and workflow
+  templates kept primary instruction files smaller while preserving task-specific
+  context.
+- **Runtime portability:** the same workflow state supported Codex, CLI, web/API,
+  VS Code extension scaffolding, and future Claude/Cursor instruction renders.
+
+## Finding: Parallel Independent Commands Are Safe So Far
+
+- **Date checked:** 2026-05-06
+- **Workspace:** `/tmp/oo-parallel-dogfood`
+- **Commands tested in parallel:** `task add`, `delegation decide`,
+  duplicate `task add`, same-path `lock claim`, `validate`, `task list`, and
+  concurrent `evidence add`.
+- **Observed behavior:** independent writes serialized correctly. Duplicate
+  tasks failed with `task already exists`. Same-path locks allowed one winner
+  and blocked the second. Concurrent evidence writes produced distinct artifacts
+  and a valid event log.
+- **Validation:** `orchestra validate --json` returned valid after the stress
+  run.
+
+## Finding: Parallel Dependent Commands Need DAG Semantics
+
+- **Date found:** 2026-05-06
+- **Observed behavior:** when a parent agent schedules `task add` and an
+  immediate dependent command such as `delegation decide --task <id>` in the
+  same parallel batch, the dependent command can run before the task exists and
+  fail with `unknown task`.
+- **Impact:** this is not state corruption, but it creates noisy false failures
+  when the parent agent treats dependent steps as independent parallel work.
+- **Recommended product fix:** add a future batch runner with explicit
+  `dependsOn` ordering, or make dependent command failures retryable when the
+  missing task is being created in the same batch.
+- **Current workaround:** only run independent Open Orchestra commands in
+  parallel. Run `task add` before `context`, `delegation`, `plan`, `review`, or
+  `evidence` for that task.
+
+## Finding: Renamed Project Paths Must Be Revalidated Before Generation
+
+- **Date found:** 2026-05-06
+- **Observed behavior:** after the project directory moved from `cursor-rules`
+  to `open-orchestra`, a file-generation tool attempted to write new files
+  through stale path context.
+- **Impact:** generated files can be created outside the intended repo, leaving
+  imports in the current repo pointing at missing files.
+- **Recommended product fix:** add a workspace guard that verifies `cwd`,
+  `package.json`, and `.git` root before generated file writes.
+- **Current workaround:** after a rename or context transition, run
+  `pwd`, `git status --short`, and `ls` for every newly generated file before
+  continuing.

package/docs/orchestra-mvp.md

@@ -11,6 +11,31 @@ It stores workflow state in `.agent-workflow/` and coordinates agents through fi
 - Existing `AGENTS.md`, `CLAUDE.md`, Cursor rules, and generated instruction files remain supported entry points.
 - `ORCHESTRA.md` is the intended future primary guide name; it is not required for existing projects.
 
+## Prompt Registry
+
+Open Orchestra initializes `.generated-prompts/` beside `.agent-workflow/`. The prompt registry stores the latest prompt intent and generation context by artifact type so future agents can preserve conventions without loading all history into the main instruction files.
+
+Generated register files:
+
+```text
+.generated-prompts/
+  cicd.md
+  code.md
+  diagrams.md
+  docs.md
+  evals.md
+  services.md
+  tests.md
+  ui.md
+```
+
+Existing register files are preserved unless `orchestra init --force` is used.
+
+## 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).
+
+
 ## Commands
 
 ```bash
@@ -41,6 +66,22 @@ node bin/orchestra.js lock list
 node bin/orchestra.js lock release --id lock-123
 node bin/orchestra.js roles list
 node bin/orchestra.js roles list --json
+node bin/orchestra.js skills list
+node bin/orchestra.js skills list --json
+node bin/orchestra.js skills plan --task TASK-1
+node bin/orchestra.js skills plan --task TASK-1 --json
+node bin/orchestra.js skills render --target generic --task TASK-1
+node bin/orchestra.js skills render --target claude --task TASK-1
+node bin/orchestra.js skills render --target cursor --skills static-analysis,playwright-evidence
+node bin/orchestra.js skills render --target codex --task TASK-1
+node bin/orchestra.js skills render --target vscode --task TASK-1 --json
+node bin/orchestra.js skills validate
+node bin/orchestra.js skills validate --json
+node bin/orchestra.js sources list
+node bin/orchestra.js sources list --json
+node bin/orchestra.js lessons list
+node bin/orchestra.js lessons add --operation "shell edit" --failed-action "bad escaping" --error-signature "syntax error" --root-cause "unescaped token" --fix "escape token" --prevention "dry run first" --applies-to node,markdown --verified-by precommit
+node bin/orchestra.js lessons promote --to doc --filter escaping
 node bin/orchestra.js readiness --task TASK-1
 node bin/orchestra.js gate --gate architecture --task TASK-1
 node bin/orchestra.js gate --gate qa-release --task TASK-1
@@ -81,6 +122,86 @@ node bin/orchestra.js model set-role --role developer --provider openai --model
 node bin/orchestra.js model complete-fake --provider primary --model fake-model --prompt "hello" --fallbacks backup --fail-provider primary
 node bin/orchestra.js model provenance add --task TASK-1 --role developer --provider openai --model gpt-example --prompt-id prompt-1 --response-id response-1 --finish-reason stop
 node bin/orchestra.js model provenance list --task TASK-1 --json
+
+# Autonomous workflow
+node bin/orchestra.js workflow run --task TASK-1 --dry-run --gates phase
+node bin/orchestra.js workflow run --task TASK-1 --gates none
+node bin/orchestra.js workflow run --task TASK-1 --gates phase
+node bin/orchestra.js workflow run --task TASK-1 --gates all
+node bin/orchestra.js workflow run --task TASK-1 --resume <run-id>
+node bin/orchestra.js workflow runs
+node bin/orchestra.js workflow runs --json
+
+# Clarification loop
+node bin/orchestra.js workflow clarify --run <run-id> --from developer --to po --question "..."
+node bin/orchestra.js workflow clarify --run <run-id> --from developer --to architect --question "..."
+node bin/orchestra.js workflow clarify --run <run-id> --from qa --to po --question "..."
+node bin/orchestra.js workflow clarify-respond --run <run-id> --clarification <id> --answer "..."
+node bin/orchestra.js workflow clarify-list --run <run-id>
+node bin/orchestra.js workflow clarify-list --run <run-id> --json
+
+# Benchmark & burndown
+node bin/orchestra.js estimate --task TASK-1 --sizing m --solo-days 5 --ai-unguided-days 3
+node bin/orchestra.js estimate --task TASK-1 --sizing l --solo-days 8 --ai-unguided-days 5 --confidence high --declared-by pm --json
+node bin/orchestra.js benchmark --task TASK-1
+node bin/orchestra.js benchmark --task TASK-1 --json
+node bin/orchestra.js benchmark --summary
+node bin/orchestra.js benchmark --summary --json
+node bin/orchestra.js burndown --sprint TASK-1,TASK-2,TASK-3
+node bin/orchestra.js burndown --sprint TASK-1,TASK-2,TASK-3 --json
+```
+
+## Autonomous Workflow Engine
+
+`orchestra workflow run` executes a full story lifecycle as a governed multi-phase sequence. Each phase creates a sub-task, generates handoff artifacts, and persists state in an append-only run log.
+
+```
+PM → PO [gate] → Architect [sizing gate] → Developer → QA [gate] → Release
+```
+
+```bash
+# Inspect the phase graph without persisting state
+orchestra workflow run --task FEAT-001 --dry-run --gates phase
+
+# Fully autonomous — no human approval required
+orchestra workflow run --task FEAT-001 --gates none
+
+# Gate-controlled — pauses at po→architect and qa→release
+orchestra workflow run --task FEAT-001 --gates phase
+
+# Resume a paused or clarification-suspended run
+orchestra workflow run --task FEAT-001 --resume <run-id>
+
+# List all runs with status and phase trace
+orchestra workflow runs
+```
+
+**Architect sizing gate:** always enforced regardless of `--gates` mode. The architect must record a sizing decision (`xs/s/m/l/xl`) before the developer phase starts. If missing, the run fails with the exact command to resolve it:
+
+```bash
+orchestra decision add --task FEAT-001 --owner architect \
+  --title "Story sizing" --decision "m [5 points]" \
+  --context "..." --consequences "..." --status accepted
+```
+
+### Clarification Loop
+
+Developers or QA engineers can surface blocking questions to the PO or architect mid-phase without abandoning the run.
+
+```bash
+# Open a clarification (suspends the active developer/qa phase)
+orchestra workflow clarify --run <run-id> --from developer --to po \
+  --question "Should empty input return null or throw?"
+
+# Answer the clarification (resumes the phase)
+orchestra workflow clarify-respond --run <run-id> --clarification <id> \
+  --answer "Return null — downstream handles it."
+
+# Resume execution after the answer
+orchestra workflow run --task FEAT-001 --resume <run-id>
+
+# Inspect all clarifications for a run
+orchestra workflow clarify-list --run <run-id>
 ```
 
 ## Workflow Files
@@ -92,6 +213,11 @@ node bin/orchestra.js model provenance list --task TASK-1 --json
   tasks.json
   locks.json
   events.jsonl
+  workflow-runs.jsonl       ← autonomous run state (append-only)
+  clarifications.jsonl      ← clarification loop records (append-only)
+  estimates.jsonl           ← declared effort baselines (append-only)
+  source-of-truth.json
+  agent-lessons.jsonl
   approvals/
   decisions/
   handoffs/
@@ -121,7 +247,9 @@ The role catalog JSON includes capabilities, required handoff fields, blocking a
 
 Open Orchestra initializes a broad role catalog but does not require every role to participate in every task. The parent/orchestrator should activate roles based on task type, risk, touched paths, impact areas, and gate requirements.
 
-Default roles include delivery roles such as Product Manager, Product Owner, Business Analyst, Architect, Developer, QA, Security, DevOps, SRE, DBA, UX/UI Designer, Release Manager, Compliance/Privacy, and Technical Writer. They also include orchestration roles for modern multi-agent systems: Planner, Reviewer/Critic, Toolsmith, Context Curator, Policy/Governance, Observability/Incident Response, Data/Privacy Officer, Domain Expert, UX Researcher/Accessibility Reviewer, Performance Engineer, and Game Designer.
+Default roles include delivery and specialist roles such as Product Manager, Product Owner, Business Analyst, Architect, Developer, Tech Lead, Frontend Specialist, Backend Specialist, Mobile Specialist, QA, SDET, Security, DevOps, Platform Engineer, SRE, DBA, UX/UI Designer, Release Manager, Compliance/Privacy, Technical Writer, AI Evaluation Engineer, and Support/Customer Operations. They also include orchestration roles for modern multi-agent systems: Planner, Reviewer/Critic, Toolsmith, Context Curator, Policy/Governance, Observability/Incident Response, Data/Privacy Officer, Domain Expert, UX Researcher/Accessibility Reviewer, Performance Engineer, and Game Designer.
+
+Specialist profiles and their source rationale are documented in [dev-team-specialist-role-profiles.md](dev-team-specialist-role-profiles.md).
 
 Each default role declares:
 
@@ -167,10 +295,40 @@ The VS Code Control Center scaffold is under `extensions/vscode-open-orchestra`.
 - `src/commands.ts` is the CLI adapter: it parses command options, delegates to services, and renders terminal output.
 - Services accept an explicit repo root, so future web, GitHub Actions, Playwright, or multi-model orchestration layers can reuse the same core without depending on `process.cwd()`.
 
+## Benchmark & Sprint Burndown
+
+`orchestra estimate` declares the three-mode effort baseline at story start. After the autonomous run completes, `orchestra benchmark` joins the declared estimate with the actual cycle time and quality signals automatically computed from the event log.
+
+Quality signals collected automatically:
+- `REVIEW_RECORDED` events → review count, blocking reviews (result=block or severity high/critical)
+- `EVIDENCE_ADDED` events → evidence artifact count
+- `LESSON_RECORDED` events → lesson count
+- `GATE_BLOCKED` events → gate block count
+- `MODEL_PROVENANCE_RECORDED` events → total tokens, estimated cost
+
+```bash
+# Declare baseline at story start (once per story)
+orchestra estimate --task TASK-1 --sizing m --solo-days 5 --ai-unguided-days 3
+
+# Per-story benchmark after run completes
+orchestra benchmark --task TASK-1
+
+# Sprint summary table across all stories with estimates
+orchestra benchmark --summary
+
+# Sprint burndown (developer points > architect points as fallback)
+orchestra burndown --sprint TASK-1,TASK-2,TASK-3
+```
+
+See [benchmark.md](benchmark.md) for the full reference.
+
 ## Current Scope
 
-- No real LLM calls.
+- Autonomous workflow engine (`workflow run`) executes the full PM→PO→Architect→Developer→QA→Release phase sequence with configurable human gates and an architect sizing gate.
+- Clarification loop (`workflow clarify`) allows developer and QA phases to surface blocking questions to PO or architect without abandoning the run.
+- Benchmark (`orchestra estimate` + `orchestra benchmark`) compares declared effort baselines against actual cycle time and automatically collected quality signals from the event log.
+- Sprint burndown (`orchestra burndown`) computes ideal vs actual lines from developer or architect story point estimates.
+- No real LLM calls in the autonomous engine — phases complete deterministically and generate handoff artifacts; LLM execution per phase is a future layer.
 - No automatic code editing.
-- No Playwright generation yet.
 - Python workers are represented in config only and disabled by default.
 - Static analysis is enforced locally through `.githooks/pre-commit` after running `npm run hooks:install`.

package/docs/runtime-adapters.md

@@ -0,0 +1,86 @@
+# Runtime Adapters
+
+Open Orchestra uses one adapter catalog for LLM runtimes, IDEs, and CLI agents.
+The catalog keeps target names, default files, managed-block support, structured
+payload support, and usage guidance in one place.
+
+## Adapter Catalog
+
+```bash
+node bin/orchestra.js runtime adapters --json
+```
+
+Current targets:
+
+- `generic`: provider-agnostic Markdown in `ORCHESTRA.md`.
+- `claude`: Claude project memory in `CLAUDE.md`.
+- `cursor`: Cursor MDC rules in `.cursor/rules/open-orchestra.mdc`.
+- `codex`: Codex instructions in `AGENTS.md`.
+- `vscode`: extension/chat payloads in `.vscode/open-orchestra.runtime.json`
+  and `.vscode/open-orchestra.md`.
+- `windsurf`: Windsurf rules in `.windsurf/rules/open-orchestra.md`.
+
+## Init Modes
+
+Default project init keeps the current compact bootstrap behavior:
+
+```bash
+node bin/orchestra.js init
+```
+
+Generate only selected runtime files:
+
+```bash
+node bin/orchestra.js init --target claude,cursor,windsurf
+```
+
+Advisory mode creates workflow state without root instruction files unless a
+target is explicit:
+
+```bash
+node bin/orchestra.js init --advisory
+node bin/orchestra.js init --advisory --target claude
+```
+
+Unsafe roots are blocked before writes. Unknown non-temp directories require an
+explicit confirmation:
+
+```bash
+node bin/orchestra.js init --confirm-unknown
+```
+
+## Runtime Loop
+
+After init, any runtime should use the same local control-plane loop:
+
+```bash
+node bin/orchestra.js health --json
+node bin/orchestra.js task list --json
+node bin/orchestra.js context --task STORY-001 --json
+node bin/orchestra.js delegation decide --task STORY-001 --json
+node bin/orchestra.js skills render --target codex --task STORY-001
+node bin/orchestra.js protocol render --target codex --task STORY-001
+node bin/orchestra.js workflow render --target codex --task STORY-001
+```
+
+Change `--target` to the runtime that is executing the work. The workflow state,
+roles, evidence, reviews, and gates remain runtime-agnostic.
+
+## Web And VS Code
+
+The local web console exposes workspace classification and supported runtime
+targets through:
+
+```bash
+node bin/orchestra.js web
+```
+
+The API contracts are:
+
+```bash
+curl -s http://127.0.0.1:3717/api/workspace/classification
+curl -s http://127.0.0.1:3717/api/runtime/adapters
+```
+
+These endpoints are intended for VS Code, Cursor-like extensions, and other
+clients that need to show safe next actions without parsing human CLI output.

package/docs/runtime-llm-flow.md

@@ -0,0 +1,124 @@
+# Runtime LLM Flow
+
+Open Orchestra is the local control plane. The active LLM runtime is the parent
+agent today.
+
+That means Claude, Codex, Cursor, VS Code, Windsurf, or another LLM starts the
+work, reads the relevant project instructions, and calls `orchestra` commands to
+coordinate tasks, roles, skills, handoffs, reviews, evidence, gates, and model
+routing metadata. Open Orchestra does not yet spawn real provider-backed
+subagents by itself.
+
+## Startup Flow
+
+Use this sequence for a new project or a new task:
+
+```bash
+node bin/orchestra.js init
+node bin/orchestra.js health --json
+node bin/orchestra.js task add --id STORY-001 --title "Short title" --owner developer --goal "Outcome"
+node bin/orchestra.js context --task STORY-001 --json
+node bin/orchestra.js delegation decide --task STORY-001 --json
+node bin/orchestra.js plan --task STORY-001 --json
+node bin/orchestra.js skills plan --task STORY-001 --json
+node bin/orchestra.js skills render --target codex --task STORY-001
+node bin/orchestra.js protocol render --target codex --task STORY-001
+node bin/orchestra.js workflow render --target codex --task STORY-001
+node bin/orchestra.js commands manifest --json
+node bin/orchestra.js runtime bootstrap --target codex
+node bin/orchestra.js evidence add --task STORY-001 --role developer --type command --summary "npm run precommit passed" --command "npm run precommit" --exit-code 0
+node bin/orchestra.js gate --gate architecture --task STORY-001
+node bin/orchestra.js summary --json
+```
+
+Use `--target claude`, `--target cursor`, `--target codex`, `--target vscode`,
+`--target windsurf`, or `--target generic` when rendering skills, protocol, or
+workflow instructions for a specific runtime.
+
+`orchestra init` also refreshes compact managed bootstrap blocks in
+`ORCHESTRA.md` and `AGENTS.md`. These blocks tell the active LLM how to discover
+commands and which task loop to run without copying the full manual into the
+always-loaded context.
+
+Use explicit init targets when a project should generate runtime-specific files:
+
+```bash
+node bin/orchestra.js runtime adapters --json
+node bin/orchestra.js init --target claude,cursor,windsurf
+```
+
+## Parent Agent Prompts
+
+Claude:
+
+```text
+Use Open Orchestra as the local control plane for this repo. Treat yourself as
+the parent agent. Start by running health, context, delegation, plan, skills
+plan, and target-specific skill/protocol render commands. Do not spawn or claim
+subagents unless the local workflow state and user approval make that explicit.
+Record evidence and reviews before saying work is complete.
+```
+
+Codex:
+
+```text
+Use the local orchestra CLI before implementation. Confirm the task exists,
+inspect context and delegation, render Codex skills/protocol/workflow context,
+implement with focused tests, run precommit, then record evidence and review
+artifacts in Open Orchestra.
+```
+
+Cursor:
+
+```text
+Use Open Orchestra for task state and context. Render Cursor-targeted skills and
+protocol instead of copying large rule files. Keep generated MDC/MD blocks
+managed, record test evidence, and do not overwrite user-authored content.
+```
+
+Generic LLM runtime:
+
+```text
+Act as the parent agent. Use Open Orchestra commands as the source of truth for
+tasks, roles, skills, workflow templates, evidence, reviews, and gates. Ask the
+user before changing architecture or spending budget. Treat provider execution
+as future capability unless the project exposes an approved adapter.
+```
+
+## Model Routing
+
+Current model routing is metadata and policy plumbing. These commands inspect
+or update routing state, but they do not yet execute real provider-backed
+subagents:
+
+```bash
+node bin/orchestra.js model providers --json
+node bin/orchestra.js model set-role --role qa --provider fake --model fake-model
+node bin/orchestra.js model provenance list --json
+node bin/orchestra.js budget check --json
+```
+
+Future multi-model delegation should route by role capability, risk, budget,
+latency, and required evidence. For example, a parent agent could keep planning
+local, route security review to a stronger security model, route Playwright
+analysis to a browser-capable runtime, and request user approval before any
+budget fallback.
+
+## Current Limits
+
+- Open Orchestra has fake/provider-routing primitives, not real autonomous
+  provider execution.
+- It records delegation decisions, but it does not automatically spawn
+  subagents yet.
+- Parallel independent CLI commands are expected to work, but dependent commands
+  still need parent-agent ordering or future DAG semantics.
+- Workflow files are local state. Promote durable lessons into docs, skills, or
+  managed instruction blocks only after review.
+
+## Related Docs
+
+- [Skill Loading Strategy](skill-loading-strategy.md)
+- [Runtime Adapters](runtime-adapters.md)
+- [Open Orchestra MVP](orchestra-mvp.md)
+- [Source of Truth and Agent Learning](source-of-truth-and-agent-learning.md)
+- [Dogfooding Findings](open-orchestra-dogfooding-findings.md)

package/docs/setup-agents-dogfooding-findings.md

@@ -0,0 +1,101 @@
+# Setup Agents Dogfooding Findings
+
+This file tracks issues found while using Open Orchestra to coordinate the
+`setup-agents` improvement backlog.
+
+## Finding 1: Concurrent `task add` commands can corrupt `tasks.json`
+
+- **Open Orchestra issue:** https://github.com/jterrats/open-orchestra/issues/85
+- **Status:** fixed in Open Orchestra
+
+- **Date found:** 2026-05-06
+- **Source repo:** `/Users/polux/dev/setup-agents`
+- **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.
+- **Expected behavior:** state writes should be serialized, locked, or written atomically so concurrent commands either succeed safely or fail without corrupting existing state.
+- **Workaround used:** manually rewrote `.agent-workflow/tasks.json` as valid JSON and continued with sequential state-changing commands.
+- **Suggested fix:** introduce file-level locking plus atomic write through a temp file and rename for all workflow state mutations.
+- **Resolution:** workflow state writes are serialized with per-file lock directories and JSON state files are written through temporary files followed by atomic rename.
+
+## Finding 2: Evidence type validation is stricter than the CLI help implies
+
+- **Open Orchestra issue:** https://github.com/jterrats/open-orchestra/issues/84
+- **Status:** fixed in Open Orchestra
+
+- **Date found:** 2026-05-06
+- **Source repo:** `/Users/polux/dev/setup-agents`
+- **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.
+- **Expected behavior:** CLI help should show the allowed values, and validation failures should suggest the nearest valid type when possible.
+- **Workaround used:** recorded validation evidence as `--type command`.
+- **Suggested fix:** update command help to include the enum and consider aliases such as `validation -> command`.
+- **Resolution:** `validation` is accepted as an alias for `command`; CLI help lists canonical types and the alias; invalid type errors include valid types and aliases.
+
+## Finding 3: `reviewer` is not accepted as a review role
+
+- **Open Orchestra issue:** https://github.com/jterrats/open-orchestra/issues/86
+- **Status:** fixed in Open Orchestra
+
+- **Date found:** 2026-05-06
+- **Source repo:** `/Users/polux/dev/setup-agents`
+- **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.
+- **Expected behavior:** `reviewer` should either be a valid role alias or the error should list accepted role ids.
+- **Workaround used:** record the approval with an existing valid role.
+- **Suggested fix:** add `reviewer` as a role alias or expose accepted roles in validation errors and CLI help.
+- **Resolution:** `reviewer` is accepted as an alias for `reviewer_critic`; CLI help lists the alias; unknown reviewer role errors include accepted role ids and aliases.
+
+## Finding 4: Concurrent `lock claim` commands can create duplicate lock ids
+
+- **Open Orchestra issue:** https://github.com/jterrats/open-orchestra/issues/87
+- **Status:** fixed in Open Orchestra
+
+- **Date found:** 2026-05-06
+- **Source repo:** `/Users/polux/dev/setup-agents`
+- **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.
+- **Expected behavior:** lock ids should be collision-resistant even when lock claims happen in the same millisecond.
+- **Workaround used:** avoid concurrent state-mutating Orchestra commands and continue sequentially.
+- **Suggested fix:** generate lock ids with a random suffix or monotonic per-process sequence in addition to the timestamp.
+- **Resolution:** lock ids now include a timestamp plus `crypto.randomUUID()`, and concurrent lock claim regression coverage verifies uniqueness.
+
+## Finding 5: Runtime bootstrap examples are not portable after package install
+
+- **Open Orchestra issue:** https://github.com/jterrats/open-orchestra/issues/96
+- **Status:** fixed in Open Orchestra
+
+- **Date found:** 2026-05-06
+- **Source repo:** `/Users/polux/dev/setup-agents`
+- **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.
+- **Expected behavior:** generated runtime bootstrap guidance should use the installed executable form, such as `orchestra health --json`, or derive a target-appropriate command prefix from the runtime/install context.
+- **Workaround used:** run `node_modules/.bin/orchestra ...` directly from the consuming repo.
+- **Suggested fix:** update command manifest examples and runtime bootstrap rendering to prefer `orchestra` for installed usage, with repo-local `node bin/orchestra.js` reserved for Open Orchestra development docs.
+- **Resolution:** command manifest examples and generated runtime bootstrap blocks now use the portable installed executable form, `orchestra ...`; regression coverage verifies generated bootstrap content does not include `node bin/orchestra.js`.
+
+## Finding 6: Concurrent `evidence add` commands can overwrite artifact files
+
+- **Open Orchestra issue:** https://github.com/jterrats/open-orchestra/issues/98
+- **Status:** fixed in Open Orchestra
+
+- **Date found:** 2026-05-06
+- **Source repo:** `/Users/polux/dev/open-orchestra`
+- **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.
+- **Expected behavior:** every evidence event should keep a unique artifact path even under concurrent CLI usage.
+- **Workaround used:** rerun evidence recording sequentially.
+- **Suggested fix:** include a collision-resistant suffix in generated evidence artifact filenames.
+- **Resolution:** evidence artifact filenames now include a UUID in addition to task, timestamp, and type; concurrent CLI regression coverage verifies unique artifact paths.
+
+## Workspace State Safety Notes
+
+- Open Orchestra serializes local workflow state writes with per-file lock directories next to the target file.
+- 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.