@mgiles/perk 3.1.0 → 3.3.0

package/README.md

@@ -110,6 +110,11 @@ just ci
 managed by [prek](https://prek.j178.dev) and runs `ruff check` on staged Python. Re-run
 `just hooks` after a fresh clone if hooks are missing.
 
+Focused Python selections while iterating — `just test-py-fast` (`-m "not slow"`) and
+`just test-py-slow` (`-m slow`) — and how to time a tier are documented in
+[docs/developers/testing.md](docs/developers/testing.md); `just test`, `just ci`, GitHub CI and
+perk's in-session `run_ci` always run the whole Python suite.
+
 Without `just`: `uv run …` for Python (`uv run perk init`, `uv run pytest`,
 `uv run ruff check perk tests`, `uv run ty check`) and `npm run …` for TypeScript
 (`npm run lint`, `npm run typecheck`).

package/extension/authoring/gist/draft.ts

@@ -0,0 +1,198 @@
+// The gist working-draft feature: the typed `GistDraft` model, its schema_version-1 JSON
+// encode/decode (JSON is storage/transport only — the review surface is `renderGistDraft`'s
+// markdown, never raw bytes), and the two draft operations over the WorkflowSession seam.
+//
+// Carve-out doctrine: the artifact name is the fixed constant `GIST_DRAFT_ARTIFACT` and every
+// byte flows through the session seam (file + verified `session_artifacts` pointer), so the only
+// thing the draft ops can ever touch is the one working-gist artifact in the current run's data
+// dir (gitignored scratch). A revision is a WHOLE-VALUE replacement — no revision ids, no
+// compare-and-swap claims the backing cannot prove.
+//
+// Format doctrine: the artifact carries `{schema_version, title?, scope?, prose}` — deliberately
+// light: a gist is a problem-space statement of intent with no structured roadmap
+// (contracts.md §8.41).
+
+import type { SessionArtifactReceipt, WorkflowSession } from "../../session/workflowSession.ts";
+
+/** The registry stage id of the gist-authoring session (shared with planMode's defer check). */
+export const GIST_AUTHOR_STAGE = "gist-author";
+
+/** The gist consumption tiers (`scope` — contracts.md §8.41). */
+export const GIST_SCOPES = ["plan", "objective"] as const;
+
+export type GistScope = (typeof GIST_SCOPES)[number];
+
+/** The fixed working-gist artifact name (one JSON file: the prose + the optional scope hint). */
+export const GIST_DRAFT_ARTIFACT = "gist-draft.json";
+
+/** The validated working-gist draft shape. */
+export interface GistDraft {
+  title?: string;
+  scope?: GistScope;
+  prose: string;
+}
+
+/**
+ * Serialize a working gist as the schema_version-1 JSON artifact: deterministic key order via
+ * the explicit literal; `title`/`scope` omitted when blank — byte-identical to what the artifact
+ * always carried. Pure; never throws.
+ */
+export function encodeGistDraft(draft: {
+  prose: string;
+  title?: string;
+  scope?: GistScope;
+}): string {
+  const title = draft.title?.trim();
+  const payload = {
+    schema_version: 1,
+    ...(title ? { title } : {}),
+    ...(draft.scope ? { scope: draft.scope } : {}),
+    prose: draft.prose,
+  };
+  return `${JSON.stringify(payload, null, 2)}\n`;
+}
+
+/** The classified decode outcome — `problem` carries the exact refusal bytes for edge rendering. */
+export type DecodeGistDraftResult = { ok: true; draft: GistDraft } | { ok: false; problem: string };
+
+/**
+ * Decode + validate working-gist artifact bytes. A CLASSIFIED refusal (never a warn+null
+ * fallback) on malformed JSON, a non-object payload, an unsupported `schema_version`, or blank
+ * prose — the same refusal taxonomy, with the problem bytes rendered by the consuming edge.
+ * `title` is kept only when a non-blank string; `scope` only when a member of the enum (an
+ * unknown scope degrades to absent, never poisons the draft). Never throws.
+ */
+export function decodeGistDraft(content: string): DecodeGistDraftResult {
+  const refuse = (why: string): { ok: false; problem: string } => ({
+    ok: false,
+    problem: `${GIST_DRAFT_ARTIFACT} ${why} — refusing the draft`,
+  });
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return refuse("is not valid JSON");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return refuse("is not a JSON object");
+  }
+  const payload = parsed as Record<string, unknown>;
+  if (payload.schema_version !== 1) {
+    return refuse(`has an unsupported schema_version (${JSON.stringify(payload.schema_version)})`);
+  }
+  const prose = payload.prose;
+  if (typeof prose !== "string" || !prose.trim()) {
+    return refuse("has no prose");
+  }
+  const title =
+    typeof payload.title === "string" && payload.title.trim() ? payload.title : undefined;
+  const scope =
+    typeof payload.scope === "string" && (GIST_SCOPES as readonly string[]).includes(payload.scope)
+      ? (payload.scope as GistScope)
+      : undefined;
+  return {
+    ok: true,
+    draft: {
+      ...(title !== undefined ? { title } : {}),
+      ...(scope !== undefined ? { scope } : {}),
+      prose,
+    },
+  };
+}
+
+/**
+ * Render the draft as the markdown review surface (JSON is storage/transport only — contracts
+ * §8.1): the optional `# title` heading, a `Scope:` line when the hint is set, and the prose
+ * verbatim. Pure; never throws.
+ */
+export function renderGistDraft(draft: GistDraft): string {
+  let out = "";
+  if (draft.title) out += `# ${draft.title}\n\n`;
+  if (draft.scope) out += `Scope: ${draft.scope}\n\n`;
+  return out + draft.prose;
+}
+
+/**
+ * The revise outcome. `rejected` splits by `reason` so the adapter renders the exact failure
+ * taxonomy it always had: `blank_prose` (input refused), `no_identity` (no session), and
+ * `write_refused` (the seam refused before any effect); `unverified` means an effect may have
+ * landed but the read-back proof failed. `problem` carries the caller-facing message bytes.
+ */
+export type ReviseGistDraftResult =
+  | { status: "revised"; receipt: SessionArtifactReceipt; bytes: number }
+  | { status: "unchanged"; receipt: SessionArtifactReceipt; bytes: number }
+  | { status: "rejected"; reason: "blank_prose" | "no_identity" | "write_refused"; problem: string }
+  | { status: "unverified"; problem: string };
+
+/**
+ * Rewrite the working gist draft (a whole-value replacement) through the session seam.
+ * Diagnostic precedence preserved: blank prose is refused FIRST, missing identity second
+ * (the identity-optional session classifies `runId: null` — an identity-less caller still
+ * opens), then the verified artifact write. Never throws.
+ */
+export function reviseGistDraft(
+  input: { prose: string; title?: string; scope?: GistScope },
+  session: WorkflowSession,
+): ReviseGistDraftResult {
+  if (!input.prose.trim()) {
+    return {
+      status: "rejected",
+      reason: "blank_prose",
+      problem: "no gist prose to write (pass the full working draft)",
+    };
+  }
+  if (session.runId === null) {
+    return {
+      status: "rejected",
+      reason: "no_identity",
+      problem: "session has no run_id — cannot write the gist-draft artifact",
+    };
+  }
+  const content = encodeGistDraft(input);
+  const bytes = Buffer.byteLength(content, "utf8");
+  const written = session.writeArtifact(GIST_DRAFT_ARTIFACT, content);
+  switch (written.status) {
+    case "applied":
+      return { status: "revised", receipt: written.receipt, bytes };
+    case "unchanged":
+      return { status: "unchanged", receipt: written.receipt, bytes };
+    case "rejected":
+      return {
+        status: "rejected",
+        reason: "write_refused",
+        problem: `could not write the ${GIST_DRAFT_ARTIFACT} artifact (see warnings)`,
+      };
+    case "unverified":
+      return {
+        status: "unverified",
+        problem: `could not write the ${GIST_DRAFT_ARTIFACT} artifact (see warnings)`,
+      };
+  }
+}
+
+/**
+ * The classified resume outcome: a refused draft is a fail-closed STOP at every consumer —
+ * it never takes the no-draft fallbacks' side effects (gate exit, driven turn). `raw` is the
+ * artifact bytes the draft was decoded from — the reviewed-bytes baseline; consumers that
+ * render and fence must use this one read for both (a second read could be newer than what
+ * the human saw).
+ */
+export type ResumeGistDraftResult =
+  | { kind: "valid"; draft: GistDraft; raw: string }
+  | { kind: "absent" }
+  | { kind: "refused"; problem: string };
+
+/**
+ * Resume the working gist draft from the session, classified: seam `absent` → `absent` (the
+ * genuine no-draft arm); seam `invalid` → `refused` carrying the seam's problem (a corrupted
+ * artifact is truthfully rendered at the edge — the seam's own stderr tier is untouched); a
+ * decodable-but-refused payload → `refused` with the decoder's problem. Never throws.
+ */
+export function resumeGistDraft(session: WorkflowSession): ResumeGistDraftResult {
+  const read = session.readArtifact(GIST_DRAFT_ARTIFACT);
+  if (read.status === "absent") return { kind: "absent" };
+  if (read.status === "invalid") return { kind: "refused", problem: read.problem };
+  const decoded = decodeGistDraft(read.content);
+  if (!decoded.ok) return { kind: "refused", problem: decoded.problem };
+  return { kind: "valid", draft: decoded.draft, raw: read.content };
+}

