@mgiles/perk 1.1.0 → 2.0.0

package/shared/providers.yaml

@@ -16,7 +16,8 @@
 #   id      — the stable provider id. NOT the cache.plan-ref `provider` string:
 #             that field is the ISSUE BACKEND (the stamped `backend_id`, e.g.
 #             "github"), not the seam id — see contracts.md §8.10 / §8.21.
-#   seam    — `plan` | `todo` | `askuser` | `footer` | `web` (the five seams pluggability-taxonomy.md scope-fenced).
+#   seam    — `plan` | `todo` | `askuser` | `footer` | `web` (the five seams; see
+#             pluggability-taxonomy.md for the scope fence).
 #   package — the foreign Pi package spec added to .pi/settings.json `packages`
 #             (e.g. "npm:@tombell/pi-plan"); `null` for perk's own bundled reference
 #             provider (nothing to add — perk produces the contract natively). NOT
@@ -95,6 +96,12 @@
 # is pi-web-access-specific (it depends on `fetch_content`'s GitHub-clone path) and is accepted as
 # lost under a foreign web selection. Fail-safe: any config-read error resolves to `pi-web-access`,
 # keeping today's behavior exactly.
+#
+# There is NO review seam: the two surface-named review doors (`/pr-review-terminal` — the hunk
+# terminal TUI; `/pr-review-browser` — the plannotator browser UI) are the selection (the command
+# IS the surface pick). The hunk CLI converges unconditionally (init/doctor's best-effort
+# `review-cli` install/verify); the plannotator package rides the plan seam's `plannotator-plan`
+# entry.
 
 schema_version: 1
 

package/shared/registry.yaml

@@ -52,12 +52,11 @@ state_keys:
 # actual dedicated cold-door routing lives in code via `perk/cli/stages.py` `DEDICATED_STAGES`
 # (the generic launcher generator skips those ids). The field documents intent; it does not route.
 # `doors.cold_remote` records which stages a remote runner may run (cli-vs-pi §4.5) —
-# a real registry-recorded constraint, not merely "not built yet". P2.T8c flips it
-# `true` on `implement` + `address` (the agentic, headless-runnable stages a Phase-3 CI
-# worker drives); `plan`/`save` need interactive local exploration and
-# `submit`/`land`/`learn` are quick deterministic ops, so they stay `false`. Phase 2
-# *builds + resolves* the target (the resolver + this door + the --json descriptor);
-# Phase 3 *drives* it. Revisable in Phase 3.
+# a settled design decision, not merely "not built yet". It is `true` exactly on the
+# bounded agentic stages (`implement`, `address`), where the goal is already pinned by
+# a plan or by reviewer feedback. The interactive/exploratory stages (planning above
+# all) and the quick deterministic human-gate ops (`submit`/`land`/`learn`) are
+# local-only by design — review, merge, and judgment capture stay where a human is.
 # ---------------------------------------------------------------------------
 stages:
   - id: objective-author
@@ -129,7 +128,7 @@ stages:
     summary: Do the work on a branch (requires fresh context; cold-only).
     mode: read-write
     worktree: create          # first stage that needs a branch/worktree (folds in erk's `prepare`)
-    doors: { warm: false, cold_local: true, cold_remote: true }  # P2.T8c: a Phase-3 CI worker can run it
+    doors: { warm: false, cold_local: true, cold_remote: true }  # bounded agentic stage — remotely runnable
     run_id: { warm: keep, cold_local: mint, cold_remote: mint }
     command: implement
     requires: [cache.plan-ref]   # T4: cold door derives plan-<pr_id> from the active ref
@@ -155,7 +154,7 @@ stages:
     summary: Classify PR review feedback (isolated child) and resolve the threads.
     mode: read-write
     worktree: reuse
-    doors: { warm: true, cold_local: true, cold_remote: true }  # P2.T8c: a Phase-3 CI worker can run it
+    doors: { warm: true, cold_local: true, cold_remote: true }  # bounded agentic stage — remotely runnable
     run_id: { warm: keep, cold_local: mint, cold_remote: mint }
     command: pr address
     # P2.T7: a spawned read-only child (borrowed pi-subagents) fetches + classifies feedback;

package/shared/schemas/inputs/review-submit-batch.schema.json

