@entelligentsia/forgecli 0.3.0 → 0.7.6

package/dist/extensions/forgecli/wf-engine/predicate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"predicate.js","sourceRoot":"","sources":["../../../../src/extensions/forgecli/wf-engine/predicate.ts"],"names":[],"mappings":"AAKA,MAAM,KAAK,GAAG,oCAAoC,CAAC;AAEnD,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,GAAqB;IAC/D,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC/B,IAAI,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,IAAI,sCAAsC,CAAC,CAAC;IAChG,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAElC,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;IACvE,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,mBAAmB,MAAM,+BAA+B,CAAC,CAAC;IAC5E,CAAC;IAED,QAAQ,EAAE,EAAE,CAAC;QACX,KAAK,IAAI,CAAC,CAAC,OAAO,GAAG,KAAK,GAAG,CAAC;QAC9B,KAAK,IAAI,CAAC,CAAC,OAAO,GAAG,KAAK,GAAG,CAAC;QAC9B,KAAK,GAAG,CAAC,CAAE,OAAQ,GAAc,GAAK,GAAc,CAAC;QACrD,KAAK,IAAI,CAAC,CAAC,OAAQ,GAAc,IAAK,GAAc,CAAC;QACrD,KAAK,GAAG,CAAC,CAAE,OAAQ,GAAc,GAAK,GAAc,CAAC;QACrD,KAAK,IAAI,CAAC,CAAC,OAAQ,GAAc,IAAK,GAAc,CAAC;QACrD,OAAO,CAAC,CAAG,MAAM,IAAI,KAAK,CAAC,8BAA8B,EAAE,GAAG,CAAC,CAAC;IAClE,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,GAAY,EAAE,MAAc;IAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,GAAG,GAAY,GAAG,CAAC;IACvB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAC9D,GAAG,GAAI,GAA+B,CAAC,CAAC,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/extensions/forgecli/wf-engine/prompt-compiler.d.ts

@@ -0,0 +1,15 @@
+export interface PromptContext {
+    wf: {
+        instanceId: string;
+        workingDir: string;
+    };
+    node: {
+        execId: string;
+        id: string;
+    };
+    state: unknown;
+    loop?: {
+        item: unknown;
+    };
+}
+export declare function compilePrompt(promptFile: string, ctx: PromptContext): string;

package/dist/extensions/forgecli/wf-engine/prompt-compiler.js

@@ -0,0 +1,23 @@
+import * as fs from "node:fs";
+export function compilePrompt(promptFile, ctx) {
+    let body = fs.readFileSync(promptFile, "utf8");
+    body = substitute(body, "{{wf.instanceId}}", ctx.wf.instanceId);
+    body = substitute(body, "{{wf.workingDir}}", ctx.wf.workingDir);
+    body = substitute(body, "{{node.execId}}", ctx.node.execId);
+    body = substitute(body, "{{node.id}}", ctx.node.id);
+    body = substitute(body, "{{state}}", JSON.stringify(ctx.state, null, 2));
+    if (ctx.loop) {
+        body = substitute(body, "{{loop.item}}", JSON.stringify(ctx.loop.item, null, 2));
+        // Also support {{loop.item.<key>}} for shallow object access
+        if (typeof ctx.loop.item === "object" && ctx.loop.item !== null) {
+            for (const [k, v] of Object.entries(ctx.loop.item)) {
+                body = substitute(body, `{{loop.item.${k}}}`, String(v));
+            }
+        }
+    }
+    return body;
+}
+function substitute(s, token, value) {
+    return s.split(token).join(value);
+}
+//# sourceMappingURL=prompt-compiler.js.map

package/dist/extensions/forgecli/wf-engine/prompt-compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-compiler.js","sourceRoot":"","sources":["../../../../src/extensions/forgecli/wf-engine/prompt-compiler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAS9B,MAAM,UAAU,aAAa,CAAC,UAAkB,EAAE,GAAkB;IAClE,IAAI,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC/C,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,mBAAmB,EAAI,GAAG,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC;IAClE,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,mBAAmB,EAAI,GAAG,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC;IAClE,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,iBAAiB,EAAM,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAChE,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,aAAa,EAAU,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5D,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,WAAW,EAAY,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACnF,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QACb,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,eAAe,EAAM,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACrF,6DAA6D;QAC7D,IAAI,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YAChE,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBACnD,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,UAAU,CAAC,CAAS,EAAE,KAAa,EAAE,KAAa;IACzD,OAAO,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACpC,CAAC"}

package/dist/extensions/forgecli/wf-engine/register.d.ts

