@mgiles/perk 1.0.1 → 2.0.0

package/extension/doors/selfcheck.ts

@@ -13,12 +13,26 @@
 // the converged content actually *reached* the prompt. That closes perk's two-plane blind spot —
 // doctor checks disk, selfcheck checks the prompt.
 //
+// The same report additionally carries a per-surface payload CENSUS — derived counts/chars for
+// `appendSystemPrompt`, `contextFiles`, the skills catalog section, the active tool definitions,
+// and perk-injected `custom_message` branch context. Report-only: the census never affects the
+// ok/level verdict (contracts.md §8.7).
+//
 // Sensitivity: `getSystemPromptOptions()` exposes the full system-prompt construction inputs. This
-// module logs ONLY derived booleans/counts (never the raw prompt text). See docs/learned/pi/.
+// module logs ONLY derived output — identifiers (paths, skill/tool names, source strings,
+// customTypes) and counts/chars; never prompt/content text. See docs/learned/pi/.
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  type ExtensionAPI,
+  formatSkillsForPrompt,
+  type Skill,
+  type ToolInfo,
+} from "@earendil-works/pi-coding-agent";
+import { BINDING_HEADER } from "../substrate/bindingDelivery.ts";
+import { registerPerkCommand } from "../substrate/command.ts";
+import { branchOf } from "../substrate/workflowState.ts";
 import { report as reportTo } from "../surfaces/report.ts";
 
 /** Project-scoped ambient routing index, relative to the repo root. */
@@ -27,10 +41,15 @@ export const AMBIENT_INDEX_REL_PATH = join(".pi", "APPEND_SYSTEM.md");
 /** The managed `AGENTS.md` block marker (cross-plane: written by `perk init`, read here). */
 export const MANAGED_AGENTS_MARKER = "<!-- BEGIN perk managed -->";
 
-/** The narrow slice of `BuildSystemPromptOptions` the verifier probes. */
+/** The slice of `BuildSystemPromptOptions` the verifier + census probe (all optional). */
 export interface SystemPromptProbeInput {
+  customPrompt?: string;
   appendSystemPrompt?: string;
   contextFiles?: { path: string; content: string }[];
+  skills?: Skill[];
+  selectedTools?: string[];
+  toolSnippets?: Record<string, string>;
+  promptGuidelines?: string[];
 }
 
 /** Read the on-disk ambient routing index (`.pi/APPEND_SYSTEM.md`), or `null` if absent. */
