@osolmaz/pi-workflows 0.9.1 → 0.11.0

package/docs/plans/2026-08-19-workflow-composition-plan.md

@@ -0,0 +1,308 @@
+---
+title: Add typed workflow composition and automatic repair
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-19
+---
+
+# Add typed workflow composition and automatic repair
+
+Pi Workflows needs reusable nested workflows with normal TypeScript imports. Monitor must be able to devise and implement a repair when mutation is authorized. Autoimplement must move back to solution design when new evidence invalidates its plan, correct failed reviewer commands, track P0, P1, and P2 findings, and use long CI waits for additional local testing.
+
+The canonical behavior is in [Workflow composition](../WORKFLOW_COMPOSITION.md).
+
+## Outcome
+
+A workflow can run alone or as a typed child in one durable parent run. Authors can import a child definition, map its input, and route from named exits. Dynamic project, global, built-in, and path references remain available.
+
+The package will ship `autoplan`, `autoimplement`, and `monitor` as compatible built-ins. Monitor will remain observation-only by default. An explicitly authorized monitor can run outer solution design, autoimplementation, internal redesign, and a fresh target check without copying workflow nodes.
+
+## Scope
+
+### Public workflow API
+
+- Add generic workflow input and named-exit contracts.
+- Add runtime input and exit validation.
+- Add direct typed `includeWorkflow(child, options)` composition.
+- Keep dynamic `includeWorkflow({ workflow, input })` references.
+- Add `defineWorkflowRegistry()` for shipped typed definitions.
+- Type-check child input mappers and parent exit names where the child is imported directly.
+
+### Resolution and execution
+
+- Resolve all direct and dynamic includes before `run_started`.
+- Reject direct and indirect source cycles.
+- Compile one qualified executable graph.
+- Give child callbacks a local invocation view.
+- Support repeated and nested mounts.
+- Apply root and per-invocation step limits.
+- Record named entry and exit transitions.
+- Keep one pause, cancellation, checkpoint, update, notification, and presentation lifecycle.
+
+### Persistence and display
+
+- Record all child sources and their mount paths.
+- Record a digest of the resolved definition.
+- Refuse normal resume when any source or digest changes.
+- Add mount data to the definition snapshot.
+- Add include entry and exit trace events.
+- Group qualified child nodes in viewers while preserving flat replay.
+
+### Workflow library
+
+- Make `autoplan` accept an existing plan and new evidence.
+- Add `ready` and `blocked` exits to `autoplan`.
+- Rebuild `autoimplement` around explicit issue routes.
+- Include `autoplan` inside `autoimplement` for redesign.
+- Track P0, P1, and P2 review findings by round.
+- Rerun review only after P0 or P1 work.
+- Permit P2 work without another reviewer round.
+- Generate, validate, execute, and correct exact Pi Reviewer commands.
+- Track PR comments, CI, merge, and final PR reporting.
+- Bound one CI watch to five minutes.
+- Route a long CI wait to useful local testing before checking CI again.
+- Add authorized repair to monitor through outer `autoplan` and `autoimplement` mounts.
+- Detect repeated repair with no changed issue, plan, implementation, evidence, or target state.
+
+## Non-goals
+
+- Do not change Pi core or use private Pi APIs.
+- Do not create another run store, service, or child Pi session.
+- Do not let a child jump into a parent or sibling node.
+- Do not permit recursive include graphs.
+- Do not add unrestricted model-selected node names.
+- Do not let monitor mutate a target without explicit authorization.
+- Do not replace Pi Reviewer with another reviewer after an invocation failure.
+- Do not merge before required gates pass or an allowed unrelated failure is recorded.
+- Do not rewrite existing terminal run bundles.
+
+## Data contracts
+
+### Child result
+
+A completed child mount exposes a discriminated result:
+
+```typescript
+type IncludedResult<TExits> = {
+  [K in keyof TExits]: { exit: K; output: TExits[K] };
+}[keyof TExits];
+```
+
+### Source record
+
+```typescript
+type WorkflowMountedSource = {
+  mountPath: string[];
+  workflowName: string;
+  source: WorkflowSource;
+};
+```
+
+### Review round
+
+```typescript
+type ReviewRound = {
+  command: StructuredCommand;
+  p0: ReviewFinding[];
+  p1: ReviewFinding[];
+  p2: ReviewFinding[];
+  lower: ReviewFinding[];
+  invocationSucceeded: boolean;
+};
+```
+
+P0 or P1 findings route to redesign or fix, then verification, push, and another review. P2-only work routes through a separate verification path and then continues to PR comments without another review.
+
+### CI decision
+
+```typescript
+type CiDecision = {
+  status: "green" | "failed" | "pending" | "unavailable";
+  relatedFailures: string[];
+  unrelatedFailures: string[];
+  trackingCommand?: StructuredCommand;
+};
+```
+
+A pending result must include a validated `gh` tracking command. The shell action stops after five minutes. A timeout routes to opportunistic local testing. The workflow checks CI again after that work.
+
+## Implementation sequence
+
+### 1. Typed contracts
+
+- Make workflow definitions generic over input and exits.
+- Add source identity, input parser, exit parser, and include declarations.
+- Add direct and dynamic `includeWorkflow()` overloads.
+- Add registry helpers and compile-time contract tests.
+- Keep old workflow definitions valid.
+
+### 2. Composition resolver
+
+- Resolve nested direct and dynamic definitions.
+- Preserve parent-relative paths.
+- Build the complete source list.
+- Reject source cycles with the mount chain.
+- Validate child exit nodes and parent include edges.
+- Compile qualified nodes and internal entry and exit transitions.
+- Attach immutable composition metadata to the resolved definition.
+
+### 3. Local execution context
+
+- Project each child callback to its mount-local input, outputs, results, and steps.
+- Hide parent and sibling data.
+- Start each re-entry after the latest mount-entry step.
+- Expose only the latest named child result to the parent.
+- Enforce per-invocation and root step limits.
+- Emit include entry and exit events.
+
+### 4. Persistence and resume
+
+- Add mounted sources and the resolved digest to state and manifest projections.
+- Add mount metadata to definition snapshots.
+- Compare the complete identity during resume and continuation.
+- Keep old single-source bundles readable.
+- Add trace reconstruction and torn-tail tests for include transitions.
+
+### 5. Viewer grouping
+
+- Derive groups from snapshot mount metadata.
+- Keep qualified names in replay and details.
+- Update TypeScript and Rust fixtures together.
+
+### 6. Autoplan
+
+- Move the current workflow into the built-in library.
+- Add typed input, `ready`, and `blocked` exits.
+- Accept a previous plan and new evidence.
+- Calculate a plan digest.
+- Return whether the selected plan changed.
+- Keep the current practical, in-scope selection rule.
+
+### 7. Autodoc and autoimplement
+
+Add standalone autodoc and build this autoimplement graph:
+
+```text
+find existing plan
+  -> missing or unclear -> blocked
+  -> documentation current -> implement
+  -> documentation missing or stale -> autodoc -> implement
+  -> verify
+  -> classify issue
+     -> redesign -> autoplan -> autodoc -> optional approval -> implement
+     -> fix -> verify
+     -> publish -> write reviewer command -> run reviewer
+
+review result
+  -> command error -> rewrite command -> run reviewer
+  -> P0/P1 -> classify issue
+  -> P2 -> address P2 -> verify P2 -> PR comments
+  -> clean -> PR comments
+
+PR comments
+  -> redesign
+  -> fix
+  -> CI
+
+CI
+  -> related design failure -> redesign
+  -> related local failure -> fix
+  -> pending -> track for at most five minutes
+  -> tracking timeout -> run additional useful tests -> check CI
+  -> green or allowed unrelated failure -> merge
+  -> unavailable or forbidden -> blocked
+```
+
+The structured plan input is optional because the plan can already exist in conversation context or canonical documentation. Its absence never authorizes initial autoplan. Autoimplement blocks when no clear plan exists, skips autodoc for current documentation, and records every evidence-driven revision through autodoc before continuing.
+
+The workflow will collect all review rounds in its final output. It will never rerun Pi Reviewer solely because P2 work changed files.
+
+### 8. Monitor repair
+
+- Add explicit repair authorization to monitor input.
+- Add `repair` to the check result only when authorization is present.
+- Mount outer `autoplan`, `autodoc`, optional `plan-approval`, and `autoimplement`.
+- Pass the documented outer plan into autoimplement.
+- Return exact replan instructions to autoplan and ask again.
+- Check the target again after a reported repair.
+- Stop on repeated no-progress evidence.
+- Keep ordinary monitor calls observation-only and backward compatible.
+
+### 9. Skills and docs
+
+- Update workflow authoring, persistence, monitor, and controller-boundary docs.
+- Align the public monitor and autoimplement skills with the new workflows.
+- Run the normal agent synchronization command in the source repository after skill edits.
+- Record any implementation departure in this plan and the canonical specification.
+
+## Acceptance criteria
+
+- Direct imports infer child input and named exits.
+- Invalid direct input mappings fail type checking.
+- Invalid child exit names fail type checking or definition validation.
+- Dynamic references resolve through existing precedence rules.
+- Two mounts of one child do not share invocation state.
+- Standalone autodoc adopts current documents, updates stale documents, and blocks without a selected plan.
+- Autoimplement finds a clear existing plan and never invokes initial autoplan because a plan input is absent.
+- Nested redesign uses a fresh autoplan invocation and passes the revised plan through autodoc.
+- Source cycles fail before the run bundle is created.
+- Included checkpoints, updates, notifications, pause, cancellation, and resume behave like root nodes.
+- Every mounted source and the resolved digest is durable.
+- P0 and P1 work triggers another review round.
+- P2-only work can be addressed without another review round.
+- A failed reviewer command can be corrected and rerun without changing reviewer tools.
+- A pending CI decision supplies an exact command.
+- A CI wait longer than five minutes routes to useful local testing.
+- Monitor mutates only when repair is explicitly authorized.
+- A repaired monitor target is checked again.
+- Repeated repair without changed evidence stops as blocked.
+- Existing workflows and terminal run bundles remain valid.
+
+## Verification
+
+Run focused checks while implementing:
+
+```bash
+npx vitest run test/composition.test.ts test/graph.test.ts test/loader.test.ts
+npx vitest run test/engine.test.ts test/run-resume.test.ts test/store.test.ts
+npx vitest run test/builtin-autoplan.test.ts test/builtin-autoimplement.test.ts test/builtin-monitor.test.ts
+```
+
+Run all repository gates before review:
+
+```bash
+npm run check
+npm run test:e2e
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+npx -y @simpledoc/simpledoc check
+git diff --check
+```
+
+Run Pi Reviewer against the pushed branch. Fix every P0 and P1 finding and rerun it. P2-only changes do not require another reviewer run unless they expose a new P0 or P1 concern. Check PR comments and CI after review passes.
+
+## Release
+
+This adds compatible public APIs to a pre-1.0 package. The planned version is `0.10.0`. Existing `0.9.x` run bundles remain readable, and no published version is rewritten.
+
+## Implementation record
+
+The implementation follows the canonical specification with one visible detail: compiled include entry and exit transitions have durable internal step records so resume can reconstruct the active invocation. They do not consume root or child `maxSteps` limits. Viewers label them as entry and named-exit transitions.
+
+Direct imports check mapped input and exit names. `includedResult()` recovers the discriminated child result type from a parent output. Dynamic overrides carry a direct contract definition and must match its stable `contractId`, input presence, and named exits.
+
+The shipped workflows are registered built-ins:
+
+- `autoplan` returns `ready` or `blocked` with plan lineage.
+- `autodoc` records selected plans as a standalone and included built-in.
+- `autoimplement` finds an existing plan, conditionally documents it, and supports evidence-driven redesign, implementation fixes, exact reviewer and CI commands, P0 through P2 history, bounded CI watches, PR comments, merge, and final reporting.
+- `monitor` remains observation-only by default and enables composed repair only through an explicit repair policy.
+
+The package and Rust viewer version is `0.10.0`.
+
+## Contract impact
+
+- **Session state:** normal workflow messages and tool results only.
+- **Other persistent data:** additive mount, source, digest, review, and CI evidence in existing run bundles.
+- **Pi internals:** none.
+- **Public Pi API:** existing documented extension APIs only.
+- **Public Pi Workflows API:** generic input and exits, direct and dynamic `includeWorkflow()`, and `defineWorkflowRegistry()`.

