@wichayutdew/pi-workflows 2.6.0 → 2.7.0

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

@@ -1,70 +1,23 @@
-You are the independent verification stage for local work. You are the active workflow step; do not modify files, amend commits, or delegate this work.
+You are the independent verification stage for local work. Stay read-only in this delegated child; do not modify files, amend commits, or launch subagents.
 
 Original request:
 {{workflow.input}}
 
-Immutable approved plan:
+Approved plan:
 {{reviewed.artifact}}
 
 Approval feedback:
 {{reviewed.feedback}}
 
-Implementation ledger or blocked recovery handoff:
+Implementation ledger:
 {{last.summary}}
 
-The approved plan is final authority. Do not ask a terminal question. If
-verification cannot follow the approved contract, diagnose and recover as
-described below; do not request a live decision.
+## Rules & Verification Criteria
 
-Re-read repository instructions and inspect the contracted repository, every
-approved criterion, diff, commit, caller, test, and current status. Run the
-exact standalone commands under `repositories[0].reviewer[].command`, including
-the complete repository test suite plus non-fixing format and lint checks.
-Confirm the actual child cwd, registered worktree, dedicated branch, and
-workspace manifest still identify the same prepared workspace; never create,
-switch, or replace it.
-Static Bash permissions are inspection-only; do not invent or broaden a
-command. Confirm exact commit titles, unchanged post-review snapshots,
-RED/GREEN evidence, and per-criterion outcomes. When preparation recorded a
-clean baseline, require a clean final worktree. When it recorded unrelated
-dirty resumable work, require that exact baseline state to remain unchanged and
-that no task-owned change remains uncommitted. Treat a skipped, stale,
-unavailable, timed-out, blocked, or failing required check as non-passing.
-
-Any regression, lint failure, formatting failure, or other actionable local
-verification finding must use outcome `failed`, with the exact evidence and
-smallest fix. The workflow transition returns `failed` directly to
-implementation. Do not use `retry` or `blocked` for such a finding.
-
-If the approved verification contract is exactly
-`Not applicable - read-only plan.`, the absence of repository test commands is
-intentional. Independently re-check every requested fact and acceptance
-criterion with non-mutating inspection, confirm the checkout stayed unchanged,
-and do not invent or require code-change tests, formatting, lint, commits, or
-RED/GREEN evidence that the approved read-only task does not call for.
-
-Do not stop at the first failed tool or command. Read the exact error, inspect
-current state, and try safe semantically equivalent read-only alternatives.
-Invocation-only repair is allowed when it preserves the exact check, target,
-flags, and side-effect scope; never turn a failing check into a different or
-weaker check. If a transient or context-bound failure has another safe attempt,
-use outcome `retry` with the exact call, error, attempts, current state, next
-alternative, and exact approved fenced `json` contract unchanged. Use `blocked`
-with exact evidence when reviewed intent, targets, commands, or authority are
-materially invalid, or after safe alternatives are exhausted and retry cannot
-resolve the environmental or access constraint.
-
-Call `workflow_complete_step` alone with outcome `passed` only when every
-criterion and required command passes with no actionable finding. The summary
-must repeat all approved criteria and contracts and provide fresh evidence.
-Use outcome `failed` for an actionable implementation or verification finding;
-include the full criteria, exact failure, location, evidence, and smallest
-required fix so the next implementation attempt has a complete handoff. For
-both `passed` and `failed`, include the exact approved fenced `json` repository
-contract unchanged so a retry retains only reviewed worker commands. Use
-`blocked` for an invalid approved contract or when offered recovery cannot make
-verification proceed safely.
-On a retry after `blocked`, re-check the blocked
-source or reconciliation issue and use any remaining safe relevant alternative;
-do not repeat an exhausted attempt without a changed precondition. Do not ask a
-terminal question.
+1. **Independent Verification**: Re-run all standalone commands under `repositories[0].reviewer[]` (`full-tests`, `lint`, `format`).
+2. **Strict Evidence**: Confirm exact commit title, clean status (or original dirty baseline preserved), and explicit criterion proofs. Any failing or skipped check is non-passing.
+3. **Outcomes**:
+   - `passed`: All acceptance criteria and automated checks verified.
+   - `failed`: Actionable failure or regression. Automatically returns to `implement` stage for fix.
+   - `retry`: Recoverable read-only environment failure.
+   - `blocked`: Corrupted workspace or missing review authority.