@@ -0,0 +1,9 @@
+import type { ExtensionAPI } from "@entelligentsia/pi-coding-agent";
+export interface RegisterRunWorkflowOptions {
+    cwd?: string;
+    /** Explicit single search dir. If set, overrides the CWD-first/bundled-fallback resolution. */
+    workflowsDir?: string;
+    /** Bundled workflows shipped with the package — used as fallback when CWD/workflows/<id> doesn't exist. */
+    bundledWorkflowsDir?: string;
+}
+export declare function registerRunWorkflow(pi: ExtensionAPI, options?: RegisterRunWorkflowOptions): void;

package/dist/extensions/forgecli/wf-engine/register.js

@@ -0,0 +1,59 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { runWorkflow } from "./engine.js";
+import { getSessionRegistry } from "../session-registry.js";
+export function registerRunWorkflow(pi, options = {}) {
+    pi.registerCommand("forge:run-workflow", {
+        description: "Run a generic workflow defined in workflows/<workflowId>/workflow.yaml. " +
+            "Resolution: CWD/workflows/<id> first, then bundled examples. " +
+            "Usage: /forge:run-workflow <workflowId> [entryPrompt...]",
+        async handler(args, ctx) {
+            const cwd = options.cwd ?? process.cwd();
+            const trimmed = args.trim();
+            if (!trimmed) {
+                ctx.ui.notify("× /forge:run-workflow — workflowId required. Usage: /forge:run-workflow <workflowId> [prompt]", "error");
+                return;
+            }
+            const [workflowId, ...rest] = trimmed.split(/\s+/);
+            const entryPrompt = rest.join(" ");
+            // Resolve workflowsDir: explicit override > CWD/workflows (if it has the id) > bundled fallback
+            let workflowsDir;
+            if (options.workflowsDir) {
+                workflowsDir = options.workflowsDir;
+            }
+            else {
+                const cwdCandidate = path.join(cwd, "workflows");
+                if (fs.existsSync(path.join(cwdCandidate, workflowId, "workflow.yaml"))) {
+                    workflowsDir = cwdCandidate;
+                }
+                else if (options.bundledWorkflowsDir) {
+                    workflowsDir = options.bundledWorkflowsDir;
+                }
+                else {
+                    workflowsDir = cwdCandidate; // last resort — will surface a clear not-found error
+                }
+            }
+            try {
+                const result = await runWorkflow({
+                    workflowsDir,
+                    workflowId,
+                    cwd,
+                    entryPrompt,
+                    notify: (line) => ctx.ui.notify(line, "info"),
+                    registry: getSessionRegistry(),
+                });
+                if (result.status === "completed") {
+                    ctx.ui.notify(`✓ workflow complete: ${result.workingDir}`, "info");
+                }
+                else {
+                    ctx.ui.notify(`× workflow halted (${result.haltReason}): ${result.workingDir}`, "error");
+                }
+            }
+            catch (err) {
+                const e = err;
+                ctx.ui.notify(`× /forge:run-workflow threw: ${e.message ?? "unknown"}`, "error");
+            }
+        },
+    });
+}
+//# sourceMappingURL=register.js.map

package/dist/extensions/forgecli/wf-engine/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../../../src/extensions/forgecli/wf-engine/register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAU5D,MAAM,UAAU,mBAAmB,CAAC,EAAgB,EAAE,UAAsC,EAAE;IAC5F,EAAE,CAAC,eAAe,CAAC,oBAAoB,EAAE;QACvC,WAAW,EACT,0EAA0E;YAC1E,+DAA+D;YAC/D,0DAA0D;QAC5D,KAAK,CAAC,OAAO,CAAC,IAAY,EAAE,GAA4B;YACtD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;YAEzC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YAC5B,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,+FAA+F,EAAE,OAAO,CAAC,CAAC;gBACxH,OAAO;YACT,CAAC;YACD,MAAM,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACnD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAEnC,gGAAgG;YAChG,IAAI,YAAgC,CAAC;YACrC,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;gBACzB,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;YACtC,CAAC;iBAAM,CAAC;gBACN,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;gBACjD,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC;oBACxE,YAAY,GAAG,YAAY,CAAC;gBAC9B,CAAC;qBAAM,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC;oBACvC,YAAY,GAAG,OAAO,CAAC,mBAAmB,CAAC;gBAC7C,CAAC;qBAAM,CAAC;oBACN,YAAY,GAAG,YAAY,CAAC,CAAG,qDAAqD;gBACtF,CAAC;YACH,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC;oBAC/B,YAAY;oBACZ,UAAU;oBACV,GAAG;oBACH,WAAW;oBACX,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC;oBAC7C,QAAQ,EAAE,kBAAkB,EAAE;iBAC/B,CAAC,CAAC;gBACH,IAAI,MAAM,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;oBAClC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,wBAAwB,MAAM,CAAC,UAAU,EAAE,EAAE,MAAM,CAAC,CAAC;gBACrE,CAAC;qBAAM,CAAC;oBACN,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,sBAAsB,MAAM,CAAC,UAAU,MAAM,MAAM,CAAC,UAAU,EAAE,EAAE,OAAO,CAAC,CAAC;gBAC3F,CAAC;YACH,CAAC;YAAC,OAAO,GAAY,EAAE,CAAC;gBACtB,MAAM,CAAC,GAAG,GAA2B,CAAC;gBACtC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,gCAAgC,CAAC,CAAC,OAAO,IAAI,SAAS,EAAE,EAAE,OAAO,CAAC,CAAC;YACnF,CAAC;QACH,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/extensions/forgecli/wf-engine/remit-check.d.ts