package/docs/run-bundles.md

@@ -32,6 +32,27 @@ temporary directories.
       sha256-<64 hex>.txt
 ```
 
+Human decision records use a separate additive directory next to `runs/` so a waiting run bundle remains immutable:
+
+```text
+~/.pi/agent/workflows/decisions/
+  <decision-id>/
+    request.json
+    deliveries/<channel>/<attempt-id>.json
+    answers/<attempt-id>.json
+    resolution.json # atomic accepted-or-cancelled fence
+    accepted.json
+    cancelled.json   # present only when a pending request is cancelled or expires
+    settlements/<channel>/<attempt-id>.json
+    continuation.json
+```
+
+The request links to the waiting run, node, attempt, workflow source, and canonical request digest. A v2 request stores the canonical subject and a separate normalized operator presentation. Its subject, presentation, revision, choices, and input prompts are bound to the request digest. V2 accepted records and redacted continuation receipts preserve the subject and presentation digests. Final records use no-replace creation and adopt only identical retries. `resolution.json` is the first accepted-or-cancelled fence. It materializes either `accepted.json` or the mutually exclusive `cancelled.json`; a crash can rebuild that detail from the resolution. `continuation.json` binds an accepted answer to one deterministic continuation run. Delivery and settlement records cannot change the accepted answer.
+
+Telegram multipart delivery uses additive v2 delivery records for the overall intent, each part, and completion. Part records contain only recipient indexes, part indexes, counts, and content digests. Telegram chat and message IDs remain in the private disposable channel projection and never enter run or decision bundles. An ambiguous part remains unknown and is not retried blindly.
+
+A human-decision continuation preserves the parent's original workflow input and replaces the carried checkpoint output with the accepted typed response for routing. Its `humanDecision` state is a redacted receipt. A v2 receipt includes the subject digest, presentation digest, and revision, but not the subject itself. Verified actor, channel, event, and idempotency provenance remains in the private sibling decision records and is not copied into the run bundle. Ordinary checkpoint continuations keep using the answer as the continuation input. Existing bundles without human decision data remain valid. V1 requests and their original digests are never rewritten.
+
 Run ids are `<UTC timestamp>-<workflow slug>-<8 hex chars>`, so lexical order
 is chronological order.
 
@@ -142,11 +163,13 @@ Identity and pointers, kept in sync with the state on every snapshot:
 }
 ```
 
