Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## Unreleased

- Changed: `@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui` dev dependencies move from ^0.83.0 to 1.4.0; type check and the full validate pass unchanged.
- Fixed: since pi 1.2.0 `before_agent_start` also fires for runs started by `pi.sendMessage` with `triggerTurn`, which is how the refinement protocol starts its scan. The handler now leaves a `"custom"` run untouched, so the refinement run no longer receives the autonomy prompt and no longer consumes the one-shot intent debt or session briefing meant for the next user prompt. Covered by `tests/lifecycle-hooks.test.ts`; recorded as an amendment to the autonomous-refinement-protocol ADR.

## [0.5.1] - 2026-09-14

- Added: root `mcp-arch.yaml` declaring the graded scope (`repo: .`) and excluding `.pi/` — the embedded upstream-template clone that duplicated every enola finding (~1,100 phantom symbols, ~1,729 facts).
Expand Down
1 change: 1 addition & 0 deletions extensions/pi-brain/hooks/lifecycle.ts
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,7 @@ export function registerLifecycleHooks(
const home = await requireBrain(ctx.cwd);
lastSystemPrompt.current = event.systemPrompt ?? "";
if (!home) return {};
if (event.messageType === "custom") return {};

const state = await readAutonomy(home);
const agentsLoaded = hasAgentsMd(event.systemPromptOptions?.contextFiles);
Expand Down
3,198 changes: 1,399 additions & 1,799 deletions package-lock.json

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,8 @@
"validate": "npm run check && npm test && node tools/brain-sync.mjs && node tools/brain-links.mjs && node tools/brain-intent.mjs --check"
},
"devDependencies": {
"@earendil-works/pi-coding-agent": "^0.83.0",
"@earendil-works/pi-tui": "^0.83.0",
"@earendil-works/pi-coding-agent": "1.4.0",
"@earendil-works/pi-tui": "1.4.0",
"tsx": "^4.23.1",
"typescript": "^5.9.3"
},
Expand Down
83 changes: 83 additions & 0 deletions tests/lifecycle-hooks.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
/**
* Lifecycle hook tests: since pi 1.2.0 before_agent_start also fires for
* runs started by pi.sendMessage with triggerTurn (the refinement run), so
* the brain's handler must act only on user prompts.
*/

import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
import { mkdtemp, writeFile, mkdir, rm } from "node:fs/promises";
import { join } from "node:path";
import { tmpdir } from "node:os";
import { registerLifecycleHooks } from "../extensions/pi-brain/hooks/lifecycle.js";
import { recordIntentTarget } from "../extensions/pi-brain/intent-first.js";

type Handler = (event: any, ctx: ExtensionContext) => Promise<any>;

async function createTempBrainHome(): Promise<string> {
const dir = await mkdtemp(join(tmpdir(), "pi-brain-lifecycle-test-"));
await mkdir(join(dir, "wiki", "_state"), { recursive: true });
await writeFile(join(dir, "brain.config.yml"), "org: Test Org\n", "utf-8");
await writeFile(join(dir, "wiki", "_state", "autonomy.json"), JSON.stringify({ enabled: true }), "utf-8");
await writeFile(join(dir, "wiki", "_state", "inbox.md"), "---\nkind: inbox\n---\n\n# Inbox\n", "utf-8");
return dir;
}

function createContext(cwd: string): ExtensionContext {
return {
cwd,
isIdle: () => true,
sessionManager: { getSessionFile: () => join(cwd, ".pi", "session.json"), getEntries: () => [] },
ui: { notify: () => {} },
} as unknown as ExtensionContext;
}

