@mgiles/perk 3.1.0 → 3.3.0

package/extension/pi/v1/delivery/stackRecover.ts

@@ -0,0 +1,265 @@
+// The stacked-delivery recovery bindings (contracts.md §8.51): the `objective_stack_recover`
+// typed tool and the `/objective-recover` driving command over the Python cold worker
+// `perk objective stack recover` (mutations canonical in Python — recovery classification,
+// roll-forward, and the sweep are cold-plane facts; the warm layer decodes, renders, and
+// delegates). The §8.56 reconcile decision (`decideStackReconcile`) rides every successful
+// envelope — recover's journal-complete re-emission may carry evidence (the death-after-close
+// repair) and must drive exactly like a landing close.
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { STACK_NO_OBJECTIVE_MESSAGE } from "../../../delivery/stackObjective.ts";
+import { decideStackReconcile } from "../../../delivery/stackReconcile.ts";
+import {
+  booleanField,
+  type ColdJson,
+  numberField,
+  objectField,
+  objectListField,
+  runColdDoor,
+  stringField,
+  stringListField,
+} from "../../../substrate/coldDoor.ts";
+import { render } from "../../../substrate/prompts.ts";
+import { failFor, ok } from "../../../substrate/result.ts";
+import type { ToolGating } from "../../../substrate/toolGating.ts";
+import { booleanParam, idParam, paramsOf, stringParam } from "../../../substrate/toolParams.ts";
+import { resolveStackObjective } from "../../../substrate/workflowState.ts";
+import { driveStackReconcile, evidenceLines, registerStackDrivingCommand } from "./stackDrive.ts";
+import type { StackResult } from "./stackSync.ts";
+
+/** Render the `stack recover --json` envelope (classification rows + sweep) — fully lenient. */
+export function renderRecoverOutcome(payload: ColdJson): string {
+  const lines: string[] = [];
+  const dryRun = booleanField(payload, "dry_run") === true;
+  if (dryRun) lines.push("dry run: nothing was concluded, journaled, or swept");
+  const operations = objectListField(payload, "operations");
+  if (operations.length === 0) lines.push("no unresolved operations");
+  for (const row of operations) {
+    lines.push(
+      `${stringField(row, "operation_id") ?? "?"} (${stringField(row, "kind") ?? "?"}, ` +
+        `prepared ${stringField(row, "prepared_created") ?? "?"}): ` +
+        `${stringField(row, "classification") ?? "?"} → ${stringField(row, "action") ?? "?"}`,
+    );
+    const detail = stringField(row, "detail");
+    if (detail !== undefined) lines.push(`  ${detail}`);
+    // The external-prefix structured preview (dry-run included — what --accept-prefix records).
+    for (const merged of objectListField(row, "merged_layers")) {
+      const sha = stringField(merged, "merge_commit_sha") ?? "?";
+      lines.push(
+        `  merged: ${stringField(merged, "node_id") ?? "?"} ` +
+          `pr #${numberField(merged, "pr_number") ?? "?"} as ${sha.slice(0, 12)}`,
+      );
+    }
+    for (const rem of objectListField(row, "remainder")) {
+      const head = stringField(rem, "head_sha") ?? "?";
+      lines.push(
+        `  remainder: pr #${numberField(rem, "pr_number") ?? "?"} ` +
+          `${stringField(rem, "state") ?? "?"} at ${head.slice(0, 12)}`,
+      );
+    }
+  }
+  if (booleanField(payload, "selection_required") === true) {
+    lines.push('several operations are unresolved — re-run with operation: "<ULID>" to act on one');
+  }
+  for (const row of objectListField(payload, "landed_layers")) {
+    const finalized = booleanField(row, "finalized");
+    const verdict =
+      finalized === true
+        ? "finalized"
+        : finalized === false
+          ? "FINALIZE FAILED (see notes)"
+          : "would finalize";
+    const sha = stringField(row, "merge_commit_sha") ?? "?";
+    lines.push(
+      `landed ${stringField(row, "node_id") ?? "?"} plan #${stringField(row, "plan_id") ?? "?"} ` +
+        `(pr #${numberField(row, "pr_number") ?? "?"}, merged as ${sha.slice(0, 12)}): ${verdict}`,
+    );
+  }
+  if (booleanField(payload, "objective_closed") === true) {
+    const id = stringField(objectField(payload, "objective") ?? {}, "id") ?? "?";
+    lines.push(`objective #${id} complete — closed`);
+  }
+  lines.push(...evidenceLines(payload));
+  lines.push(...stringListField(payload, "notes").map((note) => `note: ${note}`));
+  const sweepSkipped = stringField(payload, "sweep_skipped");
+  if (sweepSkipped !== undefined) {
+    lines.push(`sweep skipped: ${sweepSkipped}`);
+  } else {
+    const worktrees = stringListField(payload, "swept_worktrees");
+    const refs = stringListField(payload, "swept_refs");
+    if (worktrees.length > 0 || refs.length > 0) {
+      const verb = dryRun ? "would sweep" : "swept";
+      lines.push(
+        `${verb} ${worktrees.length} orphaned worktree(s) and ${refs.length} orphaned ref(s)`,
+      );
+    }
+  }
+  for (const failure of objectListField(payload, "sweep_failures")) {
+    lines.push(
+      `sweep failure: ${stringField(failure, "target") ?? "?"} ` +
+        `(${stringField(failure, "error") ?? "?"})`,
+    );
+  }
+  return lines.join("\n");
+}
+
+/** The seed guidance the warm `/objective-recover` injects (classify → human approval → act). */
+export function objectiveRecoverGuidance(objective: string): string {
+  return render("stages/objective-recover.md", { objective });
+}
+
+interface RecoverToolParams {
+  objective: string | undefined;
+  operation: string | undefined;
+  dryRun: boolean;
+  abandon: boolean;
+  acceptPrefix: boolean;
+  confirm: boolean;
+}
+
+function decodeRecoverParams(params: unknown): RecoverToolParams | null {
+  const p = paramsOf(params);
+  if (p === null) return null;
+  const objective = idParam(p, "objective");
+  const operation = stringParam(p, "operation");
+  const dryRun = booleanParam(p, "dry_run");
+  const abandon = booleanParam(p, "abandon");
+  const acceptPrefix = booleanParam(p, "accept_prefix");
+  const confirm = booleanParam(p, "confirm");
+  if (objective === null || operation === null || dryRun === null || abandon === null) return null;
+  if (acceptPrefix === null || confirm === null) return null;
+  if (dryRun && (abandon || acceptPrefix)) return null; // the CLI matrix: preview first, then act
+  if (abandon && acceptPrefix) return null; // mutually exclusive conclusions
+  return {
+    objective: objective ?? undefined,
+    operation: operation ?? undefined,
+    dryRun: dryRun ?? false,
+    abandon: abandon ?? false,
+    acceptPrefix: acceptPrefix ?? false,
+    confirm: confirm ?? false,
+  };
+}
+
+/** The recover argv: report/dry-run modes pass neither conclusion flag nor `--yes`. */
+export function buildStackRecoverArgs(objective: string, p: RecoverToolParams): string[] {
+  const args = ["objective", "stack", "recover", objective];
+  if (p.operation !== undefined) args.push("--operation", p.operation);
+  if (p.dryRun) args.push("--dry-run");
+  if (p.abandon) args.push("--abandon", "--yes");
+  if (p.acceptPrefix) args.push("--accept-prefix", "--yes");
+  args.push("--json");
+  return args;
+}
+
+async function stackRecover(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  p: RecoverToolParams,
+): Promise<StackResult> {
+  const fail = failFor(ctx, "objective-recover", "objective_stack_recover");
+  if (p.abandon && !p.confirm) {
+    return fail(
+      "abandoning an unresolved operation journals its permanent conclusion — preview with " +
+        "dry_run: true, then pass confirm: true on explicit human approval.",
+      "confirmation_required",
+    );
+  }
+  if (p.acceptPrefix && !p.confirm) {
+    return fail(
+      "accepting an externally merged prefix journals a permanent degraded-atomicity breach — " +
+        "preview with dry_run: true, then pass confirm: true on explicit human approval.",
+      "confirmation_required",
+    );
+  }
+  const objective = resolveStackObjective(p.objective, ctx);
+  if (objective === null) return fail(STACK_NO_OBJECTIVE_MESSAGE, "no_objective");
+  const r = await runColdDoor<ColdJson>(pi, ctx, buildStackRecoverArgs(objective, p), {
+    label: "perk objective stack recover",
+    decode: (payload) => payload,
+  });
+  if (!r.ok) return fail(r.message, r.errorType);
+  const decision = decideStackReconcile(r.data);
+  if (decision.drive) driveStackReconcile(pi, ctx, decision.evidence);
+  return ok(renderRecoverOutcome(r.data), { objective });
+}
+
+const RECOVER_TOOL_GUIDELINES = [
+  "Call objective_stack_recover inside the /objective-recover flow: dry_run: true classifies and reports; the real call concludes deterministically (all-after rolls forward — LAND included) and sweeps orphaned residue.",
+  "abandon: true requires confirm: true (explicit human approval) and an all-before classification — never abandon to make a report go away; mixed classifications need human investigation.",
+  "accept_prefix: true requires confirm: true and an external_prefix LAND classification — it records the externally merged prefix as a degraded-atomicity breach; then cascade the remainder with objective_stack_sync { base: true } and land it with objective_stack_land.",
+];
+
+/** Install the stacked-delivery recovery bindings: the `objective_stack_recover` typed tool +
+ * the `/objective-recover` driving command. */
+export function installStackRecoverBindings(pi: ExtensionAPI, gating: ToolGating): void {
+  pi.registerTool({
+    name: "objective_stack_recover",
+    label: "Objective stack recover",
+    description:
+      "Conclude an objective's unresolved stack operations (classify against fresh authority; " +
+      "roll forward what verified complete — LAND included; abandon with proof under " +
+      "abandon+confirm; accept an externally merged LAND prefix as a recorded breach under " +
+      "accept_prefix+confirm) and sweep orphaned sync residue. dry_run reports without acting. " +
+      "Delegates to the perk cold door.",
+    promptSnippet: "Conclude unresolved stack operations + sweep orphaned residue",
+    promptGuidelines: RECOVER_TOOL_GUIDELINES,
+    executionMode: "sequential",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        objective: {
+          type: ["string", "number"],
+          description: "The objective issue id (inferred from the session when omitted).",
+        },
+        operation: {
+          type: "string",
+          description: "The target operation ULID (required when several are unresolved).",
+        },
+        dry_run: {
+          type: "boolean",
+          description: "Classify and report only — no roll-forward, no abandon, no sweep.",
+        },
+        abandon: {
+          type: "boolean",
+          description: "Abandon the target operation (requires an all-before proof + confirm).",
+        },
+        accept_prefix: {
+          type: "boolean",
+          description:
+            "Accept an externally merged LAND prefix as a recorded degraded-atomicity breach " +
+            "(requires an external_prefix classification + confirm).",
+        },
+        confirm: {
+          type: "boolean",
+          description: "Explicit human approval (required with abandon or accept_prefix).",
+        },
+      },
+    },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const decoded = decodeRecoverParams(params);
+      if (decoded === null) {
+        return failFor(
+          ctx,
+          "objective-recover",
+          "objective_stack_recover",
+        )(
+          "objective_stack_recover takes { objective?, operation?, dry_run?, abandon?, " +
+            "accept_prefix?, confirm? } — dry_run composes with neither conclusion flag, and " +
+            "abandon and accept_prefix are mutually exclusive",
+          "bad_input",
+        );
+      }
+      return stackRecover(pi, ctx, decoded);
+    },
+  });
+
+  registerStackDrivingCommand(pi, gating, {
+    name: "objective-recover",
+    description:
+      "Drive stack recovery: classify unresolved operations, present the report, conclude via " +
+      "the typed recover tool on explicit approval. Pass an objective number (else the active " +
+      "objective).",
+    guidance: objectiveRecoverGuidance,
+  });
+}

