@whamp/pi-pstack 0.7.0

package/extensions/pstack/pstack-roles.ts

@@ -0,0 +1,252 @@
+/** Cardinality of a pstack model role. single, repeat, fanout, or pick-one. */
+export const ROLE_CARDINALITIES = {
+	SINGLE: "single",
+	REPEAT: "repeat",
+	FANOUT: "fanout",
+	PICK_ONE: "pick-one",
+} as const;
+
+/** Cardinality controlling whether a role stores one selector or a model list. */
+export type PstackRoleCardinality = (typeof ROLE_CARDINALITIES)[keyof typeof ROLE_CARDINALITIES];
+
+/** Setup section containing a related group of pstack roles. */
+export type PstackRoleGroup =
+	| "Implementation"
+	| "Judgment and prose"
+	| "How"
+	| "Why"
+	| "Reflect"
+	| "Arena"
+	| "Swarm"
+	| "Architect"
+	| "Interrogate";
+
+/** One pstack role's cardinality, setup group, purpose, and v1 legacy name. */
+export interface PstackRoleDefinition {
+	readonly cardinality: PstackRoleCardinality;
+	readonly group: PstackRoleGroup;
+	readonly purpose: string;
+	readonly legacyName: string;
+}
+
+/** Registry of pstack model roles. Single source for role names and cardinality. */
+export const PSTACK_ROLES = {
+	"feature implementation": {
+		cardinality: "single",
+		group: "Implementation",
+		purpose: "Implement the scoped feature after design.",
+		legacyName: "feature, refactoring",
+	},
+	"refactoring implementation": {
+		cardinality: "single",
+		group: "Implementation",
+		purpose: "Make behavior-preserving structural edits.",
+		legacyName: "feature, refactoring",
+	},
+	"bug-fix": {
+		cardinality: "single",
+		group: "Implementation",
+		purpose: "Implement the diagnosed fix.",
+		legacyName: "bug-fix",
+	},
+	"perf-issue": {
+		cardinality: "single",
+		group: "Implementation",
+		purpose: "Implement a measured performance change.",
+		legacyName: "perf-issue",
+	},
+	hillclimb: {
+		cardinality: "repeat",
+		group: "Implementation",
+		purpose: "Implement each bounded metric experiment.",
+		legacyName: "hillclimb",
+	},
+	judgment: {
+		cardinality: "single",
+		group: "Judgment and prose",
+		purpose: "Give a general decision or second opinion.",
+		legacyName: "judgment and prose",
+	},
+	prose: {
+		cardinality: "single",
+		group: "Judgment and prose",
+		purpose: "Draft or revise user-facing writing.",
+		legacyName: "judgment and prose",
+	},
+	"hardest tasks": {
+		cardinality: "single",
+		group: "Judgment and prose",
+		purpose: "Handle an explicitly escalated difficult task.",
+		legacyName: "hardest tasks",
+	},
+	"how explorers": {
+		cardinality: "repeat",
+		group: "How",
+		purpose: "Investigate each architecture slice.",
+		legacyName: "how explorer",
+	},
+	"how explainer": {
+		cardinality: "single",
+		group: "How",
+		purpose: "Investigate and explain a simple question.",
+		legacyName: "how explainer",
+	},
+	"how synthesizer": {
+		cardinality: "single",
+		group: "How",
+		purpose: "Combine completed architecture findings.",
+		legacyName: "how explainer",
+	},
+	"why investigators": {
+		cardinality: "repeat",
+		group: "Why",
+		purpose: "Investigate each evidence source.",
+		legacyName: "why investigators",
+	},
+	"why synthesizer": {
+		cardinality: "single",
+		group: "Why",
+		purpose: "Reconcile historical evidence and uncertainty.",
+		legacyName: "why synthesizer",
+	},
+	"reflect judgment reviewer": {
+		cardinality: "single",
+		group: "Reflect",
+		purpose: "Review decisions made in the session.",
+		legacyName: "reflect judgment, divergent, synthesizer",
+	},
+	"reflect tooling reviewer": {
+		cardinality: "single",
+		group: "Reflect",
+		purpose: "Review tool choice and verification.",
+		legacyName: "reflect tooling",
+	},
+	"reflect divergent reviewer": {
+		cardinality: "single",
+		group: "Reflect",
+		purpose: "Challenge the session's shared assumptions.",
+		legacyName: "reflect judgment, divergent, synthesizer",
+	},
+	"reflect synthesizer": {
+		cardinality: "single",
+		group: "Reflect",
+		purpose: "Reconcile the three reflection reports.",
+		legacyName: "reflect judgment, divergent, synthesizer",
+	},
+	"arena runners": {
+		cardinality: "fanout",
+		group: "Arena",
+		purpose: "Produce one complete candidate per list entry.",
+		legacyName: "arena runners",
+	},
+	"arena judge pool": {
+		cardinality: "pick-one",
+		group: "Arena",
+		purpose: "Choose one model to judge all completed candidates.",
+		legacyName: "arena cross-judge pool",
+	},
+	"swarm workers": {
+		cardinality: "repeat",
+		group: "Swarm",
+		purpose: "Use one model across N bounded worker tasks.",
+		legacyName: "swarm workers",
+	},
+	"architect runners": {
+		cardinality: "fanout",
+		group: "Architect",
+		purpose: "Produce at least two distinct design candidates.",
+		legacyName: "architect runners",
+	},
+	"interrogate reviewers": {
+		cardinality: "fanout",
+		group: "Interrogate",
+		purpose: "Review the same artifact once per list entry.",
+		legacyName: "interrogate reviewers",
+	},
+} as const satisfies Record<string, PstackRoleDefinition>;
+
+/** Exact key for one atomic model-selection job. */
+export type PstackRoleName = keyof typeof PSTACK_ROLES;
+
+declare const PSTACK_MODEL_SELECTOR_BRAND: unique symbol;
+
+/** Branded model selector. Constructed only after selector safety checks. */
+export type PstackModelSelector = string & {
+	readonly [PSTACK_MODEL_SELECTOR_BRAND]: true;
+};
+
+/** Canonical explicit inheritance value. auto normalizes to this. */
+export const PSTACK_INHERIT_PARENT = "inherit-parent" as const;
+
+type ModelList = readonly [PstackModelSelector, ...PstackModelSelector[]];
+
+type ExplicitRoleSelection<R extends PstackRoleName> =
+	(typeof PSTACK_ROLES)[R]["cardinality"] extends "single" | "repeat"
+		? PstackModelSelector
+		: ModelList;
+
+/** Valid normalized selection for a role's declared cardinality. */
+export type PstackRoleSelection<R extends PstackRoleName> =
+	| typeof PSTACK_INHERIT_PARENT
+	| ExplicitRoleSelection<R>;
+
+/** Normalized v2 role map. Omitted roles inherit the parent model. */
+export type PstackRoleSelections = {
+	readonly [R in PstackRoleName]?: PstackRoleSelection<R>;
+};
+
+/** Normalized v2 pstack role configuration. */
+export interface PstackRoleConfig {
+	readonly version: 2;
+	readonly roles: PstackRoleSelections;
+	readonly skillsEnabled: boolean;
+}
+
+/** Retired v1 role with no replacement. */
+export const RETIRED_PSTACK_ROLE_NAME = "how critics";
+
+/** True when value is a v2 pstack role name. */
+export function isPstackRoleName(value: string): value is PstackRoleName {
+	return Object.hasOwn(PSTACK_ROLES, value);
+}
+
+/** v2 pstack role names in registry order. */
+export const PSTACK_ROLE_NAMES: readonly PstackRoleName[] =
+	Object.keys(PSTACK_ROLES).filter(isPstackRoleName);
+
+/** Markdown role reference generated from the registry. */
+export function formatPstackRoleReferenceMarkdown(): string {
+	const lines = [
+		"# Pstack model roles",
+		"",
+		"Generated from `extensions/pstack/pstack-roles.ts`. Edit the registry, not this file.",
+		"",
+		"Cardinality:",
+		"",
+		"- `single`: one job, one selector.",
+		"- `repeat`: one selector, reused for N children the workflow chooses.",
+		"- `fanout`: one child per list entry.",
+		"- `pick-one`: a candidate list, then one child.",
+		"",
+		"| Role | Cardinality | Purpose |",
+		"| --- | --- | --- |",
+	];
+	for (const name of PSTACK_ROLE_NAMES) {
+		const definition = PSTACK_ROLES[name];
+		lines.push(`| \`${name}\` | \`${definition.cardinality}\` | ${definition.purpose} |`);
+	}
+	lines.push("");
+	return lines.join("\n");
+}
+
+/** v1 role name to v2 targets, derived from registry legacyName fields. */
+export const PSTACK_LEGACY_ROLE_TARGETS: ReadonlyMap<string, readonly PstackRoleName[]> = (() => {
+	const map = new Map<string, PstackRoleName[]>();
+	for (const name of PSTACK_ROLE_NAMES) {
+		const legacyName = PSTACK_ROLES[name].legacyName;
+		const group = map.get(legacyName);
+		if (group) group.push(name);
+		else map.set(legacyName, [name]);
+	}
+	return map;
+})();