-`workflowSource` identifies the definition used by the run. User workflow
+`workflowSource` identifies the root definition used by the run. User workflow
 files use an absolute path and SHA-256 hash. Package-provided workflows use a
-stable identity such as `{ "kind": "builtin", "id": "monitor", "revision": "1" }`.
+stable identity such as `{ "kind": "builtin", "id": "monitor", "revision": "4" }`.
 A built-in identity does not contain an installation path.
 
+A composed run also records `workflowSources`, sorted by mount path, and `definitionDigest`. Each mounted source has `mountPath`, `workflowName`, and the same file or built-in source identity. The digest is SHA-256 over the resolved definition snapshot.
+
 `paths.artifacts` is declared from bundle creation so a live session-event
 patch can safely reference a newly written artifact before the next workflow
 state projection. The directory itself is created only when needed.
@@ -160,8 +183,7 @@ A serializable snapshot of the graph taken at run start
 (`pi-workflows.definition-snapshot.v1`). Functions such as prompts and
 validators are not serialized. Each node keeps only its metadata (`nodeType`,
 `timeoutMs`, `statusDetail`, `expectedOutput`, `summary`, `actionExecution`),
-and edges are copied verbatim. The snapshot is what lets viewers draw all
-nodes, including ones that have not run yet. It is immutable after run start.
+and edges are copied verbatim. Included nodes also record `mountPath`, `localNodeId`, and internal entry or exit status. The top-level `composition.mounts` list records every mount, entry, named exit, and child step limit. The snapshot is what lets viewers draw all nodes, including ones that have not run yet. It is immutable after run start.
 
 ## Resume and repair
 
