@osolmaz/pi-workflows 0.9.0 → 0.10.0

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

@@ -0,0 +1,300 @@
+---
+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 `autodevise`, `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 `autodevise` accept an existing plan and new evidence.
+- Add `ready` and `blocked` exits to `autodevise`.
+- Rebuild `autoimplement` around explicit issue routes.
+- Include `autodevise` 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 `autodevise` 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. Autodevise
+
+- 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. Autoimplement
+
+Build this graph:
+
+```text
+prepare plan
+  -> implement
+  -> verify
+  -> classify issue
+     -> redesign -> autodevise -> 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 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 `autodevise` and `autoimplement`.
+- Pass the outer plan into autoimplement.
+- 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.
+- Nested redesign uses a fresh autodevise invocation.
+- 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-autodevise.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:
+
+- `autodevise` returns `ready` or `blocked` with plan lineage.
+- `autoimplement` supports 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

@@ -142,11 +142,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 +162,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 +177,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 +207,14 @@ The full run projection (`WorkflowRunState` in
     "path": "/repo/.pi/workflows/autoimplement.workflow.ts",
     "hash": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"
   },
+  "workflowSources": [
+    {
+      "mountPath": ["redesign"],
+      "workflowName": "autodevise",
+      "source": { "kind": "builtin", "id": "autodevise", "revision": "1" }
+    }
+  ],
+  "definitionDigest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
   "startedAt": "…",
   "updatedAt": "…",
   "status": "running",
@@ -215,9 +226,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 +327,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

