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
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ When autonomy is ON, the agent may perform low-risk maintenance silently (batchi

pi-brain supports two delivery modes, controlled by `LOCAL_FIRST` in `.env`:

- **LOCAL_FIRST=true (default for solo operators):** land each phase as a local commit on the current branch. Do not open PRs unless the user explicitly asks. Keep commits small and focused on one ADR/PRD/bet at a time.
- **LOCAL_FIRST=true (opt-in for solo operators; `.env.example` ships `false`):** land each phase as a local commit on the current branch. Do not open PRs unless the user explicitly asks. Keep commits small and focused on one ADR/PRD/bet at a time.
- **LOCAL_FIRST=false (team/CI mode):** open a PR per phase or per bet. Each PR must link to the approved ADR/PRD/bet in the brain.

### PR conventions
Expand Down
12 changes: 11 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,17 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## Unreleased
## [0.5.2] - 2026-10-25

- Fixed: the GitHub-release update fallback (`/brain:update` when the package manager path fails) nested directories on apply (`extensions/extensions/`) and never placed `tools/lib`, `tools/brain-intent.mjs`, `tools/brain-projects.mjs`, `tools/run-tasks.mjs` or `tools/migrate-clone.mjs`. One shared owned-path list (`tools/lib/template-owned.mjs`) now serves the fallback and `tools/migrate-clone.mjs`, and apply replaces the owned path in place. Covered by `tests/template-update.test.ts`, which also fails when a file under `tools/` is missing from the list.
- Fixed: the template version was stamped as four different values (package 0.5.1, repo config v0.5.0, clone script v0.3.0, `/brain:setup` v0.3.2). `package.json` is now the single source, read by `/brain:setup` and `tools/clone-pi-brain.sh`; `tests/version-consistency.test.ts` guards it.
- Fixed: `tools/connectors/run.mjs` looked for `github.mjs` inside the clone, so `brain_pull_connectors` failed in a content-only clone; it now runs the one beside it. The GitHub connector exited 1 silently when no repos were configured (it tested `.size` on an array); it now prints its no-repos message and exits 0. Covered by `tests/connectors.test.ts`.
- Fixed: the detached background-task runner was looked up inside the clone. It is resolved through the package like other tool scripts, and declines with an explanation when it would load from `node_modules` (Node cannot load TypeScript there) instead of spawning a worker that dies silently.
- Changed: the drift report no longer declares a `Matched` count that nothing produced.
- Docs: the README describes the regenerative loop at its real size (`data_model` blocks, target `types`; other block types are listed but not rendered), lists all 19 tools and every command, and gives the real test commands (`npm test`, `npm run validate`); GETTING_STARTED and AGENTS no longer call `LOCAL_FIRST=true` a default (`.env.example` ships `false`); connector docs say only GitHub exists; the org roadmap opening line is current.
- Hygiene: a refinement page that named a private project and a former employer is rewritten and renamed (`strengthen-enola-integration-from-prior-art.md`, links updated); owner-specific home paths are removed from the repository config, source snapshot headers, receipts and wiki pages. The `enola.binary` pin in `brain.config.yml` is commented out; set `ENOLA_BINARY` in `.env` to pin a build locally.
- Changed: `package.json` declares a `files` whitelist, so the npm package carries the extension, tools, skills, prompts, themes, personas, types, CI templates and docs (146 files), and no longer this repository's own `wiki/`, `sources/`, `log/` or `.enola/` state (320 files in 0.5.1).
- Folded: refinement on pi's `agent_before_settle` hook instead of the `triggerTurn` send. It raises the supported pi floor and changes when refinement fires, so it needs a design pass; it is a stated limit, not fixed.

- 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.
Expand Down
12 changes: 6 additions & 6 deletions GETTING_STARTED.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,15 +43,15 @@ This gives every pi session the brain extension, skills, prompts, themes, templa
- [ ] Configure a provider API key so pi can use an LLM.
- Set `GOOGLE_API_KEY`, `ANTHROPIC_API_KEY`, etc. in `.env` or via `/login`.
- [ ] Decide on delivery mode.
- Solo/local-first: set `LOCAL_FIRST="true"` in `.env` (default). Land small commits directly.
- Solo/local-first: set `LOCAL_FIRST="true"` in `.env` (`.env.example` ships `"false"`, so this is opt-in). Land small commits directly.
- Team/CI mode: set `LOCAL_FIRST="false"`. Open a PR per bet, using `.github/pull_request_template.md`.

## 3. Configure the brain

- [ ] Edit `brain.config.yml`:
- set `org`
- add active repos/scopes
- enable connectors and list repos/pages/channels if needed
- list repos under `connectors.github.repos` if you want GitHub snapshots (the only connector that exists; the notion, slack, datadog, langfuse and structure keys are reserved placeholders that nothing reads yet)
- set `auto_connect: true` only if you want connectors to run opportunistically
- [ ] Run `/brain:setup` if you want the wizard.

Expand Down Expand Up @@ -89,19 +89,19 @@ This gives every pi session the brain extension, skills, prompts, themes, templa

## 7. Generate and sync code from intent

If your PRD/ADR uses YAML intent blocks, pi-brain can generate and track code:
If your PRD/ADR carries a `data_model` YAML intent block, pi-brain can generate TypeScript interfaces from it and track drift against your code. `types` is the only target today; other block types are not rendered:

- [ ] Build from approved intent.
```bash
/brain:build <scope> <types|interfaces|...>
/brain:build <scope> types
```
- [ ] Check for drift between intent and existing code.
```bash
/brain:diff <scope> <types|...>
/brain:diff <scope> types
```
- [ ] Reconcile drift with proposals.
```bash
/brain:sync-code <scope> <types|...>
/brain:sync-code <scope> types
```
- [ ] Propose revisions to intent based on new evidence.
```bash
Expand Down
28 changes: 17 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,21 +23,23 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the PR-first workflow and local valid

## Regenerative intent workflow

pi-brain is evolving from a static intent store into a regenerative system where approved intent drives code and agents maintain intent over time:
A small, working loop exists for one kind of intent: data models. A PRD or ADR can carry a fenced YAML intent block of type `data_model` (a name plus typed fields). The other block types the parser reads (`api_surface`, `behavior`, `invariant`) are collected and listed, but nothing renders or diffs them yet.

```
PRD/ADR with YAML intent blocks
PRD/ADR with a data_model intent block
↓
/brain:build → generated code
/brain:build <scope> types → generated TypeScript interfaces (a draft under ai-suggestions/)
↓
/brain:diff → drift report
/brain:diff <scope> types → drift report against the interfaces in your code
↓
/brain:sync-code → proposals / apply
/brain:sync-code <scope> types → one proposal per drift item, for a human to decide
↓
/brain:revise → updated intent
/brain:revise → suggested updates to intent
```

Commands: `/brain:build`, `/brain:diff`, `/brain:sync-code`, `/brain:revise`, `/brain:collaborate`, `/brain:rfc-contribute`, `/brain:enqueue`, `/brain:run-tasks`, `/brain:tasks`, `/brain:bg-agent`, `/brain:enola-status`, `/brain:enola-check`, `/brain:enola-capture`, `/brain:enola-generate`, `/brain:enola-diff`, `/brain:enola-citations`, `/brain:enola-baseline`, `/brain:enola-query`, `/brain:enola-impact`.
`types` is the only build and diff target. The drift report compares interface and field names, types and optionality, and lists what is missing in code, extra in code, or mismatched. It does not generate application code beyond those interfaces, and it never edits your code on its own.

Commands: `/brain:build`, `/brain:diff`, `/brain:sync-code`, `/brain:revise`, `/brain:collaborate`, `/brain:rfc-contribute`, `/brain:enqueue`, `/brain:run-tasks`, `/brain:tasks`, `/brain:bg-agent`, `/brain:enola-status`, `/brain:enola-check`, `/brain:enola-capture`, `/brain:enola-generate`, `/brain:enola-diff`, `/brain:enola-citations`, `/brain:enola-baseline`, `/brain:enola-query`, `/brain:enola-impact`, `/brain:enola-govern`, `/brain:enola-plan`, `/brain:enola-findings`, `/brain:enola-judge`.

## Vision: how pi-brain manages knowledge

Expand Down Expand Up @@ -250,10 +252,11 @@ The **package** (installed globally via `pi install @misabegovic/pi-brain`) prov
| `/brain:ingest-repo <path-or-url> [scope]` | Onboard a repository as a maintained project. |
| `/brain:projects` | List onboarded projects. |
| `/brain:convert [subdir]` | Convert current repo into a pi-brain clone. |
| `/brain:dump-prompt` | Dump the last system prompt seen to `tests/fixtures/` (a development baseline tool). |

## Tools

The extension registers these tools for the agent:
The extension registers these 19 tools for the agent:

- `brain_status` — read the status dashboard.
- `brain_capture` — append an item to the inbox.
Expand All @@ -270,6 +273,9 @@ The extension registers these tools for the agent:
- `brain_convert` — convert current repo into a pi-brain clone.
- `brain_pull_connectors` — run configured pull connectors.
- `brain_autonomy` — read or toggle autonomous brain-maintenance mode.
- `brain_update` — update pi-brain (package manager first, GitHub release diff as fallback).
- `brain_enola` — run an enola operation (check, baseline, generate, diff, citations, query, impact or govern).
- `brain_enola_capture` — run enola check and capture structural regressions as an ai-suggestion.
- `brain_ingest` — ingest a file, directory, or URL into `sources/`.

## Design principles
Expand All @@ -294,10 +300,10 @@ Or let `/brain:setup` install it for you. It runs `tools/brain-sync.mjs` before
## Testing

```bash
NODE_PATH=/path/to/pi-coding-agent/node_modules \
node --import /path/to/jiti-register.mjs tests/load.test.ts
npm test # runs every tests/*.test.ts through tsx
npm run validate # type check, tests, wiki sync, link graph, intent check
```

## Roadmap

pi-brain-specific evolutions — multi-repo aggregation, connector producers, richer TUI widgets, and customer packaging — are tracked in this repo's own `wiki/` as the shell is inhabited.
Possible evolutions (multi-repo aggregation, more connectors beyond GitHub, richer TUI widgets, customer packaging) are not committed work; the roadmap is tracked in this repo's own `wiki/` as the shell is inhabited.
7 changes: 5 additions & 2 deletions brain.config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,8 @@ enola.enabled: true
# The PATH copy is a downstream/dev build (0.4.10 at the time of pinning).
# enola-oss is the stock upstream build, upgraded in place; the baseline is
# re-pinned after every upgrade (extractor versions must match to grade).
enola.binary: ~/.local/bin/enola-oss
# enola.binary: /path/to/enola
# (or set ENOLA_BINARY in .env, which takes precedence and keeps a local path out of the repo)
enola.gate_build: false
enola.gate_sync_code: false
enola.auto_baseline: false
Expand All @@ -40,6 +41,8 @@ enola.auto_baseline: false
archived_repos: []

# Connector configuration (all pull-only, off until configured).
# Only the github connector exists today; the other keys are reserved
# placeholders that nothing reads yet.
# Credentials live in .env (read-only-scoped tokens), never in this file.
connectors:
github:
Expand Down Expand Up @@ -81,4 +84,4 @@ brain_session_shutdown: true

# pi-brain template version this clone was created from or last updated to.
# Used by /brain:update to diff against upstream releases.
template_version: "v0.5.0"
template_version: "v0.5.2"
3 changes: 2 additions & 1 deletion extensions/pi-brain/commands/shape.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import { pathExists } from "../utils.ts";
import { readOrg } from "../brain-home.ts";
import { validateMarkdown, regenerateViews } from "../views.ts";
import { requireBrain } from "../context.ts";
import { readPackageVersion } from "../resources.ts";

export function registerShapeCommands(pi: ExtensionAPI) {
pi.registerCommand("brain:shape", {
Expand Down Expand Up @@ -109,7 +110,7 @@ export function registerShapeCommands(pi: ExtensionAPI) {
"brain_session_shutdown: true",
"",
"# pi-brain template version this clone was created from or last updated to.",
`template_version: "v0.3.2"`,
`template_version: "v${await readPackageVersion()}"`,
"",
];
await writeFile(join(cwd, "brain.config.yml"), configLines.join("\n"), "utf-8");
Expand Down
4 changes: 1 addition & 3 deletions extensions/pi-brain/diff.ts
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ function intentToInterface(block: IntentBlock): TsInterface {
}

export interface DriftItem {
kind: "missing_in_code" | "extra_in_code" | "type_mismatch" | "optional_mismatch" | "matched";
kind: "missing_in_code" | "extra_in_code" | "type_mismatch" | "optional_mismatch";
interfaceName: string;
fieldName?: string;
intentType?: string;
Expand Down Expand Up @@ -127,7 +127,6 @@ export function diffInterfaces(intent: TsInterface[], code: TsInterface[]): Drif
}

export function formatDriftReport(scope: string, target: string, items: DriftItem[]): string {
const matched = items.filter((i) => i.kind === "matched");
const missing = items.filter((i) => i.kind === "missing_in_code");
const extra = items.filter((i) => i.kind === "extra_in_code");
const mismatches = items.filter((i) => i.kind === "type_mismatch" || i.kind === "optional_mismatch");
Expand All @@ -138,7 +137,6 @@ export function formatDriftReport(scope: string, target: string, items: DriftIte
`Generated at: ${new Date().toISOString()}`,
"",
"## Summary",
`- Matched: ${matched.length}`,
`- Missing in code: ${missing.length}`,
`- Extra in code: ${extra.length}`,
`- Mismatches: ${mismatches.length}`,
Expand Down
2 changes: 1 addition & 1 deletion extensions/pi-brain/enola.ts
Original file line number Diff line number Diff line change
Expand Up @@ -297,7 +297,7 @@ export async function captureEnolaRegressions(home: BrainHome): Promise<{ captur
}

// ---------------------------------------------------------------------------
// Receipt-based architecture state (inspired by an earlier brain)
// Receipt-based architecture state (patterns from a more mature multi-repo integration)
// ---------------------------------------------------------------------------

export interface EnolaReceipt {
Expand Down
10 changes: 9 additions & 1 deletion extensions/pi-brain/tasks.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import * as path from "node:path";
import { randomUUID } from "node:crypto";
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import type { BrainHome, AutonomyTrustConfig } from "./types.ts";
import { resolveResource } from "./resources.ts";
import { requireBrain } from "./context.ts";
import { getTrustLevel, shouldProceed } from "./autonomy.ts";
import { isValidIdentifier } from "./utils.ts";
Expand Down Expand Up @@ -310,7 +311,14 @@ export async function runTasksDetached(
return { started: false, pids: [], message: "No pending background tasks." };
}

const runnerPath = path.join(home.path, "tools", "run-tasks.mjs");
const runnerPath = await resolveResource(path.join("tools", "run-tasks.mjs"), home);
if (runnerPath.split(path.sep).includes("node_modules")) {
return {
started: false,
pids: [],
message: "The detached runner cannot start from an npm install (Node does not load TypeScript from node_modules). Run /brain:run-tasks without --detach to process the pending tasks in this session.",
};
}
const command = process.execPath;
const baseArgs: string[] = [];

Expand Down
41 changes: 7 additions & 34 deletions extensions/pi-brain/template-update.ts
Original file line number Diff line number Diff line change
@@ -1,32 +1,13 @@
import { readFile, writeFile, stat, mkdir, copyFile } from "node:fs/promises";
import { readFile, writeFile, mkdir, cp, rm } from "node:fs/promises";
import { join, dirname } from "node:path";
import type { BrainHome } from "./types.ts";
import { execFilePromise, pathExists, extractSimpleYamlValue } from "./utils.ts";
import { TEMPLATE_OWNED_PATHS } from "../../tools/lib/template-owned.mjs";

export const TEMPLATE_OWNER = "misabegovic";
export const TEMPLATE_REPO = "pi-brain";

export const TEMPLATE_OWNED_PATHS = [
"AGENTS.md",
"GETTING_STARTED.md",
"README.md",
"extensions",
"skills",
"prompts",
"themes",
"tools/templates",
"tools/connectors",
"tools/brain-convert.mjs",
"tools/brain-ingest-repo.mjs",
"tools/brain-links.mjs",
"tools/brain-state.mjs",
"tools/brain-sync.mjs",
"tools/clone-pi-brain.sh",
"tools/setup-local.sh",
"tools/git-hooks",
".github",
"personas",
];
export { TEMPLATE_OWNED_PATHS };

export interface TemplateChange {
path: string;
Expand Down Expand Up @@ -112,16 +93,8 @@ export async function diffTemplatePaths(home: BrainHome, upstreamDir: string): P
export async function applyTemplateChange(home: BrainHome, upstreamDir: string, change: TemplateChange) {
const localPath = join(home.path, change.path);
const upstreamPath = join(upstreamDir, change.path);
if (change.status === "removed") {
await execFilePromise("rm", ["-rf", localPath]);
} else {
const parent = dirname(localPath);
await mkdir(parent, { recursive: true });
const s = await stat(upstreamPath);
if (s.isDirectory()) {
await execFilePromise("cp", ["-R", upstreamPath, localPath]);
} else {
await copyFile(upstreamPath, localPath);
}
}
await rm(localPath, { recursive: true, force: true });
if (change.status === "removed") return;
await mkdir(dirname(localPath), { recursive: true });
await cp(upstreamPath, localPath, { recursive: true });
}
1 change: 1 addition & 0 deletions log/log.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,3 +45,4 @@ Append-only operations log for this pi-brain instance.
- 2026-09-14: Released v0.5.1 — enola grading restored (stock binary pinned via enola.binary, upgraded to 0.4.19; mcp-arch.yaml excludes .pi/upstream-ref; brain-intent compiles page-to-code anchors only), release records for v0.4.0/v0.5.0 written, template_version bumped to v0.5.0.
- 2026-09-14: capture: npm publish for @misabegovic/pi-brain@0.5.1 is pending: registry auth is expired (npm whoami → 401 against registry.npmj
- 2026-09-14: Published @misabegovic/pi-brain@0.5.1 to npm (registry verified); inbox task archived.
- 2026-10-25: Final polish pass for 0.5.2: update fallback and owned-path list fixed, one template version, connector runner and task runner resolved from the package, docs aligned with the code, private-project and home-path references removed (two files under sources/doc/ had only their source_path header lines edited for that reason). Refinement on agent_before_settle and an npm files whitelist folded. See CHANGELOG.
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

20 changes: 18 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@misabegovic/pi-brain",
"version": "0.5.1",
"version": "0.5.2",
"description": "A cozy knowledge home for pi. Distributed as a global package; brain clones are content-only and inherit skills, prompts, themes, tools, and the extension from the install.",
"keywords": [
"pi-package",
Expand Down Expand Up @@ -48,5 +48,21 @@
"peerDependencies": {
"@earendil-works/pi-coding-agent": "*",
"typebox": "*"
}
},
"files": [
"extensions",
"skills",
"prompts",
"themes",
"personas",
"tools",
"types",
".github",
".env.example",
"AGENTS.md",
"GETTING_STARTED.md",
"README.md",
"CHANGELOG.md",
"tsconfig.json"
]
}
Loading
Loading