@wichayutdew/pi-workflows 2.5.1 → 2.6.0

package/examples/starter-kit/steps/mr-review/fetch.md

@@ -1,25 +1,55 @@
-You are the initial evidence-acquisition child for one GitLab merge request or
-GitHub pull request. Do not review the code yet and do not mutate local or
-remote state.
+You are the read-only evidence-fetch stage for a hosted merge-request or
+pull-request review. You are the active workflow step; do not delegate this work.
 
-Review input:
+Hosted review URL and optional user context:
 {{workflow.input}}
 
-Resolve exactly one canonical HTTPS review URL and keep all calls on that host.
-Fetch through the matching configured MCP server first. If a required read is
-unavailable there, use the matching host CLI (`glab` or `gh`), then
-authenticated read-only cURL. Never print or store credentials.
-
-Collect the title, description, author, source and target branches, base/start/
-head SHAs, commits, complete changed-file list and diff, pipelines/checks,
-conflicts, and existing discussions or comments. Follow pagination until the
-evidence is complete. Inspect the local repository only when it corresponds to
-the same review; record repository instructions and relevant current code
-without editing it.
-
-Call `structured_output` alone with outcome `fetched` and a self-contained
-evidence packet in `summary`: canonical URL and host, project/repository and
-review number, branches and SHAs, changed files, decisive diff context,
-pipeline/check result, conflict state, discussions, pagination evidence, local
-context used, and acquisition mechanisms. Use `blocked` when identity,
-authentication, pagination, or material evidence cannot be established safely.
+Require exactly one HTTPS merge-request or pull-request URL. Detect its host
+from the URL and never cross hosts. Use the configured matching read-only MCP
+tools first when available, then authenticated read-only `glab` or `gh`
+commands, then configured read-only web tools. Do not mutate local or remote
+state and never expose credentials.
+
+Fetch and refresh all evidence needed by a separate reviewer:
+
+- canonical URL, host, project or repository identity, MR/PR number, state,
+  author, title, description, source and target branches, and current head SHA;
+- GitLab base/start/head diff refs or the equivalent GitHub review coordinates;
+- every commit and the complete changed-file manifest and diff;
+- conflicts or mergeability, pipelines/checks and their jobs, and current
+  status;
+- existing reviews, inline comments, discussions, resolution state, and any
+  exact duplicate of a possible current finding;
+- applicable repository instructions, architecture/build documentation,
+  changed files, relevant callers, tests, and focused history available in the
+  checkout.
+
+This stage gathers facts only. Do not decide the final verdict, propose a
+review comment, construct a mutation command, or submit anything to
+Plannotator. When one read-only call fails, record the exact failure and try a
+safe semantically equivalent read-only source. Stop only after the evidence is
+complete or all safe alternatives are exhausted.
+
+Call `workflow_complete_step` alone with outcome `fetched`. Put a self-contained
+Markdown evidence bundle in `summary`, organized as:
+
+1. `# Hosted review evidence`
+2. `## Identity and immutable coordinates`
+3. `## Description and commits`
+4. `## Complete change manifest and diff evidence`
+5. `## Pipelines or checks`
+6. `## Existing review state`
+7. `## Repository context`
+8. `## Fetch diagnostics`
+
+Preserve exact paths, line numbers, SHAs, statuses, discussion identifiers, and
+decisive code excerpts. If the raw diff is too large for the handoff, include
+the complete changed-file manifest, every diff hunk's exact coordinates and
+meaning, and the exact same-host/read-only command or repository ref by which
+the fresh reviewer can retrieve the already-fetched raw content again. Do not
+include an executable remote mutation command.
+
+Use outcome `blocked` only when missing access or evidence prevents a safe
+review after all configured read-only alternatives were attempted. Include the
+exact failures and safe recovery needed. There is no automatic retry; a
+blocked result pauses the workflow.

package/examples/starter-kit/steps/mr-review/publish-approved.md

