@osolmaz/pi-workflows 0.12.0 → 0.13.0

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

@@ -8,13 +8,17 @@
     "schema",
     "decisionId",
     "requestDigest",
+    "subjectDigest",
+    "presentationDigest",
     "runId",
     "workflowName",
     "nodeId",
     "attemptId",
     "audience",
     "title",
-    "body",
+    "subject",
+    "presentation",
+    "revision",
     "choices",
     "createdAt"
   ],
@@ -22,13 +26,19 @@
     "schema": { "const": "pi-workflows.human-decision-request.v1" },
     "decisionId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$" },
     "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "subjectDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "presentationDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
     "runId": { "type": "string" },
     "workflowName": { "type": "string" },
     "nodeId": { "type": "string" },
     "attemptId": { "type": "string" },
     "audience": { "type": "string" },
     "title": { "type": "string", "minLength": 1 },
-    "body": true,
+    "subject": true,
+    "presentation": {
+      "$ref": "decision-presentation-v1.schema.json"
+    },
+    "revision": { "type": "integer", "minimum": 1 },
     "choices": {
       "type": "object",
       "minProperties": 1,
@@ -54,6 +64,16 @@
       }
     },
     "createdAt": { "type": "string", "format": "date-time" },
-    "expiresAt": { "type": "string", "format": "date-time" }
-  }
+    "expiresAt": { "type": "string", "format": "date-time" },
+    "defaultResponse": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["choice"],
+      "properties": {
+        "choice": { "type": "string" },
+        "input": { "type": "object", "additionalProperties": { "type": "string" } }
+      }
+    }
+  },
+  "dependentRequired": { "defaultResponse": ["expiresAt"] }
 }

package/skills/autoimplement/SKILL.md

@@ -20,6 +20,7 @@ Build the input as follows:
 - `baseBranch`: Use the requested base or the repository default branch.
 - `merge`: Set `true` only when the user explicitly requested merge or an applicable standing instruction authorizes it. Otherwise set `false`.
 - `documents`: Include known canonical plan or specification paths. Use an empty array when none are known.
+- `approval`: Omit it for the default behavior: ask on each new plan and continue after 10 minutes without an answer. Use `{ "mode": "required" }` when the user says to block on plan changes. Use `{ "mode": "skip" }` when the user says to continue without asking about plan changes.
 - `concurrency`: Include it only when the conversation gives explicit limits.
 
 When one repository is clearly named, derive the scope without asking the user to restate it. A safe derived scope permits only work needed for the task in that repository, including local verification and normal branch and pull-request publication. It excludes unrelated repositories, merge, release, deployment, credentials, and policy changes unless those actions are explicitly authorized.