package/extension/authoring/gist/prose.ts

@@ -0,0 +1,46 @@
+// The gist feature's model-facing prose units: the two tool-guideline arrays, the
+// gist-authoring context content builder, and the injection marker/customType constants.
+// Prose-unit MEANING and ORDER live here (the feature); the v1 adapter only PLACES these units
+// in Pi registration fields and event payloads (module-contracts.md's prose split). Prompting,
+// NOT enforcement — the read-only tool gate is the enforcement.
+
+import { render } from "../../substrate/prompts.ts";
+
+/** The gist-authoring context customType (distinct from planMode's `perk:plan-context`). */
+export const GIST_AUTHOR_CONTEXT_TYPE = "perk:gist-author-context";
+
+/** The injected gist-authoring context's identity marker (the strip + dedup key). */
+export const GIST_AUTHOR_MARKER = "[GIST AUTHORING]";
+
+/**
+ * The gist-authoring session context: live state + pointers only (contracts.md §8.57 — the flow
+ * is stated by the launch statement, the detail by the `perk-gist-author` skill). It names the
+ * working-draft artifact (`gist_draft`), the review tool (`plan_review`), and the bound skill;
+ * it never restates the flow.
+ */
+export const GIST_AUTHORING_CONTEXT = render("contexts/gist-authoring.md", {
+  marker: GIST_AUTHOR_MARKER,
+});
+
+/**
+ * Build the full gist-authoring injection, appending the project-config authoring addendum when
+ * present. Pure over the addendum — the ADAPTER loads `[workflow] plan_authoring` per event and
+ * passes the value in (the narrow-views doctrine).
+ */
+export function gistAuthoringContextContent(addendum: string | undefined): string {
+  return addendum ? `${GIST_AUTHORING_CONTEXT}\n\n${addendum.trim()}` : GIST_AUTHORING_CONTEXT;
+}
+
+/** The `gist_draft` tool guidelines (verbatim prose units; the adapter places them). */
+export const GIST_DRAFT_TOOL_GUIDELINES = [
+  "Call gist_draft to persist the current working gist as you author or revise it; pass the FULL prose each time (it rewrites the whole draft).",
+  "gist_draft never saves to the issue backend and never ends the turn — gist_save//gist-save remain the canonical save surface.",
+  "Pass gist_draft's `scope` only once the consumption tier is settled: `plan` for plan-sized intent, `objective` for objective-sized intent.",
+];
+
+/** The `gist_save` tool guidelines (verbatim prose units; the adapter places them). */
+export const GIST_SAVE_TOOL_GUIDELINES = [
+  "Use gist_save only after the gist says what it means; it creates the tracked gist in the issue backend and ends the turn.",
+  "Pass gist_save the statement-of-intent PROSE in `prose` — problem-focused, with at most high-level solution leanings; no implementation steps or roadmap.",
+  "Pass gist_save's `scope` only once the consumption tier is settled (plan or objective); omit it to keep the pre-seeded/default scope.",
+];