@@ -176,10 +198,12 @@ instead of failing. Resume is a named operation with strict rules:
    `state.traceSeq` and the trace agree again before any new event.
 3. Completed nodes replay from the projection. The in-flight node reruns with
    a fresh attempt; a `run_resumed` trace event marks the boundary.
-4. `state.workflowSource` pins the workflow source from run start. File
+4. `state.workflowSource` pins the root workflow source from run start. File
    sources require the same hash. Built-in sources require the same catalog
-   id and revision. Resume refuses a mismatch unless forced, and a forced
-   resume records the mismatch in the `run_resumed` payload.
+   id and revision.
+5. Composed runs also require the same sorted `workflowSources` and
+   `definitionDigest`. A changed or missing child refuses normal resume.
+6. A forced resume records the identity mismatch in the `run_resumed` payload.
 
 Continuation runs (answering a checkpoint) are new bundles, not resumed ones.
 They link back through `state.parentRunId`, carry the parent's outputs,
@@ -204,6 +228,14 @@ The full run projection (`WorkflowRunState` in
     "path": "/repo/.pi/workflows/autoimplement.workflow.ts",
     "hash": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"
   },
+  "workflowSources": [
+    {
+      "mountPath": ["redesign"],
+      "workflowName": "autoplan",
+      "source": { "kind": "builtin", "id": "autoplan", "revision": "1" }
+    }
+  ],
+  "definitionDigest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
   "startedAt": "…",
   "updatedAt": "…",
   "status": "running",
