@gtrabanco/pi-agentic-workflow 0.13.3 → 0.15.0

package/dist/config/schema.js

@@ -9,7 +9,7 @@ import { OPERATIONS, PATH_GLOB_MAX_LENGTH, PHASE_STATES, REQUIREMENTS } from "./
  * strong model ran when it did not. Only a *missing* file resolves to the
  * default, and that decision belongs to the loader.
  */
-const ROOT_KEYS = new Set(["default", "commands", "onUnavailableRoute", "onSettle", "pathProtection"]);
+const ROOT_KEYS = new Set(["default", "commands", "onUnavailableRoute", "onSettle", "pathProtection", "advance"]);
 const ROUTE_KEYS = new Set(["model", "thinking"]);
 const COMMAND_NAME = /^[a-z0-9][a-z0-9._-]*$/u;
 function isRecord(value) {
@@ -41,6 +41,44 @@ function isUnavailableRoutePolicy(value) {
 function isSettlePolicy(value) {
     return SETTLE_POLICIES.includes(value);
 }
+/** Strict validator for the optional `advance` conductor config (feature 62). */
+const ADVANCE_KEYS = new Set(["iterationsCap", "sensitivePaths", "securityPaths", "runLogPath"]);
+function checkAdvance(value, path, issues) {
+    if (!isRecord(value)) {
+        issues.push({ path, message: "must be an object" });
+        return undefined;
+    }
+    const out = {};
+    for (const key of Object.keys(value)) {
+        if (!ADVANCE_KEYS.has(key)) {
+            issues.push({ path: `${path}.${displayKey(key)}`, message: `unknown advance key "${key}" (allowed: iterationsCap, sensitivePaths, securityPaths, runLogPath)` });
+            continue;
+        }
+        const v = value[key];
+        if (key === "iterationsCap") {
+            if (typeof v !== "number" || !Number.isInteger(v) || v < 1) {
+                issues.push({ path: `${path}.iterationsCap`, message: "must be a positive integer" });
+                continue;
+            }
+            out.iterationsCap = v;
+        }
+        else if (key === "runLogPath") {
+            if (typeof v !== "string" || v.length === 0) {
+                issues.push({ path: `${path}.runLogPath`, message: "must be a non-empty string" });
+                continue;
+            }
+            out.runLogPath = v;
+        }
+        else {
+            if (!Array.isArray(v) || v.some((e) => typeof e !== "string")) {
+                issues.push({ path: `${path}.${key}`, message: "must be an array of strings" });
+                continue;
+            }
+            out[key] = v;
+        }
+    }
+    return out;
+}
 /** Strict validator for the optional `pathProtection` override (feature 60, AC10). */
 function checkPathProtection(value, path, issues) {
     if (!isRecord(value)) {
@@ -176,7 +214,7 @@ function validateConfig(value) {
         if (!ROOT_KEYS.has(key)) {
             issues.push({
                 path: `$.${displayKey(key)}`,
-                message: `unknown config key "${key}" (allowed: default, commands, onUnavailableRoute, onSettle, pathProtection)`,
+                message: `unknown config key "${key}" (allowed: default, commands, onUnavailableRoute, onSettle, pathProtection, advance)`,
             });
         }
     }
@@ -225,6 +263,11 @@ function validateConfig(value) {
             config.onSettle = value.onSettle;
         }
     }
+    if (value.advance !== undefined) {
+        const advance = checkAdvance(value.advance, "$.advance", issues);
+        if (advance)
+            config.advance = advance;
+    }
     if (value.pathProtection !== undefined) {
         const override = checkPathProtection(value.pathProtection, "$.pathProtection", issues);
         if (override)

package/dist/config/types.d.ts

@@ -42,6 +42,8 @@ export interface ConfigFile {
     onSettle?: SettlePolicy;
     /** The tighten-only path-protection override (feature 60, AC10). */
     pathProtection?: PathProtectionOverride;
+    /** Conductor (advance) knobs (feature 62). */
+    advance?: AdvanceConfigFile;
 }
 export type UnavailableRoutePolicy = "stop" | "inherit";
 /**
@@ -65,6 +67,10 @@ export interface EffectiveConfig {
     onSettle: SettlePolicy;
     /** The effective path-protection policy: the shipped floor tightened by any override. */
     pathProtection: ResolvedPathPolicy;
+    /** The effective advance (conductor) knobs (feature 62). Resolved by
+     *  mergeConfigs; the shipped DEFAULT_CONFIG predates it and leaves it
+     *  absent — consumers fall back to DEFAULT_ADVANCE_CONFIG. */
+    advance?: AdvanceConfig;
 }
 export interface ConfigProblem {
     scope: "global" | "project";
@@ -76,3 +82,19 @@ export interface ConfigPaths {
     global: string;
     project: string;
 }
+/** Per-iteration control knobs for the conductor loop. */
+export interface AdvanceConfigFile {
+    iterationsCap?: number;
+    sensitivePaths?: string[];
+    securityPaths?: string[];
+    runLogPath?: string;
+}
+/** Effective advance configuration with all fields resolved. */
+export interface AdvanceConfig {
+    iterationsCap: number;
+    sensitivePaths: string[];
+    securityPaths: string[];
+    runLogPath: string;
+}
+/** The shipped advance defaults (mirrors conductor DEFAULT_CONDUCTOR_CONFIG). */
+export declare const DEFAULT_ADVANCE_CONFIG: Readonly<AdvanceConfig>;

package/dist/config/types.js

@@ -13,3 +13,10 @@ export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhig
 export const MAX_MODEL_CHAIN = 4;
 export const UNAVAILABLE_ROUTE_POLICIES = ["stop", "inherit"];
 export const SETTLE_POLICIES = ["keep", "restore"];
+/** The shipped advance defaults (mirrors conductor DEFAULT_CONDUCTOR_CONFIG). */
+export const DEFAULT_ADVANCE_CONFIG = {
+    iterationsCap: 12,
+    sensitivePaths: [],
+    securityPaths: [],
+    runLogPath: ".agentic-workflow/advance-run.log",
+};

package/dist/extension/conductor-command.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The native `advance` command wiring (feature 62).
+ *
+ * Bridges the pi-free conductor loop to a live session: real sensor spawn,
+ * real git probes, real run-log writes, real WIP-commit parking. One stage
+ * per invocation by default — the invoked skill must settle before the next
+ * sensor run can observe its effect — with `--continue` running the bounded
+ * full loop. `--fullauto`/`--unattended` switch the unattended adversarial
+ * floor on. The conductor never merges (feature 20 merge authority).
+ */
+import type { LoadedConfig } from "../config/load.js";
+import type { CommandRegistrar } from "./factory.js";
+import type { InvocationContext, ModelRef } from "../routing/types.js";
+/** Register the native `advance` command on the shared registrar. */
+export declare function registerAdvanceCommand<M extends ModelRef = ModelRef>(registrar: CommandRegistrar<M>, deps: {
+    surface: (ctx: InvocationContext<M>) => {
+        sendUserMessage(content: string, options?: {
+            expandPromptTemplates?: boolean;
+        }): void;
+    };
+    /** The same bound config reader the router uses (factory's `read`). */
+    readConfig: (ctx: InvocationContext<M>) => LoadedConfig;
+}, commandNames: Set<string>): void;

package/dist/extension/conductor-command.js

@@ -0,0 +1,93 @@
+/**
+ * The native `advance` command wiring (feature 62).
+ *
+ * Bridges the pi-free conductor loop to a live session: real sensor spawn,
+ * real git probes, real run-log writes, real WIP-commit parking. One stage
+ * per invocation by default — the invoked skill must settle before the next
+ * sensor run can observe its effect — with `--continue` running the bounded
+ * full loop. `--fullauto`/`--unattended` switch the unattended adversarial
+ * floor on. The conductor never merges (feature 20 merge authority).
+ */
+import { execFile } from "node:child_process";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { DEFAULT_ADVANCE_CONFIG } from "../config/types.js";
+import { runtimeBin } from "../runtime.js";
+import { runConductorLoop } from "../conductor/loop.js";
+import { decideFromEnvelope } from "../conductor/decide.js";
+import { invocationFromDecision } from "../conductor/invoke.js";
+import { judgeUrgency } from "../conductor/urgency.js";
+import { ADVANCE_COMMAND } from "../routing/types.js";
+function git(args, cwd) {
+    return new Promise((res) => {
+        execFile("git", args, { cwd, timeout: 5_000 }, (err, stdout) => {
+            res({ ok: !err, stdout: typeof stdout === "string" ? stdout : "" });
+        });
+    });
+}
+async function gitProbe(cwd) {
+    const status = await git(["status", "--porcelain"], cwd);
+    const ahead = await git(["rev-list", "--count", "@{upstream}..HEAD"], cwd);
+    // No upstream (or probe failure) reads as unpushed work: fail closed to partial.
+    return { porcelain: status.stdout, ahead: ahead.ok ? Number.parseInt(ahead.stdout.trim(), 10) || 0 : 1 };
+}
+function appendRunLog(config, cwd, line) {
+    const path = resolve(cwd, config.runLogPath ?? ".agentic-workflow/advance-run.log");
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        appendFileSync(path, `${line}\n`, "utf8");
+    }
+    catch {
+        // A run log that cannot be written never blocks the stage itself.
+    }
+}
+async function parkInFlight(cwd) {
+    await git(["add", "-A"], cwd);
+    await git(["commit", "-m", "wip: parked by advance (urgent interrupt)"], cwd);
+}
+/** Register the native `advance` command on the shared registrar. */
+export function registerAdvanceCommand(registrar, deps, commandNames) {
+    registrar.registerCommand(ADVANCE_COMMAND, {
+        description: "Deterministic conductor: sensor → decide → invoke the next stage; stops on needs_input/stop. Never merges.",
+        handler: async (_args, ctx) => {
+            const flags = _args.split(/\s+/).filter(Boolean);
+            const attended = !flags.includes("--fullauto") && !flags.includes("--unattended");
+            const continueLoop = flags.includes("--continue");
+            // The effective advance knobs: the merged config when it carries the
+            // key, the shipped defaults otherwise.
+            let config = { ...DEFAULT_ADVANCE_CONFIG };
+            try {
+                const loaded = deps.readConfig(ctx);
+                if (loaded.ok && loaded.config.advance)
+                    config = loaded.config.advance;
+            }
+            catch {
+                // Config trouble falls back to the shipped advance defaults; the loop
+                // itself is fail-closed on the sensor side anyway.
+            }
+            const surface = deps.surface(ctx);
+            const result = await runConductorLoop({
+                cwd: ctx.cwd,
+                runtimeBin: runtimeBin(),
+                commandNames,
+                maxInvokes: continueLoop ? undefined : 1,
+                attended,
+                config,
+                runSensor: (cwd, bin) => import("../conductor/sensor.js").then(({ runSensor }) => runSensor(cwd, bin)),
+                decide: decideFromEnvelope,
+                invocation: invocationFromDecision,
+                judgeUrgency,
+                sendUserMessage: (invocation) => {
+                    surface.sendUserMessage(invocation, { expandPromptTemplates: true });
+                    return Promise.resolve({ ok: true });
+                },
+                gitProbe: () => gitProbe(ctx.cwd),
+                appendRunLog: (line) => appendRunLog(config, ctx.cwd, line),
+                parkInFlight: () => {
+                    return parkInFlight(ctx.cwd);
+                },
+            });
+            ctx.notify(`${result.banner} — ${result.detail ?? ""} (iterations: ${result.iterations})`, "info");
+        },
+    });
+}

package/dist/extension/factory.js

@@ -2,7 +2,8 @@ import { loadConfig } from "../config/load.js";
 import { readCatalogue } from "../routing/catalogue.js";
 import { createRouter } from "../routing/dispatch.js";
 import { dirtyWorktreeWarning, receiptGuard } from "./receipt-guard.js";
-import { SETTINGS_COMMAND, SETTINGS_COMMAND_ALIAS } from "../routing/types.js";
+import { ADVANCE_COMMAND, SETTINGS_COMMAND, SETTINGS_COMMAND_ALIAS } from "../routing/types.js";
+import { registerAdvanceCommand } from "./conductor-command.js";
 export function createExtension(deps) {
     const { registrar, surface, skillsDir, agentDir, hint, settings } = deps;
     const catalogue = readCatalogue(skillsDir);
@@ -21,6 +22,7 @@ export function createExtension(deps) {
     };
     const knownCommands = new Set([
         ...catalogue.commands.map((entry) => entry.name),
+        ADVANCE_COMMAND,
         SETTINGS_COMMAND,
         SETTINGS_COMMAND_ALIAS,
     ]);
@@ -49,6 +51,9 @@ export function createExtension(deps) {
             ctx.notify(`Settings could not be opened: ${error.message}`, "error");
         }
     };
+    // The native conductor command (feature 62): registered in code, not derived
+    // from a skill dir, and able to invoke every catalogue command by name.
+    registerAdvanceCommand(registrar, { surface, readConfig: read }, knownCommands);
     registrar.registerCommand(SETTINGS_COMMAND, {
         description: "Show and configure per-command model routing",
         handler: settingsHandler,

package/dist/routing/types.d.ts

@@ -90,6 +90,8 @@ export type DispatchOutcome = {
     message: string;
 };
 /** Slash name of the settings console (SPEC S4, AC3, AC10). */
+/** The native conductor command (feature 62): sensor → decide → invoke loop. */
+export declare const ADVANCE_COMMAND = "advance";
 export declare const SETTINGS_COMMAND = "agentic-workflow-settings";
 /** Shorthand alias for the same console — a pointer to the same handler, never a separate route (OB-5, AC6). */
 export declare const SETTINGS_COMMAND_ALIAS = "aw-settings";

package/dist/routing/types.js

@@ -1,5 +1,7 @@
 export const modelRefKey = (model) => `${model.provider}/${model.id}`;
 /** Slash name of the settings console (SPEC S4, AC3, AC10). */
+/** The native conductor command (feature 62): sensor → decide → invoke loop. */
+export const ADVANCE_COMMAND = "advance";
 export const SETTINGS_COMMAND = "agentic-workflow-settings";
 /** Shorthand alias for the same console — a pointer to the same handler, never a separate route (OB-5, AC6). */
 export const SETTINGS_COMMAND_ALIAS = "aw-settings";

package/dist/runtime.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Runtime resolver — determines what runtime pi itself runs under so
+ * spawned children inherit the same choice.
+ *
+ * The current process is always pi (this module lives inside the package
+ * that ships with pi). Whichever runtime launched pi decides what
+ * children get:
+ *  - pi installed via `bun add -g` → bun
+ *  - pi installed via `npm install -g` → node
+ *
+ * `AGENTIC_WORKFLOW_RUNTIME` env override is the highest priority: it
+ * always wins, letting the operator force a specific runtime regardless
+ * of how pi was installed.
+ *
+ * Exported from the package's public entry (compiled from src/ → dist/).
+ * Intended call site: wherever the extension spawns a `.mjs` script,
+ * use `runtimeBin()` + `runtimeEnv()` instead of a hardcoded `"node"`
+ * or `"bun"`.
+ */
+/**
+ * Detect the runtime of the *current process* (which is pi).
+ * Returns `"bun"` when `globalThis.Bun` exists, or when
+ * `process.execPath` contains the substring `"bun"`; otherwise `"node"`.
+ */
+export declare function detectRuntime(): "bun" | "node";
+/**
+ * Return an environment object for spawned children that ensures
+ * `AGENTIC_WORKFLOW_RUNTIME` is set.
+ *
+ * Priority:
+ * 1. If the caller passes an explicit value, use it (user override).
+ * 2. If `AGENTIC_WORKFLOW_RUNTIME` is already in `process.env`, use it.
+ * 3. Fall back to the detected runtime.
+ *
+ * Returns `{ AGENTIC_WORKFLOW_RUNTIME: "bun" | "node" }`.
+ */
+export declare function runtimeEnv(overrides?: {
+    AGENTIC_WORKFLOW_RUNTIME?: "bun" | "node";
+}): Record<string, string>;
+/**
+ * Return the executable name to spawn for running a script.
+ * Returns `"bun"` or `"node"` based on the detected runtime,
+ * respecting the `AGENTIC_WORKFLOW_RUNTIME` env override.
+ */
+export declare function runtimeBin(): "bun" | "node";

package/dist/runtime.js

@@ -0,0 +1,62 @@
+/**
+ * Runtime resolver — determines what runtime pi itself runs under so
+ * spawned children inherit the same choice.
+ *
+ * The current process is always pi (this module lives inside the package
+ * that ships with pi). Whichever runtime launched pi decides what
+ * children get:
+ *  - pi installed via `bun add -g` → bun
+ *  - pi installed via `npm install -g` → node
+ *
+ * `AGENTIC_WORKFLOW_RUNTIME` env override is the highest priority: it
+ * always wins, letting the operator force a specific runtime regardless
+ * of how pi was installed.
+ *
+ * Exported from the package's public entry (compiled from src/ → dist/).
+ * Intended call site: wherever the extension spawns a `.mjs` script,
+ * use `runtimeBin()` + `runtimeEnv()` instead of a hardcoded `"node"`
+ * or `"bun"`.
+ */
+/**
+ * Detect the runtime of the *current process* (which is pi).
+ * Returns `"bun"` when `globalThis.Bun` exists, or when
+ * `process.execPath` contains the substring `"bun"`; otherwise `"node"`.
+ */
+export function detectRuntime() {
+    if (globalThis.Bun !== undefined) {
+        return "bun";
+    }
+    const execPath = process.execPath ?? "";
+    if (execPath.includes("bun")) {
+        return "bun";
+    }
+    return "node";
+}
+/**
+ * Return an environment object for spawned children that ensures
+ * `AGENTIC_WORKFLOW_RUNTIME` is set.
+ *
+ * Priority:
+ * 1. If the caller passes an explicit value, use it (user override).
+ * 2. If `AGENTIC_WORKFLOW_RUNTIME` is already in `process.env`, use it.
+ * 3. Fall back to the detected runtime.
+ *
+ * Returns `{ AGENTIC_WORKFLOW_RUNTIME: "bun" | "node" }`.
+ */
+export function runtimeEnv(overrides) {
+    const value = overrides?.AGENTIC_WORKFLOW_RUNTIME ??
+        process.env.AGENTIC_WORKFLOW_RUNTIME ??
+        detectRuntime();
+    return { AGENTIC_WORKFLOW_RUNTIME: value };
+}
+/**
+ * Return the executable name to spawn for running a script.
+ * Returns `"bun"` or `"node"` based on the detected runtime,
+ * respecting the `AGENTIC_WORKFLOW_RUNTIME` env override.
+ */
+export function runtimeBin() {
+    const env = process.env.AGENTIC_WORKFLOW_RUNTIME;
+    if (env === "bun" || env === "node")
+        return env;
+    return detectRuntime();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.13.3",
+  "version": "0.15.0",
   "description": "Pi package: canonical agentic-workflow skills, friendly slash commands, and per-command model routing.",
   "keywords": [
     "pi-package",
@@ -56,7 +56,9 @@
     "@earendil-works/pi-coding-agent": ">=0.87.0"
   },
   "dependencies": {
-    "@earendil-works/pi-tui": "0.87.0"
+    "@earendil-works/pi-tui": "0.87.0",
+    "@gtrabanco/agentic-workflow": "file:../agentic-workflow",
+    "@gtrabanco/agentic-workflow-schema": "4.5.0"
   },
   "devDependencies": {
     "@types/node": "24.13.3",

package/skills/audit-docs/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: audit-docs
 user-invocable: true
-version: 2.1.0
+version: 2.1.1
 argument-hint: "[--fix]"
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -11,7 +11,8 @@ description: >
   entries already merged/closed, broken documentation-map links, dependency
   cycles, artifacts in the wrong language, naming-convention violations — and
   reports them ranked by severity, fixing only low-risk items on request.
-  On Claude Code and want hand-tuned per-skill model/effort tiers? Install the `#claude` branch instead (`npx skills add gtrabanco/agentic-workflow#claude`) — see the README. This branch is model-agnostic: the skill inherits whatever model and effort your agent session is already using.
+  Model-agnostic: the skill inherits whatever model and effort your agent
+  session is already using.
   Triggers: "check doc consistency", "are the docs in sync", "audit the docs",
   "doc coherence review", "did the docs drift", "validate the roadmap".
 ---
@@ -93,12 +94,12 @@ run the command shown, don't infer.
     feature/fix-scoped changes committed directly without a PR: HIGH.
 13. **Generated-docs provenance (only when the documentation map declares a
     `Docs site` block; otherwise state n/a).** Scan the declared content dir
-    for pages carrying `generated-by: agentic-workflow/generate-docs`. For
+    for orphan pages
     each: (a) its `source-unit` exists in the roadmap or fix index — no match
     is an **orphan** (low: propose deletion or re-attribution); (b) the
     unit's PR merged **after** the page's `updated` date with commits touching
     the page's subject paths — that page is **stale** (LOW: propose
-    `/generate-docs <unit>` to refresh). Cite page path + unit per finding.
+). Cite page path + unit per finding.
 14. **Commit format & dependency discipline.** Sample the unit branches'
     commits: `<type>(<scope>): <summary>` conventional format (violations:
     LOW). Every `in-progress`/`done` row's `Depends on:` closure was merged —
@@ -149,7 +150,7 @@ enables:
 - **No slash-command menu** — where this skill says `/<skill>`, open that
   skill's `SKILL.md` (wherever your agent installed the skills) and follow it
   literally, in a fresh conversation: hand-offs assume a clean context.
-- **No per-skill `model:`/`effort:`** — on the `#claude` branch the frontmatter pins these tiers; here, pick tiers yourself:
+- **No per-skill `model:`/`effort:`** — no skill pins a tier; pick tiers yourself:
   these are mostly mechanical cross-document checks — a mid-tier model is
   enough; escalate to your strongest only for a deep audit.
 

package/skills/audit-pr/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: audit-pr
 user-invocable: true
-version: 5.3.0
+version: 5.3.1
 argument-hint: <pr-number> (optional — defaults to the current branch's PR)
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT

package/skills/audit-pr/references/PORTABILITY.md

@@ -7,7 +7,7 @@ enables:
 - **No slash-command menu** — where this skill says `/<skill>`, open that
   skill's `SKILL.md` (wherever your agent installed the skills) and follow it
   literally, in a fresh conversation: hand-offs assume a clean context.
-- **No per-skill `model:`/`effort:`** — on the `#claude` branch the frontmatter pins these tiers; here, pick tiers yourself:
+- **No per-skill `model:`/`effort:`** — no skill pins a tier; pick tiers yourself:
   the merge gate is the highest-stakes automated verdict — run it on your
   **strongest** model, never on the cheap tier that wrote the code.
 - **Receipt consumption is comment-based, not forge-branded.** The