package/extension/pi/v1/delivery/stackStatus.ts

@@ -0,0 +1,237 @@
+// The stacked-delivery status read (contracts.md §8.51): the `objective_stack_status` tool +
+// the `/objective-stack` command over the Python cold worker `perk objective stack status`
+// (read-only end to end — the command works in every session, including gate-on; the tool stays
+// deliberately gate-off, documented in toolGating.ts). Pure decoding + rendering + delegation —
+// no feature operation backs this module (zero-policy passthrough); the mutating stack family
+// lives in the sibling adapters (stackSync.ts / stackRecover.ts / stackLand.ts over the
+// `delivery/` feature ops, with the shared drive helpers in stackDrive.ts).
+//
+// Objective inference: explicit param/argument → workflow `active_objective` → plan-ref
+// `objective_id` (`resolveStackObjective`); the warm layer always passes the resolved objective
+// explicitly to the cold door. Cold-envelope decodes are lenient/render-only — the fully-lenient
+// identity decode keeps the decode-rejection arm unreachable (`bad_output` remains reachable
+// only via unparseable/non-object stdout, owned by the cold-door seam).
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  parseStackObjectiveArg,
+  STACK_NO_OBJECTIVE_MESSAGE,
+} from "../../../delivery/stackObjective.ts";
+import {
+  booleanField,
+  type ColdJson,
+  numberField,
+  objectField,
+  objectListField,
+  runColdDoor,
+  stringField,
+  stringListField,
+} from "../../../substrate/coldDoor.ts";
+import { registerPerkCommand } from "../../../substrate/command.ts";
+import { failFor, ok, type Result } from "../../../substrate/result.ts";
+import { idParam, paramsOf } from "../../../substrate/toolParams.ts";
+import { resolveStackObjective } from "../../../substrate/workflowState.ts";
+import { report } from "../../../surfaces/report.ts";
+
+/** The lenient finding-row render shared with the landing readiness preview
+ * (stackLand.ts imports it — the ONE copy; the door-era duplicate died with the door). */
+export function findingLines(train: ColdJson, key: string): string[] {
+  const rows = objectListField(train, key);
+  if (rows.length === 0) return [];
+  return [
+    `${key}:`,
+    ...rows.map((f) => `  - [${stringField(f, "code") ?? "?"}] ${stringField(f, "message") ?? ""}`),
+  ];
+}
+
+/** Render the `stack status --json` envelope (train + operations + continuation + residue) —
+ * fully lenient: a missing/mistyped field degrades that line, never the render. */
+export function renderStackStatus(payload: ColdJson): string {
+  const lines: string[] = [];
+  const id = stringField(objectField(payload, "objective") ?? {}, "id") ?? "?";
+  const noTrain = stringField(payload, "no_train");
+  if (noTrain !== undefined) lines.push(`Objective #${id}: ${noTrain}`);
+  const train = objectField(payload, "train");
+  if (train !== undefined) {
+    const layers = objectListField(train, "layers");
+    const landedLen = numberField(train, "landed_prefix_len") ?? 0;
+    const landedNote = landedLen > 0 ? `, landed ${landedLen}` : "";
+    lines.push(
+      `Objective #${id}: stacked delivery train (base ${stringField(train, "base") ?? "?"}, ` +
+        `published prefix ${numberField(train, "published_prefix_len") ?? "?"}/${layers.length}` +
+        `${landedNote})`,
+    );
+    layers.forEach((layer, index) => {
+      const parts = [stringField(layer, "node_id") ?? "?"];
+      parts.push(stringField(layer, "branch") ?? "no branch");
+      const pr = numberField(layer, "pr_number");
+      if (pr !== undefined) parts.push(`pr #${pr}`);
+      parts.push(`[${stringField(layer, "publication") ?? "?"}]`);
+      const handoff = stringField(layer, "handoff");
+      if (handoff !== undefined && handoff !== "not_applicable") parts.push(`handoff ${handoff}`);
+      lines.push(`  ${index + 1}. ${parts.join(" ")}`);
+    });
+    const readiness = objectField(train, "next_build_ready");
+    if (readiness !== undefined) {
+      if (booleanField(readiness, "ready") === true) {
+        lines.push(`  next build-ready: ${stringField(readiness, "node_id") ?? "?"}`);
+      } else {
+        lines.push(`  build blocked: ${stringField(readiness, "reason") ?? "?"}`);
+      }
+    }
+    // The additive planning_gate block (contracts §8.46): render the handoff rows from their
+    // pinned fields only — leniently (missing/mistyped fields degrade, never reject); the
+    // technical rows already ride the build-blocked line/findings.
+    const gate = objectField(train, "planning_gate");
+    if (gate !== undefined && booleanField(gate, "ready") !== true) {
+      const gatedNode = stringField(gate, "node_id") ?? "?";
+      for (const row of objectListField(gate, "blockers")) {
+        if (stringField(row, "kind") !== "handoff") continue;
+        const state = stringField(row, "handoff_state") ?? "?";
+        let detail =
+          `${stringField(row, "dependency_node_id") ?? "?"} ` +
+          `(plan #${stringField(row, "plan") ?? "?"}, PR #${numberField(row, "pr") ?? "?"}) — ` +
+          state;
+        const stamped = stringField(row, "stamped_head");
+        const current = stringField(row, "current_head");
+        if (state === "stale" && stamped !== undefined && current !== undefined) {
+          detail += `; stamped ${stamped.slice(0, 12)} ≠ head ${current.slice(0, 12)}`;
+        }
+        const remediation = stringField(row, "remediation") ?? "?";
+        lines.push(
+          `  planning gated: ${gatedNode} waits on ${detail}; record the handoff: ${remediation}`,
+        );
+      }
+    }
+    lines.push(...findingLines(train, "blockers"));
+    lines.push(...findingLines(train, "information"));
+  }
+  for (const op of objectListField(payload, "operations")) {
+    lines.push(
+      `unresolved operation: ${stringField(op, "operation_id") ?? "?"} ` +
+        `(${stringField(op, "kind") ?? "?"}, prepared ${stringField(op, "prepared_created") ?? "?"})`,
+    );
+  }
+  const continuation = objectField(payload, "continuation");
+  if (continuation !== undefined) {
+    if (booleanField(continuation, "parseable") === true) {
+      lines.push(
+        `pending continuation: operation ${stringField(continuation, "operation_id") ?? "?"} ` +
+          `stopped on node ${stringField(continuation, "conflict_node_id") ?? "?"} ` +
+          `(worktree ${stringField(continuation, "worktree_path") ?? "?"})`,
+      );
+    } else {
+      lines.push(
+        `pending continuation: UNPARSEABLE manifest at ${
+          stringField(continuation, "manifest_path") ?? "?"
+        }`,
+      );
+    }
+    if (booleanField(continuation, "parseable") === true) {
+      lines.push(
+        "  resume via objective_stack_sync { continue: true }, discard via { abort: true }, or " +
+          "dispatch automated resolution via { resolve: true } (on explicit human request)",
+      );
+    } else {
+      lines.push(
+        "  resume via objective_stack_sync { continue: true }, or discard via { abort: true }",
+      );
+    }
+  }
+  const orphans = objectField(payload, "orphaned_residue");
+  if (orphans !== undefined) {
+    const worktrees = stringListField(orphans, "worktrees");
+    const refs = stringListField(orphans, "refs");
+    if (booleanField(orphans, "observed") === false) {
+      lines.push(`orphaned residue: not observed — ${stringField(orphans, "reason") ?? "?"}`);
+    } else if (worktrees.length > 0 || refs.length > 0) {
+      lines.push(
+        `orphaned residue: ${worktrees.length} worktree(s), ${refs.length} ref(s) — ` +
+          "sweep via objective_stack_recover",
+      );
+    }
+  }
+  return lines.length > 0 ? lines.join("\n") : `Objective #${id}: empty status report`;
+}
+
+/** The one status cold-door read both surfaces share (label keeps every fallback/failure text
+ * byte-compatible; the identity decode keeps the envelope render-only). */
+function readStackStatus(pi: ExtensionAPI, ctx: ExtensionContext, objective: string) {
+  return runColdDoor<ColdJson>(pi, ctx, ["objective", "stack", "status", objective, "--json"], {
+    label: "perk objective stack status",
+    decode: (payload) => payload,
+  });
+}
+
+/** The tool implementation: resolve, delegate, render, never throw. */
+async function stackStatus(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  objectiveParam: string | undefined,
+): Promise<Result<{ objective: string }>> {
+  const fail = failFor(ctx, "objective-stack", "objective_stack_status");
+  const objective = resolveStackObjective(objectiveParam, ctx);
+  if (objective === null) return fail(STACK_NO_OBJECTIVE_MESSAGE, "no_objective");
+  const r = await readStackStatus(pi, ctx, objective);
+  if (!r.ok) return fail(r.message, r.errorType);
+  return ok(renderStackStatus(r.data), { objective });
+}
+
+/** Install the stacked-delivery status read: the `objective_stack_status` tool (strict
+ * tri-state param decode, non-terminating) + the `/objective-stack` command. */
+export function installStackStatusBindings(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "objective_stack_status",
+    label: "Objective stack status",
+    description:
+      "Report an objective's stacked delivery train: layers, publication states, build " +
+      "readiness, unresolved operations, pending continuation, and orphaned sync residue. " +
+      "Read-only (delegates to the perk cold door).",
+    promptSnippet: "Report the objective's stacked delivery train (read-only)",
+    promptGuidelines: [
+      "objective_stack_status is read-only — call it freely to inspect the delivery train, unresolved operations, pending continuations, and orphaned residue (objective inferred when omitted).",
+    ],
+    executionMode: "sequential",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        objective: {
+          type: ["string", "number"],
+          description: "The objective issue id (inferred from the session when omitted).",
+        },
+      },
+    },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const p = paramsOf(params);
+      const objective = p === null ? null : idParam(p, "objective");
+      if (p === null || objective === null) {
+        return failFor(
+          ctx,
+          "objective-stack",
+          "objective_stack_status",
+        )("objective_stack_status takes { objective?: <id> }", "bad_input");
+      }
+      return stackStatus(pi, ctx, objective);
+    },
+  });
+
+  registerPerkCommand(pi, "objective-stack", {
+    description:
+      "Show an objective's stacked delivery train (status, operations, continuation, residue). " +
+      "Pass an objective number (else the active objective, else the plan-ref's).",
+    handler: async (args, ctx) => {
+      const objective = resolveStackObjective(parseStackObjectiveArg(args ?? "") ?? undefined, ctx);
+      if (objective === null) {
+        report(ctx, "objective-stack", "warning", STACK_NO_OBJECTIVE_MESSAGE);
+        return;
+      }
+      const r = await readStackStatus(pi, ctx, objective);
+      if (!r.ok) {
+        report(ctx, "objective-stack", "error", r.message, { alsoLog: true });
+        return;
+      }
+      report(ctx, "objective-stack", "info", renderStackStatus(r.data));
+    },
+  });
+}