@gtrabanco/pi-agentic-workflow 0.13.3 → 0.15.0

package/dist/conductor/sensor.js

@@ -0,0 +1,150 @@
+/**
+ * runSensor — spawn the workflow-status sensor, validate its output.
+ *
+ * Spawns `<bin> scripts/workflow-status.mjs --json-only` in `cwd`,
+ * collects stdout, parses JSON, validates against the envelope v2 strict
+ * schema, and checks for degradations.
+ *
+ * Any failure path (spawn error, non-JSON, invalid JSON, schema invalid,
+ * degradations present) returns `{ ok: false, refusal: "sensor-degraded", detail }`.
+ */
+import { spawn } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { validateEnvelope } from "@gtrabanco/agentic-workflow-schema";
+const TIMEOUT_MS = 30_000;
+function coerceEnvelope(raw) {
+    return raw;
+}
+function resolveCwd(cwd) {
+    try {
+        accessSync(cwd, constants.R_OK | constants.X_OK);
+        return cwd;
+    }
+    catch {
+        return process.cwd();
+    }
+}
+export function runSensor(cwd, bin) {
+    return new Promise((resolve) => {
+        const resolvedCwd = resolveCwd(cwd);
+        const child = spawn(bin, ["scripts/workflow-status.mjs", "--json-only"], {
+            cwd: resolvedCwd,
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: TIMEOUT_MS,
+        });
+        let stdout = "";
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        const timer = setTimeout(() => {
+            child.kill("SIGTERM");
+            resolve({
+                ok: false,
+                refusal: "sensor-degraded",
+                detail: "sensor timed out after 30s",
+            });
+        }, TIMEOUT_MS);
+        child.on("error", (_err) => {
+            clearTimeout(timer);
+            resolve({
+                ok: false,
+                refusal: "sensor-degraded",
+                detail: `spawn error: ${_err.message}`,
+            });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (code === null || code >= 128) {
+                resolve({
+                    ok: false,
+                    refusal: "sensor-degraded",
+                    detail: `process exited with code ${code ?? "unknown"}`,
+                });
+                return;
+            }
+            tryParseAndValidate(stdout, resolve);
+        });
+    });
+}
+function tryParseAndValidate(raw, resolve) {
+    // Parse contract: the real sensor emits bare JSON on stdout
+    // (`--json-only` is an accepted no-op); a fenced ```json block is
+    // accepted as a defensive fallback (the schema package's own
+    // extraction contract for skill turn output).
+    const candidate = parseJsonCandidate(raw);
+    if (candidate === null) {
+        resolve({
+            ok: false,
+            refusal: "sensor-degraded",
+            detail: "no JSON found in sensor output",
+        });
+        return;
+    }
+    // Validate the envelope object. The non-strict validator is the consumer
+    // contract here: the real sensor emits the documented additive fields
+    // (next.reason, next.candidate_count) that the fenced strict parser
+    // (skill-turn-output oriented) rejects.
+    const v2Result = validateEnvelope(candidate.parsed);
+    if (!v2Result.ok) {
+        resolve({
+            ok: false,
+            refusal: "sensor-degraded",
+            detail: `schema invalid: ${v2Result.errors.join("; ")}`,
+        });
+        return;
+    }
+    const envelope = candidate.parsed;
+    // Check for degradations in detail
+    const detail = envelope.detail;
+    if (detail?.degradations &&
+        Array.isArray(detail.degradations) &&
+        detail.degradations.length > 0) {
+        resolve({
+            ok: false,
+            refusal: "sensor-degraded",
+            detail: `sensor degraded: ${detail.degradations.join(", ")}`,
+        });
+        return;
+    }
+    resolve({ ok: true, envelope: coerceEnvelope(envelope) });
+}
+/**
+ * Parse sensor output: bare JSON first (the real `--json-only` contract),
+ * then the last fenced ```json block (defensive fallback matching the
+ * schema package's extraction contract). Returns null when neither parses.
+ */
+function parseJsonCandidate(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+        try {
+            return { parsed: JSON.parse(trimmed) };
+        }
+        catch {
+            // fall through to the fenced extraction
+        }
+    }
+    const block = extractLastJsonBlock(text);
+    if (block === null)
+        return null;
+    try {
+        return { parsed: JSON.parse(block) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Extract the last fenced ```json block from raw text.
+ * Matches the envelope parse contract used by the schema package.
+ */
+function extractLastJsonBlock(text) {
+    const match = text.match(/```json\s*([\s\S]*?)\s*```/g);
+    if (!match || match.length === 0)
+        return null;
+    // Take the last one
+    const last = match[match.length - 1];
+    return last
+        .replace(/^```json\s*/i, "")
+        .replace(/\s*```$/, "")
+        .trim();
+}

package/dist/conductor/snapshot.d.ts

@@ -0,0 +1,13 @@
+/**
+ * snapshotFromEnvelope — pure mapping from an Envelope v2 to a WorkflowSnapshot v1.
+ *
+ * The conductor builds its own lightweight snapshot from the envelope; it does
+ * NOT call compileWorkflowSnapshot (that's a separate concern).
+ */
+import type { WorkflowSnapshot } from "@gtrabanco/agentic-workflow-schema";
+import type { EnvelopeLike } from "./types.js";
+/**
+ * Map an Envelope v2 into a WorkflowSnapshot v1.
+ * Pure function — no I/O, no side effects.
+ */
+export declare function snapshotFromEnvelope(env: EnvelopeLike): WorkflowSnapshot;

package/dist/conductor/snapshot.js

@@ -0,0 +1,60 @@
+/**
+ * snapshotFromEnvelope — pure mapping from an Envelope v2 to a WorkflowSnapshot v1.
+ *
+ * The conductor builds its own lightweight snapshot from the envelope; it does
+ * NOT call compileWorkflowSnapshot (that's a separate concern).
+ */
+/**
+ * Map an Envelope v2 into a WorkflowSnapshot v1.
+ * Pure function — no I/O, no side effects.
+ */
+export function snapshotFromEnvelope(env) {
+    const detail = env.detail;
+    const rs = detail?.repository_state;
+    const status = String(rs?.status ?? "unknown");
+    const sourceRevision = rs?.source_revision ?? env.summary;
+    // Map unit
+    const unitLike = env.unit;
+    const unit = unitLike
+        ? {
+            kind: unitLike.type === "fix" ? "fix" : "feature",
+            id: unitLike.id ?? "",
+            status: "",
+        }
+        : null;
+    // Phase: current, total, completed; names not available from envelope
+    const phaseRaw = env.phase;
+    const phase = {
+        current: phaseRaw?.current ?? null,
+        total: phaseRaw?.total ?? null,
+        completed: phaseRaw?.completed ?? null,
+        names: [],
+    };
+    // Repository: branch from unit.branch, headSha from pr.head_sha or falls back
+    const pr = env.pr;
+    const branch = unitLike?.branch ?? "";
+    const headShaFromPr = pr?.head_sha;
+    const headSha = headShaFromPr ?? sourceRevision;
+    // dirty is always false from the envelope
+    const dirty = false;
+    // Detect contradictions from the envelope's repository_state
+    const contradictions = status === "contradicted"
+        ? [{ field: "repository_state", source: "workflow-status", line: 0, detail: "repository_state is contradicted" }]
+        : [];
+    // Detect unknowns from the envelope's repository_state
+    const unknowns = status === "unknown"
+        ? [{ field: "repository_state", reason: "repository_state is unknown" }]
+        : [];
+    return {
+        contract: "agentic-workflow/workflow-snapshot",
+        version: 1,
+        sourceRevision,
+        repository: { branch, headSha, dirty },
+        repositoryState: status,
+        unit,
+        phase,
+        provenance: [{ field: "envelope", source: "workflow-status", line: 0 }],
+        contradictions,
+        unknowns,
+    };
+}

package/dist/conductor/types.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Conductor types — configuration, sensor result, decision, and loop envelope.
+ *
+ * The conductor is a deterministic loop: sensor -> decide -> invoke -> repeat.
+ * Everything is pure data; no I/O lives in this module.
+ */
+/**
+ * Per-iteration control knobs for the conductor loop.
+ * All values are optional in the config file; the exported DEFAULT
+ * supplies the shipped defaults.
+ */
+export interface ConductorConfig {
+    /** Maximum loop iterations before a hard stop. */
+    iterationsCap?: number;
+    /** Path globs that should not be modified during the loop. */
+    sensitivePaths?: readonly string[];
+    /** Path globs that require extra scrutiny during the loop. */
+    securityPaths?: readonly string[];
+    /** Path to the run log file, relative to the project root. */
+    runLogPath?: string;
+}
+/**
+ * Shipped default conductor configuration.
+ * Deeply frozen so that merges always produce new objects.
+ */
+export declare const DEFAULT_CONDUCTOR_CONFIG: ConductorConfig;
+/**
+ * Merge two advance config files on top of the default.
+ * Known keys only — unknown keys are silently dropped.
+ * Returns a new object each call.
+ */
+export declare function mergeAdvanceConfig(globalFile?: ConductorConfig, projectFile?: ConductorConfig): ConductorConfig;
+/** Result returned by runSensor — success or refusal. */
+export type SensorResult = {
+    ok: true;
+    envelope: EnvelopeLike;
+} | {
+    ok: false;
+    refusal: "sensor-degraded";
+    detail: string;
+};
+/** Result of mapping a decision to an invocable command string. */
+export type InvocationResult = {
+    ok: true;
+    invocation: string;
+    adversarial?: number;
+} | {
+    ok: false;
+    refusal: "no-decision-available" | "precondition-uncheckable" | "rendering-failed";
+    detail?: string;
+};
+export type UrgencyVerdict = "no-urgent" | "interrupt-now" | "finish-first";
+export interface UrgencyResult {
+    verdict: UrgencyVerdict;
+    /** Issue number present only when verdict is not "no-urgent". */
+    issue?: number;
+    reason: string;
+}
+export interface LoopDeps {
+    runSensor: (cwd: string, bin: string) => Promise<SensorResult>;
+    decide: (input: {
+        envelope: EnvelopeLike;
+        lastOutcome: OutcomeLike | null;
+        lastOutcomeSourceRevision: string | null;
+        policy: PolicyLike;
+        reviewLoopCycles?: {
+            spec?: number;
+            plan?: number;
+        };
+    }) => ActionDecision;
+    invocation: (decision: ActionDecision, opts: InvocationOpts) => InvocationResult;
+    sendUserMessage: (invocation: string) => Promise<{
+        ok: boolean;
+    }>;
+    gitProbe: () => Promise<{
+        porcelain: string;
+        ahead: number;
+    }>;
+    appendRunLog: (line: string) => void;
+    config: ConductorConfig;
+    attended: boolean;
+    judgeUrgency: (envelope: EnvelopeLike) => UrgencyResult;
+    parkInFlight: () => Promise<void>;
+    /** Working directory the sensor runs in (defaults to process.cwd()). */
+    cwd?: string;
+    /** Runtime binary for the sensor spawn (defaults to "bun"). */
+    runtimeBin?: string;
+    /** Command names the invocation mapper accepts (defaults to the lane fallback set). */
+    commandNames?: Set<string>;
+    /** Decision policy forwarded to the decide step (defaults to the lane fallback). */
+    policy?: PolicyLike;
+    /** Stop after this many successful invocations (1 = one stage per invocation).
+     *  Unlimited when omitted (tests drive the full loop). */
+    maxInvokes?: number;
+}
+export interface LoopResult {
+    banner: string;
+    stopCode?: string;
+    detail?: string;
+    iterations: number;
+}
+export interface InvocationOpts {
+    commandNames: Set<string>;
+    attended: boolean;
+    sensitive?: boolean;
+    security?: boolean;
+    unitScope?: {
+        type: string;
+        id: string;
+    };
+    continuation?: {
+        preconditions?: ContinuationPrecondition[];
+    };
+}
+export interface ContinuationPrecondition {
+    id: string;
+    check: string;
+    satisfied: boolean;
+}
+export type CloseoutStatus = "clean" | "partial";
+/** Minimal envelope shape as seen by the conductor. */
+export interface EnvelopeLike {
+    skill: string;
+    state: string;
+    summary: string;
+    unit: {
+        type: string;
+        id: string | null;
+        issue: number | null;
+        branch: string | null;
+    } | null;
+    phase: {
+        current: string | null;
+        total: number | null;
+        completed: number | null;
+    };
+    pr: {
+        number: number | null;
+        url: string | null;
+        state: string;
+        head_sha: string | null;
+        merge_ready: boolean | null;
+        ci: string | null;
+    };
+    gates: {
+        verification: string | null;
+        review_pending: boolean | null;
+        audit_pending: boolean | null;
+    };
+    findings: {
+        fix_now: unknown[];
+        issues_filed: number[];
+        untriaged: number;
+        decisions_recorded: number;
+    };
+    blockers: unknown[];
+    dependencies: {
+        unmet: string[];
+        build_order: string[];
+    };
+    recommendations: {
+        product_audit: boolean;
+        reason: string | null;
+    };
+    needs_input: {
+        question: string;
+        options: string[];
+    } | null;
+    next: {
+        recommended: string;
+        alternatives: string[];
+        tier: string;
+        continuation?: {
+            argv: string[];
+            preconditions: ContinuationPrecondition[];
+            convergence: string;
+        };
+    };
+    detail: unknown;
+}
+/** Minimal outcome shape as seen by the conductor. */
+export interface OutcomeLike {
+    contract: string;
+    version: number;
+    skill: string;
+    status: string;
+    summary: string;
+    next: {
+        intent: string;
+        targets: string[];
+    };
+    blockers: unknown[];
+    questions: unknown[];
+    discoveries: unknown[];
+    evidence_refs: string[];
+}
+/** Minimal policy shape as seen by decide. */
+export interface PolicyLike {
+    allowedIntents: string[];
+    forgeWriteAuthorized: boolean;
+}
+/** Minimal action decision shape as returned by decide. */
+export interface ActionDecision {
+    kind: "invoke" | "sense" | "stop";
+    intent: string;
+    targets: string[];
+    reasonCode: string;
+    evidenceRefs: string[];
+    detail: string;
+}
+/** Minimal workflow snapshot shape. */
+export interface WorkflowSnapshotLike {
+    contract: string;
+    version: number;
+    sourceRevision: string;
+    repository: {
+        branch: string;
+        headSha: string;
+        dirty: boolean;
+    };
+    repositoryState: "missing" | "draft" | "frozen" | "contradicted" | "needs-input" | "unknown";
+    unit: {
+        kind: "feature" | "fix";
+        id: string;
+        status: string;
+    } | null;
+    phase: {
+        current: string | null;
+        total: number | null;
+        completed: number | null;
+        names: string[];
+    };
+    provenance: Array<{
+        field: string;
+        source: string;
+        line: number;
+    }>;
+    contradictions: Array<{
+        field: string;
+        source: string;
+        line: number;
+        detail: string;
+    }>;
+    unknowns: Array<{
+        field: string;
+        reason: string;
+    }>;
+}

package/dist/conductor/types.js

@@ -0,0 +1,47 @@
+/**
+ * Conductor types — configuration, sensor result, decision, and loop envelope.
+ *
+ * The conductor is a deterministic loop: sensor -> decide -> invoke -> repeat.
+ * Everything is pure data; no I/O lives in this module.
+ */
+/**
+ * Shipped default conductor configuration.
+ * Deeply frozen so that merges always produce new objects.
+ */
+export const DEFAULT_CONDUCTOR_CONFIG = Object.freeze({
+    iterationsCap: 12,
+    sensitivePaths: Object.freeze([]),
+    securityPaths: Object.freeze([]),
+    runLogPath: ".agentic-workflow/advance-run.log",
+});
+/**
+ * Merge two advance config files on top of the default.
+ * Known keys only — unknown keys are silently dropped.
+ * Returns a new object each call.
+ */
+export function mergeAdvanceConfig(globalFile = {}, projectFile = {}) {
+    const result = {
+        iterationsCap: DEFAULT_CONDUCTOR_CONFIG.iterationsCap,
+        sensitivePaths: globalFile.sensitivePaths?.slice() ?? [],
+        securityPaths: globalFile.securityPaths?.slice() ?? [],
+        runLogPath: DEFAULT_CONDUCTOR_CONFIG.runLogPath,
+    };
+    if (projectFile.iterationsCap !== undefined) {
+        result.iterationsCap = projectFile.iterationsCap;
+    }
+    if (projectFile.sensitivePaths !== undefined) {
+        result.sensitivePaths = projectFile.sensitivePaths.slice();
+    }
+    if (projectFile.securityPaths !== undefined) {
+        result.securityPaths = projectFile.securityPaths.slice();
+    }
+    if (projectFile.runLogPath !== undefined) {
+        result.runLogPath = projectFile.runLogPath;
+    }
+    return Object.freeze({
+        iterationsCap: result.iterationsCap,
+        sensitivePaths: Object.freeze(result.sensitivePaths ?? []),
+        securityPaths: Object.freeze(result.securityPaths ?? []),
+        runLogPath: result.runLogPath,
+    });
+}

package/dist/conductor/urgency.d.ts

@@ -0,0 +1,16 @@
+/**
+ * judgeUrgency > classify urgency from an envelope's urgent detail.
+ *
+ * Implements the five-row urgency table:
+ *   1. no urgent issues → no-urgent
+ *   2. fix-next label present → finish-first (queue head, never interrupt)
+ *   3. interruptibility.dirty === false → interrupt-now
+ *   4. tasks_from_boundary ≤ 1 → finish-first
+ *   5. else → finish-first (fail-safe: finish first, never interrupt mid-phase)
+ */
+import type { EnvelopeLike, UrgencyResult } from "./types.js";
+/**
+ * Classify urgency from an envelope's urgent detail.
+ * Pure function > no I/O, no side effects.
+ */
+export declare function judgeUrgency(env: EnvelopeLike): UrgencyResult;

package/dist/conductor/urgency.js

@@ -0,0 +1,70 @@
+/**
+ * judgeUrgency > classify urgency from an envelope's urgent detail.
+ *
+ * Implements the five-row urgency table:
+ *   1. no urgent issues → no-urgent
+ *   2. fix-next label present → finish-first (queue head, never interrupt)
+ *   3. interruptibility.dirty === false → interrupt-now
+ *   4. tasks_from_boundary ≤ 1 → finish-first
+ *   5. else → finish-first (fail-safe: finish first, never interrupt mid-phase)
+ */
+/**
+ * Classify urgency from an envelope's urgent detail.
+ * Pure function > no I/O, no side effects.
+ */
+export function judgeUrgency(env) {
+    const detail = env.detail;
+    const urgent = detail?.urgent;
+    if (!urgent) {
+        return { verdict: "no-urgent", reason: "no urgent detail found" };
+    }
+    const issues = urgent.issues ?? [];
+    const interruptibility = urgent.interruptibility;
+    // Row 1: no urgent issues → no-urgent
+    if (issues.length === 0) {
+        return { verdict: "no-urgent", reason: "no urgent issues present" };
+    }
+    // Pick the first issue (highest priority)
+    const firstIssue = issues[0];
+    const issueNumber = firstIssue.number;
+    // Row 2: fix-next label → finish-first (queue head, never interrupt)
+    const hasFixNext = issues.some((i) => i.label === "fix-next");
+    if (hasFixNext) {
+        return {
+            verdict: "finish-first",
+            issue: issueNumber,
+            reason: "fix-next issue in queue: finish current unit first, queue head priority",
+        };
+    }
+    // Fall through to interruptibility checks
+    if (interruptibility) {
+        // Row 3: dirty === false → interrupt-now
+        if (!interruptibility.dirty) {
+            return {
+                verdict: "interrupt-now",
+                issue: issueNumber,
+                reason: `unit ${interruptibility.unit} is not dirty > safe to interrupt`,
+            };
+        }
+        // Row 4: tasks_from_boundary ≤ 1 → finish-first
+        if (interruptibility.tasks_from_boundary <= 1) {
+            return {
+                verdict: "finish-first",
+                issue: issueNumber,
+                reason: "few tasks remaining (≤ 1) > finish first",
+            };
+        }
+        // Row 5: fail-safe finish-first (dirty, tasks > 1, no fix-next)
+        return {
+            verdict: "finish-first",
+            issue: issueNumber,
+            reason: "fail-safe: unit is dirty with multiple tasks remaining > finish first, never interrupt mid-phase",
+        };
+    }
+    // No interruptibility data → finish-first (fail-safe)
+    return {
+        verdict: "finish-first",
+        issue: issueNumber,
+        reason: "no interruptibility data available > finish first (fail-safe)",
+    };
+}

package/dist/config/merge.js

@@ -1,5 +1,6 @@
 import { DEFAULT_CONFIG, DEFAULT_ROUTE } from "./defaults.js";
 import { SHIPPED_PATH_POLICY, intersectPathPolicy, mergePathProtectionOverrides } from "./path-policy.js";
+import { DEFAULT_ADVANCE_CONFIG } from "./types.js";
 /**
  * Project-over-global merge (SPEC S5, S6).
  *
@@ -32,13 +33,32 @@ export function mergeConfigs(globalFile = {}, projectFile = {}) {
     for (const name of new Set([...Object.keys(globalCommands), ...Object.keys(projectCommands)])) {
         commands[name] = resolveRoute(effectiveDefault, globalCommands[name], projectCommands[name]);
     }
-    return {
+    const merged = {
         default: effectiveDefault,
         commands,
         onUnavailableRoute: projectFile.onUnavailableRoute ?? globalFile.onUnavailableRoute ?? DEFAULT_CONFIG.onUnavailableRoute,
         onSettle: projectFile.onSettle ?? globalFile.onSettle ?? DEFAULT_CONFIG.onSettle,
         pathProtection: intersectPathPolicy(SHIPPED_PATH_POLICY, mergePathProtectionOverrides(globalFile.pathProtection, projectFile.pathProtection)),
     };
+    // Advance knobs appear only when a scope declares them, so configs that
+    // predate feature 62 keep their exact resolved shape (no undefined key).
+    const advance = mergeAdvance(globalFile.advance, projectFile.advance);
+    if (advance !== undefined)
+        merged.advance = advance;
+    return merged;
+}
+/** Project-over-global merge of the advance (conductor) knobs (feature 62).
+ *  Absent from the result when neither scope declares any — the resolved
+ *  shape of pre-62 configs is byte-stable. */
+function mergeAdvance(global, project) {
+    if (global === undefined && project === undefined)
+        return undefined;
+    return {
+        iterationsCap: pick(DEFAULT_ADVANCE_CONFIG.iterationsCap, project?.iterationsCap, global?.iterationsCap),
+        sensitivePaths: project?.sensitivePaths ?? global?.sensitivePaths ?? [...DEFAULT_ADVANCE_CONFIG.sensitivePaths],
+        securityPaths: project?.securityPaths ?? global?.securityPaths ?? [...DEFAULT_ADVANCE_CONFIG.securityPaths],
+        runLogPath: pick(DEFAULT_ADVANCE_CONFIG.runLogPath, project?.runLogPath, global?.runLogPath),
+    };
 }
 /** The route a command runs under: its own resolved override, else the default route. */
 export function effectiveRoute(config, command) {