pi-goala 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -1,8 +1,19 @@
 # Changelog
 
+## 0.3.2 (2026-07-26)
+
+- Document how `AGENTS.md` and Pi skills customise project and personal
+  workflows around Goala's lifecycle.
+- Describe planning, execution, and verification models as roles rather than
+  incorrectly presenting the repair loop as a separate phase.
+- Clarify the fallback executor activation threshold and distinguish it from
+  unavailable-model fallback.
+- Add direct and extension-level routing tests for every model role, including
+  the fallback activation boundary.
+
 ## 0.3.1 (2026-07-26)
 
-- Make each phase default to keeping its current model configuration.
+- Make each role default to keeping its current model configuration.
 - Separate reasoning-effort changes from provider/model changes.
 - Select provider, then a filtered model, while skipping provider selection
   when only one authenticated provider is available.
@@ -10,7 +21,7 @@
 
 ## 0.3.0 (2026-07-26)
 
-- Add interactive per-phase provider, model, and reasoning selection from Pi's
+- Add interactive per-role provider, model, and reasoning selection from Pi's
   authenticated available-model registry.
 - Support mixed-provider planner, executor, step-verifier, final-verifier, and
   repeated-repair roles.
@@ -69,7 +80,7 @@
 
 ## 0.1.0
 
-- Add persistent goal, plan, execution, verification, and bounded repair phases.
+- Add persistent goal, plan, execution, verification, and bounded repair loops.
 - Add configurable planner, executor, verifier, and repair model roles.
 - Add fresh planning/execution sessions and logical verifier context isolation.
 - Add verifier-gated local episodic memory with SQLite FTS5 retrieval.

package/README.md

@@ -39,7 +39,7 @@ pi install npm:pi-goala
 Pin a release for reproducible team installations:
 
 ```text
-pi install npm:pi-goala@0.3.1
+pi install npm:pi-goala@0.3.2
 ```
 
 Pi's package command both downloads Goala and registers its extension. A plain
@@ -49,7 +49,7 @@ supported installation path.
 From GitHub or a local checkout:
 
 ```text
-pi install git:github.com/barryking/pi-goala@v0.3.1
+pi install git:github.com/barryking/pi-goala@v0.3.2
 pi install /absolute/path/to/pi-goala
 ```
 
@@ -317,6 +317,7 @@ Use this hierarchy:
 | Detailed architecture, domain rules, and decisions | Versioned repository docs, linked from `AGENTS.md` |
 | Product direction and future milestones | `PROJECT_GOAL.md` or `ROADMAP.md` |
 | Personal defaults that apply to every repository | `~/.pi/agent/AGENTS.md` |
+| Repeatable procedures such as commit/PR, release, deployment, or framework workflows | Pi skills, referenced from `AGENTS.md` when mandatory |
 | Distilled experience from successfully completed work | Verified Goala episodic memory |
 
 Pi loads repository and global `AGENTS.md` files into every fresh Goala phase.
@@ -357,6 +358,22 @@ can include it as an evidence-backed episode finding. Important decisions
 should still be committed to the repository; future memory is bounded,
 relevance-ranked, and deliberately treated as untrusted evidence.
 
+### Customise your workflow
+
+Goala works with a standard Pi installation and provides the goal, planning,
+execution, verification, and memory lifecycle. It does not prescribe every
+project procedure.
+
+Put concise, always-applicable rules in the repository's `AGENTS.md`, and put
+personal defaults that apply across repositories in
+`~/.pi/agent/AGENTS.md`. Use Pi skills for detailed, repeatable procedures such
+as commit and pull-request handling, releases, deployments, migrations, or
+framework-specific workflows.
+
+When a skill is mandatory for particular work, reference it from `AGENTS.md`.
+This keeps the instructions loaded into every phase short while allowing the
+full procedure to be loaded only when relevant.
+
 ### When direction changes
 
 Use `/goal revise <feedback>` when the current checkpoint needs rework. Use
