@jterrats/open-orchestra 0.2.1 → 0.3.1

package/docs/orchestra-mvp.md

@@ -122,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
@@ -133,6 +213,9 @@ 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/
@@ -212,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jterrats/open-orchestra",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "type": "module",
   "bin": {
     "orchestra": "bin/orchestra.js"
@@ -27,11 +27,10 @@
     "eslint": "^10.2.1",
     "prettier": "^3.8.3",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.0"
-  },
-  "dependencies": {
+    "typescript-eslint": "^8.59.0",
     "chart.js": "^4.5.1"
   },
+  "dependencies": {},
   "description": "Local control plane for AI-assisted development orchestration, evidence gates, and agent workflows.",
   "repository": {
     "type": "git",