@@ -0,0 +1,6 @@
+import type { Event, NodeDef } from "./types.js";
+export interface RemitCheckResult {
+    ok: boolean;
+    violations: string[];
+}
+export declare function checkRemit(emitted: Event[], node: NodeDef, loopItemId?: string): RemitCheckResult;

package/dist/extensions/forgecli/wf-engine/remit-check.js

@@ -0,0 +1,42 @@
+export function checkRemit(emitted, node, loopItemId) {
+    const violations = [];
+    // Must have started + exactly one terminal
+    const startedCount = emitted.filter(e => e.type === "started").length;
+    if (startedCount !== 1)
+        violations.push(`expected exactly 1 'started' event, got ${startedCount}`);
+    const terminals = emitted.filter(e => e.type === "success" || e.type === "failure");
+    if (terminals.length !== 1)
+        violations.push(`expected exactly 1 terminal event (success/failure), got ${terminals.length}`);
+    if (terminals.length === 1) {
+        const term = terminals[0];
+        if (term.type === "success" && term.writes?.artifact) {
+            const pattern = node.expects.success.writes?.artifact?.pattern;
+            if (!pattern) {
+                violations.push(`node emitted artifact but expects.success.writes.artifact not declared`);
+            }
+            else {
+                const resolved = pattern.replace(/\{loop\.item\.id\}/g, loopItemId ?? "");
+                if (term.writes.artifact.path !== resolved) {
+                    violations.push(`artifact path '${term.writes.artifact.path}' does not match declared pattern '${resolved}'`);
+                }
+            }
+        }
+        if (term.type === "success" && term.writes?.state) {
+            const allowed = node.expects.success.writes?.state ?? [];
+            for (const key of Object.keys(term.writes.state)) {
+                const matched = allowed.some(a => {
+                    const resolved = a.replace(/\{loop\.item\.id\}/g, loopItemId ?? "");
+                    return resolved === key;
+                });
+                if (!matched) {
+                    violations.push(`state write '${key}' not in declared expects.success.writes.state`);
+                }
+            }
+        }
+        if (term.type === "failure" && (!term.reason || typeof term.reason !== "string")) {
+            violations.push(`failure event missing 'reason' string`);
+        }
+    }
+    return { ok: violations.length === 0, violations };
+}
+//# sourceMappingURL=remit-check.js.map

package/dist/extensions/forgecli/wf-engine/remit-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remit-check.js","sourceRoot":"","sources":["../../../../src/extensions/forgecli/wf-engine/remit-check.ts"],"names":[],"mappings":"AAOA,MAAM,UAAU,UAAU,CACxB,OAAgB,EAChB,IAAa,EACb,UAAmB;IAEnB,MAAM,UAAU,GAAa,EAAE,CAAC;IAEhC,2CAA2C;IAC3C,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,MAAM,CAAC;IACtE,IAAI,YAAY,KAAK,CAAC;QAAE,UAAU,CAAC,IAAI,CAAC,2CAA2C,YAAY,EAAE,CAAC,CAAC;IAEnG,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IACpF,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,UAAU,CAAC,IAAI,CAAC,4DAA4D,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;IAE5H,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;QAC1B,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC;YACrD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC;YAC/D,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,UAAU,CAAC,IAAI,CAAC,wEAAwE,CAAC,CAAC;YAC5F,CAAC;iBAAM,CAAC;gBACN,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,qBAAqB,EAAE,UAAU,IAAI,EAAE,CAAC,CAAC;gBAC1E,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBAC3C,UAAU,CAAC,IAAI,CAAC,kBAAkB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,sCAAsC,QAAQ,GAAG,CAAC,CAAC;gBAChH,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;YAClD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,IAAI,EAAE,CAAC;YACzD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;oBAC/B,MAAM,QAAQ,GAAG,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,UAAU,IAAI,EAAE,CAAC,CAAC;oBACpE,OAAO,QAAQ,KAAK,GAAG,CAAC;gBAC1B,CAAC,CAAC,CAAC;gBACH,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,UAAU,CAAC,IAAI,CAAC,gBAAgB,GAAG,gDAAgD,CAAC,CAAC;gBACvF,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,EAAE,CAAC;YACjF,UAAU,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;AACrD,CAAC"}