@@ -215,9 +247,10 @@ The full run projection (`WorkflowRunState` in
 }
 ```
 
-- `workflowSource` is the canonical source identity. Resuming a file requires
-  the same hash. Resuming a built-in requires the same catalog revision. A
-  mismatch refuses the resume instead of loading another definition.
+- `workflowSource` is the canonical root source identity. Resuming a file requires
+  the same hash. Resuming a built-in requires the same catalog revision.
+- `workflowSources` and `definitionDigest` attest the complete composed graph.
+  A mismatch refuses resume instead of loading another child definition.
 - `status` is one of `running`, `waiting`, `completed`, `failed`, `timed_out`,
   or `cancelled`. A controller host records an abandoned bundle as `failed`
   with a final `run_interrupted` trace event. Before doing that, recovery checks
@@ -315,6 +348,8 @@ Event catalog and payload contracts:
 | `agent_prompt_sent` | agent   | `prompt`                                                            |
 | `node_finished`     | node    | `outcome: "ok"`, `durationMs`, `output`, `conversation?`, `action?` |
 | `node_failed`       | node    | `outcome`, `durationMs`, `error`, `conversation?`, `action?`        |
+| `include_entered`   | run     | `mountPath`, `workflowName`, `invocation`                           |
+| `include_exited`    | run     | `mountPath`, `workflowName`, `invocation`, `exit`, `output`         |
 | `run_paused`        | run     | _(empty)_                                                           |
 | `run_resumed`       | run     | _(empty)_                                                           |
 | `run_completed`     | run     | `status`, `finalOutput`                                             |

package/docs/workflows.md

@@ -15,8 +15,11 @@ Files are discovered by suffix (`.workflow.ts`, `.workflow.js`, `.workflow.mts`,
 2. `~/.pi/agent/workflows/` globally
 3. Workflows built into Pi Workflows
 
-Pi Workflows includes a built-in `monitor` workflow. A project or global file
-named `monitor.workflow.ts` replaces it. The package registers each built-in in
+Pi Workflows includes built-in `autoplan`, `autodoc`, `autoimplement`,
+`plan-approval`, and `monitor` workflows. `autoplan` is the current name for the
+planning workflow that was first released as `autodevise`; the old command and
+export are not retained. A project or global file named `monitor.workflow.ts`
+replaces the built-in monitor. The package registers each built-in in
 a process-local catalog with a stable reference such as `builtin:monitor` and
 an explicit revision. Built-ins are imported with the engine when a Pi process
 starts. They are not read from the package directory when a run starts or
@@ -53,15 +56,20 @@ export default defineWorkflow({
 
 Top-level fields:
 
-| Field                | Type                   | Notes                                                                                                                                                                                                              |
-| -------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `name`               | `string`               | Required. Used in run ids and the step contract. `answer`, `cancel`, `list`, `pause`, `resume`, and `status` are reserved for `/workflow` subcommands.                                                             |
-| `title`              | `string` or function   | Optional run title, resolved once at start from `{ input, workflowName }`. Async resolution is bounded (30s) and cancellable.                                                                                      |
-| `presentationPrompt` | `string` or function   | Optional instructions for a normal assistant response after the run. A function receives `{ state, finalOutput, signal }` and may return a prompt or `undefined`. See [Result presentation](#result-presentation). |
-| `startAt`            | `string`               | Required. Id of the first node.                                                                                                                                                                                    |
-| `nodes`              | `Record<string, node>` | Required, non-empty. Node ids must match `[A-Za-z_][A-Za-z0-9_-]*`.                                                                                                                                                |
-| `edges`              | `WorkflowEdge[]`       | Required. See routing below.                                                                                                                                                                                       |
-| `maxSteps`           | `number`               | Optional loop bound, default 100. The run fails when exceeded.                                                                                                                                                     |
+| Field                | Type                      | Notes                                                                                                                                                                                                              |
+| -------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `name`               | `string`                  | Required. Used in run ids and the step contract. `answer`, `cancel`, `list`, `pause`, `resume`, and `status` are reserved for `/workflow` subcommands.                                                             |
+| `source`             | `string`                  | Optional `import.meta.url` for exact provenance when another TypeScript workflow imports this definition directly.                                                                                                 |
+| `contractId`         | `string`                  | Optional stable input-and-exit contract identity. Dynamic overrides must match it.                                                                                                                                 |
+| `input`              | `function`                | Optional runtime input normalizer and validator. Its return type is the workflow input type.                                                                                                                       |
+| `title`              | `string` or function      | Optional run title, resolved once at start from `{ input, workflowName }`. Async resolution is bounded (30s) and cancellable.                                                                                      |
+| `presentationPrompt` | `string` or function      | Optional instructions for a normal assistant response after the run. A function receives `{ state, finalOutput, signal }` and may return a prompt or `undefined`. See [Result presentation](#result-presentation). |
+| `startAt`            | `string`                  | Required. Id of the first node.                                                                                                                                                                                    |
+| `nodes`              | `Record<string, node>`    | Required, non-empty. Node ids must match `[A-Za-z_][A-Za-z0-9_-]*`.                                                                                                                                                |
+| `includes`           | `Record<string, include>` | Optional imported or dynamically resolved child workflows.                                                                                                                                                         |
+| `exits`              | `Record<string, exit>`    | Optional named successful terminal nodes used when another workflow includes this workflow.                                                                                                                        |
+| `edges`              | `WorkflowEdge[]`          | Required. See routing below.                                                                                                                                                                                       |
+| `maxSteps`           | `number`                  | Optional loop bound, default 100. The run fails when exceeded.                                                                                                                                                     |
 
 `defineWorkflow` validates the shape eagerly (node ids, edge shapes, function
 fields) and validates the graph (unknown targets, duplicate outgoing edges,
@@ -266,6 +274,39 @@ checkpoint({
 });
 ```
 
