@mgiles/perk 3.1.0 → 3.3.0

package/extension/substrate/config.ts

@@ -1,7 +1,7 @@
 // The minimal TS config port. Mirrors `perk/substrate/config.py`'s overlay: read
 // `.perk/config.toml` (committed) overlaid by `.perk/local.toml` (gitignored, local wins). The only
 // setting consumed today is an optional `[workflow]` plan-authoring addendum, appended into the
-// `perk:plan-context` injection (extension/factories/planMode.ts) when present.
+// `perk:plan-context` injection (extension/pi/v1/plan.ts) when present.
 //
 // Deliberately dependency-free: rather than pull a runtime TOML dependency into the published
 // extension, this reads the narrow TOML subset perk actually uses — `[section]` headers +
@@ -48,9 +48,11 @@ export interface PerkConfig {
   /**
    * The agent-keyed `[models.subagents]` table: a per-agent model override for each perk-owned
    * project agent (`pr-reviewer`, `review-classifier`, `objective-explorer`, `conflict-resolver`,
-   * `learn-analyst`, `adversarial-reviewer`, `review-angle-selector`, `draft-reviewer`,
+   * `learn-analyst`, `adversarial-reviewer`, `draft-reviewer`,
    * `harvest-analyst` — consumed by `run_harvest_wave` at execute time — `dream-analyst` and
-   * `dream-reducer` — consumed by `run_dream_wave` at execute time — and the
+   * `dream-reducer` — consumed by `run_dream_wave` at execute time — `scout` — the
+   * general-purpose read-only analysis lane (task-defined scope), consumed by `run_scout_wave`
+   * at execute time — and the
    * dev-only `session-auditor`, whose def is repo-local to perk's own repository
    * (`.pi/agents/perk-dev/session-auditor.md`, never delivered by `perk init`), so the key is
    * dormant in consumer repos). Each configured
@@ -58,8 +60,12 @@ export interface PerkConfig {
    * workflowScript call — a default flowing onto every lane, single-child runs included (as
    * /pr-review does); when a key is absent the agent's frontmatter `model` (in
    * `.pi/agents/perk/<name>.md`; the session-auditor's in its repo-local def) is the default.
-   * (`subagents.agentOverrides` does NOT reach project agents — `pi-subagents`'
-   * `applyBuiltinOverrides` applies only to builtins — so this inline injection is the mechanism.)
+   * (Since pi-subagents 0.64.0, `subagents.agentOverrides` applies its FULL override set to
+   * custom/project agents too — a settings override CAN displace a def's frontmatter-pinned
+   * `model:` (the pre-0.64 frontmatter-sensitive fill is gone; verified in the installed
+   * package source). The inline workflow-level injection remains perk's mechanism on its own
+   * merits: the config table is perk-owned (no settings churn), and the spawn-time
+   * workflow-level `model` wins over the def-level model however that def model was set.)
    * A value may carry a `:thinking` suffix (`"anthropic/claude-sonnet-4-5:high"`) or be the
    * `"inherit"` sentinel (child inherits the parent session's model) — both resolved by
    * pi-subagents on the injected value (the last-colon segment counts as thinking only when it
@@ -73,11 +79,11 @@ export interface PerkConfig {
     "conflict-resolver"?: string;
     "learn-analyst"?: string;
     "adversarial-reviewer"?: string;
-    "review-angle-selector"?: string;
     "draft-reviewer"?: string;
     "harvest-analyst"?: string;
     "dream-analyst"?: string;
     "dream-reducer"?: string;
+    scout?: string;
     "session-auditor"?: string;
   };
   /**
@@ -125,8 +131,8 @@ function unescapeBasic(raw: string): string {
  * Parse the narrow TOML subset perk consumes. Returns `{ tables, arrays }`: `tables` is a
  * `{ section: { key: scalar } }` map (top-level keys under the `""` section); `arrays` is a
  * `{ name: [{ key: scalar }, ...] }` map fed by `[[name]]` array-of-tables. Scalars are quoted
- * strings, native `true`/`false` booleans, and numeric literals; anything else is skipped —
- * this is intentionally NOT a full TOML parser.
+ * strings (basic `"…"`/`"""…"""` and literal `'…'`/`'''…'''`), native `true`/`false` booleans,
+ * and numeric literals; anything else is skipped — this is intentionally NOT a full TOML parser.
  */
 export function parseTomlSubset(text: string): TomlSubset {
   const root: Record<string, TomlScalar> = {};
@@ -168,17 +174,19 @@ export function parseTomlSubset(text: string): TomlSubset {
     const value = line.slice(eq + 1).trim();
     if (key === "") continue;
 
-    // Multi-line basic string: """ ... """ (possibly spanning lines).
-    if (value.startsWith('"""')) {
+    // Multi-line strings: basic `""" ... """` (escapes honoured) or literal `''' ... '''`
+    // (bytes verbatim), possibly spanning lines.
+    const multi = value.startsWith('"""') ? '"""' : value.startsWith("'''") ? "'''" : null;
+    if (multi) {
       let body = value.slice(3);
-      if (body.endsWith('"""') && body.length >= 3) {
+      if (body.endsWith(multi) && body.length >= 3) {
         body = body.slice(0, -3);
       } else {
         const parts: string[] = [body];
         i++;
         for (; i < lines.length; i++) {
           const raw = lines[i] ?? "";
-          const end = raw.indexOf('"""');
+          const end = raw.indexOf(multi);
           if (end !== -1) {
             // A bare closing delimiter on its own line contributes no trailing content (so the
             // newline that precedes it is not appended as an empty segment).
@@ -191,7 +199,7 @@ export function parseTomlSubset(text: string): TomlSubset {
         // A leading newline immediately after the opening delimiter is trimmed (TOML rule).
         if (body.startsWith("\n")) body = body.slice(1);
       }
-      dest[key] = unescapeBasic(body);
+      dest[key] = multi === '"""' ? unescapeBasic(body) : body;
       continue;
     }
 
@@ -202,6 +210,13 @@ export function parseTomlSubset(text: string): TomlSubset {
       continue;
     }
 
+    // Single-line literal string: '...' (no escapes; a trailing inline comment is dropped).
+    const literal = value.match(/^'([^']*)'/);
+    if (literal) {
+      dest[key] = literal[1] ?? "";
+      continue;
+    }
+
     // Unquoted scalar: strip an inline `#` comment, then read native booleans and numbers.
     const hash = value.indexOf("#");
     const bare = (hash === -1 ? value : value.slice(0, hash)).trim();
@@ -326,11 +341,11 @@ const SUBAGENT_KEYS = [
   "conflict-resolver",
   "learn-analyst",
   "adversarial-reviewer",
-  "review-angle-selector",
   "draft-reviewer",
   "harvest-analyst",
   "dream-analyst",
   "dream-reducer",
+  "scout",
   // Dev-only: the perk-dev session-audit judgment wave's auditor (dormant in consumer repos).
   "session-auditor",
 ] as const;
@@ -387,12 +402,135 @@ export const GITHUB_ISSUE_BACKEND_ID: IssueBackendId = "github";
  * because the TS plane only renders prompts — it never writes canonical issues.
  */
 export function resolveIssueBackendId(cwd: string): IssueBackendId {
+  const backend = resolveIssueDestination(cwd).backend;
+  if (backend === "github" || backend === "linear") return backend;
+  return GITHUB_ISSUE_BACKEND_ID;
+}
+
+/** The committed `[issues]` routing keys — where a save is written and (Linear) which team owns it. */
+export interface IssueDestination {
+  backend: string | null;
+  team: string | null;
+}
+
+/**
+ * The committed `[issues]` routing as the save-destination fence reads it. `keys` when the
+ * document provably spells the table the way the subset reader parses it — `backend`/`team`
+ * are then exactly what Python's `tomllib` reads; `document` when parity cannot be proven (a
+ * dotted-key / inline-table / quoted-key spelling, an escape, a duplicate header …) — the
+ * verbatim text travels alongside the best-effort keys so the fence can widen to every byte that
+ * might route the save instead of trusting a read the authoritative parser may not share.
+ */
+export type IssueRouting =
+  | ({ kind: "keys" } & IssueDestination)
+  | ({ kind: "document"; text: string } & IssueDestination);
+
+/** `StrippedStr`'s boundary rule: a string is stripped and a blank one reads as absent. */
+function strippedString(value: TomlScalar | undefined): string | null {
+  if (typeof value !== "string") return null;
+  const stripped = value.trim();
+  return stripped === "" ? null : stripped;
+}
+
+/**
+ * Can the fence trust `parseTomlSubset(text).tables.issues` as exactly what Python's `tomllib`
+ * reads for `[issues] backend`/`team`? Proven only when the document spells the table in the one
+ * shape the subset reader handles at parity: a single bare `[issues]` header; `backend`/`team`
+ * (each at most once, undotted) as plain single-line strings with no backslash (the subset's
+ * escape handling is not `tomllib`'s); and no other header or key segment spelling `issues` —
+ * dotted keys, inline tables, quoted keys, `[[issues]]` and super-/sub-tables all reach `tomllib`
+ * unseen here. Every line the scanner cannot classify answers `false` (widen, never guess).
+ */
+function issueKeysProvable(text: string): boolean {
+  const lines = text.split(/\r?\n/);
+  let inIssues = false;
+  let issuesHeaders = 0;
+  const seen = new Set<string>();
+  for (let i = 0; i < lines.length; i++) {
+    const line = (lines[i] ?? "").trim();
+    if (line === "" || line.startsWith("#")) continue;
+
+    if (line.startsWith("[")) {
+      const array = line.match(/^\[\[([^\]]+)\]\]$/);
+      const table = array ? null : line.match(/^\[([^\]]+)\]$/);
+      const inner = (array?.[1] ?? table?.[1])?.trim();
+      // A header shape the subset reader skips (e.g. a trailing comment) would misplace the keys
+      // that follow it; quoted segments can spell any key at all.
+      if (inner === undefined || /["']/.test(inner)) return false;
+      if (table && inner === "issues") {
+        issuesHeaders++;
+        if (issuesHeaders > 1) return false;
+        inIssues = true;
+        continue;
+      }
+      const segments = inner.split(".").map((segment) => segment.trim());
+      if (segments.includes("issues")) return false;
+      inIssues = false;
+      continue;
+    }
+
+    const eq = line.indexOf("=");
+    if (eq === -1) return false;
+    const key = line.slice(0, eq).trim();
+    const value = line.slice(eq + 1).trim();
+    if (key === "" || /["']/.test(key)) return false;
+    const segments = key.split(".").map((segment) => segment.trim());
+    if (segments.includes("issues")) return false;
+    if (inIssues && (segments[0] === "backend" || segments[0] === "team")) {
+      if (segments.length > 1 || seen.has(key)) return false;
+      seen.add(key);
+      if (!/^("[^"\\]*"|'[^']*')\s*(#.*)?$/.test(value)) return false;
+      continue;
+    }
+    // Skip a multi-line string body (the subset reader's rule) so its lines are never mistaken
+    // for headers or keys.
+    const multi = value.startsWith('"""') ? '"""' : value.startsWith("'''") ? "'''" : null;
+    if (multi) {
+      const body = value.slice(3);
+      if (body.endsWith(multi) && body.length >= 3) continue;
+      for (i++; i < lines.length; i++) {
+        if ((lines[i] ?? "").includes(multi)) break;
+      }
+    }
+  }
+  return true;
+}
+
+/**
+ * Read the committed main-checkout `[issues]` routing for the save-destination fence: the
+ * `backend`/`team` keys as Python's boundary reads them (stripped, blank → `null`, non-string →
+ * `null`) plus whether that read is provably `tomllib`'s (`kind: "keys"`) or the whole document
+ * must stand in for it (`kind: "document"`, carrying the verbatim text). Committed
+ * `.perk/config.toml` only (never the `local.toml` overlay), anchored to the MAIN checkout like
+ * `resolveIssueBackendId`. A missing file or a read failure is the empty table (`keys`,
+ * both `null`) — Python reads the same absence.
+ */
+export function resolveIssueRouting(cwd: string): IssueRouting {
+  const empty: IssueRouting = { kind: "keys", backend: null, team: null };
   try {
-    const committed = readTomlFile(configFile(mainCheckoutRoot(cwd)));
-    const backend = committed.tables.issues?.backend;
-    if (backend === "github" || backend === "linear") return backend;
-    return GITHUB_ISSUE_BACKEND_ID;
+    const path = configFile(mainCheckoutRoot(cwd));
+    if (!existsSync(path)) return empty;
+    const text = readFileSync(path, "utf8");
+    const issues = parseTomlSubset(text).tables.issues;
+    const keys: IssueDestination = {
+      backend: strippedString(issues?.backend),
+      team: strippedString(issues?.team),
+    };
+    return issueKeysProvable(text)
+      ? { kind: "keys", ...keys }
+      : { kind: "document", text, ...keys };
   } catch {
-    return GITHUB_ISSUE_BACKEND_ID;
+    return empty;
   }
 }
+
+/**
+ * Read the committed main-checkout `[issues] backend`/`team` values (no validation, no default):
+ * the two keys that decide where the Python save lands (`perk/backends/resolve.py`). The
+ * `resolveIssueRouting` read without its parity verdict — callers wanting the fail-safe backend
+ * id use `resolveIssueBackendId`.
+ */
+export function resolveIssueDestination(cwd: string): IssueDestination {
+  const { backend, team } = resolveIssueRouting(cwd);
+  return { backend, team };
+}

package/extension/substrate/git.ts

@@ -3,10 +3,11 @@
 // Node builtins only (so it loads cleanly under `node --test`); shells `git` via `execFileSync`,
 // never with a shell. Fail-open by design: every failure degrades to the caller's `cwd` (or null
 // where stated) rather than throwing — the carriers that use this must never wedge a session.
-// The ONE deliberate fail-closed composition is `revalidationBracket` (documented there): a
-// snapshot proof must treat an unprovable probe as drift, never as "unchanged".
+// `revalidationBracket` and `worktreeGitDir` deliberately fail closed: snapshot proofs and
+// writer coordination must never invent identity from a failed probe.
 
 import { execFileSync } from "node:child_process";
+import { realpathSync, statSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
 
 /**
@@ -35,6 +36,64 @@ export function mainCheckoutRoot(cwd: string): string {
   return resolve(common, "..");
 }
 
+/** Canonical PER-WORKTREE Git directory for execution exclusion, never a cwd fallback. */
+export function worktreeGitDir(cwd: string): string | null {
+  try {
+    const out = execFileSync("git", ["rev-parse", "--absolute-git-dir"], {
+      cwd,
+      encoding: "utf8",
+      timeout: 5_000,
+      stdio: ["ignore", "pipe", "ignore"],
+    }).replace(/\r?\n$/, "");
+    if (!isAbsolute(out) || /[\0\r\n]/.test(out) || !statSync(out).isDirectory()) return null;
+    return realpathSync(out);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The git-config entries that decide WHERE a GitHub-backed save lands: every `remote.*.url` and
+ * `remote.*.gh-resolved` key (`gh` resolves the target repo from exactly these). Returns the
+ * NUL-separated `key\nvalue` entries sorted lexicographically and re-joined with `\0` (a
+ * canonical form fit for digesting), `""` when the repo has no remotes at all (git exits 1 with
+ * empty stdout), or `null` when the destination cannot be verified (not a repo, git missing,
+ * any other failure). **Fails closed** on purpose: a caller fencing a save must treat `null` as
+ * "unverifiable", never as "unchanged". No other git config participates — `branch.*`,
+ * `user.*`, and friends never route a save, so they must never invalidate a review.
+ *
+ * Repo membership is probed first (`worktreeGitDir`): outside a repo `git config` still reads
+ * the global/system files and reports "no match" — which would masquerade as a verified empty
+ * destination.
+ */
+export function remoteConfig(cwd: string): string | null {
+  if (worktreeGitDir(cwd) === null) return null;
+  try {
+    const out = execFileSync(
+      "git",
+      ["config", "--null", "--get-regexp", "^remote\\..*\\.(url|gh-resolved)$"],
+      {
+        cwd,
+        encoding: "utf8",
+        timeout: 5_000,
+        maxBuffer: 1024 * 1024,
+        stdio: ["ignore", "pipe", "ignore"],
+      },
+    );
+    return out
+      .split("\0")
+      .filter((entry) => entry !== "")
+      .sort()
+      .join("\0");
+  } catch (error) {
+    // `git config --get-regexp` exits 1 with empty stdout when NO key matches — a repo with no
+    // remotes is a verified (empty) destination, not a failure.
+    const failure = error as { status?: unknown; stdout?: unknown };
+    if (failure.status === 1 && String(failure.stdout ?? "") === "") return "";
+    return null;
+  }
+}
+
 /** Run one git command; trimmed stdout, or null on any failure (the module's fail-open style). */
 function git(cwd: string, args: string[], timeout?: number): string | null {
   try {
@@ -96,6 +155,27 @@ export function headSha(cwd: string): string | null {
   return git(cwd, ["rev-parse", "HEAD"]);
 }
 
+/** Whether HEAD is a positively-PROVEN unborn branch pointer: `symbolic-ref -q HEAD` resolves
+ * AND `for-each-ref` proves the pointed-to ref ABSENT (an exit-0 run, empty output). `false` =
+ * the ref EXISTS (a failing `headSha` read was transient, not unborn); **fail-open to null**
+ * when either probe fails outright — callers must never read null as unborn. Own `execFileSync`
+ * for the second probe: `git()` conflates empty output (absence — meaningful here) with
+ * failure. */
+export function unbornHead(cwd: string): boolean | null {
+  const pointer = git(cwd, ["symbolic-ref", "-q", "HEAD"]);
+  if (pointer === null) return null;
+  try {
+    const out = execFileSync("git", ["for-each-ref", "--format=%(refname)", pointer], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return out.trim() === "";
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Whether the working tree has anything uncommitted (`git status --porcelain`). Untracked files
  * count as dirty — deliberate: the model decides whether they belong in a commit. **Fail-open to
@@ -122,9 +202,11 @@ export function worktreeDirty(cwd: string): boolean | null {
  * `git status --porcelain`, so a status-based cleanliness proof over a flagged index is not a
  * proof. **Fail-open to null** on any failure (not a repo, git missing) — callers must NOT
  * conflate null with "no flags". Own `execFileSync` rather than the `git()` helper: `git()`
- * conflates empty output (an empty index — meaningful here) with failure.
+ * conflates empty output (an empty index — meaningful here) with failure. Module-private:
+ * `revalidationBracket`'s default flags probe is the one consumer (tests reach the arms through
+ * the bracket — real-repo flag arms — and its `probes` seam for the null arm).
  */
-export function indexHidesChanges(cwd: string): boolean | null {
+function indexHidesChanges(cwd: string): boolean | null {
   try {
     const out = execFileSync("git", ["ls-files", "-v"], {
       cwd,
@@ -141,8 +223,8 @@ export function indexHidesChanges(cwd: string): boolean | null {
 }
 
 /**
- * The dream-snapshot revalidation bracket (contracts.md §8.65) — the module's ONE deliberately
- * **fail-closed** composition (a documented exception to the fail-open charter above): it exists
+ * The dream-snapshot revalidation bracket (contracts.md §8.65) — a deliberately
+ * **fail-closed** snapshot composition (an exception to the fail-open probe defaults): it exists
  * to PROVE the repository still matches a stamped snapshot, so an unprovable probe must read as
  * drift, never as "unchanged". The claim is END-STATE equality only — HEAD unchanged, the
  * working tree clean, and no assume-unchanged/skip-worktree index flags (which would hide edits

package/extension/substrate/modelVisible.ts

@@ -0,0 +1,53 @@
+// Model-visible output capping (route-don't-relay). The byte-cap helper the stage-execution
+// seam and the CI executor bound their model-facing text with: full results stay in scratch
+// files; only a capped, notice-carrying slice reaches the model.
+
+/** The model-visible byte cap (matches subagent's PER_TASK_OUTPUT_CAP); overridable per call. */
+export const DEFAULT_MODEL_VISIBLE_CAP = 50 * 1024;
+
+export interface CapResult {
+  /** The (possibly truncated) text safe to show the model. */
+  shown: string;
+  /** Total UTF-8 byte length of the original text. */
+  bytesTotal: number;
+  /** UTF-8 byte length of `shown` (before the truncation notice). */
+  bytesShown: number;
+  /** Whether truncation occurred. */
+  truncated: boolean;
+}
+
+/**
+ * UTF-8-byte-safe truncation (subagent's byte-trim loop). Under cap ⇒ unchanged, truncated:false.
+ * When truncated, a notice points at the scratch file holding the full result; the notice sits at
+ * the cut edge (appended in head mode, prepended in tail mode) so a top-down reader immediately
+ * knows which side is missing.
+ *
+ * `keep` mirrors the SDK's truncateHead/truncateTail guidance: "head" (default) for
+ * model-authored summaries/handoffs where the beginning matters; "tail" for command/CI logs where
+ * failure summaries live at the end. Deliberately perk's own byte-only util (not the SDK's
+ * line-count-aware `truncateTail`): `CapResult`'s byte fields and the scratch-pointing notice are
+ * load-bearing in `CiCheckResult`. Pure.
+ */
+export function capForModel(
+  text: string,
+  cap: number = DEFAULT_MODEL_VISIBLE_CAP,
+  scratchPath: string | null = null,
+  keep: "head" | "tail" = "head",
+): CapResult {
+  const bytesTotal = Buffer.byteLength(text, "utf8");
+  if (bytesTotal <= cap) {
+    return { shown: text, bytesTotal, bytesShown: bytesTotal, truncated: false };
+  }
+  let trimmed = keep === "head" ? text.slice(0, cap) : text.slice(-cap);
+  while (Buffer.byteLength(trimmed, "utf8") > cap) {
+    trimmed = keep === "head" ? trimmed.slice(0, -1) : trimmed.slice(1);
+  }
+  const bytesShown = Buffer.byteLength(trimmed, "utf8");
+  const omitted = bytesTotal - bytesShown;
+  const where = scratchPath ? ` Full output preserved at ${scratchPath}.` : "";
+  const shown =
+    keep === "head"
+      ? `${trimmed}\n\n[Output truncated: ${omitted} bytes omitted.${where}]`
+      : `[Output truncated: ${omitted} bytes omitted.${where}]\n\n${trimmed}`;
+  return { shown, bytesTotal, bytesShown, truncated: true };
+}

package/extension/substrate/paths.ts

@@ -1,8 +1,8 @@
 // perk-owned dot-directory path construction — the TS twin of perk/substrate/paths.py
 // (contracts.md §8.1).
 //
-// The sole construction site for the perk-owned config family (`config.toml`/`local.toml`) and
-// the perk dir. The config family now lives at `.perk/` (TS reads the target only — the legacy
+// The sole construction site for the perk-owned config family (`config.toml`/`local.toml`).
+// The config family now lives at `.perk/` (TS reads the target only — the legacy
 // `.pi/perk.toml` migration is Python-side). The workflow family lives in the established cache
 // seam (substrate/cache.ts's `workflowDir`); together these two modules own every perk-owned
 // dot-path on this plane.
@@ -17,11 +17,6 @@ import { join } from "node:path";
 export const CONFIG_FILENAME = "config.toml";
 export const LOCAL_CONFIG_FILENAME = "local.toml";
 
-/** The perk-owned dot-dir root (shared with Pi today). */
-export function perkDir(cwd: string): string {
-  return join(cwd, ".pi");
-}
-
 /** The single config-family redirection point (the file helpers derive from it). */
 export function configDir(cwd: string): string {
   return join(cwd, ".perk");

package/extension/substrate/prompts.ts

@@ -17,6 +17,10 @@
 //
 // This seam is LIVE in production: render is imported by the worker, the warm doors, the
 // factories, and the mode/adapter context modules (the `prompts/contexts/` injections).
+//
+// Besides the render seam itself, the module carries ONE cross-plane selector wrapping it:
+// `planReadInstruction`, the per-backend plan-read arm shared by the doors and the
+// stage-execution seam.
 
 import { render as miniJinjaRender } from "./miniJinja.ts";
 
@@ -24,3 +28,21 @@ import { render as miniJinjaRender } from "./miniJinja.ts";
 export function render(name: string, vars: Record<string, unknown>): string {
   return miniJinjaRender(name, vars);
 }
+
+/**
+ * The per-backend plan-read instruction — the prompt SSOT for "how do I read the saved
+ * plan". Byte-identical to `src/perk/run/launch/prompts.py::_plan_read_instruction` (the Python
+ * twin — likewise a prompts module); drift in either plane fails the paired parity suites.
+ * `github` reads via `gh`; `linear` points at the pi-mono-linear tools with an `open <url>`
+ * fallback; any other provider falls back to opening the url.
+ *
+ * The wording lives in the canonical templates `prompts/common/plan-read/*.md`, rendered
+ * identically by both planes via the shared render seam (contracts.md §8.31); branching stays in
+ * code — only the arm chosen and the vars passed differ. Golden-fixture parity (the three
+ * `plan-read-*` cases) plus a thin per-arm selection test replace the dedicated substring parity.
+ */
+export function planReadInstruction(provider: string, prId: string, url: string): string {
+  if (provider === "github") return render("common/plan-read/github.md", { pr_id: prId, url });
+  if (provider === "linear") return render("common/plan-read/linear.md", { pr_id: prId, url });
+  return render("common/plan-read/other.md", { pr_id: prId, url });
+}

package/extension/substrate/registry.ts

@@ -12,6 +12,8 @@ import { sharedDir } from "./resources.ts";
 export interface RegistryStage {
   id: string;
   command: string;
+  /** `read-only` | `read-write` — the gate the cold claim persists as `perk:workflow-state.mode`. */
+  mode: string;
   doors: Record<string, boolean>;
   predecessors: string[];
   successors: string[];