@@ -51,6 +52,32 @@ Replace the example values below with facts from the conversation, then make one
 }
 ```
 
+### Plan-change decisions
+
+The workflow gates only plans that it creates or changes after the run starts. A supplied or discovered existing plan does not receive another decision.
+
+Use required approval when the user says to block on plan changes:
+
+```json
+{
+  "approval": {
+    "mode": "required"
+  }
+}
+```
+
+Skip plan decisions when the user says to accept every new plan immediately:
+
+```json
+{
+  "approval": {
+    "mode": "skip"
+  }
+}
+```
+
+Omit `approval` for autonomous mode. It asks the `operator` audience and continues with the exact presented plan after 10 minutes without an accepted answer. The workflow owns this decision. The model must not answer the protected decision through the workflow tool.
+
 Do not manually duplicate stages already owned by the workflow. Autoimplement runs independent pi-reviewer commands, pending CI watches, and local verification commands from separate repositories in bounded batches. It keeps model turns, fixes, pushes, comment changes, merges, and releases ordered. One repository uses the same batch path with concurrency one.
 
 When this skill is loaded inside an active workflow step, do not start another workflow. Complete the current step contract with the available tools.

package/skills/autoplan/SKILL.md

@@ -37,13 +37,14 @@ When this skill is loaded inside an active workflow step, do not start another w
 Outside Pi, or when the workflow is unavailable:
 
 1. Frame the problem, observable success criteria, scope, constraints, and interfaces under our control.
-2. Devise the most elegant long-term production-ready solution within that scope.
+2. Record two through four distinct practical candidates. Give each one a stable id, short title, plain gist, full solution, rationale, parts, and trade-offs.
 3. Describe the holy grail separately. Name every dependency outside our authority.
-4. Choose the right option without asking the user to decide between them.
+4. Choose the right option without asking the user to decide between them. Record one rejection reason for every other explicit candidate.
    - Choose the ideal when it is proportionate, production-ready, in scope, and implementable through interfaces we control.
    - Otherwise choose the strongest practical in-scope solution with a clear path toward the ideal.
    - Do not block only because the ideal requires an upstream or external change.
 5. Write a detailed implementation plan. For each step, state what changes, where it changes, and how to verify it.
-6. Stop as blocked only when no truthful in-scope solution can meet the success criteria.
+6. Present one short plain assistant message with the chosen plan, its main steps, and a one-line gist and rejection reason for every other candidate. Call it selected for approval when a later human decision still applies.
+7. Stop as blocked only when no truthful in-scope solution can meet the success criteria.
 
-When revising a plan, preserve the previous plan and new evidence. State whether the plan changed and why. Do not implement unless the user also requested implementation.
+When revising a plan, preserve the previous plan and new evidence. Record whether the previous plan remains a candidate or why new evidence rejects it. State whether the final plan changed and why. “All plans” means the explicit candidate records, never hidden model reasoning. Do not implement unless the user also requested implementation.

package/skills/monitor/SKILL.md

@@ -1,198 +1,154 @@
 ---
 name: monitor
-description: Use when the user asks to monitor, watch, track, or periodically check a running command, remote Job, CI run, deployment, publication, or other long-running objective. Starts the built-in Pi monitor workflow immediately in the current session and drives the objective autonomously, including routine recovery, until verified completion or a material blocker.
+description: Use when the user asks to monitor, watch, track, or periodically check a running command, remote Job, CI run, deployment, publication, or other long-running goal. Starts the built-in Pi monitor workflow immediately and finishes the authorized goal through direct advance, recovery, or composed repair work until completion or a material blocker.
 compatibility: Requires pi-workflows and the built-in monitor workflow.
 ---
 
 # Monitor
 
-Use the built-in Pi `monitor` workflow as an autopilot for the requested objective. Monitoring is not passive status polling. The agent must maintain nominal operation, repair recoverable failures, resume durable work, and continue until the complete objective is verified or a material blocker makes safe continuation impossible.
+Use the built-in Pi `monitor` workflow to finish the user's authorized goal. It observes the real target first, acts when safe authorized work is available, verifies every action immediately, and waits only while useful work is moving or an external event is pending.
 
-A monitor request authorizes routine, bounded work needed to preserve and finish the stated objective, subject to the conversation and repository approval boundaries. Apply other skills as safety and operating instructions. Do not turn their normal checks into new approval requests when the monitored objective and an existing approval already cover the action. Monitoring does not authorize changing the objective, method, model, data source, production selection, or other consequential contract.
+Monitoring does not grant new authority. Preserve the exact objective, allowed and forbidden changes, cost ceiling, provider and runtime contract, required checks, stop conditions, and recovery rules from the conversation and repository instructions.
 
-## Start the workflow without delay
+## Start the workflow
 
-Build the complete input and start the workflow in the same turn. As soon as the user invokes this skill:
+When no workflow is active, list workflows only when you must confirm that `monitor` is available. Build the complete input before starting, then call `workflow` with `action: "start"` exactly once in the same turn as the user's request.
 
-1. Read the current conversation, active plan, repository instructions, and applicable compute, runtime, credential, deployment, or publication skills.
-2. Preserve the exact objective, immutable execution contract, current identifiers, durable progress, cost already spent, approval ceilings, finish criteria, and known recovery rules in the workflow input. Write or update a durable plan or incident note first only when the work needs one for safe continuation.
-3. Make the workflow instructions faithful to what the user requested. Do not reduce an implementation or recovery objective to observation-only monitoring.
-4. Call `workflow` with `action: "start"` in the current Pi session without asking for another confirmation or waiting for a later turn.
-5. Let the first workflow check run immediately. Do not use Unified Exec sleeps, manual polling loops, a second scheduler, or a separate Pi session as a substitute.
+The public input has four fields:
 
-Do not finish the initiating turn before the workflow start call. If a safe contract cannot yet be written because a critical identifier or boundary is missing, gather it immediately when possible. Ask the user only when the missing decision is consequential and cannot be inferred safely.
+- `task`: Required. Put the complete goal, stable target identifiers, current durable progress, sources of truth, allowed files and systems, forbidden changes, cost limits, provider/runtime contract, required checks, allowed recovery actions, and stop boundaries here.
+- `stopWhen`: Optional. Use the user's complete finish rule. Omit it only when the user gave no finish rule, which means explicit user stop.
+- `everyMinutes`: Optional. Use the user's interval. The default is 30 minutes.
+- `maxChecks`: Optional. Include it only when the user supplied a check limit.
 
-## Build the monitor contract
+Do not send any other field. Inputs such as `repair`, `checkTimeoutMinutes`, `reportWhen`, and `audience` are invalid.
 
-Derive the workflow input from the full conversation:
+When the task can change code or remote state, make `task` state the absolute repository path, concrete edit and test scope, base branch, commit and push authority, pull-request and merge authority, release and deployment authority, and inherited constraints. A repository path alone is not a scope. Derive a narrow scope when one repository and task are clear instead of asking the user to repeat it.
 
-- `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.
-
-Replace the example values below with facts from the conversation, then make one start call:
+Replace the example values with facts from the conversation:
 
 ```json
 {
   "action": "start",
   "workflow": "monitor",
   "input": {
-    "task": "Monitor GitHub Actions run 123456 in owner/repository. Inspect the run and its artifacts, retry only transient status reads, and report each check. Do not change code or repository state.",
-    "everyMinutes": 5,
-    "stopWhen": "Stop when run 123456 completes and its required artifacts are verified, or when a material external blocker prevents truthful verification.",
-    "checkTimeoutMinutes": 10
-  }
-}
-```
-
-For authorized repair, add a complete `repair` object instead of leaving mutation authority implicit:
-
-```json
-{
-  "repair": {
-    "authorized": true,
-    "repository": "/absolute/path/to/repository",
-    "scope": "Only /absolute/path/to/repository. May diagnose and fix failures related to the monitored objective, test, commit, push, and update its pull request. Must not modify other repositories, merge, release, deploy, change credentials, or change repository policy.",
-    "constraints": ["Keep the monitored objective and method unchanged."],
-    "baseBranch": "main",
-    "merge": false
+    "task": "Finish the six missing modules in /absolute/path/to/repository. Resume only from verified saved outputs. May edit launch manifests and module outputs, run the named checks, and restart the existing pinned workers. Keep the current provider and runtime. Stay below the recorded cumulative cost ceiling. Do not change unrelated files, credentials, model selection, data source, base branch main, or production state. Commit and push are not authorized. Pull requests, merge, release, and deployment are not authorized. Stop before any action outside these limits.",
+    "stopWhen": "All 27 modules have verified durable outputs, or safe continuation is blocked.",
+    "everyMinutes": 15
   }
 }
 ```
 