+A typed human decision is an authoring layer over checkpoint:
+
+```typescript
+const choices = defineHumanChoices({
+  continue: choice({ label: "Continue" }),
+  stop: choice({ label: "Stop" }),
+  replan: choice({
+    label: "Replan",
+    input: textInput({ name: "instructions", prompt: "What should change?" }),
+  }),
+});
+
+humanDecision({
+  audience: "operator",
+  choices,
+  request: ({ outputs }) => ({
+    title: "Approve plan",
+    subject: outputs.plan,
+    presentation: {
+      schema: "pi-workflows.decision-presentation.v1",
+      summary: "Review the implementation plan.",
+      blocks: [{ kind: "paragraph", text: "The plan is ready for approval." }],
+    },
+  }),
+});
+```
+
+The waiting run stores a versioned request and asks every channel configured for the logical audience. The structured `subject` remains machine data. Channels receive only the normalized `presentation`, title, choices, and input prompts. The first valid verified human answer wins. A continuation preserves the original workflow input and exposes the accepted answer as the checkpoint output. `humanDecisionEdge()` provides exhaustive routing for the choices. Existing `body` requests remain a legacy compatibility form and use deterministic readable formatting.
+
+The model-facing workflow tool cannot answer a protected human decision. Pi interactive UI and configured external channels use a host-owned answer path. Ordinary checkpoints keep the existing `/workflow answer` behavior.
+
+See [Human decisions](HUMAN_DECISIONS.md) for channels, recovery, persistence, and plan approval.
+
 ### decision
 
 `decision` is sugar over `agent` for constrained choices. It builds the prompt