package/examples/starter-kit/ticket.workflow.yaml

@@ -1,7 +1,7 @@
 version: 1
 id: ticket
 command: ticket
-description: Prepare a dedicated workspace, plan, implement, and verify a Jira ticket
+description: 'Prepare a dedicated workspace, plan, implement, and verify an issue-tracker ticket. Example: /ticket PROJ-123 Fix a missing client-id header'
 start: prepare-workspace
 maxStepVisits: 20
 summaryMaxChars: 30000
@@ -10,18 +10,19 @@ steps:
     title: Prepare dedicated branch and worktree
     prompt:
       file: steps/shared/prepare-workspace.md
-    agent: worker
+    agent: workspace-preparer
     workspace:
-      bindOn: [ready]
-      allowedRoots: ['~/repositories/worktrees']
+      bindOn:
+        - ready
+      allowedRoots:
+        - ~/repositories/worktrees
     permissions:
       tools: [read, ls, bash]
-      skills: [caveman, coding-standards, using-git-worktrees]
+      mcp: []
+      extensions: [/]
+      skills: [using-git-worktrees, caveman]
       bash:
         mode: unrestricted
-    requires:
-      tools: [read, ls, bash]
-      skills: [caveman, coding-standards, using-git-worktrees]
     transitions:
       ready: plan
       retry: prepare-workspace
@@ -32,65 +33,38 @@ steps:
       file: steps/ticket/plan.md
     agent: planner
     permissions:
-      tools: [read, ls, bash]
-      mcp: &ticket-mcp
-        - atlassian/atlassian_getAccessibleAtlassianResources
-        - atlassian/atlassian_getJiraIssue
-        - atlassian/atlassian_getJiraIssueRemoteIssueLinks
-        - atlassian/atlassian_searchJiraIssuesUsingJql
-        - context7/resolve-library-id
-        - context7/query-docs
-        - sourcegraph/code_finder
-        - sourcegraph/commit_search
-        - sourcegraph/diff_search
-        - sourcegraph/keyword_search
-        - sourcegraph/list_files
-        - sourcegraph/list_repos
-        - sourcegraph/nls_search
-        - sourcegraph/read_file
-        - gh_grep/searchGitHub
-      extensions: [pi-web-tools]
+      tools: [read, ls, bash, mcp]
+      mcp: [atlassian, context7, sourcegraph, glean, gitlab]
+      extensions: [/]
       skills:
-        &ticket-plan-skills [
-          caveman,
+        [
           jira-ticket,
           coding-standards,
-          brainstorming,
+          writing-plans,
+          search-code-sourcegraph,
+          caveman,
         ]
       bash:
-        mode: allow-list
-        allow: &ticket-inspection-bash
-          - executable: grep
-          - executable: head
-          - executable: ls
-          - executable: pwd
-          - executable: rg
-          - executable: stat
-          - executable: tail
-          - executable: wc
-          - executable: git
-            argsPrefixes:
-              [
-                [status],
-                [diff],
-                [grep],
-                [log],
-                [ls-files],
-                [rev-parse],
-                [show],
-                [merge-base],
-                [rev-list],
-                [worktree, list],
-              ]
-    requires:
-      tools: [read, ls, bash, mcp]
-      skills: *ticket-plan-skills
+        mode: unrestricted
     gate:
       provider: plannotator
       submitOutcome: submit
       approvedOutcome: approved
       rejectedOutcome: changes-requested
       timeoutMs: 30000
+      artifactContract:
+        maxChars: 10000
+        requiredSubstrings:
+          - '## Review summary'
+          - '## Review focus'
+          - '## Proposed approach'
+          - '## Validation'
+          - '## Risks'
+          - '## Execution appendix (machine-readable)'
+          - '## Publication contract'
+        forbiddenSubstrings:
+          - 'The complete gate artifact is the exact Markdown saved at'
+        onValidationFailure: retry
     transitions:
       approved: implement
       changes-requested: plan
@@ -103,23 +77,13 @@ steps:
       file: steps/ticket/implement.md
     agent: worker
     permissions:
-      tools: [read, ls, bash, edit, write]
-      mcp: *ticket-mcp
+      tools: [read, ls, bash, edit, write, mcp]
+      mcp: [context7]
+      extensions: [/]
       skills:
-        &ticket-implement-skills [
-          caveman,
-          jira-ticket,
-          coding-standards,
-          systematic-debugging,
-          test-driven-development,
-          verification-before-completion,
-          receiving-code-review,
-        ]
+        [coding-standards, test-driven-development, lint-commands, caveman]
       bash:
         mode: unrestricted
-    requires:
-      tools: [read, ls, bash, edit, write, mcp]
-      skills: *ticket-implement-skills
     transitions:
       ready: verify
       retry: implement
@@ -130,20 +94,13 @@ steps:
       file: steps/ticket/verify.md
     agent: reviewer
     permissions:
-      tools: [read, ls, bash]
-      mcp: *ticket-mcp
+      tools: [read, ls, bash, mcp]
+      mcp: [gitlab]
+      extensions: [/]
       skills:
-        &ticket-verify-skills [
-          caveman,
-          jira-ticket,
-          coding-standards,
-          verification-before-completion,
-        ]
+        [verification-before-completion, lint-commands, commit-format, caveman]
       bash:
         mode: unrestricted
-    requires:
-      tools: [read, ls, bash, mcp]
-      skills: *ticket-verify-skills
     transitions:
       passed: $done
       failed: implement

package/examples/starter-kit/work.workflow.yaml

@@ -1,7 +1,7 @@
 version: 1
 id: work
 command: work
-description: Prepare a dedicated workspace, plan, implement, and verify local work
+description: 'Prepare a dedicated workspace, plan, implement, and verify local work. Example: /work Add rate limiting to user registration endpoint'
 start: prepare-workspace
 maxStepVisits: 20
 summaryMaxChars: 30000
@@ -10,18 +10,19 @@ steps:
     title: Prepare dedicated branch and worktree
     prompt:
       file: steps/shared/prepare-workspace.md
-    agent: worker
+    agent: workspace-preparer
     workspace:
-      bindOn: [ready]
-      allowedRoots: ['~/repositories/worktrees']
+      bindOn:
+        - ready
+      allowedRoots:
+        - ~/repositories/worktrees
     permissions:
       tools: [read, ls, bash]
-      skills: [caveman, coding-standards, using-git-worktrees]
+      mcp: []
+      extensions: [/]
+      skills: [using-git-worktrees, caveman]
       bash:
         mode: unrestricted
-    requires:
-      tools: [read, ls, bash]
-      skills: [caveman, coding-standards, using-git-worktrees]
     transitions:
       ready: plan
       retry: prepare-workspace
@@ -32,55 +33,31 @@ steps:
       file: steps/work/plan.md
     agent: planner
     permissions:
-      tools: [read, ls, bash]
-      mcp: &work-mcp
-        - context7/resolve-library-id
-        - context7/query-docs
-        - sourcegraph/code_finder
-        - sourcegraph/commit_search
-        - sourcegraph/diff_search
-        - sourcegraph/keyword_search
-        - sourcegraph/list_files
-        - sourcegraph/list_repos
-        - sourcegraph/nls_search
-        - sourcegraph/read_file
-        - gh_grep/searchGitHub
-      extensions: [pi-web-tools]
-      skills: &work-plan-skills [caveman, brainstorming, coding-standards]
+      tools: [read, ls, bash, mcp]
+      mcp: [context7, sourcegraph, glean, gh_grep]
+      extensions: [/]
+      skills:
+        [coding-standards, writing-plans, search-code-sourcegraph, caveman]
       bash:
-        mode: allow-list
-        allow: &work-inspection-bash
-          - executable: grep
-          - executable: head
-          - executable: ls
-          - executable: pwd
-          - executable: rg
-          - executable: stat
-          - executable: tail
-          - executable: wc
-          - executable: git
-            argsPrefixes:
-              [
-                [status],
-                [diff],
-                [grep],
-                [log],
-                [ls-files],
-                [rev-parse],
-                [show],
-                [merge-base],
-                [rev-list],
-                [worktree, list],
-              ]
-    requires:
-      tools: [read, ls, bash]
-      skills: *work-plan-skills
+        mode: unrestricted
     gate:
       provider: plannotator
       submitOutcome: submit
       approvedOutcome: approved
       rejectedOutcome: changes-requested
       timeoutMs: 30000
+      artifactContract:
+        maxChars: 8000
+        requiredSubstrings:
+          - '## Review summary'
+          - '## Review focus'
+          - '## Proposed approach'
+          - '## Validation'
+          - '## Risks'
+          - '## Execution appendix (machine-readable)'
+        forbiddenSubstrings:
+          - 'The complete gate artifact is the exact Markdown saved at'
+        onValidationFailure: retry
     transitions:
       approved: implement
       changes-requested: plan
@@ -93,22 +70,13 @@ steps:
       file: steps/work/implement.md
     agent: worker
     permissions:
-      tools: [read, ls, bash, edit, write]
-      mcp: *work-mcp
+      tools: [read, ls, bash, edit, write, mcp]
+      mcp: [context7]
+      extensions: [/]
       skills:
-        &work-implement-skills [
-          caveman,
-          coding-standards,
-          systematic-debugging,
-          test-driven-development,
-          verification-before-completion,
-          receiving-code-review,
-        ]
+        [coding-standards, test-driven-development, lint-commands, caveman]
       bash:
         mode: unrestricted
-    requires:
-      tools: [read, ls, bash, edit, write]
-      skills: *work-implement-skills
     transitions:
       ready: verify
       retry: implement
@@ -120,18 +88,12 @@ steps:
     agent: reviewer
     permissions:
       tools: [read, ls, bash]
-      mcp: *work-mcp
+      mcp: []
+      extensions: [/]
       skills:
-        &work-verify-skills [
-          caveman,
-          coding-standards,
-          verification-before-completion,
-        ]
+        [verification-before-completion, lint-commands, commit-format, caveman]
       bash:
         mode: unrestricted
-    requires:
-      tools: [read, ls, bash]
-      skills: *work-verify-skills
     transitions:
       passed: $done
       failed: implement

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wichayutdew/pi-workflows",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "A declarative, pauseable workflow harness for Pi",
   "license": "MIT",
   "repository": {
@@ -23,16 +23,19 @@
     "src",
     "examples",
     "schemas",
+    "scripts",
     "README.md",
     "LICENSE"
   ],
   "pi": {
     "extensions": [
-      "./src/index.ts"
+      "./src/index.ts",
+      "./src/herdr-workflow-state.ts"
     ]
   },
   "scripts": {
     "build": "bun build ./src/index.ts --outdir=dist --target=node --format=esm --packages=external",
+    "patch:herdr": "node ./scripts/patch-herdr-agent-state.mjs",
     "format": "bunx --bun prettier . --write",
     "format:check": "bunx --bun prettier . --check",
     "lint": "bun --bun eslint .",
@@ -56,7 +59,7 @@
     "@earendil-works/pi-coding-agent": "^0.81.1",
     "@earendil-works/pi-tui": "^0.81.1",
     "@eslint/js": "^10.0.1",
-    "@types/bun": "^1.3.14",
+    "@types/bun": "^1.4.0",
     "@types/node": "^24.0.0",
     "eslint": "^10.7.0",
     "globals": "^17.7.0",
@@ -65,7 +68,7 @@
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.64.0"
   },
-  "packageManager": "bun@1.3.14",
+  "packageManager": "bun@1.4.0",
   "engines": {
     "node": ">=22.19.0"
   }

package/schemas/workflow.schema.json

@@ -514,6 +514,61 @@
         }
       }
     },