@@ -0,0 +1,66 @@
+{
+  "$defs": {
+    "ReviewSubmitCommentInput": {
+      "additionalProperties": false,
+      "description": "One inline comment in the machine-authored submission batch (strict: a typo fails loudly).\n\n`line` is **non-nullable** by design: unanchorable (`line: null`) findings are folded into\nthe review body upstream, during the triage curation \u2014 never submitted as inline comments.",
+      "properties": {
+        "path": {
+          "minLength": 1,
+          "title": "Path",
+          "type": "string"
+        },
+        "line": {
+          "title": "Line",
+          "type": "integer"
+        },
+        "side": {
+          "default": "RIGHT",
+          "enum": [
+            "LEFT",
+            "RIGHT"
+          ],
+          "title": "Side",
+          "type": "string"
+        },
+        "body": {
+          "minLength": 1,
+          "title": "Body",
+          "type": "string"
+        }
+      },
+      "required": [
+        "path",
+        "line",
+        "body"
+      ],
+      "title": "ReviewSubmitCommentInput",
+      "type": "object"
+    }
+  },
+  "additionalProperties": false,
+  "description": "The strict `review-submit` batch shape (`{body, comments?}` \u2014 the event rides the flag).\n\nNo `fyi` field: in-session triage color is structurally unpostable through this door\n(strict extra-forbid rejects it). `comments` stays nullable so an explicit `null` is\ntolerated, normalized to `[]` in conversion.",
+  "properties": {
+    "body": {
+      "default": "",
+      "title": "Body",
+      "type": "string"
+    },
+    "comments": {
+      "anyOf": [
+        {
+          "items": {
+            "$ref": "#/$defs/ReviewSubmitCommentInput"
+          },
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Comments"
+    }
+  },
+  "title": "ReviewSubmitBatchInput",
+  "type": "object"
+}

package/shared/schemas/outputs/pr-review-checkout.schema.json

@@ -0,0 +1,69 @@
+{
+  "additionalProperties": false,
+  "description": "The ``--json`` serialization boundary of :class:`ReviewCheckoutResult` (flat; envelope\nkeys first). ``path`` is absolute; the SHAs are full 40-char.",
+  "properties": {
+    "success": {
+      "title": "Success",
+      "type": "boolean"
+    },
+    "error_type": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Error Type"
+    },
+    "message": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Message"
+    },
+    "path": {
+      "title": "Path",
+      "type": "string"
+    },
+    "pr": {
+      "title": "Pr",
+      "type": "integer"
+    },
+    "url": {
+      "title": "Url",
+      "type": "string"
+    },
+    "head_sha": {
+      "title": "Head Sha",
+      "type": "string"
+    },
+    "base_sha": {
+      "title": "Base Sha",
+      "type": "string"
+    },
+    "base_ref": {
+      "title": "Base Ref",
+      "type": "string"
+    }
+  },
+  "required": [
+    "success",
+    "error_type",
+    "message",
+    "path",
+    "pr",
+    "url",
+    "head_sha",
+    "base_sha",
+    "base_ref"
+  ],
+  "title": "PrReviewCheckoutOut",
+  "type": "object"
+}

package/shared/schemas/outputs/pr-review-cleanup.schema.json

@@ -0,0 +1,54 @@
+{
+  "additionalProperties": false,
+  "description": "The ``--json`` serialization boundary of :class:`ReviewCleanupResult` (flat; envelope\nkeys first). ``path`` is absolute.",
+  "properties": {
+    "success": {
+      "title": "Success",
+      "type": "boolean"
+    },
+    "error_type": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Error Type"
+    },
+    "message": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Message"
+    },
+    "pr": {
+      "title": "Pr",
+      "type": "integer"
+    },
+    "path": {
+      "title": "Path",
+      "type": "string"
+    },
+    "removed": {
+      "title": "Removed",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "success",
+    "error_type",
+    "message",
+    "pr",
+    "path",
+    "removed"
+  ],
+  "title": "PrReviewCleanupOut",
+  "type": "object"
+}

package/shared/schemas/outputs/pr-review-submit.schema.json

@@ -0,0 +1,64 @@
+{
+  "additionalProperties": false,
+  "description": "The ``--json`` serialization boundary of the submission result (flat; envelope keys\nfirst). ``event`` is the flag spelling; ``mode`` \u2208\n``validated | review | review_folded | comment_fallback``.",
+  "properties": {
+    "success": {
+      "title": "Success",
+      "type": "boolean"
+    },
+    "error_type": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Error Type"
+    },
+    "message": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Message"
+    },
+    "dry_run": {
+      "title": "Dry Run",
+      "type": "boolean"
+    },
+    "pr": {
+      "title": "Pr",
+      "type": "integer"
+    },
+    "event": {
+      "title": "Event",
+      "type": "string"
+    },
+    "mode": {
+      "title": "Mode",
+      "type": "string"
+    },
+    "comment_count": {
+      "title": "Comment Count",
+      "type": "integer"
+    }
+  },
+  "required": [
+    "success",
+    "error_type",
+    "message",
+    "dry_run",
+    "pr",
+    "event",
+    "mode",
+    "comment_count"
+  ],
+  "title": "PrReviewSubmitOut",
+  "type": "object"
+}

