fix(workflows): address second review pass on workflow composition

- Add a downstream consumption test: a parent step after the workflow call
  evaluates `{{ steps.call.output.echoed }}`, so a failure to publish the
  completed child's output into the caller context before continuing is now
  caught (final-state inspection alone could not).
- Update the built-in step inventories from 12 to 13 and add the `workflow`
  step to workflows/README.md and workflows/ARCHITECTURE.md.
- Drop the two dangling references to spec/workflow_composition/ (the design
  decisions and implementation plan are not part of this change).

Assisted-by: opencode (model: deepseek-v4.1-flash, supervised)

Author: Markus

src/specify_cli/workflows/composition.py

@@ -1,7 +1,6 @@
 """Workflow composition — scoped subtree execution helpers.
 
-Implements the decisions recorded in
-``spec/workflow_composition/design_decisions.md``:
+Implements the workflow composition decisions:
 
 - reserved output names and the composition depth limit,
 - registry-backed, installed-and-enabled target resolution,

tests/workflows/test_workflow_composition.py

@@ -1,8 +1,7 @@
 """Tests for workflow composition (the built-in ``type: workflow`` step).
 
 Covers the composition helpers, engine scoped execution, strict input binding,
-persistence/resume, and CLI reporting. See
-``spec/workflow_composition/implementation_plan.md``.
+persistence/resume, and CLI reporting.
 """
 
 from __future__ import annotations
@@ -301,6 +300,10 @@ def _parent_and_child(self, project_dir):
                         "workflow": "child",
                         "input": {"declared": "{{ inputs.shared }}"},
                     },
+                    _shell(
+                        "consume",
+                        "echo {{ steps.call.output.echoed | default('MISSING') }}",
+                    ),
                 ],
                 inputs={"shared": {"type": "string", "default": "secret"}},
             ),
@@ -322,6 +325,14 @@ def test_caller_cannot_see_child_locals(self, project_dir):
         # Only declared outputs + stable metadata cross the boundary.
         assert set(call_output) == {"workflow", "status", "echoed"}
 
+    def test_caller_can_consume_child_output_downstream(self, project_dir):
+        """The caller context must publish a completed child's output *before*
+        the next step runs, so a downstream expression can consume it."""
+        self._parent_and_child(project_dir)
+        state = _run(project_dir, "parent")
+        assert state.status == RunStatus.COMPLETED
+        assert state.step_results["consume"]["output"]["stdout"].strip() == "secret"
+
 
 class TestPublicOutputShapes:
     def test_completed_shape(self, project_dir):

workflows/ARCHITECTURE.md

@@ -79,7 +79,7 @@ When a `gate` step pauses execution, the engine persists `current_step_index` an
 
 ## Step Types
 
-The engine ships with 12 built-in step types, each in its own subpackage under `src/specify_cli/workflows/step/`:
+The engine ships with 13 built-in step types, each in its own subpackage under `src/specify_cli/workflows/step/`:
 
 | Type Key | Class | Purpose | Returns `next_steps`? |
 |----------|-------|---------|-----------------------|
@@ -95,6 +95,7 @@ The engine ships with 12 built-in step types, each in its own subpackage under `
 | `do-while` | `DoWhileStep` | Loop, always runs body at least once | Yes (always) |
 | `fan-out` | `FanOutStep` | Dispatch per item over a collection | No (engine expands) |
 | `fan-in` | `FanInStep` | Aggregate results from fan-out | No |
+| `workflow` | `WorkflowStep` | Run an installed workflow as a scoped subtree | No |
 
 ## Step Registry
 

workflows/README.md

@@ -85,7 +85,7 @@ The bundled `speckit` workflow only declares `spec` (and optional
 
 ## Step Types
 
-Workflows support 12 built-in step types:
+Workflows support 13 built-in step types:
 
 ### Command Steps (default)
 
@@ -313,6 +313,28 @@ Aggregate results from fan-out steps:
   output: {}
 ```
 
+### Workflow Steps
+
+Compose an installed workflow as a scoped subtree of the current run — a
+function call with one run state and one process. Values cross the boundary
+only through the target's declared `inputs` and `outputs`:
+
+```yaml
+- id: run-selected
+  type: workflow
+  workflow: "{{ inputs.target }}"   # installed, registered, and enabled
+  input:
+    report: "{{ inputs.report }}"
+```
+
+The `workflow` value must resolve to something the engine captures — a declared
+workflow input or a preceding step's captured output such as a `shell` step's
+`stdout`. A `prompt` step streams its output and returns an empty `stdout`, so
+it cannot drive `workflow` selection. The child receives only the bound declared
+inputs, and only its declared outputs (merged with `workflow` and `status`) are
+published back to the caller. See
+[Workflow composition](../docs/reference/workflows.md#workflow-composition-type-workflow).
+
 ## Error Handling
 
 By default, any step that returns `StepResult(status=StepStatus.FAILED, ...)`