@entelligentsia/forgecli 1.0.25 → 1.0.36

package/dist/extensions/forgecli/orchestrators/task/task-verdict-loop.js

@@ -0,0 +1,152 @@
+// task-verdict-loop.ts — review-phase verdict + revision/loopback handling
+// for the run-task pipeline. Extracted VERBATIM from run-task.ts's phase loop
+// (FORGE-S31 file-size refactor) as a pure decision function: it performs the
+// same store reads, ctx.ui notifications, state writes, transcript records,
+// tree-node finalization, and halt-advisor dispatch the inline block did, and
+// returns a small discriminated result the caller's loop switches on.
+//
+// Behavior-preserving: no logic changes. The only structural change is that the
+// inline `return {...}` paths now return `{ kind: "return"; result }`, the
+// `continue` path returns `{ kind: "loopback"; toIndex }`, and the fall-through
+// (approved) path returns `{ kind: "advance" }`.
+import { resolveAdvisorModel, runHaltAdvisor } from "../halt-advisor.js";
+import { recoverPhaseSummary } from "../common/summary-recovery.js";
+import { findPredecessorIndex } from "./task-body.js";
+import { PHASES, SUMMARY_KEY_BY_ROLE } from "./task-phases.js";
+import { readVerdict } from "./task-record.js";
+import { writeState } from "./task-state.js";
+/**
+ * Evaluate the review-phase verdict and decide the loop's next move.
+ * Mirrors the inline block that previously lived in runTaskPipelineInner.
+ */
+export function handleReviewVerdict(p) {
+    const { phase, taskId, storeCli, cwd, forgeRoot, iterationCounts, currentPhaseIndex, modelRoutingConfig, ctx } = p;
+    const { orchTranscript, finishPhaseNode, recoveredPhases } = p;
+    let verdict = readVerdict(taskId, phase.role, storeCli, cwd);
+    // Completion recovery (forge-engineering#41): a clean stop with no verdict in
+    // the store is most often the subagent writing the {PHASE}-SUMMARY.json
+    // sidecar but eliding the set-summary that registers it. Register the sidecar
+    // ourselves (once per phase), then re-read. Phases whose verdict comes from
+    // task.status (approve → summaryKey null) are not recoverable this way.
+    if (verdict === "missing") {
+        const summaryKey = SUMMARY_KEY_BY_ROLE[phase.role];
+        if (summaryKey && !recoveredPhases.has(phase.role)) {
+            recoveredPhases.add(phase.role);
+            const rec = recoverPhaseSummary({ storeCli, entityId: taskId, summaryKey, cwd });
+            if (rec.ok) {
+                const recheck = readVerdict(taskId, phase.role, storeCli, cwd);
+                if (recheck !== "missing") {
+                    ctx.ui.notify(`⟳ forge:run-task — ${phase.role}: subagent skipped set-summary; orchestrator registered ` +
+                        `the '${summaryKey}' sidecar and the verdict is now present.`, "info");
+                    verdict = recheck;
+                }
+            }
+        }
+    }
+    // Surface the resolved verdict on the dashboard (mirrored to the root node).
+    ctx.ui.notify(`  verdict: ${phase.role} → ${verdict === "approved" ? "〇 approved" : verdict === "revision" ? "⟳ revision" : `× ${verdict}`}`, verdict === "approved" || verdict === "revision" ? "info" : "error");
+    if (verdict === "missing") {
+        ctx.ui.notify(`× forge:run-task — verdict missing for phase ${phase.role} after subagent completed. ` +
+            "Subagent may have crashed or failed to write summaries. Halting for advisory.", "error");
+        finishPhaseNode("failed");
+        writeState(cwd, {
+            taskId,
+            phaseIndex: currentPhaseIndex,
+            iterationCounts,
+            halted: true,
+            lastError: `verdict missing for ${phase.role}`,
+            savedAt: new Date().toISOString(),
+        });
+        // A missing verdict IS a postflight-outputs failure: the canonical
+        // phase summary the subagent must write (e.g. summaries.code_review)
+        // was never recorded, so there is no verdict to route on. review-phase
+        // workflows declare no `outputs` block, so runPostflightGate is a
+        // pass-through here — this readVerdict check is the effective gate.
+        // Route it through the halt-recovery advisor (FORGE-S26-T18), the same
+        // hand-off the postflight-gate-unsatisfied branch uses, instead of a
+        // bare escalation — so the strongest configured model can diagnose the
+        // missing-summary cause. Best-effort, non-fatal (FORGE-S26-T19 parity).
+        const gateFailure = {
+            phase: phase.role,
+            reasonCode: "verdict-missing",
+            detail: `Phase '${phase.role}' completed but no verdict was found in the store. ` +
+                "The canonical phase summary was not written, so the orchestrator has no verdict to route on.",
+            remediation: "Re-run the phase and ensure the subagent's forge_store set-summary call " +
+                'uses args:["<recordId>", "<phaseKey>"] with the literal phase key as args[1] ' +
+                "(e.g. code_review), and that the call exits zero before the subagent returns.",
+        };
+        const advisorModel = resolveAdvisorModel(modelRoutingConfig, ctx.model);
+        void runHaltAdvisor({
+            gateFailure,
+            advisorModel,
+            taskId,
+            cwd,
+            ctx: { ui: ctx.ui },
+            forgeRoot,
+        });
+        return {
+            kind: "return",
+            result: {
+                status: "halted",
+                lastPhaseIndex: currentPhaseIndex,
+                iterationCounts,
+                lastError: `verdict missing for ${phase.role}`,
+            },
+        };
+    }
+    if (verdict === "revision") {
+        // Increment iteration count for this review phase
+        iterationCounts[phase.role] = (iterationCounts[phase.role] ?? 0) + 1;
+        if (iterationCounts[phase.role] >= phase.maxIterations) {
+            ctx.ui.notify(`× forge:run-task — revision cap reached for phase ${phase.role} ` +
+                `(${iterationCounts[phase.role]}/${phase.maxIterations} iterations). Escalating.`, "error");
+            finishPhaseNode("escalated");
+            writeState(cwd, {
+                taskId,
+                phaseIndex: currentPhaseIndex,
+                iterationCounts,
+                halted: true,
+                lastError: `revision cap reached for ${phase.role}`,
+                savedAt: new Date().toISOString(),
+            });
+            return {
+                kind: "return",
+                result: {
+                    status: "escalated",
+                    lastPhaseIndex: currentPhaseIndex,
+                    iterationCounts,
+                    lastError: `revision cap reached for ${phase.role}`,
+                },
+            };
+        }
+        // Loop back to predecessor non-review phase. The review
+        // subagent itself finished cleanly — `revision` is its verdict,
+        // not a failure — so its node closes as completed before the
+        // predecessor re-dispatches under a fresh node ID.
+        finishPhaseNode("completed");
+        const predIndex = findPredecessorIndex(PHASES, currentPhaseIndex);
+        ctx.ui.notify(`⟳ forge:run-task — ${phase.role} returned revision; looping to ${PHASES[predIndex]?.role ?? predIndex} ` +
+            `(attempt ${iterationCounts[phase.role]}/${phase.maxIterations})`, "info");
+        orchTranscript.record({
+            kind: "phase-loopback",
+            ts: new Date().toISOString(),
+            fromPhase: phase.role,
+            toPhase: PHASES[predIndex]?.role ?? String(predIndex),
+            fromPhaseIndex: currentPhaseIndex,
+            toPhaseIndex: predIndex,
+            reason: `${phase.role} returned revision (attempt ${iterationCounts[phase.role]}/${phase.maxIterations})`,
+        });
+        // Write intermediate state (not halted — still running)
+        writeState(cwd, {
+            taskId,
+            phaseIndex: predIndex,
+            iterationCounts,
+            halted: false,
+            savedAt: new Date().toISOString(),
+        });
+        return { kind: "loopback", toIndex: predIndex };
+    }
+    // verdict === "approved": advance
+    return { kind: "advance" };
+}
+//# sourceMappingURL=task-verdict-loop.js.map