@@ -370,13 +387,17 @@ new bounded goal when the desired outcome has materially changed.
 
 The recommended OpenAI Codex preset is:
 
-| Phase | Model | Reasoning |
+| Model role | Model | Reasoning |
 |---|---|---:|
-| Plan | `gpt-5.6-sol` | medium |
-| Execute | `gpt-5.6-luna` | medium |
-| Optional step verification | `gpt-5.6-luna` | medium |
-| Verify | `gpt-5.6-sol` | medium |
-| Repeated repair | `gpt-5.6-terra` | medium |
+| Planner | `gpt-5.6-sol` | medium |
+| Executor | `gpt-5.6-luna` | medium |
+| Optional step verifier | `gpt-5.6-luna` | medium |
+| Final verifier | `gpt-5.6-sol` | medium |
+| Fallback executor | `gpt-5.6-terra` | medium |
+
+Repeated repair is not a separate lifecycle phase. It loops back into
+execution after verification fails. The fallback executor replaces the normal
+executor only after the configured number of failed verification attempts.
 
 If those models are unavailable, Goala can use the model that was active
 when Pi started. Run `/goala-setup current` to persist that portable

package/docs/architecture.md

@@ -3,7 +3,8 @@
 Goala is one Pi extension with three responsibilities:
 
 1. persist a goal and its acceptance contract;
-2. route work through plan, execute, verify, and repair phases;
+2. route work through planning, execution, independent verification, and a
+   bounded repair loop;
 3. retrieve and promote bounded verified memory.
 
 ## Module boundaries
@@ -13,7 +14,7 @@ own one concern:
 
 | Module | Responsibility |
 |---|---|
-| `index.ts` | Commands, phase transitions, model routing, and event orchestration |
+| `index.ts` | Commands, phase transitions, and event orchestration |
 | `tools.ts` | Tool schemas and state transitions caused by tool submissions |
 | `session.ts` | Fresh-session handoff and logical phase context slicing |
 | `sources.ts` | Safe project-local source resolution, hashing, and drift detection |
@@ -23,6 +24,7 @@ own one concern:
 | `workflow.ts` | Goal-state types, normalization, and invariants |
 | `memory.ts` | Verified episodic storage and retrieval |
 | `recovery.ts` | Discovery of unfinished goals in saved Pi sessions |
+| `routing.ts` | Model-role selection and fallback-executor activation |
 | `setup.ts` | Interactive available-model selection for each lifecycle role |
 | `config.ts` | Namespaced configuration and model-role presets |
 

package/docs/configuration.md