package/dist/extensions/forgecli/wf-engine/state-store.d.ts

@@ -0,0 +1,13 @@
+import type { Event, RuntimeState } from "./types.js";
+export declare class StateStore {
+    private readonly workingDir;
+    constructor(workingDir: string);
+    initialState(initial: RuntimeState): void;
+    readState(): RuntimeState;
+    writeState(s: RuntimeState): void;
+    appendEvents(events: Event[]): void;
+    writeArtifact(relPath: string, content: string): void;
+    writeNodeArchive(nodeExecId: string, files: Record<string, string>): void;
+    private statePath;
+    private eventLogPath;
+}

package/dist/extensions/forgecli/wf-engine/state-store.js

@@ -0,0 +1,43 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+export class StateStore {
+    workingDir;
+    constructor(workingDir) {
+        this.workingDir = workingDir;
+    }
+    initialState(initial) {
+        fs.mkdirSync(this.workingDir, { recursive: true });
+        fs.mkdirSync(path.join(this.workingDir, "nodes"), { recursive: true });
+        fs.mkdirSync(path.join(this.workingDir, "artifacts"), { recursive: true });
+        fs.writeFileSync(this.statePath(), JSON.stringify(initial, null, 2));
+        fs.writeFileSync(this.eventLogPath(), ""); // create empty file
+    }
+    readState() {
+        return JSON.parse(fs.readFileSync(this.statePath(), "utf8"));
+    }
+    writeState(s) {
+        // Atomic write: tmp + rename
+        const tmp = `${this.statePath()}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(s, null, 2));
+        fs.renameSync(tmp, this.statePath());
+    }
+    appendEvents(events) {
+        const lines = events.map(e => JSON.stringify(e)).join("\n") + "\n";
+        fs.appendFileSync(this.eventLogPath(), lines);
+    }
+    writeArtifact(relPath, content) {
+        const abs = path.join(this.workingDir, relPath);
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, content);
+    }
+    writeNodeArchive(nodeExecId, files) {
+        const dir = path.join(this.workingDir, "nodes", nodeExecId);
+        fs.mkdirSync(dir, { recursive: true });
+        for (const [name, content] of Object.entries(files)) {
+            fs.writeFileSync(path.join(dir, name), content);
+        }
+    }
+    statePath() { return path.join(this.workingDir, "state.json"); }
+    eventLogPath() { return path.join(this.workingDir, "events.log.jsonl"); }
+}
+//# sourceMappingURL=state-store.js.map

package/dist/extensions/forgecli/wf-engine/state-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-store.js","sourceRoot":"","sources":["../../../../src/extensions/forgecli/wf-engine/state-store.ts"],"names":[],"mappings":"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"}

package/dist/extensions/forgecli/wf-engine/types.d.ts

@@ -0,0 +1,66 @@
+export interface WorkflowDef {
+    id: string;
+    version: number;
+    description?: string;
+    nodes: NodeDef[];
+    edges: EdgeDef[];
+}
+export interface NodeDef {
+    id: string;
+    prompt: string;
+    loop?: LoopSpec;
+    expects: ExpectsSpec;
+}
+export interface LoopSpec {
+    over: string;
+    alias: string;
+    alsoEmitsItemId?: boolean;
+    group?: string;
+    head?: boolean;
+}
+export interface ExpectsSpec {
+    success: {
+        writes?: {
+            state?: string[];
+            artifact?: {
+                pattern: string;
+            };
+        };
+    };
+    failure: {};
+}
+export interface EdgeDef {
+    from: string;
+    on: "success" | "failure" | "exhausted";
+    to?: string;
+    halt?: string;
+    terminal?: "complete";
+    advance?: "loop-or-next";
+    next?: string;
+    when?: string;
+}
+export interface RuntimeState {
+    cursor: string;
+    loopCursor: Record<string, number>;
+    entryPrompt?: string;
+    [key: string]: unknown;
+}
+export interface Event {
+    eventId: string;
+    nodeExecId: string;
+    type: "started" | "progress" | "success" | "failure" | "workflow.started" | "workflow.completed" | "workflow.halted" | "node.dispatched" | "node.committed" | "node.remit-violation";
+    ts: string;
+    writes?: {
+        state?: Record<string, unknown>;
+        artifact?: {
+            path: string;
+            content: string;
+        };
+    };
+    summary?: string;
+    reason?: string;
+    details?: string;
+    workflowId?: string;
+    instanceId?: string;
+    violatedRule?: string;
+}

package/dist/extensions/forgecli/wf-engine/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/extensions/forgecli/wf-engine/types.ts"],"names":[],"mappings":""}

package/dist/extensions/forgecli/wf-engine/worker.d.ts

@@ -0,0 +1,11 @@
+import { type AgentSessionEvent } from "@entelligentsia/pi-coding-agent";
+export interface WorkerResult {
+    responseText: string;
+    exitCode: 0 | 1;
+    errorMessage?: string;
+}
+export declare function dispatchLlmWorker(opts: {
+    compiledPrompt: string;
+    cwd: string;
+    onEvent?: (event: AgentSessionEvent) => void;
+}): Promise<WorkerResult>;

package/dist/extensions/forgecli/wf-engine/worker.js

@@ -0,0 +1,50 @@
+import { AuthStorage, createAgentSession, DefaultResourceLoader, getAgentDir, ModelRegistry, SessionManager, } from "@entelligentsia/pi-coding-agent";
+export async function dispatchLlmWorker(opts) {
+    const loader = new DefaultResourceLoader({
+        cwd: opts.cwd,
+        agentDir: getAgentDir(),
+        systemPromptOverride: () => "You are a workflow node worker. Read the user message carefully. "
+            + "At the end of your reply, emit a ```json events block per the protocol. "
+            + "Outside that block, you may write reasoning prose if helpful — but the engine ignores it.",
+        noExtensions: true,
+        noSkills: true,
+        noPromptTemplates: true,
+        noContextFiles: true,
+    });
+    await loader.reload();
+    const authStorage = AuthStorage.create();
+    const modelRegistry = ModelRegistry.create(authStorage);
+    const { session } = await createAgentSession({
+        sessionManager: SessionManager.inMemory(),
+        authStorage,
+        modelRegistry,
+        resourceLoader: loader,
+    });
+    let responseText = "";
+    const unsub = session.subscribe((event) => {
+        if (opts.onEvent)
+            opts.onEvent(event);
+        if (event.type === "turn_end" && event.message) {
+            const msg = event.message;
+            if (msg.role === "assistant") {
+                for (const part of msg.content) {
+                    if (part.type === "text")
+                        responseText += part.text;
+                }
+            }
+        }
+    });
+    try {
+        await session.prompt(opts.compiledPrompt);
+        unsub();
+        session.dispose();
+        return { responseText, exitCode: 0 };
+    }
+    catch (err) {
+        unsub();
+        session.dispose();
+        const e = err;
+        return { responseText, exitCode: 1, errorMessage: e.message ?? "worker threw" };
+    }
+}
+//# sourceMappingURL=worker.js.map