package/extension/authoring/gist/review.ts

@@ -0,0 +1,133 @@
+// The gist review feature: the `GistDraftReviewer` role (one production adapter per review
+// backend — plannotator bridge or first-party editor, both built in pi/v1 — plus a scripted fake
+// in the tests) and the one-entry `reviewGist` operation.
+//
+// Ordering is the review door's exact discipline: resume-the-draft FIRST (absent → `noDraft` —
+// the draft artifact is the SOLE review source, never a param, never the transcript), render the
+// markdown surface, review, then route the verdict — an approval carrying direct edits SKIPS the
+// save and returns one revise round (rendered edits cannot be folded back into the structured
+// draft mechanically; the gate stays untouched); a plain approval re-reads the artifact through
+// `gistApprovalSave` (the save source is the artifact, never the reviewed bytes). Headless
+// detection stays in the adapter — the feature never sees `hasUI`.
+
+import type { WorkflowSession } from "../../session/workflowSession.ts";
+import type { ApprovalGate } from "../review/approvalGate.ts";
+import { renderGistDraft, resumeGistDraft } from "./draft.ts";
+import { type GistApprovalSaveOutcome, type GistBackend, gistApprovalSave } from "./save.ts";
+
+/**
+ * The reviewer's verdict on the rendered draft. An approval carrying reviewer edits of the
+ * rendered markdown is its OWN variant (`approvedDirectEdits`) with `feedback` required — the
+ * edits ARE the feedback, so an edits-without-feedback value is unrepresentable and can never
+ * fall through to the save path. The backend adapter translates its own vocabulary (e.g.
+ * plannotator's `# Direct Edits` feedback section) into this variant.
+ */
+export type GistReviewOutcome =
+  | { status: "approved"; feedback?: string; reviewId?: string }
+  | { status: "approvedDirectEdits"; feedback: string; reviewId?: string }
+  | { status: "denied"; feedback?: string; reviewId?: string }
+  | { status: "dismissed" }
+  | { status: "aborted" }
+  | { status: "unavailable"; warning: string };
+
+/** The reviewer role: judge the RENDERED markdown surface (never raw artifact JSON). */
+export interface GistDraftReviewer {
+  review(rendered: string, signal?: AbortSignal): Promise<GistReviewOutcome>;
+}
+
+/** The one-entry review outcome — each arm carries exactly what its caller renders.
+ * `refusedDraft` (pre-review) and `approvedRefusedDraft` (the approval-time race) are the
+ * fail-closed stops for an invalid artifact: nothing reviewed/saved, the gate untouched. */
+export type ReviewGistResult =
+  | { status: "noDraft" }
+  | { status: "refusedDraft"; problem: string }
+  | { status: "directEditsRevise"; feedback: string; reviewId?: string }
+  | {
+      status: "approvedSaved";
+      save: Extract<GistApprovalSaveOutcome, { status: "saved" }>;
+      feedback?: string;
+      reviewId?: string;
+    }
+  | {
+      status: "approvedSaveFailed";
+      save: Extract<GistApprovalSaveOutcome, { status: "save-failed" }>;
+      feedback?: string;
+      reviewId?: string;
+    }
+  | { status: "approvedNoDraft"; feedback?: string; reviewId?: string }
+  | { status: "approvedRefusedDraft"; problem: string; feedback?: string; reviewId?: string }
+  | { status: "denied"; feedback?: string; reviewId?: string }
+  | { status: "dismissed" }
+  | { status: "aborted" }
+  | { status: "unavailable"; warning: string };
+
+/**
+ * Review the working gist draft end-to-end: resume → render → review → route. An approval with
+ * `directEdits` (and feedback to fold) returns the revise round with NOTHING saved and the gate
+ * untouched; a plain approval runs `gistApprovalSave` (which re-reads the artifact at save time
+ * — `approvedNoDraft` is the defensive vanished-between-reads arm; `approvedRefusedDraft` its
+ * corrupted-between-reads sibling, feedback/reviewId preserved across the race). Never throws.
+ */
+export async function reviewGist(
+  deps: {
+    session: WorkflowSession;
+    reviewer: GistDraftReviewer;
+    backend: GistBackend;
+    gate: ApprovalGate;
+  },
+  signal?: AbortSignal,
+): Promise<ReviewGistResult> {
+  if (signal?.aborted) return { status: "aborted" };
+  const resumed = resumeGistDraft(deps.session);
+  if (resumed.kind === "absent") return { status: "noDraft" };
+  if (resumed.kind === "refused") return { status: "refusedDraft", problem: resumed.problem };
+  const rendered = renderGistDraft(resumed.draft);
+  const outcome = await deps.reviewer.review(rendered, signal);
+  if (signal?.aborted) return { status: "aborted" };
+  return completeGistReview(outcome, () => gistApprovalSave(deps));
+}
+
+/** Subject policy only: callers authorize effects before entering this completion seam. */
+export async function completeGistReview(
+  outcome: GistReviewOutcome,
+  approvalSave: () => Promise<GistApprovalSaveOutcome>,
+): Promise<ReviewGistResult> {
+  if (outcome.status === "approvedDirectEdits") {
+    return {
+      status: "directEditsRevise",
+      feedback: outcome.feedback,
+      ...(outcome.reviewId !== undefined ? { reviewId: outcome.reviewId } : {}),
+    };
+  }
+  if (outcome.status === "approved") {
+    const carried = {
+      ...(outcome.feedback !== undefined ? { feedback: outcome.feedback } : {}),
+      ...(outcome.reviewId !== undefined ? { reviewId: outcome.reviewId } : {}),
+    };
+    const save = await approvalSave();
+    switch (save.status) {
+      case "saved":
+        return { status: "approvedSaved", save, ...carried };
+      case "save-failed":
+        return { status: "approvedSaveFailed", save, ...carried };
+      case "no-draft":
+        return { status: "approvedNoDraft", ...carried };
+      case "refused-draft":
+        return { status: "approvedRefusedDraft", problem: save.problem, ...carried };
+    }
+  }
+  switch (outcome.status) {
+    case "denied":
+      return {
+        status: "denied",
+        ...(outcome.feedback !== undefined ? { feedback: outcome.feedback } : {}),
+        ...(outcome.reviewId !== undefined ? { reviewId: outcome.reviewId } : {}),
+      };
+    case "dismissed":
+      return { status: "dismissed" };
+    case "aborted":
+      return { status: "aborted" };
+    case "unavailable":
+      return { status: "unavailable", warning: outcome.warning };
+  }
+}