+    "artifactContract": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "maxChars",
+        "requiredSubstrings",
+        "forbiddenSubstrings",
+        "equalOccurrenceGroups"
+      ],
+      "properties": {
+        "maxChars": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 200000
+        },
+        "requiredSubstrings": {
+          "type": "array",
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1024
+          }
+        },
+        "forbiddenSubstrings": {
+          "type": "array",
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1024
+          }
+        },
+        "equalOccurrenceGroups": {
+          "type": "array",
+          "maxItems": 32,
+          "items": {
+            "type": "array",
+            "minItems": 2,
+            "maxItems": 32,
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 1024
+            }
+          }
+        },
+        "onValidationFailure": {
+          "const": "retry"
+        }
+      }
+    },
     "gate": {
       "oneOf": [
         {
@@ -533,6 +588,9 @@
             },
             "rejectedOutcome": {
               "$ref": "#/$defs/identifier"
+            },
+            "artifactContract": {
+              "$ref": "#/$defs/artifactContract"
             }
           }
         },
@@ -563,6 +621,9 @@
               "minimum": 1000,
               "maximum": 30000,
               "default": 30000
+            },
+            "artifactContract": {
+              "$ref": "#/$defs/artifactContract"
             }
           }
         }

package/scripts/patch-herdr-agent-state.mjs