package/dist/extensions/forgecli/wf-engine/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../../../../src/extensions/forgecli/wf-engine/worker.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,qBAAqB,EACrB,WAAW,EACX,aAAa,EACb,cAAc,GAEf,MAAM,iCAAiC,CAAC;AASzC,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAIvC;IACC,MAAM,MAAM,GAAG,IAAI,qBAAqB,CAAC;QACvC,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,QAAQ,EAAE,WAAW,EAAE;QACvB,oBAAoB,EAAE,GAAG,EAAE,CACzB,mEAAmE;cACjE,0EAA0E;cAC1E,2FAA2F;QAC/F,YAAY,EAAE,IAAI;QAClB,QAAQ,EAAE,IAAI;QACd,iBAAiB,EAAE,IAAI;QACvB,cAAc,EAAE,IAAI;KACrB,CAAC,CAAC;IACH,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;IAEtB,MAAM,WAAW,GAAK,WAAW,CAAC,MAAM,EAAE,CAAC;IAC3C,MAAM,aAAa,GAAG,aAAa,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAExD,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,kBAAkB,CAAC;QAC3C,cAAc,EAAE,cAAc,CAAC,QAAQ,EAAE;QACzC,WAAW;QACX,aAAa;QACb,cAAc,EAAE,MAAM;KACvB,CAAC,CAAC;IAEH,IAAI,YAAY,GAAG,EAAE,CAAC;IAEtB,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,KAAwB,EAAE,EAAE;QAC3D,IAAI,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YAC/C,MAAM,GAAG,GAAG,KAAK,CAAC,OAAkB,CAAC;YACrC,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;gBAC7B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;oBAC/B,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;wBAAE,YAAY,IAAI,IAAI,CAAC,IAAI,CAAC;gBACtD,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC1C,KAAK,EAAE,CAAC;QACR,OAAO,CAAC,OAAO,EAAE,CAAC;QAClB,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;IACvC,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,KAAK,EAAE,CAAC;QACR,OAAO,CAAC,OAAO,EAAE,CAAC;QAClB,MAAM,CAAC,GAAG,GAA2B,CAAC;QACtC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,OAAO,IAAI,cAAc,EAAE,CAAC;IAClF,CAAC;AACH,CAAC"}