package/extensions/pstack/pstack-setup-plan.ts

@@ -0,0 +1,223 @@
+import { isSafeModelSelector } from "./config.ts";
+import {
+	PSTACK_INHERIT_PARENT,
+	PSTACK_ROLE_NAMES,
+	PSTACK_ROLES,
+	type PstackRoleCardinality,
+	type PstackModelSelector,
+	type PstackRoleConfig,
+	type PstackRoleGroup,
+	type PstackRoleName,
+	type PstackRoleSelections,
+} from "./pstack-roles.ts";
+
+/** Session model used to build setup selectors. thinkingLevel becomes a trailing suffix. */
+export interface PstackScopedModelEntry {
+	readonly model: {
+		readonly provider: string;
+		readonly id: string;
+	};
+	readonly thinkingLevel?: string;
+}
+
+/** One registry-driven setup step. kind is scalar for single/repeat and list for fanout/pick-one. */
+export interface PstackSetupRoleStep {
+	readonly role: PstackRoleName;
+	readonly cardinality: PstackRoleCardinality;
+	readonly purpose: string;
+	readonly group: PstackRoleGroup;
+	readonly kind: "scalar" | "list";
+	readonly current?: PstackModelSelector | readonly PstackModelSelector[];
+}
+
+type PstackSetupChoice = typeof PSTACK_INHERIT_PARENT | PstackModelSelector;
+type MutableSetupRoles = Record<string, PstackModelSelector | readonly PstackModelSelector[]>;
+
+/** Ordered setup plan for every pstack role. */
+export interface PstackSetupPlan {
+	readonly steps: readonly PstackSetupRoleStep[];
+	readonly choices: readonly PstackSetupChoice[];
+}
+
+function checkedModelSelector(value: string): PstackModelSelector | undefined {
+	if (value === PSTACK_INHERIT_PARENT || value === "auto" || !isSafeModelSelector(value)) {
+		return undefined;
+	}
+	// SAFETY: PstackModelSelector is branded only after the shared selector validator accepts it.
+	return value as PstackModelSelector;
+}
+
+function uniqueSafeSelectors(selectors: readonly string[]): PstackModelSelector[] {
+	const out: PstackModelSelector[] = [];
+	const seen = new Set<string>();
+	for (const value of selectors) {
+		const selector = checkedModelSelector(value);
+		if (selector === undefined || seen.has(selector)) continue;
+		seen.add(selector);
+		out.push(selector);
+	}
+	return out;
+}
+
+function scopedSelector(entry: PstackScopedModelEntry): string {
+	const base = `${entry.model.provider}/${entry.model.id}`;
+	return entry.thinkingLevel === undefined || entry.thinkingLevel === ""
+		? base
+		: `${base}:${entry.thinkingLevel}`;
+}
+
+/** Build setup selectors from scoped models, preserving thinkingLevel suffixes. */
+export function pstackModelSelectorsFromSession(input: {
+	scopedModels?: readonly PstackScopedModelEntry[];
+	availableModels?: readonly { readonly provider: string; readonly id: string }[];
+}): PstackModelSelector[] {
+	if (input.scopedModels !== undefined && input.scopedModels.length > 0) {
+		return uniqueSafeSelectors(input.scopedModels.map(scopedSelector));
+	}
+	return uniqueSafeSelectors(
+		(input.availableModels ?? []).map((model) => `${model.provider}/${model.id}`),
+	);
+}
+
+function pstackSetupPickKind(cardinality: PstackRoleCardinality): "scalar" | "list" {
+	return cardinality === "fanout" || cardinality === "pick-one" ? "list" : "scalar";
+}
+
+function configuredSelectors(config: PstackRoleConfig): PstackModelSelector[] {
+	const values: string[] = [];
+	for (const name of PSTACK_ROLE_NAMES) {
+		const value = config.roles[name];
+		if (typeof value === "string") values.push(value);
+		else if (Array.isArray(value)) values.push(...value);
+	}
+	return uniqueSafeSelectors(values);
+}
+
+/** Build a registry-driven setup plan. Includes configured selectors even when unavailable. */
+export function buildPstackSetupPlan(input: {
+	config: PstackRoleConfig;
+	sessionSelectors: readonly PstackModelSelector[];
+}): PstackSetupPlan {
+	const extras = configuredSelectors(input.config).filter(
+		(selector) => !input.sessionSelectors.includes(selector),
+	);
+	const choices = [
+		PSTACK_INHERIT_PARENT,
+		...uniqueSafeSelectors(input.sessionSelectors),
+		...extras,
+	];
+	const steps: PstackSetupRoleStep[] = PSTACK_ROLE_NAMES.map((role) => {
+		const definition = PSTACK_ROLES[role];
+		const current = input.config.roles[role];
+		return {
+			role,
+			cardinality: definition.cardinality,
+			purpose: definition.purpose,
+			group: definition.group,
+			kind: pstackSetupPickKind(definition.cardinality),
+			...(current === undefined || current === PSTACK_INHERIT_PARENT ? {} : { current }),
+		};
+	});
+	return { steps, choices };
+}
+
+function stripCurrentMark(choice: string): string {
+	return choice.endsWith(" (current)") ? choice.slice(0, -" (current)".length) : choice;
+}
+
+function labeledChoices(
+	choices: readonly PstackSetupChoice[],
+	current: PstackModelSelector | readonly PstackModelSelector[] | undefined,
+): string[] {
+	const currents = new Set(Array.isArray(current) ? current : current ? [current] : []);
+	return choices.map((choice) => (currents.has(choice) ? `${choice} (current)` : choice));
+}
+
+function rolePromptTitle(step: PstackSetupRoleStep): string {
+	return `${step.group}. ${step.role} [${step.cardinality}]. ${step.purpose}`;
+}
+
+function omitRole(roles: MutableSetupRoles, role: PstackRoleName): MutableSetupRoles {
+	if (!(role in roles)) return roles;
+	const next = { ...roles };
+	delete next[role];
+	return next;
+}
+
+function assignRole(
+	roles: MutableSetupRoles,
+	role: PstackRoleName,
+	value: PstackModelSelector | readonly PstackModelSelector[],
+): MutableSetupRoles {
+	return { ...roles, [role]: value };
+}
+
+function asRoleSelections(roles: MutableSetupRoles): PstackRoleSelections {
+	// SAFETY: keys are registry role names and values passed selector safety checks.
+	return roles as PstackRoleSelections;
+}
+
+function mutableSetupRoles(config: PstackRoleConfig): MutableSetupRoles {
+	let roles: MutableSetupRoles = {};
+	for (const role of PSTACK_ROLE_NAMES) {
+		const value = config.roles[role];
+		if (value === undefined || value === PSTACK_INHERIT_PARENT) continue;
+		roles = assignRole(roles, role, value);
+	}
+	return roles;
+}
+
+/** Collect setup choices into a new config. Cancel returns undefined and does not reuse the loaded object. */
+export async function collectPstackSetupSelections(input: {
+	config: PstackRoleConfig;
+	plan: PstackSetupPlan;
+	select: (title: string, options: string[]) => Promise<string | undefined>;
+}): Promise<PstackRoleConfig | undefined> {
+	let roles = mutableSetupRoles(input.config);
+	for (const step of input.plan.steps) {
+		if (step.kind === "scalar") {
+			const choice = await input.select(
+				rolePromptTitle(step),
+				labeledChoices(input.plan.choices, step.current),
+			);
+			if (choice === undefined) return undefined;
+			const value = checkedModelSelector(stripCurrentMark(choice));
+			roles =
+				value === undefined ? omitRole(roles, step.role) : assignRole(roles, step.role, value);
+			continue;
+		}
+
+		const first = await input.select(
+			rolePromptTitle(step),
+			labeledChoices(input.plan.choices, step.current),
+		);
+		if (first === undefined) return undefined;
+		const selected = checkedModelSelector(stripCurrentMark(first));
+		if (selected === undefined) {
+			roles = omitRole(roles, step.role);
+			continue;
+		}
+
+		const picked: PstackModelSelector[] = [selected];
+		const addChoices = [
+			"done",
+			...input.plan.choices.filter((choice) => choice !== PSTACK_INHERIT_PARENT),
+		];
+		while (true) {
+			const next = await input.select(
+				`Add another model for ${step.role}? [${step.cardinality}]`,
+				addChoices,
+			);
+			if (next === undefined) return undefined;
+			if (next === "done") break;
+			const value = checkedModelSelector(stripCurrentMark(next));
+			if (value !== undefined) picked.push(value);
+		}
+		roles = assignRole(roles, step.role, picked);
+	}
+	return {
+		version: 2,
+		roles: asRoleSelections(roles),
+		skillsEnabled: input.config.skillsEnabled,
+	};
+}

