@mgiles/perk 3.1.0 → 3.3.0

package/extension/session/lifecycleGates.ts

@@ -0,0 +1,64 @@
+// Pi-free session-lifecycle gate policy: the planning-stage lifecycle-door refusal (the shared
+// first check of the warm /submit, /address, /land, and /learn doors) and the plan-read handoff
+// priming for a fresh implement session. The Pi registration half (the session_before_fork/
+// switch hooks + the guard-only `/implement` command) lives in `pi/v1/lifecycleGates.ts`; this
+// module carries the policy those adapters apply.
+
+import type { PlanRef } from "../substrate/cache.ts";
+import { planReadInstruction, render } from "../substrate/prompts.ts";
+import { type BranchSource, branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
+
+// The planning stages whose sessions never legitimately run lifecycle doors. After an approved
+// save, a still-live planning session holds TWO plan identities — the cwd binding (a positioned
+// stacked session's predecessor checkout, read via readPlanRef(ctx.cwd)) and the just-saved plan
+// on active_plan_ref — so a door invocation there could act on the predecessor. At the repo root
+// the same invocation fails confusingly today; the refusal is honest in both shapes.
+const PLANNING_STAGES = new Set(["plan", "objective-plan"]);
+
+/**
+ * The planning-stage lifecycle-door refusal (the shared first check of the warm /submit,
+ * /address, /land, and /learn doors): when this session's workflow-state `stage` is a planning
+ * stage, return the refusal message directing the human at the fresh-session implement door;
+ * `null` otherwise (non-planning stages — and stage-less sessions — are unaffected). Fail-CLOSED
+ * on an unreadable branch: without the state this guard cannot prove the session is not a
+ * positioned planning session (whose cwd binding is the PREDECESSOR — the exact target it
+ * protects), so an unreadable read refuses rather than letting the door act.
+ */
+export function planningStageRefusal(ctx: BranchSource, door: string): string | null {
+  let stage: string | undefined;
+  try {
+    stage = rebuildWorkflowState(branchOf(ctx)).stage;
+  } catch (error) {
+    return (
+      `${door} is unavailable: the session's workflow state could not be read ` +
+      `(${String(error)}), so this cannot be proven not to be a planning session — ` +
+      "retry, or implement the saved plan with `perk impl <N>` in a fresh session."
+    );
+  }
+  if (stage === undefined || !PLANNING_STAGES.has(stage)) return null;
+  return (
+    `${door} is unavailable in a planning session (stage ${stage}): a planning session can ` +
+    "hold two plan identities (its checkout's own binding and the just-saved plan) — " +
+    "implement the saved plan with `perk impl <N>` in a fresh session instead."
+  );
+}
+
+/**
+ * The plan-read priming seed for a fresh implement session. The in-session twin of
+ * `perk/run/launch.py`'s `_implement_prompt`: carry the plan FORWARD (read it from its canonical
+ * source), never summarize it — the plan is the only artifact that crosses the boundary.
+ *
+ * The wording lives in the canonical template `prompts/stages/implement.md`, rendered by the shared
+ * seam (contracts.md §8.31); branching stays in code — only the `read_cmd` var differs. This warm
+ * handoff is now byte-identical to the cold/worker primer, so it carries the same "Progress
+ * tracking:" tail (the prior shorter near-copy omission is removed).
+ */
+export function implementHandoffPrompt(ref: PlanRef): string {
+  const readCmd = planReadInstruction(ref.provider, String(ref.pr_id), ref.url);
+  return render("stages/implement.md", {
+    provider: ref.provider,
+    pr_id: String(ref.pr_id),
+    url: ref.url,
+    read_cmd: readCmd,
+  });
+}

package/extension/session/saveDestination.ts

@@ -0,0 +1,87 @@
+// The save-destination fence's capture: WHERE an approved draft would be written, reduced to
+// per-component digests so a review can tell "the destination moved" from "unrelated config
+// noise" without ever retaining or reporting a raw routing value (contracts.md §8.23).
+//
+// Exactly three inputs route a save — the committed `[issues] backend`/`team` (the Python
+// resolver's whole vocabulary), the git `remote.*.url`/`remote.*.gh-resolved` entries `gh`
+// resolves the repo from (GitHub backend only; Linear never reads remotes), and the objective
+// node claim a plan save links to. Everything else (`branch.*`, `user.*`, `[workflow] base`,
+// credentials, the process environment, the run handoff) is deliberately NOT a component: none
+// of it decides where the artifact lands, so none of it may strand an approval.
+//
+// The `issues` component digests the two keys only while the extension's TOML subset reader
+// provably reads them as Python's `tomllib` does; a spelling it cannot vouch for (dotted keys,
+// an inline table, escapes …) widens the component to the whole committed document, so a
+// routing edit the subset reader cannot see still moves the digest. Widening over-fences
+// (an unrelated edit to that file then reads as "issues changed"); it never under-fences.
+import { type IssueRouting, resolveIssueRouting } from "../substrate/config.ts";
+import { remoteConfig } from "../substrate/git.ts";
+import { digestSessionData } from "../substrate/sessionData.ts";
+
+export const DESTINATION_COMPONENTS = ["issues", "remotes", "node_claim"] as const;
+export type DestinationComponent = (typeof DESTINATION_COMPONENTS)[number];
+
+/** Component name → `digestSessionData(value)`. No aggregate digest; no raw value retained. */
+export type SaveDestination = Readonly<Partial<Record<DestinationComponent, string>>>;
+
+/** The seams the capture shells through — injectable so tests can prove the Linear arm never forks git. */
+export interface SaveDestinationPorts {
+  issues(cwd: string): IssueRouting;
+  remotes(cwd: string): string | null;
+}
+
+const PRODUCTION_PORTS: SaveDestinationPorts = {
+  issues: resolveIssueRouting,
+  remotes: remoteConfig,
+};
+
+/** The `issues` component's digest input: the proven keys, or the unproven document verbatim. */
+function issuesComponent(issues: IssueRouting): string {
+  return issues.kind === "keys"
+    ? JSON.stringify({ backend: issues.backend, team: issues.team })
+    : JSON.stringify({ document: issues.text });
+}
+
+/**
+ * Capture the save destination at `cwd` for a review that would link `nodeClaim`. `issues` and
+ * `node_claim` are always present; `remotes` whenever the read backend is anything but exactly
+ * `"linear"` — GitHub, unset (the fail-safe default), unknown, or a value the reader cannot
+ * vouch for (an escaped `"\u0067ithub"` reads verbatim here while Python saves to GitHub):
+ * only a Linear save never consults git remotes, so only there does no git subprocess run. (The
+ * only way the subset reader reads `"linear"` is a bare `[issues]` table `tomllib` reads the
+ * same way.) Returns `null` when the destination cannot be verified (the GitHub arm's remotes
+ * read failed) — callers must treat that as "unverifiable", never as "unchanged".
+ */
+export function captureSaveDestination(
+  cwd: string,
+  nodeClaim: { objective: string; node: string } | null,
+  ports: SaveDestinationPorts = PRODUCTION_PORTS,
+): SaveDestination | null {
+  const issues = ports.issues(cwd);
+  const destination: Partial<Record<DestinationComponent, string>> = {
+    issues: digestSessionData(issuesComponent(issues)),
+    node_claim: digestSessionData(
+      JSON.stringify(
+        nodeClaim === null ? null : { objective: nodeClaim.objective, node: nodeClaim.node },
+      ),
+    ),
+  };
+  if (issues.backend !== "linear") {
+    const remotes = ports.remotes(cwd);
+    if (remotes === null) return null;
+    destination.remotes = digestSessionData(remotes);
+  }
+  return destination;
+}
+
+/**
+ * The components whose digests differ between the reviewed and current captures, in
+ * `DESTINATION_COMPONENTS` order; a key present on one side only counts as changed. "Changed at
+ * all" is `changed.length > 0`.
+ */
+export function changedDestinationComponents(
+  reviewed: SaveDestination,
+  current: SaveDestination,
+): DestinationComponent[] {
+  return DESTINATION_COMPONENTS.filter((component) => reviewed[component] !== current[component]);
+}