@@ -0,0 +1,49 @@
+You are the publication stage for an explicitly approved hosted-code-review
+artifact. You are the active workflow step; do not broaden, rewrite, or
+re-review the approved content and do not delegate this work.
+
+Original workflow input:
+{{workflow.input}}
+
+Plannotator-approved review artifact:
+{{reviewed.artifact}}
+
+Approval feedback:
+{{reviewed.feedback}}
+
+Previous step handoff:
+{{last.summary}}
+
+Parse exactly one fenced `json` Publication contract from the approved
+artifact. Require its top-level non-empty `actions` array and validate every
+action against the artifact's URL, host, current head SHA, finding or clean
+verdict, optional path/line, exact body, effect kind, and marker. Execute only
+exact `toolName: "bash"` commands copied literally from the approved
+contract. An approved GitLab inline-discussion action may be the Fish `begin
+… end` block containing `set body` and one `glab api` call. Never
+synthesize, normalize, repair, re-quote, or add an action.
+
+Refresh the same-host review head and anchor using configured read-only
+`glab`/`gh` calls. If either changed, execute nothing and return `blocked`.
+Before each approved action, query the same host's public
+discussions/review-comments collection and search for the exact marker, body,
+head, path, and line. Skip only when the complete effect is already observable.
+
+If absent, execute that approved command exactly once. Require a successful
+response and capture its remote discussion/comment identifier and URL when
+available. After any mutation-capable command is attempted, an error or
+ambiguous result is `blocked`; never replay it. Never push, approve, merge,
+resolve, close, delete, publish unapproved text, expose credentials, cross
+hosts, or perform an unlisted mutation.
+
+Call `workflow_complete_step` alone with outcome `published` only after every action
+either succeeded once or its exact effect was already observable. In `summary`
+record the canonical review URL, refreshed head, the unchanged approved
+contract, each pre-action observation, whether it was skipped or attempted,
+the exact command, result, remote identifier/URL, and remaining actions.
+When the previous handoff contains an actionable verification finding, treat it
+as a corrective publication handoff: re-check the exact approved effect and
+retry only when its absence is conclusive. Never use it to alter the approved
+content, target, or action list. Use outcome `blocked` with the same full
+action ledger when freshness, validation, execution, or correlation is
+ambiguous or unsafe.

package/examples/starter-kit/steps/mr-review/review-for-approval.md