package/dist/forge-payload/.base-pack/workflows/_fragments/context-injection.md

@@ -34,15 +34,21 @@ else:
 
 ## Prior Phase Summary Block
 
-Re-read the task record from disk after each phase so summaries accumulate:
+Re-read the record from disk after each phase so summaries accumulate.
+For bugs, pass `record_type="bug"` to read from the bugs store path.
 
 ```python
-task_record_fresh = read_json(f".forge/store/tasks/{task_id}.json")
-summaries = (task_record_fresh or {}).get("summaries", {})
+# record_type: "task" (default) or "bug"
+if record_type == "bug":
+  record_fresh = read_json(f".forge/store/bugs/{record_id}.json")
+else:
+  record_fresh = read_json(f".forge/store/tasks/{record_id}.json")
+summaries = (record_fresh or {}).get("summaries", {})
 
 SUMMARY_PHASE_LABELS = {
   "plan": "Plan", "review_plan": "Plan review",
-  "implementation": "Implementation", "code_review": "Code review", "validation": "Validation"
+  "implementation": "Implementation", "code_review": "Code review",
+  "validation": "Validation", "approve": "Approve", "triage": "Triage"
 }
 summary_lines = []
 for phase_key, label in SUMMARY_PHASE_LABELS.items():

package/dist/forge-payload/.base-pack/workflows/_fragments/event-emission-schema.md

@@ -1,29 +1,73 @@
 # Fragment: Event Emission Schema
 
-<!-- Canonical required/optional event field table for orchestrator workflows.
-     Referenced by meta-orchestrate.md and meta-fix-bug.md. -->
-
-Every phase emits a structured event via `/forge:store emit {sprintId} '{event-json}'`.
-
-**Required fields** (defined in `.forge/schemas/event.schema.json`):
-
-| Field | Value |
-|-------|-------|
-| `eventId` | `{ISO_TIMESTAMP}_{TASK_ID}_{role}_{action}` e.g. `20260415T141523000Z_ACME-S02-T03_implement_plan-task` |
-| `taskId` | Task ID from the task manifest |
-| `sprintId` | Sprint ID from the task manifest |
-| `role` | Pipeline phase role (e.g. `plan`, `review-plan`, `implement`, `review-code`, `approve`, `commit`) |
-| `action` | Slash command invoked in namespaced form (e.g. `/forge:implement`, `/forge:review-plan`) |
-| `phase` | Pipeline phase name (e.g. `plan`, `review-plan`, `implement`, `review-code`, `approve`, `commit`) |
-| `iteration` | 1-based iteration count for this phase |
-| `startTimestamp` | ISO 8601 timestamp recorded **before** spawning the phase subagent |
-| `endTimestamp` | ISO 8601 timestamp recorded **after** the subagent returns |
-| `durationMinutes` | Decimal minutes elapsed between start and end |
-| `model` | Resolved model identifier (e.g. `claude-sonnet-4-6`). Read from `CLAUDE_CODE_SUBAGENT_MODEL` on single-cluster runtimes, or `ANTHROPIC_DEFAULT_{TIER}_MODEL` on tiered clusters. |
-
-**Optional fields** (merged from sidecar when present):
-`verdict`, `notes`, `inputTokens`, `outputTokens`, `cacheReadTokens`,
-`cacheWriteTokens`, `estimatedCostUSD`.
-
-Use only the field names above — no aliases (`agent`, `status`, `timestamp`, `details`).
-When in doubt, read `.forge/schemas/event.schema.json` directly.
+<!-- Canonical contract: subagents write judgement-only SUMMARY files; the
+     orchestrator stitches runtime telemetry + judgement into the canonical
+     event and emits it. Referenced by meta-orchestrate.md and meta-fix-bug.md.
+
+     PLAN-11 / SLICE-2 (2026-05-14): the LLM no longer hand-builds event JSON.
+     Runtime facts (model, provider, eventId, timestamps, iteration, tokens)
+     are owned by the orchestrator, never the subagent. The subagent only
+     produces judgement and lets the orchestrator complete the record. -->
+
+## Who writes what
+
+| Actor              | Owns (writes)                                                                                   | Never touches |
+|--------------------|-------------------------------------------------------------------------------------------------|---------------|
+| **Subagent (LLM)** | judgement fields: `verdict`, `notes`, `findings`, `objective`, `type`                           | `eventId`, `model`, `provider`, `startTimestamp`, `endTimestamp`, `durationMinutes`, `iteration`, `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `tokenSource` |
+| **Orchestrator**   | everything else — composes the canonical event from runtime telemetry + the subagent's SUMMARY  | the judgement fields themselves (copies them through unchanged) |
+
+The LLM is the wrong actor for runtime facts: it has no privileged access to
+the model/provider it ran under, the wall clock at spawn time, or the token
+counts reported by the runtime stream. Every LLM guess at these fields is
+wrong by construction.
+
+## What the subagent does
+
+After completing its phase, the subagent writes one file:
+
+```
+.forge/cache/{PHASE}-SUMMARY.json
+```
+
+Examples: `PLAN-SUMMARY.json`, `REVIEW-PLAN-SUMMARY.json`,
+`IMPLEMENT-SUMMARY.json`, `REVIEW-CODE-SUMMARY.json`, `COMMIT-SUMMARY.json`.
+
+The SUMMARY contains judgement only. Required keys are phase-specific
+(see `forge/schemas/phase-summary.schema.json` for the exact shape per
+phase) but typically include `verdict`, `notes`, and any `findings`
+the phase produces. The subagent **must not** include runtime fields —
+adding `model`, `provider`, timestamps, or token counts to the SUMMARY is
+ignored at best and rejected at worst.
+
+The subagent **does not** call `store-cli emit` for phase events. That
+shell-out is reserved for the orchestrator.
+
+## What the orchestrator does
+
+After the subagent returns, the orchestrator constructs the event from:
+
+1. **Runtime telemetry** captured during the subagent run:
+   `model`, `provider`, token usage (`inputTokens`, `outputTokens`,
+   `cacheReadTokens`, `cacheWriteTokens`, `tokenSource: "reported"`).
+2. **Known task context** the orchestrator already tracks for run-task:
+   `taskId`, `sprintId`, `phase`, `iteration`.
+3. **Bracketed wall times** the orchestrator records around the subagent
+   call: `startTimestamp`, `endTimestamp`, `durationMinutes`.
+4. **Judgement blob** read from `{PHASE}-SUMMARY.json`: `verdict`, `notes`,
+   `findings`, etc.
+
+The orchestrator then emits via:
+
+```
+node "$FORGE_ROOT/tools/store-cli.cjs" emit {sprintId} '{complete-event-json}'
+```
+
+## Why no example record here
+
+This fragment intentionally contains **no hardcoded example model strings,
+provider names, or timestamps**. Such examples were the historical source of
+LLM hallucination — subagents would copy the example verbatim ("the model
+is claude-sonnet-4-6 because the workflow says so") even when running on a
+completely different runtime. The schema lives at
+`.forge/schemas/event.schema.json`; consult it directly when verifying a
+field set.

package/dist/forge-payload/.base-pack/workflows/_fragments/finalize.md

@@ -1,23 +1,13 @@
-## Finalize: Token Reporting and Sidecar Emission
+## Finalize: Subagent Closure
 
 Before returning, every subagent MUST:
 
-1. Run `/cost` to retrieve session token usage.
-2. Parse the output for five fields: `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `estimatedCostUSD`.
-   - If `/cost` succeeds, add `"tokenSource": "reported"` to the sidecar JSON.
-   - If `/cost` fails or is unavailable, set all token fields to `null` and add `"tokenSource": "missing"`.
-3. Write the usage sidecar via `/forge:store emit {sprintId} '{sidecar-json}' --sidecar` with format:
-   ```json
-   {
-     "eventId": "<eventId passed by orchestrator>",
-     "inputTokens": <integer or null>,
-     "outputTokens": <integer or null>,
-     "cacheReadTokens": <integer or null>,
-     "cacheWriteTokens": <integer or null>,
-     "estimatedCostUSD": <number or null>,
-     "tokenSource": "reported" | "missing"
-   }
-   ```
-4. **NEVER skip sidecar write.** Always emit (with reported data or with nulls).
+1. Write any phase-specific summary the workflow body requires (e.g. PLAN.md, CODE_REVIEW.md).
+2. Confirm `task.status` reflects the phase outcome (via `store-cli update-status` if applicable).
+3. Return cleanly.
 
-The `eventId` is passed by the orchestrator in the subagent prompt. If unavailable, derive from context.
+**Subagents MUST NOT write token-usage sidecars.** Token telemetry is owned by the orchestrator, which captures provider-reported usage from the runtime as the subagent runs and emits the canonical event (with `provider`, `model`, `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `tokenSource: "reported"`) on the subagent's behalf.
+
+If the runtime does not surface usage (rare), the orchestrator emits the event **without** the token fields — never with placeholder zeros or a `"missing"` marker. Honest absence beats misleading presence.
+
+The `eventId` is passed by the orchestrator in the subagent prompt and is used only for non-token writes (e.g. `set-summary`, `update-status` history).