package/extension/doors/learnCode.ts

@@ -1,100 +0,0 @@
-// hop-2 — the learn-code plan factory's warm transition surface: the `/learn-code` command.
-//
-// The warm twin of the `perk learn code` cold door (sibling of `/learn-docs`). It DELEGATES the
-// gather to the Python plane (`perk learn code --gather --json` via the shared cold-door client
-// `runColdDoor` — gate-safe, not subject to the read-only bash allowlist), decodes
-// `{ inbox_path, learn_numbers }`, then injects the factory guidance via `pi.sendUserMessage` so
-// the model reads the inbox, authors a code plan, and calls `plan_save` with `consumed_learn`. No
-// model tool — the model uses the existing `plan_save` tool.
-//
-// Headless-safe: rich UI is guarded by `ctx.hasUI`; without a UI it logs to stderr and returns
-// (the gather still runs so the inbox is materialized, but no turn is driven).
-
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { bindingSuffix } from "../substrate/bindingDelivery.ts";
-import { type ColdJson, runColdDoor, stringField } from "../substrate/coldDoor.ts";
-import { registerPerkCommand } from "../substrate/command.ts";
-import { render } from "../substrate/prompts.ts";
-import { report } from "../surfaces/report.ts";
-
-/** The decoded `perk learn code --gather --json` payload slice the warm door consumes. */
-interface LearnCodeGatherPayload {
-  inbox_path: string;
-  /** Opaque string learn-issue ids (GitHub "45", Linear "ENG-45") — §8.21. */
-  learn_numbers: string[];
-}
-
-/** Strict decode — the guidance dereferences both fields; `launched` is unconsumed. Exported for offline reject-branch tests. */
-export function decodeGather(payload: ColdJson): LearnCodeGatherPayload | null {
-  const inboxPath = stringField(payload, "inbox_path");
-  const numbers = payload.learn_numbers;
-  if (inboxPath === undefined) return null;
-  // String ids are canonical (§8.21); numbers are tolerated + coerced (older envelopes).
-  if (
-    !Array.isArray(numbers) ||
-    !numbers.every((n) => typeof n === "string" || typeof n === "number")
-  ) {
-    return null;
-  }
-  return { inbox_path: inboxPath, learn_numbers: numbers.map((n) => String(n)) };
-}
-
-/**
- * The seed guidance the warm `/learn-code` injects to start the factory loop (the perk-learn-code
- * skill pointer rides the skill-binding suffix — not hardcoded here). Pure + exported
- * for offline tests.
- */
-export function learnCodeGuidance(inboxPath: string, learnNumbers: string[]): string {
-  return render("stages/learn-code.md", {
-    inbox_path: inboxPath,
-    num_list: learnNumbers.join(", "),
-  });
-}
-
-/** Register the warm learn-code door: the `/learn-code` command (no model tool). */
-export function registerLearnCode(pi: ExtensionAPI): void {
-  registerPerkCommand(pi, "learn-code", {
-    description:
-      "Start the learn-code plan factory: gather pre-stamped SHOULD_BE_CODE perk:learn issues into " +
-      "an inbox and author a plan routing each into its real code home.",
-    handler: async (_args, ctx: ExtensionContext) => {
-      // Report-only door (no Result type): branch on `errorType` directly (the coldDoor header
-      // convention). A clean "nothing to route" exits non-zero with error_type=no_learn_issues —
-      // the client's envelope-aware arm surfaces it gently.
-      const r = await runColdDoor<LearnCodeGatherPayload>(
-        pi,
-        ctx,
-        ["learn", "code", "--gather", "--json"],
-        { label: "perk learn code", decode: decodeGather },
-      );
-      if (!r.ok) {
-        if (r.errorType === "no_learn_issues") {
-          report(
-            ctx,
-            "learn-code",
-            "warning",
-            "nothing to route into code (no SHOULD_BE_CODE perk:learn issues).",
-          );
-        } else {
-          report(ctx, "learn-code", "error", `gather failed: ${r.message}`);
-        }
-        return;
-      }
-
-      if (!ctx.hasUI) {
-        // Headless can't drive a turn — the inbox is materialized; log and return (fail-safe).
-        console.error(
-          `perk: /learn-code invoked (headless) — gathered ${r.data.learn_numbers.length} ` +
-            `learn issue(s) into ${r.data.inbox_path}; run interactively to author the code plan.`,
-        );
-        return;
-      }
-
-      report(ctx, "learn-code", "info", `gathered ${r.data.learn_numbers.length} learn issue(s)`);
-      pi.sendUserMessage(
-        learnCodeGuidance(r.data.inbox_path, r.data.learn_numbers) +
-          bindingSuffix(ctx.cwd, "command:learn-code"),
-      );
-    },
-  });
-}

