@osolmaz/pi-workflows 0.10.0 → 0.11.1

package/dist/builtins/autoimplement.workflow.js

@@ -1,8 +1,14 @@
 import path from "node:path";
 import { agent, compute, defineWorkflow, includeWorkflow, includedResult, shell, } from "../workflows/definition.js";
-import autodeviseWorkflow, {} from "./autodevise.workflow.js";
+import { digest } from "../workflows/human-decision.js";
+import autodocWorkflow, {} from "./autodoc.workflow.js";
+import autoplanWorkflow, {} from "./autoplan.workflow.js";
+import planApprovalWorkflow, {} from "./plan-approval.workflow.js";
 const FIVE_MINUTES_MS = 5 * 60_000;
 const TEN_MINUTES_MS = 10 * 60_000;
+const MAX_BLOCKER_CHALLENGES = 3;
+const MAX_CHALLENGE_ITEMS = 5;
+const MAX_CHALLENGE_TEXT = 500;
 function requireRecord(value, label) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         throw new Error(`${label} must be an object`);
@@ -15,6 +21,68 @@ function requireString(value, label) {
     }
     return value.trim();
 }
+function boundedChallengeItems(value, label) {
+    if (!Array.isArray(value) || value.length > MAX_CHALLENGE_ITEMS) {
+        throw new Error(`${label} must be an array with at most ${MAX_CHALLENGE_ITEMS} items`);
+    }
+    return value.map((item, index) => {
+        const text = requireString(item, `${label}[${index}]`);
+        if (text.length > MAX_CHALLENGE_TEXT) {
+            throw new Error(`${label}[${index}] must be at most ${MAX_CHALLENGE_TEXT} characters`);
+        }
+        return text;
+    });
+}
+function parseBlockerChallenge(value) {
+    const result = requireRecord(value, "blocker challenge");
+    if (result.route !== "continue" && result.route !== "blocked") {
+        throw new Error("blocker challenge route must be continue or blocked");
+    }
+    for (const key of ["blockingNow", "outsideAuthority", "canProceed"]) {
+        if (typeof result[key] !== "boolean") {
+            throw new Error(`blocker challenge ${key} must be a boolean`);
+        }
+    }
+    const blockingNow = result.blockingNow;
+    const outsideAuthority = result.outsideAuthority;
+    const canProceed = result.canProceed;
+    const reason = requireString(result.reason, "blocker challenge reason");
+    if (reason.length > MAX_CHALLENGE_TEXT) {
+        throw new Error(`blocker challenge reason must be at most ${MAX_CHALLENGE_TEXT} characters`);
+    }
+    if (typeof result.nextAction !== "string") {
+        throw new Error("blocker challenge nextAction must be a string");
+    }
+    const nextAction = result.nextAction.trim();
+    if (nextAction.length > MAX_CHALLENGE_TEXT) {
+        throw new Error(`blocker challenge nextAction must be at most ${MAX_CHALLENGE_TEXT} characters`);
+    }
+    const alternativesChecked = boundedChallengeItems(result.alternativesChecked, "blocker challenge alternativesChecked");
+    const evidence = boundedChallengeItems(result.evidence, "blocker challenge evidence");
+    if (result.route === "blocked") {
+        if (blockingNow !== true ||
+            outsideAuthority !== true ||
+            canProceed !== false ||
+            nextAction.length > 0 ||
+            alternativesChecked.length === 0 ||
+            evidence.length === 0) {
+            throw new Error("blocked challenge requires blockingNow=true, outsideAuthority=true, canProceed=false, an empty nextAction, and concrete alternatives and evidence");
+        }
+    }
+    else if (canProceed !== true || nextAction.length === 0) {
+        throw new Error("continue challenge requires canProceed=true and a practical nextAction");
+    }
+    return {
+        route: result.route,
+        blockingNow,
+        outsideAuthority,
+        canProceed,
+        reason,
+        nextAction,
+        alternativesChecked,
+        evidence,
+    };
+}
 function parseInput(value) {
     const input = requireRecord(value, "autoimplement input");
     const constraints = input.constraints;
@@ -25,6 +93,47 @@ function parseInput(value) {
     if (input.merge !== undefined && typeof input.merge !== "boolean") {
         throw new Error("autoimplement merge must be a boolean");
     }
+    const documents = input.documents;
+    if (documents !== undefined &&
+        (!Array.isArray(documents) || documents.some((item) => typeof item !== "string"))) {
+        throw new Error("autoimplement documents must be an array of strings");
+    }
+    let documentation;
+    if (input.documentation !== undefined) {
+        if (input.plan === undefined) {
+            throw new Error("autoimplement documentation requires an explicit plan");
+        }
+        const raw = requireRecord(input.documentation, "autoimplement documentation");
+        if (raw.status !== "current") {
+            throw new Error("autoimplement documentation status must be current");
+        }
+        const planDigest = requireString(raw.planDigest, "autoimplement documentation planDigest");
+        if (planDigest !== digest(input.plan)) {
+            throw new Error("autoimplement documentation planDigest does not match the explicit plan");
+        }
+        if (!Array.isArray(raw.documents) || raw.documents.some((item) => typeof item !== "string")) {
+            throw new Error("autoimplement documentation documents must be an array of strings");
+        }
+        documentation = {
+            status: "current",
+            planDigest,
+            documents: [...raw.documents],
+        };
+    }
+    let approval;
+    if (input.approval !== undefined) {
+        const raw = requireRecord(input.approval, "autoimplement approval");
+        const maxReplans = raw.maxReplans ?? 3;
+        if (!Number.isInteger(maxReplans) ||
+            maxReplans < 1 ||
+            maxReplans > 20) {
+            throw new Error("autoimplement approval maxReplans must be from 1 through 20");
+        }
+        approval = {
+            audience: requireString(raw.audience, "autoimplement approval audience"),
+            maxReplans: maxReplans,
+        };
+    }
     return {
         task: requireString(input.task, "autoimplement task"),
         ...(input.plan !== undefined ? { plan: input.plan } : {}),
@@ -37,6 +146,38 @@ function parseInput(value) {
             ? { baseBranch: requireString(input.baseBranch, "baseBranch") }
             : {}),
         merge: input.merge === true,
+        ...(documents !== undefined ? { documents: [...documents] } : {}),
+        ...(documentation !== undefined ? { documentation } : {}),
+        ...(approval !== undefined ? { approval } : {}),
+    };
+}
+function parseExistingPlan(value) {
+    const result = requireRecord(value, "existing plan discovery");
+    if (result.route !== "found" && result.route !== "blocked") {
+        throw new Error("existing plan discovery route must be found or blocked");
+    }
+    if (result.route === "found") {
+        if (result.plan === undefined)
+            throw new Error("found plan must include plan");
+        if (result.documentation !== "current" &&
+            result.documentation !== "missing" &&
+            result.documentation !== "stale") {
+            throw new Error("found plan documentation must be current, missing, or stale");
+        }
+    }
+    if (!Array.isArray(result.documents) ||
+        result.documents.some((item) => typeof item !== "string")) {
+        throw new Error("existing plan documents must be an array of strings");
+    }
+    return {
+        route: result.route,
+        ...(result.plan !== undefined ? { plan: result.plan } : {}),
+        ...(result.documentation !== undefined
+            ? { documentation: result.documentation }
+            : {}),
+        documents: [...result.documents],
+        reason: requireString(result.reason, "existing plan discovery reason"),
+        evidence: result.evidence ?? null,
     };
 }
 function parseRoute(value, routes, label) {
@@ -124,10 +265,73 @@ function latestCiCommand(context) {
 }
 function currentPlan(context) {
     const adopted = context.outputs.adoptPlan;
-    return adopted?.plan ?? context.input.plan;
+    if (adopted?.plan !== undefined)
+        return adopted.plan;
+    const documented = context.outputs.documentation;
+    if (documented?.exit === "ready" && documented.output?.plan !== undefined) {
+        return documented.output.plan;
+    }
+    const discovered = context.outputs.findPlan;
+    if (discovered?.route === "found" && discovered.plan !== undefined)
+        return discovered.plan;
+    return context.input.plan;
+}
+function currentPlanDigest(context) {
+    const adopted = context.outputs.adoptPlan;
+    if (typeof adopted?.planDigest === "string")
+        return adopted.planDigest;
+    const documented = context.outputs.documentation;
+    if (documented?.exit === "ready" && typeof documented.output?.planDigest === "string") {
+        return documented.output.planDigest;
+    }
+    const plan = currentPlan(context);
+    if (plan === undefined)
+        throw new Error("autoimplement does not have a selected plan");
+    return digest(plan);
+}
+function blockerChallenges(context) {
+    return context.state.steps
+        .filter((step) => step.nodeId === "challengeBlocker" && step.outcome === "ok")
+        .map((step) => step.output);
+}
+function latestBlockerClaim(context) {
+    const ids = [
+        "classifyImplementation",
+        "classifyVerification",
+        "repairReviewCommand",
+        "inspectComments",
+        "inspectCi",
+        "repairCiCommand",
+        "assessTrackedCi",
+        "classifyCi",
+        "finalizeDelivery",
+    ];
+    for (let index = context.state.steps.length - 1; index >= 0; index -= 1) {
+        const step = context.state.steps[index];
+        if (step && ids.includes(step.nodeId)) {
+            return { source: step.nodeId, result: step.output };
+        }
+    }
+    throw new Error("No model-generated blocker claim is available to challenge");
+}
+function recentWorkflowAttempts(context) {
+    return context.state.steps.slice(-12).map((step) => ({
+        nodeId: step.nodeId,
+        outcome: step.outcome,
+        output: step.output,
+    }));
 }
 function latestIssue(context) {
+    const approval = context.outputs.approval;
+    if (approval?.exit === "replan" && typeof approval.output?.instructions === "string") {
+        return {
+            source: "human-replan",
+            instructions: approval.output.instructions,
+            priorPlanDigest: currentPlanDigest(context),
+        };
+    }
     const ids = [
+        "challengeBlocker",
         "classifyImplementation",
         "classifyVerification",
         "triageReview",
@@ -190,6 +394,8 @@ function reviewRounds(context) {
 }
 function latestBlockedReason(context) {
     const candidates = [
+        "challengeBlockerGuard",
+        "challengeBlocker",
         "finalizeDelivery",
         "inspectCi",
         "assessTrackedCi",
@@ -198,7 +404,11 @@ function latestBlockedReason(context) {
         "classifyImplementation",
         "classifyVerification",
         "triageReview",
+        "replanGuard",
         "adoptPlan",
+        "findPlan",
+        "documentation",
+        "approval",
     ];
     for (let index = context.state.steps.length - 1; index >= 0; index -= 1) {
         const step = context.state.steps[index];
@@ -222,11 +432,46 @@ export const autoimplementWorkflow = defineWorkflow({
     title: ({ input }) => `autoimplement: ${input.task.slice(0, 60)}`,
     presentationPrompt: "Summarize what was implemented, the review rounds by severity, the CI result, the PR or merge result, and any remaining limitation. Include exact validation commands.",
     startAt: "prepare",
-    maxSteps: 160,
+    maxSteps: 240,
     includes: {
+        documentation: includeWorkflow(autodocWorkflow, {
+            input: (context) => {
+                const request = context.input;
+                const discovery = context.outputs.findPlan;
+                const plan = currentPlan(context);
+                if (plan === undefined)
+                    throw new Error("autoimplement documentation is missing a plan");
+                return {
+                    task: request.task,
+                    plan,
+                    ...(request.repository !== undefined ? { repository: request.repository } : {}),
+                    documents: request.documents ?? request.documentation?.documents ?? discovery?.documents ?? [],
+                    evidence: latestIssue(context),
+                };
+            },
+        }),
+        approval: includeWorkflow(planApprovalWorkflow, {
+            input: (context) => {
+                const request = context.input;
+                if (request.approval === undefined) {
+                    throw new Error("autoimplement approval was entered without an approval policy");
+                }
+                const plan = currentPlan(context);
+                if (plan === undefined)
+                    throw new Error("autoimplement approval is missing a plan");
+                const revisions = context.state.steps.filter((step) => step.nodeId === "approval/approve").length;
+                return {
+                    task: request.task,
+                    plan,
+                    planDigest: currentPlanDigest(context),
+                    audience: request.approval.audience,
+                    revision: revisions + 1,
+                };
+            },
+        }),
         redesign: includeWorkflow({
-            workflow: "autodevise",
-            contract: autodeviseWorkflow,
+            workflow: "autoplan",
+            contract: autoplanWorkflow,
             input: (context) => {
                 const request = context.input;
                 return {
@@ -251,26 +496,84 @@ export const autoimplementWorkflow = defineWorkflow({
     },
     nodes: {
         prepare: compute({
-            run: ({ input }) => ({
-                route: input.plan === undefined ? "redesign" : "implement",
-            }),
+            run: ({ input }) => {
+                const request = input;
+                return {
+                    route: request.plan === undefined
+                        ? "find"
+                        : request.documentation?.status === "current"
+                            ? "ready"
+                            : "document",
+                };
+            },
+        }),
+        findPlan: agent({
+            statusDetail: "finding existing plan",
+            prompt: ({ input }) => {
+                const request = input;
+                return [
+                    "Find the clear plan that has already been selected for this task.",
+                    "Use the current conversation context and referenced canonical documents.",
+                    "Do not devise, improve, replace, document, or implement a plan.",
+                    "Return blocked when no single clear existing plan can be found.",
+                    "Report whether its canonical documentation is current, missing, or stale.",
+                    `Task: ${request.task}`,
+                    `Repository: ${request.repository ?? "current repository"}`,
+                    `Referenced documents: ${JSON.stringify(request.documents ?? [])}`,
+                ].join("\n");
+            },
+            expectedOutput: '{ "route": "found" | "blocked", "plan": {} (required when found), "documentation": "current" | "missing" | "stale" (required when found), "documents": ["canonical file"], "reason": "reason", "evidence": "evidence" }',
+            validate: parseExistingPlan,
+        }),
+        routeFoundPlan: compute({
+            run: ({ outputs }) => {
+                const discovered = outputs.findPlan;
+                if (discovered.route !== "found" || discovered.plan === undefined) {
+                    return { route: "blocked", reason: discovered.reason, evidence: discovered.evidence };
+                }
+                return {
+                    route: discovered.documentation === "current" ? "ready" : "document",
+                    plan: discovered.plan,
+                    reason: discovered.reason,
+                    evidence: discovered.evidence,
+                };
+            },
         }),
         adoptPlan: compute({
             run: ({ outputs }) => {
-                const result = includedResult(autodeviseWorkflow, outputs.redesign);
+                const result = includedResult(autoplanWorkflow, outputs.redesign);
                 if (result.exit !== "ready")
                     throw new Error("redesign did not return a ready plan");
                 return {
-                    route: result.output.changed ? "implement" : "blocked",
+                    route: result.output.changed ? "document" : "blocked",
                     plan: result.output.plan,
                     planDigest: result.output.planDigest,
                     changed: result.output.changed,
                     reason: result.output.changed
-                        ? "The plan changed in response to new evidence."
+                        ? "The plan changed in response to new evidence and must be documented."
                         : "Redesign returned the same plan for the same unresolved evidence.",
                 };
             },
         }),
+        maybeApproval: compute({
+            run: ({ input }) => ({
+                route: input.approval === undefined ? "implement" : "approve",
+            }),
+        }),
+        replanGuard: compute({
+            run: (context) => {
+                const request = context.input;
+                const limit = request.approval?.maxReplans ?? 3;
+                const replans = context.state.steps.filter((step) => step.nodeId === "approval/replan").length;
+                return replans > limit
+                    ? {
+                        route: "blocked",
+                        reason: `Plan approval reached the ${limit}-replan safety limit.`,
+                        evidence: context.outputs.approval,
+                    }
+                    : { route: "redesign", replans, limit };
+            },
+        }),
         implement: agent({
             timeoutMs: 60 * 60_000,
             statusDetail: "implementing",
@@ -279,6 +582,8 @@ export const autoimplementWorkflow = defineWorkflow({
                 return [
                     `Implement this task end-to-end: ${request.task}`,
                     `Plan: ${JSON.stringify(currentPlan(context))}`,
+                    `Authorized scope: ${request.scope ?? request.repository ?? "the current repository and task"}`,
+                    `Constraints: ${JSON.stringify(request.constraints ?? [])}`,
                     "Follow repository instructions and use the most elegant long-term production-ready implementation without unnecessary work.",
                     "If implementation exposes a new design or scope problem, report it precisely instead of forcing the old plan.",
                     "Do not merge yet.",
@@ -300,6 +605,51 @@ export const autoimplementWorkflow = defineWorkflow({
             expectedOutput: `{ "route": "verify" | "redesign" | "fix" | "blocked", "summary": "reason", "evidence": "evidence" }`,
             validate: (value) => parseRoute(value, ["verify", "redesign", "fix", "blocked"], "implementation assessment"),
         }),
+        challengeBlockerGuard: compute({
+            run: (context) => {
+                const challenges = blockerChallenges(context);
+                return challenges.length >= MAX_BLOCKER_CHALLENGES
+                    ? {
+                        route: "blocked",
+                        reason: `Blocker challenge reached the ${MAX_BLOCKER_CHALLENGES}-attempt workflow safety limit.`,
+                        evidence: { attempts: challenges.length, challenges },
+                    }
+                    : {
+                        route: "challenge",
+                        attempt: challenges.length + 1,
+                        limit: MAX_BLOCKER_CHALLENGES,
+                    };
+            },
+        }),
+        challengeBlocker: agent({
+            statusDetail: "challenging blocker claim",
+            prompt: (context) => {
+                const request = context.input;
+                return [
+                    "Independently challenge the latest claim that autoimplement is blocked.",
+                    "Are you really blocked?",
+                    "Is this really a blocker right now?",
+                    "Can you find a safe way to move forward and finish this?",
+                    "Are you getting stuck on something trivial, procedural, reversible, or already authorized?",
+                    "Inspect the task, approved plan, current result, evidence, scope, authority, previous attempts, and viable alternatives.",
+                    "Distinguish a true external blocker from ordinary rollout work, local implementation work, a design adjustment, a missing verification step, or a reversible operational task.",
+                    "A local test failure, stale package, packaging or artifact mismatch, rollback preparation, or deployment procedure is not by itself outside authority.",
+                    "If a safe deployment and rollback path is already authorized, a supported cutover is work to do, not a blocker.",
+                    "Confirm blocked only when the issue blocks progress now, is outside authority, and has no safe practical path forward.",
+                    "Return continue with the next practical action when work can proceed. Keep text concise, with at most five alternatives and five evidence items.",
+                    `Task: ${request.task}`,
+                    `Approved plan: ${JSON.stringify(currentPlan(context))}`,
+                    `Current result and claimed blocker: ${JSON.stringify(latestBlockerClaim(context))}`,
+                    `Authorized scope: ${request.scope ?? request.repository ?? "the current repository and task"}`,
+                    `Constraints and authority: ${JSON.stringify(request.constraints ?? [])}`,
+                    `Merge authorized: ${request.merge === true}`,
+                    `Previous blocker challenges: ${JSON.stringify(blockerChallenges(context))}`,
+                    `Recent workflow attempts: ${JSON.stringify(recentWorkflowAttempts(context))}`,
+                ].join("\n");
+            },
+            expectedOutput: `{ "route": "continue" | "blocked", "blockingNow": true | false, "outsideAuthority": true | false, "canProceed": true | false, "reason": "concise reason", "nextAction": "practical action or empty when blocked", "alternativesChecked": ["checked alternative"], "evidence": ["concrete evidence"] }`,
+            validate: parseBlockerChallenge,
+        }),
         verify: agent({
             timeoutMs: 45 * 60_000,
             statusDetail: "verifying",
@@ -601,28 +951,73 @@ export const autoimplementWorkflow = defineWorkflow({
     edges: [
         {
             from: "prepare",
-            switch: { on: "$.route", cases: { redesign: "redesign", implement: "implement" } },
+            switch: {
+                on: "$.route",
+                cases: { find: "findPlan", document: "documentation", ready: "maybeApproval" },
+            },
+        },
+        {
+            from: "findPlan",
+            switch: { on: "$.route", cases: { found: "routeFoundPlan", blocked: "blocked" } },
+        },
+        {
+            from: "routeFoundPlan",
+            switch: {
+                on: "$.route",
+                cases: { ready: "maybeApproval", document: "documentation", blocked: "blocked" },
+            },
         },
         { from: "redesign.ready", to: "adoptPlan" },
         { from: "redesign.blocked", to: "blocked" },
         {
             from: "adoptPlan",
-            switch: { on: "$.route", cases: { implement: "implement", blocked: "blocked" } },
+            switch: { on: "$.route", cases: { document: "documentation", blocked: "blocked" } },
+        },
+        { from: "documentation.ready", to: "maybeApproval" },
+        { from: "documentation.blocked", to: "blocked" },
+        {
+            from: "maybeApproval",
+            switch: { on: "$.route", cases: { approve: "approval", implement: "implement" } },
+        },
+        { from: "approval.continue", to: "implement" },
+        { from: "approval.stop", to: "blocked" },
+        { from: "approval.replan", to: "replanGuard" },
+        {
+            from: "replanGuard",
+            switch: { on: "$.route", cases: { redesign: "redesign", blocked: "blocked" } },
         },
         { from: "implement", to: "classifyImplementation" },
         {
             from: "classifyImplementation",
             switch: {
                 on: "$.route",
-                cases: { verify: "verify", redesign: "redesign", fix: "fix", blocked: "blocked" },
+                cases: {
+                    verify: "verify",
+                    redesign: "redesign",
+                    fix: "fix",
+                    blocked: "challengeBlockerGuard",
+                },
             },
         },
+        {
+            from: "challengeBlockerGuard",
+            switch: { on: "$.route", cases: { challenge: "challengeBlocker", blocked: "blocked" } },
+        },
+        {
+            from: "challengeBlocker",
+            switch: { on: "$.route", cases: { continue: "redesign", blocked: "blocked" } },
+        },
         { from: "verify", to: "classifyVerification" },
         {
             from: "classifyVerification",
             switch: {
                 on: "$.route",
-                cases: { publish: "publish", redesign: "redesign", fix: "fix", blocked: "blocked" },
+                cases: {
+                    publish: "publish",
+                    redesign: "redesign",
+                    fix: "fix",
+                    blocked: "challengeBlockerGuard",
+                },
             },
         },
         { from: "fix", to: "verify" },
@@ -641,7 +1036,10 @@ export const autoimplementWorkflow = defineWorkflow({
         },
         {
             from: "repairReviewCommand",
-            switch: { on: "$.route", cases: { retry: "runReview", blocked: "blocked" } },
+            switch: {
+                on: "$.route",
+                cases: { retry: "runReview", blocked: "challengeBlockerGuard" },
+            },
         },
         {
             from: "assessReview",
@@ -668,7 +1066,12 @@ export const autoimplementWorkflow = defineWorkflow({
             from: "inspectComments",
             switch: {
                 on: "$.route",
-                cases: { redesign: "redesign", fix: "fix", ci: "inspectCi", blocked: "blocked" },
+                cases: {
+                    redesign: "redesign",
+                    fix: "fix",
+                    ci: "inspectCi",
+                    blocked: "challengeBlockerGuard",
+                },
             },
         },
         {
@@ -679,7 +1082,7 @@ export const autoimplementWorkflow = defineWorkflow({
                     green: "finalizeDelivery",
                     failed: "classifyCi",
                     pending: "trackCi",
-                    unavailable: "blocked",
+                    unavailable: "challengeBlockerGuard",
                 },
             },
         },
@@ -692,7 +1095,10 @@ export const autoimplementWorkflow = defineWorkflow({
         },
         {
             from: "repairCiCommand",
-            switch: { on: "$.route", cases: { retry: "trackCi", blocked: "blocked" } },
+            switch: {
+                on: "$.route",
+                cases: { retry: "trackCi", blocked: "challengeBlockerGuard" },
+            },
         },
         {
             from: "assessTrackedCi",
@@ -702,7 +1108,7 @@ export const autoimplementWorkflow = defineWorkflow({
                     green: "finalizeDelivery",
                     failed: "classifyCi",
                     pending: "opportunisticTest",
-                    unavailable: "blocked",
+                    unavailable: "challengeBlockerGuard",
                 },
             },
         },
@@ -715,13 +1121,16 @@ export const autoimplementWorkflow = defineWorkflow({
                     redesign: "redesign",
                     fix: "fix",
                     unrelated: "finalizeDelivery",
-                    blocked: "blocked",
+                    blocked: "challengeBlockerGuard",
                 },
             },
         },
         {
             from: "finalizeDelivery",
-            switch: { on: "$.status", cases: { completed: "finalize", blocked: "blocked" } },
+            switch: {
+                on: "$.status",
+                cases: { completed: "finalize", blocked: "challengeBlockerGuard" },
+            },
         },
     ],
 });