package/extension/authoring/gist/save.ts

@@ -0,0 +1,118 @@
+// The gist save feature: the narrow exterior `GistBackend` port (one production adapter — the
+// `perk gist create` cold door in pi/v1 — plus one deterministic fake in the tests: the port
+// admission rule), the `saveGist` operation, and the shared APPROVED-review → save orchestration
+// `gistApprovalSave` (the exported name contracts.md §8.41 pins).
+//
+// Unlike the plan/objective siblings there is NO session linkage after the save — nothing
+// consumes a gist in-session (adoption happens later via the cold doors), so a successful save
+// just carries the backend's id/url/scope facts for the caller to relay.
+
+import type { WorkflowSession } from "../../session/workflowSession.ts";
+import { type ApprovalGate, saveThroughApprovalGate } from "../review/approvalGate.ts";
+import { GIST_SCOPES, type GistScope, resumeGistDraft } from "./draft.ts";
+
+/** The backend save facts (`id` is the opaque string gist id — contracts §8.21). */
+export type GistBackendSaveResult =
+  | { status: "saved"; id: string; url: string; existed: boolean | null; scope: string | null }
+  | { status: "failed"; message: string; errorType: string };
+
+/**
+ * The narrow exterior port the save operation writes through. `runId: null` means the caller has
+ * no session identity — the backend omits its run linkage (an identity-less save keeps working).
+ */
+export interface GistBackend {
+  save(req: {
+    prose: string;
+    title?: string;
+    scope?: GistScope;
+    runId: string | null;
+  }): Promise<GistBackendSaveResult>;
+}
+
+/**
+ * The save outcome: the backend facts, or a typed refusal/failure (message bytes caller-facing).
+ * Deliberately the SAME union as the backend result — `saveGist` adds the local validation
+ * refusals on the shared `failed` variant and otherwise returns the backend value unchanged, so
+ * a second hand-mirrored vocabulary would only invite drift. Alias, not copy.
+ */
+export type SaveGistOutcome = GistBackendSaveResult;
+
+/**
+ * The single save operation both surfaces call: validate the prose/scope (the exact refusals the
+ * save always had), then write through the backend port. The backend owns scope resolution
+ * beyond the explicit value (launch-handoff seed, default). Never throws.
+ */
+export async function saveGist(
+  input: { prose: string; title?: string; scope?: GistScope },
+  deps: { backend: GistBackend; runId: string | null },
+): Promise<SaveGistOutcome> {
+  const prose = input.prose.trim();
+  if (!prose) {
+    return {
+      status: "failed",
+      message: "no gist prose to save (draft the gist first)",
+      errorType: "invalid_input",
+    };
+  }
+  if (input.scope !== undefined && !(GIST_SCOPES as readonly string[]).includes(input.scope)) {
+    return {
+      status: "failed",
+      message: "scope must be plan or objective",
+      errorType: "invalid_input",
+    };
+  }
+  return deps.backend.save({
+    prose,
+    ...(input.title !== undefined ? { title: input.title } : {}),
+    ...(input.scope !== undefined ? { scope: input.scope } : {}),
+    runId: deps.runId,
+  });
+}
+
+/** The approval→save orchestration outcome (the gist `ApprovalSaveOutcome`). `refused-draft`
+ * is the fail-closed stop for an invalid artifact: nothing saved, the gate never touched —
+ * distinct from `no-draft` (the genuine draft-less fallback arm). */
+export type GistApprovalSaveOutcome =
+  | { status: "no-draft" }
+  | { status: "refused-draft"; problem: string }
+  | { status: "saved"; save: Extract<SaveGistOutcome, { status: "saved" }>; gateExited: boolean }
+  | {
+      status: "save-failed";
+      save: Extract<SaveGistOutcome, { status: "failed" }>;
+      gateExited: false;
+    };
+
+/**
+ * The shared APPROVED-review → save orchestration (an APPROVED `plan_review` gist arm and the
+ * manual `/gist-save` failsafe both run THIS). Flow: re-read the draft artifact at save time
+ * (`resumeGistDraft` — never the rendered markdown, never in-hand bytes) → `saveGist` through
+ * `saveThroughApprovalGate` (the D1a invariant: snapshot before the save; exit only after a
+ * successful save while read-only; a failed save leaves the gate ON). No draft → `no-draft`
+ * (nothing saved, the gate untouched); a REFUSED draft → `refused-draft` before the gate
+ * snapshot (fail-closed stop — `gateExited` semantics never arise). Title precedence:
+ * the explicit override (`/gist-save [title]` — a pinned behavior) wins over the draft's; scope
+ * is always the draft's.
+ */
+export async function gistApprovalSave(
+  deps: { session: WorkflowSession; backend: GistBackend; gate: ApprovalGate },
+  opts: { title?: string } = {},
+): Promise<GistApprovalSaveOutcome> {
+  const resumed = resumeGistDraft(deps.session);
+  if (resumed.kind === "absent") return { status: "no-draft" };
+  if (resumed.kind === "refused") return { status: "refused-draft", problem: resumed.problem };
+  const draft = resumed.draft;
+  const { outcome: save, gateExited } = await saveThroughApprovalGate(deps.gate, () =>
+    saveGist(
+      {
+        prose: draft.prose,
+        ...(opts.title !== undefined || draft.title !== undefined
+          ? { title: opts.title ?? draft.title }
+          : {}),
+        ...(draft.scope !== undefined ? { scope: draft.scope } : {}),
+      },
+      { backend: deps.backend, runId: deps.session.runId },
+    ),
+  );
+  if (save.status !== "saved") return { status: "save-failed", save, gateExited: false };
+  return { status: "saved", save, gateExited };
+}