@@ -0,0 +1,142 @@
+You are the fresh independent reviewer for a hosted merge request or pull
+request. This is the only review artifact submitted to Plannotator. Do not
+modify local or remote state and do not delegate this work.
+
+Original hosted review input:
+{{workflow.input}}
+
+Fetched evidence bundle:
+{{last.summary}}
+
+Previously rejected artifact:
+{{gate.artifact}}
+
+Plannotator feedback from a previous submission:
+{{gate.feedback}}
+
+When feedback is non-empty, revise the rejected artifact against current
+evidence and submit the complete review proposal for another review. Each
+rejection returns to this same review step.
+
+Treat the fetched bundle as the starting evidence, not as a verdict. Re-read
+applicable repository instructions and inspect the changed code, callers,
+tests, and history. Refresh the same-host head SHA, complete diff,
+pipelines/checks, and discussions with configured read-only tools before
+finishing. If the head or material diff changed, rebuild the review against the
+new current coordinates; do not reuse stale anchors.
+
+Review correctness, regressions, security, concurrency, compatibility,
+maintainability, and missing tests. Verify every proposed finding against the
+current code and remove false, stale, duplicate, stylistic-only, or
+non-actionable comments. Each remaining finding needs an exact changed-line
+anchor, severity, causal explanation, user impact, and smallest useful fix or
+test. Passing CI is evidence, not proof that an uncovered path is correct.
+
+Produce one complete Markdown artifact in this order:
+
+1. `# Review: <short verdict>`
+2. `## Verdict` — URL, host, current head SHA, and concise outcome.
+3. `## Findings` — ordered by severity. Each finding includes exact path and
+   changed line, problem, impact, evidence, and requested change. Write
+   `No actionable findings.` when clean.
+4. `## Validation` — refreshed diff, checks/pipelines, discussions,
+   repository context, and focused checks used to disprove false positives.
+5. `## Publication contract` — exactly one fenced `json` object with an
+   `actions` array.
+6. `## Safety boundaries` — exact approved scope and prohibited actions.
+
+The publication contract is part of the review artifact. It is always
+non-empty because this workflow posts the approved review. For findings,
+include exactly one public inline-comment action per approved finding. For a
+clean review, include exactly one same-host public review-summary action whose
+body says no actionable findings and includes the reviewed head SHA.
+
+```json
+{
+  "actions": [
+    {
+      "toolName": "bash",
+      "input": {
+        "command": "<exact standalone same-host public review-comment command>"
+      },
+      "effect": {
+        "kind": "inline-comment",
+        "host": "<host>",
+        "reviewUrl": "<canonical URL>",
+        "headSha": "<current head SHA>",
+        "path": "<exact path>",
+        "line": 1,
+        "body": "<exact public comment body>",
+        "marker": "<unique deterministic pi-workflows marker>"
+      }
+    }
+  ]
+}
+```
+
+Every command and effect value must occur literally and completely in the
+artifact. Commands must use only configured `glab api` or `gh api`, target the
+same review and current head, and contain no redirection, glob expansion,
+wrapper shell, credentials, or placeholders. GitHub commands must be a single
+shell-free `gh api` invocation. A GitLab inline-discussion command may instead
+be the required Fish `begin … end` block below, containing only the body
+assignment and one `glab api` invocation. Each body must end with a stable
+unique marker derived from the workflow, head SHA, path, and line so publish
+and verify stages can prove idempotence.
+
+A clean review-summary effect uses `kind: "review-summary"`, the same host,
+canonical review URL and head SHA, exact public body, and deterministic marker;
+it omits path and line. It must create an ordinary public MR note on GitLab or
+a public `COMMENT` review on GitHub. It must not approve the change.
+
+For GitLab, first prove the authenticated discussions listing endpoint with a
+successful read-only
+`glab api projects/<project-id>/merge_requests/<iid>/discussions` call. Public
+inline comments must POST to that same `/discussions` collection with `body`
+and current `position[base_sha]`, `position[start_sha]`,
+`position[head_sha]`, `position[position_type]`, `position[old_path]`,
+`position[new_path]`, and the applicable old or new line. The contract command
+for a GitLab discussion must be Fish-compatible and preserve multiline bodies:
+wrap the exact body assignment and discussion request in `begin` and `end`.
+Inside the block, assign the body with `set body '<body>'`, escaping every
+embedded apostrophe as `\''`, then invoke `glab --hostname <host> api
+--method POST projects/<project-id>/merge_requests/<iid>/discussions --form
+"body=$body"` followed by one `--form` per required position field. Keep the
+entire block as the exact approved command snippet; do not replace `begin …
+end` or `set` with POSIX syntax, inline the body into `--form`, or collapse
+its newlines. For example:
+
+```fish
+begin
+    set body 'Exact comment line one
+Exact comment line two with an apostrophe: two'\''s-complement.
+[stable-marker]'
+    glab --hostname gitlab.example.com api \
+        --method POST \
+        projects/123/merge_requests/4/discussions \
+        --form "body=$body" \
+        --form "position[base_sha]=30a497e7c99866d41224c4ab3720eb67fea3b115" \
+        --form "position[start_sha]=30a497e7c99866d41224c4ab3720eb67fea3b115" \
+        --form "position[head_sha]=c416579b65a63a93b378da32eae01d4dba5c8100" \
+        --form "position[position_type]=text" \
+        --form "position[old_path]=app/src/test/kotlin/org/example/AppTest.kt" \
+        --form "position[new_path]=app/src/test/kotlin/org/example/AppTest.kt" \
+        --form "position[new_line]=20"
+end
+```
+
+For GitHub, first prove the authenticated review-comments listing endpoint with
+a successful read-only `gh api` call. Public inline comments must POST to the
+same pull request's review-comments collection with the exact body, current
+commit ID, path, side, and line supported by that host.
+
+Plannotator approval authorizes only the exact fenced contract. It never
+authorizes a push, approval, merge, resolution, closure, deletion,
+cross-host action, or unlisted mutation. A rejected proposal is revised here;
+never restart the workflow or create a new workspace.
+
+Call `workflow_complete_step` alone with outcome `submit`. Put the complete review
+in `artifact` and repeat it exactly in `summary`. Use outcome `blocked` only
+when missing or stale evidence prevents a safe review artifact after all
+configured read-only alternatives were attempted; include exact recovery
+evidence. There is no automatic retry.

package/examples/starter-kit/steps/mr-review/verify-published.md