package/dist/extensions/forgecli/orchestrators/task/task-verdict-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-verdict-loop.js","sourceRoot":"","sources":["../../../../../src/extensions/forgecli/orchestrators/task/task-verdict-loop.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,8EAA8E;AAC9E,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAC9E,sEAAsE;AACtE,EAAE;AACF,gFAAgF;AAChF,2EAA2E;AAC3E,gFAAgF;AAChF,iDAAiD;AAKjD,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAEtD,OAAO,EAAwB,MAAM,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAqB,UAAU,EAAE,MAAM,iBAAiB,CAAC;AA0BhE;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAoB;IACvD,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,eAAe,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IACnH,MAAM,EAAE,cAAc,EAAE,eAAe,EAAE,eAAe,EAAE,GAAG,CAAC,CAAC;IAE/D,IAAI,OAAO,GAAG,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;IAE7D,8EAA8E;IAC9E,wEAAwE;IACxE,8EAA8E;IAC9E,4EAA4E;IAC5E,wEAAwE;IACxE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,UAAU,GAAG,mBAAmB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACnD,IAAI,UAAU,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACpD,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAChC,MAAM,GAAG,GAAG,mBAAmB,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC;YACjF,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;gBAC/D,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;oBAC3B,GAAG,CAAC,EAAE,CAAC,MAAM,CACZ,sBAAsB,KAAK,CAAC,IAAI,0DAA0D;wBACzF,QAAQ,UAAU,2CAA2C,EAC9D,MAAM,CACN,CAAC;oBACF,OAAO,GAAG,OAAO,CAAC;gBACnB,CAAC;YACF,CAAC;QACF,CAAC;IACF,CAAC;IAED,6EAA6E;IAC7E,GAAG,CAAC,EAAE,CAAC,MAAM,CACZ,cAAc,KAAK,CAAC,IAAI,MAAM,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,OAAO,EAAE,EAAE,EAC9H,OAAO,KAAK,UAAU,IAAI,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CACnE,CAAC;IAEF,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC3B,GAAG,CAAC,EAAE,CAAC,MAAM,CACZ,gDAAgD,KAAK,CAAC,IAAI,6BAA6B;YACtF,+EAA+E,EAChF,OAAO,CACP,CAAC;QACF,eAAe,CAAC,QAAQ,CAAC,CAAC;QAC1B,UAAU,CAAC,GAAG,EAAE;YACf,MAAM;YACN,UAAU,EAAE,iBAAiB;YAC7B,eAAe;YACf,MAAM,EAAE,IAAI;YACZ,SAAS,EAAE,uBAAuB,KAAK,CAAC,IAAI,EAAE;YAC9C,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACV,CAAC,CAAC;QAC1B,mEAAmE;QACnE,qEAAqE;QACrE,uEAAuE;QACvE,kEAAkE;QAClE,oEAAoE;QACpE,uEAAuE;QACvE,qEAAqE;QACrE,uEAAuE;QACvE,wEAAwE;QACxE,MAAM,WAAW,GAAoB;YACpC,KAAK,EAAE,KAAK,CAAC,IAAI;YACjB,UAAU,EAAE,iBAAiB;YAC7B,MAAM,EACL,UAAU,KAAK,CAAC,IAAI,qDAAqD;gBACzE,8FAA8F;YAC/F,WAAW,EACV,0EAA0E;gBAC1E,+EAA+E;gBAC/E,+EAA+E;SAChF,CAAC;QACF,MAAM,YAAY,GAAG,mBAAmB,CAAC,kBAAkB,EAAE,GAAG,CAAC,KAAY,CAAC,CAAC;QAC/E,KAAK,cAAc,CAAC;YACnB,WAAW;YACX,YAAY;YACZ,MAAM;YACN,GAAG;YACH,GAAG,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,EAAS,EAAE;YAC1B,SAAS;SACT,CAAC,CAAC;QACH,OAAO;YACN,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE;gBACP,MAAM,EAAE,QAAQ;gBAChB,cAAc,EAAE,iBAAiB;gBACjC,eAAe;gBACf,SAAS,EAAE,uBAAuB,KAAK,CAAC,IAAI,EAAE;aAC9C;SACD,CAAC;IACH,CAAC;IAED,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;QAC5B,kDAAkD;QAClD,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QAErE,IAAI,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;YACxD,GAAG,CAAC,EAAE,CAAC,MAAM,CACZ,qDAAqD,KAAK,CAAC,IAAI,GAAG;gBACjE,IAAI,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,aAAa,2BAA2B,EAClF,OAAO,CACP,CAAC;YACF,eAAe,CAAC,WAAW,CAAC,CAAC;YAC7B,UAAU,CAAC,GAAG,EAAE;gBACf,MAAM;gBACN,UAAU,EAAE,iBAAiB;gBAC7B,eAAe;gBACf,MAAM,EAAE,IAAI;gBACZ,SAAS,EAAE,4BAA4B,KAAK,CAAC,IAAI,EAAE;gBACnD,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACV,CAAC,CAAC;YAC1B,OAAO;gBACN,IAAI,EAAE,QAAQ;gBACd,MAAM,EAAE;oBACP,MAAM,EAAE,WAAW;oBACnB,cAAc,EAAE,iBAAiB;oBACjC,eAAe;oBACf,SAAS,EAAE,4BAA4B,KAAK,CAAC,IAAI,EAAE;iBACnD;aACD,CAAC;QACH,CAAC;QAED,wDAAwD;QACxD,gEAAgE;QAChE,6DAA6D;QAC7D,mDAAmD;QACnD,eAAe,CAAC,WAAW,CAAC,CAAC;QAC7B,MAAM,SAAS,GAAG,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;QAClE,GAAG,CAAC,EAAE,CAAC,MAAM,CACZ,sBAAsB,KAAK,CAAC,IAAI,kCAAkC,MAAM,CAAC,SAAS,CAAC,EAAE,IAAI,IAAI,SAAS,GAAG;YACxG,YAAY,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,aAAa,GAAG,EAClE,MAAM,CACN,CAAC;QACF,cAAc,CAAC,MAAM,CAAC;YACrB,IAAI,EAAE,gBAAgB;YACtB,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YAC5B,SAAS,EAAE,KAAK,CAAC,IAAI;YACrB,OAAO,EAAE,MAAM,CAAC,SAAS,CAAC,EAAE,IAAI,IAAI,MAAM,CAAC,SAAS,CAAC;YACrD,cAAc,EAAE,iBAAiB;YACjC,YAAY,EAAE,SAAS;YACvB,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,+BAA+B,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,aAAa,GAAG;SACzG,CAAC,CAAC;QACH,wDAAwD;QACxD,UAAU,CAAC,GAAG,EAAE;YACf,MAAM;YACN,UAAU,EAAE,SAAS;YACrB,eAAe;YACf,MAAM,EAAE,KAAK;YACb,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACV,CAAC,CAAC;QAC1B,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;IACjD,CAAC;IAED,kCAAkC;IAClC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC5B,CAAC"}