-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 `autoplan`, standalone `autodoc`, optional `plan-approval`, `autoimplement`, and internal redesign when needed, then checks the target again. Do not copy their prompts into the monitor task.
-
-Add `repair.approval` only when the user requests a human plan decision. Set its named `audience` and a bounded `maxReplans`. A verified continue answer starts implementation. Stop ends the repair truthfully. Replan preserves the exact operator text, sends it back to autoplan, documents the revised plan, and asks again. The model-facing workflow answer tool cannot answer this gate.
-
-## 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:
-
-- downloading, building, and running code pinned by the monitored objective;
-- building and running task containers from a pinned benchmark or repository revision;
-- installing pinned dependencies in the planned isolated environment;
-- running canaries, tests, retries, restarts, and temporary cleanup;
-- repairing configuration or storage-path errors without changing the method; and
-- continuing paid work that already has applicable approval.
+Do not start a second Monitor for the same goal while one is active. When this skill is loaded inside a workflow step, complete that step. Do not start a nested workflow.
 
-Pinned third-party code is part of the objective when the task names its exact repository, revision, lock file, image digest, or benchmark release. Resolve mutable references to immutable revisions when the applicable safety rules require it. Do not ask once per image, package, or task. New unpinned code, unrelated code, or broader privileges remain outside the monitor's authority.
+## Observation steps
 
-## Paid infrastructure authority
+Every Monitor cycle starts with a read-only `observe` step. Use normal read-only tools to inspect the target's authoritative state, active work, durable outputs, checkpoints, failures, and applicable authority.
 
