@chllming/wave-orchestration 0.7.1 → 0.7.3

package/docs/plans/waves/wave-5.md

@@ -0,0 +1,382 @@
+# Wave 5 - Schema Versioning, Artifact Hierarchy, and Human Input Workflow
+
+**Commit message**: `Arch: harden schema versioning, artifact classification, and human input workflow`
+
+## Component promotions
+
+- state-artifacts-and-feedback: qa-proved
+
+## Context7 defaults
+
+- bundle: node-typescript
+- query: "JSON schema migration, artifact metadata, workflow state machines, SLA tracking in Node.js"
+
+## Agent A0: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- id: codex
+- model: gpt-5-codex
+- codex.profile_name: review
+- codex.search: true
+- codex.json: true
+
+### Context7
+
+- bundle: none
+
+### Prompt
+
+```text
+Primary goal:
+- Verify schema versioning is explicit on all derived-state schemas, artifact classes are labeled, and human input workflow semantics are in the control plane — not the supervisor.
+
+Required context before coding:
+- Read docs/plans/end-state-architecture.md (sections: Schema Versioning, Artifact Hierarchy, Human Input Workflow).
+- Read docs/reference/repository-guidance.md.
+
+Specific expectations:
+- confirm every persisted artifact carries _meta.artifactClass
+- confirm every derived-state schema carries schemaVersion
+- confirm readers tolerate unknown fields (forward compatibility)
+- confirm human input SLA, reroute, escalation, and timeout semantics live in control-plane events and the reducer, NOT in the supervisor
+- confirm the supervisor only observes/collects/submits human-input responses
+- do not PASS if any derived cache is missing _meta or schemaVersion
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-5-cont-qa.md
+```
+
+## Agent A8: Integration Steward
+
+### Role prompts
+
+- docs/agents/wave-integration-role.md
+
+### Executor
+
+- id: claude
+- model: claude-sonnet-4-6
+
+### Context7
+
+- bundle: none
+
+### Capabilities
+
+- integration
+- docs-shared-plan
+
+### Prompt
+
+```text
+Synthesize schema versioning, artifact hierarchy, and human input workflow changes.
+
+Required context before coding:
+- Read docs/plans/end-state-architecture.md.
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+
+Verify:
+- schema migration functions exist for all version transitions
+- artifact classes are consistent between the hierarchy doc and actual file writes
+- human input workflow integrates with existing clarification triage and escalation paths
+- no regression in existing coordination flows
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-5.md
+- .tmp/main-wave-launcher/integration/wave-5.json
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- id: opencode
+- opencode.files: docs/plans/end-state-architecture.md,docs/plans/current-state.md
+
+### Context7
+
+- bundle: none
+
+### Prompt
+
+```text
+Update shared plan docs to reflect schema versioning, artifact classification, and human input workflow.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+
+File ownership (only touch these paths):
+- docs/plans/current-state.md
+- docs/plans/master-plan.md
+- docs/plans/migration.md
+- docs/plans/wave-orchestrator.md
+- docs/plans/component-cutover-matrix.md
+- docs/plans/component-cutover-matrix.json
+- docs/reference/wave-control.md
+```
+
+## Agent A1: Schema Versioning and Artifact Classification
+
+### Executor
+
+- profile: implement-fast
+- model: gpt-5-codex
+- codex.add_dirs: scripts,test
+- fallbacks: claude, opencode
+
+### Context7
+
+- bundle: node-typescript
+- query: "JSON schema migration, semver, forward compatibility patterns"
+
+### Components
+
+- state-artifacts-and-feedback
+
+### Exit contract
+
+- completion: contract
+- durability: none
+- proof: unit
+- doc-impact: owned
+
+### Deliverables
+
+- scripts/wave-orchestrator/schema-versioning.mjs
+- test/wave-orchestrator/schema-versioning.test.ts
+
+### Proof artifacts
+
+- path: .tmp/wave-5-state-proof/schema-migration-report.json | kind: migration-report | required-for: pilot-live
+
+### Prompt
+
+```text
+Add explicit schema versioning to all derived-state schemas and artifact class labels to all persisted artifacts.
+
+Schema versioning rules:
+1. Forward compatibility: readers tolerate unknown fields.
+2. Version-gated migration: materializer runs migration function when version advances.
+3. Every schema file declares schemaVersion: N.
+
+Every persisted artifact includes _meta:
+  {
+    "_meta": {
+      "artifactClass": "canonical-event" | "canonical-snapshot" | "derived-cache" | "human-projection",
+      "schemaVersion": N,
+      "generatedAt": ISO8601,
+      "source": "description of canonical input"
+    }
+  }
+
+Artifact class definitions:
+- canonical-event: append-only, never rewritten (control-plane JSONL, coordination JSONL)
+- canonical-snapshot: written once per event, immutable, attempt-scoped paths
+- derived-cache: materialized from canonical sources, can be deleted and rebuilt
+- human-projection: convenience output, never read by the system
+
+Schemas requiring versioning (add migration functions):
+- Agent result envelope (v2)
+- Gate snapshot (v2)
+- Task graph (v1)
+- Integration summary (v2)
+- Retry plan (v2)
+- Proof registry (v2)
+- Relaunch plan (v2)
+- Run state (v3)
+- Trace bundle (v3)
+- Control-plane event (v2)
+- Coordination record (v2)
+- Contradiction (v1)
+- Fact (v1)
+- Wave manifest (v2)
+- Dashboard (v2)
+- Assignment snapshot (v1)
+- Dependency snapshot (v1)
+- Ledger (v1)
+- Docs queue (v1)
+- Security summary (v1)
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/end-state-architecture.md (sections: Schema Versioning, Artifact Hierarchy).
+- Read scripts/wave-orchestrator/artifact-schemas.mjs.
+- Read scripts/wave-orchestrator/dashboard-state.mjs.
+
+File ownership (only touch these paths):
+- scripts/wave-orchestrator/schema-versioning.mjs
+- scripts/wave-orchestrator/artifact-schemas.mjs
+- test/wave-orchestrator/schema-versioning.test.ts
+- .tmp/wave-5-state-proof/
+```
+
+## Agent A2: Human Input Workflow Subsystem
+
+### Executor
+
+- profile: implement-fast
+- model: gpt-5-codex
+- codex.add_dirs: scripts,test
+- fallbacks: claude, opencode
+
+### Context7
+
+- bundle: node-typescript
+- query: "Workflow state machines, SLA tracking, timeout policies in event-sourced systems"
+
+### Components
+
+- state-artifacts-and-feedback
+
+### Exit contract
+
+- completion: contract
+- durability: none
+- proof: unit
+- doc-impact: none
+
+### Deliverables
+
+- scripts/wave-orchestrator/human-input-workflow.mjs
+- test/wave-orchestrator/human-input-workflow.test.ts
+
+### Proof artifacts
+
+- path: .tmp/wave-5-state-proof/human-input-sla-log.json | kind: workflow-log | required-for: pilot-live
+
+### Prompt
+
+```text
+Implement the human input workflow subsystem.
+
+Key design rule: human-input workflow semantics (SLA, reroute, escalation, timeout, closure blocking) live in:
+- control-plane events
+- reducer state
+- this workflow module
+
+The session supervisor only observes, collects, and submits responses. It does NOT own SLA or escalation logic.
+
+Human input entity (extended from existing):
+  {
+    requestId, waveNumber, lane,
+    kind:              "clarification" | "escalation" | "approval" | "decision",
+    status:            "pending" | "assigned" | "answered" | "escalated" | "resolved" | "timed_out" | "rerouted",
+    requestedBy, requestedAt,
+    assignedTo:        string | null,
+    assignedAt:        ISO8601 | null,
+    answeredAt:        ISO8601 | null,
+    resolvedAt:        ISO8601 | null,
+    timeoutPolicy: {
+      ackDeadlineMs, resolveDeadlineMs, escalateAfterMs
+    },
+    reroutePolicy: {
+      maxReroutes, rerouteHistory: [{ from, to, reason, at }]
+    },
+    linkedRequests:    [requestId],
+    closureCondition:  string | null,
+    slaMetrics: {
+      timeToAck, timeToResolve, wasEscalated, wasRerouted, wasTimedOut
+    }
+  }
+
+Implementation:
+1. Add human-input workflow logic to human-input-workflow.mjs.
+2. Workflow state transitions go to control-plane events.
+3. The reducer materializes human input state from events.
+4. The closure engine treats unresolved human inputs as hard blockers.
+5. The retry engine can plan around timed-out requests by escalating or rerouting.
+6. SLA metrics are computed by the reducer, not by the supervisor.
+7. Integrate with existing clarification-triage.mjs for backward compatibility.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/end-state-architecture.md (section: Human Input Workflow).
+- Read scripts/wave-orchestrator/clarification-triage.mjs.
+- Read scripts/wave-orchestrator/feedback.mjs.
+- Read scripts/wave-orchestrator/launcher-supervisor.mjs (human feedback monitoring to keep but not expand).
+
+File ownership (only touch these paths):
+- scripts/wave-orchestrator/human-input-workflow.mjs
+- scripts/wave-orchestrator/clarification-triage.mjs
+- test/wave-orchestrator/human-input-workflow.test.ts
+- .tmp/wave-5-state-proof/
+```
+
+## Agent A3: Projection Writer
+
+### Executor
+
+- profile: implement-fast
+- model: gpt-5-codex
+- codex.add_dirs: scripts,test
+- fallbacks: claude, opencode
+
+### Context7
+
+- bundle: node-typescript
+
+### Components
+
+- state-artifacts-and-feedback
+
+### Exit contract
+
+- completion: contract
+- durability: none
+- proof: unit
+- doc-impact: none
+
+### Deliverables
+
+- scripts/wave-orchestrator/projection-writer.mjs
+- test/wave-orchestrator/projection-writer.test.ts
+
+### Proof artifacts
+
+- path: .tmp/wave-5-state-proof/projection-artifact-manifest.json | kind: artifact-manifest | required-for: pilot-live
+
+### Prompt
+
+```text
+Implement the projection writer — the single module responsible for all non-canonical file writes.
+
+The projection writer takes derived state from the materializer, gate verdicts from the gate engine, and wave state from the reducer, and writes:
+- dashboards (global + per-wave) — artifactClass: human-projection
+- markdown board projections — artifactClass: human-projection
+- coordination board projection — artifactClass: human-projection
+- trace bundles — artifactClass: canonical-snapshot
+- quality metrics — artifactClass: derived-cache
+- human-facing status summaries — artifactClass: human-projection
+- wave manifest — artifactClass: human-projection
+
+Rules:
+1. Never reads its own outputs.
+2. Always writes atomically (writeJsonAtomic / writeTextAtomic).
+3. Labels every artifact with _meta including artifactClass and schemaVersion.
+4. Consolidates dashboard writes currently scattered across launcher.mjs and dashboard-state.mjs.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/end-state-architecture.md (sections: Layer 3, Artifact Hierarchy).
+- Read scripts/wave-orchestrator/dashboard-state.mjs (current dashboard writes to consolidate).
+- Read scripts/wave-orchestrator/traces.mjs (trace bundle writes).
+
+File ownership (only touch these paths):
+- scripts/wave-orchestrator/projection-writer.mjs
+- test/wave-orchestrator/projection-writer.test.ts
+- .tmp/wave-5-state-proof/
+```

package/docs/plans/waves/wave-6.md

@@ -0,0 +1,321 @@
+# Wave 6 - Proof Families, Workflow Backend, and Architecture Completion
+
+**Commit message**: `Arch: add proof families, workflow backend boundary, and complete architecture refactor`
+
+## Component promotions
+
+- wave-parser-and-launcher: pilot-live
+- closure-sweep-and-role-gates: pilot-live
+- executor-abstraction-and-prompt-transport: pilot-live
+
+## Context7 defaults
+
+- bundle: node-typescript
+- query: "Workflow backend abstraction, deployment verification, proof family validation in Node.js"
+
+## Agent A0: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- id: codex
+- model: gpt-5-codex
+- codex.profile_name: review
+- codex.search: true
+- codex.json: true
+
+### Context7
+
+- bundle: none
+
+### Prompt
+
+```text
+Primary goal:
+- Verify that the full end-state architecture is landed, internally consistent, and tested.
+
+Required context before coding:
+- Read docs/plans/end-state-architecture.md (all sections).
+- Read docs/reference/repository-guidance.md.
+
+Specific expectations:
+- confirm proof families (code_proof, integration_proof, deploy_proof) are independently evaluated
+- confirm the workflow backend boundary abstracts event persistence, state queries, timer management, and human input behind a clean interface
+- confirm the local-file backend is the only implementation and passes all tests
+- confirm the full end-state module architecture is realized:
+  Layer 1: canonical authority set (control-plane, coordination-store, wave-files)
+  Layer 2: phase engines (implementation, derived-state, gate, closure, retry, reducer)
+  Layer 3: session supervisor + projection writer
+  Layer 4: thin launcher orchestrator
+- confirm every design principle from the architecture doc is implemented
+- confirm all 10 feedback corrections are addressed
+- do not PASS if any phase engine still reads from derived caches or projections
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-6-cont-qa.md
+```
+
+## Agent A8: Integration Steward
+
+### Role prompts
+
+- docs/agents/wave-integration-role.md
+
+### Executor
+
+- id: claude
+- model: claude-sonnet-4-6
+
+### Context7
+
+- bundle: none
+
+### Capabilities
+
+- integration
+- docs-shared-plan
+- contradiction-recovery
+
+### Prompt
+
+```text
+Final integration synthesis for the architecture refactor.
+
+Required context before coding:
+- Read docs/plans/end-state-architecture.md.
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+
+Verify end-to-end:
+- a wave can run through the full pipeline: parse → reduce → plan → select → materialize → launch → wait → evaluate → close
+- retry correctly uses task graph and two-phase proof for targeted reruns
+- contradiction detection, repair, and resolution work end-to-end
+- human input workflow blocks closure and supports escalation/reroute
+- replay tests pass using stored events from waves 0-5
+- the workflow backend boundary is clean enough that swapping the implementation would not require changes to phase engines
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-6.md
+- .tmp/main-wave-launcher/integration/wave-6.json
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- id: opencode
+- opencode.files: docs/plans/end-state-architecture.md,docs/plans/current-state.md
+
+### Context7
+
+- bundle: none
+
+### Prompt
+
+```text
+Final documentation update reflecting the completed architecture refactor.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+
+Update all shared plan docs to reflect the final landed state.
+Mark the end-state architecture doc as landed (not aspirational).
+Update the component cutover matrix with all promotions.
+
+File ownership (only touch these paths):
+- docs/plans/current-state.md
+- docs/plans/master-plan.md
+- docs/plans/migration.md
+- docs/plans/wave-orchestrator.md
+- docs/plans/end-state-architecture.md
+- docs/plans/component-cutover-matrix.md
+- docs/plans/component-cutover-matrix.json
+- docs/reference/proof-metrics.md
+- docs/reference/wave-control.md
+```
+
+## Agent A1: Proof Family Split
+
+### Executor
+
+- profile: implement-fast
+- model: gpt-5-codex
+- codex.add_dirs: scripts,test
+- fallbacks: claude, opencode
+
+### Context7
+
+- bundle: node-typescript
+- query: "Proof validation, deployment health checks, test runner integration"
+
+### Components
+
+- closure-sweep-and-role-gates
+
+### Exit contract
+
+- completion: contract
+- durability: none
+- proof: unit
+- doc-impact: owned
+
+### Deliverables
+
+- scripts/wave-orchestrator/proof-families.mjs
+- test/wave-orchestrator/proof-families.test.ts
+
+### Proof artifacts
+
+- path: .tmp/wave-6-proof/proof-family-report.json | kind: proof-family-report | required-for: pilot-live
+
+### Prompt
+
+```text
+Implement the three proof families: code_proof, integration_proof, deploy_proof.
+
+code_proof — validates agent's owned deliverables:
+- tests pass (unit/integration/live per contract)
+- build succeeds
+- diff clean outside owned paths
+- deliverables exist and non-empty
+- proof artifacts present and SHA256-valid
+- component promotions meet target maturity
+
+integration_proof — validates cross-cutting contracts:
+- interface contracts consistent between components
+- dependency resolution clean
+- no open integration conflicts
+- no open contradictions on shared state
+- cross-lane dependencies resolved
+- integration summary: zero unresolved blockers
+
+deploy_proof — validates runtime behavior (opt-in):
+- rollout artifact exists (if declared)
+- runtime health check passes (if declared)
+- post-deploy evidence collected (if declared)
+- no deployment-blocking regressions
+- deploy-kind specific validation (Railway, Docker, k8s, etc.)
+
+The gate engine evaluates each family independently. A wave can be:
+  code_proof: satisfied, integration_proof: satisfied, deploy_proof: not_applicable
+
+Implementation:
+1. Define proof family schema in proof-families.mjs.
+2. Update gate engine to evaluate each family.
+3. Update proof registry to tag bundles with proof family.
+4. Update result envelope role-specific payloads for deploy role.
+5. Write tests covering each family independently.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/end-state-architecture.md (section: Proof Families).
+- Read scripts/wave-orchestrator/proof-registry.mjs.
+- Read scripts/wave-orchestrator/launcher-gates.mjs.
+
+File ownership (only touch these paths):
+- scripts/wave-orchestrator/proof-families.mjs
+- scripts/wave-orchestrator/proof-registry.mjs
+- scripts/wave-orchestrator/launcher-gates.mjs
+- test/wave-orchestrator/proof-families.test.ts
+- .tmp/wave-6-proof/
+```
+
+## Agent A2: Workflow Backend Boundary
+
+### Executor
+
+- profile: implement-fast
+- model: gpt-5-codex
+- codex.add_dirs: scripts,test
+- fallbacks: claude, opencode
+
+### Context7
+
+- bundle: node-typescript
+- query: "Workflow engine abstraction, repository pattern, dependency injection in Node.js"
+
+### Components
+
+- wave-parser-and-launcher
+- executor-abstraction-and-prompt-transport
+
+### Exit contract
+
+- completion: contract
+- durability: none
+- proof: unit
+- doc-impact: none
+
+### Deliverables
+
+- scripts/wave-orchestrator/workflow-backend.mjs
+- scripts/wave-orchestrator/workflow-backend-local.mjs
+- test/wave-orchestrator/workflow-backend.test.ts
+
+### Proof artifacts
+
+- path: .tmp/wave-6-proof/workflow-backend-trace.json | kind: backend-trace | required-for: pilot-live
+
+### Prompt
+
+```text
+Introduce the workflow backend abstraction boundary.
+
+The workflow backend interface:
+  WorkflowBackend {
+    // Event persistence
+    appendEvent(event) → void
+    readEvents(filter) → [Event]
+
+    // State queries (backed by reducer)
+    getWaveState(lane, wave) → WaveState
+    getTaskState(taskId) → TaskState
+    getOpenBlockers(lane, wave) → [Blocker]
+    getClosureEligibility(lane, wave) → ClosureState
+
+    // Timer management
+    scheduleTimer(id, dueAt, payload) → void
+    cancelTimer(id) → void
+    getExpiredTimers() → [Timer]
+
+    // Human input
+    createHumanInput(request) → requestId
+    resolveHumanInput(requestId, response) → void
+    getOpenHumanInputs(filter) → [HumanInput]
+  }
+
+Local-file backend implementation:
+- appendEvent → JSONL append to control-plane log
+- readEvents → parse JSONL with filter
+- getWaveState → call wave-state-reducer.reduce()
+- Timer management → file-based tracking under .tmp/<lane>-wave-launcher/timers/
+- Human input → existing feedback queue + human-input-workflow.mjs
+
+Design rules:
+1. Phase engines interact with state ONLY through the backend interface.
+2. The local-file backend is the only implementation for now.
+3. The interface is clean enough that a Temporal-backed or service-backed backend could replace it without rewriting phase engines.
+4. The backend does NOT own business logic — it persists events and answers queries.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/end-state-architecture.md (section: Workflow Backend Boundary).
+- Read scripts/wave-orchestrator/control-plane.mjs (current event persistence).
+- Read scripts/wave-orchestrator/wave-state-reducer.mjs (state queries).
+
+File ownership (only touch these paths):
+- scripts/wave-orchestrator/workflow-backend.mjs
+- scripts/wave-orchestrator/workflow-backend-local.mjs
+- test/wave-orchestrator/workflow-backend.test.ts
+- .tmp/wave-6-proof/
+```