async function main() {
const home = await createTempBrainHome();
try {
const handlers: Record<string, Handler> = {};
const api = { on: (event: string, handler: Handler) => { handlers[event] = handler; } } as unknown as ExtensionAPI;
const briefed = new Set<string>();
registerLifecycleHooks(api, { current: "" }, briefed, { always: [], home: [], bootstrap: [] });

const handler = handlers["before_agent_start"];
if (!handler) throw new Error("before_agent_start handler not registered");
const ctx = createContext(home);
const sessionFile = join(home, ".pi", "session.json");

recordIntentTarget(sessionFile, { kind: "code", repoName: "warehouse-app", relPath: "app/models/shift.rb" } as any);

const custom = await handler(
{
type: "before_agent_start",
messageType: "custom",
systemPrompt: "base",
systemPromptOptions: {},
message: { customType: "brain-refinement-trigger", content: "Run the autonomous refinement protocol.", display: false },
},
ctx,
);
if (custom && (custom.systemPrompt !== undefined || custom.message !== undefined)) {
throw new Error(`custom-message run was modified: ${JSON.stringify(custom)}`);
}
if (briefed.has(sessionFile)) throw new Error("custom-message run consumed the session briefing");
console.log("✓ a triggerTurn custom run is left untouched");

const user = await handler(
{ type: "before_agent_start", messageType: "user", prompt: "hello", systemPrompt: "base", systemPromptOptions: {} },
ctx,
);
if (!user.systemPrompt.includes("intent debt")) throw new Error("user prompt did not receive the intent debt left by the custom run");
if (!user.systemPrompt.includes("autonomy") && user.systemPrompt === "base") throw new Error("user prompt got no brain context");
if (!briefed.has(sessionFile)) throw new Error("user prompt did not receive the session briefing");
console.log("✓ the next user prompt still receives the one-shot intent debt and briefing");

console.log("✓ lifecycle hooks test passed");
} finally {
await rm(home, { recursive: true, force: true });
}
}