package/dist/extensions/forgecli/plan.d.ts

@@ -0,0 +1,22 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { extractPersonaNames } from "./lib/frontmatter-parser.js";
+export { extractPersonaNames };
+import { checkMaterialization, type MaterializationCheck } from "./lib/manifest-checker.js";
+export { checkMaterialization, type MaterializationCheck };
+export type ArgMode = "empty" | "file" | "text";
+export interface ParsedArgs {
+    mode: ArgMode;
+    taskRef: string;
+    sourceLabel: string;
+}
+export declare function parsePlanArgs(rawArgs: string, cwd: string): ParsedArgs;
+export interface ComposeKickoffOpts {
+    workflowMd: string;
+    personaIdentity: string;
+    parsed: ParsedArgs;
+}
+export declare function composeKickoff(opts: ComposeKickoffOpts): string;
+export interface RegisterPlanOptions {
+    cwd?: string;
+}
+export declare function registerPlan(pi: ExtensionAPI, options?: RegisterPlanOptions): void;

package/dist/extensions/forgecli/plan.js

@@ -0,0 +1,167 @@
+// forge:plan — native kickoff handler (FORGE-S20-T05).
+//
+// Replaces the auto-generated stub previously installed by
+// registerAllForgeCommands (forge-commands.ts). Like S19 sprint-intake and
+// FORGE-S20-T04 enhance, this is a Kickoff Shim (Pack-04 + Pack-06):
+//   1. Reads `.forge/workflows/plan_task.md` (the materialized workflow).
+//   2. Verifies four Pack-06 materialization markers — refuses to dispatch on
+//      regression and emits a per-marker `ctx.ui.notify` so a user sees the
+//      cause.
+//   3. Loads the persona declared in the workflow's `deps.personas:`
+//      frontmatter via the FORGE-S20-T02 loader (no ad-hoc fs.readFile of
+//      `.forge/personas/`).
+//   4. Composes ONE kickoff message: persona identity, dispatch instructions
+//      (read TASK_PROMPT.md, follow workflow, write PLAN.md/PLAN-SUMMARY.json,
+//      forge_store-driven status updates), the workflow body verbatim, and
+//      argv as @<path> file ref or free-form text.
+//   5. Hands control to the LLM via `sendKickoff(pi, text)` —
+//      `deliverAs: "steer"`. Never raw `pi.sendUserMessage`.
+//
+// Per FORGE-S20 SPRINT_REQUIREMENTS Constraints and T05 AC#4: the
+// prompt-injection fallback is DELETED — no FORGE_LEGACY_KICKOFF flag, no
+// markdown-stub for this command.
+//
+// FORGE-S26-T11: pipeline step guard added. Checks task status via store-cli
+// before dispatching. --force flag bypasses the guard.
+//
+// Iron Laws:
+//   IL1 — code only under forge-cli/src/extensions/forgecli/.
+//   IL4 — no JSON.stringify-into-subagent dispatch.
+//   IL6 — no shell-string interpolation; no spawn calls here.
+//   IL7 — every failure path emits ctx.ui.notify and returns; no silent
+//         continuation.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { assertAudience } from "./audience-gate.js";
+import { discoverForgeConfig } from "./forge-root.js";
+import { sendKickoff } from "./kickoff.js";
+// FORGE-S25-T16: extracted to lib modules. Re-exported here for backward compat
+// (plan.test.ts, bundled-base-pack-markers.test.ts, run-task.ts, run-sprint.ts,
+// fix-bug.ts all import checkMaterialization / extractPersonaNames from plan.js).
+import { extractPersonaNames } from "./lib/frontmatter-parser.js";
+import { parseGuardArgs, runPipelineGuard } from "./lib/pipeline-guard.js";
+import { loadPersona, PersonaSkillLoaderError } from "./parsers/persona-skill-loader.js";
+import { loadWorkflow, WorkflowLoaderError } from "./parsers/workflow-loader.js";
+export { extractPersonaNames };
+import { checkMaterialization } from "./lib/manifest-checker.js";
+export { checkMaterialization };
+export function parsePlanArgs(rawArgs, cwd) {
+    const trimmed = (rawArgs ?? "").trim();
+    if (trimmed === "") {
+        return { mode: "empty", taskRef: "", sourceLabel: "(no input — engineer infers task from store/context)" };
+    }
+    if (trimmed.startsWith("@")) {
+        const ref = trimmed.slice(1).trim();
+        const filePath = path.isAbsolute(ref) ? ref : path.resolve(cwd, ref);
+        const seed = fs.readFileSync(filePath, "utf8");
+        return { mode: "file", taskRef: seed, sourceLabel: `(seed from file: ${ref})` };
+    }
+    return { mode: "text", taskRef: trimmed, sourceLabel: "(seed from inline text)" };
+}
+export function composeKickoff(opts) {
+    const { workflowMd, personaIdentity, parsed } = opts;
+    const sections = ["# /forge:plan", ""];
+    if (personaIdentity.trim().length > 0) {
+        sections.push(personaIdentity.trim(), "");
+    }
+    sections.push("## Dispatch", "", "Run the workflow below. Specifically:", "", "1. Read the task prompt at `engineering/sprints/<SPRINT_ID>/<TASK_ID>/TASK_PROMPT.md` (the source of truth).", "2. Query the store for the task and its sprint/feature context via `forge_store_query` — do NOT raw-read `.forge/store/`.", "3. Follow the workflow Algorithm verbatim: load context, research, plan, knowledge writeback, finalize.", "4. Write `PLAN.md` and `PLAN-SUMMARY.json` to the task directory using the `write` tool.", "5. Update task status by calling the `forge_store` MCP tool: `{command:'update-status', args:['task','<TASK_ID>','status','<new-status>']}`. Never raw-write `.forge/store/`. Do NOT bash-shell `forge store ...`.", "6. Honour Pack-06 Read/Write/Ask/Store discipline: writes go via the `forge_store` MCP tool (canonical 2-positional write: `args:['<entity>','<json>']`, id INSIDE json); in-conversation clarifications use `forge_ask_user`.");
+    sections.push("", "---", "", "## Workflow", "", workflowMd.trim(), "", "---");
+    if (parsed.mode === "empty") {
+        sections.push("", "## Input", "", "(no seed — infer task from sprint context and store)");
+    }
+    else {
+        sections.push("", `## Input — ${parsed.sourceLabel}`, "", parsed.taskRef.trim());
+    }
+    return sections.join("\n");
+}
+// Registration -------------------------------------------------------------
+const WORKFLOW_REL_PATH = path.join(".forge", "workflows", "plan_task.md");
+export function registerPlan(pi, options = {}) {
+    pi.registerCommand("forge:plan", {
+        description: "Run the plan-task workflow for a Forge task. " +
+            "Usage: /forge:plan [@<file> | <free-form text>]. " +
+            "Empty args → engineer infers the task from sprint/store context.",
+        async handler(args, ctx) {
+            const cwd = options.cwd ?? process.cwd();
+            const workflowPath = path.join(cwd, WORKFLOW_REL_PATH);
+            // Pipeline step guard (FORGE-S26-T11): check task state before dispatching.
+            const guardParsed = parseGuardArgs(args);
+            if (!guardParsed.force) {
+                const forgeConfig = discoverForgeConfig(cwd);
+                if (forgeConfig) {
+                    const guard = runPipelineGuard("plan", guardParsed.taskIdHint, forgeConfig.forgeRoot, cwd);
+                    if (guard.blocked) {
+                        ctx.ui.notify(guard.message, "error");
+                        return;
+                    }
+                }
+            }
+            // Use cleanArgs (--force stripped) for workflow dispatch
+            const effectiveArgs = guardParsed.cleanArgs;
+            let workflowMd;
+            let workflowAudience;
+            try {
+                const loaded = loadWorkflow(workflowPath);
+                workflowMd = loaded.rawMarkdown;
+                workflowAudience = loaded.audience;
+            }
+            catch (err) {
+                if (err instanceof WorkflowLoaderError) {
+                    if (err.code === "missing_file") {
+                        ctx.ui.notify(`× forge:plan — workflow not found at ${WORKFLOW_REL_PATH}; run /forge:init or /forge:rebuild first.`, "error");
+                    }
+                    else {
+                        ctx.ui.notify(`× forge:plan — workflow load failed (${err.code}): ${err.message}`, "error");
+                    }
+                    return;
+                }
+                const e = err;
+                ctx.ui.notify(`× forge:plan — failed to read workflow: ${e.message ?? "unknown"}`, "error");
+                return;
+            }
+            let parsed;
+            try {
+                parsed = parsePlanArgs(effectiveArgs, cwd);
+            }
+            catch (err) {
+                const e = err;
+                ctx.ui.notify(`× forge:plan — failed to read seed: ${e.message ?? "unknown"}`, "error");
+                return;
+            }
+            const check = checkMaterialization(workflowPath, workflowMd);
+            if (!check.ok) {
+                for (const marker of check.missing) {
+                    ctx.ui.notify(`× workflow regression: ${marker} not found in ${workflowPath}`, "error");
+                }
+                return;
+            }
+            const personas = extractPersonaNames(workflowMd);
+            let personaIdentity = "";
+            if (personas.length > 0) {
+                try {
+                    const persona = loadPersona(personas[0], { cwd });
+                    personaIdentity = persona.identity;
+                }
+                catch (err) {
+                    if (err instanceof PersonaSkillLoaderError) {
+                        ctx.ui.notify(`× forge:plan — persona '${personas[0]}' load failed (${err.code}): ${err.message}`, "error");
+                        return;
+                    }
+                    const e = err;
+                    ctx.ui.notify(`× forge:plan — persona load error: ${e.message ?? "unknown"}`, "error");
+                    return;
+                }
+            }
+            if (!assertAudience({ workflowName: "plan_task", audience: workflowAudience }, ctx)) {
+                return;
+            }
+            const kickoff = composeKickoff({
+                workflowMd,
+                personaIdentity,
+                parsed,
+            });
+            sendKickoff(pi, kickoff);
+        },
+    });
+}
+//# sourceMappingURL=plan.js.map

