docs: archive completed superpowers plans

2026-06-04 22:29:32 +07:00
parent e001b524d6
commit 0d34174a84
93 changed files with 88 additions and 10 deletions
@@ -0,0 +1,119 @@
+# Workflow Artifact Hardening Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make saved workflow artifacts safe enough to rely on before merging MCP server modes or exposing workflow execution more broadly.
+
+**Architecture:** Keep `wf_artifacts` provider-neutral. `wf_mcp` may project artifact operations, but validation, storage, artifact creation, and diagnostics should stay in `wf_artifacts` where possible.
+
+**Tech Stack:** Python 3.14, Pydantic v2, pytest, `wf_core.Workflow` validation, existing `wf_mcp` broker service.
+
+---
+
+## Why This Comes First
+
+The live Codex probe proved the artifact execution path works, but it also found
+a real weakness: `create_workflow_artifact_from_plan` saved an invalid
+`state_schema` shape, and the error surfaced only when `run_workflow_deployment`
+tried to compile the workflow.
+
+Before unifying broker and transparent proxy modes, artifact creation should
+reject invalid plans earlier and return structured diagnostics.
+
+## Scope
+
+This plan hardens saved workflow creation and dependency validation. It does not
+merge MCP server modes and does not add native subgraphs.
+
+## Tasks
+
+### Task 1: Validate Plan Shape During Artifact Creation
+
+**Files:**
+
+- Modify: `src/wf_artifacts/factory.py`
+- Test: `tests/artifacts/test_factory.py`
+
+- [ ] Add a failing test proving `create_workflow_artifact_from_plan` rejects a
+      plan that cannot become a `wf_core.Workflow`.
+- [ ] Implement validation by constructing `wf_core.Workflow.model_validate`
+      from the plan fields.
+- [ ] Keep the validation dependency one-way: `wf_artifacts` may import
+      `wf_core`, but `wf_core` must not import `wf_artifacts`.
+- [ ] Return `ValueError` with a concise message containing the failing field
+      path or Pydantic error message.
+- [ ] Run `uv run --with pytest pytest tests\artifacts\test_factory.py -q`.
+
+### Task 2: Add Artifact Creation Diagnostics
+
+**Files:**
+
+- Modify: `src/wf_artifacts/models.py`
+- Modify: `src/wf_artifacts/factory.py`
+- Test: `tests/artifacts/test_factory.py`
+
+- [ ] Decide whether creation failures should raise exceptions only or also
+      expose a `validate_workflow_artifact_plan(...) -> list[DependencyDiagnostic]`
+      style function.
+- [ ] Recommended v1: add a separate `validate_workflow_artifact_plan(plan)`
+      that returns structured diagnostics, while the factory still raises on errors.
+- [ ] Add tests for missing `input_schema`, missing `output_schema`, invalid
+      state schema, and missing start node.
+
+### Task 3: Validate Direct Workflow Dependencies
+
+**Files:**
+
+- Modify: `src/wf_artifacts/validation.py`
+- Test: `tests/artifacts/test_validation.py`
+
+- [ ] Add artifact-store-aware validation for `workflow_dependencies`.
+- [ ] Validate exact artifact-version pins.
+- [ ] Return `dependency_missing` when a child artifact version does not exist.
+- [ ] Return `dependency_cycle` when direct/transitive workflow artifact
+      dependencies cycle.
+- [ ] Do not copy child dependency snapshots into the parent.
+
+### Task 4: Improve Capability Contract Checking
+
+**Files:**
+
+- Modify: `src/wf_artifacts/validation.py`
+- Test: `tests/artifacts/test_validation.py`
+- Optional: `src/wf_mcp/broker/artifact_tools.py`
+
+- [ ] Preserve current hash comparison behavior.
+- [ ] Add tests for kind mismatch, for example required `tool` but available
+      `node_spec`.
+- [ ] Decide whether `node_spec` can satisfy `tool` when the provider is an MCP
+      wrapper. Recommended: no implicit kind coercion in `wf_artifacts`; adapters
+      should present the available kind they mean to expose.
+- [ ] Add diagnostics with `code="capability_kind_mismatch"`.
+
+### Task 5: Document Current Runtime Limitations In Tool Responses
+
+**Files:**
+
+- Modify: `src/wf_mcp/broker/artifact_tools.py`
+- Test: `tests/wf_mcp/test_broker_server.py`
+
+- [ ] Keep interrupting artifacts rejected by `run_workflow_deployment`.
+- [ ] Add `repair_hint` text explaining native subgraphs/nested resume are not
+      implemented yet.
+- [ ] Add a test proving unsupported interrupt artifacts return a diagnostic
+      instead of raising.
+
+## Verification
+
+- [ ] `uv run --with pytest pytest tests\artifacts -q`
+- [ ] `uv run --with pytest pytest tests\wf_mcp\test_broker_server.py -q`
+- [ ] `uv run --with pytest pytest -q`
+- [ ] `uv run ruff check src tests examples main.py`
+- [ ] `uv run basedpyright src tests examples main.py --level error`
+
+## Non-Goals
+
+- No native `wf_core` subgraph implementation.
+- No MCP Tasks implementation.
+- No run history persistence.
+- No broker/transparent mode merge in this plan.