@osolmaz/pi-workflows 0.12.1 → 0.13.0

package/skills/monitor/SKILL.md

@@ -1,226 +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. Omit `repair.approval` for the default behavior: ask on each new repair plan and continue after 10 minutes without an answer. Use `{ "mode": "required" }` to block on plan changes or `{ "mode": "skip" }` to continue without asking.
-
-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
-  }
-}
-```
-
-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 shared plan-change path. Supply the problem, observed evidence, and a stable fingerprint of the issue plus target state. The path runs Autoplan, Autodoc, the configured plan decision, and Autoimplement, then checks the target again. Autoimplement does not ask again for the plan selected by Monitor. It uses the same shared path if later evidence requires another plan. Do not copy their prompts into the monitor task.
-
-### Repair plan decisions
-
-Omit `repair.approval` for autonomous mode. It asks the `operator` audience and continues with the exact presented plan after 10 minutes without an accepted answer.
-
-Block until the operator answers:
-
-```json
-{
-  "repair": {
-    "approval": {
-      "mode": "required"
-    }
-  }
-}
-```
-
-Continue without asking:
-
-```json
-{
-  "repair": {
-    "approval": {
-      "mode": "skip"
-    }
+    "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
   }
 }
 ```
 
-`continue` starts implementation. `stop` ends the repair truthfully. `replan` preserves the exact operator text, sends it through the shared plan-change workflow, records 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.
-
-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.
-
-## Paid infrastructure 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.
+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.
 
-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.
+## Observation steps
 
-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.
+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.
 
-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.
+Answer these questions:
 
-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.
+- 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?
 
-## Complete workflow checks
+Select one route:
 
-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.
+- `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.
 
-For each check:
+Keep Monitor state, goal state, and target work state separate. Never call the target running because Monitor itself is active.
 
-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.
+For `act`, provide one exact action with:
 
-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.
+- `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
 
-## Publish progress when measurable
+An action description records authority. It does not create authority.
 
-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.
+## Direct action steps
 
-Progress is optional. Do not invent it for work that has no factual count, total, rate, or source estimate.
+`advance` starts or continues normal requested work. `recover` restarts or resumes work after an operational stop.
 
-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.
+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.
 
-Each track uses `pi-workflows.progress.v1` and can include:
+Submit the real result with the unchanged failure and target-state IDs. Monitor observes again immediately. Do not wait for the next interval first.
 
-- `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.
+## Repair steps
 
-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.
+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.
 
-For several concurrent processes, publish one stable track per process. The Pi widget and viewers show them separately and keep each ETA independent.
+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.
 
-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.
+Stop affected paid workers at safe boundaries before repairing a shared code or data defect. Preserve durable outputs and failure evidence.
 
-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.
+If the same failure and target-state IDs return after one completed repair, stop. Do not run the same repair cycle again.
 
-## Apply finish rules
+## Authority and paid work
 
-### Still active
+Monitor may perform an action only when the full action is inside existing authority. Stop when authority is absent, unclear, or too narrow.
 
-Continue. Keep reports short unless the state changed materially.
+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.
 
-### Completed
+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.
 
-Stop only after the inferred finish criterion is true. Verify required final artifacts, checksums, receipts, publication state, or downstream health before selecting `stop`.
+Do not change protected model, method, data source, hardware class, provider/runtime contract, credential destination, production selection, or objective without new authority.
 
-### Failed, stopped, or blocked
+## Progress
 
-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.
+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.
 
-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.
+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.
 
-Stop only for a material blocker, such as:
+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.
 
-- 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.
+## Reports
 
-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.
+Every accepted observation produces one status notification. Use this form when target work is active:
 
-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,13 +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 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

@@ -30,7 +30,7 @@ Replace the example values below with facts from the conversation, then make one
 }
 ```
 
-The workflow is read-only. It collects committed and working-tree evidence, reads matching pull-request metadata when available, runs isolated reviews, verifies their claims, and reports one verdict. It does not edit files, post comments, or fix findings.
+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.