package/dist/extensions/forgecli/plan.js.map

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

package/dist/extensions/forgecli/quiz-agent.d.ts

@@ -0,0 +1,17 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export interface ParsedQuizAgentArgs {
+    mode: "empty" | "file" | "text";
+    topicSeed: string;
+    sourceLabel: string;
+}
+export declare function parseQuizAgentArgs(rawArgs: string, cwd: string): ParsedQuizAgentArgs;
+export interface ComposeQuizAgentKickoffOpts {
+    commandMd: string;
+    parsed: ParsedQuizAgentArgs;
+}
+export declare function composeQuizAgentKickoff(opts: ComposeQuizAgentKickoffOpts): string;
+export interface RegisterQuizAgentOptions {
+    forgeRoot: string | null;
+    cwd?: string;
+}
+export declare function registerQuizAgent(pi: ExtensionAPI, options: RegisterQuizAgentOptions): void;

package/dist/extensions/forgecli/quiz-agent.js

@@ -0,0 +1,98 @@
+// forge:quiz-agent — native kickoff handler (FORGE-S23-T11).
+//
+// Replaces the auto-generated stub previously installed by
+// registerAllForgeCommands (forge-commands.ts). Kickoff Shim archetype
+// (Pack-04 + Pack-06): single LLM handoff in current context, no fork.
+//
+// Ultra-thin shim: reads commands/quiz-agent.md and dispatches.
+// Optional topic seed or @<file> narrows the quiz scope.
+//
+// Workflow source: <forgeRoot>/commands/quiz-agent.md (command file).
+// Note: quiz_agent.md also exists in .forge/workflows/ but lacks 3 of
+// 4 Pack-06 markers. Using the command file for consistency with the
+// other 5 handlers in this batch. Follow-up task can upgrade to read
+// from .forge/workflows/quiz_agent.md when it has all markers.
+//
+// File-existence check only — command files lack Pack-06 workflow markers.
+//
+// Iron Laws:
+//   IL1 — code only under forge-cli/src/extensions/forgecli/.
+//   IL4 — no JSON.stringify-into-subagent dispatch.
+//   IL6 — no shell-string interpolation; no spawn calls here.
+//   IL7 — every failure path emits ctx.ui.notify and returns; no silent
+//         continuation.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { sendKickoff } from "./kickoff.js";
+export function parseQuizAgentArgs(rawArgs, cwd) {
+    const trimmed = (rawArgs ?? "").trim();
+    if (!trimmed) {
+        return { mode: "empty", topicSeed: "", sourceLabel: "(no topic — full KB quiz)" };
+    }
+    if (trimmed.startsWith("@")) {
+        const ref = trimmed.slice(1).trim();
+        const filePath = path.isAbsolute(ref) ? ref : path.resolve(cwd, ref);
+        const topicSeed = fs.readFileSync(filePath, "utf8");
+        return { mode: "file", topicSeed, sourceLabel: `(topic from file: ${ref})` };
+    }
+    return { mode: "text", topicSeed: trimmed, sourceLabel: "(topic from inline text)" };
+}
+export function composeQuizAgentKickoff(opts) {
+    const { commandMd, parsed } = opts;
+    const sections = ["# /forge:check-agent", ""];
+    sections.push("## Dispatch", "");
+    sections.push("Run the quiz-agent workflow below to verify this agent has read and understood the project knowledge base. " +
+        "Ask factual questions about the project's architecture, entity model, and sprint conventions — do not accept vague answers. " +
+        "Report pass/fail with specific evidence.");
+    sections.push("", "---", "", "## Command", "", commandMd.trim(), "", "---");
+    if (parsed.mode === "empty") {
+        sections.push("", "## Topic", "", "(no topic specified — quiz the full KB scope)");
+    }
+    else {
+        sections.push("", `## Topic — ${parsed.sourceLabel}`, "", parsed.topicSeed.trim());
+    }
+    return sections.join("\n");
+}
+// ── Registration ──────────────────────────────────────────────────────────
+const COMMAND_NAME = "quiz-agent";
+export function registerQuizAgent(pi, options) {
+    pi.registerCommand("forge:check-agent", {
+        description: "Verify an agent has loaded and understood the project knowledge base — run a short factual quiz. " +
+            "Usage: /forge:check-agent [@<file> | <topic>]. Empty args run a full KB quiz.",
+        async handler(args, ctx) {
+            const { forgeRoot } = options;
+            const cwd = options.cwd ?? process.cwd();
+            if (!forgeRoot) {
+                ctx.ui.notify("× forge:check-agent — no Forge project at cwd; run /forge:init to bootstrap", "warning");
+                return;
+            }
+            const commandPath = path.join(forgeRoot, "commands", `${COMMAND_NAME}.md`);
+            let commandMd;
+            try {
+                commandMd = fs.readFileSync(commandPath, "utf8");
+            }
+            catch (err) {
+                const e = err;
+                if (e.code === "ENOENT") {
+                    ctx.ui.notify(`× forge:check-agent — command file not found at commands/${COMMAND_NAME}.md; run /forge:init or /forge:rebuild first.`, "error");
+                }
+                else {
+                    ctx.ui.notify(`× forge:check-agent — failed to read command file: ${e.message ?? "unknown error"}`, "error");
+                }
+                return;
+            }
+            let parsed;
+            try {
+                parsed = parseQuizAgentArgs(args, cwd);
+            }
+            catch (err) {
+                const e = err;
+                ctx.ui.notify(`× forge:check-agent — failed to parse args: ${e.message ?? "unknown"}`, "error");
+                return;
+            }
+            const kickoff = composeQuizAgentKickoff({ commandMd, parsed });
+            sendKickoff(pi, kickoff);
+        },
+    });
+}
+//# sourceMappingURL=quiz-agent.js.map