package/extensions/pstack/skill-strip.ts

@@ -0,0 +1,62 @@
+export interface StripResult {
+	prompt: string;
+	removed: number;
+}
+
+const OPEN_TAG = "\n<available_skills>";
+const CLOSE_TAG = "</available_skills>";
+const ENTRY_DELIMITER = "  <skill>";
+const ENTRY_SPLIT = /(?=  <skill>)/;
+const LOCATION_PATTERN = /<location>([\s\S]*?)<\/location>/;
+const HEADER_MARKER = "\n\nThe following skills provide specialized instructions";
+
+function decodeXmlEntities(value: string): string {
+	return value
+		.replaceAll("&lt;", "<")
+		.replaceAll("&gt;", ">")
+		.replaceAll("&quot;", '"')
+		.replaceAll("&apos;", "'")
+		.replaceAll("&amp;", "&");
+}
+
+export function stripSkillsByLocationPrefix(systemPrompt: string, locationPrefix: string): StripResult {
+	const prefix = locationPrefix.trim().replace(/\/$/, "");
+	if (!prefix) return { prompt: systemPrompt, removed: 0 };
+
+	const openStart = systemPrompt.indexOf(OPEN_TAG);
+	if (openStart === -1) return { prompt: systemPrompt, removed: 0 };
+	const contentStart = openStart + OPEN_TAG.length;
+	const closeStart = systemPrompt.indexOf(CLOSE_TAG, contentStart);
+	if (closeStart === -1) return { prompt: systemPrompt, removed: 0 };
+
+	const chunks = systemPrompt.slice(contentStart, closeStart).split(ENTRY_SPLIT);
+	const kept: string[] = [];
+	let removed = 0;
+	for (const chunk of chunks) {
+		if (!chunk.startsWith(ENTRY_DELIMITER)) {
+			kept.push(chunk);
+			continue;
+		}
+		const rawLocation = chunk.match(LOCATION_PATTERN)?.[1] ?? "";
+		if (decodeXmlEntities(rawLocation).startsWith(`${prefix}/`)) {
+			removed++;
+			continue;
+		}
+		kept.push(chunk);
+	}
+	if (removed === 0) return { prompt: systemPrompt, removed: 0 };
+
+	const anyKeptEntry = kept.some((chunk) => chunk.startsWith(ENTRY_DELIMITER));
+	if (!anyKeptEntry) {
+		const headerStart = systemPrompt.slice(0, openStart).indexOf(HEADER_MARKER);
+		const cutStart = headerStart !== -1 ? headerStart : openStart;
+		return {
+			prompt: systemPrompt.slice(0, cutStart) + systemPrompt.slice(closeStart + CLOSE_TAG.length),
+			removed,
+		};
+	}
+	return {
+		prompt: systemPrompt.slice(0, contentStart) + kept.join("") + systemPrompt.slice(closeStart),
+		removed,
+	};
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+	"name": "@whamp/pi-pstack",
+	"version": "0.7.0",
+	"description": "pstack for Pi: rigorous agent workflows you can parallelize with confidence - poteto-mode playbooks, engineering principles, multi-model review panels, and subagents.",
+	"type": "module",
+	"license": "MIT",
+	"author": "Will Hampson <whamp@ggl.slmail.me> (https://github.com/Whamp)",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Whamp/pi-extensions.git",
+		"directory": "packages/pi-pstack"
+	},
+	"bugs": {
+		"url": "https://github.com/Whamp/pi-extensions/issues"
+	},
+	"homepage": "https://github.com/Whamp/pi-extensions/tree/master/packages/pi-pstack#readme",
+	"publishConfig": {
+		"access": "public"
+	},
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"skills",
+		"workflow",
+		"principles",
+		"poteto-mode",
+		"subagents",
+		"unslop"
+	],
+	"files": [
+		"extensions/",
+		"!extensions/**/*.test.ts",
+		"skills/",
+		"agents/",
+		"README.md",
+		"LICENSE"
+	],
+	"dependencies": {
+		"typebox": "1.3.7"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*"
+	},
+	"pi": {
+		"extensions": [
+			"./extensions/pstack/index.ts"
+		],
+		"skills": [
+			"./skills"
+		],
+		"subagents": {
+			"agents": [
+				"./agents"
+			]
+		}
+	},
+	"scripts": {
+		"test": "node --experimental-strip-types --test extensions/pstack/*.test.ts skills/poteto-mode/scripts/check-plan.test.mjs scripts/reground-from-cursor.test.mjs"
+	}
+}