@@ -314,6 +355,43 @@ A missing case for the resolved value fails the run with a routing error. A
 node with no outgoing edge (or no matching failure route) ends the run:
 `completed` on success, `failed`/`timed_out`/`cancelled` otherwise.
 
+## Included workflows
+
+Use `includeWorkflow()` to mount a standalone workflow under a parent name:
+
+```typescript
+import repair from "./repair.workflow.js";
+
+includes: {
+  repair: includeWorkflow(repair, {
+    input: ({ outputs }) => ({ issue: outputs.check }),
+  }),
+},
+```
+
+The child declares named exits:
+
+```typescript
+exits: {
+  completed: { from: "finalize", validate: parseCompleted },
+  blocked: { from: "blocked", validate: parseBlocked },
+},
+```
+
+Enter through the mount and leave through `<mount>.<exit>`:
+
+```typescript
+{ from: "check", to: "repair" }
+{ from: "repair.completed", to: "check" }
+{ from: "repair.blocked", to: "finish" }
+```
+
+Direct imports check child input and exit names in TypeScript. Use `includedResult(child, outputs.mount)` to recover the child's discriminated exit output without a cast. Dynamic discovered names, built-in references, and file paths are also supported. Every reference resolves before the run starts.
+
+Child callbacks receive local input, outputs, results, and steps from their current invocation. Persisted node identities include the mount path. Re-entry starts with empty child-local state. Root and child step limits both apply. Internal entry and exit transitions do not consume those limits.
+
+The run records every mounted source and a digest of the resolved graph. Resume refuses a changed child source. Source cycles are rejected before the run starts. See [Workflow composition](WORKFLOW_COMPOSITION.md) for typing, persistence, nesting, and viewer rules.
+
 ## Model workflow control
 
 The model sees one `workflow` tool. Its `action` field supports:
@@ -322,7 +400,7 @@ The model sees one `workflow` tool. Its `action` field supports:
 - `start` with a workflow name or path and structured input.
 - `status` for the active run or a supplied run ID.
 - `pause`, `resume`, and `cancel` for the active run.
-- `answer` with checkpoint input and an optional run ID.
+- `answer` with ordinary checkpoint input and an optional run ID. Protected `humanDecision()` gates reject this model-facing action.
 - `update` for a non-completing update from the current agent attempt.
 - `submit` for the current workflow step contract.
 
@@ -333,6 +411,14 @@ The normal extension offers all actions. The headless RPC bridge offers only
 `update` and `submit`, so a workflow child cannot recursively control other
 runs.
 
+### Built-in planning and implementation
+
+The built-in `autoplan` workflow selects a practical in-scope solution and writes a detailed plan. The standalone `autodoc` workflow finds an already selected plan, records it in canonical documentation, verifies those documents, and never devises or implements. The built-in `autoimplement` workflow finds a clear existing plan from explicit input, conversation context, or referenced canonical documents. It blocks when no clear plan exists. An explicit plan bypasses autodoc only when a current-document receipt carries its matching plan digest; otherwise autodoc inspects and adopts or updates the canonical documents. Later invalidating evidence returns to `autoplan` followed by `autodoc`.
+
+The built-in `plan-approval` workflow offers verified human `continue`, `stop`, and exact-text `replan` exits. It is optional. A replan exit returns the unchanged text to autoplan, documents the revised plan, and asks again through a new plan digest.
+
+Autoimplement writes and runs the exact Pi Reviewer command. It records P0 through P2 by review round. P0 or P1 work requires another review. P2-only work can be addressed and verified without another reviewer run. CI tracking commands are also explicit. One CI watch lasts at most five minutes, after which the model runs more useful local tests before checking CI again.
+
 ### Built-in monitor
 
 The built-in `monitor` workflow turns a plain request for repeated checks into
