@wichayutdew/pi-workflows 2.0.0 → 2.1.0

package/README.md

@@ -71,6 +71,14 @@ user-owned starting point for:
 | `/mr-review`  | Fetch a hosted review, produce a child review, approve it, publish it, and verify the remote effect.       |
 | `/mr-comment` | Fetch review comments, plan and approve fixes, edit only the current branch/worktree, verify, push, reply. |
 
+The starter YAML explicitly selects Pi Subagents' standard role profiles:
+`scout` for evidence gathering, `planner` for implementation plans, `worker`
+for mutations and publication, and `reviewer` for independent review and
+verification. Change those `subagent.agent` values when your own Pi Subagents
+configuration uses different profiles. The generic `pi-workflows.step` profile
+remains available for user-authored `subagent: {}` steps, but the starter kit
+does not rely on it.
+
 Install the integrations required by these four examples:
 
 ```bash
@@ -137,10 +145,14 @@ workspace:
 `/work` and `/ticket` bind the exact worktree returned by their user-authored
 preparation prompt. `/mr-comment` intentionally has no workspace-binding step:
 every child stays on the branch and worktree from which the run started.
-Approval rejection pauses either review workflow; it never launches an
-automatic replacement plan. Remote publication prompts first check whether an
-approved effect already exists because the harness cannot guarantee
-exactly-once external side effects.
+Requested changes return only to the gated plan or review step with the user's
+feedback; they never restart workspace preparation or the whole workflow. The
+starter `/work` and `/ticket` planners use a separate `workspace-refresh`
+outcome only for source-ancestry drift. It revisits preparation in the same
+canonical worktree; the prompt may safely rebase its clean run-owned branch but
+can never bind a replacement directory.
+Remote publication prompts first check whether an approved effect already
+exists because the harness cannot guarantee exactly-once external side effects.
 
 ## Add a workflow
 
@@ -210,16 +222,16 @@ loaded extensions or prompt resources are diagnosed before aliases register.
 
 Top-level fields:
 
-| Field             | Required | Default | Description                                                                                        |
-| ----------------- | -------- | ------- | -------------------------------------------------------------------------------------------------- |
-| `version`         | Yes      | —       | Configuration contract version. Currently `1`.                                                     |
-| `id`              | Yes      | —       | Stable workflow identifier.                                                                        |
-| `command`         | Yes      | —       | Slash command without `/`.                                                                         |
-| `description`     | Yes      | —       | Command description.                                                                               |
-| `start`           | Yes      | —       | First step identifier.                                                                             |
-| `steps`           | Yes      | —       | Step map. Order is controlled by transitions, not file order.                                      |
-| `maxStepVisits`   | No       | `5`     | Loop guard for each step.                                                                          |
-| `summaryMaxChars` | No       | `4000`  | Maximum step `summary` length. Reviewed gate artifacts use their separate 200,000-character limit. |
+| Field             | Required | Default | Description                                                                               |
+| ----------------- | -------- | ------- | ----------------------------------------------------------------------------------------- |
+| `version`         | Yes      | —       | Configuration contract version. Currently `1`.                                            |
+| `id`              | Yes      | —       | Stable workflow identifier.                                                               |
+| `command`         | Yes      | —       | Slash command without `/`.                                                                |
+| `description`     | Yes      | —       | Command description.                                                                      |
+| `start`           | Yes      | —       | First step identifier.                                                                    |
+| `steps`           | Yes      | —       | Step map. Order is controlled by transitions, not file order.                             |
+| `maxStepVisits`   | No       | `5`     | Loop guard for each step.                                                                 |
+| `summaryMaxChars` | No       | `4000`  | Maximum step `summary` length. Gate artifacts use their separate 200,000-character limit. |
 
 Each step supports:
 
@@ -245,6 +257,7 @@ Supported prompt variables:
 {{last.summary}}
 {{reviewed.artifact}}
 {{reviewed.feedback}}
+{{gate.artifact}}
 {{gate.feedback}}
 {{resume.input}}
 ```
@@ -252,10 +265,11 @@ Supported prompt variables:
 Unknown variables fail configuration loading.
 
 `{{last.summary}}` normally contains the previous completed step's handoff.
-After a step-requested `$pause`, it contains both the preserved incoming
-previous-step handoff and the latest paused-attempt summary. Gate artifacts and
-summaries stay separate: prompts opt into the opaque approved artifact through
-`{{reviewed.artifact}}`.
+During a step-requested `$pause` or same-step human gate revision, it contains
+both the preserved incoming handoff and latest current-step summary. Gate
+artifacts and summaries stay separate: prompts opt into an opaque approved
+artifact through `{{reviewed.artifact}}` or the latest rejected artifact
+through `{{gate.artifact}}`.
 `{{resume.input}}` contains guidance supplied to the current attempt through
 `/workflow-resume [guidance]`. If a prompt omits that variable, the harness
 adds the guidance in a clearly delimited standard section, so every workflow
