@jterrats/open-orchestra 0.4.2-beta.1 → 0.4.2-beta.2

package/docs/traceability-flow.md

@@ -0,0 +1,89 @@
+# Story To Release Traceability
+
+Open Orchestra keeps delivery traceability in `.agent-workflow/`. The goal is
+to connect a backlog story to technical work, verification evidence, reviews,
+and release readiness without relying on chat history.
+
+## Product Owner Refinement
+
+Start with a task that has a backlog item, goal, scope, acceptance criteria,
+risks, and test strategy:
+
+```bash
+orchestra task add --id STORY-1 --title "..." --owner product_owner --backlog HU-1 --acceptance "criterion one,criterion two"
+orchestra task update --id STORY-1 --goal "..." --scope "..." --risks "..." --test-strategy "..."
+orchestra readiness --task STORY-1
+```
+
+The task record is the story anchor. Keep acceptance criteria user-visible and
+avoid hiding product requirements in handoff notes.
+
+## Developer Delivery
+
+Before implementation, the developer reads the context bundle and records
+material decisions:
+
+```bash
+orchestra context --task STORY-1 --json
+orchestra decision add --task STORY-1 --owner developer --title "..." --context "..." --decision "..." --consequences "..."
+```
+
+Implementation evidence belongs on the task:
+
+```bash
+orchestra evidence add --task STORY-1 --role developer --type command --summary "unit tests passed" --command "npm test" --exit-code 0
+```
+
+## QA Verification
+
+QA verifies acceptance criteria, regression areas, edge cases, and data setup.
+Browser automation should use Playwright evidence when the behavior is
+user-facing:
+
+```bash
+orchestra playwright plan --task STORY-1
+orchestra playwright evidence --task STORY-1 --kind trace --path test-results/story-1.zip --summary "acceptance flow trace"
+orchestra review --task STORY-1 --role qa --result approve --findings "..." --recommendation "..."
+```
+
+Developer-to-QA handoff should include touched files, commands, known gaps, and
+recommended Playwright coverage.
+
+## Advisory Conversion
+
+Advisory mode stores portable planning artifacts under
+`.agent-workflow/advisory/`. Convert `project-task.json` into a real project
+task only after the target repository and scope are confirmed.
+
+Setup-agents imports preserve external references under
+`task.externalRefs.setupAgents`, including evidence IDs, handoff IDs, acceptance
+status, and contract version.
+
+## Release Readiness
+
+Release readiness composes task readiness, architecture, QA, risk, evidence,
+handoffs, reviews, and locks:
+
+```bash
+orchestra gate --gate release-readiness --task STORY-1
+orchestra release check --json
+orchestra release candidate --version <version> --json
+```
+
+The release manager should only accept unresolved risks when they are recorded
+as explicit reviews, decisions, or release evidence.
+
+## Generated Reference Separation
+
+Generated runtime files such as `AGENTS.md`, `ORCHESTRA.md`, and runtime adapter
+blocks guide agents. Delivery truth remains in `.agent-workflow/` artifacts:
+
+- `tasks.json` for backlog and ownership state.
+- `decisions/` for why choices were made.
+- `handoffs/` for role-to-role transfer.
+- `evidence/` for command, file, screenshot, trace, video, log, or report proof.
+- `reviews/` for approvals, blocks, and accepted risks.
+- `releases/` for release candidate and rollback evidence.
+
+Do not treat generated prompt text as delivery evidence unless it is explicitly
+attached through `orchestra evidence add`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jterrats/open-orchestra",
-  "version": "0.4.2-beta.1",
+  "version": "0.4.2-beta.2",
   "type": "module",
   "bin": {
     "orchestra": "bin/orchestra.js"
@@ -9,8 +9,9 @@
     "build": "tsc && npm run build:web",
     "typecheck": "tsc --noEmit",
     "test": "npm run build && node --test test/**/*.js extensions/**/*.test.cjs",
-    "lint": "eslint . && prettier --check \"{bin,scripts,test,src}/**/*.js\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.json\"",
-    "format": "prettier --write \"{bin,scripts,test,src}/**/*.js\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.json\"",
+    "test:e2e": "npm run build && playwright test",
+    "lint": "eslint . && prettier --check \"{bin,e2e,scripts,test,src}/**/*.js\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.{js,json}\"",
+    "format": "prettier --write \"{bin,e2e,scripts,test,src}/**/*.js\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.{js,json}\"",
     "secret-scan": "node scripts/secret-scan.js",
     "validate:workflow": "sh -c 'test ! -d .agent-workflow || (npm run build && node bin/orchestra.js validate)'",
     "precommit": "npm run lint && npm run typecheck && npm run secret-scan && npm test && npm run validate:workflow",
@@ -23,15 +24,15 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@playwright/test": "^1.59.1",
     "@types/node": "^25.6.0",
+    "chart.js": "^4.5.1",
     "esbuild": "^0.28.0",
     "eslint": "^10.2.1",
     "prettier": "^3.8.3",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.0",
-    "chart.js": "^4.5.1"
+    "typescript-eslint": "^8.59.0"
   },
-  "dependencies": {},
   "description": "Local control plane for AI-assisted development orchestration, evidence gates, and agent workflows.",
   "repository": {
     "type": "git",