@@ -0,0 +1,36 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const target =
+  process.env.HERDR_PI_EXTENSION_PATH ??
+  join(homedir(), '.pi', 'agent', 'extensions', 'herdr-agent-state.ts');
+const source = await readFile(target, 'utf8');
+if (source.includes('pi-workflows-herdr-lifecycle-patch:start')) {
+  console.log(`Herdr workflow patch already present: ${target}`);
+  process.exit(0);
+}
+const state =
+  '  // pi-workflows-herdr-lifecycle-patch:start\n  let workflowActive = false;\n  let workflowMessage: string | undefined;\n  // pi-workflows-herdr-lifecycle-patch:end\n';
+const listener =
+  '  // pi-workflows-herdr-lifecycle-patch:start\n  pi.events.on("pi-workflows:state", (data) => {\n    if (!rootSession || !data || typeof data !== "object") return;\n    const event = data as { state?: string; message?: string };\n    workflowActive = event.state === "working";\n    workflowMessage = event.message;\n    publishState();\n  });\n  // pi-workflows-herdr-lifecycle-patch:end\n\n';
+let patched = source.replace(
+  '  let blockedCount = 0;',
+  `${state}  let blockedCount = 0;`,
+);
+patched = patched.replace(
+  '    if (agentActive) {\n      return { state: "working" as const, message: undefined };',
+  '    if (agentActive || workflowActive) {\n      return { state: "working" as const, message: workflowMessage };',
+);
+patched = patched.replace(
+  '    return { state: "idle" as const, message: undefined };',
+  '    return { state: "idle" as const, message: workflowMessage };',
+);
+patched = patched.replace(
+  '  pi.events.on("herdr:blocked",',
+  `${listener}  pi.events.on("herdr:blocked",`,
+);
+if (patched === source)
+  throw new Error(`Unsupported Herdr integration layout: ${target}`);
+await writeFile(target, patched);
+console.log(`Patched Herdr workflow lifecycle reporting: ${target}`);

package/src/config/types.ts

@@ -49,10 +49,19 @@ export type StepAgent = {
 export type PromptSpec =
   { readonly inline: string } | { readonly file: string };
 
+export type ArtifactContract = {
+  readonly maxChars: number;
+  readonly requiredSubstrings: ReadonlyArray<string>;
+  readonly forbiddenSubstrings: ReadonlyArray<string>;
+  readonly equalOccurrenceGroups: ReadonlyArray<ReadonlyArray<string>>;
+  readonly onValidationFailure?: 'retry';
+};
+
 type GateDefinition = {
   readonly submitOutcome: string;
   readonly approvedOutcome: string;
   readonly rejectedOutcome: string;
+  readonly artifactContract?: ArtifactContract;
 };
 
 export type PromptGate = GateDefinition & {