@@ -53,15 +53,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,
@@ -314,6 +319,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:
@@ -333,6 +375,12 @@ 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 `autodevise` workflow selects a practical in-scope solution and writes a detailed plan. The built-in `autoimplement` workflow implements a supplied plan and returns to its internal `autodevise` mount when new evidence invalidates that plan.
+
+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 +389,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 can route through outer `autodevise`, `autoimplement`, and internal redesign before the monitor checks the target again. A repeated issue with unchanged target evidence stops as blocked.
+
+`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/autodevise.workflow.ts

@@ -0,0 +1 @@
+export { autodeviseWorkflow as default } from "@osolmaz/pi-workflows/builtins";

package/examples/workflows/autoimplement.workflow.ts

@@ -1,92 +1 @@
-import { agent, compute, decision, decisionEdge, defineWorkflow } from "@osolmaz/pi-workflows";
-
-type AutoimplementInput = {
-  task?: string;
-};
-
-const reviewChoices = ["clean", "issues_found"] as const;
-
-/**
- * Implement, verify, then loop a self-review until it comes back clean. The
- * decision edge routes `issues_found` back to the fix step, and the engine's
- * maxSteps guard bounds the loop.
- */
-export default defineWorkflow({
-  name: "autoimplement",
-  title: ({ input }) => {
-    const task = (input as AutoimplementInput).task;
-    return task ? `autoimplement: ${task.slice(0, 60)}` : undefined;
-  },
-  presentationPrompt:
-    "Summarize what was implemented, what verification passed, and any remaining limitation. Be concise and direct.",
-  maxSteps: 20,
-  startAt: "implement",
-  nodes: {
-    implement: agent({
-      timeoutMs: 60 * 60_000,
-      statusDetail: "implementing",
-      prompt: ({ input }) => {
-        const task =
-          (input as AutoimplementInput).task ?? "the plan discussed so far in this conversation";
-        return [
-          `Implement ${task} end-to-end.`,
-          "Aim for the most elegant, long-term production-ready solution without gold-plating.",
-        ].join("\n");
-      },
-      expectedOutput: `{ "summary": "what was implemented", "files": ["changed file", "changed file"] }`,
-    }),
-    verify: agent({
-      timeoutMs: 30 * 60_000,
-      statusDetail: "verifying",
-      prompt: () =>
-        [
-          "Verify the implementation.",
-          "Run the test suite plus any relevant builds, linters, or local smoke tests.",
-          "Do not run destructive commands.",
-        ].join("\n"),
-      expectedOutput: `{ "passed": true | false, "details": "what was run and what happened" }`,
-    }),
-    review: decision({
-      choices: reviewChoices,
-      question: ({ outputs }) =>
-        [
-          "Critically review your implementation as a strict reviewer.",
-          "Look for correctness bugs, missed requirements, and failing checks.",
-          "Pick `issues_found` if anything must be fixed, otherwise `clean`.",
-          "",
-          `Verification: ${JSON.stringify(outputs.verify)}`,
-        ].join("\n"),
-    }),
-    fix: agent({
-      timeoutMs: 30 * 60_000,
-      statusDetail: "fixing",
-      prompt: ({ outputs }) =>
-        [
-          "Fix the issues you found in review, then stop.",
-          "",
-          `Review: ${JSON.stringify(outputs.review)}`,
-        ].join("\n"),
-      expectedOutput: `{ "fixed": "what was changed" }`,
-    }),
-    finalize: compute({
-      run: ({ outputs }) => ({
-        implementation: outputs.implement,
-        verification: outputs.verify,
-        review: outputs.review,
-      }),
-    }),
-  },
-  edges: [
-    { from: "implement", to: "verify" },
-    { from: "verify", to: "review" },
-    decisionEdge({
-      from: "review",
-      choices: reviewChoices,
-      cases: {
-        clean: "finalize",
-        issues_found: "fix",
-      },
-    }),
-    { from: "fix", to: "verify" },
-  ],
-});
+export { autoimplementWorkflow as default } from "@osolmaz/pi-workflows/builtins";

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "osolmaz.pi-workflows"
 name = "Pi Workflows"
-version = "0.9.0"
+version = "0.10.0"
 min_herdr_version = "0.7.0"
 description = "Open the active Pi Workflows run in piw from a managed Herdr pane."
 platforms = ["linux", "macos"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osolmaz/pi-workflows",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Workflow and controller runtime with a live terminal viewer for the pi coding agent",
   "keywords": [
     "pi-package"
@@ -41,6 +41,10 @@
     "./controllers": {
       "types": "./dist/controllers/index.d.ts",
       "default": "./dist/controllers/index.js"
+    },
+    "./builtins": {
+      "types": "./dist/builtins/index.d.ts",
+      "default": "./dist/builtins/index.js"
     }
   },
   "publishConfig": {

package/skills/monitor/SKILL.md

@@ -29,11 +29,14 @@ Derive the workflow input from the full conversation:
 - `task`: State the complete objective, the exact current target and stable identifiers, authoritative status sources, durable progress and final-output surfaces, routine actions authorized by the monitor request, other recorded approvals, immutable boundaries, cost and credential rules, and required validation or downstream operations.
 - `everyMinutes`: Use the user's interval when present. Use `30` when the user gives no interval. The built-in workflow accepts intervals from 1 minute through 24 hours.
 - `stopWhen`: Infer verified completion from the full conversation. Describe completion of the complete objective, not only the end of one physical process. Also name material blockers that require human intervention.
+- `repair`: Include this object only when the request or an existing approval authorizes mutation. Set `authorized: true` and record the repository, scope, base branch, merge policy, and constraints that apply. Omit it for observation-only work.
 
 When the conversation gives no clear finish criterion, set `stopWhen` to `Stop only when the user explicitly asks to stop.` Do not use that fallback when a broader implementation, repair, publication, or deployment objective is clear from context.
 
 Do not invent a finite check count. Omit `maxChecks` unless the user explicitly requests one. The workflow host can apply its own safety upper bound. Disclose that bound if it appears.
 
+When repair is authorized, route a concrete code or design defect through the monitor's composed repair path. Supply the problem, observed evidence, and a stable fingerprint of the issue plus target state. The workflow runs outer `autodevise`, `autoimplement`, and internal redesign when needed, then checks the target again. Do not copy their prompts into the monitor task.
+
 ## Keep routine work moving
 
 While the workflow is active, do routine, bounded work required by the exact objective without asking for another confirmation. This includes:
@@ -140,7 +143,9 @@ Stop only for a material blocker, such as:
 - a cost, time, or resource ceiling that cannot safely contain the remaining work;
 - evidence that the requested result cannot be made truthful or valid under the current contract.
 
-Never keep paid workers retrying a deterministic shared failure. Contain affected work, report the evidence and ETA impact, and stop for a decision.
+Never keep paid workers retrying a deterministic shared failure. When repair is authorized and the defect is inside scope, stop affected work, preserve the evidence, and use the composed repair path. Stop for a decision when repair is outside scope or would change a protected contract.
+
+If the same issue and target-state fingerprint return after a completed repair, report the no-progress result and stop. Do not start the same repair again.
 
 ### Status unavailable