main().catch((err) => {
console.error(err);
process.exit(1);
});
62 changes: 47 additions & 15 deletions wiki/_state/links.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"generated_at": "2026-09-14T10:50:30.231Z",
"node_count": 108,
"edge_count": 655,
"generated_at": "2026-10-22T11:51:00.173Z",
"node_count": 109,
"edge_count": 658,
"nodes": [
{
"path": "brain/_archive/bets/embed-pi-brain-default-behaviour.md",
Expand Down Expand Up @@ -234,6 +234,13 @@
"confidence": "high",
"title": "Integrate optional enola intelligence into relevant pi-brain skills"
},
{
"path": "brain/ai-suggestions/refinement/intent-stamp-test-order-sensitivity.md",
"kind": "refinement",
"status": "draft",
"confidence": "low",
"title": "> Unreviewed ai-suggestion — promote only via /brain:tend."
},
{
"path": "brain/ai-suggestions/refinement/learn-from-tt-brain-enola-integration.md",
"kind": "refinement",
Expand Down Expand Up @@ -1029,44 +1036,44 @@
{
"source": "brain/adrs/autonomous-refinement-protocol",
"target": "brain/prds/autonomous-refinement-protocol",
"kind": "markdown",
"kind": "related",
"provenance": "body",
"context": "wiki/brain/prds/autonomous-refinement-protocol.md"
"context": "Related section"
},
{
"source": "brain/adrs/autonomous-refinement-protocol",
"target": "brain/bets/autonomous-refinement-protocol",
"kind": "markdown",
"kind": "related",
"provenance": "body",
"context": "wiki/brain/bets/autonomous-refinement-protocol.md"
"context": "Related section"
},
{
"source": "brain/adrs/autonomous-refinement-protocol",
"target": "brain/epics/regenerative-intent",
"kind": "markdown",
"kind": "related",
"provenance": "body",
"context": "wiki/brain/epics/regenerative-intent.md"
"context": "Related section"
},
{
"source": "brain/adrs/autonomous-refinement-protocol",
"target": "brain/adrs/smarter-autonomy",
"kind": "markdown",
"kind": "related",
"provenance": "body",
"context": "wiki/brain/adrs/smarter-autonomy.md"
"context": "Related section"
},
{
"source": "brain/adrs/autonomous-refinement-protocol",
"target": "brain/constraints/adr-before-structural-changes",
"kind": "markdown",
"kind": "related",
"provenance": "body",
"context": "wiki/brain/constraints/adr-before-structural-changes.md"
"context": "Related section"
},
{
"source": "brain/adrs/autonomous-refinement-protocol",
"target": "brain/constraints/explicit-approval-for-commits",
"kind": "markdown",
"kind": "related",
"provenance": "body",
"context": "wiki/brain/constraints/explicit-approval-for-commits.md"
"context": "Related section"
},
{
"source": "brain/adrs/background-task-runner",
Expand Down Expand Up @@ -3777,6 +3784,13 @@
"provenance": "body",
"context": "Integrate optional enola intelligence into relevant pi-brain"
},
{
"source": "index",
"target": "brain/ai-suggestions/refinement/intent-stamp-test-order-sensitivity",
"kind": "markdown",
"provenance": "body",
"context": "> Unreviewed ai-suggestion — promote only via /brain:tend."
},
{
"source": "index",
"target": "brain/ai-suggestions/refinement/learn-from-tt-brain-enola-integration",
Expand Down Expand Up @@ -4197,6 +4211,13 @@
"provenance": "body",
"context": "Structural regression detected by enola (2026-09-14)"
},
{
"source": "org/options",
"target": "brain/ai-suggestions/refinement/intent-stamp-test-order-sensitivity",
"kind": "markdown",
"provenance": "body",
"context": "> Unreviewed ai-suggestion — promote only via /brain:tend."
},
{
"source": "org/options",
"target": "brain/pitches/upstream-template-sync",
Expand Down Expand Up @@ -4631,6 +4652,13 @@
"provenance": "body",
"context": "Structural regression detected by enola (2026-09-14)"
},
{
"source": "org/roadmap",
"target": "brain/ai-suggestions/refinement/intent-stamp-test-order-sensitivity",
"kind": "markdown",
"provenance": "body",
"context": "> Unreviewed ai-suggestion — promote only via /brain:tend."
},
{
"source": "org/roadmap",
"target": "brain/pitches/upstream-template-sync",
Expand Down Expand Up @@ -5640,6 +5668,10 @@
"path": "brain/ai-suggestions/refinement/enola-insights-split-heavy-registration-functions.md",
"incoming": 3
},
{
"path": "brain/ai-suggestions/refinement/intent-stamp-test-order-sensitivity.md",
"incoming": 3
},
{
"path": "brain/ai-suggestions/refinement/learn-from-tt-brain-enola-integration.md",
"incoming": 3
Expand Down
10 changes: 10 additions & 0 deletions wiki/brain/adrs/autonomous-refinement-protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,3 +90,13 @@ The protocol must NOT:
- [wiki/brain/adrs/smarter-autonomy.md](../adrs/smarter-autonomy.md)
- [wiki/brain/constraints/adr-before-structural-changes.md](../constraints/adr-before-structural-changes.md)
- [wiki/brain/constraints/explicit-approval-for-commits.md](../constraints/explicit-approval-for-commits.md)

## Amendments

### 2026-10-22: refinement runs are not user prompts to the before_agent_start hook

The direction is unchanged; a host release changed what the hook sees. Since pi 1.2.0 (verified against 1.4.0), `before_agent_start` also fires for a run started by `pi.sendMessage` with `triggerTurn`, which is how the protocol starts its scan from the `agent_settled` hook. The event is a union on `messageType`: user prompts carry `prompt`, custom messages carry the starting `message`.

Left unguarded, the brain's `before_agent_start` handler would append the autonomy prompt to the refinement run and would hand the one-shot intent-debt accounting and the session briefing to the refinement run instead of the next user prompt. The decision is that the handler skips a run whose `messageType` is `"custom"` (so an older host that sends no `messageType` behaves as before) and returns an empty result for a custom run, so a refinement run carries exactly what it carried before pi 1.2.0.

Measured line: `tests/lifecycle-hooks.test.ts` fails on the unguarded handler (a custom-message event consumes the intent debt and the briefing) and passes on the guarded one; pi 1.4.0 is the verified host version.
1 change: 1 addition & 0 deletions wiki/org/options.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ The immediate options are finishing touches after the regenerative-intent delive

<!-- brain-state: shaping -->
- [Structural regression detected by enola (2026-09-14)](../brain/ai-suggestions/enola/enola-regression-2026-09-14.md)
- [> Unreviewed ai-suggestion — promote only via /brain:tend.](../brain/ai-suggestions/refinement/intent-stamp-test-order-sensitivity.md)
- [Upstream template sync for pi-brain clones](../brain/pitches/upstream-template-sync.md)
- [PRD — Tap pi’s full extension surface for pi-brain](../brain/prds/tap-pi-extension-surface.md)
<!-- /brain-state -->
Expand Down
1 change: 1 addition & 0 deletions wiki/org/roadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@ The regenerative-intent epic is delivered and the link graph is clean. Next comm

<!-- brain-state: shaping -->
- [Structural regression detected by enola (2026-09-14)](../brain/ai-suggestions/enola/enola-regression-2026-09-14.md)
- [> Unreviewed ai-suggestion — promote only via /brain:tend.](../brain/ai-suggestions/refinement/intent-stamp-test-order-sensitivity.md)
- [Upstream template sync for pi-brain clones](../brain/pitches/upstream-template-sync.md)
- [PRD — Tap pi’s full extension surface for pi-brain](../brain/prds/tap-pi-extension-surface.md)
<!-- /brain-state -->
Expand Down
Loading