@@ -341,12 +427,17 @@ one looping workflow run. Its input is:
 ```json
 {
   "task": "Check pull request 123",
-  "stopWhen": "The pull request is merged or closed"
+  "stopWhen": "The pull request is merged or closed",
+  "repair": {
+    "authorized": true,
+    "scope": "the current repository"
+  }
 }
 ```
 
-The first check runs immediately. `everyMinutes` defaults to 30. Each accepted
-check must provide one concise report and choose `continue` or `stop`. The
+The first check runs immediately. Omit `repair` for observation-only monitoring. An authorized repair routes through outer `autoplan`, `autodoc`, optional `plan-approval`, `autoimplement`, and internal redesign before the monitor checks the target again. A repeated issue with unchanged target evidence stops as blocked. Add `repair.approval` with a named audience and bounded replan limit only when the operator wants a human decision before implementation.
+
+`everyMinutes` defaults to 30. Each accepted check must provide one concise report and choose `continue`, `repair` when authorized, or `stop`. The
 runtime queues that report as a workflow notification with `triggerTurn:
 false`, so it does not cause an assistant reply. A check can also provide
 independent progress tracks. The regular Pi model running the check observes

package/examples/workflows/approved-plan.workflow.ts

@@ -0,0 +1,58 @@
+import { compute, defineWorkflow, includeWorkflow, includedResult } from "@osolmaz/pi-workflows";
+import autodoc from "../../src/builtins/autodoc.workflow.js";
+import autoplan from "../../src/builtins/autoplan.workflow.js";
+import planApproval from "../../src/builtins/plan-approval.workflow.js";
+
+export default defineWorkflow({
+  name: "approved-plan-example",
+  startAt: "design",
+  maxSteps: 80,
+  includes: {
+    design: includeWorkflow(autoplan, {
+      input: ({ input, outputs }) => {
+        const prior = outputs.design as { exit?: string; output?: { plan?: unknown } } | undefined;
+        const answer = outputs.approval as
+          | { exit?: string; output?: { instructions?: string } }
+          | undefined;
+        return {
+          problem: (input as { task: string }).task,
+          ...(prior?.exit === "ready" ? { previousPlan: prior.output?.plan } : {}),
+          ...(answer?.exit === "replan" ? { newEvidence: answer.output?.instructions } : {}),
+        };
+      },
+    }),
+    documentation: includeWorkflow(autodoc, {
+      input: ({ input, outputs }) => {
+        const result = includedResult(autoplan, outputs.design);
+        if (result.exit !== "ready") throw new Error("design is not ready");
+        return { task: (input as { task: string }).task, plan: result.output.plan };
+      },
+    }),
+    approval: includeWorkflow(planApproval, {
+      input: ({ input, outputs }) => {
+        const result = includedResult(autodoc, outputs.documentation);
+        if (result.exit !== "ready") throw new Error("documentation is not ready");
+        return {
+          task: (input as { task: string }).task,
+          plan: result.output.plan,
+          planDigest: result.output.planDigest,
+          audience: "operator",
+        };
+      },
+    }),
+  },
+  nodes: {
+    done: compute({ run: ({ outputs }) => ({ status: "approved", approval: outputs.approval }) }),
+    stopped: compute({ run: ({ outputs }) => ({ status: "stopped", approval: outputs.approval }) }),
+    blocked: compute({ run: ({ outputs }) => ({ status: "blocked", outputs }) }),
+  },
+  edges: [
+    { from: "design.ready", to: "documentation" },
+    { from: "design.blocked", to: "blocked" },
+    { from: "documentation.ready", to: "approval" },
+    { from: "documentation.blocked", to: "blocked" },
+    { from: "approval.continue", to: "done" },
+    { from: "approval.stop", to: "stopped" },
+    { from: "approval.replan", to: "design" },
+  ],
+});