@wichayutdew/pi-workflows 2.3.0 → 2.4.1

package/agents/step.md

@@ -22,3 +22,11 @@ pi-subagents' `structured_output`; `workflow_complete_step` belongs to
 main-agent workflow steps. Never call `contact_supervisor`,
 `subagent_supervisor`, or `intercom`. The workflow prompt defines artifact
 content and format, acceptance criteria, and the meaning of every outcome.
+
+For a non-success outcome, treat `summary` as an operator handoff, not a
+diagnostic transcript: lead with a plain-language decision, list each
+independent issue with its decisive evidence and the concrete action/owner, and
+end with the safe next move. Omit policy narration, raw logs, successful-check
+or clean-state notes, and assertions that the child lacks authority; state the
+prerequisite that would unblock it. Mention a passed check only when it directly
+explains the remaining issue.

package/dist/index.js

@@ -786,16 +786,16 @@ function parseWorkspaceRoots(value, path, errors) {
   if (value === undefined)
     return ["."];
   if (!Array.isArray(value)) {
-    errors.push(`${path}: expected an array of relative paths`);
+    errors.push(`${path}: expected an array of workspace paths`);
     return [];
   }
   if (value.length > MAX_WORKSPACE_ALLOWED_ROOTS) {
-    errors.push(`${path}: at most ${MAX_WORKSPACE_ALLOWED_ROOTS} relative paths are allowed`);
+    errors.push(`${path}: at most ${MAX_WORKSPACE_ALLOWED_ROOTS} workspace paths are allowed`);
   }
   const roots = value.slice(0, MAX_WORKSPACE_ALLOWED_ROOTS).reduce((result, item, index) => {
     const itemPath = `${path}[${index}]`;
     if (typeof item !== "string" || !item || item.trim() !== item) {
-      errors.push(`${itemPath}: expected a non-empty relative path`);
+      errors.push(`${itemPath}: expected a non-empty workspace path`);
       return result;
     }
     const root = item;
@@ -803,8 +803,8 @@ function parseWorkspaceRoots(value, path, errors) {
       errors.push(`${itemPath}: path exceeds ${MAX_WORKSPACE_PATH_CHARS} characters`);
       return result;
     }
-    if (root.includes("\x00") || isAbsolute(root) || win32.parse(root).root !== "") {
-      errors.push(`${itemPath}: expected a relative path`);
+    if (root.includes("\x00") || win32.parse(root).root !== "" && !isAbsolute(root)) {
+      errors.push(`${itemPath}: expected a relative, absolute, or home-relative path`);
       return result;
     }
     if (result.includes(root)) {
@@ -814,7 +814,7 @@ function parseWorkspaceRoots(value, path, errors) {
     return [...result, root];
   }, []);
   if (roots.length === 0) {
-    errors.push(`${path}: at least one relative path is required`);
+    errors.push(`${path}: at least one workspace path is required`);
   }
   return roots;
 }
@@ -2381,7 +2381,7 @@ var parseWorkspace2 = (value, outcomes) => {
   if (!isStringArray(bindOn) || bindOn.length === 0 || new Set(bindOn).size !== bindOn.length || bindOn.some((outcome) => !outcomes.includes(outcome))) {
     throw new Error("child policy workspace bindOn outcomes are invalid");
   }
-  if (!isStringArray(allowedRoots) || allowedRoots.length === 0 || allowedRoots.length > MAX_WORKSPACE_ALLOWED_ROOTS || new Set(allowedRoots).size !== allowedRoots.length || allowedRoots.some((root) => !root.trim() || root !== root.trim() || root.length > MAX_WORKSPACE_PATH_CHARS || root.includes("\x00") || isAbsolute4(root) || win322.parse(root).root !== "")) {
+  if (!isStringArray(allowedRoots) || allowedRoots.length === 0 || allowedRoots.length > MAX_WORKSPACE_ALLOWED_ROOTS || new Set(allowedRoots).size !== allowedRoots.length || allowedRoots.some((root) => !root.trim() || root !== root.trim() || root.length > MAX_WORKSPACE_PATH_CHARS || root.includes("\x00") || win322.parse(root).root !== "" && !isAbsolute4(root))) {
     throw new Error("child policy workspace allowed roots are invalid");
   }
   return { workspace: { bindOn, allowedRoots } };
@@ -5316,11 +5316,13 @@ async function showWorkflowStatus(ctx, getSnapshot, statusShortcut = DEFAULT_STA
 }
 // src/harness/workspace-directory.ts
 import { realpathSync, statSync } from "node:fs";
+import { homedir as homedir2 } from "node:os";
 import { isAbsolute as isAbsolute10, relative as relative6, resolve as resolve10, sep as sep5, win32 as win323 } from "node:path";
 var isWithin2 = (root, candidate) => {
   const pathFromRoot = relative6(root, candidate);
   return pathFromRoot === "" || pathFromRoot !== ".." && !pathFromRoot.startsWith(`..${sep5}`) && !isAbsolute10(pathFromRoot);
 };
+var resolveAllowedRoot = (startCwd, allowedRoot) => allowedRoot === "~" ? homedir2() : allowedRoot.startsWith("~/") ? resolve10(homedir2(), allowedRoot.slice(2)) : isAbsolute10(allowedRoot) ? allowedRoot : resolve10(startCwd, allowedRoot);
 function resolveWorkspaceDirectory({
   candidateCwd,
   startCwd,
@@ -5337,10 +5339,10 @@ function resolveWorkspaceDirectory({
   }
   const canonicalStart = realpathSync(startCwd);
   const canonicalRoots = allowedRoots.map((allowedRoot) => {
-    if (!allowedRoot || isAbsolute10(allowedRoot) || win323.parse(allowedRoot).root !== "" || allowedRoot.includes("\x00")) {
-      throw new Error("workspace allowed roots must be non-empty relative paths");
+    if (!allowedRoot || win323.parse(allowedRoot).root !== "" && !isAbsolute10(allowedRoot) || allowedRoot.includes("\x00")) {
+      throw new Error("workspace allowed roots must be non-empty relative, absolute, or home-relative paths");
     }
-    return realpathSync(resolve10(canonicalStart, allowedRoot));
+    return realpathSync(resolveAllowedRoot(canonicalStart, allowedRoot));
   });
   const canonicalCwd = realpathSync(candidateCwd);
   if (!statSync(canonicalCwd).isDirectory()) {
@@ -7000,6 +7002,25 @@ function buildDelegatedCompletionInstructions() {
     "Stay within the configured permissions and do not broaden mutation targets or external side effects."
   ];
 }
+function buildNonSuccessSummaryInstructions(outcomes) {
+  const nonSuccessOutcomes = outcomes.filter((outcome) => ["blocked", "failed", "retry"].includes(outcome));
+  if (nonSuccessOutcomes.length === 0)
+    return [];
+  return [
+    "## Human-readable non-success results",
+    "",
+    `For ${nonSuccessOutcomes.map((outcome) => `\`${outcome}\``).join(", ")}, write a decision-first summary. It is shown verbatim to the operator and handed to a fresh child. Use this format:`,
+    "",
+    "# <Failed | Blocked | Retry>: <one-sentence plain-language decision>",
+    "1. **<short issue>** — <only the decisive evidence, including an exact command/error, path, or identifier when it enables action>.",
+    "   **Action:** <the specific owner or role> must <the concrete evidence, decision, or change needed>.",
+    "2. Repeat only for other independent issues (at most three total).",
+    "**Next:** <the exact safe next move, such as provide the listed evidence and run `/workflow-resume`>.",
+    "",
+    "Do not include a process narrative, raw logs, repeated policy constraints, successful checks, clean-state notes, or statements that merely say the child lacks authority. Mention a passed check only when it directly explains the remaining issue. Name the missing prerequisite and who can supply it. Keep only details needed to make the decision or complete the next action.",
+    ""
+  ];
+}
 
 // src/prompt/template.ts
 function currentStepHandoff(run) {
@@ -7131,6 +7152,7 @@ function buildStepTask(options) {
     ...contract.workspaceLines,
     "",
     "Put a self-contained compact handoff in `summary`; this is the only step context passed to the next fresh child.",
+    ...buildNonSuccessSummaryInstructions(contract.outcomes),
     ...isDelegated ? buildDelegatedCompletionInstructions() : [],
     "Do not call the completion tool alongside other tool calls."
   ].join(`

package/examples/starter-kit/steps/mr-comment/plan.md

@@ -25,8 +25,9 @@ to close evidence gaps.
 Classify every unresolved comment as valid, partly valid, invalid, or already
 addressed, with causal evidence. Define scoped code changes, exact
 repository-native checks, an optional commit, and the public reply for each
-comment. Include a non-force push only when verified local code must reach the
-host. Never include approval, merge, resolution, closure, deletion,
+comment. Include the matching non-force push whenever a committed code fix must
+reach the host, and one same-host reply action for every comment that requires
+a response. Never include approval, merge, resolution, closure, deletion,
 force-push, cross-host mutation, or unrelated work.
 
 This user-owned prompt defines the Plannotator artifact:

package/examples/starter-kit/steps/mr-comment/publish.md

@@ -20,7 +20,8 @@ an exact already-present non-force push SHA or an exact reply by the current
 user with the approved marker. Execute each remaining action once, in approved
 order, through its exact configured MCP tool/input or standalone `git`, `glab`,
 `gh`, or authenticated cURL command. Push before replies that describe the
-code fix.
+code fix. Automatically perform every required approved push and reply; never
+ask the user to perform one.
 
 Require a successful same-host, target-correlated response. Never change reply
 meaning, target another comment, expose credentials, force-push, approve,

package/examples/starter-kit/steps/mr-comment/verify.md

@@ -22,6 +22,13 @@ comment/anchor. Verify every remote action is same-host, non-force,
 idempotently observable, and limited to the approved push and replies. Do not
 execute remote actions here.
 
+Any regression, lint failure, formatting failure, or other actionable local
+finding is `failed`; the workflow sends that outcome directly back to
+implementation. Do not use `blocked` for a fixable local finding. When a code
+fix was committed, require the matching approved non-force push action before
+the replies. A valid unresolved review comment requires its approved public
+reply action.
+
 Call `structured_output` alone with:
 
 - `ready` when all criteria pass and approved remote actions remain;
@@ -32,4 +39,5 @@ Call `structured_output` alone with:
   that cannot proceed safely.
 
 For `ready` and `failed`, include complete fresh evidence and the unchanged
-Execution contract in `summary`.
+Execution contract in `summary`. A `ready` handoff automatically proceeds to
+the publisher; do not ask the user to push or post a reply.

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

@@ -25,6 +25,17 @@ Never alter the approved body, target another head or anchor, expose
 credentials, approve, merge, resolve, close, delete, push, cross hosts, or add
 an unlisted action.
 
+For a GitLab inline discussion, the API requires `position` as a nested object.
+Prefer an exact configured GitLab MCP mutation whose schema accepts that object.
+When using `glab api`, submit every discussion field as multipart form data with
+`--form`, including `position[base_sha]`, `position[start_sha]`,
+`position[head_sha]`, `position[position_type]`, both paths, and the applicable
+line. Do not use `--field` or `--raw-field` for any `position[...]` key: those
+flags serialize JSON scalar keys and do not construct GitLab's nested position,
+which can create an unanchored general discussion. Before calling
+`structured_output`, fetch the returned discussion and require its note to have
+the approved position/path/line as well as the approved body and marker.
+
 After a mutation-capable call is attempted, ambiguity is `blocked`; do not
 blindly replay it. Call `structured_output` alone with outcome `published` only
 after every approved effect succeeded now or was proven already present.

package/examples/starter-kit/steps/ticket/implement.md

@@ -26,7 +26,8 @@ errors and state before trying a safe equivalent. Never weaken validation,
 broaden scope, or mutate Jira.
 
 Run the approved checks, and stage or commit only when the approved plan calls
-for it. Do not push or publish in this step.
+for it. Do not push or publish in this step; independent verification publishes
+only the reviewed Publication contract after it has passed.
 
 Call `structured_output` alone with outcome `ready` when the result is ready for
 independent review. Summarize ticket identity, changed files, commands/results,

package/examples/starter-kit/steps/ticket/plan.md

@@ -56,11 +56,51 @@ This user-owned prompt defines the Plannotator artifact. Produce:
 5. `## Acceptance criteria`
 6. `## Validation commands`
 7. `## Risks and unresolved decisions`
+8. `## Publication contract`
 
 Include exact target files and observable results. Derive every repository
 command from current scripts or authoritative tool help. Do not assume a
 language, framework, package manager, flag order, or cwd syntax.
 
+The Publication contract is part of the reviewed artifact and authorizes the
+post-verification publication. State the exact bound branch, remote, target
+branch, merge-request title and description, and the GitLab project or hosted
+remote evidence. The title must use this Conventional Commit format exactly:
+`fix: [<JiraId>] <brief summary of the changes>`. The description must use this
+format exactly, replacing placeholders with current evidence and omitting the
+Experiment ID line when none exists:
+
+```md
+- Jira ID : {JiraId}
+- Experiment ID : {ExperimentId, if any}
+
+## Proposed changes
+- {changes}
+
+## Test added in this MR
+  - **Unit test**
+     - {test cases}
+  - **Functional test (If need)**
+     - {test cases}
+  - **Integration test (If need)**
+     - {test cases}
+
+ ## Tested scenarios with screenshots
+  | Scenario   | Production            | This branch  |
+  | ---        | ---                   | ---          |
+  | Scenario 1 | paste screenshot here | paste screenshot here |
+  | Scenario 2 | paste screenshot here | paste screenshot here |
+
+/assign me
+```
+
+It authorizes only a non-force push of the verified HEAD to that same branch
+and creation of one merge request for this ticket. Do not include credentials,
+arbitrary shell commands, history rewrites, branch deletion, Jira mutation,
+merging, or any other remote mutation. If the remote, target branch, or
+merge-request metadata cannot be established safely from current evidence, use
+`blocked` rather than leaving a publish decision for the verification step.
+
 Call `structured_output` alone with outcome `submit`, the complete Markdown in
 `artifact`, and a self-contained execution handoff in `summary`. Use `blocked`
 when ticket identity, access, or evidence is insufficient for a safe plan. Use

package/examples/starter-kit/steps/ticket/verify.md

@@ -1,5 +1,7 @@
-You independently verify the approved ticket work. Do not edit files, amend
-commits, change worktrees, or mutate Jira or any other external service.
+You independently verify the approved ticket work, then publish its reviewed
+Publication contract. Do not edit files, amend commits, change worktrees, or
+mutate Jira. The only allowed external mutations are the contract's non-force
+push and one GitLab merge-request creation.
 
 Ticket input:
 {{workflow.input}}
@@ -17,13 +19,57 @@ ticket acceptance criterion against current code and behavior. Run every exact
 repository-native validation command from the approved plan. A skipped, stale,
 unavailable, or failing required check is not passing.
 
+Any regression, lint failure, formatting failure, or other actionable local
+verification finding is `failed`; the workflow sends that outcome directly back
+to implementation. Do not use `blocked` for a fixable local finding.
+
+Only after all local criteria pass, parse the approved `## Publication contract`
+and validate its branch, remote, target branch, project, title, and description
+against the bound workspace and current remote evidence. The commit being
+published must be the current verified `HEAD`; record its full SHA. Query the
+remote branch and existing GitLab merge requests first. If the exact SHA is
+already published, do not push again. Otherwise push only that current HEAD to
+the contract branch with a non-force `git push`. Publish only committed code:
+never stage, commit, stash, discard, or otherwise consider pending staged or
+unstaged working-tree changes part of the publication. Those changes must not
+change the exact `HEAD` SHA being pushed. Never use `--force`, `--set-upstream`,
+refspec wildcards, another remote, or another branch. If the push is rejected,
+ambiguous, or proves that the remote branch contains different history, use
+`blocked` and do not attempt a workaround.
+
+Use MCP only for an enabled, exact server/tool selector. Every MCP call must
+name both `server` and `tool`; never use MCP discovery or proxy modes such as
+`action`, `connect`, `describe`, `search`, `regex`, or a server-only call. Use
+the configured Atlassian tool for Jira evidence. This ticket workflow does not
+authorize GitLab MCP tools, so inspect and create GitLab merge requests with
+the authenticated host CLI instead of attempting an MCP call.
+
+Before the first remote query or push, run the contract's `git ls-remote`
+branch check as one standalone Bash call, never as part of a command chain.
+This is the SSH-authentication preflight and may display a 1Password approval.
+If SSH authentication is unavailable (for example, the agent socket cannot be
+reached, the agent refuses the signature, or approval is cancelled), do not try
+alternate credentials or a workaround. Return `blocked` with the redacted
+diagnostic and the precise recovery: unlock/approve the configured 1Password
+SSH key for the remote host in an interactive session, then resume this step.
+
+After the branch is confirmed remote, reuse an existing open merge request only
+when its source branch, target branch, and ticket correlation match the contract.
+Otherwise create exactly one GitLab merge request using the contract title and
+description. Refresh it and confirm its URL, project, source branch, target
+branch, and head SHA. Never merge, close, approve, alter an unrelated MR, or
+retry an ambiguous mutation. A missing or materially incomplete Publication
+contract is `blocked`, not permission to infer a publish action.
+
 Call `structured_output` alone with:
 
-- `passed` only when all criteria and checks pass;
+- `passed` only when all criteria and checks pass and the reviewed commit is
+  pushed and represented by the matching GitLab merge request;
 - `failed` for an actionable implementation defect, with exact location,
   evidence, and the smallest corrective handoff;
 - `blocked` when ticket or repository evidence is stale or verification cannot
   proceed safely.
 
 Include the refreshed ticket identity, commands/results, per-criterion evidence,
-diff/commit identity, and final status in the summary. Do not fix findings.
+diff/commit identity, remote branch result, merge-request URL/identity, and
+final status in the summary. Do not fix findings.

package/examples/starter-kit/steps/work/verify.md

@@ -18,6 +18,10 @@ derive any necessary invocation-only correction from current scripts or tool
 help without weakening the check. A skipped, stale, unavailable, or failing
 required check is not passing.
 
+Any regression, lint failure, formatting failure, or other actionable local
+verification finding is `failed`; the workflow sends that outcome directly back
+to implementation. Do not use `blocked` for a fixable local finding.
+
 Call `structured_output` alone with:
 
 - `passed` only when every criterion and required check passes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wichayutdew/pi-workflows",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "description": "A declarative, pauseable workflow harness for Pi",
   "license": "MIT",
   "repository": {

package/schemas/workflow.schema.json

@@ -124,6 +124,19 @@
         }
       ]
     },
+    "workspaceRoot": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4096,
+      "pattern": "^\\S(?:.*\\S)?$",
+      "allOf": [
+        {
+          "not": {
+            "pattern": "\\u0000"
+          }
+        }
+      ]
+    },
     "resourceName": {
       "type": "string",
       "pattern": "^[A-Za-z0-9_@./:+-]+$"
@@ -575,7 +588,7 @@
           "uniqueItems": true,
           "default": ["."],
           "items": {
-            "$ref": "#/$defs/relativePath"
+            "$ref": "#/$defs/workspaceRoot"
           }
         }
       }

package/src/config/types.ts

@@ -95,7 +95,7 @@ export type WorkflowGate = PromptGate | PlannotatorGate;
 export type StepWorkspaceBinding = {
   /** Outcomes whose result establishes the workspace for later steps. */
   readonly bindOn: ReadonlyArray<string>;
-  /** Paths relative to the run-start directory that may contain the workspace. */
+  /** Relative, absolute, or ~/ home-relative paths that may contain the workspace. */
   readonly allowedRoots: ReadonlyArray<string>;
 };
 

package/src/config/validation/step.ts

@@ -159,12 +159,12 @@ function parseWorkspaceRoots(
 ): Array<string> {
   if (value === undefined) return ['.'];
   if (!Array.isArray(value)) {
-    errors.push(`${path}: expected an array of relative paths`);
+    errors.push(`${path}: expected an array of workspace paths`);
     return [];
   }
   if (value.length > MAX_WORKSPACE_ALLOWED_ROOTS) {
     errors.push(
-      `${path}: at most ${MAX_WORKSPACE_ALLOWED_ROOTS} relative paths are allowed`,
+      `${path}: at most ${MAX_WORKSPACE_ALLOWED_ROOTS} workspace paths are allowed`,
     );
   }
 
@@ -173,7 +173,7 @@ function parseWorkspaceRoots(
     .reduce<Array<string>>((result, item, index) => {
       const itemPath = `${path}[${index}]`;
       if (typeof item !== 'string' || !item || item.trim() !== item) {
-        errors.push(`${itemPath}: expected a non-empty relative path`);
+        errors.push(`${itemPath}: expected a non-empty workspace path`);
         return result;
       }
       const root = item;
@@ -185,10 +185,11 @@ function parseWorkspaceRoots(
       }
       if (
         root.includes('\0') ||
-        isAbsolute(root) ||
-        win32.parse(root).root !== ''
+        (win32.parse(root).root !== '' && !isAbsolute(root))
       ) {
-        errors.push(`${itemPath}: expected a relative path`);
+        errors.push(
+          `${itemPath}: expected a relative, absolute, or home-relative path`,
+        );
         return result;
       }
       if (result.includes(root)) {
@@ -198,7 +199,7 @@ function parseWorkspaceRoots(
       return [...result, root];
     }, []);
   if (roots.length === 0) {
-    errors.push(`${path}: at least one relative path is required`);
+    errors.push(`${path}: at least one workspace path is required`);
   }
   return roots;
 }

package/src/harness/workspace-directory.ts

@@ -1,4 +1,5 @@
 import { realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { isAbsolute, relative, resolve, sep, win32 } from 'node:path';
 
 export type ResolveWorkspaceDirectoryOptions = {
@@ -17,6 +18,15 @@ const isWithin = (root: string, candidate: string): boolean => {
   );
 };
 
+const resolveAllowedRoot = (startCwd: string, allowedRoot: string): string =>
+  allowedRoot === '~'
+    ? homedir()
+    : allowedRoot.startsWith('~/')
+      ? resolve(homedir(), allowedRoot.slice(2))
+      : isAbsolute(allowedRoot)
+        ? allowedRoot
+        : resolve(startCwd, allowedRoot);
+
 /**
  * Canonicalizes and validates one YAML-authorized execution directory.
  *
@@ -46,15 +56,14 @@ export function resolveWorkspaceDirectory({
   const canonicalRoots = allowedRoots.map((allowedRoot) => {
     if (
       !allowedRoot ||
-      isAbsolute(allowedRoot) ||
-      win32.parse(allowedRoot).root !== '' ||
+      (win32.parse(allowedRoot).root !== '' && !isAbsolute(allowedRoot)) ||
       allowedRoot.includes('\0')
     ) {
       throw new Error(
-        'workspace allowed roots must be non-empty relative paths',
+        'workspace allowed roots must be non-empty relative, absolute, or home-relative paths',
       );
     }
-    return realpathSync(resolve(canonicalStart, allowedRoot));
+    return realpathSync(resolveAllowedRoot(canonicalStart, allowedRoot));
   });
   const canonicalCwd = realpathSync(candidateCwd);
   if (!statSync(canonicalCwd).isDirectory()) {

package/src/integrations/subagents/child-policy-sections.ts

@@ -149,8 +149,7 @@ const parseWorkspace = (
         root !== root.trim() ||
         root.length > MAX_WORKSPACE_PATH_CHARS ||
         root.includes('\0') ||
-        isAbsolute(root) ||
-        win32.parse(root).root !== '',
+        (win32.parse(root).root !== '' && !isAbsolute(root)),
     )
   ) {
     throw new Error('child policy workspace allowed roots are invalid');

package/src/prompt/step-sections.ts

@@ -85,3 +85,33 @@ export function buildDelegatedCompletionInstructions(): ReadonlyArray<string> {
     'Stay within the configured permissions and do not broaden mutation targets or external side effects.',
   ];
 }
+
+/**
+ * Builds the shared operator-facing format for non-successful step results.
+ *
+ * The summary is posted verbatim to chat and is the only context available to
+ * a fresh child, so it must remain actionable without becoming a transcript.
+ */
+export function buildNonSuccessSummaryInstructions(
+  outcomes: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+  const nonSuccessOutcomes = outcomes.filter((outcome) =>
+    ['blocked', 'failed', 'retry'].includes(outcome),
+  );
+  if (nonSuccessOutcomes.length === 0) return [];
+
+  return [
+    '## Human-readable non-success results',
+    '',
+    `For ${nonSuccessOutcomes.map((outcome) => `\`${outcome}\``).join(', ')}, write a decision-first summary. It is shown verbatim to the operator and handed to a fresh child. Use this format:`,
+    '',
+    '# <Failed | Blocked | Retry>: <one-sentence plain-language decision>',
+    '1. **<short issue>** — <only the decisive evidence, including an exact command/error, path, or identifier when it enables action>.',
+    '   **Action:** <the specific owner or role> must <the concrete evidence, decision, or change needed>.',
+    '2. Repeat only for other independent issues (at most three total).',
+    '**Next:** <the exact safe next move, such as provide the listed evidence and run `/workflow-resume`>.',
+    '',
+    'Do not include a process narrative, raw logs, repeated policy constraints, successful checks, clean-state notes, or statements that merely say the child lacks authority. Mention a passed check only when it directly explains the remaining issue. Name the missing prerequisite and who can supply it. Keep only details needed to make the decision or complete the next action.',
+    '',
+  ];
+}

package/src/prompt/step-task.ts

@@ -4,6 +4,7 @@ import { createStepContract } from './step-contract.ts';
 import {
   buildDelegatedCompletionInstructions,
   buildDelegatedHandoffSection,
+  buildNonSuccessSummaryInstructions,
   buildRestartWorkspaceSection,
   buildResourceSection,
 } from './step-sections.ts';
@@ -149,6 +150,7 @@ export function buildStepTask(options: BuildStepTaskOptions): string {
     ...contract.workspaceLines,
     '',
     'Put a self-contained compact handoff in `summary`; this is the only step context passed to the next fresh child.',
+    ...buildNonSuccessSummaryInstructions(contract.outcomes),
     ...(isDelegated ? buildDelegatedCompletionInstructions() : []),
     'Do not call the completion tool alongside other tool calls.',
   ].join('\n');