docs: record draft CLI diagnostic guidance

This commit is contained in:
lda
2026-06-29 22:17:25 +07:00 Verified
parent bc35ad29d5
commit d72911d490
4 changed files with 22 additions and 11 deletions
+6 -7
View File
@@ -297,16 +297,15 @@ stable.
only; optional inputs are surfaced in wrapper-hint notes for explicit binding.
Implementation plan:
[`required-only wrapper inputs`](historical/superpowers/plans/2026-06-29-required-only-wrapper-inputs.md).
- Completed: `wf draft set-input` rejects `local.x` targets before RPC and
shows the equivalent bare-target mapping.
- Completed: `wf draft add-step --route` errors include declared outcomes and
direct add/remove repair guidance.
- Completed: repeated idempotent `wf draft bind input/state -> local` behavior
is covered by regression tests.
Planned challenge-driven UX follow-ups:
- Improve `wf draft set-input` diagnostics when agents write local targets as
`local.x`; the command expects bare local field names such as `x`.
- Improve `wf draft add-step --route` diagnostics when agents route undeclared
outcomes, for example `error=fail` on a single-`ok` capability. The error
should include declared outcomes and a compact repair hint.
- Add an explicit re-invocation regression for idempotent
`wf draft bind input.x -> local.x` / `state.x -> local.x` repairs.
- Design a separate composite-binding/data-shaping slice for cases such as
mapping state fields into a structured `report` object. Do not hide this
behind the existing path binding syntax without a deliberate model.
+6 -2
View File
@@ -328,7 +328,9 @@ wf draft compile concat_ws
```
`set-input` maps graph source paths to node-local input fields:
`input.text=text` means `input.text -> local.text`.
`input.text=text` means `input.text -> local.text`. Targets are bare
node-local field names: write `--map input.text=text`, not
`--map input.text=local.text`.
`set-output` maps node-local output fields to workflow state paths:
`text=state.text` means `local.text -> state.text`.
@@ -396,7 +398,9 @@ the corresponding workflow input/state schema fields from the capability input
schema.
When the capability declares multiple outcomes, provide exactly one
`--route OUTCOME=TARGET` for each declared outcome. Missing or unknown outcomes
are rejected before the draft is mutated.
are rejected before the draft is mutated. When `add-step --route` rejects an
outcome, use the declared outcomes and repair text from the error. Remove
unknown route entries and add one route for each missing declared outcome.
```bash
wf draft add-step report_ws \