@osolmaz/pi-workflows 0.10.0 → 0.11.1

package/docs/plans/2026-08-20-autoimplement-blocker-challenge-plan.md

@@ -0,0 +1,138 @@
+---
+title: Confirm blockers before autoimplement stops
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-20
+---
+
+# Confirm blockers before autoimplement stops
+
+Autoimplement must not stop only because one model says that work is blocked. A separate agent must challenge the claim and confirm that the blocker is real before the workflow uses its terminal blocked result.
+
+The canonical workflow behavior is in [Workflow authoring reference](../workflows.md#built-in-planning-and-implementation).
+
+## Outcome
+
+Add one independent `challengeBlocker` agent node to the built-in autoimplement workflow. Use only existing public Pi Workflows primitives. Keep the graph explicit and reuse the existing redesign include and terminal blocked result.
+
+The challenge asks these questions in plain terms:
+
+- Are you really blocked?
+- Is this really a blocker right now?
+- Can you find a safe way to move forward and finish this?
+- Are you getting stuck on something trivial, procedural, reversible, or already authorized?
+
+The challenge inspects the task, approved plan, current result, evidence, scope, authority, previous attempts, and viable alternatives. It distinguishes a true external blocker from normal rollout work, local implementation work, a design adjustment, a missing verification step, or a reversible operational task.
+
+## Output and validation
+
+The challenge returns this bounded structured output:
+
+```json
+{
+  "route": "continue | blocked",
+  "blockingNow": true,
+  "outsideAuthority": true,
+  "canProceed": false,
+  "reason": "concise reason",
+  "nextAction": "",
+  "alternativesChecked": ["checked alternative"],
+  "evidence": ["concrete evidence"]
+}
+```
+
+A terminal blocked result is valid only when all these conditions hold:
+
+- `route` is `blocked`.
+- `blockingNow` is `true`.
+- `outsideAuthority` is `true`.
+- `canProceed` is `false`.
+- `nextAction` is empty.
+- `alternativesChecked` contains checked practical alternatives.
+- `evidence` contains concrete evidence.
+
+A `continue` result must name the next practical action. Contradictory output, such as `route: blocked` with `canProceed: true`, cannot route to the terminal blocked result.
+
+Keep the output concise and bounded.
+
+## Routing
+
+Route `classifyImplementation.blocked` to `challengeBlocker`. A `continue` challenge result routes to the existing redesign include. Redesign can revise and document the plan, then return through implementation, verification, review, comment handling, CI, and delivery. A valid `blocked` result routes to the existing terminal blocked result.
+
+Inspect each later model-produced blocked exit in verification, review, comment handling, CI, delivery, and equivalent current nodes. Route operational or model-judged blockers through the same challenge when it is safe. Use one reusable challenge node and existing edges or includes. Do not copy the prompt into several nodes and do not add an engine-level blocker feature.
+
+Preserve direct terminal stops for these hard boundaries:
+
+- an explicit human stop;
+- cancellation;
+- an exhausted workflow safety or replan limit;
+- a protected authorization gap;
+- an independent blocked result from redesign when another challenge could make an unsafe or unbounded loop.
+
+Limit blocker challenges to three attempts in one run. Include all earlier challenge outputs in each later challenge prompt. If a fourth challenge would be needed, stop with the normal safety-limit reason. Do not repeat an unsupported blocker assertion.
+
+Include the latest challenge output in the workflow's latest-issue or context helper. A later redesign must receive the rejected blocker, its evidence, and its required next action.
+
+## Required behavior
+
+A supported cutover does not become blocked only because an artifact has an ownership or packaging mismatch. In the Bob artifact incident, authorized deployment and rollback make the safe rollout work part of the task. The challenge must return `continue`, name the next rollout action, and route to redesign.
+
+A missing external authorization for a prohibited remote mutation can remain blocked when no non-mutating path completes the task.
+
+A local test failure, stale package, packaging mismatch, rollback preparation, or deployment procedure is not, by itself, outside the granted authority.
+
+## Tests
+
+Add focused tests in `test/builtin-autoimplement.test.ts` or the best current autoimplement test file. Prove all these cases:
+
+1. A false blocker routes to redesign and continued work.
+2. A confirmed blocker reaches the terminal blocked result.
+3. Contradictory blocked output is rejected or cannot route to the terminal blocked result.
+4. The Bob artifact-ownership mismatch returns `continue` when rollout is authorized.
+5. An explicit human stop bypasses the challenge.
+6. A protected authorization gap remains a hard stop.
+7. An independent `redesign.blocked` path does not create a loop.
+8. Earlier challenge context is present and the three-attempt bound works.
+9. All relevant late-stage model-generated blocker routes use the challenge.
+10. Normal success paths remain unchanged.
+
+Keep compute nodes pure. Put the independent reasoning in the challenge agent node.
+
+## Documentation
+
+Update `docs/workflows.md` with the blocker-confirmation rule, hard-stop exceptions, and bounded routing. Keep the public behavior concise. Do not add internal details that users do not need.
+
+## Verification
+
+Run focused tests during development. Before completion, run these exact checks:
+
+```bash
+npm run check
+npm run test:e2e
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+git diff --check
+```
+
+Verify discovery and behavior through the installed package path or the repository's supported real-Pi end-to-end path. A fresh Pi process is required because built-in discovery is process-local.
+
+Review the final diff for missing blocker routes, accidental unbounded loops, and false terminal blockers. Fix each valid finding.
+
+## Boundaries
+
+- Preserve current run-bundle schemas unless a schema change is required. Do not add a persistence layer.
+- Use existing public Pi Workflows primitives only. Do not change Pi core.
+- Keep explicit human and protected authorization boundaries intact.
+- Use a hard cutover. Do not retain a legacy blocker route.
+- Preserve unrelated work and do not modify other repositories.
+- Make only the smallest source-based adjustment needed to preserve the approved behavior.
+- Do not stop for a trivial, reversible, or already authorized issue.
+- Commit coherent changes with a Conventional Commit message and push after all checks pass.
+- Do not publish a package, create a release, or merge anything.
+
+## Contract impact
+
+- **Session state:** normal workflow messages and tool results only.
+- **Other persistent data:** none beyond the existing run bundle records for normal node outputs.
+- **Pi internals:** none.
+- **Public Pi API:** existing documented extension APIs only.
+- **Public Pi Workflows API:** existing agent, compute, edge, and included-workflow primitives only.

package/docs/plans/2026-08-20-herdr-plugin-sync-plan.md

@@ -0,0 +1,104 @@
+---
+title: Keep the Herdr plugin linked after package updates
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-20
+---
+
+# Keep the Herdr plugin linked after package updates
+
+Pi Workflows ships its Herdr plugin inside the npm package. Herdr records the package's absolute path. npm can move an installed package between nested and hoisted `node_modules` directories during an update, which leaves Herdr linked to a path that no longer exists.
+
+Pi Workflows will own one explicit command that finds its own package and repairs this link. OnurPi will call that command after it installs an exact reviewed Pi Workflows release. OnurPi will not contain Herdr paths, manifests, or link-repair rules.
+
+## Outcome
+
+The canonical command is:
+
+```bash
+pi-workflows herdr sync --json
+```
+
+`pi-workflows herdr setup` remains an alias for compatibility.
+
+The command validates the bundled package before it changes Herdr. It then creates a missing link, enables a disabled link, leaves a correct link unchanged, or replaces a link to another package path or version. A successful result requires a new Herdr query that shows the expected plugin ID, package version, package root, manifest path, enabled state, and no warning.
+
+## Scope
+
+### Pi Workflows
+
+- Resolve the installed package root from the running CLI.
+- Validate `package.json`, `herdr-plugin.toml`, and the bundled viewer before changing Herdr.
+- Reconcile the current registration through Herdr's public CLI.
+- Return a versioned JSON result with one of `linked`, `relinked`, `enabled`, `unchanged`, or `unavailable`.
+- Return `unavailable` only when the Herdr executable is absent.
+- Treat malformed package data, malformed Herdr output, command failures, identity conflicts, and failed verification as errors.
+- Keep output bounded and use argument arrays instead of shell commands.
+- Test source and packed-package layouts, including paths that contain spaces.
+
+### OnurPi
+
+- Keep the Pi Workflows dependency pinned to an exact reviewed release.
+- Invoke the local `pi-workflows herdr sync --json` command from an explicit TypeScript sync script after dependency installation.
+- Accept the versioned result and keep Herdr-specific behavior in Pi Workflows.
+- Keep package installation free of `postinstall` side effects.
+
+## Non-goals
+
+- Do not create another Herdr plugin package or release.
+- Do not duplicate the manifest or viewer in OnurPi.
+- Do not add hard-coded `node_modules` paths.
+- Do not edit Herdr state files directly.
+- Do not change Herdr core or Pi core.
+- Do not hot-reload running Pi processes. A running process still needs `/reload` or restart after a package update.
+- Do not add a service, watcher, or implicit package-install mutation.
+
+## Command contract
+
+The JSON result uses schema `pi-workflows.herdr-sync.v1` and contains:
+
+- the result status;
+- whether Herdr state changed;
+- the plugin ID;
+- the expected and effective versions when available;
+- the effective enabled state when available;
+- a plain summary; and
+- an advisory that running Pi processes must reload after a package update.
+
+A missing Herdr executable returns `unavailable` with exit code zero because Herdr is an optional integration. Every other failure returns a nonzero exit code and does not claim success.
+
+The command preflights the new package before unlinking an old registration. Herdr currently exposes separate unlink and link commands, so replacement cannot be atomic. If replacement fails, Pi Workflows makes one restore attempt only when the previous package root still passes the same validation. It then reports the state found by a fresh Herdr query.
+
+Concurrent sync commands converge on the same target. After a failed or ambiguous mutation, the command queries Herdr and adopts the result only when another process already reached the exact expected state. It does not repeat the same mutation blindly.
+
+## Compatibility
+
+Existing `herdr setup` callers use the same implementation. Other Pi Workflows CLI commands do not change. The npm package remains the only source of the plugin manifest and viewer.
+
+OnurPi adds only invocation timing and result handling. It does not parse the Herdr manifest or issue link commands.
+
+## Verification
+
+### Pi Workflows
+
+- Test first link, unchanged link, disabled link, moved package path, stale path, and version update.
+- Test missing Herdr, malformed manifests, malformed plugin records, command failures, post-action mismatches, and bounded restore behavior.
+- Test concurrent adoption and paths with spaces.
+- Run the CLI from `npm pack` contents in nested and hoisted layouts.
+- Run `npm run check`, `npm run test:e2e`, Slophammer, SimpleDoc, and diff checks.
+
+### OnurPi
+
+- Test every structured result and invalid command output with a fake executable.
+- Verify the wrapper contains no plugin ID, manifest copy, Herdr mutation command, or package path.
+- Verify root and wrapper dependency pins remain equal.
+- Run `npm run check`, `npm run slophammer`, SimpleDoc, and diff checks.
+
+### Adoption
+
+After a separately approved Pi Workflows release, update OnurPi to that exact version and run:
+
+```bash
+npm run workflows:sync
+```
+
+Then verify the Herdr plugin list, open `piw`, and start or reload Pi to confirm resource discovery. Repeating the sync must return `unchanged`.

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.
 
@@ -210,8 +231,8 @@ The full run projection (`WorkflowRunState` in
   "workflowSources": [
     {
       "mountPath": ["redesign"],
-      "workflowName": "autodevise",
-      "source": { "kind": "builtin", "id": "autodevise", "revision": "1" }
+      "workflowName": "autoplan",
+      "source": { "kind": "builtin", "id": "autoplan", "revision": "1" }
     }
   ],
   "definitionDigest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",

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
@@ -271,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
@@ -364,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.
 
@@ -377,10 +413,16 @@ 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.
+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.
 
+A model-generated blocker from implementation or a safe later stage does not end autoimplement by itself. A separate blocker-challenge agent checks the task, approved plan, current result, evidence, scope, authority, earlier attempts, and practical alternatives. It confirms a blocker only when the blocker exists now, is outside the granted authority, has no safe path forward, has an empty next action, and includes concrete evidence and checked alternatives. A rejected blocker must name the next practical action and routes through the existing redesign workflow before implementation and verification continue.
+
+Autoimplement can run the blocker challenge at most three times in one run. Each later challenge receives the earlier challenge results. Reaching the limit stops with the normal workflow safety-limit reason. Explicit human stops, cancellation, exhausted workflow or replan limits, protected authorization gaps, and an independent blocked result from redesign remain direct stops. These hard boundaries do not enter the blocker challenge.
+
 ### Built-in monitor
 
 The built-in `monitor` workflow turns a plain request for repeated checks into
@@ -397,7 +439,7 @@ one looping workflow run. Its input is:
 }
 ```
 
-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.
+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:

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" },
+  ],
+});

package/examples/workflows/autoplan.workflow.ts

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

package/examples/workflows/human-decision.workflow.ts

@@ -0,0 +1,62 @@
+import {
+  choice,
+  compute,
+  defineHumanChoices,
+  defineWorkflow,
+  humanDecision,
+  humanDecisionEdge,
+  textInput,
+} from "@osolmaz/pi-workflows";
+
+const choices = defineHumanChoices({
+  continue: choice({ label: "Yes, continue" }),
+  stop: choice({ label: "No, stop" }),
+  replan: choice({
+    label: "Replan",
+    input: textInput({ name: "instructions", prompt: "What should change?" }),
+  }),
+});
+
+export default defineWorkflow({
+  name: "human-decision-example",
+  startAt: "proposal",
+  nodes: {
+    proposal: compute({
+      run: ({ input }) => ({
+        summary: "Apply the proposed workflow change.",
+        changes: ["Keep the durable subject.", "Show readable decision text."],
+        source: input,
+      }),
+    }),
+    approve: humanDecision({
+      audience: "operator",
+      choices,
+      request: ({ outputs }) => {
+        const proposal = outputs.proposal as { summary: string; changes: string[] };
+        return {
+          title: "Approve the proposal",
+          subject: proposal,
+          presentation: {
+            schema: "pi-workflows.decision-presentation.v1",
+            summary: proposal.summary,
+            blocks: [
+              { kind: "section", title: "Changes" },
+              { kind: "bullets", items: proposal.changes },
+            ],
+          },
+        };
+      },
+    }),
+    continued: compute({ run: ({ outputs }) => ({ status: "continue", answer: outputs.approve }) }),
+    stopped: compute({ run: ({ outputs }) => ({ status: "stop", answer: outputs.approve }) }),
+    replan: compute({ run: ({ outputs }) => ({ status: "replan", answer: outputs.approve }) }),
+  },
+  edges: [
+    { from: "proposal", to: "approve" },
+    humanDecisionEdge({
+      from: "approve",
+      choices,
+      cases: { continue: "continued", stop: "stopped", replan: "replan" },
+    }),
+  ],
+});

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "osolmaz.pi-workflows"
 name = "Pi Workflows"
-version = "0.10.0"
+version = "0.11.1"
 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.10.0",
+  "version": "0.11.1",
   "description": "Workflow and controller runtime with a live terminal viewer for the pi coding agent",
   "keywords": [
     "pi-package"
@@ -23,6 +23,7 @@
     "skills",
     "examples",
     "docs",
+    "schemas",
     "plugins/herdr",
     "herdr-plugin.toml",
     "README.md",

package/schemas/decision-presentation-v1.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/osolmaz/pi-workflows/schemas/decision-presentation-v1.schema.json",
+  "title": "Pi Workflows decision presentation v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "summary", "blocks"],
+  "properties": {
+    "schema": { "const": "pi-workflows.decision-presentation.v1" },
+    "summary": { "type": "string", "minLength": 1, "maxLength": 16000 },
+    "blocks": {
+      "type": "array",
+      "maxItems": 256,
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "text"],
+            "properties": {
+              "kind": { "const": "paragraph" },
+              "text": { "type": "string", "minLength": 1, "maxLength": 16000 }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "title"],
+            "properties": {
+              "kind": { "const": "section" },
+              "title": { "type": "string", "minLength": 1, "maxLength": 16000 }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "items"],
+            "properties": {
+              "kind": { "const": "bullets" },
+              "items": {
+                "type": "array",
+                "minItems": 1,
+                "maxItems": 256,
+                "items": { "type": "string", "minLength": 1, "maxLength": 16000 }
+              }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "items"],
+            "properties": {
+              "kind": { "const": "fields" },
+              "items": {
+                "type": "array",
+                "minItems": 1,
+                "maxItems": 256,
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["label", "value"],
+                  "properties": {
+                    "label": { "type": "string", "minLength": 1, "maxLength": 16000 },
+                    "value": { "type": "string", "minLength": 1, "maxLength": 16000 }
+                  }
+                }
+              }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "text"],
+            "properties": {
+              "kind": { "const": "preformatted" },
+              "text": { "type": "string", "minLength": 1, "maxLength": 16000 }
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/schemas/human-decision-accepted-v1.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-accepted-v1.schema.json",
+  "title": "Pi Workflows accepted human decision v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "decisionId",
+    "requestDigest",
+    "response",
+    "source",
+    "idempotencyKey",
+    "acceptedAt",
+    "answerDigest"
+  ],
+  "properties": {
+    "schema": { "const": "pi-workflows.human-decision-accepted.v1" },
+    "decisionId": { "type": "string" },
+    "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "response": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["choice"],
+      "properties": {
+        "choice": { "type": "string" },
+        "input": { "type": "object", "additionalProperties": { "type": "string" } }
+      }
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["channel", "actorId", "eventId"],
+      "properties": {
+        "channel": { "type": "string" },
+        "actorId": { "type": "string" },
+        "eventId": { "type": "string" }
+      }
+    },
+    "idempotencyKey": { "type": "string" },
+    "acceptedAt": { "type": "string", "format": "date-time" },
+    "answerDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
+  }
+}