package/dist/extensions/forgecli/quiz-agent.js.map

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

package/dist/extensions/forgecli/read-command.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export declare function registerReadCommand(pi: ExtensionAPI, forgeRoot: string | null): void;

package/dist/extensions/forgecli/read-command.js

@@ -0,0 +1,100 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { startReviewServer } from "./review-server.js";
+import { resolveEntityRef, resolveToolDir } from "./store-resolver.js";
+function isNonInteractive() {
+    return process.env.FORGE_YES === "1" || process.env.FORGE_NON_INTERACTIVE === "1";
+}
+export function registerReadCommand(pi, forgeRoot) {
+    pi.registerCommand("forge:read", {
+        description: "Review a Forge artifact in the browser and provide inline feedback",
+        async handler(args, ctx) {
+            if (!forgeRoot) {
+                ctx.ui.notify("forge:read — no Forge project at cwd; run /forge:init to bootstrap", "warning");
+                return;
+            }
+            if (isNonInteractive()) {
+                ctx.ui.notify("forge:read requires interactive mode (browser review). Unset FORGE_YES/FORGE_NON_INTERACTIVE.", "error");
+                return;
+            }
+            const arg = args.trim();
+            if (!arg) {
+                ctx.ui.notify("Usage: /forge:read <task-id|sprint-id|@path|natural language>\n" +
+                    "Examples: /forge:read S01-T01  |  /forge:read S01  |  " +
+                    "/forge:read @engineering/sprints/HELLO-S01/HELLO-S01-T01  |  " +
+                    "/forge:read the i18n task", "error");
+                return;
+            }
+            const toolDir = resolveToolDir(forgeRoot);
+            const resolved = await resolveEntityRef(arg, toolDir, ctx.cwd, {
+                ctx,
+                statusLabel: "forge:read",
+            }).catch((err) => {
+                ctx.ui.setStatus("forge:read", undefined);
+                ctx.ui.notify(`Store query failed: ${err.message}`, "error");
+                return null;
+            });
+            if (!resolved)
+                return;
+            let taskDir;
+            let label;
+            if ("dir" in resolved) {
+                taskDir = resolved.dir;
+                label = path.basename(taskDir);
+            }
+            else {
+                const item = resolved.item;
+                if (!item.fileRefs?.md) {
+                    ctx.ui.notify(`No markdown index found for ${item.id}`, "error");
+                    return;
+                }
+                taskDir = path.dirname(path.join(ctx.cwd, item.fileRefs.md));
+                label = `${item.id} — ${item.title}`;
+                ctx.ui.notify(`Resolved to ${item.type}: ${item.id} (${item.title})`, "info");
+            }
+            let files;
+            try {
+                files = await fs.readdir(taskDir);
+            }
+            catch {
+                ctx.ui.notify(`No artifacts found at ${taskDir}`, "warning");
+                return;
+            }
+            const mdFiles = files.filter((f) => f.endsWith(".md"));
+            if (mdFiles.length === 0) {
+                ctx.ui.notify(`No markdown artifacts found at ${taskDir}`, "info");
+                return;
+            }
+            const selectedFile = await ctx.ui.select(`Select artifact to review for ${label}:`, mdFiles);
+            if (!selectedFile)
+                return;
+            const artifactPath = path.join(taskDir, selectedFile);
+            ctx.ui.notify(`Starting local review server for ${selectedFile}…`, "info");
+            ctx.ui.setStatus("forge:read", "Waiting for browser review…");
+            try {
+                const feedback = await startReviewServer(artifactPath, `${label} — ${selectedFile}`);
+                ctx.ui.setStatus("forge:read", undefined);
+                if (feedback && feedback.length > 0) {
+                    ctx.ui.notify(`Received ${feedback.length} feedback item(s). Sending to Forge…`, "info");
+                    const itemType = "item" in resolved ? resolved.item.type : "artifact";
+                    const itemId = "item" in resolved ? resolved.item.id : label;
+                    let promptText = `I have reviewed the artifact \`${selectedFile}\` for ${itemType} ${itemId}. Here is my inline feedback:\n\n`;
+                    for (const fb of feedback) {
+                        promptText += `> **Text:** "${fb.selectedText}"\n`;
+                        promptText += `> **Feedback:** ${fb.comment}\n\n`;
+                    }
+                    promptText += `Please process this feedback and update the artifact accordingly.`;
+                    pi.sendUserMessage(promptText, { deliverAs: "steer" });
+                }
+                else {
+                    ctx.ui.notify("Review completed with no feedback submitted.", "info");
+                }
+            }
+            catch (err) {
+                ctx.ui.setStatus("forge:read", undefined);
+                ctx.ui.notify(`forge:read error: ${err.message}`, "error");
+            }
+        },
+    });
+}
+//# sourceMappingURL=read-command.js.map

package/dist/extensions/forgecli/read-command.js.map

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