lda-wf/docs/historical/superpowers/plans/2026-05-12-workflow-artifact-hardening.md

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.