@@ -314,17 +328,19 @@ workspace:
 On a binding outcome, the result must include
 `workspace: { cwd: "/absolute/directory" }`. The harness resolves its real path,
 requires an existing directory under one configured root relative to the
-run-start directory, persists it once, and passes that exact directory to every
-reachable downstream child, revisit, recovery attempt, and resume. Other
-outcomes must omit `workspace`; later results cannot replace the binding. All
+run-start directory, persists that canonical identity, and passes it to every
+reachable downstream child, revisit, recovery attempt, and resume. If the sole
+binding step is revisited, it may re-affirm the same canonical directory; a
+different directory is rejected. Other outcomes must omit `workspace`. All
 reachable nonterminal steps after a binding must be delegated because the main
 Pi process cannot change its working directory.
 
 The workflow prompt owns how the directory is prepared and what it represents.
 The harness does not know Git, worktrees, languages, frameworks, or command
-syntax, and it never derives a directory from summaries or gate artifacts. A
-legacy checkpoint without a captured directory fails closed before delegation;
-abort it and start a new run.
+syntax, and it never derives a directory from summaries or gate artifacts. The
+starter kit's guarded rebase policy is therefore prompt-owned domain behavior,
+not extension behavior. A legacy checkpoint without a captured directory fails
+closed before delegation; abort it and start a new run.
 
 Use a profile name directly when only the child profile changes:
 
@@ -524,7 +540,7 @@ gate:
   rejectedOutcome: changes-requested
 transitions:
   approved: implement
-  changes-requested: $pause
+  changes-requested: plan
   blocked: $pause
 ```
 
@@ -532,9 +548,13 @@ When the step completes with outcome `submit`, it must include the full content
 in `artifact`. Pi shows Approve, Request changes, and Pause workflow. Requested
 changes are returned through `{{gate.feedback}}`; approval persists the
 artifact as `{{reviewed.artifact}}` while the step's `summary` remains the
-compact handoff. A requested change pauses at the same step with feedback, so
-revision starts only after explicit `/workflow-resume`. Dismissing the panel
-keeps the pending artifact, so `/workflow-resume` reopens the same review.
+compact handoff. Here, `changes-requested: plan` immediately runs a fresh
+attempt of that exact gated step with the rejected draft in
+`{{gate.artifact}}`, the original incoming step handoff, and the new feedback,
+then opens another review. Use
+`changes-requested: $pause` instead when revision should require an explicit
+`/workflow-resume`. Dismissing the panel keeps the pending artifact, so
+`/workflow-resume` reopens the same review.
 
 Dialog-capable UI is available in Pi TUI and RPC modes. In print or JSON mode,
 the gate pauses safely until resumed in TUI or RPC.
@@ -575,7 +595,7 @@ gate:
   timeoutMs: 30000
 transitions:
   approved: implement
-  changes-requested: $pause
+  changes-requested: plan
   blocked: $pause
 ```
 
@@ -589,6 +609,17 @@ review identifier and accepts only the matching decision. On approval, the
 artifact is preserved as an opaque template value; the separate `summary`
 remains the next step's compact handoff.
 
+The `approved` boolean from Plannotator is authoritative; feedback text and
+annotation labels stay opaque. A rejection follows only the YAML transition
+shown above. A same-step rejection is an explicitly human-controlled revision
+loop, so that human-mediated transition bypasses the visit-limit check and may
+continue until approval. The visit is still recorded, and later automatic
+entries remain guarded. A same-step agent retry during revision preserves the
+incoming handoff, rejected artifact, and feedback, but it does not bypass the
+visit-limit check. Gate feedback is capped at 50,000 characters; history and
+user notifications use a compact rejection summary while `{{gate.feedback}}`
+receives the bounded full value.
+
 The artifact is never substituted for a missing summary. If an older pending
 gate has no separately stored summary, its transition uses an empty compact
 handoff.
@@ -731,8 +762,10 @@ a failed or aborted run, and `◆` a paused step or pending review.
 Use `↑`/`↓` or `j`/`k` to select a step, then `Enter`, `→`, or `l` to inspect
 the bounded task supplied to each attempt, its result and gate decision, and a
 chronological execution log when available. In the detail view,