@@ -129,6 +148,214 @@ export function buildSelfcheckReport(input: {
   return { version, sharedOk, ambient, agents, ok, summary, level: ok ? "info" : "warning" };
 }
 
+// ---------------------------------------------------------------------------
+// The per-surface payload census (contracts.md §8.7). Pure builders over the same
+// `getSystemPromptOptions()` slice plus the tool registry and the session branch. All counts are
+// `string.length` char counts (rendered with a `c` suffix). Identifiers (paths, skill/tool names,
+// source strings, customTypes) and counts/chars only — never prompt/content text.
+// ---------------------------------------------------------------------------
+
+/** Derived per-surface counts for the system-prompt construction inputs. */
+export interface PromptCensus {
+  /** `customPrompt` length; `null` = pi's built-in default is in use (not measurable here). */
+  basePromptChars: number | null;
+  appendChars: number;
+  contextFiles: { count: number; totalChars: number; files: { path: string; chars: number }[] };
+  /** `hidden` = skills with `disableModelInvocation`; `promptSectionChars` is the exact
+   *  system-prompt contribution (pi's own exported `formatSkillsForPrompt`). */
+  skills: { visible: number; hidden: number; promptSectionChars: number };
+  toolGuidelineChars: number;
+  toolSnippetChars: number;
+}
+
+/** Census the system-prompt surfaces from the probed options (undefined → zeros). */
+export function promptCensus(options: SystemPromptProbeInput | undefined): PromptCensus {
+  const files = (options?.contextFiles ?? []).map((f) => ({
+    path: f.path,
+    chars: f.content.length,
+  }));
+  const skills = options?.skills ?? [];
+  const hidden = skills.filter((s) => s.disableModelInvocation).length;
+  let guidelineChars = 0;
+  for (const g of options?.promptGuidelines ?? []) guidelineChars += g.length;
+  let snippetChars = 0;
+  for (const s of Object.values(options?.toolSnippets ?? {})) snippetChars += s.length;
+  return {
+    basePromptChars: options?.customPrompt === undefined ? null : options.customPrompt.length,
+    appendChars: (options?.appendSystemPrompt ?? "").length,
+    contextFiles: {
+      count: files.length,
+      totalChars: files.reduce((sum, f) => sum + f.chars, 0),
+      files,
+    },
+    skills: {
+      visible: skills.length - hidden,
+      hidden,
+      // formatSkillsForPrompt filters disableModelInvocation skills itself, so passing the full
+      // list measures exactly the visible skills' prompt-section contribution.
+      promptSectionChars: formatSkillsForPrompt(skills).length,
+    },
+    toolGuidelineChars: guidelineChars,
+    toolSnippetChars: snippetChars,
+  };
+}
+
+/** Derived counts for the tool-definitions payload (active tools = the per-request payload). */
+export interface ToolsCensus {
+  active: number;
+  all: number;
+  /** Sum of `JSON.stringify({name, description, parameters})` over ACTIVE tools. */
+  schemaChars: number;
+  /** Active tools grouped by `sourceInfo.source`, sorted by source string (stable output). */
+  bySource: { source: string; active: number; schemaChars: number }[];
+}
+
+/** Census the tool registry: active vs registered counts + per-source schema chars. */
+export function toolsCensus(allTools: ToolInfo[], activeNames: string[]): ToolsCensus {
+  const activeSet = new Set(activeNames);
+  const bySource = new Map<string, { active: number; schemaChars: number }>();
+  let schemaChars = 0;
+  for (const tool of allTools) {
+    if (!activeSet.has(tool.name)) continue;
+    const chars = JSON.stringify({
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters,
+    }).length;
+    schemaChars += chars;
+    const row = bySource.get(tool.sourceInfo.source) ?? { active: 0, schemaChars: 0 };
+    row.active += 1;
+    row.schemaChars += chars;
+    bySource.set(tool.sourceInfo.source, row);
+  }
+  return {
+    active: activeNames.length,
+    all: allTools.length,
+    schemaChars,
+    bySource: [...bySource.entries()]
+      .map(([source, row]) => ({ source, ...row }))
+      .sort((a, b) => (a.source < b.source ? -1 : a.source > b.source ? 1 : 0)),
+  };
+}
+
+/**
+ * The structural slice of a session entry the branch census reads. Injected contexts persist as
+ * `type: "custom_message"` entries carrying `content` — distinct from `type: "custom"` state
+ * entries (workflow state, checkpoints), which the census must NOT count as context.
+ */
+export interface CensusBranchEntry {
+  type: string;
+  customType?: string;
+  content?: unknown;
+}
+
+/** Derived counts for perk-injected branch context (perk's customTypes share the `perk:` prefix). */
+export interface BranchContextCensus {
+  entries: number;
+  /** `custom_message` entries whose customType starts with `perk:`, sorted by customType. */
+  perkContexts: { customType: string; copies: number; totalChars: number }[];
+  /** `custom_message` entries without the `perk:` prefix (borrowed packages). */
+  otherCustomMessages: { copies: number; totalChars: number };
+  /** Entries (any type) whose JSON form carries `BINDING_HEADER` — the cold↔warm dedup marker. */
+  bindingHeaderCopies: number;
+}
+
+/** Char count of a `custom_message` entry's content — string, `text`-part array, or JSON size. */
+function contentChars(content: unknown): number {
+  if (content === undefined) return 0;
+  if (typeof content === "string") return content.length;
+  if (Array.isArray(content)) {
+    let sum = 0;
+    for (const part of content) {
+      if (typeof part !== "object" || part === null || Array.isArray(part)) continue;
+      const text = (part as { text?: unknown }).text;
+      if (typeof text === "string") sum += text.length;
+    }
+    return sum;
+  }
+  return JSON.stringify(content).length;
+}
+
+/** Census the session branch's injected context (counts/chars only — never message content). */
+export function branchContextCensus(entries: readonly CensusBranchEntry[]): BranchContextCensus {
+  const perk = new Map<string, { copies: number; totalChars: number }>();
+  const other = { copies: 0, totalChars: 0 };
+  let bindingHeaderCopies = 0;
+  for (const entry of entries) {
+    if (JSON.stringify(entry).includes(BINDING_HEADER)) bindingHeaderCopies += 1;
+    if (entry.type !== "custom_message") continue;
+    const chars = contentChars(entry.content);
+    const customType = entry.customType ?? "";
+    if (customType.startsWith("perk:")) {
+      const row = perk.get(customType) ?? { copies: 0, totalChars: 0 };
+      row.copies += 1;
+      row.totalChars += chars;
+      perk.set(customType, row);
+    } else {
+      other.copies += 1;
+      other.totalChars += chars;
+    }
+  }
+  return {
+    entries: entries.length,
+    perkContexts: [...perk.entries()]
+      .map(([customType, row]) => ({ customType, ...row }))
+      .sort((a, b) => (a.customType < b.customType ? -1 : a.customType > b.customType ? 1 : 0)),
+    otherCustomMessages: other,
+    bindingHeaderCopies,
+  };
+}
+
+/**
+ * Render the census as a fixed multi-line block. The line grammar (the `census:` /
+ * `append-system-prompt:` / `context-files:` / `skills:` / `tools:` / `per source:` / `branch:` /
+ * `perk contexts:` keys) is stable — the closing audit diffs against these exact keys.
+ */
+export function renderCensus(
+  prompt: PromptCensus,
+  tools: ToolsCensus,
+  branch: BranchContextCensus,
+): string {
+  const lines: string[] = ["census:"];
+  lines.push(
+    prompt.basePromptChars === null
+      ? "  base-prompt: pi-default (not measured)"
+      : `  base-prompt: custom ${prompt.basePromptChars}c`,
+  );
+  lines.push(`  append-system-prompt: ${prompt.appendChars}c`);
+  const fileList = prompt.contextFiles.files.map((f) => `${f.path}=${f.chars}c`).join(", ");
+  lines.push(
+    `  context-files: ${prompt.contextFiles.count} file(s), ${prompt.contextFiles.totalChars}c` +
+      (fileList.length > 0 ? ` — ${fileList}` : ""),
+  );
+  lines.push(
+    `  skills: ${prompt.skills.visible} visible + ${prompt.skills.hidden} hidden; ` +
+      `prompt-section=${prompt.skills.promptSectionChars}c`,
+  );
+  lines.push(
+    `  tools: ${tools.active} active / ${tools.all} registered; schemas=${tools.schemaChars}c; ` +
+      `guidelines=${prompt.toolGuidelineChars}c; snippets=${prompt.toolSnippetChars}c`,
+  );
+  if (tools.bySource.length > 0) {
+    const rows = tools.bySource
+      .map((r) => `${r.source}=${r.active} (${r.schemaChars}c)`)
+      .join("; ");
+    lines.push(`    per source: ${rows}`);
+  }
+  lines.push(
+    `  branch: ${branch.entries} entries; binding-header-copies=${branch.bindingHeaderCopies}`,
+  );
+  const perkRows = branch.perkContexts.map(
+    (r) => `${r.customType} ×${r.copies} (${r.totalChars}c)`,
+  );
+  const perkSegment = perkRows.length > 0 ? perkRows.join("; ") : "none";
+  lines.push(
+    `    perk contexts: ${perkSegment}; other custom_message ` +
+      `×${branch.otherCustomMessages.copies} (${branch.otherCustomMessages.totalChars}c)`,
+  );
+  return lines.join("\n");
+}
+
 /**
  * Register `/perk-selfcheck`: the session-wiring verifier. Runs on a command context (the only
  * context exposing `getSystemPromptOptions()`), so it sees the live splice — not just disk.
@@ -137,7 +364,7 @@ export function registerSelfcheck(
   pi: ExtensionAPI,
   opts: { version: string; sharedOk: boolean },
 ): void {
-  pi.registerCommand("perk-selfcheck", {
+  registerPerkCommand(pi, "perk-selfcheck", {
     description:
       "Verify perk's session wiring: the ambient index + managed AGENTS block reached the prompt.",
     handler: async (_args, ctx) => {
@@ -148,8 +375,15 @@ export function registerSelfcheck(
         onDiskIndex: readAmbientIndex(ctx.cwd),
         options,
       });
-      // Headless-safe: report() surfaces the derived booleans/counts (never raw prompt content).
-      reportTo(ctx, "selfcheck", report.level, report.summary);
+      // The census is report-only: it rides the same report but never affects ok/level. A command
+      // doesn't fire `before_agent_start`, so the branch reads as of the last completed turn.
+      const census = renderCensus(
+        promptCensus(options),
+        toolsCensus(pi.getAllTools(), pi.getActiveTools()),
+        branchContextCensus(branchOf(ctx)),
+      );
+      // Headless-safe: report() surfaces the derived counts/identifiers (never raw prompt content).
+      reportTo(ctx, "selfcheck", report.level, `${report.summary}\n${census}`);
     },
   });
 }

package/extension/doors/submit.ts

@@ -21,8 +21,11 @@ import {
   runColdDoor,
   stringField,
 } from "../substrate/coldDoor.ts";
+import { registerPerkCommand } from "../substrate/command.ts";
 import { loadPerkConfig } from "../substrate/config.ts";
+import { render } from "../substrate/prompts.ts";
 import { failFor, type OkDetails, ok, type Result } from "../substrate/result.ts";
+import { captureSessionPointer } from "../substrate/sessionPointers.ts";
 import { appendWorkflowState, branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
 import { report } from "../surfaces/report.ts";
 
@@ -104,12 +107,38 @@ function isUnmergeable(details: SubmitDetails): details is OkDetails<SubmitOk> {
 export async function submitPr(pi: ExtensionAPI, ctx: ExtensionContext): Promise<SubmitResult> {
   const fail = failFor(ctx, "submit");
 
-  const r = await runColdDoor<SubmitOk>(pi, ctx, ["pr", "submit", "--json"], {
+  // Stamp this implement run id into the plan-header `impl_run_ids` linkage (contracts.md
+  // §8.35) so a later/other session can resolve the implement session pointers cross-run.
+  // Mirrors planSave's `--run-id` thread; covers the interactive /submit AND the headless worker
+  // drive (both flow through this warm door). Absent run_id ⇒ omit (bare-stamp untouched).
+  const runId = rebuildWorkflowState(branchOf(ctx)).run_id ?? "";
+  const args = ["pr", "submit", "--json"];
+  if (runId) args.push("--run-id", runId);
+  const r = await runColdDoor<SubmitOk>(pi, ctx, args, {
     label: "perk pr submit",
     decode: decodeSubmit,
   });
   if (!r.ok) return fail(r.message, r.errorType);
 
+  // Capture `implementation/main` at the moment the run id enters `impl_run_ids` (contracts.md
+  // §8.35): any run id stamped into the linkage gets its pointer captured in the same gesture.
+  // This covers address/warm sessions that submit — which the stage-gated `session_start` capture
+  // never sees — so a submitted run resolves `found` instead of `missing`. For the implement
+  // session's own /submit it is an idempotent same-session refresh; `preserveForeign` guarantees
+  // it can never clobber a different session's pointer. Best-effort + non-fatal like every
+  // capture site (a successful submit must stand).
+  if (runId) {
+    captureSessionPointer({
+      cwd: ctx.cwd,
+      runId,
+      klass: "implementation",
+      site: "main",
+      // Optional-chained: best-effort, and some side-session fakes have no getSessionFile.
+      sessionFile: ctx.sessionManager.getSessionFile?.(),
+      preserveForeign: true,
+    });
+  }
+
   const verb = r.data.pr.existed ? "Found existing" : "Opened draft";
   const conflicted = r.data.mergeable === false && (r.data.conflicts?.length ?? 0) > 0;
   // Reset the counter on every clean (or undetermined) submit — idempotent; keeps a later
@@ -147,23 +176,12 @@ export function conflictResolutionGuidance(
   cap: number,
   model?: string,
 ): string {
-  const modelClause = model
-    ? `, and pass \`model: "${model}"\` on that call (the configured [subagents] conflict-resolver model)`
-    : " (no model override — the agent's default model is used)";
-  return [
-    `perk /submit — your PR has merge conflicts against \`${base}\`; resolve them before the work ` +
-      "is submitted for review. This is attempt " +
-      `${attempt} of ${cap}.`,
-    `1. Spawn the \`perk.conflict-resolver\` agent via the \`subagent\` tool with \`context: "fresh"\`${modelClause}. ` +
-      "A fresh context keeps this implementation session's history from biasing the resolution.",
-    `2. Tell it: rebase the PR branch onto \`${base}\` and **carefully** resolve all merge ` +
-      "conflicts so the resulting diff is **clean** (no stray markers, no unrelated churn) and " +
-      "**correct** (preserve the change's intent on both sides). The child reads its own plan + PR " +
-      "diff context first (it runs `perk pr review-context`) so it resolves with the change's " +
-      "intent in hand, verifies, and force-pushes — the raw diff never enters this session.",
-    "3. After the child reports success, call `/submit` again to re-verify mergeability. Do NOT " +
-      "edit or resolve conflicts yourself here — the child owns the rebase/resolve/push.",
-  ].join("\n");
+  return render("stages/conflict-resolution.md", {
+    base,
+    attempt: String(attempt),
+    cap: String(cap),
+    model: model ?? "",
+  });
 }
 
 /**
@@ -239,7 +257,7 @@ export function registerSubmit(pi: ExtensionAPI): void {
     },
   });
 
-  pi.registerCommand("submit", {
+  registerPerkCommand(pi, "submit", {
     description: "Push the branch and open a draft PR for the active plan (implement → submit).",
     handler: async (_args, ctx) => {
       const result = await submitPr(pi, ctx);