-A monitoring request does not grant spending approval or create a default spending ceiling. Before launching, resuming, retrying, or replacing paid work, load and follow the paid-compute, provider, Job-control, and runtime skills that apply. Use any applicable approval already recorded in the conversation or repository instructions.
+Answer these questions:
 
-When the paid action remains within the approved method, hardware, concurrency, cumulative cost ceiling, and recovery assumptions, continue without asking again. Stop for a decision before new paid work only when there is no applicable approval, the ceiling would be exceeded, or evidence invalidates an approved assumption.
+- Is the goal complete?
+- Is useful target work active?
+- Is the goal incomplete and idle?
+- Did work fail?
+- Is there a material blocker?
+- Which safe actions are already authorized?
 
-The monitor may use a credential only when the conversation or repository has already authorized that credential's source, destination, and purpose. It may reuse that authorization for retries and replacement attempts under the same objective. It must not discover unrelated credentials, broaden scopes, copy credentials to a new store, or print secret values.
+Select one route:
 
-Use the user-supplied interval instead of the example value when present. Add `maxChecks` only when the user explicitly supplies that limit. Do not send `reportWhen`; the current monitor reports every accepted check.
+- `wait`: Useful target work is moving, or an external event must finish.
+- `act`: The goal is incomplete and one safe authorized action is available.
+- `stop`: The goal is complete or cannot continue safely.
 
-Do not start a second monitor for the same objective while one is active. Update or replace the run only when the objective or contract changes. A replacement must preserve the previous accepted observation and durable recovery state.
+Keep Monitor state, goal state, and target work state separate. Never call the target running because Monitor itself is active.
 
-## Complete workflow checks
+For `act`, provide one exact action with:
 
-Each workflow check arrives with an exact step contract. Apply only the operational authority recorded in `task`. The default monitor contract is recovery-capable autopilot within recorded approval boundaries, not authority to create new spending or change the objective.
+- `kind`: `advance`, `recover`, or `repair`
+- incomplete work and factual evidence
+- the exact next action
+- the existing authorization and its source
+- allowed and forbidden mutation targets
+- cost and provider/runtime limits
+- required checks and stop conditions
+- verification method
+- stable failure and target-state IDs
 
-For each check:
+An action description records authority. It does not create authority.
 
-1. Query the target's authoritative status.
-2. Query durable progress and final-output surfaces. Run independent reads in parallel when useful.
-3. Compare the current values with the previous accepted observation.
-4. If operation is not nominal, preserve evidence, diagnose the issue, apply the smallest authorized repair, and verify that durable progress resumes. Fix issues and restart Jobs or processes when that is necessary to keep the same objective moving.
-5. Include a concise report for every accepted check. Report absolute totals and meaningful deltas when counters matter.
-6. Select `continue` or `stop` as required by the step contract.
-7. Call `workflow` with `action: "submit"` exactly once, using the supplied step and attempt IDs and the required output shape.
+## Direct action steps
 
-The workflow sends each report as a Pi notification. Notifications do not start a new assistant turn. Do not add a separate assistant reply to a workflow notification.
+`advance` starts or continues normal requested work. `recover` restarts or resumes work after an operational stop.
 
-## Publish progress when measurable
+The separate `act` step uses normal tools and performs only the stated action. Do not plan, document, redesign, broaden scope, or add related work. A routine start, resume, retry, launch-file refresh, or checkpoint continuation stays direct and small.
 
-The regular Pi model that runs the check is the observation adapter. It reads the target through the tools and sources named in the task, maps observed facts to progress tracks, and publishes them through the existing `workflow` tool. There is no separate monitor model.
+Submit the real result with the unchanged failure and target-state IDs. Monitor observes again immediately. Do not wait for the next interval first.
 
-Progress is optional. Do not invent it for work that has no factual count, total, rate, or source estimate.
+## Repair steps
 
-When the target exposes measurable progress, publish one or more tracks with `workflow` action `update` while the check is active when that gives the user useful current state. Include the latest tracks in the final check output, then call `submit` exactly once. Use a stable key for each independent process or workstream. Use `overall` for a real aggregate only; do not add unrelated tracks together.
+Use `repair` only for a code or configuration defect. Monitor composes the existing plan-change and Autoimplement workflows for repair. Do not start those workflows manually or copy their planning, documentation, implementation, review, or delivery steps.
 