package/skills/architect/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: architect
+description: "Sketch types, signatures, and module structure before code, then stay in the loop while implementation fills in. Use for /skill:architect, 'architect this', 'design this', or non-trivial work where jumping to code would lock in the wrong shape."
+disable-model-invocation: true
+---
+
+# Architect
+
+Design before implementing. Sketch types, function signatures, class shapes, and module boundaries with `not implemented` bodies and pseudocode. Synthesize across multiple model perspectives, then fill in code against the chosen sketch. If implementation proves the sketch wrong, throw it out and redesign.
+
+## Start
+
+Open a todolist with one entry per phase before starting.
+
+1. Ground
+2. Sketch
+3. Agree
+4. Implement
+5. Scrap
+
+## Phase A: Ground the problem
+
+Build a real mental model of every system the new code touches. Run the **how** skill over the relevant subsystems.
+
+Naming a file isn't grounding. Produce the traced model `how` prescribes. If the design redefines ownership or layering, also run the **why** skill on the existing shape so the rationale becomes a constraint, not a guess.
+
+Skip Phase A only when the work is genuinely greenfield with no surrounding system to integrate.
+
+## Phase B: Sketch
+
+Run the **arena** skill with the design-sketch task and the Phase A grounding artifacts. Pass `references/runner-prompt.md` as each runner's prompt. Each candidate produces a design package shaped per `references/rationale-template.md`.
+
+Override Arena's candidate selector with `architect runners` (defaults inherit-parent). Require at least two candidates. The Arena judge still uses `arena judge pool`.
+
+Design it twice. Require at least two structurally distinct candidates before synthesis, even when the first looks sufficient. This is the **exhaust-the-design-space** principle skill made concrete. Whole-shape alternatives, not point fixes inside one shape.
+
+Screen every candidate against [`references/design-red-flags.md`](references/design-red-flags.md) before synthesis. Reject or revise shallow modules, information leakage, temporal decomposition, and pass-through methods.
+
+Compare viable candidates on interface depth. Prefer the design that hides more complexity behind a smaller, simpler public surface. A rich interface can keep call chains short by concentrating capability instead of scattering it across layers.
+
+Arena returns one synthesized design package. The synthesis decision populates the rationale's "Synthesis decision" section.
+
+## Phase C: Agree (opt-in)
+
+Default: proceed directly to implementation with the synthesized design. No human checkpoint.
+
+Opt in to a checkpoint when the invoker explicitly asks: "/skill:architect with checkpoint," "stop and show me before implementing," or similar. Then surface the synthesized design and pause for sign-off.
+
+The synthesis can ship as its own commit either way, as the "scaffold first" mode of the **foundational-thinking** principle skill. Planned and scoped breakage during fill-in is fine, per the **outcome-oriented-execution** principle skill. For adversarial pressure on the design before implementing, run the **interrogate** skill on the synthesized sketch.
+
+If the human pushes back on the shape (in a checkpoint or after the fact), treat that as Phase A evidence. Re-ground and re-run Phase B before writing more code.
+
+## Phase D: Implement against the sketch
+
+Replace `not implemented` bodies with code, pseudocode with logic. The synthesized sketch is the contract.
+
+Deviations from the sketch are signal worth surfacing, not friction to absorb silently. If a function needs a parameter the sketch didn't anticipate, ask whether the sketch was wrong, the requirement was missed, or the implementation is overreaching.
+
+## Phase E: Scrap when the architecture is wrong
+
+If implementation keeps producing friction the sketch can't absorb, throw the sketch out. Don't bolt fixes onto a wrong design, per the **redesign-from-first-principles** and **fix-root-causes** principle skills.
+
+The signal is a *pattern*, not single instances. Tells:
+
+- The same shape of workaround appearing repeatedly across unrelated code.
+- Multiple unrelated edge cases that all need special-case branches.
+- Types that need escape hatches (`any`, casts, optional fields always set in practice) to compile.
+- The "we need a lock" reflex when the sketch said the state wasn't shared.
+- Callers having to know the abstraction's internal rules to use it.
+- Two or more independent Phase D deviations of the same shape across the implementation.
+
+Use judgment. A few edge cases don't condemn an architecture. Some problems are legitimately complex. Complexity in the data is not complexity in the design.
+
+When you scrap:
+
+1. Re-run the **how** skill over what's been built.
+2. Redesign as if the new constraints had been day-one assumptions, per redesign-from-first-principles.
+3. Subtract before adding, per the **subtract-before-you-add** principle skill. The new sketch should be smaller than the old one before it grows.
+4. Return to Phase B and re-run arena.
+
+## Outputs
+
+The caller's usage is written first and the type sketch derived from it. One file with new types and signatures for small changes. Module map plus type definitions for larger work. The rationale ships alongside, shaped per `references/rationale-template.md`, including the usage sketch and the synthesis decision.