package/extension/doors/learnDocs.ts

@@ -1,100 +0,0 @@
-// hop-2 — the learned-docs plan factory's warm transition surface: the `/learn-docs` command.
-//
-// The warm twin of the `perk learn docs` cold door. It DELEGATES the gather to the Python plane
-// (`perk learn docs --gather --json` via the shared cold-door client `runColdDoor` — gate-safe,
-// not subject to the read-only bash allowlist), decodes `{ inbox_path, learn_numbers }`, then
-// injects the factory guidance via
-// `pi.sendUserMessage` so the model reads the inbox, authors a docs plan, and calls `plan_save`
-// with `consumed_learn`. No model tool — the model uses the existing `plan_save` tool.
-//
-// Headless-safe: rich UI is guarded by `ctx.hasUI`; without a UI it logs to stderr and returns
-// (the gather still runs so the inbox is materialized, but no turn is driven).
-
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { bindingSuffix } from "../substrate/bindingDelivery.ts";
-import { type ColdJson, runColdDoor, stringField } from "../substrate/coldDoor.ts";
-import { registerPerkCommand } from "../substrate/command.ts";
-import { render } from "../substrate/prompts.ts";
-import { report } from "../surfaces/report.ts";
-
-/** The decoded `perk learn docs --gather --json` payload slice the warm door consumes. */
-interface LearnDocsGatherPayload {
-  inbox_path: string;
-  /** Opaque string learn-issue ids (GitHub "45", Linear "ENG-45") — §8.21. */
-  learn_numbers: string[];
-}
-
-/** Strict decode — the guidance dereferences both fields; `launched` is unconsumed. Exported for offline reject-branch tests. */
-export function decodeGather(payload: ColdJson): LearnDocsGatherPayload | null {
-  const inboxPath = stringField(payload, "inbox_path");
-  const numbers = payload.learn_numbers;
-  if (inboxPath === undefined) return null;
-  // String ids are canonical (§8.21); numbers are tolerated + coerced (older envelopes).
-  if (
-    !Array.isArray(numbers) ||
-    !numbers.every((n) => typeof n === "string" || typeof n === "number")
-  ) {
-    return null;
-  }
-  return { inbox_path: inboxPath, learn_numbers: numbers.map((n) => String(n)) };
-}
-
-/**
- * The seed guidance the warm `/learn-docs` injects to start the factory loop (the perk-learn-docs
- * skill pointer rides the skill-binding suffix — not hardcoded here). Pure + exported
- * for offline tests.
- */
-export function learnDocsGuidance(inboxPath: string, learnNumbers: string[]): string {
-  return render("stages/learn-docs.md", {
-    inbox_path: inboxPath,
-    num_list: learnNumbers.join(", "),
-  });
-}
-
-/** Register the warm learned-docs door: the `/learn-docs` command (no model tool). */
-export function registerLearnDocs(pi: ExtensionAPI): void {
-  registerPerkCommand(pi, "learn-docs", {
-    description:
-      "Start the learned-docs plan factory: gather open perk:learn issues into an inbox and author " +
-      "a docs/learned consolidation plan.",
-    handler: async (_args, ctx: ExtensionContext) => {
-      // Report-only door (no Result type): branch on `errorType` directly (the coldDoor header
-      // convention). A clean "nothing to consolidate" exits non-zero with
-      // error_type=no_learn_issues — the client's envelope-aware arm surfaces it gently.
-      const r = await runColdDoor<LearnDocsGatherPayload>(
-        pi,
-        ctx,
-        ["learn", "docs", "--gather", "--json"],
-        { label: "perk learn docs", decode: decodeGather },
-      );
-      if (!r.ok) {
-        if (r.errorType === "no_learn_issues") {
-          report(
-            ctx,
-            "learn-docs",
-            "warning",
-            "nothing to consolidate (no open perk:learn issues).",
-          );
-        } else {
-          report(ctx, "learn-docs", "error", `gather failed: ${r.message}`);
-        }
-        return;
-      }
-
-      if (!ctx.hasUI) {
-        // Headless can't drive a turn — the inbox is materialized; log and return (fail-safe).
-        console.error(
-          `perk: /learn-docs invoked (headless) — gathered ${r.data.learn_numbers.length} ` +
-            `learn issue(s) into ${r.data.inbox_path}; run interactively to author the docs plan.`,
-        );
-        return;
-      }
-
-      report(ctx, "learn-docs", "info", `gathered ${r.data.learn_numbers.length} learn issue(s)`);
-      pi.sendUserMessage(
-        learnDocsGuidance(r.data.inbox_path, r.data.learn_numbers) +
-          bindingSuffix(ctx.cwd, "command:learn-docs"),
-      );
-    },
-  });
-}