-Each track uses `pi-workflows.progress.v1` and can include:
+Preserve the repair approval rule in `task`. `required` mode waits for an explicit operator choice. `skip` mode starts the selected repair without a gate. Default `auto` mode asks and then continues with the exact presented plan after 10 minutes when no answer arrives. These become the internal repair action's `"mode": "required"` or `"mode": "skip"`; they are not public Monitor input fields.
 
-- `status`: `pending`, `running`, `waiting`, `blocked`, `completed`, `failed`, `cancelled`, or `unknown`;
-- `label` and `phase` for short display text and estimation epochs;
-- `completed`, `total`, and `unit` for factual counts;
-- `sourceUpdatedAt` and `sourceEstimatedFinishAt` when the target provides its own fresh estimate.
+Stop affected paid workers at safe boundaries before repairing a shared code or data defect. Preserve durable outputs and failure evidence.
 
-Submit observed facts. The workflow computes rates, confidence, remaining work, and measured ETA from durable samples. Do not guess a count, rate, or ETA. A changed phase, total, unit, or lower completed count starts a new estimation epoch.
+If the same failure and target-state IDs return after one completed repair, stop. Do not run the same repair cycle again.
 
-For several concurrent processes, publish one stable track per process. The Pi widget and viewers show them separately and keep each ETA independent.
+## Authority and paid work
 
-Keep the monitored target independent of pi-workflows. Do not require a target Job or application to import pi-workflows, emit a Pi schema, write a Pi progress file, expose a Pi endpoint, create a progress store, or add a progress reader command solely for monitoring. Do not add provider-specific clients or credentials to pi-workflows. Target-specific observation belongs in the check task and is performed by the regular Pi model with already authorized tools.
+Monitor may perform an action only when the full action is inside existing authority. Stop when authority is absent, unclear, or too narrow.
 
-Before proposing a new progress API, transport, schema, or persistence layer, prove that the model cannot observe the needed facts and publish them through the existing `workflow update` and `submit` path. If the target does not expose enough facts for ETA, report `ETA unavailable`. Application telemetry changes require separate scope and should expose normal operational facts rather than a Pi-specific protocol.
+A monitoring request does not grant spending approval. Before paid work starts or resumes, verify the applicable approval, method, hardware, concurrency, cumulative cost, and remaining ceiling. When the next action remains inside those limits, continue without asking again. Stop when the next action would exceed the limit or when the limit cannot be verified.
 
-## Apply finish rules
+Pinned task code, images, packages, and dependencies that are already part of the authorized goal do not need a new decision for each normal use. Do not ask once per image, package, or task. New unpinned code, broader privileges, or a changed method remain outside authority.
 
-### Still active
+Do not change protected model, method, data source, hardware class, provider/runtime contract, credential destination, production selection, or objective without new authority.
 
-Continue. Keep reports short unless the state changed materially.
+## Progress
 
-### Completed
+The regular Pi model is the observation adapter. Read measurable facts with normal tools and publish useful progress through `workflow` action `update` while the step is active. Include the latest tracks in the final observation output.
 
-Stop only after the inferred finish criterion is true. Verify required final artifacts, checksums, receipts, publication state, or downstream health before selecting `stop`.
+Use stable keys. Report factual completed and total values, rates, and source ETA values only when the target exposes them. Otherwise report that progress or ETA is unavailable.
 
-### Failed, stopped, or blocked
+Do not require the monitored process, Job, application, provider, or repository to implement a Pi-specific API, file, endpoint, store, schema, command, service, transport, or dependency.
 
-Do not disarm the monitor for a superficial reason. One failed physical Job, command, CI run, deployment attempt, upload, or status read is not the end of the objective. Treat it as an operational event, preserve evidence and durable state, diagnose it, apply the smallest safe repair, restart or resume the same immutable contract, restore nominal operation, and keep monitoring.
+## Reports
 
-Examples of recoverable conditions include transient provider or network errors, platform eviction, rate limits, expired physical attempts, safe checkpoint reconciliation, exact path or configuration mistakes, bounded storage failures, and a stalled deployment that has a documented recovery action.
+Every accepted observation produces one status notification. Use this form when target work is active:
 