package/dist/forge-payload/.base-pack/workflows/_fragments/friction-emit.md

@@ -0,0 +1,73 @@
+<!-- Canonical Friction Emit fragment.
+     Referenced from meta-implement.md, meta-fix-bug.md, meta-validate.md,
+     meta-plan-task.md, and meta-orchestrate.md. /forge:enhance --phase 2
+     greps generated workflows for `## Friction Emit` to discover the channel.
+
+     PLAN-11 / SLICE-2 (2026-05-14): friction is now recorded via the
+     `friction-emit.cjs` tool which appends judgement-only records to
+     `.forge/cache/FRICTION-{workflow}.jsonl`. The orchestrator drains this
+     file at phase-end, stamps runtime attribution (model/provider/usage/
+     timestamps/eventId) onto each record, and emits the events. The LLM
+     never hand-builds a friction event JSON. -->
+
+# Friction Emit (Fragment)
+
+When the persona detects skill friction during the workflow — a referenced
+skill is unused, fails on invocation, is missing from the registry, has gone
+stale relative to current architecture, or is redundant with another skill —
+record a judgement-only friction signal. The orchestrator drains the
+signals and emits the corresponding events so `/forge:enhance --phase 2`
+can act on them.
+
+## Trigger conditions
+
+Set `--issue` on the emitted record to one of the following tokens:
+
+| Token              | When to emit                                                                     |
+|--------------------|----------------------------------------------------------------------------------|
+| `skill_unused`     | A skill listed in the persona's skill block was loaded but never consulted.      |
+| `skill_failed`     | A skill was consulted but its guidance produced an error or required correction. |
+| `skill_missing`    | The workflow needed guidance the available skills did not cover.                 |
+| `skill_stale`      | A skill's guidance contradicts current architecture / supersedes its own advice. |
+| `skill_redundant`  | Two skills provided overlapping or conflicting guidance for the same decision.   |
+
+Emit one record per distinct friction signal — do not coalesce multiple
+findings into a single record.
+
+## Judgement-only contract
+
+The friction recorder accepts only judgement fields. Runtime-attribution
+fields (`model`, `provider`, `eventId`, timestamps, token counts) are
+**rejected** if passed — they belong to the orchestrator and are stamped on
+at drain time.
+
+```sh
+node "$FORGE_ROOT/tools/friction-emit.cjs" \
+  --workflow {workflow-key} \
+  --persona  {persona-noun} \
+  --issue    skill_unused \
+  [--subkind  skill_unused] \
+  [--evidence '{"trajectory_excerpt":"...","tool_errors":["..."],"retrieval_score":0.0,"skillId":"..."}']
+```
+
+Required flags: `--workflow`, `--persona`, `--issue`.
+Optional flags: `--subkind` (frozen enum
+`skill_unused|skill_failed|skill_missing|skill_stale|skill_redundant`
+or experimental `^x_[a-z_]+$`), `--evidence` (JSON object with
+`trajectory_excerpt`, `tool_errors`, `retrieval_score` (0..1), `skillId`).
+
+The tool appends one line of judgement-only JSON to
+`.forge/cache/FRICTION-{workflow}.jsonl`. The orchestrator reads this file
+after the phase completes, stamps each record with the captured runtime
+attribution (model, provider, usage, wall times, eventId), and emits the
+resulting events via `store-cli emit`.
+
+## Per-workflow values
+
+| Workflow         | `workflow` | `persona`     | `phase`      |
+|------------------|------------|---------------|--------------|
+| meta-implement   | implement  | engineer      | implement    |
+| meta-fix-bug     | fix-bug    | bug-fixer     | fix-bug      |
+| meta-validate    | validate   | qa-engineer   | validate     |
+| meta-plan-task   | plan-task  | architect     | plan         |
+| meta-orchestrate | orchestrate| orchestrator  | orchestrate  |