@mgiles/perk 1.0.1

package/extension/substrate/bindingDelivery.ts

@@ -0,0 +1,199 @@
+// Warm-door (TS-extension) delivery of resolved skill bindings — the in-session twin of the cold
+// door (perk/substrate/binding_delivery.py). Both planes render the SAME resolved overlay (defaults
+// ⊕ user bindings; `nudge` -> a pointer line, `transclude` -> the inlined skill body) under the
+// SAME header literal. The cold door appends it to a launch's initial prompt; this module renders
+// it at two WARM surfaces:
+//
+//   Mechanism A — stage triggers: a `before_agent_start` handler (mirroring planMode.ts /
+//   objectiveAuthor.ts) injects the launched stage's bindings as a hidden context message — the
+//   delivery path for `stage:plan`'s `perk-plan` pointer, since a cold `perk plan` launches idle
+//   (no initial prompt to augment).
+//   Mechanism B — `bindingSuffix()` is appended into the guidance of perk's warm slash-commands so
+//   each self-delivers its pointer (a warm `/objective-plan` run outside a stage:objective-plan
+//   session gets none from Mechanism A).
+//
+// This is the SINGLE delivery path for perk's own nudges. Delivery NEVER double-delivers: the
+// cold↔warm dedup marker is `BINDING_HEADER` itself — the cold door's initial prompt and every warm
+// injection carry it, so Mechanism A injects ONLY when nothing on the branch already carries the
+// header (idempotent across turns/reloads; after compaction drops the original it re-delivers).
+//
+// LBYL throughout: a missing/unreadable transclude target degrades to the nudge pointer with a
+// loud-but-non-fatal warning, never throws, never blocks a turn. Resolver shape `issues` are NOT
+// surfaced warm (the cold launch + doctor own them); only the transclude `warnings` are.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadDefaultBindings, resolveBindings, type SkillBinding } from "./bindings.ts";
+import { loadPerkConfig } from "./config.ts";
+import { type BranchEntry, branchOf, rebuildWorkflowState } from "./workflowState.ts";
+
+/**
+ * The cross-plane dedup marker AND render header. MUST stay byte-identical to the Python cold
+ * door's `_HEADER` (perk/substrate/binding_delivery.py) — both planes render under it so a cold launch and a
+ * warm injection never double-deliver. Pinned by a literal test in both planes (§8.9).
+ */
+export const BINDING_HEADER = "The following skill binding(s) apply here:";
+
+/** The hidden context customType carrying a warm-injected stage-binding render (Mechanism A). */
+export const BINDING_CONTEXT_TYPE = "perk:binding-context";
+
+const SKILLS_SUBDIR = join(".agents", "skills");
+const SKILL_FILENAME = "SKILL.md";
+
+/** The rendered warm delivery for one trigger: the prompt fragment (or `null`) + any warnings. */
+export interface BindingRender {
+  text: string | null;
+  warnings: string[];
+}
+
+/**
+ * The full resolved bindings: the shipped defaults ⊕ the user overlay. The TS twin of cold's
+ * `resolve_bindings(...).bindings` (perk/substrate/binding_delivery.py) — delivers the defaults too
+ * (perk's own nudges are no longer hardcoded), so there is no longer a default subtraction.
+ */
+export function resolvedBindings(cwd: string): SkillBinding[] {
+  return resolveBindings(loadPerkConfig(cwd).bindings, loadDefaultBindings()).bindings;
+}
+
+/**
+ * Render the resolved bindings matching `trigger` into a header-joined fragment (or `null` when
+ * none match). `nudge` renders a `Follow the \`<skill>\` skill.` pointer; `transclude` inlines
+ * `.agents/skills/<skill>/SKILL.md` (frontmatter stripped), degrading to the nudge pointer with a
+ * loud-but-non-fatal warning when the file is absent/unreadable. Pure but for the LBYL file read.
+ */
+export function renderBindings(cwd: string, trigger: string): BindingRender {
+  const mine = resolvedBindings(cwd).filter((binding) => binding.trigger === trigger);
+  const warnings: string[] = [];
+  const parts: string[] = [];
+  for (const binding of mine) {
+    if (binding.mode === "transclude") {
+      const body = readSkillBody(cwd, binding.skill);
+      if (body !== null) {
+        parts.push(`Skill \`${binding.skill}\` (inlined for \`${binding.trigger}\`):\n\n${body}`);
+        continue;
+      }
+      warnings.push(
+        `skill binding: transclude target for \`${binding.skill}\` not found under ` +
+          `${SKILLS_SUBDIR}/${binding.skill}/${SKILL_FILENAME} — falling back to a pointer.`,
+      );
+    } else if (!skillInstalled(cwd, binding.skill)) {
+      // The nudge mirror of the transclude warning: a binding to a skill that is
+      // not installed is reported loud-but-non-fatal, never silently delivered. The pointer is
+      // still emitted so the model gets the nudge.
+      warnings.push(
+        `skill binding: skill \`${binding.skill}\` for \`${binding.trigger}\` is not installed ` +
+          `under ${SKILLS_SUBDIR}/${binding.skill}/${SKILL_FILENAME} — the pointer may dangle.`,
+      );
+    }
+    parts.push(`Follow the \`${binding.skill}\` skill.`);
+  }
+  const text = parts.length > 0 ? [BINDING_HEADER, ...parts].join("\n\n") : null;
+  return { text, warnings };
+}
+
+/**
+ * The Mechanism-B suffix: the rendered bindings for `trigger` to append into a warm command's
+ * guidance (empty string when none match). Every perk warm slash-command self-delivers its pointer
+ * this way, by `stage:<id>` or `command:<id>`. A leading blank line keeps it
+ * visually distinct from the guidance it follows. Any render warnings (missing transclude target or
+ * uninstalled nudge skill) are `console.error`-ed loud-but-non-fatal — the nudge
+ * fallback still reaches the model, but the misconfiguration is no longer surfaced silently.
+ */
+export function bindingSuffix(cwd: string, trigger: string): string {
+  const { text, warnings } = renderBindings(cwd, trigger);
+  for (const warning of warnings) console.error(`perk: ${warning}`);
+  return text ? `\n\n${text}` : "";
+}
+
+/** Whether `.agents/skills/<skill>/SKILL.md` exists under `cwd` (the warm delivery read path). */
+function skillInstalled(cwd: string, skill: string): boolean {
+  return existsSync(join(cwd, SKILLS_SUBDIR, skill, SKILL_FILENAME));
+}
+
+/** Read `.agents/skills/<skill>/SKILL.md` (frontmatter stripped); `null` if absent/unreadable. */
+function readSkillBody(cwd: string, skill: string): string | null {
+  const path = join(cwd, SKILLS_SUBDIR, skill, SKILL_FILENAME);
+  if (!existsSync(path)) return null;
+  try {
+    return stripFrontmatter(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Drop a leading `---`-delimited YAML frontmatter block; return the body stripped. */
+function stripFrontmatter(text: string): string {
+  if (!text.startsWith("---\n")) return text;
+  const lines = text.split("\n");
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === "---")
+      return lines
+        .slice(i + 1)
+        .join("\n")
+        .trim();
+  }
+  return text; // no closing delimiter — leave the text unchanged
+}
+
+/**
+ * Whether anything on the branch already carries `BINDING_HEADER` — the cold launch's initial
+ * prompt OR a prior warm injection. Serializing each entry is the robust, shape-agnostic scan: the
+ * header is a distinctive literal, so a substring hit means "already delivered on this branch".
+ */
+function branchHasHeader(branch: readonly BranchEntry[]): boolean {
+  return branch.some((entry) => JSON.stringify(entry).includes(BINDING_HEADER));
+}
+
+/** The launched stage's `stage:<id>` render, or `null` when there is no stage / nothing matches. */
+function activeStageRender(cwd: string, branch: readonly BranchEntry[]): BindingRender | null {
+  const stage = rebuildWorkflowState(branch).stage;
+  if (!stage) return null;
+  return renderBindings(cwd, `stage:${stage}`);
+}
+
+/**
+ * Register warm-door binding delivery: Mechanism A's dedup-guarded `before_agent_start` injection
+ * plus a `context` strip mirroring planMode.ts / objectiveAuthor.ts (keep while the stage's
+ * bindings are live; strip the stale custom otherwise). Inert when nothing matches the stage;
+ * never throws. Mechanism B (`bindingSuffix`) is wired by the command modules themselves.
+ */
+export function registerBindingDelivery(pi: ExtensionAPI): void {
+  // Mechanism A — inject the launched stage's resolved bindings as a hidden context message,
+  // but ONLY when no entry on the branch already carries BINDING_HEADER (the cold door's initial
+  // prompt or a prior warm inject) — the cold↔warm idempotency guard.
+  pi.on("before_agent_start", async (_event, ctx) => {
+    const branch = branchOf(ctx);
+    const rendered = activeStageRender(ctx.cwd, branch);
+    if (rendered === null || rendered.text === null) return;
+    if (branchHasHeader(branch)) return;
+    for (const warning of rendered.warnings) console.error(`perk: ${warning}`);
+    return {
+      message: {
+        customType: BINDING_CONTEXT_TYPE,
+        content: rendered.text,
+        display: false,
+      },
+    };
+  });
+
+  // Strip a STALE binding-context custom from the model window when the current stage no longer
+  // renders bindings (stage changed, or the overlay was removed) — the same hygiene planMode /
+  // objectiveAuthor apply to their authoring contexts. While the stage IS live we keep it (the
+  // model must see the nudge), and the dedup above relies on it persisting on the branch.
+  //
+  // Deliberately NARROWER than planMode: it strips ONLY the BINDING_CONTEXT_TYPE custom, never a
+  // user message carrying the header — a cold launch's initial prompt legitimately carries
+  // BINDING_HEADER and must survive in context.
+  pi.on("context", async (event, ctx) => {
+    const branch = branchOf(ctx);
+    const rendered = activeStageRender(ctx.cwd, branch);
+    if (rendered !== null && rendered.text !== null) return;
+    return {
+      messages: event.messages.filter((m) => {
+        const msg = m as { customType?: string };
+        return msg.customType !== BINDING_CONTEXT_TYPE;
+      }),
+    };
+  });
+}

package/extension/substrate/bindings.ts

@@ -0,0 +1,180 @@
+// The TS plane's reader for the shared skill-binding set (`shared/bindings.yaml`).
+//
+// Twin of perk/substrate/bindings.py: both planes parse the SAME bundled file (no codegen). This is
+// the SECOND parsed cross-plane contract (the first being registry.yaml). A binding maps a
+// `trigger` ("<kind>:<id>", kind ∈ {stage, command}) to a `skill` plus a per-binding
+// delivery `mode` (nudge/transclude).
+//
+// The Python CLI is the authoritative validator (perk/substrate/bindings.py); this side does a thin
+// structural parse only — no deep content validation here. The binding set is CONSUMED: the
+// resolver (`resolveBindings`) and warm-door delivery (`extension/substrate/bindingDelivery.ts`)
+// are live.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "./miniYaml.ts";
+import { sharedDir } from "./resources.ts";
+
+export interface SkillBinding {
+  trigger: string;
+  kind: string;
+  targetId: string;
+  skill: string;
+  mode: string;
+}
+
+export const BINDING_TRIGGER_KINDS = ["stage", "command"] as const;
+export const BINDING_MODES = ["nudge", "transclude"] as const;
+
+/** One shape finding for a user binding (registry-free; mirror of Python's `Issue`). */
+export interface BindingIssue {
+  where: string;
+  message: string;
+}
+
+/** The effective binding set after overlaying user bindings onto shipped defaults. */
+export interface ResolvedBindings {
+  bindings: SkillBinding[];
+  issues: BindingIssue[];
+}
+
+/** Split a `"<kind>:<id>"` trigger on the first `:`. No colon -> `["", ""]`. */
+function splitTrigger(trigger: string): [string, string] {
+  const idx = trigger.indexOf(":");
+  if (idx === -1) return ["", ""];
+  return [trigger.slice(0, idx), trigger.slice(idx + 1)];
+}
+
+/** Parse the bundled `bindings.yaml`. Throws on a missing file or unexpected shape. */
+export function loadDefaultBindings(): SkillBinding[] {
+  const path = join(sharedDir(), "bindings.yaml");
+  const data = parse(readFileSync(path, "utf8")) as unknown;
+
+  if (typeof data !== "object" || data === null) {
+    throw new Error(`perk: ${path} is not a mapping`);
+  }
+  const record = data as Record<string, unknown>;
+  const bindings = record.bindings;
+  if (!Array.isArray(bindings)) {
+    throw new Error(`perk: ${path} has no bindings`);
+  }
+
+  return bindings.map((raw) => {
+    const entry = raw as Record<string, unknown>;
+    const trigger = typeof entry.trigger === "string" ? entry.trigger : "";
+    const [kind, targetId] = splitTrigger(trigger);
+    return {
+      trigger,
+      kind,
+      targetId,
+      skill: typeof entry.skill === "string" ? entry.skill : "",
+      mode: typeof entry.mode === "string" ? entry.mode : "",
+    };
+  });
+}
+
+/**
+ * Parse `.pi/perk.toml` `[[bindings]]` rows (string tables) into `SkillBinding`s. Tolerant like
+ * the YAML reader: absent/ill-typed fields become empty strings so the *resolver* reports them.
+ */
+export function parseUserBindings(rows: Array<Record<string, string>>): SkillBinding[] {
+  return rows.map((row) => {
+    const trigger = typeof row.trigger === "string" ? row.trigger : "";
+    const [kind, targetId] = splitTrigger(trigger);
+    return {
+      trigger,
+      kind,
+      targetId,
+      skill: typeof row.skill === "string" ? row.skill : "",
+      mode: typeof row.mode === "string" ? row.mode : "",
+    };
+  });
+}
+
+/**
+ * Shape issues for a *single* binding (skill/mode/trigger well-formedness). Registry-free —
+ * target-existence is `doctor`'s job. Duplicate-trigger detection is the caller's.
+ */
+function bindingIssues(binding: SkillBinding): BindingIssue[] {
+  const issues: BindingIssue[] = [];
+  const where = binding.trigger || "bindings";
+
+  if (!binding.skill) issues.push({ where, message: "missing `skill`" });
+  if (!(BINDING_MODES as readonly string[]).includes(binding.mode)) {
+    issues.push({ where, message: `\`mode\` must be one of ${BINDING_MODES.join(", ")}` });
+  }
+
+  if (!binding.trigger) {
+    issues.push({ where: "bindings", message: "a binding is missing its `trigger`" });
+  } else if (!binding.trigger.includes(":")) {
+    issues.push({ where, message: "`trigger` must be of the form `<kind>:<id>`" });
+  } else if (!(BINDING_TRIGGER_KINDS as readonly string[]).includes(binding.kind)) {
+    issues.push({
+      where,
+      message: `\`trigger\` kind must be one of ${BINDING_TRIGGER_KINDS.join(", ")}`,
+    });
+  } else if (!binding.targetId) {
+    issues.push({ where, message: "`trigger` has an empty `<id>`" });
+  }
+
+  return issues;
+}
+
+/** Return every shape issue across a user binding set (empty == valid); duplicates included. */
+export function validateUserBindings(bindings: SkillBinding[]): BindingIssue[] {
+  const issues: BindingIssue[] = [];
+  const seen = new Set<string>();
+  for (const binding of bindings) {
+    issues.push(...bindingIssues(binding));
+    if (binding.trigger) {
+      if (seen.has(binding.trigger)) {
+        issues.push({ where: binding.trigger, message: "duplicate `trigger`" });
+      }
+      seen.add(binding.trigger);
+    }
+  }
+  return issues;
+}
+
+/**
+ * Overlay user bindings onto shipped defaults (trigger-keyed; pure). Defaults are trusted (not
+ * re-validated). Each user binding is applied iff it is shape-valid AND its trigger was not already
+ * applied by an earlier user binding; otherwise it is dropped and its issue recorded. An applied
+ * binding replaces in place the default with the same trigger, or appends at a new trigger — so the
+ * resolved set has unique triggers by construction. Target-existence stays `doctor`.
+ */
+export function resolveBindings(
+  userBindings: SkillBinding[],
+  defaults: SkillBinding[] = loadDefaultBindings(),
+): ResolvedBindings {
+  const resolved = [...defaults];
+  const index = new Map<string, number>();
+  for (let i = 0; i < resolved.length; i++) {
+    const entry = resolved[i];
+    if (entry) index.set(entry.trigger, i);
+  }
+  const issues: BindingIssue[] = [];
+  const applied = new Set<string>();
+
+  for (const binding of userBindings) {
+    const shapeIssues = bindingIssues(binding);
+    if (shapeIssues.length > 0) {
+      issues.push(...shapeIssues);
+      continue;
+    }
+    if (applied.has(binding.trigger)) {
+      issues.push({ where: binding.trigger, message: "duplicate `trigger`" });
+      continue;
+    }
+    applied.add(binding.trigger);
+    const at = index.get(binding.trigger);
+    if (at !== undefined) {
+      resolved[at] = binding;
+    } else {
+      index.set(binding.trigger, resolved.length);
+      resolved.push(binding);
+    }
+  }
+
+  return { bindings: resolved, issues };
+}

package/extension/substrate/cache.ts

@@ -0,0 +1,163 @@
+// `.pi/workflow/` cache-tier I/O — the TS twin of perk/state/cache.py (contracts.md §8.1).
+//
+// Both planes read and write the SAME files; the cross-plane contract is the *files*, not a
+// shared module. State-tiering primitives only — no workflow semantics. Imports use no
+// relative paths (only node builtins), so this module loads cleanly under `node --test`.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface Handoff {
+  run_id: string;
+  consumed: boolean;
+  mode?: string;
+  /** The registry stage id the cold launch primed (e.g. `objective-author`). */
+  stage?: string;
+  pi_session_id?: string;
+  [key: string]: unknown;
+}
+
+export function workflowDir(cwd: string): string {
+  return join(cwd, ".pi", "workflow");
+}
+
+// --- handoff -----------------------------------------------------------------------------
+
+export function handoffPath(cwd: string, runId: string): string {
+  return join(workflowDir(cwd), "handoff", `${runId}.json`);
+}
+
+export function readHandoff(cwd: string, runId: string): Handoff | null {
+  const path = handoffPath(cwd, runId);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, "utf8")) as Handoff;
+}
+
+/** Mark a handoff consumed (idempotent); a no-op when absent. Keeps the file (audit + GC). */
+export function markHandoffConsumed(
+  cwd: string,
+  runId: string,
+  opts: { piSessionId?: string } = {},
+): void {
+  const data = readHandoff(cwd, runId);
+  if (data === null) return;
+  data.consumed = true;
+  if (opts.piSessionId !== undefined) data.pi_session_id = opts.piSessionId;
+  writeFileSync(handoffPath(cwd, runId), `${JSON.stringify(data, null, 2)}\n`, "utf8");
+}
+
+// --- scratch -----------------------------------------------------------------------------
+//
+// This module is the INTERIOR path-primitive seam for scratch/session-data (contracts.md §8.1):
+// production code never hand-builds the `scratch`/`runs` path segments
+// outside this module (guard-tested by cacheGuard.test.ts; the ctx-level current-run seam is
+// sessionData.ts and the exterior twin is perk/state/cache.py).
+
+export function scratchDir(cwd: string): string {
+  return join(workflowDir(cwd), "scratch");
+}
+
+export function runScratchDir(cwd: string, runId: string): string {
+  return join(scratchDir(cwd), "runs", runId);
+}
+
+/**
+ * The session data dir for a run — a dedicated `data/` subdir so
+ * run-scoped session artifacts never overlap perk machine records (dispatch.json,
+ * events.ndjson, ci-*.md) living directly in the run dir. Pure path — created lazily by the
+ * sessionData.ts write helpers.
+ */
+export function sessionDataDir(cwd: string, runId: string): string {
+  return join(runScratchDir(cwd, runId), "data");
+}
+
+export function ensureRunScratch(cwd: string, runId: string): string {
+  const dir = runScratchDir(cwd, runId);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * The run-scoped structured run-event stream (contracts §8.12) — an NDJSON file under the
+ * gitignored run scratch dir. Co-located with the run's read-only-child scratch so a runner/reader
+ * finds all run artifacts under one dir.
+ */
+export function runEventsPath(cwd: string, runId: string): string {
+  return join(runScratchDir(cwd, runId), "events.ndjson");
+}
+
+/** Names of all run scratch dirs (used to enumerate fork siblings). */
+export function listRunIds(cwd: string): string[] {
+  const dir = join(scratchDir(cwd), "runs");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name);
+}
+
+// --- plan-ref: the active plan->branch ref pointer (plan-ref.json) -----------------------
+
+/** The provider-agnostic plan ref (contracts.md §8.4); the TS twin of perk.plan.PlanRef. */
+export interface PlanRef {
+  provider: string;
+  pr_id: string;
+  url: string;
+  labels: string[];
+  objective_id: string | null;
+  // The pinned target branch; Python-owned, parity-only on the warm plane.
+  base?: string | null;
+}
+
+export function planRefPath(cwd: string): string {
+  return join(workflowDir(cwd), "plan-ref.json");
+}
+
+export function readPlanRef(cwd: string): PlanRef | null {
+  const path = planRefPath(cwd);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, "utf8")) as PlanRef;
+}
+
+export function writePlanRef(cwd: string, ref: PlanRef): void {
+  mkdirSync(workflowDir(cwd), { recursive: true });
+  writeFileSync(planRefPath(cwd), `${JSON.stringify(ref, null, 2)}\n`, "utf8");
+}
+
+// --- plan body cache (`cache.plan`) ------------------------------------------------------
+
+/**
+ * The materialized plan-body cache (`cache.plan`, contracts §8.1). Written by the Python cold door
+ * (`perk implement` → `launch.materialize_plan_body`) when it positions the worktree; read here so
+ * in-session checkpoints seed from its `## Steps` list (inert when absent).
+ */
+export function planBodyPath(cwd: string): string {
+  return join(workflowDir(cwd), "plan.md");
+}
+
+export function readPlanBody(cwd: string): string | null {
+  const path = planBodyPath(cwd);
+  if (!existsSync(path)) return null;
+  return readFileSync(path, "utf8");
+}
+
+// --- markers (existence-only) ------------------------------------------------------------
+
+/** The land->learn semaphore; the TS twin of perk.state.cache.PENDING_LEARN. */
+export const PENDING_LEARN = "pending-learn";
+
+export function markerPath(cwd: string, name: string): string {
+  return join(workflowDir(cwd), "markers", name);
+}
+
+export function setMarker(cwd: string, name: string): void {
+  mkdirSync(join(workflowDir(cwd), "markers"), { recursive: true });
+  writeFileSync(markerPath(cwd, name), "", "utf8");
+}
+
+export function hasMarker(cwd: string, name: string): boolean {
+  return existsSync(markerPath(cwd, name));
+}
+
+export function clearMarker(cwd: string, name: string): void {
+  rmSync(markerPath(cwd, name), { force: true });
+}