@@ -105,6 +105,13 @@ unchanged.
 }
 ```
 
+`fallbackExecutor` is not a separate lifecycle phase. It replaces the normal
+executor inside the repair loop after repeated verification failures.
+`afterRepairCycle` is the number of failed verification attempts that activates
+it. With the default value of `2`, the first repair still uses the normal
+executor; after the repaired work fails verification again, subsequent
+execution uses the fallback executor.
+
 Restart Pi or use `/reload` after manually editing the file.
 
 Version 1 configuration used one top-level `provider`. Goala reads that schema,

package/extensions/goala/config.ts

@@ -218,7 +218,7 @@ export const GOALA_SETUP_PRESETS: readonly GoalaSetupPreset[] = [
 	},
 	{
 		id: "current",
-		label: "Use the current model for every phase",
+		label: "Use the current model for every role",
 		create: (currentModel) =>
 			currentModel
 				? currentModelConfig(currentModel.provider, currentModel.id)
@@ -250,13 +250,14 @@ export function formatConfig(config: GoalaConfig): string {
 		`Executor: ${formatProfile(config.executor)}`,
 		`Step verifier: ${formatProfile(config.stepVerifier)}`,
 		`Verifier: ${formatProfile(config.verifier)}`,
-		`Fallback: ${formatProfile(config.fallbackExecutor)} from repair ${config.fallbackExecutor.afterRepairCycle}`,
+		`Fallback executor: ${formatProfile(config.fallbackExecutor)}`,
+		`Fallback executor activates after: ${config.fallbackExecutor.afterRepairCycle} failed verification attempts`,
 		`Review policy: ${config.reviewPolicy}`,
 		`Memory: ${config.memory.enabled ? "enabled" : "disabled"}; auto-recall ${config.memory.autoRecall ? "on" : "off"}`,
-		`Current-model fallback: ${config.allowCurrentModelFallback ? "allowed" : "disabled"}`,
+		`Unavailable-model fallback to current Pi model: ${config.allowCurrentModelFallback ? "allowed" : "disabled"}`,
 	].join("\n");
 }
 
 function formatProfile(profile: ModelProfile): string {
-	return `${profile.provider}/${profile.model}:${profile.thinkingLevel}`;
+	return `${profile.provider}/${profile.model} · ${profile.thinkingLevel} reasoning`;
 }

package/extensions/goala/index.ts

@@ -10,7 +10,6 @@ import {
 	loadConfig,
 	writeConfig,
 	type GoalaConfig,
-	type ModelProfile,
 	type ReviewPolicy,
 	type ThinkingLevel,
 } from "./config.ts";
@@ -37,6 +36,7 @@ import {
 	findRecoverableGoals,
 	formatRecoveryStatus,
 } from "./recovery.ts";
+import { modelProfileForPhase } from "./routing.ts";
 import {
 	moveToFreshSession,
 	slicePhaseContext,
@@ -102,23 +102,6 @@ export default function goala(pi: ExtensionAPI): void {
 		displayPlan(pi, state);
 	}
 
-	function profileForPhase(): ModelProfile {
-		if (
-			state.phase === "planning" ||
-			state.phase === "awaiting-execution" ||
-			state.phase === "awaiting-review"
-		) return config.planner;
-		if (state.phase === "verifying-step") return config.stepVerifier;
-		if (state.phase === "verifying") return config.verifier;
-		if (
-			state.phase === "executing" &&
-			state.repairCycles >= config.fallbackExecutor.afterRepairCycle
-		) {
-			return config.fallbackExecutor;
-		}
-		return config.executor;
-	}
-
 	async function statusForSession(
 		ctx: ExtensionCommandContext,
 	): Promise<string> {
@@ -143,7 +126,11 @@ export default function goala(pi: ExtensionAPI): void {
 			return true;
 		}
 
-		const profile = profileForPhase();
+		const profile = modelProfileForPhase(
+			config,
+			state.phase,
+			state.repairCycles,
+		);
 		let model = ctx.modelRegistry.find(profile.provider, profile.model);
 		if (!model && config.allowCurrentModelFallback) {
 			const fallback = sessionDefaultModel ?? (ctx.model
@@ -563,12 +550,12 @@ Do not edit files or rely on executor claims. Finish with submit_step_verificati
 		if (!choice && ctx.hasUI) {
 			const selected = await ctx.ui.select("Goala setup", [
 				...GOALA_SETUP_PRESETS.map((preset) => preset.label),
-				"Configure each phase",
+				"Configure each role",
 				"Show current configuration",
 			]);
 			choice = selected === "Show current configuration"
 				? "status"
-				: selected === "Configure each phase"
+				: selected === "Configure each role"
 					? "custom"
 				: GOALA_SETUP_PRESETS.find((preset) => preset.label === selected)?.id ?? "";
 		}

package/extensions/goala/routing.ts

@@ -0,0 +1,28 @@
+import type {
+	GoalaConfig,
+	ModelProfile,
+} from "./config.ts";
+import type { Phase } from "./workflow.ts";
+
+export function modelProfileForPhase(
+	config: GoalaConfig,
+	phase: Phase,
+	repairCycles: number,
+): ModelProfile {
+	if (
+		phase === "planning" ||
+		phase === "awaiting-execution" ||
+		phase === "awaiting-review"
+	) {
+		return config.planner;
+	}
+	if (phase === "verifying-step") return config.stepVerifier;
+	if (phase === "verifying") return config.verifier;
+	if (
+		phase === "executing" &&
+		repairCycles >= config.fallbackExecutor.afterRepairCycle
+	) {
+		return config.fallbackExecutor;
+	}
+	return config.executor;
+}

package/extensions/goala/setup.ts

@@ -21,7 +21,7 @@ const MODEL_ROLES: ReadonlyArray<{ key: ModelRole; label: string }> = [
 	{ key: "executor", label: "Executor" },
 	{ key: "stepVerifier", label: "Step verifier" },
 	{ key: "verifier", label: "Final verifier" },
-	{ key: "fallbackExecutor", label: "Repair fallback" },
+	{ key: "fallbackExecutor", label: "Fallback executor" },
 ];
 
 const THINKING_LEVELS: readonly ThinkingLevel[] = [
@@ -38,7 +38,7 @@ const KEEP_CURRENT = "Keep current";
 const CHANGE_REASONING = "Change reasoning effort";
 const CHANGE_MODEL = "Change provider or model";
 const SAVE_CONFIGURATION = "Save configuration";
-const EDIT_PHASE = "Edit a phase";
+const EDIT_ROLE = "Edit a role";
 const CANCEL = "Cancel";
 
 function titleCase(value: string): string {
@@ -225,8 +225,12 @@ async function configureRole(
 		...(currentModel?.reasoning ? [CHANGE_REASONING] : []),
 		CHANGE_MODEL,
 	];
+	const activation =
+		role.key === "fallbackExecutor"
+			? `\nActivates after ${config.fallbackExecutor.afterRepairCycle} failed verification attempts`
+			: "";
 	const action = await ctx.ui.select(
-		`${role.label}\nCurrent: ${profileLabel(ctx, available, current)}`,
+		`${role.label}${activation}\nCurrent: ${profileLabel(ctx, available, current)}`,
 		actions,
 	);
 	if (!action) return false;
@@ -251,8 +255,13 @@ function reviewSummary(
 	config: GoalaConfig,
 ): string {
 	return MODEL_ROLES.map(
-		(role) =>
-			`${role.label}: ${profileLabel(ctx, available, config[role.key])}`,
+		(role) => {
+			const label =
+				role.key === "fallbackExecutor"
+					? `${role.label} (after ${config.fallbackExecutor.afterRepairCycle} failed verification attempts)`
+					: role.label;
+			return `${label}: ${profileLabel(ctx, available, config[role.key])}`;
+		},
 	).join("\n");
 }
 
@@ -261,7 +270,7 @@ export async function selectModelRoles(
 	current: GoalaConfig,
 ): Promise<GoalaConfig | undefined> {
 	if (!ctx.hasUI) {
-		ctx.ui.notify("Per-phase model setup requires interactive Pi.", "warning");
+		ctx.ui.notify("Per-role model setup requires interactive Pi.", "warning");
 		return undefined;
 	}
 
@@ -287,13 +296,13 @@ export async function selectModelRoles(
 	while (true) {
 		const action = await ctx.ui.select(
 			`Review Goala configuration\n${reviewSummary(ctx, available, proposed)}`,
-			[SAVE_CONFIGURATION, EDIT_PHASE, CANCEL],
+			[SAVE_CONFIGURATION, EDIT_ROLE, CANCEL],
 		);
 		if (!action || action === CANCEL) return undefined;
 		if (action === SAVE_CONFIGURATION) return proposed;
 
 		const selectedRole = await ctx.ui.select(
-			"Choose a phase to edit",
+			"Choose a role to edit",
 			MODEL_ROLES.map((role) => role.label),
 		);
 		if (!selectedRole) return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-goala",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Goal-oriented agent lifecycle, evidence, and verified memory for Pi.",
   "type": "module",
   "author": "Barry King",