-Stop only for a material blocker, such as:
-
-- a deterministic shared code or data defect that makes further attempts unsafe;
-- an invalid, missing, or unverifiable checkpoint when useful state would be lost;
-- a required credential that has no prior source-and-destination authorization;
-- a changed model, method, source, hardware class, objective, or production decision;
-- a destructive or security-sensitive action outside the recorded authority;
-- 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. 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
-
-Retry only a cheap, bounded status read. If the source remains unavailable, report the gap. Continue only when observation remains safe and the finish criterion is not met.
-
-## Check the right surfaces
-
-Depending on the target, inspect:
-
-- Process, Job, workflow, CI, or deployment status.
-- Durable receipts and counters.
-- Checkpoints or partial outputs.
-- Final manifests, databases, publications, or release artifacts.
-- Error state and the freshness of the last durable update.
+```text
+Monitor: active
+Goal: incomplete
+Work: running
+Progress: 21/27 modules
+Last action: resumed six missing modules
+Next check: 15 minutes
+```
 
-Logs and progress counters alone do not prove saved work or completion. Prefer durable artifacts and authoritative remote state.
+Use this form when the target is idle and an action will run:
 
-## Stop on user request
+```text
+Monitor: active
+Goal: incomplete
+Work: idle
+Next action: refreshing launch files and resuming work now
+```
 
-When the user asks to stop, cancel the active monitor workflow with `workflow({ action: "cancel" })` and confirm that monitoring stopped. Do not wait for the next scheduled check.
+Show absolute progress before deltas. Do not invent an ETA.
 
-## Status format
+## Stop conditions
 
-For an unchanged active target, prefer a compact report:
+Stop when:
 
-```text
-Target remains running:
-- Progress: <absolute total> (<delta since last report>)
-- Cost or resource use: <total>
-- Durable output: <state>
-- Next check: <interval>
-```
+- the goal is complete
+- a material blocker prevents safe continuation
+- the next action is outside authority
+- a paid action lacks approval or would exceed its ceiling
+- a protected contract would change
+- a required credential lacks prior source-and-destination authority
+- a useful checkpoint is invalid or cannot be preserved
+- the same failure and target state return after one completed repair
+- the safety limit is reached
+- the user asks to stop
 
-Explain anomalies, failures, or approval boundaries when they occur. Avoid repeating the full history at every check.
+When the user asks to stop, cancel the active Monitor immediately with `workflow({ action: "cancel" })` and confirm that monitoring stopped.

package/skills/pi-workflows/SKILL.md

@@ -20,7 +20,7 @@ Use the smallest applicable action:
 - `pause`, `resume`, and `cancel` control the current active run.
 - `answer` supplies input to an ordinary waiting checkpoint. It cannot satisfy a protected `humanDecision()` gate.
 - `update` publishes a non-completing durable update for the active step attempt.
-- `submit` completes the active agent step with its required output.
+- `submit` completes an active submitted agent step with its required output. An assistant-message step completes through its normal visible reply instead.
 
 Use `start` only once for one requested run. Before starting, load the matching workflow skill when one exists and build its complete input. Include scope, authority, constraints, identifiers, and finish criteria required by that skill. Do not start with placeholders that still need user or model repair.
 
@@ -43,10 +43,10 @@ Do not build a manual polling loop around a workflow that already schedules its
 When a workflow step message arrives:
 
 1. Do the requested work with the available tools.
-2. Produce output that matches the exact expected shape.
-3. Call `workflow` with `action: "submit"` exactly once, using the step and attempt ids from that message.
-4. If validation rejects the output, correct it and submit again with the same current ids.
-5. After acceptance, end the turn. The workflow sends the next step or presentation message when needed.
+2. Follow the completion form in the current step contract.
+3. For a submitted step, produce the exact expected shape and call `workflow` with `action: "submit"` exactly once, using the current step and attempt ids. If validation rejects the output, correct it and submit again with the same ids.
+4. For an assistant-message step, reply with the requested normal assistant message. Do not call `workflow submit`; the settled visible reply is the node output.
+5. After completion, do not add another response. The workflow sends the next step or final presentation when needed.
 
 A node id can run more than once in a loop. Each run has a new attempt id. Never reuse an attempt id from conversation history.
 
@@ -70,12 +70,13 @@ Follow these rules:
 - Reuse a finite workflow with a direct typed `includeWorkflow()` mount. Use a controller only when the child needs an independent run or indefinite reconciliation.
 - Give included workflows named exits, map their input explicitly, and keep parent edges out of child internals.
 - Keep `compute` pure. Put external effects in agent, function-action, or shell-action nodes.
