@jterrats/open-orchestra 0.1.0 → 0.3.0

package/dist/workspace.js

@@ -2,12 +2,19 @@ import path from "node:path";
 import { readFile, writeFile } from "node:fs/promises";
 import { DIRECTORIES, FILES, WORKFLOW_DIR } from "./constants.js";
 import { defaultConfig, defaultRoles } from "./defaults.js";
+import { defaultSourceOfTruthCatalog } from "./knowledge-base.js";
+import { initPromptRegistry, PROMPT_REGISTRY_DIR } from "./prompt-registry.js";
+import { getRuntimeAdapter } from "./runtime-adapters.js";
+import { renderRuntimeBootstrap, upsertRuntimeBootstrapBlock, } from "./runtime-bootstrap.js";
+import { classifyWorkspace } from "./workspace-classification.js";
 import { appendJsonLine, ensureDir, exists, readJson, resolveWorkflowPath, writeJson, } from "./fs-utils.js";
 import { validateRoles, validateTasks } from "./validation.js";
 export function workflowRoot(root = process.cwd()) {
     return path.join(root, WORKFLOW_DIR);
 }
-export async function initWorkspace({ root = process.cwd(), force = false, } = {}) {
+export async function initWorkspace({ root = process.cwd(), force = false, advisory = false, confirmUnknown = false, bootstrapTargetFile, runtimeTargets, } = {}) {
+    const classification = await classifyWorkspace({ root, advisory });
+    assertInitAllowed(classification, confirmUnknown);
     const base = workflowRoot(root);
     if ((await exists(base)) && !force) {
         throw new Error(`${WORKFLOW_DIR} already exists. Use --force to overwrite generated files.`);
@@ -16,19 +23,119 @@ export async function initWorkspace({ root = process.cwd(), force = false, } = {
     for (const directory of DIRECTORIES) {
         await ensureDir(path.join(base, directory));
     }
-    await writeJson(path.join(base, FILES.config), defaultConfig);
+    await writeJson(path.join(base, FILES.config), {
+        ...defaultConfig,
+        mode: advisory ? "advisory" : "project",
+        workspaceClassification: classification,
+    });
     await writeJson(path.join(base, FILES.roles), defaultRoles);
     await writeJson(path.join(base, FILES.tasks), []);
     await writeJson(path.join(base, FILES.locks), []);
     await writeFile(path.join(base, FILES.events), "", "utf8");
+    await writeJson(path.join(base, FILES.sourceOfTruth), defaultSourceOfTruthCatalog());
+    await writeFile(path.join(base, FILES.agentLessons), "", "utf8");
+    const promptRegistry = advisory
+        ? { mode: "advisory", skipped: true }
+        : await initPromptRegistry({ root, force });
+    const runtimeBootstrap = advisory
+        ? await initAdvisoryRuntimeBootstrapFiles({
+            root,
+            ...(bootstrapTargetFile ? { bootstrapTargetFile } : {}),
+            ...(runtimeTargets ? { runtimeTargets } : {}),
+        })
+        : await initRuntimeBootstrapFiles(root, initBootstrapTargets(runtimeTargets));
     await appendEvent(root, {
         type: "WORKFLOW_INITIALIZED",
         actor: "parent",
-        summary: "Initialized agent workflow workspace",
-        artifacts: [WORKFLOW_DIR],
+        summary: advisory
+            ? "Initialized advisory agent workflow workspace"
+            : "Initialized agent workflow workspace",
+        artifacts: [
+            WORKFLOW_DIR,
+            ...(advisory ? [] : [PROMPT_REGISTRY_DIR]),
+            path.join(WORKFLOW_DIR, FILES.sourceOfTruth),
+            path.join(WORKFLOW_DIR, FILES.agentLessons),
+        ],
+        metadata: {
+            mode: advisory ? "advisory" : "project",
+            promptRegistry,
+            runtimeBootstrap,
+            workspaceClassification: classification,
+        },
     });
     return base;
 }
+function assertInitAllowed(classification, confirmUnknown) {
+    if (classification.writePolicy === "blocked") {
+        throw new Error(`workspace is unsafe for init: ${classification.reasons.join(", ")}. ${classification.recommendedAction}`);
+    }
+    if (classification.writePolicy === "confirm_required" && !confirmUnknown) {
+        throw new Error(`workspace requires explicit confirmation: ${classification.reasons.join(", ")}. ${classification.recommendedAction}`);
+    }
+}
+async function initAdvisoryRuntimeBootstrapFile(root, bootstrapTargetFile) {
+    const target = targetFromBootstrapFile(bootstrapTargetFile);
+    return initRuntimeBootstrapFiles(root, [
+        { file: bootstrapTargetFile, target },
+    ]);
+}
+async function initAdvisoryRuntimeBootstrapFiles({ root, bootstrapTargetFile, runtimeTargets, }) {
+    const targets = initBootstrapTargets(runtimeTargets, false);
+    if (bootstrapTargetFile) {
+        return [
+            ...(await initAdvisoryRuntimeBootstrapFile(root, bootstrapTargetFile)),
+            ...(await initRuntimeBootstrapFiles(root, targets)),
+        ];
+    }
+    return initRuntimeBootstrapFiles(root, targets);
+}
+async function initRuntimeBootstrapFiles(root, targets = [
+    { file: "ORCHESTRA.md", target: "generic" },
+    { file: "AGENTS.md", target: "codex" },
+]) {
+    const changed = [];
+    for (const item of targets) {
+        const filePath = path.join(root, item.file);
+        const existing = await readFile(filePath, "utf8").catch(() => "");
+        const result = upsertRuntimeBootstrapBlock(existing, renderRuntimeBootstrap(item.target));
+        if (result.changed && !result.drift) {
+            await ensureDir(path.dirname(filePath));
+            await writeFile(filePath, result.content, "utf8");
+            changed.push(item.file);
+        }
+    }
+    return changed;
+}
+function initBootstrapTargets(runtimeTargets, useProjectDefaults = true) {
+    if (!runtimeTargets || runtimeTargets.length === 0) {
+        return useProjectDefaults
+            ? [
+                { file: "ORCHESTRA.md", target: "generic" },
+                { file: "AGENTS.md", target: "codex" },
+            ]
+            : [];
+    }
+    return runtimeTargets.flatMap((target) => getRuntimeAdapter(target).defaultInstructionFiles.map((file) => ({
+        file,
+        target,
+    })));
+}
+function targetFromBootstrapFile(filePath) {
+    const baseName = path.basename(filePath).toLowerCase();
+    if (baseName === "claude.md") {
+        return "claude";
+    }
+    if (baseName.includes("cursor")) {
+        return "cursor";
+    }
+    if (baseName.includes("windsurf")) {
+        return "windsurf";
+    }
+    if (baseName === "agents.md") {
+        return "codex";
+    }
+    return "generic";
+}
 export async function loadWorkspace(root = process.cwd()) {
     const base = workflowRoot(root);
     if (!(await exists(base))) {

package/dist/workspace.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"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"}

package/docs/autonomous-workflow.md

@@ -0,0 +1,165 @@
+# Autonomous Workflow
+
+`orchestra workflow run` executes a full story lifecycle as a governed multi-phase sequence without requiring manual step-by-step commands. Each phase creates a sub-task, generates handoff artifacts, and persists state in an append-only run log at `.agent-workflow/workflow-runs.jsonl`.
+
+## Phase Graph
+
+```
+PM → PO [gate] → Architect [sizing gate] → Developer → QA [gate] → Release
+```
+
+| Phase | Role | Summary |
+|-------|------|---------|
+| `pm` | product_manager | Product framing, prioritization, and success metrics |
+| `po` | product_owner | Backlog refinement, story sizing, and acceptance criteria |
+| `architect` | architect | Technical tasking, design decisions, and size estimation |
+| `developer` | developer | Implementation against acceptance criteria |
+| `qa` | qa | Verification against acceptance criteria and edge cases |
+| `release` | release_manager | Release candidate validation and PR creation |
+
+## Gate Modes
+
+```bash
+orchestra workflow run --task <id> --gates none    # fully autonomous
+orchestra workflow run --task <id> --gates phase   # gates at po→architect and qa→release
+orchestra workflow run --task <id> --gates all     # gate at every transition
+```
+
+| Mode | Pauses at |
+|------|-----------|
+| `none` | Never — fully autonomous |
+| `phase` | `po→architect` and `qa→release` |
+| `all` | Every phase transition |
+
+When a gate is reached, the run writes a review artifact to `.agent-workflow/approvals/` and prints the exact `--resume` command. The run resumes when a human approves and runs that command.
+
+## Architect Sizing Gate
+
+Regardless of `--gates` mode, the architect phase always requires a sizing decision before the developer phase starts. If no sizing decision is found, the run stops with the exact command to resolve it:
+
+```bash
+orchestra decision add \
+  --task <id> \
+  --owner architect \
+  --title "Story sizing" \
+  --decision "m [5 points]" \
+  --context "Authentication story, moderate complexity" \
+  --consequences "Fits in a two-day sprint slot" \
+  --status accepted
+```
+
+Valid sizing labels: `xs`, `s`, `m`, `l`, `xl`. An optional numeric point estimate can be appended to the decision text.
+
+## Usage
+
+```bash
+# Inspect the phase graph without persisting state
+orchestra workflow run --task FEAT-001 --dry-run --gates phase
+
+# Fully autonomous run
+orchestra workflow run --task FEAT-001 --gates none
+
+# Run with human approval gates
+orchestra workflow run --task FEAT-001 --gates phase
+
+# Resume a paused run after approving a gate
+orchestra workflow run --task FEAT-001 --resume <run-id>
+
+# Cap the number of QA→developer retry iterations (default: 5)
+orchestra workflow run --task FEAT-001 --gates none --max-iterations 3
+
+# List all runs
+orchestra workflow runs
+orchestra workflow runs --json
+```
+
+## Clarification Loop
+
+Developers or QA engineers can surface blocking questions to the PO or architect mid-phase. The active phase is suspended until the answer is recorded, then resumed normally.
+
+Clarification is only allowed from `developer` and `qa` phases. Questions can be directed to `po` (product_owner) or `architect`.
+
+```bash
+# Open a clarification — suspends the active developer or qa phase
+orchestra workflow clarify \
+  --run <run-id> \
+  --from developer \
+  --to po \
+  --question "Should empty input return null or throw a validation error?"
+
+# The PO or architect answers
+orchestra workflow clarify-respond \
+  --run <run-id> \
+  --clarification <clarification-id> \
+  --answer "Return null — downstream code handles it with a friendly message."
+
+# Resume execution — picks up exactly where the phase left off
+orchestra workflow run --task FEAT-001 --resume <run-id>
+
+# List all clarifications for a run (open and answered)
+orchestra workflow clarify-list --run <run-id>
+orchestra workflow clarify-list --run <run-id> --json
+```
+
+Clarification records are persisted in `.agent-workflow/clarifications.jsonl` and are visible in `orchestra context --task <id>`.
+
+## Run States
+
+| Status | Meaning |
+|--------|---------|
+| `running` | Execution in progress |
+| `paused` | Waiting for human gate approval or clarification answer |
+| `done` | All phases completed successfully |
+| `failed` | Run stopped due to a missing prerequisite (e.g. sizing decision) |
+
+## Phase States
+
+| Status | Meaning |
+|--------|---------|
+| `pending` | Not yet started |
+| `running` | Currently executing |
+| `done` | Completed and handed off |
+| `gate_paused` | Completed; waiting for human gate approval before next phase |
+| `awaiting_clarification` | Suspended; waiting for a clarification answer |
+| `qa_failed` | QA found issues; developer phase will retry |
+| `blocked` | Blocked by an unresolvable condition |
+
+## Persistent Files
+
+```text
+.agent-workflow/
+  workflow-runs.jsonl       ← one JSON line per run state snapshot (append-only)
+  clarifications.jsonl      ← one JSON line per clarification state snapshot (append-only)
+  approvals/                ← gate review artifacts (Markdown)
+  handoffs/                 ← inter-phase handoff artifacts (Markdown)
+```
+
+## Example: Full Lifecycle with gates=phase
+
+```
+$ orchestra workflow run --task FEAT-001 --gates phase
+Started autonomous workflow wfrun-... for task FEAT-001 [gates=phase]
+→ pm (product_manager) task=FEAT-001-pm
+  ✓ handoff → product_owner (...)
+→ po (product_owner) task=FEAT-001-po
+  ✓ handoff → architect (...)
+  ⏸ gate po→architect — review: .agent-workflow/approvals/FEAT-001-gate-po-to-architect-....md
+  Approve: orchestra workflow run --task FEAT-001 --resume wfrun-...
+
+$ orchestra workflow run --task FEAT-001 --resume wfrun-...
+Resuming run wfrun-... from phase architect
+→ architect (architect) task=FEAT-001-architect
+  ✓ sizing=m (5 pts)
+  ✓ handoff → developer (...)
+→ developer (developer) task=FEAT-001-developer
+  ✓ handoff → qa (...)
+→ qa (qa) task=FEAT-001-qa
+  ✓ handoff → release_manager (...)
+  ⏸ gate qa→release — review: .agent-workflow/approvals/FEAT-001-gate-qa-to-release-....md
+  Approve: orchestra workflow run --task FEAT-001 --resume wfrun-...
+
+$ orchestra workflow run --task FEAT-001 --resume wfrun-...
+Resuming run wfrun-... from phase release
+→ release (release_manager) task=FEAT-001-release
+Workflow complete [run=wfrun-...]
+```

package/docs/benchmark.md

@@ -0,0 +1,219 @@
+# Benchmark & Sprint Burndown
+
+Open Orchestra measures the effectiveness of AI-assisted development across three modes and generates a sprint burndown from story point estimates. All cycle time and quality data is computed automatically from the event log — no manual input is required after the initial estimate declaration.
+
+## Three Modes
+
+| Mode | How measured |
+|------|-------------|
+| **Solo (no LLM)** | Declared by PM or architect at story start — contrafactual estimate |
+| **AI-unguided** | Declared at story start — how long with a general LLM but no roles, gates, or skills |
+| **AI + Orchestra (actual)** | Measured automatically from `AUTONOMOUS_PHASE_DONE` timestamps in the event log |
+
+The first two are self-reported. Orchestra only measures the third. The comparison is meaningful even with declared baselines because it creates a consistent, auditable record across many stories.
+
+## Usage
+
+### 1. Declare baselines at story start
+
+Record the three-mode estimate before work begins — ideally during the architect phase.
+
+```bash
+orchestra estimate \
+  --task FEAT-001 \
+  --sizing m \
+  --solo-days 5 \
+  --ai-unguided-days 3 \
+  --confidence high \
+  --declared-by pm
+```
+
+Options:
+
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--task` | Yes | — | Task ID |
+| `--sizing` | Yes | — | `xs`, `s`, `m`, `l`, `xl` |
+| `--solo-days` | Yes | — | Estimated days without any AI |
+| `--ai-unguided-days` | Yes | — | Estimated days with a general LLM, no Orchestra |
+| `--confidence` | No | `medium` | `low`, `medium`, `high` |
+| `--declared-by` | No | `pm` | Role recording the estimate |
+| `--json` | No | — | Structured output |
+
+### 2. Run the story autonomously
+
+```bash
+orchestra workflow run --task FEAT-001 --gates phase
+```
+
+The autonomous engine records all necessary data automatically as phases complete.
+
+### 3. View the benchmark
+
+```bash
+# Per-story
+orchestra benchmark --task FEAT-001
+
+# All stories with estimates
+orchestra benchmark --summary
+orchestra benchmark --summary --json
+```
+
+Example per-story output:
+
+```
+Benchmark: FEAT-001  [complete]
+  Sizing:      m
+  Solo:        5d  (declared)
+  AI-unguided: 3d  (declared)
+  Actual:      1.4d
+  vs Solo:     -72%
+  vs AI:       -53%
+  QA loops:    1
+  Reviews:     3 (0 blocking)
+  Evidence:    5 artifacts
+  Gate blocks: 0
+  Lessons:     2
+  Tokens:      17500in / 5000out
+  Cost:        $0.0257
+```
+
+Example summary table:
+
+```
+Story          Size Solo   AI     Actual   vs Solo  vs AI    QA   Rev  Blk  Ev   Les
+────────────────────────────────────────────────────────────────────────────────────
+TASK-042       m    5d     3d     1.4d     -72%     -53%     1    3    0    5    2
+TASK-089       l    8d     5d     2.1d     -74%     -58%     2    4    1    7    3
+TASK-101       s    2d     1.5d   0.6d     -70%     -60%     0    2    0    3    1
+
+Avg savings vs solo:        -72%
+Avg savings vs AI-unguided: -57%
+Stories with actuals:       3/3
+```
+
+## Quality Signals
+
+All quality signals are computed automatically from the event log for the task. No additional commands are needed.
+
+| Signal | Source event | What it means |
+|--------|-------------|---------------|
+| `reviewCount` | `REVIEW_RECORDED` | Total reviews across all roles |
+| `blockingReviews` | `REVIEW_RECORDED` with `result=block` or `severity=high/critical` | Reviews that blocked progress |
+| `evidenceCount` | `EVIDENCE_ADDED` | Artifacts attached (commands, files, screenshots, traces) |
+| `gateBlockCount` | `GATE_BLOCKED` | Times a workflow gate evaluation failed |
+| `lessonCount` | `LESSON_RECORDED` | Lessons generated during the story |
+| `totalInputTokens` | `MODEL_PROVENANCE_RECORDED` | Input tokens across all LLM calls |
+| `totalOutputTokens` | `MODEL_PROVENANCE_RECORDED` | Output tokens across all LLM calls |
+| `estimatedCostUsd` | `MODEL_PROVENANCE_RECORDED` | Estimated cost of all LLM calls |
+
+Token and cost signals appear automatically once the autonomous engine makes real LLM calls. No changes to the benchmark layer are needed.
+
+## Sprint Burndown
+
+The burndown uses story points from `DECISION_RECORDED` events. Developer points take priority over architect sizing when both exist.
+
+```bash
+# ASCII chart with ideal and actual lines
+orchestra burndown --sprint FEAT-001,FEAT-002,FEAT-003
+
+# JSON series for dashboards or external tools
+orchestra burndown --sprint FEAT-001,FEAT-002,FEAT-003 --json
+```
+
+Example output:
+
+```
+Sprint burndown  total=18 pts  tasks=3
+
+ 18 │*
+ 16 │
+ 14 │      ·
+ 12 │      *
+ 10 │
+  8 │            ·
+  6 │            *
+  4 │
+  2 │
+  0 │                                                  ·
+     └───────────────────────────────────────────────────
+       Day 0                                        Day 3
+       · ideal   * actual
+
+Task breakdown:
+  FEAT-001       arch=5     dev=8      resolved=8   done 2026-05-06
+  FEAT-002       arch=5     dev=—      resolved=5   done 2026-05-06
+  FEAT-003       arch=5     dev=—      resolved=5   pending
+```
+
+### Developer Story Point Estimation
+
+Architect sizing (`xs/s/m/l/xl` + optional points) reflects technical scope. Developer points reflect implementation effort from the developer's perspective. When both exist, the burndown uses developer points — the divergence between the two is a calibration signal worth tracking.
+
+Developer records their estimate with:
+
+```bash
+orchestra decision add \
+  --task FEAT-001 \
+  --owner developer \
+  --title "Dev estimate" \
+  --decision "M / 8 points" \
+  --context "Familiar codebase area, clean interfaces" \
+  --consequences "Fits in one sprint slot" \
+  --status accepted
+```
+
+The `metadata.points` value is extracted automatically from `DECISION_RECORDED` events where `actor=developer`.
+
+## JSON Output
+
+All benchmark and burndown commands support `--json` for structured output.
+
+`orchestra benchmark --task <id> --json`:
+```json
+{
+  "taskId": "FEAT-001",
+  "sizingLabel": "m",
+  "soloEstimateDays": 5,
+  "aiUnguidedEstimateDays": 3,
+  "actualDays": 1.4,
+  "vsSoloPct": -72,
+  "vsAiUnguidedPct": -53,
+  "qaIterations": 1,
+  "quality": {
+    "reviewCount": 3,
+    "blockingReviews": 0,
+    "evidenceCount": 5,
+    "gateBlockCount": 0,
+    "lessonCount": 2,
+    "totalInputTokens": 17500,
+    "totalOutputTokens": 5000,
+    "estimatedCostUsd": 0.0257
+  },
+  "status": "complete"
+}
+```
+
+`orchestra burndown --sprint ... --json`:
+```json
+{
+  "sprintTaskIds": ["FEAT-001", "FEAT-002"],
+  "totalPoints": 13,
+  "idealLine": [{ "day": 0, "remaining": 13 }, { "day": 1, "remaining": 7 }, { "day": 2, "remaining": 0 }],
+  "actualLine": [{ "day": 0, "remaining": 13, "completedTaskIds": [] }, { "day": 1, "remaining": 5, "completedTaskIds": ["FEAT-001"] }],
+  "taskBreakdown": [
+    { "taskId": "FEAT-001", "architectPoints": 5, "developerPoints": 8, "resolvedPoints": 8, "completedAt": "2026-05-06T..." },
+    { "taskId": "FEAT-002", "architectPoints": 5, "developerPoints": null, "resolvedPoints": 5, "completedAt": null }
+  ],
+  "warnings": []
+}
+```
+
+## Persistent Files
+
+```text
+.agent-workflow/
+  estimates.jsonl     ← one JSON line per estimate (append-only, latest-per-task wins)
+```
+
+Estimates are append-only. Recording a new estimate for the same task replaces the previous one in reads (latest-wins by taskId).