-`↑`/`↓` or `j`/`k` scrolls; `←`, `h`, or `Esc` returns to the board; `q` or the
-configured shortcut closes it. PgUp/PgDn and Home/End retain page navigation.
+`↑`/`↓` or `j`/`k` scrolls one line, while `Ctrl+D` and `Ctrl+U` scroll down and
+up by half a page. `gg` jumps to the top and `G` jumps to the bottom. `←`, `h`,
+or `Esc` returns to the board; `q` or the configured shortcut closes it.
+PgUp/PgDn and Home/End retain page navigation.
 Trace references and bounded task/result evidence live in the checkpoint, so
 completed, paused, resumed, and restored runs remain inspectable. Child logs
 are path-confined, size-bounded, control-sanitized, and redact common
@@ -763,7 +796,10 @@ Unreachable steps and cycles are reported as warnings; a cycle with an exit may
 run, but `maxStepVisits` pauses the uninterrupted run before a step can execute
 more than its configured limit. An explicit resume can continue from that
 checkpoint, so the guard bounds automatic graph advancement rather than
-guaranteeing completion or wall-clock duration.
+guaranteeing completion or wall-clock duration. An explicit human gate
+rejection back to that same gated step bypasses the check for that transition;
+the visit remains recorded and every iteration must stop for another human
+decision.
 
 Configured aliases also accept multiline input. For example, if `work` is a
 loaded workflow command, Pi Workflows normalizes:

package/dist/index.js

@@ -139,6 +139,7 @@ var PROMPT_VARIABLES = new Set([
   "last.summary",
   "reviewed.artifact",
   "reviewed.feedback",
+  "gate.artifact",
   "gate.feedback",
   "resume.input"
 ]);
@@ -3634,6 +3635,7 @@ function registerMainStepLifecycle({
 
 // src/engine/state-types.ts
 var RUN_STATE_VERSION = 1;
+var MAX_GATE_FEEDBACK_CHARS = 50000;
 var MAX_RESUME_INPUT_CHARS = 16000;
 var MAX_STEP_TRACE_TASK_CHARS = 64000;
 var MAX_STEP_TRACE_ATTEMPTS = 16;
@@ -4493,6 +4495,7 @@ var createRun = (workflow, input, baselineTools, runId, now, cwd) => {
     ...cwd ? { startCwd: cwd, cwd } : {},
     stepHandoff: "",
     lastSummary: "",
+    gateArtifact: "",
     gateFeedback: ""
   };
 };
@@ -4815,7 +4818,7 @@ function recordCurrentGateDecision(run, decision, now) {
 // src/engine/run-validation.ts
 var isRecord8 = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 var isAbsoluteCwd = (value) => typeof value === "string" && value.length > 0 && isAbsolute8(value) && !value.includes("\x00");
-var isGateApproval = (value) => isRecord8(value) && typeof value.requestId === "string" && value.requestId.length > 0 && typeof value.artifact === "string" && value.artifact.trim().length > 0 && typeof value.feedback === "string" && typeof value.stepStructuralDigest === "string" && value.stepStructuralDigest.length > 0;
+var isGateApproval = (value) => isRecord8(value) && typeof value.requestId === "string" && value.requestId.length > 0 && typeof value.artifact === "string" && value.artifact.trim().length > 0 && typeof value.feedback === "string" && value.feedback.length <= MAX_GATE_FEEDBACK_CHARS && typeof value.stepStructuralDigest === "string" && value.stepStructuralDigest.length > 0;
 var isStepAttemptResult = (value) => isRecord8(value) && typeof value.outcome === "string" && typeof value.summary === "string" && value.summary.length <= MAX_STEP_TRACE_SUMMARY_CHARS && (value.summaryTruncated === undefined || value.summaryTruncated === true) && (value.artifact === undefined || typeof value.artifact === "string") && (typeof value.artifact !== "string" || value.artifact.length <= MAX_STEP_TRACE_ARTIFACT_CHARS) && (value.artifactTruncated === undefined || value.artifactTruncated === true) && !(value.artifactTruncated === true && value.artifact === undefined) && (value.workspaceCwd === undefined || isAbsoluteCwd(value.workspaceCwd));
 var isStepGateDecision = (value) => isRecord8(value) && (value.provider === "prompt" || value.provider === "plannotator") && typeof value.requestId === "string" && value.requestId.length > 0 && typeof value.approved === "boolean" && typeof value.feedback === "string" && value.feedback.length <= MAX_STEP_TRACE_SUMMARY_CHARS && (value.feedbackTruncated === undefined || value.feedbackTruncated === true) && typeof value.resolvedAt === "number" && (value.reviewId === undefined || typeof value.reviewId === "string");
 var isSafeTraceIdentityField = (value) => typeof value === "string" && value.length > 0 && !value.includes("\x00") && !value.includes("/") && !value.includes("\\") && value !== "." && value !== "..";
@@ -4862,7 +4865,7 @@ var isStepExecutionAttempts = (value) => Array.isArray(value) && value.length <=
   return value.slice(0, index).every((earlier) => earlier.ordinal === undefined || earlier.ordinal < ordinal);
 });
 var isStepHistoryEntry = (value) => isRecord8(value) && typeof value.stepId === "string" && typeof value.stepDigest === "string" && typeof value.outcome === "string" && typeof value.summary === "string" && (value.workspaceCwd === undefined || isAbsoluteCwd(value.workspaceCwd)) && (value.artifact === undefined || typeof value.artifact === "string") && (value.approval === undefined || isGateApproval(value.approval) && value.artifact === value.approval.artifact) && (value.attempts === undefined || isStepExecutionAttempts(value.attempts)) && (value.omittedAttempts === undefined || Number.isSafeInteger(value.omittedAttempts) && value.omittedAttempts > 0) && typeof value.completedAt === "number";