-- Use structured node outputs for routing.
-- Use an ordinary checkpoint for external continuation data that the model may submit. Use `humanDecision()` for a verified human choice, and use the included `plan-approval` workflow for standard continue, stop, and exact-text replan routing.
+- Use structured node outputs when the graph must inspect fields or choose a route. Use `expectedOutput: assistantMessage()` when exact visible text is the node result.
+- Use an ordinary checkpoint for external continuation data that the model may submit. Use `humanDecision()` for a verified human choice. Use its typed `onTimeout` policy only when the workflow may supply a named automatic response after a durable deadline. A timeout response is recorded as policy provenance, not as a human answer.
+- Use the shared internal plan-change workflow for Autoplan, Autodoc, plan approval, and bounded exact-text replanning. Do not copy that sequence into Autoimplement, Monitor, or another workflow.
 - Set explicit step and command timeouts.
 - Bound ordinary loops with `maxSteps` or another clear finish rule.
 - Use a controller instead of a workflow for indefinite resource reconciliation.
-- Keep presentation separate from execution. Use `presentationPrompt` only when a final assistant response is needed.
+- Keep presentation separate from execution. Use `presentationPrompt` for one root response after the run. Use an assistant-message agent when the visible response belongs inside the graph and a parent must continue after it.
 - Preserve the single active workflow rule in one Pi session.
 
 Read [../../docs/workflows.md](../../docs/workflows.md) before creating or changing a workflow. Read [../../docs/WORKFLOW_COMPOSITION.md](../../docs/WORKFLOW_COMPOSITION.md) for nested workflows. Read [../../docs/HUMAN_DECISIONS.md](../../docs/HUMAN_DECISIONS.md) before adding a human gate or channel. Read [../../docs/DESIGN_PHILOSOPHY.md](../../docs/DESIGN_PHILOSOPHY.md) before adding public primitives. Use the examples under [../../examples/workflows](../../examples/workflows) as starting points.

package/skills/sanity-check/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: sanity-check
+description: Use when the user asks for a read-only sanity check of a repository contribution, including whether it is necessary, duplicates existing code, adds justified contracts, or has proportionate scope and tests. Starts the built-in sanity-check workflow and returns an evidence-backed keep, simplify, refactor, drop, or needs-evidence verdict.
+compatibility: Requires pi-workflows and the built-in sanity-check workflow.
+---
+
+# Sanity Check
+
+## Start the workflow
+
+Use the built-in `sanity-check` workflow when it is available. At top level, list workflows, build the complete input, and start `sanity-check` once.
+
+The workflow reviews the repository of the current Pi session. Before starting, confirm that Pi's current working directory is inside the repository that owns the contribution. Do not claim to check a different repository. If the current directory is wrong, start or use a Pi session in the correct repository first.
+
+Build the input as follows:
+
+- `mode`: Use `serial` unless the user explicitly requests parallel review. Serial mode reviews all four areas in one isolated session. Parallel mode runs one isolated review per area with concurrency four. Both modes run a separate verification review.
+- `baseRef`: Use the requested base Git reference. When the base is clear, pass it explicitly, such as `origin/main`. Omit it only when the workflow should derive the base from `origin/HEAD`, the current branch upstream, or `HEAD^`.
+
+Replace the example values below with facts from the conversation, then make one start call:
+
+```json
+{
+  "action": "start",
+  "workflow": "sanity-check",
+  "input": {
+    "mode": "serial",
+    "baseRef": "origin/main"
+  }
+}
+```
+
+The workflow is read-only. It collects committed and working-tree evidence, reads matching pull-request metadata when available, runs isolated reviews, and verifies their claims. It then shows the full detailed report as a normal assistant message, followed by a short plain-language assistant summary. The strict verified verdict remains the workflow result. It does not edit files, post comments, or fix findings.
+
+When this skill is loaded inside an active workflow step, do not start another workflow. Complete the current step contract.
+
+Outside Pi, or when the workflow is unavailable:
+
+1. Collect the committed diff from the selected base through `HEAD`, the working-tree diff, untracked files, and matching pull-request context.
+2. Review necessity, duplication, contracts, and scope and tests.
+3. For each area, report pass, concern, or unclear with exact file and symbol evidence.
+4. State the strongest evidence-based case for accepting the contribution.
+5. Verify the findings, remove unsupported claims, and return keep, simplify, refactor, drop, or needs evidence.
+6. Stay read-only unless the user separately asks to implement the required changes.