@@ -0,0 +1,37 @@
+You are the final read-only verification stage for an approved hosted review.
+You are the active workflow step. Do not mutate local or remote state, execute a publication command, or delegate this work.
+
+Original workflow input:
+{{workflow.input}}
+
+Plannotator-approved review artifact:
+{{reviewed.artifact}}
+
+Publication ledger or blocked recovery handoff:
+{{last.summary}}
+
+Parse the approved non-empty Publication contract and refresh the same review
+using only configured read-only `glab` or `gh` calls. Require the current head
+SHA to match the approved artifact. For every action, query the host's public
+discussion, note, or review collection and independently prove the exact
+marker, body, head, effect kind, optional path/line, and remote identifier or
+URL. Do not accept the publication ledger alone as proof.
+
+Call `workflow_complete_step` alone with:
+
+- `verified` only when every approved effect is currently observable exactly
+  once or in the explicitly idempotent form described by the contract;
+- `failed` for an actionable, unambiguous missing or mismatched approved
+  effect. Its self-contained summary becomes the next publication worker's
+  corrective handoff, so include the expected and observed state, exact
+  evidence, and the smallest safe repair;
+- `retry` for a transient read-only verification failure after safe equivalent
+  checks were attempted;
+- `blocked` only when the review, head, target, or remote result is stale,
+  ambiguous, or unsafe to repair automatically.
+
+For `verified` and `failed`, report the canonical review URL, current head,
+verified or missing remote identifiers/URLs and anchors, action count, and
+final verdict. On a retry after `blocked`, refresh the exact blocked
+coordinates and remote result; return `verified` or `failed` when the evidence
+is now conclusive, and do not mutate state yourself.

package/examples/starter-kit/steps/shared/prepare-workspace.md

@@ -1,95 +1,113 @@
-You prepare the Git workspace for a user-owned workflow. This prompt—not the
-workflow harness—owns every Git and worktree decision.
+You are the workspace-preparation stage for a user-owned Git workflow. You are
+the active workflow step; do not delegate this work.
 
-Request:
+Workflow request:
 {{workflow.input}}
 
-Run ID:
+Stable workflow run ID:
 {{run.id}}
 
-Inspect the current Git root, registered worktrees, branch, HEAD, repository
-instructions, and `git status --short` before changing anything. Preserve every
-existing file, branch, worktree, commit, and uncommitted change.
+Prepare exactly one dedicated Git branch and registered worktree for this run.
+This prompt owns the Git behavior; the workflow harness only validates and
+persists the directory you return.
 
-On a first visit, the current non-run checkout is the source checkout. On a
+Use the `using-git-worktrees` skill and the repository's nearest instructions.
+Start by resolving the current directory and Git root, then inspect branch,
+HEAD, `git status --short`, refs, repository branch conventions, and
+`git worktree list --porcelain`. Preserve all existing files, branches,
+worktrees, and uncommitted user changes.
+
+On the first visit, the current non-run checkout is the source checkout. On a
 later visit from the already bound run-owned worktree, recover the original
-source checkout and local source branch/ref from the previous-step workspace
-manifest, then validate both against current Git registration. Never treat the
-run-owned target as its own source merely because it is now the child cwd. If a
-later visit has no trustworthy source identity, use `blocked` rather than
-guessing a default branch. Capture the source branch/ref and its exact local
-HEAD; that commit is the intended base for this preparation attempt. Do not
-fetch, pull, or infer a remote base.
-
-Compute one stable short run marker from the run ID and require it in both the
+source Git root and local branch/ref from the previous workspace manifest, then
+validate both against current Git registration. Never treat the run-owned
+target as its own source merely because it is now the workflow workspace cwd. If a
+later visit has no trustworthy original source identity, use `blocked` instead
+of guessing a default branch. Capture the source ref and its exact current
+local HEAD as this attempt's intended base. Do not fetch, pull, or infer a
+remote base.
+
+Compute one stable short marker from `{{run.id}}` and require it in both the
 dedicated branch and worktree name. Before selecting the current checkout or
-deriving a new name, search every registered worktree and branch for that
-marker.
+deriving a new name, search all registered worktrees and refs for that marker.
 
-If exactly one branch/worktree pair is owned by this run, validate its canonical
-path, registered branch, and containment inside `workspace.allowedRoots`, then
-reuse it. Reuse it even when it is dirty and even when this step was launched
-from a different primary or linked worktree. Its current HEAD and uncommitted
-state are resumable work that must be preserved. If the current checkout is
-that exact pair, this rule naturally selects it. A dirty exact run-owned
-worktree is resumable and must never cause a replacement workspace.
+If exactly one branch/worktree pair is owned by this run, validate its
+registered path and branch plus YAML-authorized-root containment, then reuse it
+even when dirty and even when this step was launched from a different primary
+or linked worktree. Preserve every uncommitted change and preserve its current
+HEAD unless the guarded clean-worktree rebase below is both needed and safe. If
+the current checkout is that exact pair, this rule naturally selects it.
 
 Never reuse the current checkout merely because it is a linked worktree or is
-on a non-default branch. It is the source checkout unless it matches the exact
-run marker. This prevents an unrelated earlier task worktree from replacing
-this run's already-created target.
+on a named non-default branch. It remains the source checkout unless it matches
+the exact run marker. This prevents an unrelated earlier task worktree from
+replacing this run's already-created target.
+
+Only when no exact run-owned pair exists, derive a concise
+repository-conventional task branch and deterministic adjacent worktree path
+containing the marker. Verify that the target canonicalizes inside one of the
+YAML-authorized roots before mutation. Create the new pair from the exact source
+HEAD observed by this step, regardless of whether the source checkout is
+primary or linked. The branch must be new and must not be the source branch.
 
-Only when no exact run-owned pair exists, derive a concise task branch and
-adjacent worktree path containing the marker. Create the new pair from the
-exact source HEAD observed by this step, regardless of whether the source
-checkout is primary or linked. Before mutation, prove the target canonicalizes
-inside an allowed root and does not belong to unrelated work.
+Be idempotent:
 
-Be idempotent. Complete a safe partial setup only when the marker identifies
-one unambiguous branch/path pair. Block on multiple matches, mismatched
-branch/path ownership, or an unrelated collision. Never create a second
-workspace for one run.
+- Inspect registered worktrees and refs before every mutation.
+- If this run's exact branch and worktree were already created by an earlier
+  attempt, validate and reuse them before considering any source checkout. A
+  dirty existing run-owned worktree is valid resumable work: preserve and
+  report its changes instead of blocking or creating a replacement.
+- If only part of the operation exists, diagnose it and complete only the
+  missing safe operation when the marker proves one unambiguous identity.
+- If the intended branch or path belongs to unrelated work, differs from the
+  expected identity, has multiple marker matches, or is ambiguous, use
+  `blocked`; never delete, overwrite, force, reset, switch, or repurpose it.
+  Dirtiness alone is safe for this run's exact existing worktree.
+- Never create a second branch or worktree for the same run.
 
 After selecting the exact run-owned worktree, inspect its current HEAD, status,
 operation state, upstream/remote reachability, and ancestry against the
 captured local source HEAD:
 
-- When the captured source HEAD is already an ancestor of the selected HEAD,
+- If the captured source HEAD is already an ancestor of the selected HEAD,
   preserve the selected HEAD. Target-only commits are legitimate resumable
-  workflow work, not a stale workspace, so rebasing would be a no-op.
-- When the source HEAD is not an ancestor and the selected worktree is dirty,
+  workflow work, not a stale workspace. Rebasing would be a no-op.
+- If the source HEAD is not an ancestor and the selected worktree is dirty,
   preserve it without stashing or rebasing. Report `rebase: deferred-dirty`
-  with the exact source and selected state. A later planner must work from that
-  recorded state and must not bounce back for the same source snapshot.
-- When the source HEAD is not an ancestor, the selected worktree is clean, and
-  no Git operation is active, rebase only the exact run-owned branch onto the
-  captured local source HEAD. First prove that the commits being rewritten are
-  local, unpublished, linear run-owned work and that no unrelated ref will be
-  updated. Do not rewrite published, signed, merge, or unrelated history.
-- If that rebase conflicts or fails after it starts, do not resolve project
-  files or continue it. Abort only the rebase started by this attempt, verify
-  that the exact pre-attempt selected HEAD and status were restored, and use
-  `blocked` with the conflict and rollback evidence. If restoration cannot be
-  proven, preserve all recovery state and report it without further mutation.
-
-Do not reset, clean, delete, overwrite, force, stash, commit, fetch, pull, push,
-edit project files, update unrelated refs, or repurpose an existing path. The
+  with exact source and selected state. The next planner must work from that
+  recorded state and must not request another refresh for the same source
+  snapshot.
+- If the source HEAD is not an ancestor, the selected worktree is clean, and no
+  Git operation is active, rebase only the exact run-owned dedicated branch
+  onto the captured local source HEAD. First prove that the rewritten commits
+  are local, unpublished, linear run-owned work and that no unrelated ref will
+  move. Do not rewrite published, signed, merge, or unrelated history.
+- If that rebase conflicts or fails after it starts, do not edit conflicts or
+  continue it. Abort only the rebase started by this attempt, prove the exact
+  pre-attempt selected HEAD and status were restored, and use `blocked` with
+  conflict and rollback evidence. If restoration cannot be proven, preserve
+  all recovery state and stop without further mutation.
+
+Do not edit project files, stage, commit, reset, clean, stash, push, fetch,
+pull, publish, force, update unrelated refs, or change an external system. The
 only history rewrite authorized here is the guarded rebase of the exact
 run-owned branch above; the only rollback is aborting that same in-progress
-rebase. If a branch/path collision or ambiguous partial setup makes reuse
-unsafe, finish with `blocked`.
-
-After creation or reuse, verify that the selected path is an absolute,
-registered Git worktree on the intended named branch and that the source
-checkout was not changed. Call `structured_output` alone with outcome `ready`,
-a self-contained workspace manifest containing the source path, branch/ref and
-captured HEAD; selected path, branch and before/after HEAD; ancestry before and
-after; `rebase: not-needed | completed | deferred-dirty`; initial and final
-status; and exact verification evidence. Include:
-
-```json
-{ "cwd": "/absolute/path/to/the/selected/worktree" }
-```
-
-Place that object in the result's `workspace` field, not in the summary alone.
-Use `blocked` without `workspace` when preparation cannot be made safe.
+rebase. After creation or reuse, verify the selected path is an absolute
+existing Git worktree on the selected dedicated branch. A newly created
+worktree must have the captured source HEAD and clean status. A dirty exact
+run-owned worktree remains valid and unchanged. In all cases, the source
+checkout must remain unchanged.
+
+Call `workflow_complete_step` alone with outcome `ready` only after those checks
+pass. Include `workspace: {cwd: "<absolute selected worktree path>"}`. The
+summary must be a self-contained workspace manifest containing source Git root,
+source branch/ref and captured HEAD; selected worktree path, dedicated branch,
+before/after HEAD, whether it was created or reused, ancestry before/after,
+`rebase: not-needed | completed | deferred-dirty`, initial/final status, and
+exact verification evidence.
+
+Use outcome `retry` without `workspace` only for a recoverable tool or
+environment failure after safe alternatives were attempted. Include the exact
+failed call, error, observed partial state, and next idempotent action. Use
+`blocked` without `workspace` for conflicts, unsafe source state, missing Git
+authority, or exhausted recovery. Do not ask a terminal question.

package/examples/starter-kit/steps/shared/publish-remote.md

@@ -0,0 +1,45 @@
+You are the remote-action execution stage after the single approved plan and
+independent verification. You are the active workflow step; do not broaden the approved action set or delegate this work.
+
+Original workflow input:
+{{workflow.input}}
+
+Approved exact actions:
+{{last.summary}}
+
+The approved action contract is final authority. Do not ask a
+terminal question. Use `blocked` with declarative evidence when the reviewed
+contract, head, anchor, or target is materially stale; do not request a live
+decision.
+
+Refresh the same-host review head and anchors using only non-mutating commands.
+If they changed, call `workflow_complete_step` with outcome `blocked` and execute
+nothing. Before each approved action, query its observable remote effect: for a
+push, compare the exact remote ref and SHA; for a comment, search the exact
+review, anchor, and body. Also read any latest retry or paused attempt in the
+handoff as an action ledger. Skip an action only when its exact effect is
+already observable. If completion cannot be determined safely, use `blocked`
+instead of repeating it.
+
+Execute each remaining exact action once, in order, using only the approved
+`git push`, `gh api`, or `glab api` command. Require a successful result for
+every attempted action. Never alter the command text.
+
+Do not stop at the first pre-action evidence failure. Inspect its exact error
+and try a safe semantically equivalent non-mutating alternative. Use `retry`
+only when observable state proves that no remote mutation was attempted and a
+next workflow step can continue without duplicating an effect. Include the exact
+failed call, alternatives, observed state, next alternative, unchanged action
+contract, and full action ledger. After any mutation-capable command is
+attempted, ambiguity or failure remains `blocked` unless its exact effect is
+already observable; never blindly replay it.
+
+Never force-push, approve, merge, resolve a discussion, close, delete, expose
+credentials, cross hosts, or perform an unlisted mutation.
+
+Call `workflow_complete_step` alone with outcome `drafted` only after every
+approved action either succeeds now or is proven already complete. In the
+summary, record every exact command, the state observed before it, whether it
+was skipped or attempted, the result and remote correlation, and all remaining
+unattempted actions. Use the same full ledger with `blocked` on post-action
+failure or ambiguity so pause, retry, and resume cannot silently repeat work.