-var isGateResolution = (value) => isRecord8(value) && typeof value.approved === "boolean" && typeof value.feedback === "string" && typeof value.resolvedAt === "number";
+var isGateResolution = (value) => isRecord8(value) && typeof value.approved === "boolean" && typeof value.feedback === "string" && value.feedback.length <= MAX_GATE_FEEDBACK_CHARS && typeof value.resolvedAt === "number";
 var isPendingGate = (value) => isRecord8(value) && (value.provider === "prompt" || value.provider === "plannotator") && typeof value.requestId === "string" && value.requestId.length > 0 && typeof value.stepId === "string" && typeof value.artifact === "string" && (value.summary === undefined || typeof value.summary === "string") && typeof value.submittedOutcome === "string" && typeof value.requestedAt === "number" && (value.reviewId === undefined || typeof value.reviewId === "string") && (value.resolution === undefined || isGateResolution(value.resolution));
 var isVisitCounts = (value) => isRecord8(value) && Object.values(value).every((count) => typeof count === "number" && Number.isInteger(count) && count >= 0);
 var isOptionalString = (value) => value === undefined || typeof value === "string";
@@ -4890,10 +4893,10 @@ var hasValidWorkspaceState = (run, history) => {
 var isWorkflowRun = (value) => {
   if (!isRecord8(value))
     return false;
-  const hasValidRequiredFields = value.stateVersion === RUN_STATE_VERSION && typeof value.runId === "string" && typeof value.workflowId === "string" && typeof value.workflowDigest === "string" && typeof value.input === "string" && isWorkflowRunStatus(value.status) && typeof value.currentStepId === "string" && typeof value.currentStepDigest === "string" && Array.isArray(value.baselineTools) && value.baselineTools.every((tool) => typeof tool === "string") && Array.isArray(value.history) && value.history.every(isStepHistoryEntry) && (value.currentStepAttempts === undefined || isStepExecutionAttempts(value.currentStepAttempts)) && (value.currentStepOmittedAttempts === undefined || Number.isSafeInteger(value.currentStepOmittedAttempts) && value.currentStepOmittedAttempts > 0) && isVisitCounts(value.visits) && typeof value.startedAt === "number" && typeof value.updatedAt === "number" && typeof value.lastSummary === "string" && typeof value.gateFeedback === "string";
+  const hasValidRequiredFields = value.stateVersion === RUN_STATE_VERSION && typeof value.runId === "string" && typeof value.workflowId === "string" && typeof value.workflowDigest === "string" && typeof value.input === "string" && isWorkflowRunStatus(value.status) && typeof value.currentStepId === "string" && typeof value.currentStepDigest === "string" && Array.isArray(value.baselineTools) && value.baselineTools.every((tool) => typeof tool === "string") && Array.isArray(value.history) && value.history.every(isStepHistoryEntry) && (value.currentStepAttempts === undefined || isStepExecutionAttempts(value.currentStepAttempts)) && (value.currentStepOmittedAttempts === undefined || Number.isSafeInteger(value.currentStepOmittedAttempts) && value.currentStepOmittedAttempts > 0) && isVisitCounts(value.visits) && typeof value.startedAt === "number" && typeof value.updatedAt === "number" && typeof value.lastSummary === "string" && typeof value.gateFeedback === "string" && value.gateFeedback.length <= MAX_GATE_FEEDBACK_CHARS;
   if (!hasValidRequiredFields)
     return false;
-  const hasValidOptionalFields = isOptionalString(value.reviewedArtifact) && isOptionalString(value.reviewedFeedback) && isOptionalString(value.stepHandoff) && isOptionalResumeInput(value.resumeInput) && isOptionalString(value.pauseReason) && isOptionalString(value.failedStepId) && (value.pausedFrom === undefined || value.pausedFrom === "running" || value.pausedFrom === "awaiting-gate");
+  const hasValidOptionalFields = isOptionalString(value.reviewedArtifact) && isOptionalString(value.reviewedFeedback) && (typeof value.reviewedFeedback !== "string" || value.reviewedFeedback.length <= MAX_GATE_FEEDBACK_CHARS) && isOptionalString(value.stepHandoff) && isOptionalString(value.gateArtifact) && isOptionalResumeInput(value.resumeInput) && isOptionalString(value.pauseReason) && isOptionalString(value.failedStepId) && (value.pausedFrom === undefined || value.pausedFrom === "running" || value.pausedFrom === "awaiting-gate");
   if (!hasValidOptionalFields)
     return false;
   const pendingGate = value.pendingGate;
@@ -5081,6 +5084,7 @@ class WorkflowStatusView {
   statusShortcut;
   timer;
   state = initialViewportState();
+  pendingDetailTopKey = false;
   statusShortcutLabel;
   dependencies;
   transcriptCache = new Map;
@@ -5106,7 +5110,9 @@ class WorkflowStatusView {
   }
   invalidate() {}
   handleInput(data) {
-    if (data === "q" || data === "Q" || matchesKey(data, "ctrl+c") || matchesKey(data, "ctrl+d") || matchesKey(data, this.statusShortcut)) {
+    const isDetailHalfPageDown = this.state.mode === "detail" && matchesKey(data, Key.ctrl("d"));
+    const isDetailHalfPageUp = this.state.mode === "detail" && matchesKey(data, Key.ctrl("u"));
+    if (data === "q" || data === "Q" || matchesKey(data, "ctrl+c") || this.state.mode !== "detail" && matchesKey(data, "ctrl+d") || matchesKey(data, this.statusShortcut)) {
       this.close();
       return;
     }
@@ -5119,13 +5125,31 @@ class WorkflowStatusView {
       return;
     }
     const pageSize = Math.max(1, this.state.viewportRows - 2);
+    const contentHeight = Math.max(1, this.state.viewportRows - 1);
+    const halfPageSize = Math.max(1, Math.floor(contentHeight / 2));
     if (this.state.mode === "detail") {
-      if (matchesKey(data, Key.left) || data === "h") {
+      if (data === "gg" || data === "g" && this.pendingDetailTopKey) {
+        this.pendingDetailTopKey = false;
+        this.setScrollOffset(0);
+        return;
+      }
+      if (data === "g") {
+        this.pendingDetailTopKey = true;
+        return;
+      }
+      this.pendingDetailTopKey = false;
+      if (data === "G") {
+        this.setScrollOffset(Number.MAX_SAFE_INTEGER);
+      } else if (matchesKey(data, Key.left) || data === "h") {
         this.showBoard();
       } else if (matchesKey(data, Key.down) || data === "j") {
         this.setScrollOffset(this.state.scrollOffset + 1);
       } else if (matchesKey(data, Key.up) || data === "k") {
         this.setScrollOffset(this.state.scrollOffset - 1);
+      } else if (isDetailHalfPageDown) {
+        this.setScrollOffset(this.state.scrollOffset + halfPageSize);
+      } else if (isDetailHalfPageUp) {
+        this.setScrollOffset(this.state.scrollOffset - halfPageSize);
       } else if (matchesKey(data, Key.pageDown)) {
         this.setScrollOffset(this.state.scrollOffset + pageSize);
       } else if (matchesKey(data, Key.pageUp)) {
@@ -5137,6 +5161,7 @@ class WorkflowStatusView {
       }
       return;
     }
+    this.pendingDetailTopKey = false;
     if (matchesKey(data, Key.down) || data === "j") {
       this.moveSelection(1);
     } else if (matchesKey(data, Key.up) || data === "k") {
@@ -5168,7 +5193,7 @@ class WorkflowStatusView {
       this.ensureSelectedTranscripts(snapshot);
     }
     const rendered = lines.map((line) => padAnsi(truncateToWidth4(line, contentWidth, "…"), viewportWidth));
-    const page = paginateBoard(this.state, rendered, viewportWidth, this.tui.terminal?.rows, this.statusShortcutLabel, this.theme, this.state.mode === "detail" ? "↑/↓ or j/k scroll · PgUp/PgDn · ←/h/Esc back" : "↑/↓ or j/k select · Enter/→/l inspect · PgUp/PgDn");
+    const page = paginateBoard(this.state, rendered, viewportWidth, this.tui.terminal?.rows, this.statusShortcutLabel, this.theme, this.state.mode === "detail" ? "↑↓/jk · Ctrl+D/U half-page · gg/G top/bottom · PgUp/PgDn · ←/h/Esc" : "↑/↓ or j/k select · Enter/→/l inspect · PgUp/PgDn");
     this.state = page.state;
     return page.lines;
   }
@@ -5210,6 +5235,7 @@ class WorkflowStatusView {
     this.normalizeSelection(snapshot);
     if (!selectedStepDetail(snapshot, this.state.selectedIndex))
       return;
+    this.pendingDetailTopKey = false;
     this.state = { ...this.state, mode: "detail", scrollOffset: 0 };
     this.ensureSelectedTranscripts(snapshot);
     this.tui.requestRender(true);
@@ -5217,6 +5243,7 @@ class WorkflowStatusView {
   showBoard() {
     if (this.state.mode === "board")
       return;
+    this.pendingDetailTopKey = false;
     this.state = { ...this.state, mode: "board", scrollOffset: 0 };
     this.tui.requestRender(true);
   }
@@ -5635,7 +5662,7 @@ function formatWorkflowDoctor(reports) {
   for (const report of reports) {
     const errors = report.issues.filter((issue) => issue.level === "error");
     const warnings = report.issues.filter((issue) => issue.level === "warning");
-    lines.push(`## ${report.workflowId}`, "", `Result: ${errors.length > 0 ? "ERROR" : warnings.length > 0 ? "WARNING" : "PASS"}`, "", `Runtime loop guard: each step executes at most ${report.maxStepVisits} time${report.maxStepVisits === 1 ? "" : "s"} before the next attempted entry pauses an uninterrupted run. This bounds graph cycling; it does not guarantee $done or bound time spent inside a step or gate.`, "");
+    lines.push(`## ${report.workflowId}`, "", `Result: ${errors.length > 0 ? "ERROR" : warnings.length > 0 ? "WARNING" : "PASS"}`, "", `Runtime loop guard: automatic graph advancement enters each step at most ${report.maxStepVisits} time${report.maxStepVisits === 1 ? "" : "s"} before the next attempted entry pauses the run. An explicit human rejection back to the same gated step bypasses that check for its transition because every revision awaits another decision; the visit is still recorded. This bounds unattended cycling; it does not guarantee $done or bound time spent inside a step or gate.`, "");
     if (report.issues.length === 0) {
       lines.push("- No liveness issues found.", "");
       continue;
@@ -5789,7 +5816,7 @@ var completedStep = (run, outcome, summary, now, effects) => ({
   ...run.currentStepOmittedAttempts ? { omittedAttempts: run.currentStepOmittedAttempts } : {},
   completedAt: now
 });
-var advanceRun = (workflow, run, outcome, summary, now, effects = {}) => {
+var advanceRun = (workflow, run, outcome, summary, now, effects = {}, options = {}) => {
   if (run.status !== "running") {
     throw new Error(`workflow is ${run.status}; only a running workflow can advance`);
   }
@@ -5828,6 +5855,7 @@ var advanceRun = (workflow, run, outcome, summary, now, effects = {}) => {
       ...cwd ? { cwd } : {},
       stepHandoff: summary,
       lastSummary: summary,
+      gateArtifact: "",
       gateFeedback: "",
       pausedFrom: undefined,
       pendingGate: undefined,
@@ -5837,8 +5865,9 @@ var advanceRun = (workflow, run, outcome, summary, now, effects = {}) => {
   if (!workflow.definition.steps[target]) {
     throw new Error(`transition target "${target}" does not exist`);
   }
+  const preservesGateRevisionContext = target === run.currentStepId && (options.sameStepHumanGateRevision || Boolean(run.gateArtifact));
   const nextVisitCount = (run.visits[target] ?? 0) + 1;
-  const isOverVisitLimit = nextVisitCount > workflow.definition.maxStepVisits;
+  const isOverVisitLimit = !options.sameStepHumanGateRevision && nextVisitCount > workflow.definition.maxStepVisits;
   const visitLimitChanges = isOverVisitLimit ? {
     status: "paused",
     pausedFrom: "running",
@@ -5859,14 +5888,26 @@ var advanceRun = (workflow, run, outcome, summary, now, effects = {}) => {
     currentStepAttempts: undefined,
     currentStepOmittedAttempts: undefined,
     ...cwd ? { cwd } : {},
-    stepHandoff: summary,
+    stepHandoff: preservesGateRevisionContext ? run.stepHandoff : summary,
     lastSummary: summary,
-    gateFeedback: "",
+    gateArtifact: preservesGateRevisionContext ? run.gateArtifact : "",
+    gateFeedback: preservesGateRevisionContext ? run.gateFeedback : "",
     resumeInput: undefined
   }, now);
 };
 
 // src/engine/gate-transitions.ts
+var GATE_FEEDBACK_TRUNCATION_SUFFIX = `
+… [gate feedback truncated by Pi Workflows]`;
+var MAX_GATE_REJECTION_SUMMARY_CHARS = 500;
+var boundedGateFeedback = (feedback) => feedback.length <= MAX_GATE_FEEDBACK_CHARS ? feedback : `${feedback.slice(0, MAX_GATE_FEEDBACK_CHARS - GATE_FEEDBACK_TRUNCATION_SUFFIX.length)}${GATE_FEEDBACK_TRUNCATION_SUFFIX}`;
+var gateRejectionSummary = (feedback) => {
+  const compact = feedback.trim().replace(/\s+/g, " ");
+  if (!compact)
+    return "Gate rejected";
+  const summary = `Gate rejected: ${compact}`;
+  return summary.length <= MAX_GATE_REJECTION_SUMMARY_CHARS ? summary : `${summary.slice(0, MAX_GATE_REJECTION_SUMMARY_CHARS - 1)}…`;
+};
 var beginGate = (workflow, run, outcome, artifact, requestId, now, summary) => {
   if (run.status !== "running") {
     throw new Error(`workflow is ${run.status}; gate submission requires a running workflow`);
@@ -5907,15 +5948,32 @@ var attachGateReviewId = (run, reviewId, now) => {
   }
   return withRunUpdate(run, { pendingGate: { ...run.pendingGate, reviewId } }, now);
 };
-var failGate = (run, reason, now) => run.pendingGate ? withRunUpdate(run, {
-  status: "running",
-  pendingGate: undefined,
-  gateFeedback: reason,
-  pausedFrom: undefined,
-  pauseReason: undefined,
-  failedStepId: undefined
-}, now) : run;
-var storeGateResolution = (run, resolution, now) => run.pendingGate ? withRunUpdate(run, { pendingGate: { ...run.pendingGate, resolution } }, now) : run;
+var failGate = (run, reason, now) => {
+  if (!run.pendingGate)
+    return run;
+  return withRunUpdate(run, {
+    status: "running",
+    pendingGate: undefined,
+    gateArtifact: run.pendingGate.artifact,
+    gateFeedback: boundedGateFeedback(reason),
+    pausedFrom: undefined,
+    pauseReason: undefined,
+    failedStepId: undefined
+  }, now);
+};
+var storeGateResolution = (run, resolution, now) => {
+  if (!run.pendingGate)
+    return run;
+  return withRunUpdate(run, {
+    pendingGate: {
+      ...run.pendingGate,
+      resolution: {
+        ...resolution,
+        feedback: boundedGateFeedback(resolution.feedback)
+      }
+    }
+  }, now);
+};
 var resolveGate = (workflow, run, resolution, now) => {
   const pendingGate = run.pendingGate;
   if (!pendingGate)
@@ -5928,16 +5986,17 @@ var resolveGate = (workflow, run, resolution, now) => {
     throw new Error("gate result does not match the current step");
   }
   const outcome = resolution.approved ? step.gate.approvedOutcome : step.gate.rejectedOutcome;
+  const feedback = boundedGateFeedback(resolution.feedback);
   const stepStructuralDigest = workflow.stepStructuralDigests[pendingGate.stepId] ?? "";
   if (resolution.approved && !stepStructuralDigest) {
     throw new Error(`gated step "${pendingGate.stepId}" has no structural digest`);
   }
-  const summary = resolution.approved ? pendingGate.summary ?? "" : resolution.feedback ? `Gate rejected: ${resolution.feedback}` : "Gate rejected";
+  const summary = resolution.approved ? pendingGate.summary ?? "" : gateRejectionSummary(feedback);
   const decidedRun = recordCurrentGateDecision(run, {
     provider: pendingGate.provider,
     requestId: pendingGate.requestId,
     approved: resolution.approved,
-    feedback: resolution.feedback,
+    feedback,
     resolvedAt: resolution.resolvedAt,
     ...pendingGate.reviewId ? { reviewId: pendingGate.reviewId } : {}
   }, now);
@@ -5946,9 +6005,13 @@ var resolveGate = (workflow, run, resolution, now) => {
     pendingGate: undefined,
     pausedFrom: undefined,
     pauseReason: undefined,
-    gateFeedback: resolution.feedback
+    gateArtifact: resolution.approved ? "" : pendingGate.artifact,
+    gateFeedback: resolution.approved ? "" : feedback
   }, now);
-  const advanced = advanceRun(workflow, runnableRun, outcome, summary, now);
+  const isSameStepHumanRevision = !resolution.approved && step.transitions[outcome] === pendingGate.stepId;
+  const advanced = advanceRun(workflow, runnableRun, outcome, summary, now, {}, {
+    sameStepHumanGateRevision: isSameStepHumanRevision
+  });
   const completedApprovedGate = resolution.approved && advanced.history.length > runnableRun.history.length;
   const history = completedApprovedGate ? advanced.history.map((entry, index) => index === advanced.history.length - 1 ? {
     ...entry,
@@ -5956,7 +6019,7 @@ var resolveGate = (workflow, run, resolution, now) => {
     approval: {
       requestId: pendingGate.requestId,
       artifact: pendingGate.artifact,
-      feedback: resolution.feedback,
+      feedback,
       stepStructuralDigest
     }
   } : entry) : advanced.history;
@@ -5965,9 +6028,10 @@ var resolveGate = (workflow, run, resolution, now) => {
     history,
     ...completedApprovedGate ? {
       reviewedArtifact: pendingGate.artifact,
-      reviewedFeedback: resolution.feedback
+      reviewedFeedback: feedback
     } : {},
-    gateFeedback: resolution.feedback
+    gateArtifact: resolution.approved ? "" : pendingGate.artifact,
+    gateFeedback: resolution.approved ? "" : feedback
   };
 };
 // src/engine/run-lifecycle.ts
@@ -6251,6 +6315,7 @@ var reconcileRun = (run, workflow, now) => {
         pausedFrom: "running",
         failedStepId: undefined,
         pauseReason: `Configuration changed; restarted step "${restartedStep}"`,
+        gateArtifact: "",
         gateFeedback: ""
       }, now)
     };
@@ -6263,6 +6328,7 @@ var reconcileRun = (run, workflow, now) => {
     pausedFrom: "running",
     failedStepId: undefined,
     pauseReason: `Configuration changed; restarted step "${run.currentStepId}"`,
+    gateArtifact: "",
     gateFeedback: ""
   } : {};
   return {
@@ -6732,7 +6798,7 @@ function currentStepHandoff(run) {
     "Incoming previous-step handoff:",
     incomingHandoff,
     "",
-    "Latest paused attempt:",
+    "Latest current-step summary:",
     run.lastSummary
   ].join(`
 `);
@@ -6757,6 +6823,7 @@ function createTemplateValues({
     "last.summary": currentStepHandoff(run),
     "reviewed.artifact": run.reviewedArtifact ?? "",
     "reviewed.feedback": run.reviewedFeedback ?? "",
+    "gate.artifact": run.gateArtifact ?? "",
     "gate.feedback": run.gateFeedback,
     "resume.input": run.resumeInput ?? ""
   };

package/examples/mr-comments.workflow.yaml

@@ -68,7 +68,7 @@ steps:
       timeoutMs: 30000
     transitions:
       approved: implement
-      changes-requested: $pause
+      changes-requested: plan
       blocked: $pause
   implement:
     title: Implement the approved plan

package/examples/prompts/mr-comments/plan.md

@@ -1,8 +1,15 @@
 Create a concrete, decision-ready implementation plan from the inspected
-feedback. Account for previous Plannotator feedback:
+feedback. The previously rejected artifact is:
+
+{{gate.artifact}}
+
+Account for previous Plannotator feedback:
 
 {{gate.feedback}}
 
+When feedback is non-empty, revise the rejected artifact and submit the complete
+proposal for another review. Each rejection returns to this same planning step.
+
 Write the artifact for a human reviewer first. Use this order:
 
 # <Short outcome-oriented title>

package/examples/starter-kit/mr-comment.workflow.yaml

@@ -11,7 +11,7 @@ steps:
     prompt:
       file: steps/mr-comment/fetch.md
     subagent:
-      agent: pi-workflows.step
+      agent: scout
       context: fresh
       timeoutMs: 1800000
     permissions:
@@ -49,7 +49,7 @@ steps:
     prompt:
       file: steps/mr-comment/plan.md
     subagent:
-      agent: pi-workflows.step
+      agent: planner
       context: fresh
       timeoutMs: 1800000
     permissions:
@@ -76,7 +76,7 @@ steps:
       timeoutMs: 30000
     transitions:
       approved: implement
-      changes-requested: $pause
+      changes-requested: plan
       blocked: $pause
 
   implement:
@@ -84,7 +84,7 @@ steps:
     prompt:
       file: steps/mr-comment/implement.md
     subagent:
-      agent: pi-workflows.step
+      agent: worker
       context: fresh
       timeoutMs: 7200000
       artifacts: true
@@ -104,7 +104,7 @@ steps:
     prompt:
       file: steps/mr-comment/verify.md
     subagent:
-      agent: pi-workflows.step
+      agent: reviewer
       context: fresh
       timeoutMs: 3600000
     permissions:
@@ -125,7 +125,7 @@ steps:
     prompt:
       file: steps/mr-comment/publish.md
     subagent:
-      agent: pi-workflows.step
+      agent: worker
       context: fresh
       timeoutMs: 1800000
     permissions: