@osolmaz/pi-workflows 0.12.0 → 0.12.1

package/docs/HUMAN_DECISIONS.md

@@ -60,6 +60,10 @@ export default defineWorkflow({
     approve: humanDecision({
       audience: "operator",
       choices: planChoices,
+      onTimeout: {
+        afterMs: 10 * 60_000,
+        response: { choice: "continue" },
+      },
       request: ({ outputs }) => ({
         title: "Approve the implementation plan",
         subject: outputs.propose,
@@ -106,6 +110,8 @@ type PlanDecision =
 
 `humanDecisionEdge()` requires one destination for every choice. A missing or extra case is a TypeScript error. Runtime validation applies the same choice and input contract before an answer can win.
 
+`onTimeout` is optional. It supplies a positive duration and a response that satisfies the same choice contract. The request stores the resulting absolute deadline and validated response. When no human answer wins before the deadline, the decision recovery owner applies that response with `timeout` provenance. Omitting `onTimeout` keeps an indefinite wait. A request cannot combine `onTimeout` with a separate `expiresAt` value.
+
 ## Checkpoint behavior
 
 A human decision still has `nodeType: "checkpoint"`. The helper adds a human decision contract to that checkpoint.
@@ -118,9 +124,7 @@ When the engine reaches the node, it:
 4. asks the configured channels to deliver it; and
 5. parks the run in `waiting` state.
 
-When a valid answer is accepted, the continuation keeps the workflow's original input. The human answer becomes the checkpoint node's output in the continuation. Existing checkpoints keep their current behavior, where `/workflow answer` supplies the continuation input.
-
-This distinction preserves old workflow definitions and run bundles.
+When a valid answer is accepted, the continuation keeps the workflow's original input. The human answer becomes the checkpoint node's output in the continuation. Ordinary checkpoints keep their current behavior, where `/workflow answer` supplies the continuation input.
 
 ## Request and response contracts
 
@@ -136,12 +140,12 @@ A new decision request contains:
 - the logical audience;
 - the complete choice contract;
 - the canonical request digest;
-- an optional expiry rule; and
+- an optional absolute deadline and automatic response; and
 - the creation time.
 
-The presentation is an explicit display allowlist. A channel does not receive the subject and cannot infer operator text from it. The request digest binds the subject, visible presentation, title, revision, choices, and input prompts. Each choice has a stable ID and may have no input or one validated text input contract.
+The presentation is an explicit display allowlist. A channel does not receive the subject and cannot infer operator text from it. The request digest binds the subject, visible presentation, title, revision, choices, input prompts, deadline, and automatic response. Each choice has a stable ID and may have no input or one validated text input contract.
 
-The former `body` form remains available for existing workflow definitions. It creates a v1 request and uses a deterministic readable compatibility formatter. Oversized historical bodies receive a bounded readable prefix and an explicit omission notice with the full body digest and size. V1 request bytes and digests do not change.
+Human decisions use only `pi-workflows.human-decision-request.v1`. The former `body` request and all human-decision `v2` records are invalid. This is an alpha hard cutover: old waiting runs and decision state must be reset rather than migrated or reinterpreted.
 
 A submitted response contains:
 
@@ -268,9 +272,9 @@ Decision records live next to workflow run bundles under the pi-workflows state
 - channel settlement results; and
 - the continuation request and result.
 
-The resolution record uses a no-replace create. The first valid acceptance, cancellation, or expiry writer wins. Acceptance then materializes the matching accepted-answer detail. Cancellation or expiry materializes cancellation detail. A retry with the same response and idempotency key adopts the existing answer. A conflicting answer receives an `already decided` result.
+The resolution record uses a no-replace create. A valid human answer or eligible timeout response claims the same immutable resolution. The saved result includes `human` or `timeout` provenance. A timeout result has no human actor or channel identity. Cancellation writes a terminal tombstone that takes precedence over automatic continuation. A retry adopts the existing matching result. A conflicting or late answer receives an `already decided` result.
 
-The continuation run ID is derived from the accepted decision ID. Recovery adopts an existing matching continuation or creates it once. A crash after answer acceptance cannot run the next workflow step twice. The continuation run carries a redacted receipt with the decision ID, request digest, gate node ID, choice, acceptance time, and answer digest. Actor, channel, event, and idempotency provenance stays only in the private decision records and never enters the run bundle or model context.
+The continuation run ID is derived from the decision ID. Recovery adopts an existing matching continuation or creates it once. A crash after resolution cannot run the next workflow step twice. The continuation record and redacted receipt carry the resolution provenance, decision ID, request digest, gate node ID, choice, acceptance time, and answer digest. Human actor, channel, event, and idempotency details stay only in the private decision records and never enter the run bundle or model context.
 
 SQLite may index pending decisions and channel leases, but immutable decision files remain the source of truth. The index is disposable and rebuildable.
 
@@ -286,33 +290,19 @@ pi-workflows keeps solution choice, documentation, and implementation in separat
 
 `autoimplement` first finds the clear existing plan in its input, the conversation, or referenced canonical documents. It blocks when no clear plan exists. A caller can bypass discovery and autodoc only by supplying both the explicit plan and a `documentation` receipt whose plan digest matches it. A plan without that current-document evidence enters autodoc so the canonical documents are inspected and adopted or updated. The absence of a structured `plan` input never authorizes `autoplan`.
 
-If later implementation, verification, review, comments, or CI evidence invalidates the plan, autoimplement runs `autoplan`, sends the revised plan through `autodoc`, and then resumes implementation. An optional approval policy inserts `plan-approval` after the revised documentation.
+If later implementation, verification, review, comments, or CI evidence invalidates the plan, Autoimplement enters the shared plan-change workflow. That workflow runs Autoplan, Autodoc, plan approval, and bounded exact-text replanning. Monitor uses the same workflow for each new repair plan and passes the selected plan into Autoimplement without a second decision.
 
 ## Reusable plan approval workflow
 
-pi-workflows ships a typed `plan-approval` workflow built on `humanDecision()`. Its input contains the documented plan, plan digest, audience, and display summary. It has three named exits:
-
-- `continue`, with the approval receipt;
-- `stop`, with the stop receipt; and
-- `replan`, with the exact instructions and receipt.
-
-A parent can include it without copying prompts or channel handling:
+pi-workflows ships a typed `plan-approval` workflow built on `humanDecision()`. Its policy has three modes:
 
-```typescript
-includes: {
-  approval: includeWorkflow(planApproval, {
-    input: ({ outputs }) => ({
-      plan: outputs.devise.plan,
-      planDigest: outputs.devise.planDigest,
-      audience: "operator",
-    }),
-  }),
-},
-```
+- `auto` asks the configured audience and continues after the configured deadline. It defaults to audience `operator` and 10 minutes.
+- `required` waits for an explicit human answer.
+- `skip` creates no human decision and continues immediately.
 
-A `replan` exit returns to `autoplan` with the previous plan and the exact human instructions as new evidence. The revised plan passes through `autodoc`, receives a new digest, and enters a new approval decision. Step limits bound repeated replanning.
+The workflow has `continue`, `stop`, and exact-text `replan` exits. Continue reports `human`, `timeout`, or `skipped` provenance. Stop and replan always require a human answer.
 
-Monitor repair composes `autoplan`, `autodoc`, optional `plan-approval`, `autoimplement`, and a fresh target check. Autoimplement can mount the same approval workflow after evidence-driven redesign. Existing behavior stays unchanged when no approval policy is present.
+The internal plan-change workflow composes Autoplan, Autodoc, and plan approval once. It owns the replan count, plan digest, and positive revision. Autoimplement and Monitor include this workflow instead of copying approval routes. A plan supplied by the caller or already selected by Monitor bypasses another decision. Only a changed plan digest enters the gate.
 
 ## Recovery and cancellation
 
@@ -325,27 +315,27 @@ Recovery follows these rules:
 - ambiguous Telegram sends are not retried automatically;
 - duplicate channel updates are harmless;
 - stale responses are rejected;
-- one accepted response creates one continuation;
-- the winning channel dismisses any pending Pi dialog;
+- one human or timeout response creates one continuation;
+- the winning human answer or timeout policy dismisses any pending Pi dialog;
 - confirmed channel settlement is adopted without another remote call;
 - failed channel settlement has a bounded retry count and cannot create an unbounded record loop; and
 - cancellation resolves the owned waiting decision from durable state, even after restart, closes pending views, and prevents a later answer from continuing the run.
 
-A decision with no available channel remains waiting and reports the configuration problem. It does not silently continue or choose a default.
+A required decision with no available channel remains waiting and reports the configuration problem. An automatic decision does not need a channel to apply its saved response after the deadline. A skipped plan policy creates no decision.
 
 ## Compatibility
 
-Ordinary checkpoints, their continuation input behavior, and existing run bundles remain unchanged. V2 requests, accepted records, receipts, resolutions, and multipart delivery records are additive. Older viewers ignore them. Updated viewers label a human decision as a checkpoint, show the readable presentation and its fingerprint, and keep the canonical subject separate. Private channel configuration and transport identifiers remain hidden.
+This alpha change updates the current request, accepted-result, receipt, resolution, continuation, and snapshot contracts in place. Old active runs refuse resume through normal source and definition identity checks. There is no compatibility reader, migration, dual path, or new schema generation. Updated viewers label a human decision as a checkpoint, show its deadline and automatic action when present, and keep the canonical subject separate. Private channel configuration and transport identifiers remain hidden.
 
 The engine remains independent from Pi and Telegram. Core code owns decision contracts, validation, durable acceptance, and continuation. The Pi extension owns UI and channel lifecycle. The Telegram adapter owns Bot API translation. Workflow definitions own only the question, choices, audience, and routes.
 
 ## Contract impact
 
 - **Session state:** Pi records normal workflow messages and interactive decision results.
-- **Other persistent data:** additive decision records, a rebuildable private channel index, and private channel configuration.
+- **Other persistent data:** decision requests and resolutions can carry a deadline, automatic response, and resolution provenance in the existing decision store. The private channel index remains rebuildable.
 - **Pi internals:** none.
 - **Public Pi API:** documented extension lifecycle and UI methods only.
-- **Public pi-workflows API:** typed human choices, `humanDecision()`, `humanDecisionEdge()`, the channel interface, and the `plan-approval` workflow.
+- **Public pi-workflows API:** typed human choices, `humanDecision().onTimeout`, `humanDecisionEdge()`, the channel interface, the plan approval policy, and the shared plan-change workflow.
 
 ## Verification requirements
 

package/docs/HUMAN_DECISION_PRESENTATIONS.md

@@ -1,8 +1,8 @@
 # Human decision presentations
 
-This contract is implemented. New human decision requests separate their canonical
-subject from the complete readable message shown to an operator. Historical requests
-that use `body` remain compatible through a deterministic readable formatter.
+This contract is implemented. Human decision requests separate their canonical
+subject from the complete readable message shown to an operator. Human decisions use
+one v1 contract with no legacy body form or parallel schema version.
 The implementation plan is in
 [the human decision presentations plan](plans/2026-08-19-human-decision-presentations-plan.md).
 
@@ -52,7 +52,7 @@ not see `subject` unless the workflow explicitly copies selected text into
 
 ## Request contract
 
-A new request uses `pi-workflows.human-decision-request.v2`. It contains:
+A request uses `pi-workflows.human-decision-request.v1`. It contains:
 
 | Field                | Required | Meaning                                         |
 | -------------------- | -------- | ----------------------------------------------- |
@@ -255,25 +255,15 @@ It omits absent sections. It never serializes the plan object. `plan-approval`,
 `monitor`, `autoplan`, `autodoc`, and `autoimplement` reuse this presenter where
 they ask a person to approve a plan.
 
-## Compatibility
+## Alpha cutover
 
-Current v1 requests remain immutable.
+The human-decision request, accepted result, receipt, delivery, and resolution use one
+v1 schema family. The current structured subject and explicit presentation contract
+replaced the former body request and parallel v2 records in place.
 
-- A v1 string body becomes one readable paragraph at delivery time.
-- A v1 object body uses a deterministic compatibility formatter. It converts
-  stable key order into readable labels and fields with sections and lists.
-- An oversized v1 body remains answerable. The formatter keeps a bounded readable
-  prefix and adds an explicit omission notice with the full body digest and size.
-  It never hides omitted content behind an ellipsis.
-- The compatibility formatter reads only the historical `body`, which was
-  already the display field. It never reads a new structured subject.
-- V1 request bytes and digests do not change.
-- Pending and accepted v1 decisions continue to use v1 validation and digest
-  rules.
-- New preferred authoring emits v2. The existing body form remains a deprecated
-  compatibility overload until a separate removal is approved.
-
-No migration rewrites run bundles or decision records.
+Old waiting runs and human-decision state are incompatible. The runtime fails with a
+reset instruction instead of reading, migrating, or silently reinterpreting them.
+There is no compatibility reader, dual path, alias, or migration.
 
 ## Privacy and security
 
@@ -311,10 +301,10 @@ npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
 npx -y @simpledoc/simpledoc check
 ```
 
-Tests must cover schema validation, canonical digests, readable legacy bodies,
+Tests must cover schema validation, canonical digests, structured-value formatting,
 plan rendering, Pi and Telegram content parity, unsafe text, Unicode, multipart
-delivery, ambiguous sends, recovery, stale answers, viewer output, and proof
-that no channel serializes a subject as JSON.
+delivery, ambiguous sends, recovery, stale answers, viewer output, incompatible-state
+failure, and proof that no channel serializes a subject as JSON.
 
 ## Boundaries
 

package/docs/MONITOR.md

@@ -38,7 +38,7 @@ The monitor checks a target, sends one status notification after every accepted
 
 `repair` must set `authorized: true`. It can constrain scope, repository, base branch, merge behavior, and other implementation constraints. Omitted `merge` means the repair can prepare but cannot merge a pull request; merging requires explicit `merge: true`. Without this object the monitor is observation-only. Repair authority does not permit a protected model, benchmark, credential, hardware, spending, or scope change.
 
-`repair.approval` is optional. It contains a logical `audience` and `maxReplans` from 1 through 20. When present, monitor sends the documented repair plan through the reusable human `plan-approval` workflow. Continue starts implementation, stop ends the repair truthfully, and replan preserves exact operator text before autoplan and autodoc run again. The model-facing workflow tool cannot approve the gate.
+`repair.approval` uses `auto`, `required`, or `skip` mode. When omitted, Monitor uses `auto` with audience `operator`, a 10-minute timeout, and three allowed replans. Auto mode asks and then continues with the exact plan if no answer is accepted by the deadline. Required mode waits for an explicit human answer. Skip mode asks nothing. Continue starts implementation, stop ends the repair truthfully, and replan preserves exact operator text before the shared plan-change workflow runs again. The model-facing workflow tool cannot approve the gate.
 
 `reportWhen` is removed. The monitor always reports after every accepted check.
 
@@ -102,17 +102,11 @@ prepare
       ├─ continue → schedule → sleep → check
       └─ repair → repairGuard
            ├─ blocked → repairBlocked → repairReport → finish
-           └─ initialDesign: autoplan
+           └─ planChange
                 ├─ blocked → repairBlocked
-                └─ documentation: autodoc
+                └─ ready → implementation: autoimplement
                      ├─ blocked → repairBlocked
-                     ├─ no approval → implementation: autoimplement
-                     └─ approval: plan-approval
-                          ├─ stop → repairBlocked
-                          ├─ replan → initialDesign
-                          └─ continue → implementation: autoimplement
-                               ├─ blocked → repairBlocked
-                               └─ completed → check
+                     └─ completed → check
 ```
 
 - `prepare` is a `compute` node that validates and applies input defaults.
@@ -122,7 +116,7 @@ prepare
 - `report` is a `notify` node that queues exactly one report.
 - `decide` is a `compute` node that applies the route and check safety limit.
 - `repairGuard` stops a repeated issue when a completed repair did not change its fingerprint or observed target state.
-- `initialDesign`, `documentation`, optional `approval`, and `implementation` are included workflows. Replan returns exact operator text to initialDesign. Autoimplement can enter nested `autoplan`, then autodoc, when later evidence requires redesign.
+- `planChange` and `implementation` are included workflows. Plan change owns Autoplan, Autodoc, approval policy, and exact-text replanning. Autoimplement receives the selected plan without another decision and enters its own plan-change mount only when later evidence requires a changed plan.
 - `repairBlocked` and `repairReport` preserve a truthful blocked result and user notification.
 - `schedule` is a function `action` that publishes the next-check time.
 - `sleep` is the existing runtime-owned shell wait.

package/docs/WORKFLOW_COMPOSITION.md

@@ -265,7 +265,7 @@ monitor
 
 `autoimplement` requires a clear existing plan, but the structured `plan` input is optional because the plan can already be in conversation context or canonical documentation. It blocks when it cannot find a clear plan. It skips autodoc when documentation is current and includes autodoc when documentation is missing or stale. The absence of `input.plan` never routes to initial autoplan.
 
-Autoimplement includes `autoplan` only as evidence-driven `redesign`. When implementation, verification, review, comments, or CI proves that the approach is wrong, the revised plan passes through autodoc before implementation resumes. Local bugs go to a fix step instead.
+Autoimplement includes the shared plan-change workflow only as evidence-driven `redesign`. When implementation, verification, review, comments, or CI proves that the approach is wrong, the shared workflow runs Autoplan, Autodoc, the configured plan decision, and bounded replanning before implementation resumes. Local bugs go to a fix step instead. Existing supplied or discovered plans bypass the decision.
 
 Review rounds record findings at every severity from P0 through P2. P0 or P1 findings require another implementation and review round. A P2-only round can be addressed, but the workflow does not run the reviewer again solely because P2 work changed files.
 
@@ -281,16 +281,17 @@ Monitor remains observation-only unless its input explicitly authorizes mutation
 
 ```text
 check
-  -> initialDesign: autoplan
-  -> documentation: autodoc
-  -> approval: plan-approval when requested
-       -> replan: initialDesign
+  -> planChange
+       -> autoplan
+       -> autodoc
+       -> plan-approval
+            -> replan: autoplan
   -> implementation: autoimplement
-       -> redesign: autoplan -> autodoc when needed
+       -> redesign: planChange when needed
   -> check
 ```
 
-The outer `autoplan` creates the first plan. Autodoc records it before implementation. An optional plan approval gate can continue, stop, or return exact replan instructions to autoplan. The inner redesign mount revises a plan only when new evidence invalidates it and records the revision through autodoc. The monitor checks the target again after implementation and does not trust a repair claim by itself.
+The shared plan-change workflow creates, records, and gates each repair plan. Its default policy asks the `operator` audience and continues after 10 minutes without an answer. Required mode waits for an explicit answer. Skip mode creates no decision. Monitor passes the selected plan into Autoimplement, so Autoimplement does not ask about that digest again. A later Autoimplement redesign uses the same shared workflow for the changed digest. The monitor checks the target again after implementation and does not trust a repair claim by itself.
 
 A protected change to model choice, benchmark method, credentials, hardware, spending authority, or another user decision exits as blocked. The workflow never changes the protected part of the task silently.
 

package/docs/plans/2026-08-21-plan-change-approval-policy-plan.md

@@ -0,0 +1,322 @@
+---
+title: Plan Change Approval Policy Plan
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-21
+---
+
+# Plan change approval policy plan
+
+## Summary
+
+Autoimplement and Monitor must use one shared workflow whenever they create or revise a plan. The shared workflow plans, records the plan in canonical documentation, asks for the configured human decision, and handles bounded replanning.
+
+The default policy is autonomous. It asks the `operator` audience to continue, stop, or replan. If no valid answer is accepted within 10 minutes, it continues with the exact presented plan. A required policy waits for an explicit answer. A skip policy continues immediately without creating a human decision.
+
+The timeout default belongs to the general `humanDecision()` contract. It must be durable, deterministic, bound to the exact request and plan digest, and separate from a human answer. Autoimplement and Monitor must not contain their own decision timers or copies of approval and replan logic.
+
+## Goals
+
+The change must provide these results:
+
+- Every plan newly created or changed by Autoimplement or Monitor passes through one shared plan-change workflow.
+- Existing supplied or discovered plans do not receive a new decision.
+- The default policy asks for a decision and continues after 10 minutes when there is no answer.
+- Operators can require an explicit answer or skip the decision.
+- Pi and Telegram show and settle the same durable decision.
+- A human answer, timeout default, and cancellation cannot create more than one continuation.
+- Cancellation remains immediate and terminal.
+- Repeated entry with the same plan digest does not create another decision.
+- Monitor does not cause Autoimplement to ask again for the plan that Monitor already selected.
+
+## Approval policy
+
+Autoimplement and Monitor use the same policy shape:
+
+```ts
+type PlanApprovalPolicy = {
+  mode: "auto" | "required" | "skip";
+  audience?: string;
+  timeoutMinutes?: number;
+  maxReplans?: number;
+};
+```
+
+The workflow input field remains `approval`. When it is absent, parsing supplies this policy:
+
+```json
+{
+  "mode": "auto",
+  "audience": "operator",
+  "timeoutMinutes": 10,
+  "maxReplans": 3
+}
+```
+
+The modes have these meanings:
+
+- `auto` creates a human decision. It continues with the presented plan when no valid answer is accepted before the deadline.
+- `required` creates a human decision with no automatic response. It waits for `continue`, `stop`, or `replan`.
+- `skip` creates no human decision and continues immediately.
+
+`audience` defaults to `operator`. `timeoutMinutes` applies only to `auto` and defaults to 10. `maxReplans` defaults to 3 and bounds the exact-instructions replan loop. Parsers reject unknown fields, unsupported combinations, non-positive timeouts, and invalid replan limits.
+
+The skills must map common requests as follows:
+
+```json
+{
+  "approval": {
+    "mode": "required"
+  }
+}
+```
+
+Use this for requests such as “block on plan changes.”
+
+```json
+{
+  "approval": {
+    "mode": "skip"
+  }
+}
+```
+
+Use this for requests such as “do not block on plan changes.” Omitting `approval` uses the 10-minute autonomous default.
+
+## Shared plan-change workflow
+
+Add one internal finite workflow that owns this sequence:
+
+```text
+autoplan
+  -> autodoc
+  -> plan-approval
+       -> continue -> ready
+       -> stop -> blocked
+       -> replan -> autoplan
+```
+
+The workflow receives the planning problem, scope, constraints, repository and document context, previous plan, new evidence, and approval policy. It returns either:
+
+- `ready`, with the selected plan, plan digest, canonical documents, revision, and decision provenance; or
+- `blocked`, with the reason and evidence.
+
+The workflow owns the replan count and passes exact operator instructions back to Autoplan. Each changed plan gets a new positive revision. The plan digest binds the plan, documentation result, approval request, and final output.
+
+The workflow bypasses the human-decision node in `skip` mode but still records `skipped` as the plan selection provenance. It does not create a synthetic human receipt.
+
+Promote the existing approved-plan composition pattern into this internal built-in workflow. Keep `plan-approval` as the low-level reusable decision workflow. Do not add a standalone `plan-approval` skill.
+
+## Human-decision timeout default
+
+Extend the public `humanDecision()` definition with a general optional timeout response:
+
+```ts
+humanDecision({
+  audience: "operator",
+  choices,
+  request,
+  onTimeout: {
+    afterMs: 10 * 60_000,
+    response: { choice: "continue" },
+  },
+});
+```
+
+The policy may also be derived from the node context so the shared plan-change workflow can use its parsed input. `afterMs` must be a positive finite duration. The response must satisfy the same typed choice and input contract as a human response. An absent `onTimeout` keeps the current indefinite wait.
+
+When the engine creates the request, it computes and persists:
+
+- the absolute expiry time;
+- the validated default response;
+- the request and presentation digests;
+- the exact node and attempt identity; and
+- the plan digest and revision already present in the decision subject.
+
+The request digest includes the deadline policy and default response. A changed deadline, response, plan, or revision therefore creates a different request identity.
+
+## Resolution and provenance
+
+A timeout default is an automatic workflow-policy resolution. It is not a human answer and must not use a human actor or channel identity.
+
+The existing resolution record gains a distinct timeout-default outcome and provenance in place. Human acceptance, timeout default, and cancellation all compete for the same immutable resolution record. The first valid resolution wins. The accepted workflow output states whether the result came from:
+
+- `human`;
+- `timeout`;
+- `skipped`; or
+- `cancelled`, where a terminal record is exposed.
+
+A human answer is valid only before the deadline and while no terminal resolution exists. A late answer cannot replace a timeout default. A timeout resolver must re-read an existing resolution and adopt it rather than create another result.
+
+The plan-approval continue result carries the plan digest, decision revision, response, and resolution provenance. A timeout result carries no human actor. A skipped result carries no human-decision receipt.
+
+## Recovery and ownership
+
+Use the existing one-second human-decision recovery loop. Do not add a service, daemon, controller, or second timer system.
+
+For an unresolved request with an eligible timeout default, the current owner must:
+
+1. confirm that the parent run is still waiting at the same request;
+2. confirm that the request deadline has passed;
+3. confirm that the run and decision are not cancelled;
+4. atomically write or adopt the timeout-default resolution;
+5. create or adopt the deterministic continuation record;
+6. start the continuation only when the owning process can claim it; and
+7. settle every open Pi and Telegram view.
+
+If no owner is active at the deadline, the request becomes eligible at that time. The next active owner resolves it and starts or adopts the continuation. The saved absolute deadline means a restart does not restart the 10-minute period.
+
+Auto mode must continue after the deadline even when no decision channel is configured. Required mode remains waiting and reports the missing channel configuration. Skip mode does not use a channel.
+
+## Cancellation and races
+
+Explicit workflow cancellation remains terminal. It must cancel the waiting decision, close channel views, and prevent a timeout continuation.
+
+The cancellation path and timeout resolver must check the durable run cancellation state before and after claiming the decision resolution and before starting a continuation. If cancellation races with an automatic resolution, the cancelled run and its deterministic continuation must not execute more workflow nodes. A later recovery pass must not revive either run.
+
+A human answer and timeout default use the immutable resolution as their race boundary. Tests must cover both winners at the deadline boundary and prove that only one continuation can exist.
+
+## Autoimplement integration
+
+Autoimplement must use the shared plan-change workflow only for a changed plan produced by its internal redesign route.
+
+These plans bypass the gate:
+
+- an explicit plan supplied in the Autoimplement input;
+- a current plan found by plan discovery; and
+- a plan passed by Monitor after Monitor completed the shared plan-change workflow.
+
+When new evidence routes Autoimplement to redesign, the shared workflow receives the current plan as `previousPlan` and the new issue as evidence. A changed ready plan returns to implementation. A stopped or exhausted plan change returns blocked. The same digest must not create another decision after resume or route re-entry.
+
+Remove Autoimplement’s duplicate approval route, approval input mapping, and replan guard. Keep only policy parsing and the mapping into the shared workflow.
+
+## Monitor integration
+
+Each Monitor repair that requires a new plan enters the shared plan-change workflow. This includes every exact-instructions replan requested by the operator.
+
+A ready plan is passed to Autoimplement with its plan digest and canonical documentation state. Autoimplement treats it as selected and does not ask about it again. If Autoimplement later produces a changed plan because of implementation, review, or CI evidence, Autoimplement uses the shared workflow for that new digest.
+
+Remove Monitor’s duplicate approval route, plan-approval input mapping, and replan guard. Keep the monitor repair authorization, no-progress protection, and post-repair observation unchanged.
+
+## Skills and examples
+
+Update the Autoimplement and Monitor skills with complete one-shot calls for:
+
+- omitted approval, which uses the 10-minute autonomous default;
+- `approval.mode: "required"`; and
+- `approval.mode: "skip"`.
+
+The examples must retain the required task, scope, constraints, repository, base branch, merge authority, and other workflow-specific input. They must not show a model calling the answer action for a protected human decision.
+
+Update the workflow authoring skill and examples to explain `humanDecision().onTimeout`, timeout provenance, and the rule that only a policy-defined response can run automatically.
+
+## Public contracts and persisted data
+
+Change the current alpha contracts in place:
+
+- add `onTimeout` to the public typed human-decision definition;
+- add the persisted deadline and default response to the current human-decision request contract;
+- add timeout-default provenance to the current accepted result, receipt, resolution, continuation, and channel settlement handling where it applies;
+- add the shared `PlanApprovalPolicy` and plan-change input and output types;
+- change Autoimplement and Monitor approval inputs to the shared policy; and
+- keep existing camelCase JSON fields and current schema and contract identifiers.
+
+Persisted request and resolution JSON remains under the current human-decision state root. Run bundles remain under the current run store. Add no migration reader, dual read, dual write, alias, feature flag, or new schema generation.
+
+Increment the affected built-in revisions as one hard alpha cutover:
+
+- Autoimplement revision 6 to 7;
+- Monitor revision 7 to 8; and
+- plan-approval revision 2 to 3.
+
+Older active runs refuse resume through the existing source-change behavior. The new internal plan-change workflow does not need to be a user-facing catalog entry or skill.
+
+## Documentation
+
+When implementation ships, update:
+
+- `docs/HUMAN_DECISIONS.md` for timeout responses, provenance, recovery, races, and channel behavior;
+- `docs/WORKFLOW_COMPOSITION.md` for the shared plan-change workflow;
+- `docs/workflows.md` for the public API and Autoimplement behavior;
+- `docs/MONITOR.md` for repair-plan decisions;
+- `docs/run-bundles.md` for request, resolution, continuation, and snapshot fields;
+- Autoimplement and Monitor skill text and examples; and
+- package examples and generated layout fixtures affected by the graph change.
+
+Keep the previous human-decision and composition plans unchanged as historical records.
+
+## Implementation steps
+
+1. Add and validate the typed `humanDecision().onTimeout` contract. Bind the validated default response and absolute deadline into request identity and persisted request data.
+2. Extend the human-decision store with one atomic timeout-default resolution operation. Preserve one immutable resolution and one deterministic continuation.
+3. Update extension decision recovery to resolve eligible defaults, recover after restart, settle channels, and start only the owned continuation. Keep cancellation checks around resolution and continuation claims.
+4. Update Pi and Telegram decision presentation and settlement so the deadline and automatic action are clear and a completed timeout closes pending views.
+5. Extend plan-approval with the shared policy and explicit human, timeout, and skipped provenance.
+6. Add the internal shared plan-change workflow with Autoplan, Autodoc, plan approval, and bounded exact-instructions replanning.
+7. Replace the duplicate Autoimplement planning approval path with the shared workflow and gate only changed internal redesign results.
+8. Replace the duplicate Monitor repair-plan approval path with the shared workflow and pass its selected plan to Autoimplement without another decision.
+9. Update public exports, current schemas, built-in revisions, skills, examples, documentation, and generated fixtures.
+10. Run all unit, integration, real-Pi, documentation, formatting, dependency-boundary, and package-resource checks.
+
+## Tests
+
+Use fake clocks, temporary directories, and fake channels. Tests must not call a real model, use a real Telegram credential, or mutate a real remote.
+
+Cover:
+
+- `onTimeout` type and runtime validation;
+- absent timeout behavior;
+- the default 10-minute deadline;
+- custom positive timeout values;
+- invalid timeout and response combinations;
+- auto, required, and skip policy parsing;
+- human continue, stop, and exact-text replan;
+- human-answer and timeout-default races with each winner;
+- timeout provenance without a human actor;
+- late answer rejection;
+- immediate terminal cancellation before and during timeout resolution;
+- one continuation after concurrent or repeated recovery;
+- restart recovery before and after the deadline;
+- auto mode with no configured channel;
+- required mode with no configured channel;
+- Pi and Telegram delivery, expiry text, and settlement;
+- plan digest and positive revision binding;
+- no duplicate decision for the same digest;
+- bounded replans;
+- Autoimplement changed-plan routing;
+- Autoimplement supplied and discovered plan bypass;
+- Monitor repair-plan routing;
+- no second decision when Monitor passes its selected plan to Autoimplement;
+- later Autoimplement redesign after Monitor selection;
+- built-in revision refusal for old active runs;
+- package skill and workflow discovery; and
+- real-Pi continuation with a short fake-clock deadline and no real model.
+
+## Verification
+
+Run:
+
+```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
+```
+
+Inspect the complete public diff before each commit, push, or pull-request update. Verify GitHub CI and Pi Reviewer before delivery.
+
+## Boundaries
+
+This work changes only the pi-workflows repository. It may change the workflow engine, extension decision recovery, built-in workflow composition, skills, tests, examples, fixtures, and documentation needed for this policy.
+
+It must not:
+
+- change Pi core or use undocumented Pi APIs;
+- add a service, daemon, controller, scheduler, or persistence location;
+- change external services, credentials, Telegram configuration, CI policy, or unrelated repositories;
+- add a standalone plan-approval skill;
+- queue, revive, or extend deferred successor turns;
+- add compatibility readers, migrations, dual paths, new schema generations, aliases, or feature flags;
+- merge the implementation pull request; or
+- publish a package or release.