@osolmaz/pi-workflows 0.13.0 → 0.13.2

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "osolmaz.pi-workflows"
 name = "pi-workflows"
-version = "0.13.0"
+version = "0.13.2"
 min_herdr_version = "0.7.0"
 description = "Open the active pi-workflows run in piw from a managed Herdr pane."
 platforms = ["linux", "macos"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osolmaz/pi-workflows",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Workflow and controller runtime with a live terminal viewer for the pi coding agent",
   "keywords": [
     "pi-package"

package/skills/autodoc/SKILL.md

@@ -15,6 +15,10 @@ Build the input as follows:
 - `task`: State what selected plan must be recorded and that this run is documentation-only.
 - `plan`: Pass the complete selected plan. Autodoc does not devise or improve it.
 - `repository`: Use the absolute path of the repository that owns the canonical documentation.
+- `baseBranch`: Use the requested base or the repository default branch.
+- `scope`: Name the allowed repository and documentation edits. Exclude implementation and unauthorized remote actions.
+- `workspaceMode`: Use `auto` unless the conversation requires `branch`, `worktree`, or explicitly authorized `defaultBranch` work. Autodoc prepares the workspace only when documentation needs an update.
+- `preparedWorkspace`: Include a previously confirmed `pi-workflows.prepared-workspace.v1` result when a parent workflow already prepared the workspace. Omit it otherwise.
 - `documents`: Include every known canonical specification or plan candidate. Use an empty array when none is known.
 - `evidence`: Include implementation evidence or current-document evidence when it affects whether documentation is current.
 
@@ -31,6 +35,9 @@ Replace the example values below with facts from the conversation, then make one
       "requirements": ["Keep cancellation terminal."]
     },
     "repository": "/absolute/path/to/repository",
+    "baseBranch": "main",
+    "scope": "Only /absolute/path/to/repository. May update canonical documentation and run documentation checks. Must not implement, push, merge, release, or deploy.",
+    "workspaceMode": "auto",
     "documents": ["docs/plans/timeout-fallback-plan.md"],
     "evidence": {
       "currentBehavior": "A timeout ends the run."

package/skills/autoimplement/SKILL.md

@@ -18,6 +18,9 @@ Build the input as follows:
 - `scope`: Always include a concrete authority statement. Name every allowed repository and the allowed edit, test, commit, push, pull-request, merge, and release actions. Carry forward exclusions from the conversation. A repository path alone is not a scope.
 - `constraints`: Include all applicable user and repository constraints. Use an empty array when none apply.
 - `baseBranch`: Use the requested base or the repository default branch.
+- `workspaceMode`: Use `auto` unless the user or repository requires `branch`, `worktree`, or `defaultBranch`. `auto` keeps a correct task branch, creates a task branch from a clean default branch, and isolates a dirty default checkout in a standard sibling worktree. Use `defaultBranch` only with explicit direct-work authority.
+- `preparedWorkspace`: Include a previously confirmed `pi-workflows.prepared-workspace.v1` result when the workspace was prepared before the run. Omit it otherwise.
+- `directDefaultBranchAuthorized`: Set `true` only when direct work on the actual default branch is explicit. It does not grant commit, push, merge, or release authority.
 - `merge`: Set `true` only when the user explicitly requested merge or an applicable standing instruction authorizes it. Otherwise set `false`.
 - `documents`: Include known canonical plan or specification paths. Use an empty array when none are known.
 - `approval`: Omit it for the default behavior: ask on each new plan and continue after 10 minutes without an answer. Use `{ "mode": "required" }` when the user says to block on plan changes. Use `{ "mode": "skip" }` when the user says to continue without asking about plan changes.
@@ -46,6 +49,7 @@ Replace the example values below with facts from the conversation, then make one
     "scope": "Only /absolute/path/to/repository. May edit and test task-related files, create commits, push the task branch, and open or update its pull request. Must not modify other repositories, merge, release, deploy, change credentials, or change repository policy.",
     "constraints": ["Preserve immediate cancellation.", "Keep deferred-turn work separate."],
     "baseBranch": "main",
+    "workspaceMode": "auto",
     "merge": false,
     "documents": ["docs/plans/timeout-fallback-plan.md"]
   }

package/src/builtins/autodoc.workflow.ts

@@ -1,11 +1,35 @@
-import { agent, compute, defineWorkflow } from "../workflows/definition.js";
+import path from "node:path";
+import {
+  agent,
+  compute,
+  defineWorkflow,
+  includeWorkflow,
+  includedResult,
+} from "../workflows/definition.js";
 import { digest } from "../workflows/human-decision.js";
 import type { WorkflowNodeContext } from "../workflows/types.js";
+import changeVerificationWorkflow, {
+  type ChangeVerificationInput,
+  type ChangeVerificationResult,
+  type VerificationCheck,
+} from "./change-verification.workflow.js";
+import workspacePreparationWorkflow, {
+  parsePreparedWorkspace,
+  type PreparedWorkspace,
+  type WorkspaceMode,
+  type WorkspacePreparationInput,
+} from "./workspace-preparation.workflow.js";
 
 export type AutodocInput = {
   task: string;
   plan?: unknown;
   repository?: string;
+  baseBranch?: string;
+  scope?: string;
+  workspaceMode?: WorkspaceMode;
+  directDefaultBranchAuthorized?: boolean;
+  preparedWorkspace?: PreparedWorkspace;
+  verificationChecks?: VerificationCheck[];
   documents?: string[];
   evidence?: unknown;
 };
@@ -21,7 +45,8 @@ export type DocumentedPlan = {
     digests: Record<string, string>;
     evidence: unknown;
   };
-  verification: unknown;
+  verification: ChangeVerificationResult | { route: "ready"; reason: string };
+  workspace?: PreparedWorkspace;
 };
 
 export type AutodocBlocked = {
@@ -29,6 +54,7 @@ export type AutodocBlocked = {
   task: string;
   reason: string;
   evidence: unknown;
+  sourceNode?: string;
 };
 
 type LocatedPlan = {
@@ -47,6 +73,10 @@ type DocumentationAssessment = {
   evidence: unknown;
 };
 
+type WorkspaceGuard =
+  | { route: "ready"; repository: string }
+  | { route: "blocked"; reason: string; evidence: string[] };
+
 function requireRecord(value: unknown, label: string): Record<string, unknown> {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     throw new Error(`${label} must be an object`);
@@ -61,6 +91,12 @@ function requireString(value: unknown, label: string): string {
   return value.trim();
 }
 
+function requireAbsolutePath(value: unknown, label: string): string {
+  const result = requireString(value, label);
+  if (!path.isAbsolute(result)) throw new Error(`${label} must be absolute`);
+  return path.resolve(result);
+}
+
 function stringArray(value: unknown, label: string): string[] {
   if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
     throw new Error(`${label} must be an array of strings`);
@@ -77,15 +113,38 @@ function stringRecord(value: unknown, label: string): Record<string, string> {
   return record as Record<string, string>;
 }
 
+function parseWorkspaceMode(value: unknown): WorkspaceMode | undefined {
+  if (value === undefined) return undefined;
+  if (value !== "auto" && value !== "branch" && value !== "worktree" && value !== "defaultBranch") {
+    throw new Error("autodoc workspaceMode must be auto, branch, worktree, or defaultBranch");
+  }
+  return value;
+}
+
 function parseInput(value: unknown): AutodocInput {
   const input = requireRecord(value, "autodoc input");
   const documents = input.documents;
+  const workspaceMode = parseWorkspaceMode(input.workspaceMode);
   return {
     task: requireString(input.task, "autodoc task"),
     ...(input.plan !== undefined ? { plan: input.plan } : {}),
     ...(input.repository !== undefined
-      ? { repository: requireString(input.repository, "autodoc repository") }
+      ? { repository: requireAbsolutePath(input.repository, "autodoc repository") }
+      : {}),
+    ...(input.baseBranch !== undefined
+      ? { baseBranch: requireString(input.baseBranch, "autodoc baseBranch") }
       : {}),
+    ...(input.scope !== undefined ? { scope: requireString(input.scope, "autodoc scope") } : {}),
+    ...(workspaceMode === undefined ? {} : { workspaceMode }),
+    ...(input.directDefaultBranchAuthorized === undefined
+      ? {}
+      : { directDefaultBranchAuthorized: input.directDefaultBranchAuthorized === true }),
+    ...(input.preparedWorkspace === undefined
+      ? {}
+      : { preparedWorkspace: parsePreparedWorkspace(input.preparedWorkspace) }),
+    ...(input.verificationChecks === undefined
+      ? {}
+      : { verificationChecks: input.verificationChecks as VerificationCheck[] }),
     ...(documents !== undefined ? { documents: stringArray(documents, "autodoc documents") } : {}),
     ...(input.evidence !== undefined ? { evidence: input.evidence } : {}),
   };
@@ -132,10 +191,61 @@ function currentPlan(context: WorkflowNodeContext): unknown {
   throw new Error("autodoc does not have a selected plan");
 }
 
+function mutationRepository(request: AutodocInput): string {
+  if (request.repository !== undefined) return request.repository;
+  if (request.preparedWorkspace !== undefined) return request.preparedWorkspace.repository;
+  throw new Error("autodoc mutation requires an explicit repository");
+}
+
+function preparedWorkspace(context: WorkflowNodeContext): PreparedWorkspace {
+  const request = context.input as AutodocInput;
+  if (request.preparedWorkspace !== undefined) return request.preparedWorkspace;
+  const result = includedResult(workspacePreparationWorkflow, context.outputs.workspace);
+  if (result.exit !== "ready") throw new Error("autodoc workspace is not ready");
+  return result.output;
+}
+
+function verificationResult(context: WorkflowNodeContext): ChangeVerificationResult {
+  const result = includedResult(changeVerificationWorkflow, context.outputs.verification);
+  return result.output;
+}
+
 function blockedReason(context: WorkflowNodeContext): AutodocBlocked {
   const request = context.input as AutodocInput;
   const assessment = context.outputs.inspectDocumentation as DocumentationAssessment | undefined;
   const located = context.outputs.locatePlan as LocatedPlan | undefined;
+  if (context.outputs.verification !== undefined) {
+    const result = includedResult(changeVerificationWorkflow, context.outputs.verification);
+    return {
+      status: "blocked",
+      task: request.task,
+      reason: result.output.reason,
+      evidence: result.output,
+      sourceNode: result.output.qualifiedNode,
+    };
+  }
+  const guard = context.outputs.workspaceGuard as WorkspaceGuard | undefined;
+  if (guard?.route === "blocked") {
+    return {
+      status: "blocked",
+      task: request.task,
+      reason: guard.reason,
+      evidence: guard.evidence,
+      sourceNode: "autodoc/workspaceGuard",
+    };
+  }
+  if (context.outputs.workspace !== undefined) {
+    const result = includedResult(workspacePreparationWorkflow, context.outputs.workspace);
+    if (result.exit === "blocked") {
+      return {
+        status: "blocked",
+        task: request.task,
+        reason: result.output.reason,
+        evidence: result.output,
+        sourceNode: "autodoc/workspace",
+      };
+    }
+  }
   return {
     status: "blocked",
     task: request.task,
@@ -146,6 +256,8 @@ function blockedReason(context: WorkflowNodeContext): AutodocBlocked {
           ? located.reason
           : "Autodoc could not identify a clear selected plan or canonical document target.",
     evidence: assessment?.evidence ?? located?.evidence ?? null,
+    sourceNode:
+      assessment?.route === "blocked" ? "autodoc/inspectDocumentation" : "autodoc/locatePlan",
   };
 }
 
@@ -156,7 +268,42 @@ export const autodocWorkflow = defineWorkflow({
   input: parseInput,
   title: ({ input }) => `autodoc: ${input.task.slice(0, 60)}`,
   startAt: "prepare",
-  maxSteps: 24,
+  maxSteps: 80,
+  includes: {
+    workspace: includeWorkflow(workspacePreparationWorkflow, {
+      input: (context): WorkspacePreparationInput => {
+        const request = context.input as AutodocInput;
+        return {
+          repository: mutationRepository(request),
+          ...(request.baseBranch === undefined ? {} : { baseBranch: request.baseBranch }),
+          ...(request.scope === undefined ? {} : { scope: request.scope }),
+          ...(request.workspaceMode === undefined ? {} : { workspaceMode: request.workspaceMode }),
+          ...(request.directDefaultBranchAuthorized === undefined
+            ? {}
+            : { directDefaultBranchAuthorized: request.directDefaultBranchAuthorized }),
+          ...(request.preparedWorkspace === undefined
+            ? {}
+            : { preparedWorkspace: request.preparedWorkspace }),
+        };
+      },
+    }),
+    verification: includeWorkflow(changeVerificationWorkflow, {
+      input: (context): ChangeVerificationInput => {
+        const request = context.input as AutodocInput;
+        const update = requireRecord(context.outputs.updateDocumentation, "documentation update");
+        return {
+          originatingWorkflow: "autodoc",
+          qualifiedNode: "autodoc/verification",
+          workspace: preparedWorkspace(context),
+          ...(request.verificationChecks === undefined
+            ? {}
+            : { checks: request.verificationChecks }),
+          changedFiles: stringArray(update.files, "updated documentation files"),
+          plan: currentPlan(context),
+        };
+      },
+    }),
+  },
   exits: {
     ready: {
       from: "finalize",
@@ -184,14 +331,26 @@ export const autodocWorkflow = defineWorkflow({
           "Return blocked when no single clear selected plan exists.",
           `Task: ${request.task}`,
           `Repository: ${request.repository ?? "current repository"}`,
-          `Referenced documents: ${JSON.stringify(request.documents ?? [])}`,
-          `Evidence: ${JSON.stringify(request.evidence ?? null)}`,
+          `Preferred documents: ${JSON.stringify(request.documents ?? [])}`,
         ].join("\n");
       },
       expectedOutput:
         '{ "route": "found" | "blocked", "plan": {} (required when found), "sources": ["source"], "reason": "reason", "evidence": "evidence" }',
       validate: parseLocatedPlan,
     }),
+    workspaceGuard: compute({
+      run: ({ input }): WorkspaceGuard => {
+        const request = input as AutodocInput;
+        if (request.repository !== undefined || request.preparedWorkspace !== undefined) {
+          return { route: "ready", repository: mutationRepository(request) };
+        }
+        return {
+          route: "blocked",
+          reason: "Updating canonical documentation requires an explicit repository path.",
+          evidence: ["repository was not supplied", "preparedWorkspace was not supplied"],
+        };
+      },
+    }),
     inspectDocumentation: agent({
       statusDetail: "checking canonical documentation",
       prompt: (context) => {
@@ -221,6 +380,7 @@ export const autodocWorkflow = defineWorkflow({
           "Update the canonical specification and implementation plan to preserve the selected plan exactly.",
           "Use the repository documentation rules and keep the text plain and complete.",
           "Do not redesign the solution and do not implement code.",
+          `Prepared workspace: ${JSON.stringify(preparedWorkspace(context))}`,
           `Task: ${request.task}`,
           `Selected plan: ${JSON.stringify(currentPlan(context))}`,
           `Canonical files: ${JSON.stringify(assessment.files)}`,
@@ -239,26 +399,6 @@ export const autodocWorkflow = defineWorkflow({
         return result;
       },
     }),
-    verifyDocumentation: agent({
-      timeoutMs: 20 * 60_000,
-      statusDetail: "verifying documentation",
-      prompt: ({ outputs }) =>
-        [
-          "Verify the changed canonical documentation.",
-          "Run the repository documentation, formatting, link, and privacy checks that apply.",
-          "Do not implement code.",
-          `Documentation update: ${JSON.stringify(outputs.updateDocumentation)}`,
-        ].join("\n"),
-      expectedOutput:
-        '{ "passed": true | false, "commands": [{ "command": "exact command", "outcome": "result" }], "failures": ["failure"] }',
-      validate: (value) => {
-        const result = requireRecord(value, "documentation verification");
-        if (typeof result.passed !== "boolean") {
-          throw new Error("documentation verification passed must be boolean");
-        }
-        return result;
-      },
-    }),
     finalize: compute({
       run: (context) => {
         const request = context.input as AutodocInput;
@@ -277,7 +417,13 @@ export const autodocWorkflow = defineWorkflow({
               digests: assessment.digests,
               evidence: assessment.evidence,
             },
-            verification: { passed: true, reason: "Canonical documentation was already current." },
+            verification: {
+              route: "ready",
+              reason: "Canonical documentation was already current.",
+            },
+            ...(request.preparedWorkspace === undefined
+              ? {}
+              : { workspace: request.preparedWorkspace }),
           } satisfies DocumentedPlan;
         }
         const updateRecord = requireRecord(updated, "documentation update");
@@ -290,9 +436,10 @@ export const autodocWorkflow = defineWorkflow({
             state: "updated",
             files: stringArray(updateRecord.files, "updated documentation files"),
             digests: stringRecord(updateRecord.digests, "updated documentation digests"),
-            evidence: context.outputs.verifyDocumentation,
+            evidence: verificationResult(context),
           },
-          verification: context.outputs.verifyDocumentation,
+          verification: verificationResult(context),
+          workspace: preparedWorkspace(context),
         } satisfies DocumentedPlan;
       },
     }),
@@ -311,14 +458,18 @@ export const autodocWorkflow = defineWorkflow({
       from: "inspectDocumentation",
       switch: {
         on: "$.route",
-        cases: { current: "finalize", update: "updateDocumentation", blocked: "blocked" },
+        cases: { current: "finalize", update: "workspaceGuard", blocked: "blocked" },
       },
     },
-    { from: "updateDocumentation", to: "verifyDocumentation" },
     {
-      from: "verifyDocumentation",
-      switch: { on: "$.passed", cases: { true: "finalize", false: "blocked" } },
+      from: "workspaceGuard",
+      switch: { on: "$.route", cases: { ready: "workspace", blocked: "blocked" } },
     },
+    { from: "workspace.ready", to: "updateDocumentation" },
+    { from: "workspace.blocked", to: "blocked" },
+    { from: "updateDocumentation", to: "verification" },
+    { from: "verification.ready", to: "finalize" },
+    { from: "verification.blocked", to: "blocked" },
   ],
 });
 

package/src/builtins/autoimplement-command-batches.ts

@@ -131,17 +131,10 @@ export function parseVerificationCommandPlan(value: unknown): VerificationComman
   if (!Array.isArray(result.commands) || result.commands.length === 0) {
     throw new Error("verification commands must be a non-empty array");
   }
-  const directories = new Set<string>();
   const commands = result.commands.map((entry, index) => {
     const command = parseCommandItem(entry, `verification commands[${index}]`, {
       maxTimeoutMs: VERIFICATION_TIMEOUT_MS,
     });
-    if (directories.has(command.cwd)) {
-      throw new Error(
-        `verification commands must use distinct working directories: ${command.cwd}`,
-      );
-    }
-    directories.add(command.cwd);
     validateVerificationCommand(command, index);
     return command;
   });
@@ -285,37 +278,50 @@ function parseCommandItem(
   return { id, command, args: [...raw.args] as string[], cwd, timeoutMs, maxOutputChars };
 }
 
-function validateVerificationCommand(command: CommandBatchItem, index: number): void {
-  const forbiddenCommands = new Set([
-    "ash",
-    "bash",
-    "cmd",
-    "cmd.exe",
-    "csh",
-    "dash",
-    "fish",
-    "gh",
-    "git",
-    "ksh",
-    "powershell",
-    "powershell.exe",
-    "pwsh",
-    "pwsh.exe",
-    "rm",
-    "sh",
-    "tcsh",
-    "zsh",
-  ]);
-  const executable = path.win32.basename(path.basename(command.command)).toLowerCase();
-  if (forbiddenCommands.has(executable)) {
-    throw new Error(`verification commands[${index}].command is not allowed`);
+const FORBIDDEN_VERIFICATION_EXECUTABLES = new Set([
+  "ash",
+  "bash",
+  "cmd",
+  "cmd.exe",
+  "csh",
+  "dash",
+  "fish",
+  "gh",
+  "git",
+  "ksh",
+  "powershell",
+  "powershell.exe",
+  "pwsh",
+  "pwsh.exe",
+  "rm",
+  "sh",
+  "tcsh",
+  "zsh",
+]);
+
+export function validateVerificationCommandSafety(
+  command: string,
+  args: readonly string[],
+  label: string,
+): void {
+  const executable = path.win32.basename(path.basename(command)).toLowerCase();
+  if (FORBIDDEN_VERIFICATION_EXECUTABLES.has(executable)) {
+    throw new Error(`${label}.command is not allowed`);
   }
-  const joined = command.args.join(" ").toLowerCase();
+  const joined = args.join(" ").toLowerCase();
   if (/\b(publish|release|deploy|push|merge)\b/.test(joined)) {
-    throw new Error(`verification commands[${index}] contains a mutation or publication action`);
+    throw new Error(`${label} contains a mutation or publication action`);
   }
 }
 
+function validateVerificationCommand(command: CommandBatchItem, index: number): void {
+  validateVerificationCommandSafety(
+    command.command,
+    command.args,
+    `verification commands[${index}]`,
+  );
+}
+
 function concurrencyValue(value: unknown, field: string): number {
   return positiveInteger(
     value,