Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

feat: thin Pi adapter mounting ECC's canonical skills and commands (#2759)

Renan Olovicseb4970265169
diff --git a/.pi/README.md b/.pi/README.md
new file mode 100644
index 000000000..98f1640b6
--- /dev/null
+++ b/.pi/README.md
@@ -0,0 +1,190 @@
+# .pi — Pi Coding Agent Integration
+
+This directory contains the **Pi adapter** for ECC — a thin extension that connects the
+[@earendil-works/pi-coding-agent](https://github.com/earendil-works/pi-coding-agent)
+terminal coding agent to ECC's canonical skills, prompts, and lifecycle hooks.
+
+## Design Principle
+
+ECC's canonical assets—skills, agents, commands, and hooks—**remain the single source of truth**.
+This adapter contains **only the integration logic**. No copies, no duplication.
+
+## What This Provides
+
+- **ECC's skills** from `./skills/` — available in Pi as `/skill:<name>`
+- **ECC's commands** from `./commands/` — available in Pi as `/<name>`
+- **ECC's engineering rules** from `./rules/common/` — injected into Pi's system
+ prompt on every turn, so coding style, testing, security, git workflow, and
+ code-review standards apply in Pi as they do in other harnesses
+- **Session lifecycle hooks** — ECC's SessionStart and SessionEnd hooks, run through ECC's own
+ `run-with-flags.js`, so `ECC_HOOK_PROFILE` and `ECC_DISABLED_HOOKS` keep working under Pi
+- **Session context injection** — whatever ECC's SessionStart hook returns as
+ `additionalContext` is folded into Pi's system prompt for the next turn
+- **`/ecc-doctor`** — diagnostic command to verify the integration
+
+Verified against Pi 0.84.1: a global install exposes 285 skills and 94 commands, resolved
+directly from `skills/` and `commands/`, with no generated copies.
+
+## Installation
+
+### Option 1: Global Installation (Recommended)
+
+```bash
+# Install ECC as a Pi package
+pi install git:github.com/affaan-m/ECC
+
+# Or from a local checkout
+pi install /path/to/ECC
+
+# Or project-local only
+pi install -l /path/to/ECC
+
+# Verify
+pi list
+```
+
+Then inside Pi, run `/ecc-doctor` to confirm skills, commands, and hooks are available.
+
+To uninstall:
+
+```bash
+pi remove git:github.com/affaan-m/ECC
+```
+
+### Option 2: Zero-Install (Existing Claude Code Users)
+
+If you already have ECC installed for Claude Code, point Pi at the same canonical directories
+from `~/.pi/agent/settings.json`:
+
+```json
+{
+ "skills": ["~/.claude/skills"],
+ "prompts": ["~/.claude/commands"]
+}
+```
+
+This gives you skills and commands directly. It does **not** include the lifecycle hook adapter
+or `/ecc-doctor` — use Option 1 for the full integration.
+
+## How It Works
+
+The `extensions/index.ts` file handles:
+
+1. **Skill and command mounting** — Pi reads `./skills` and `./commands` directly via the
+ `pi` key in `package.json`. No transformation is needed: ECC's `SKILL.md` files already
+ follow the Agent Skills standard Pi implements, and ECC's command frontmatter
+ (`description`, `argument-hint`) is already Pi's prompt-template format
+2. **Lifecycle hooks** — Maps Pi's `session_start` to ECC's `session:start` hook
+ (`scripts/hooks/session-start.js`) and Pi's `session_shutdown` to ECC's `session:end:marker`
+ hook (`scripts/hooks/session-end-marker.js`), both invoked through
+ `scripts/hooks/run-with-flags.js` so ECC's profile and disable flags are honored
+3. **Rule injection** — Reads ECC's portable engineering rules from the canonical
+ `rules/common/` directory at runtime and appends them to the system prompt inside an
+ `<ecc-engineering-rules>` block on every turn. Nothing is copied into `.pi/`.
+ `agents.md`, `hooks.md`, and `performance.md` are excluded on purpose: they describe
+ Claude Code primitives Pi does not have (Task/TodoWrite delegation, Claude hook event
+ types, thinking-budget toggles), so injecting them would point the model at tools that
+ are not there. Language-specific rules under `rules/<language>/` are not injected in this
+ first adapter. Set `ECC_PI_RULES` to `0`, `false`, `off`, `none`, or `disabled` to turn
+ injection off; `/ecc-doctor` reports the current state and the injected size
+4. **Context injection** — Parses `hookSpecificOutput.additionalContext` from the SessionStart
+ hook and appends it to the system prompt on the next `before_agent_start`, wrapped in an
+ `<ecc-session-context>` block. Non-JSON hook output is tolerated, not treated as an error
+5. **Hook isolation** — Failing, missing, or slow hooks degrade to a warning and never
+ terminate the Pi session. Hook execution is bounded by a timeout and an output limit
+6. **Package resolution** — Resolves hook scripts from the installed package via `__dirname`,
+ never from `process.cwd()`, so a global install works from any project directory. Hooks
+ still *run* in the user's project directory, so project detection stays correct
+
+All hook execution is non-shell (`execFile` without shell interpretation), so paths containing
+spaces, tabs, or shell metacharacters are safe.
+
+## Scope
+
+Intentionally **out of scope** for this first adapter (to be added independently):
+
+- Subagent conversion and chains (need the `pi-subagents` companion package)
+- Structured approval gates (need `@juicesharp/rpiv-ask-user-question`)
+- Persistent todos (need `@juicesharp/rpiv-todo`)
+- Profile-based resource filtering
+- MCP translation — see below; no translation turned out to be necessary
+
+ECC works in Pi without any of these. Skills and commands are fully available today.
+
+These capabilities are provided by existing community Pi packages rather than by
+anything ECC would need to write. This adapter deliberately does not bundle or
+auto-install them: bundling would ship third-party code that executes with full
+user permissions in every ECC install, and would make optional capabilities
+mandatory. Install whichever you want yourself — `/ecc-doctor` reports which are
+present and prints the exact `pi install` command for the ones that are not.
+
+### MCP
+
+Pi core has no MCP surface by design. The community `pi-mcp-adapter` package
+adds one, and it reads the standard `mcpServers` format from `.mcp.json` and
+`~/.config/mcp/mcp.json` — which is exactly the format ECC already uses in
+`.mcp.json` and `mcp-configs/mcp-servers.json`.
+
+Verified against `pi-mcp-adapter` 2.21.2: copying ECC's `mcp-configs/mcp-servers.json`
+to a project's `.mcp.json` registers Pi's `mcp` tool and `/mcp` command with all
+35 ECC servers discovered, alongside this adapter's own `/ecc-doctor`. No
+translation layer is needed and no ECC change is required.
+
+```bash
+pi install npm:pi-mcp-adapter
+cp mcp-configs/mcp-servers.json /path/to/project/.mcp.json
+```
+
+ECC neither installs nor depends on that package. Two caveats: the adapter's
+first run against a new config performs initialization that blocks in
+non-interactive (`-p`) mode, so run it once interactively before using it
+headless; and only server discovery was verified, not live tool invocation,
+which needs real credentials for each server.
+
+## Security
+
+- Pi extensions run with the same OS permissions as the Pi process
+- This adapter does **not** auto-commit, push, merge, or deploy
+- Hooks are executed without a shell, preventing command injection
+- Hook failures are isolated and cannot silently authorize blocked operations
+
+## Troubleshooting
+
+### Skills or commands not showing up
+
+**Cause:** the package's resources are disabled, or a project-local install has not been
+trusted. Pi asks before trusting a project folder that carries its own `.pi/` resources.
+
+**Fix:** run `pi config` and confirm the ECC package's skills and prompts are enabled
+(<kbd>Tab</kbd> switches between user and project scope). Then confirm the package itself is
+registered with `pi list`.
+
+### `/ecc-doctor` not found or reports missing package root
+
+**Cause:** Extension not loaded or package installed incorrectly.
+
+**Fix:**
+1. Run `pi list` to confirm ECC is registered
+2. Restart Pi: exit and reopen the session
+3. Run `/ecc-doctor` again
+
+`/ecc-doctor` prints the resolved package root, the skill and command counts it found, the
+hook runner path, the active hook profile, and which optional companion packages are present.
+A `NOT FOUND` line points at the specific path that failed to resolve.
+
+### Hooks not firing
+
+**Cause:** the extension is not loaded, or the hooks are gated off by an ECC hook profile.
+
+**Fix:**
+1. Confirm `pi list` shows ECC and that `/ecc-doctor` reports the hook runner as found
+2. Check `ECC_HOOK_PROFILE` and `ECC_DISABLED_HOOKS` — `/ecc-doctor` prints both. A hook
+ listed in `ECC_DISABLED_HOOKS` is skipped by design
+3. Restart Pi so the extension reloads
+
+## Notes
+
+- The `.pi/extensions/` directory is the only place for adapter code
+- Skills and commands are defined in the repo root (`skills/`, `commands/`) and referenced by Pi
+- MCP is not bundled, but ECC's MCP configs load in Pi through the community `pi-mcp-adapter` — see [MCP](#mcp) above
+- This adapter was tested against Pi v0.84.1
diff --git a/.pi/extensions/index.ts b/.pi/extensions/index.ts
new file mode 100644
index 000000000..411791d72
--- /dev/null
+++ b/.pi/extensions/index.ts
@@ -0,0 +1,646 @@
+/**
+ * ECC adapter for the Pi coding agent.
+ *
+ * This is the ONLY adapter logic ECC ships for Pi. ECC's canonical assets stay
+ * the single source of truth: `skills/` and `commands/` are mounted directly by
+ * the `pi` manifest in the repo's root `package.json`. Nothing is copied or
+ * generated under `.pi/`.
+ *
+ * What this file adapts:
+ * - Pi lifecycle events -> ECC's existing hook runner (`run-with-flags.js`),
+ * so ECC hook profiles and disable flags keep working under Pi.
+ * - ECC's SessionStart `additionalContext` payload -> Pi's system prompt.
+ * - A `/ecc-doctor` command for install diagnostics.
+ *
+ * Design constraints (see .pi/README.md):
+ * - Hooks resolve relative to THIS file, never `process.cwd()`, so a global
+ * `pi install` works from any project directory.
+ * - Hooks execute via `execFile(process.execPath, [...])` with no shell, so
+ * paths containing spaces or shell metacharacters are safe.
+ * - Hook failures are isolated: a broken, missing, or slow hook degrades to a
+ * warning and never terminates the Pi session.
+ */
+
+import { execFile } from "node:child_process"
+import * as fs from "node:fs"
+import * as os from "node:os"
+import * as path from "node:path"
+
+/**
+ * Minimal structural types mirroring `@earendil-works/pi-coding-agent`.
+ *
+ * Declared locally on purpose: Pi loads extensions through jiti, which strips
+ * types without type-checking, so importing the package would add a dependency
+ * and a lockfile entry that buy nothing at runtime. Field names and signatures
+ * match the upstream `ExtensionAPI` / `ExtensionContext` declarations; install
+ * the package as a devDependency if you want editor-level checking.
+ */
+interface PiUiContext {
+ notify(message: string, type?: "info" | "warning" | "error"): void
+}
+
+interface PiSessionManager {
+ getSessionId(): string
+ getSessionFile(): string | undefined
+}
+
+interface ExtensionContext {
+ ui: PiUiContext
+ cwd: string
+ sessionManager: PiSessionManager
+}
+
+interface SessionStartEvent {
+ reason: "startup" | "reload" | "new" | "resume" | "fork"
+}
+
+interface SessionShutdownEvent {
+ reason: "quit" | "reload" | "new" | "resume" | "fork"
+}
+
+interface BeforeAgentStartEvent {
+ systemPrompt: string
+}
+
+interface BeforeAgentStartResult {
+ systemPrompt?: string
+}
+
+interface ExtensionAPI {
+ on(
+ event: "session_start",
+ handler: (event: SessionStartEvent, ctx: ExtensionContext) => Promise<void> | void
+ ): void
+ on(
+ event: "session_shutdown",
+ handler: (event: SessionShutdownEvent, ctx: ExtensionContext) => Promise<void> | void
+ ): void
+ on(
+ event: "before_agent_start",
+ handler: (
+ event: BeforeAgentStartEvent,
+ ctx: ExtensionContext
+ ) => Promise<BeforeAgentStartResult | void> | BeforeAgentStartResult | void
+ ): void
+ registerCommand(
+ name: string,
+ options: {
+ description?: string
+ handler: (args: string, ctx: ExtensionContext) => Promise<void>
+ }
+ ): void
+ sendMessage(
+ message: { customType: string; content: string; display: boolean; details?: unknown },
+ options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" }
+ ): void
+}
+
+/**
+ * ECC package root. This file lives at `<root>/.pi/extensions/index.ts`, so the
+ * root is two levels up. Pi loads extensions via jiti in CommonJS mode, which
+ * is why `__dirname` is the correct primitive here rather than
+ * `import.meta.url` (verified against Pi 0.84.1).
+ */
+const ECC_ROOT = path.resolve(__dirname, "..", "..")
+
+/** ECC's universal hook runner. It applies hook-profile and disable flags. */
+const HOOK_RUNNER = path.join(ECC_ROOT, "scripts", "hooks", "run-with-flags.js")
+
+const HOOK_TIMEOUT_MS = 30_000
+const MAX_HOOK_OUTPUT_BYTES = 1024 * 1024
+
+/**
+ * ECC rules injected into Pi's system prompt, read from the canonical
+ * `rules/common/` directory at runtime. Nothing is copied or generated.
+ *
+ * Excluded on purpose: `agents.md`, `hooks.md`, and `performance.md`. Those
+ * describe Claude Code primitives Pi does not have (Task/TodoWrite delegation,
+ * Claude hook event types, thinking-budget toggles), so injecting them would
+ * instruct the model to use tools that are not there.
+ */
+const PORTABLE_RULE_FILES = [
+ "coding-style.md",
+ "testing.md",
+ "security.md",
+ "git-workflow.md",
+ "patterns.md",
+ "development-workflow.md",
+ "code-review.md",
+] as const
+
+/** Upper bound on injected rule text, so a large edit cannot flood the prompt. */
+const MAX_RULES_BYTES = 32 * 1024
+
+/** Values ECC treats as "off" across its existing environment switches. */
+const DISABLED_VALUES = new Set(["0", "false", "off", "none", "disabled"])
+
+/**
+ * Optional Pi companion packages. ECC works without every one of these; they
+ * are reported by `/ecc-doctor` so users can see which extras are available.
+ */
+const COMPANION_PACKAGES = [
+ "pi-subagents",
+ "@juicesharp/rpiv-ask-user-question",
+ "@juicesharp/rpiv-todo",
+] as const
+
+interface HookSpec {
+ /** ECC hook id, used for profile gating and disable flags. */
+ id: string
+ /** Hook script path relative to the ECC package root. */
+ script: string
+ /** Hook profiles the hook participates in. */
+ profiles: string
+}
+
+/** Mirrors the SessionStart wiring in `hooks/hooks.json`. */
+const SESSION_START_HOOK: HookSpec = {
+ id: "session:start",
+ script: "scripts/hooks/session-start.js",
+ profiles: "minimal,standard,strict",
+}
+
+/** Mirrors the SessionEnd wiring in `hooks/hooks.json`. */
+const SESSION_END_HOOK: HookSpec = {
+ id: "session:end:marker",
+ script: "scripts/hooks/session-end-marker.js",
+ profiles: "minimal,standard,strict",
+}
+
+interface HookResult {
+ stdout: string
+ failure?: string
+}
+
+/**
+ * Run an ECC hook through ECC's own runner.
+ *
+ * Never rejects: a missing runner, a non-zero exit, a timeout, or a spawn error
+ * all resolve to a `failure` string that the caller surfaces as a warning.
+ */
+function runEccHook(
+ spec: HookSpec,
+ payload: unknown,
+ env: NodeJS.ProcessEnv,
+ cwd: string
+): Promise<HookResult> {
+ return new Promise(resolve => {
+ if (!fs.existsSync(HOOK_RUNNER)) {
+ resolve({ stdout: "", failure: `hook runner not found at ${HOOK_RUNNER}` })
+ return
+ }
+
+ const child = execFile(
+ process.execPath,
+ [HOOK_RUNNER, spec.id, spec.script, spec.profiles],
+ {
+ // Hooks inspect the user's project, so they run there. Only the script
+ // path is package-relative, and the runner resolves that from
+ // CLAUDE_PLUGIN_ROOT rather than from the working directory.
+ cwd,
+ env,
+ timeout: HOOK_TIMEOUT_MS,
+ maxBuffer: MAX_HOOK_OUTPUT_BYTES,
+ encoding: "utf8",
+ },
+ (error, stdout) => {
+ const text = typeof stdout === "string" ? stdout : ""
+ if (error) {
+ resolve({ stdout: text, failure: `${spec.id}: ${error.message}` })
+ return
+ }
+ resolve({ stdout: text })
+ }
+ )
+
+ child.on("error", error => {
+ resolve({ stdout: "", failure: `${spec.id}: ${error.message}` })
+ })
+
+ // stdin.end() writes asynchronously. A hook that exits, short-circuits, or
+ // is killed by the timeout before reading the payload makes the write fail
+ // with EPIPE, which Node reports as an `error` event rather than a throw.
+ // Without this listener that event is unhandled and would take the Pi
+ // session down, breaking the isolation guarantee documented above.
+ child.stdin?.on("error", error => {
+ resolve({ stdout: "", failure: `${spec.id}: could not write hook payload (${error.message})` })
+ })
+
+ try {
+ child.stdin?.end(JSON.stringify(payload))
+ } catch (error) {
+ resolve({
+ stdout: "",
+ failure: `${spec.id}: could not write hook payload (${(error as Error).message})`,
+ })
+ }
+ })
+}
+
+/**
+ * Working directory for hook execution: the user's project. Falls back to the
+ * ECC package root if Pi reports a directory that no longer exists, so a stale
+ * cwd degrades to a working hook rather than a spawn failure.
+ */
+function resolveHookCwd(ctx: ExtensionContext): string {
+ try {
+ if (ctx.cwd && fs.existsSync(ctx.cwd)) {
+ return ctx.cwd
+ }
+ } catch {
+ // Fall through to the package root.
+ }
+ return ECC_ROOT
+}
+
+function readSessionId(ctx: ExtensionContext): string | undefined {
+ try {
+ return ctx.sessionManager.getSessionId() || undefined
+ } catch {
+ return undefined
+ }
+}
+
+/**
+ * Build the environment ECC hooks expect.
+ *
+ * `CLAUDE_PLUGIN_ROOT` / `ECC_PLUGIN_ROOT` are how every ECC hook locates the
+ * package; setting them from `ECC_ROOT` is what makes a global install resolve
+ * correctly instead of probing the user's project. The `CLAUDE_*` session vars
+ * are the names ECC's shared hook scripts already read across harnesses.
+ */
+function buildHookEnv(ctx: ExtensionContext): NodeJS.ProcessEnv {
+ const env: NodeJS.ProcessEnv = {
+ ...process.env,
+ CLAUDE_PLUGIN_ROOT: ECC_ROOT,
+ ECC_PLUGIN_ROOT: ECC_ROOT,
+ CLAUDE_PROJECT_DIR: ctx.cwd,
+ }
+
+ const sessionId = readSessionId(ctx)
+ if (sessionId) {
+ env.CLAUDE_SESSION_ID = sessionId
+ }
+
+ return env
+}
+
+/**
+ * Map Pi's session reason onto the `source` values ECC's SessionStart hook
+ * understands. Pi's `new` and `reload` have no Claude Code equivalent, so they
+ * report as a fresh startup.
+ */
+function mapSessionSource(reason: SessionStartEvent["reason"]): string {
+ switch (reason) {
+ case "resume":
+ case "fork":
+ return "resume"
+ default:
+ return "startup"
+ }
+}
+
+/**
+ * Extract `hookSpecificOutput.additionalContext` from a hook's stdout.
+ *
+ * ECC hooks emit a JSON envelope, but the runner passes stdin straight through
+ * when a hook is disabled by profile, so non-JSON stdout is expected and must
+ * not be treated as an error.
+ */
+function extractAdditionalContext(stdout: string): string | undefined {
+ const trimmed = stdout.trim()
+ if (!trimmed.startsWith("{")) {
+ return undefined
+ }
+
+ try {
+ const parsed = JSON.parse(trimmed) as {
+ hookSpecificOutput?: { additionalContext?: unknown }
+ }
+ const context = parsed.hookSpecificOutput?.additionalContext
+ return typeof context === "string" && context.trim() ? context : undefined
+ } catch {
+ return undefined
+ }
+}
+
+function isDisabledByEnv(value: string | undefined): boolean {
+ return typeof value === "string" && DISABLED_VALUES.has(value.trim().toLowerCase())
+}
+
+/** Memoized so the rule files are read once per session, not once per turn. */
+let cachedRules: string | null | undefined
+
+/**
+ * How many of `PORTABLE_RULE_FILES` actually made it into `cachedRules`.
+ *
+ * Kept alongside the cache because `loadPortableRules` silently drops files it
+ * cannot read, files that are empty, and every file past the size cap — so the
+ * allowlist length would overstate a partial install in `/ecc-doctor`, which is
+ * the one place a user looks to find exactly that.
+ */
+let cachedRuleFileCount = 0
+
+/**
+ * ECC's portable engineering rules, concatenated from the canonical
+ * `rules/common/` directory of the installed package.
+ *
+ * Returns null when disabled via `ECC_PI_RULES` or when no rule file could be
+ * read, so a partial install degrades to "no rules" instead of failing.
+ */
+function loadPortableRules(): string | null {
+ if (cachedRules !== undefined) {
+ return cachedRules
+ }
+
+ if (isDisabledByEnv(process.env.ECC_PI_RULES)) {
+ cachedRules = null
+ cachedRuleFileCount = 0
+ return cachedRules
+ }
+
+ const sections: string[] = []
+ let total = 0
+
+ for (const file of PORTABLE_RULE_FILES) {
+ let text: string
+ try {
+ text = fs.readFileSync(path.join(ECC_ROOT, "rules", "common", file), "utf8").trim()
+ } catch {
+ continue
+ }
+
+ if (!text) {
+ continue
+ }
+
+ if (total + text.length > MAX_RULES_BYTES) {
+ break
+ }
+
+ total += text.length
+ sections.push(text)
+ }
+
+ cachedRules = sections.length > 0 ? sections.join("\n\n---\n\n") : null
+ cachedRuleFileCount = sections.length
+ return cachedRules
+}
+
+/**
+ * Pi's config directory, honoring the documented `PI_CODING_AGENT_DIR` override.
+ */
+function resolvePiConfigDir(): string {
+ const override = process.env.PI_CODING_AGENT_DIR
+ if (override && override.trim()) {
+ return override.trim()
+ }
+ return path.join(os.homedir(), ".pi", "agent")
+}
+
+/**
+ * Package names Pi currently has installed, read from the same `packages`
+ * lists Pi itself uses: the user config directory plus the project-local
+ * `.pi/settings.json`.
+ *
+ * `require.resolve` cannot answer this. Pi installs packages under its own
+ * config directory (`<config>/npm`, `<config>/git`), which is not on Node's
+ * module resolution path from this file, so resolving would report every
+ * companion as missing no matter what the user has installed.
+ */
+function listInstalledPiPackages(projectDir: string): Set<string> {
+ const names = new Set<string>()
+
+ const settingsFiles = [
+ path.join(resolvePiConfigDir(), "settings.json"),
+ path.join(projectDir, ".pi", "settings.json"),
+ ]
+
+ for (const file of settingsFiles) {
+ try {
+ const parsed = JSON.parse(fs.readFileSync(file, "utf8")) as { packages?: unknown }
+ if (!Array.isArray(parsed.packages)) {
+ continue
+ }
+ for (const entry of parsed.packages) {
+ const name = normalizePiPackageName(entry)
+ if (name) {
+ names.add(name)
+ }
+ }
+ } catch {
+ // Missing or unreadable settings are simply "nothing installed here".
+ }
+ }
+
+ return names
+}
+
+/**
+ * Reduce a `packages` entry to a bare package name.
+ *
+ * An entry is either the source string itself or an object carrying that
+ * string under `source` alongside resource filters (`{ source: "npm:x",
+ * skills: [] }`). Pi accepts both forms, and a filtered package is just as
+ * installed as a plain one, so both must resolve to the same name.
+ *
+ * Sources look like `npm:pi-subagents`, `npm:@scope/[email protected]`, a git source,
+ * or a filesystem path. Only npm sources carry a comparable package name.
+ */
+function normalizePiPackageName(entry: unknown): string | undefined {
+ const source = entry && typeof entry === "object" ? (entry as { source?: unknown }).source : entry
+
+ if (typeof source !== "string" || !source.startsWith("npm:")) {
+ return undefined
+ }
+
+ const spec = source.slice("npm:".length)
+ // Strip a trailing @version without breaking the leading @ of a scoped name.
+ const versionAt = spec.lastIndexOf("@")
+ return versionAt > 0 ? spec.slice(0, versionAt) : spec
+}
+
+function countDirectories(dir: string): number {
+ try {
+ return fs.readdirSync(dir, { withFileTypes: true }).filter(entry => entry.isDirectory()).length
+ } catch {
+ return 0
+ }
+}
+
+function countMarkdownFiles(dir: string): number {
+ try {
+ return fs.readdirSync(dir).filter(name => name.endsWith(".md")).length
+ } catch {
+ return 0
+ }
+}
+
+function readEccVersion(): string {
+ try {
+ const manifest = JSON.parse(fs.readFileSync(path.join(ECC_ROOT, "package.json"), "utf8")) as {
+ version?: string
+ }
+ return manifest.version || "unknown"
+ } catch {
+ return "unknown"
+ }
+}
+
+function describeRulesStatus(): string {
+ if (isDisabledByEnv(process.env.ECC_PI_RULES)) {
+ return "disabled via ECC_PI_RULES"
+ }
+
+ const rules = loadPortableRules()
+ if (!rules) {
+ return `NOT FOUND (${path.join(ECC_ROOT, "rules", "common")})`
+ }
+
+ const skipped = PORTABLE_RULE_FILES.length - cachedRuleFileCount
+ const shortfall = skipped > 0 ? ` (${skipped} unreadable, empty, or past the size cap)` : ""
+ return `${cachedRuleFileCount}/${PORTABLE_RULE_FILES.length} rule file(s), ${rules.length} chars, from rules/common/${shortfall}`
+}
+
+function buildDoctorReport(ctx: ExtensionContext): string {
+ const skillsDir = path.join(ECC_ROOT, "skills")
+ const commandsDir = path.join(ECC_ROOT, "commands")
+ const skillCount = countDirectories(skillsDir)
+ const commandCount = countMarkdownFiles(commandsDir)
+
+ const lines = [
+ "ECC adapter for Pi",
+ "",
+ ` ECC version: ${readEccVersion()}`,
+ ` Package root: ${ECC_ROOT}`,
+ ` Project cwd: ${ctx.cwd}`,
+ "",
+ "Canonical resources",
+ ` skills/ ${skillCount > 0 ? `${skillCount} skill(s)` : "NOT FOUND"} (${skillsDir})`,
+ ` commands/ ${commandCount > 0 ? `${commandCount} command(s)` : "NOT FOUND"} (${commandsDir})`,
+ "",
+ "Engineering rules (injected into the system prompt)",
+ ` ${describeRulesStatus()}`,
+ "",
+ "Hook runner",
+ ` ${fs.existsSync(HOOK_RUNNER) ? "found" : "NOT FOUND"} (${HOOK_RUNNER})`,
+ ` profile: ${process.env.ECC_HOOK_PROFILE || "standard (default)"}`,
+ ` disabled: ${process.env.ECC_DISABLED_HOOKS || "none"}`,
+ "",
+ "Optional companion packages (from Pi's installed package list)",
+ ]
+
+ const installed = listInstalledPiPackages(ctx.cwd)
+ for (const name of COMPANION_PACKAGES) {
+ const present = installed.has(name)
+ lines.push(` ${present ? "installed " : "not installed"} ${name}`)
+ if (!present) {
+ lines.push(` install with: pi install npm:${name}`)
+ }
+ }
+
+ lines.push(
+ "",
+ "Companion packages are optional; ECC skills, commands, and session hooks",
+ "work without them. See .pi/README.md for what each one unlocks.",
+ "Detection reads Pi's `packages` list, so a companion vendored some other",
+ "way may work while reporting as not installed."
+ )
+
+ return lines.join("\n")
+}
+
+export default function (pi: ExtensionAPI): void {
+ /**
+ * ECC's SessionStart hook returns context for the model, but Pi has no
+ * equivalent of Claude Code's `additionalContext` field. It is held here and
+ * folded into the system prompt on the next agent start, which is the
+ * documented Pi injection point that does not fabricate a user turn.
+ */
+ let pendingContext: string | undefined
+
+ pi.on("session_start", async (event, ctx) => {
+ const payload = {
+ hook_event_name: "SessionStart",
+ source: mapSessionSource(event.reason),
+ cwd: ctx.cwd,
+ session_id: readSessionId(ctx),
+ }
+
+ // Drop any context captured by an earlier session start that has not been
+ // injected yet. Pi can start a new session (/new, /resume, /fork) before
+ // `before_agent_start` consumes the previous value, and replaying context
+ // built for a different session would describe the wrong project state.
+ pendingContext = undefined
+
+ const result = await runEccHook(
+ SESSION_START_HOOK,
+ payload,
+ buildHookEnv(ctx),
+ resolveHookCwd(ctx)
+ )
+
+ if (result.failure) {
+ ctx.ui.notify(`ECC session-start hook skipped (${result.failure})`, "warning")
+ return
+ }
+
+ pendingContext = extractAdditionalContext(result.stdout)
+ })
+
+ pi.on("before_agent_start", event => {
+ const additions: string[] = []
+
+ // Rules describe standing engineering policy, so they are re-applied on
+ // every turn. The session context is a one-shot handoff and is consumed.
+ const rules = loadPortableRules()
+ if (rules) {
+ additions.push(`<ecc-engineering-rules>\n${rules}\n</ecc-engineering-rules>`)
+ }
+
+ if (pendingContext) {
+ additions.push(`<ecc-session-context>\n${pendingContext}\n</ecc-session-context>`)
+ pendingContext = undefined
+ }
+
+ if (additions.length === 0) {
+ return
+ }
+
+ return { systemPrompt: [event.systemPrompt, ...additions].join("\n\n") }
+ })
+
+ pi.on("session_shutdown", async (event, ctx) => {
+ const payload = {
+ hook_event_name: "SessionEnd",
+ reason: event.reason,
+ cwd: ctx.cwd,
+ session_id: readSessionId(ctx),
+ }
+
+ const result = await runEccHook(
+ SESSION_END_HOOK,
+ payload,
+ buildHookEnv(ctx),
+ resolveHookCwd(ctx)
+ )
+
+ if (result.failure) {
+ ctx.ui.notify(`ECC session-end hook skipped (${result.failure})`, "warning")
+ }
+ })
+
+ pi.registerCommand("ecc-doctor", {
+ description: "Report ECC adapter status: package root, canonical resources, hooks, companions",
+ handler: async (_args, ctx) => {
+ pi.sendMessage(
+ {
+ customType: "ecc-doctor",
+ content: buildDoctorReport(ctx),
+ display: true,
+ },
+ { deliverAs: "nextTurn" }
+ )
+ },
+ })
+}
diff --git a/docs/architecture/harness-adapter-compliance.md b/docs/architecture/harness-adapter-compliance.md
index 4d09a8301..09061190d 100644
--- a/docs/architecture/harness-adapter-compliance.md
+++ b/docs/architecture/harness-adapter-compliance.md
@@ -39,6 +39,7 @@ The matrix below is rendered from
| Claude Code | Native | Claude plugin assets; skills; commands; hooks; MCP config; local rules; statusline-oriented workflows | Claude-native hooks do not imply parity in other harnesses | `./install.sh --profile minimal --target claude`; Claude plugin install | `npm run harness:audit -- --format json`; `node scripts/session-inspect.js --list-adapters` | Avoid loading every skill by default; keep hooks opt-in and inspectable. |
| Codex | Instruction-backed | `AGENTS.md`; Codex plugin metadata; skills; MCP reference config; command patterns | Native hook enforcement and Claude slash-command semantics are not equivalent | `./install.sh --profile minimal --target codex`; repo-local `AGENTS.md` review | `npm run harness:audit -- --format json` | Treat hooks as policy text unless a native Codex hook surface exists. |
| OpenCode | Adapter-backed | OpenCode package/plugin metadata; shared skills; MCP config; event adapter patterns | Event names, plugin packaging, and command dispatch differ from Claude Code | OpenCode package or plugin surface from this repo | `node tests/scripts/build-opencode.test.js`; `npm run harness:audit -- --format json` | Keep hook logic in shared scripts and adapt only event shape at the edge. |
+| Pi | Adapter-backed | Pi package manifest; canonical ECC skills (skills/); canonical ECC commands as prompt templates (commands/); canonical ECC engineering rules (rules/common/) injected into the system prompt; session lifecycle hook adapter; /ecc-doctor diagnostics command | Subagents, chains, approval prompts, and persistent todos require companion Pi packages and are not part of this adapter; Pi core has no MCP surface, though ECC MCP configs load verbatim through the community pi-mcp-adapter package, which ECC neither installs nor depends on | `pi install git:github.com/affaan-m/ECC`; `pi install /path/to/ECC` from a local checkout | `node tests/pi/pi-package-manifest.test.js`; `node tests/pi/pi-extension-adapter.test.js`; `npm run harness:adapters -- --check` | Pi extensions execute with full user permissions, and hooks run without a shell and resolve from the installed package rather than the user project; Keep canonical skills and commands as the single source of truth, and never generate copies under .pi/ |
| Cursor | Adapter-backed | Cursor rules; project-local skills; hook adapter; shared scripts | Cursor hook events and rule loading differ from Claude Code | `./install.sh --profile minimal --target cursor` | `node tests/lib/install-targets.test.js`; `npm run harness:audit -- --format json` | Cursor adapters must preserve existing project rules and avoid silent overwrite. |
| Gemini | Instruction-backed | Gemini project-local instructions; shared skills; rules; compatibility docs | No full ECC hook parity; ecosystem ports must document drift from upstream ECC | `./install.sh --profile minimal --target gemini` | `node tests/lib/install-targets.test.js` | Treat Gemini ports as ecosystem adapters until validated end to end inside Gemini CLI. |
| Zed | Adapter-backed | Zed project settings; flattened project rules; shared skills; commands; agents | Zed external agents and native Agent Panel permissions are not Claude hooks | `./install.sh --profile minimal --target zed` | `node tests/lib/install-targets.test.js`; `npm run harness:audit -- --format json` | Keep project settings conservative and do not copy BYOK/OpenRouter secrets into `.zed/`. |
diff --git a/manifests/install-modules.json b/manifests/install-modules.json
index c9eb0d232..8c0ea11d8 100644
--- a/manifests/install-modules.json
+++ b/manifests/install-modules.json
@@ -113,6 +113,7 @@
".cursor",
".gemini",
".opencode",
+ ".pi",
".qwen",
".zed",
"mcp-configs",
diff --git a/package.json b/package.json
index f047c6a66..55030f5f4 100644
--- a/package.json
+++ b/package.json
@@ -50,6 +50,7 @@
".hermes/",
".kimi/",
".opencode/",
+ ".pi/",
".openclaw/",
".qwen/",
".zed/",
@@ -470,6 +471,17 @@
"ajv": "8.20.0",
"sql.js": "1.14.1"
},
+ "pi": {
+ "extensions": [
+ "./.pi/extensions/index.ts"
+ ],
+ "skills": [
+ "./skills"
+ ],
+ "prompts": [
+ "./commands"
+ ]
+ },
"devDependencies": {
"@eslint/js": "9.39.2",
"@opencode-ai/plugin": "1.17.3",
diff --git a/scripts/lib/harness-adapter-compliance.js b/scripts/lib/harness-adapter-compliance.js
index 11bb363f2..e1aafd752 100644
--- a/scripts/lib/harness-adapter-compliance.js
+++ b/scripts/lib/harness-adapter-compliance.js
@@ -122,6 +122,40 @@ const ADAPTER_RECORDS = Object.freeze([
'scripts/build-opencode.js',
],
},
+ {
+ id: 'pi',
+ harness: 'Pi',
+ state: 'Adapter-backed',
+ supported_assets: [
+ 'Pi package manifest',
+ 'canonical ECC skills (skills/)',
+ 'canonical ECC commands as prompt templates (commands/)',
+ 'canonical ECC engineering rules (rules/common/) injected into the system prompt',
+ 'session lifecycle hook adapter',
+ '/ecc-doctor diagnostics command',
+ ],
+ unsupported_surfaces: [
+ 'Subagents, chains, approval prompts, and persistent todos require companion Pi packages and are not part of this adapter',
+ 'Pi core has no MCP surface, though ECC MCP configs load verbatim through the community pi-mcp-adapter package, which ECC neither installs nor depends on',
+ ],
+ install_or_onramp: ['`pi install git:github.com/affaan-m/ECC`', '`pi install /path/to/ECC` from a local checkout'],
+ verification_commands: [
+ '`node tests/pi/pi-package-manifest.test.js`',
+ '`node tests/pi/pi-extension-adapter.test.js`',
+ '`npm run harness:adapters -- --check`',
+ ],
+ risk_notes: [
+ 'Pi extensions execute with full user permissions, and hooks run without a shell and resolve from the installed package rather than the user project',
+ 'Keep canonical skills and commands as the single source of truth, and never generate copies under .pi/',
+ ],
+ last_verified_at: '2026-08-10',
+ owner: 'ECC maintainers',
+ source_docs: [
+ '.pi/extensions/index.ts',
+ '.pi/README.md',
+ 'package.json',
+ ],
+ },
{
id: 'cursor',
harness: 'Cursor',
diff --git a/tests/pi/pi-extension-adapter.test.js b/tests/pi/pi-extension-adapter.test.js
new file mode 100644
index 000000000..aff53a8c8
--- /dev/null
+++ b/tests/pi/pi-extension-adapter.test.js
@@ -0,0 +1,1352 @@
+/**
+ * Tests for the ECC <-> Pi coding agent thin adapter (.pi/extensions/index.ts).
+ *
+ * This adapter was rejected once already (PR #2352) for four defects:
+ * (a) resolving hook scripts from `process.cwd()` instead of the installed
+ * ECC package root, which breaks global installs;
+ * (b) running hooks through an interpolated shell string
+ * (`exec(\`node ${scriptPath}\`)`), which breaks on paths with spaces
+ * and is a shell-injection risk;
+ * (c) using the undocumented `app.events` bus instead of the documented
+ * `pi.on(...)` lifecycle API;
+ * (d) shipping with no compatibility tests at all.
+ *
+ * Group 1 below reads `.pi/extensions/index.ts` as text and asserts the
+ * source contract that keeps those defects from coming back. The file is
+ * TypeScript loaded by Pi through jiti at runtime, so it cannot be
+ * `require()`d or `import()`ed from a plain Node test — source inspection is
+ * the only option available without adding a build step or a new dependency.
+ *
+ * Group 2 exercises ECC's real hook runner (`scripts/hooks/run-with-flags.js`)
+ * with the exact argv/env shape the adapter builds, so the fix is proven by
+ * behavior, not just by grep.
+ *
+ * Group 3 covers three fixes a code review added on top of the above: EPIPE
+ * isolation on `child.stdin`, clearing stale `pendingContext` at session
+ * start, and reading companion-package installs from Pi's own settings files
+ * instead of `require.resolve`. Each fix gets a source-text assertion (so a
+ * regression is caught even if the behavioral mirror still passes) plus a
+ * real behavioral test wherever the fix is about runtime behavior rather
+ * than pure control flow.
+ *
+ * Group 4 covers the adapter's injection of ECC's canonical engineering rules
+ * into Pi's system prompt (`PORTABLE_RULE_FILES`, `loadPortableRules`,
+ * `isDisabledByEnv`, and the expanded `before_agent_start` handler). The core
+ * constraint under test is that rules are read at RUNTIME from the canonical
+ * `rules/common/` directory of the installed package — nothing is copied or
+ * generated into `.pi/`. Each test pairs a source-text assertion (so a
+ * regression in the real adapter fails even if a behavioral mirror still
+ * passes) with either a real-filesystem check against this repo's actual
+ * `rules/common/` files or a hand-copied mirror of the adapter's own logic.
+ */
+
+const assert = require("assert")
+const fs = require("fs")
+const os = require("os")
+const path = require("path")
+const { spawnSync, execFile } = require("child_process")
+
+async function runTest(name, fn) {
+ try {
+ await fn()
+ console.log(` ✓ ${name}`)
+ return true
+ } catch (error) {
+ console.log(` ✗ ${name}`)
+ console.error(` ${error.message}`)
+ return false
+ }
+}
+
+/**
+ * Strips `/* ... *\/` and `// ...` comments so the "never resolves from
+ * process.cwd()" check tests real behavior, not a doc comment. The adapter's
+ * own header comment explains the anti-pattern by naming it in backticks
+ * (`"never `process.cwd()`, so a global pi install works..."`), which is
+ * correct documentation, not a regression — the check must look past it.
+ */
+function stripComments(source) {
+ return source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "")
+}
+
+/**
+ * Mirrors the adapter's own hook invocation (`runEccHook` in
+ * .pi/extensions/index.ts): same binary (`process.execPath`), same argv
+ * shape, same stdin-JSON payload, same env keys. No shell is used anywhere.
+ */
+function runHookRunner(eccRoot, hookId, relScript, profiles, payload, extraEnv, cwd) {
+ const runner = path.join(eccRoot, "scripts", "hooks", "run-with-flags.js")
+ return spawnSync(process.execPath, [runner, hookId, relScript, profiles], {
+ input: JSON.stringify(payload),
+ encoding: "utf8",
+ cwd: cwd || eccRoot,
+ timeout: 30000,
+ env: { ...process.env, CLAUDE_PLUGIN_ROOT: eccRoot, ECC_PLUGIN_ROOT: eccRoot, ...extraEnv },
+ })
+}
+
+/**
+ * Builds a minimal, standalone ECC package skeleton under a fresh temp
+ * directory so tests 8/9 can simulate a global install without touching the
+ * real repo. Only the files `run-with-flags.js` -> `session-end-marker.js`
+ * actually `require()` at runtime are copied.
+ */
+function buildEccSkeleton(repoRoot) {
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), "ecc pi test-"))
+ const hooksDir = path.join(root, "scripts", "hooks")
+ fs.mkdirSync(hooksDir, { recursive: true })
+
+ for (const name of ["run-with-flags.js", "session-end-marker.js", "pretooluse-visible-output.js"]) {
+ fs.cpSync(path.join(repoRoot, "scripts", "hooks", name), path.join(hooksDir, name))
+ }
+ fs.cpSync(path.join(repoRoot, "scripts", "lib"), path.join(root, "scripts", "lib"), { recursive: true })
+
+ return root
+}
+
+/**
+ * Mirror of the adapter's `extractAdditionalContext` (same file, same six
+ * lines of logic) so the parsing contract can be exercised directly without
+ * importing the TypeScript source. This copy proves the *behavior* below is
+ * correct, but a copy cannot detect the real adapter's guards drifting out
+ * from under it. The source-text assertions in the "additionalContext
+ * extraction tolerates non-JSON hook passthrough" test below read the real
+ * `extractAdditionalContext` out of `.pi/extensions/index.ts` and pin its
+ * guards directly, so that kind of drift fails the test instead of passing
+ * silently against this mirror.
+ */
+function extractAdditionalContext(stdout) {
+ const trimmed = stdout.trim()
+ if (!trimmed.startsWith("{")) {
+ return undefined
+ }
+ try {
+ const parsed = JSON.parse(trimmed)
+ const context = parsed.hookSpecificOutput && parsed.hookSpecificOutput.additionalContext
+ return typeof context === "string" && context.trim() ? context : undefined
+ } catch {
+ return undefined
+ }
+}
+
+/**
+ * Mirror of the adapter's `normalizePiPackageName` (same file, same handful of
+ * lines) so the object-form unwrapping and the trailing-@version stripping can
+ * be exercised directly without importing the TypeScript source. This copy
+ * proves the *behavior* below is correct, but a copy cannot detect the real
+ * adapter's guards drifting out from under it. The source-text assertions in
+ * the "companion package detection reads Pi's package list" test below read
+ * the real `normalizePiPackageName` text out of `.pi/extensions/index.ts` and
+ * pin its actual guards directly, so that kind of drift fails the test instead
+ * of passing silently against this mirror.
+ */
+function normalizePiPackageName(entry) {
+ const source = entry && typeof entry === "object" ? entry.source : entry
+ if (typeof source !== "string" || !source.startsWith("npm:")) {
+ return undefined
+ }
+ const spec = source.slice("npm:".length)
+ // Strip a trailing @version without breaking the leading @ of a scoped name.
+ const versionAt = spec.lastIndexOf("@")
+ return versionAt > 0 ? spec.slice(0, versionAt) : spec
+}
+
+/**
+ * Mirror of the per-file body of the adapter's `listInstalledPiPackages`
+ * (same file, same read-parse-normalize-collect loop), applied to a single
+ * settings file so the "npm entries only, missing/malformed settings degrade
+ * to empty" contract can be exercised against a real temp file without
+ * importing the TypeScript source or touching a real `~/.pi/agent`
+ * directory. This copy proves the *behavior* below is correct, but a copy
+ * cannot detect the real adapter's guards drifting out from under it. The
+ * source-text assertions in the "companion package detection reads Pi's
+ * package list" test above read the real `listInstalledPiPackages` /
+ * `normalizePiPackageName` text out of `.pi/extensions/index.ts` and pin its
+ * actual guards directly, so that kind of drift fails the test instead of
+ * passing silently against this mirror.
+ */
+function readInstalledPackageNames(settingsFile) {
+ const names = new Set()
+ try {
+ const parsed = JSON.parse(fs.readFileSync(settingsFile, "utf8"))
+ if (!Array.isArray(parsed.packages)) {
+ return names
+ }
+ for (const entry of parsed.packages) {
+ const name = normalizePiPackageName(entry)
+ if (name) {
+ names.add(name)
+ }
+ }
+ } catch {
+ // Missing or unreadable settings are simply "nothing installed here".
+ }
+ return names
+}
+
+/**
+ * Parses the `PORTABLE_RULE_FILES` array literal out of `.pi/extensions/index.ts`
+ * by text, so the real-filesystem-existence test and the `loadPortableRules`
+ * behavioral mirror below follow the constant instead of hardcoding the file
+ * list and silently drifting from it.
+ */
+function parsePortableRuleFiles(source) {
+ const constStart = source.indexOf("const PORTABLE_RULE_FILES")
+ if (constStart === -1) {
+ return []
+ }
+ const constEnd = source.indexOf("]", constStart)
+ if (constEnd === -1) {
+ return []
+ }
+ const constBody = source.slice(constStart, constEnd + 1)
+ return Array.from(constBody.matchAll(/["'`]([\w.-]+\.md)["'`]/g)).map(match => match[1])
+}
+
+/**
+ * Parses the numeric value of `MAX_RULES_BYTES` (e.g. `32 * 1024`) out of
+ * `.pi/extensions/index.ts`, so the cap assertion in the `loadPortableRules`
+ * behavioral mirror below follows the real constant instead of a hardcoded
+ * number. The captured expression is validated against a digits/operators
+ * whitelist before evaluation, so this never executes arbitrary source text.
+ */
+function parseMaxRulesBytes(source) {
+ const match = source.match(/const\s+MAX_RULES_BYTES\s*=\s*([0-9_ \t*/+-]+)/)
+ if (!match) {
+ return undefined
+ }
+ const expression = match[1].trim()
+ if (!expression || !/^[0-9_ \t*+]+$/.test(expression)) {
+ return undefined
+ }
+
+ // Evaluate sums of products directly instead of through Function(): the
+ // constant is only ever a literal like `32 * 1024`, and a test helper has no
+ // business compiling code at runtime.
+ const total = expression
+ .replace(/_/g, "")
+ .split("+")
+ .reduce((sum, term) => {
+ const product = term.split("*").reduce((acc, factor) => acc * Number(factor.trim()), 1)
+ return sum + product
+ }, 0)
+
+ return Number.isFinite(total) ? total : undefined
+}
+
+/**
+ * Mirror of the adapter's `loadPortableRules` (same file, same
+ * read-trim-skip-cap-join loop over `rules/common/<file>`, same
+ * `"\n\n---\n\n"` join). Deliberately omits the `ECC_PI_RULES` disable check
+ * and the `cachedRules` memoization, which are exercised separately (the
+ * disable check via `isDisabledByEnv` below; memoization is pure control
+ * flow with no behavior to mirror). This copy proves the *behavior* below is
+ * correct, but a copy cannot detect the real adapter's guards drifting out
+ * from under it. The source-text assertions in the "PORTABLE_RULE_FILES ..."
+ * and "engineering rules are read from rules/common ..." tests below read the
+ * real constant, the real `rules/common` path, and the real `MAX_RULES_BYTES`
+ * value out of `.pi/extensions/index.ts` and pin them directly, so that kind
+ * of drift fails those tests instead of passing silently against this mirror.
+ */
+function loadPortableRulesMirror(rootDir, ruleFiles, maxBytes) {
+ const sections = []
+ let total = 0
+ for (const file of ruleFiles) {
+ let text
+ try {
+ text = fs.readFileSync(path.join(rootDir, "rules", "common", file), "utf8").trim()
+ } catch {
+ continue
+ }
+ if (!text) {
+ continue
+ }
+ if (total + text.length > maxBytes) {
+ break
+ }
+ total += text.length
+ sections.push(text)
+ }
+ return sections.length > 0 ? sections.join("\n\n---\n\n") : null
+}
+
+/**
+ * Mirror of the adapter's `isDisabledByEnv` (same `DISABLED_VALUES` set, same
+ * trim + lowercase normalization). This copy proves the *behavior* below is
+ * correct, but a copy cannot detect the real adapter's guard drifting out
+ * from under it. The source-text assertion in the "isDisabledByEnv ..." test
+ * below reads the real function and the real `ECC_PI_RULES` env var name out
+ * of `.pi/extensions/index.ts` and pins them directly.
+ */
+const DISABLED_VALUES_MIRROR = new Set(["0", "false", "off", "none", "disabled"])
+function isDisabledByEnvMirror(value) {
+ return typeof value === "string" && DISABLED_VALUES_MIRROR.has(value.trim().toLowerCase())
+}
+
+async function main() {
+ console.log("\n=== Testing .pi/extensions/index.ts (Pi thin adapter) ===\n")
+
+ let passed = 0
+ let failed = 0
+
+ const repoRoot = path.join(__dirname, "..", "..")
+ const extensionPath = path.join(repoRoot, ".pi", "extensions", "index.ts")
+ const extensionSource = fs.readFileSync(extensionPath, "utf8")
+
+ const tests = [
+ // ---- Group 1: source contract -------------------------------------
+
+ ["resolves the ECC package root from __dirname, never from process.cwd()", () => {
+ assert.ok(
+ extensionSource.includes("path.resolve(__dirname"),
+ "expected the adapter to derive its package root with path.resolve(__dirname, ...); " +
+ "resolving from __dirname is what makes a globally installed ECC find its own hooks " +
+ "regardless of which project the user opened Pi in"
+ )
+
+ const withoutComments = stripComments(extensionSource)
+ assert.ok(
+ !withoutComments.includes("process.cwd()"),
+ "found process.cwd() used as executable code in .pi/extensions/index.ts; " +
+ "resolving hook scripts from the working directory breaks global installs " +
+ "because it looks for ECC's hooks inside the user's project instead of the " +
+ "installed ECC package (this is the exact defect PR #2352 was rejected for)"
+ )
+ }],
+
+ ["executes hooks via execFile with no shell, so paths with spaces or metacharacters are safe", () => {
+ assert.ok(
+ extensionSource.includes("execFile("),
+ "expected the adapter to invoke hooks via child_process.execFile(...)"
+ )
+ assert.ok(
+ extensionSource.includes("process.execPath"),
+ "expected hooks to be spawned with process.execPath, not a hardcoded 'node' string"
+ )
+
+ const shellExecPattern = /(?<!execFile)\bexec\s*\(/
+ assert.ok(
+ !shellExecPattern.test(extensionSource),
+ "found a shell-invoking exec(...) call in .pi/extensions/index.ts distinct from " +
+ "execFile(...); running hooks through an interpolated shell string " +
+ "(exec(`node ${scriptPath}`)) breaks on paths containing spaces and is a " +
+ "shell-injection risk (the exact defect PR #2352 was rejected for)"
+ )
+ assert.ok(
+ !extensionSource.includes("execSync("),
+ "found execSync(...) in .pi/extensions/index.ts; execSync runs through a shell " +
+ "by default and reintroduces the same path-with-spaces / injection risk"
+ )
+ assert.ok(
+ !extensionSource.includes("shell: true"),
+ "found `shell: true` in .pi/extensions/index.ts; opting into a shell reintroduces " +
+ "the path-with-spaces / injection risk execFile(...) with no shell was meant to avoid"
+ )
+ }],
+
+ ["registers Pi's documented pi.on(...) lifecycle, not the undocumented app.events bus", () => {
+ assert.ok(
+ extensionSource.includes(`pi.on("session_start"`),
+ "expected the adapter to register a session_start handler via pi.on(...)"
+ )
+ assert.ok(
+ extensionSource.includes(`pi.on("session_shutdown"`),
+ "expected the adapter to register a session_shutdown handler via pi.on(...)"
+ )
+ assert.ok(
+ extensionSource.includes(`pi.on("before_agent_start"`),
+ "expected the adapter to register a before_agent_start handler via pi.on(...)"
+ )
+ assert.ok(
+ !extensionSource.includes("app.events"),
+ "found app.events in .pi/extensions/index.ts; app.events is an undocumented " +
+ "event-bus API that is not part of Pi's supported extension contract and can " +
+ "change or disappear without notice"
+ )
+ assert.ok(
+ !extensionSource.includes(".events.on("),
+ "found a .events.on(...) subscription in .pi/extensions/index.ts; subscribing " +
+ "through an undocumented event bus instead of the documented pi.on(...) " +
+ "lifecycle is not part of Pi's supported extension contract"
+ )
+ }],
+
+ ["registers the ecc-doctor diagnostics command", () => {
+ assert.ok(
+ extensionSource.includes(`registerCommand("ecc-doctor"`),
+ "expected the adapter to register an 'ecc-doctor' command via pi.registerCommand(...) " +
+ "so users have an install-diagnostics entry point"
+ )
+ }],
+
+ ["bounds hook execution with a timeout and a maxBuffer", () => {
+ assert.ok(
+ extensionSource.includes("timeout"),
+ "expected the execFile(...) call options to include a timeout; an unbounded hook " +
+ "process can hang the Pi session forever on a stuck or misbehaving hook"
+ )
+ assert.ok(
+ extensionSource.includes("maxBuffer"),
+ "expected the execFile(...) call options to include a maxBuffer; without it a " +
+ "runaway hook writing unbounded stdout can crash the adapter process"
+ )
+ }],
+
+ ["exports a default extension factory function", () => {
+ assert.ok(
+ extensionSource.includes("export default function"),
+ "expected .pi/extensions/index.ts to `export default function`, matching the " +
+ "shape Pi's extension loader expects"
+ )
+ }],
+
+ ["propagates the ECC package root to hooks via CLAUDE_PLUGIN_ROOT and ECC_PLUGIN_ROOT", () => {
+ assert.ok(
+ extensionSource.includes("CLAUDE_PLUGIN_ROOT"),
+ "expected the adapter to set CLAUDE_PLUGIN_ROOT in the hook environment; ECC's " +
+ "shared hook scripts read this to locate the package root"
+ )
+ assert.ok(
+ extensionSource.includes("ECC_PLUGIN_ROOT"),
+ "expected the adapter to set ECC_PLUGIN_ROOT in the hook environment; this is " +
+ "the ECC-specific fallback the same hook scripts also read"
+ )
+ }],
+
+ // ---- Group 2: real hook-runner behavior ---------------------------
+
+ ["GLOBAL INSTALL + SPACE IN PATH: hook execution succeeds from a package root whose path contains a space", () => {
+ const skeletonRoot = buildEccSkeleton(repoRoot)
+ try {
+ assert.ok(
+ skeletonRoot.includes(" "),
+ "test setup bug: the temp skeleton directory must contain a space to reproduce " +
+ "a global-install path (e.g. 'Application Support') — got: " + skeletonRoot
+ )
+
+ const result = runHookRunner(
+ skeletonRoot,
+ "session:end:marker",
+ "scripts/hooks/session-end-marker.js",
+ "minimal,standard,strict",
+ { hook_event_name: "SessionEnd", reason: "quit", cwd: skeletonRoot, session_id: "pi-adapter-test" }
+ )
+
+ assert.strictEqual(
+ result.error,
+ undefined,
+ "hook runner failed to spawn from a package root containing a space " +
+ `(${skeletonRoot}); this is exactly the shell-interpolation regression ` +
+ `PR #2352 was rejected for (error: ${result.error && result.error.message})`
+ )
+ assert.strictEqual(
+ result.status,
+ 0,
+ "hook runner exited non-zero when invoked from a package root containing a " +
+ `space (${skeletonRoot}); a path with a space broke hook execution ` +
+ `(stderr: ${result.stderr})`
+ )
+ } finally {
+ fs.rmSync(skeletonRoot, { recursive: true, force: true })
+ }
+ }],
+
+ ["hook resolution is package-relative, not cwd-relative: still succeeds when cwd points elsewhere", () => {
+ const skeletonRoot = buildEccSkeleton(repoRoot)
+ try {
+ const result = runHookRunner(
+ skeletonRoot,
+ "session:end:marker",
+ "scripts/hooks/session-end-marker.js",
+ "minimal,standard,strict",
+ { hook_event_name: "SessionEnd", reason: "quit", cwd: os.tmpdir(), session_id: "pi-adapter-test" },
+ {},
+ os.tmpdir()
+ )
+
+ assert.strictEqual(
+ result.error,
+ undefined,
+ "hook runner failed to spawn when cwd pointed away from the ECC package root; " +
+ "a globally installed ECC must resolve its own hooks regardless of which " +
+ `project directory the user is in (error: ${result.error && result.error.message})`
+ )
+ assert.strictEqual(
+ result.status,
+ 0,
+ "hook runner exited non-zero when cwd pointed away from the ECC package root " +
+ `(cwd=${os.tmpdir()}, CLAUDE_PLUGIN_ROOT=${skeletonRoot}); this means hook ` +
+ "resolution is leaking cwd-dependence instead of being package-relative " +
+ `(stderr: ${result.stderr})`
+ )
+ } finally {
+ fs.rmSync(skeletonRoot, { recursive: true, force: true })
+ }
+ }],
+
+ ["profile gating is honored: a disabled hook and a restrictive profile both degrade cleanly", () => {
+ // Uses the same isolated skeleton as tests 8/9 (not repoRoot) so that
+ // session-end-marker.js never executes against the real checkout: a
+ // real run can leave marker artifacts behind and would make this
+ // test's outcome depend on whatever state the repo happens to be in.
+ const skeletonRoot = buildEccSkeleton(repoRoot)
+ try {
+ const disabledResult = runHookRunner(
+ skeletonRoot,
+ "session:end:marker",
+ "scripts/hooks/session-end-marker.js",
+ "minimal,standard,strict",
+ { hook_event_name: "SessionEnd", reason: "quit", cwd: skeletonRoot, session_id: "pi-adapter-test" },
+ { ECC_DISABLED_HOOKS: "session:end:marker" }
+ )
+
+ assert.strictEqual(
+ disabledResult.error,
+ undefined,
+ "hook runner failed to spawn when session:end:marker was listed in " +
+ `ECC_DISABLED_HOOKS (error: ${disabledResult.error && disabledResult.error.message})`
+ )
+ assert.strictEqual(
+ disabledResult.status,
+ 0,
+ "hook runner exited non-zero for a hook disabled via ECC_DISABLED_HOOKS; a " +
+ "disabled hook must be skipped cleanly rather than crashing the Pi session " +
+ `(stderr: ${disabledResult.stderr})`
+ )
+
+ const minimalResult = runHookRunner(
+ skeletonRoot,
+ "session:end:marker",
+ "scripts/hooks/session-end-marker.js",
+ "minimal,standard,strict",
+ { hook_event_name: "SessionEnd", reason: "quit", cwd: skeletonRoot, session_id: "pi-adapter-test" },
+ { ECC_HOOK_PROFILE: "minimal" }
+ )
+
+ assert.strictEqual(
+ minimalResult.error,
+ undefined,
+ "hook runner failed to spawn under ECC_HOOK_PROFILE=minimal " +
+ `(error: ${minimalResult.error && minimalResult.error.message})`
+ )
+ assert.strictEqual(
+ minimalResult.status,
+ 0,
+ "hook runner exited non-zero under ECC_HOOK_PROFILE=minimal; hook-profile " +
+ `gating must degrade cleanly, not crash the session (stderr: ${minimalResult.stderr})`
+ )
+ } finally {
+ fs.rmSync(skeletonRoot, { recursive: true, force: true })
+ }
+ }],
+
+ ["additionalContext extraction tolerates non-JSON hook passthrough", () => {
+ // ---- Behavioral assertions on the LOCAL MIRROR --------------------
+ // extractAdditionalContext (defined above) is a hand-copied mirror of
+ // the real function in .pi/extensions/index.ts, kept because that file
+ // is TypeScript loaded via jiti and cannot be require()'d from a plain
+ // Node test. These assertions prove the mirror's behavior; they do NOT
+ // by themselves prove the shipped adapter still behaves this way. The
+ // source-text assertions further below read the real function's text
+ // out of .pi/extensions/index.ts and pin its actual guards, so that a
+ // real adapter regression fails here even though the mirror (and the
+ // assertions run against it) would keep passing unchanged.
+ assert.strictEqual(
+ extractAdditionalContext('{"hookSpecificOutput":{"additionalContext":"hello"}}'),
+ "hello",
+ "expected additionalContext to be extracted from a well-formed hook envelope"
+ )
+ assert.strictEqual(
+ extractAdditionalContext("plain non-JSON stdout from a disabled hook"),
+ undefined,
+ "expected non-JSON stdout (the pass-through case for a disabled hook) to yield " +
+ "undefined instead of throwing or crashing the session_start handler"
+ )
+ assert.strictEqual(
+ extractAdditionalContext('{"hookSpecificOutput": malformed'),
+ undefined,
+ "expected malformed JSON to yield undefined instead of throwing"
+ )
+ assert.strictEqual(
+ extractAdditionalContext('{"unrelated":true}'),
+ undefined,
+ "expected valid JSON with no hookSpecificOutput.additionalContext field to yield undefined"
+ )
+ assert.strictEqual(
+ extractAdditionalContext('{"hookSpecificOutput":{"additionalContext":""}}'),
+ undefined,
+ "expected an empty-string additionalContext to yield undefined rather than an " +
+ "empty <ecc-session-context> block being spliced into the system prompt"
+ )
+
+ // ---- Source-text assertions on the REAL adapter -------------------
+ // Isolate the real extractAdditionalContext function's text out of
+ // .pi/extensions/index.ts (up to the next top-level function
+ // declaration) and pin its actual guards. If the adapter's real
+ // startsWith("{") check, try/catch, hookSpecificOutput?.additionalContext
+ // read, or non-empty-string requirement ever changes, these fail
+ // regardless of what the mirror above still does.
+ const functionStart = extensionSource.indexOf("function extractAdditionalContext")
+ assert.ok(
+ functionStart !== -1,
+ "expected .pi/extensions/index.ts to define a function named extractAdditionalContext"
+ )
+ const nextFunctionStart = extensionSource.indexOf("\nfunction ", functionStart + 1)
+ const extractContextSource =
+ nextFunctionStart === -1
+ ? extensionSource.slice(functionStart)
+ : extensionSource.slice(functionStart, nextFunctionStart)
+
+ assert.ok(
+ /if\s*\(\s*!\s*trimmed\.startsWith\(\s*["'`]\{["'`]\s*\)\s*\)\s*\{\s*return undefined/.test(
+ extractContextSource
+ ),
+ "expected extractAdditionalContext in .pi/extensions/index.ts to early-return " +
+ "undefined unless the trimmed stdout starts with '{'; this is what makes " +
+ "non-JSON stdout from a disabled hook a safe pass-through instead of a crash"
+ )
+ assert.ok(
+ /try\s*\{[\s\S]*?JSON\.parse\(/.test(extractContextSource),
+ "expected extractAdditionalContext in .pi/extensions/index.ts to parse the " +
+ "trimmed stdout via JSON.parse(...) inside a try block"
+ )
+ assert.ok(
+ /catch[^{]*\{\s*return undefined/.test(extractContextSource),
+ "expected extractAdditionalContext in .pi/extensions/index.ts to catch a " +
+ "JSON.parse failure and return undefined instead of throwing"
+ )
+ assert.ok(
+ /hookSpecificOutput\?\.\s*additionalContext/.test(extractContextSource),
+ "expected extractAdditionalContext in .pi/extensions/index.ts to read " +
+ "hookSpecificOutput?.additionalContext from the parsed envelope"
+ )
+ assert.ok(
+ /typeof\s+context\s*===\s*["'`]string["'`]\s*&&\s*context\.trim\(\)/.test(extractContextSource),
+ "expected extractAdditionalContext in .pi/extensions/index.ts to require a " +
+ 'non-empty string (typeof context === "string" && context.trim()) before ' +
+ "returning it, rejecting an empty-string additionalContext"
+ )
+ }],
+
+ // ---- Group 3: code-review fixes -----------------------------------
+
+ ["EPIPE isolation (source contract): child.stdin has an error listener, and the catch around child.stdin?.end(...) resolves rather than rethrows", () => {
+ const withoutComments = stripComments(extensionSource)
+ assert.ok(
+ withoutComments.includes('child.stdin?.on("error"'),
+ "expected runEccHook in .pi/extensions/index.ts to register an error listener on " +
+ 'child.stdin via child.stdin?.on("error", ...) as real code, not just described ' +
+ "in a comment; stdin.end() writes asynchronously, so a hook that exits before " +
+ "reading its payload raises an EPIPE `error` event that a try/catch around " +
+ "child.stdin?.end(...) cannot see, and an unhandled `error` event on a stream " +
+ "crashes the whole Pi session"
+ )
+
+ const runEccHookStart = extensionSource.indexOf("function runEccHook")
+ assert.ok(
+ runEccHookStart !== -1,
+ "expected .pi/extensions/index.ts to define a function named runEccHook"
+ )
+ const nextFunctionStart = extensionSource.indexOf("\nfunction ", runEccHookStart + 1)
+ const runEccHookSource =
+ nextFunctionStart === -1
+ ? extensionSource.slice(runEccHookStart)
+ : extensionSource.slice(runEccHookStart, nextFunctionStart)
+
+ const catchMatch = runEccHookSource.match(
+ /try\s*\{\s*child\.stdin\?\.end\([\s\S]*?\)\)\s*\}\s*catch\s*\(error\)\s*\{([\s\S]*?)\n\s*\}\n/
+ )
+ assert.ok(
+ catchMatch,
+ "expected runEccHook in .pi/extensions/index.ts to wrap child.stdin?.end(...) in " +
+ "a try { ... } catch (error) { ... } block"
+ )
+ const catchBody = catchMatch[1]
+ assert.ok(
+ /resolve\(/.test(catchBody),
+ "expected the catch around child.stdin?.end(...) in .pi/extensions/index.ts to " +
+ "call resolve(...); if it rethrows instead, a hook payload write failure " +
+ "escapes the Promise executor as an unhandled exception instead of degrading " +
+ "to a warning"
+ )
+ assert.ok(
+ !/\bthrow\b/.test(catchBody),
+ "found a rethrow inside the catch around child.stdin?.end(...) in " +
+ ".pi/extensions/index.ts; this is the exact EPIPE-crashes-the-session " +
+ "regression the surrounding error handling exists to prevent"
+ )
+ }],
+
+ ["EPIPE isolation (real behavioral proof): a large stdin write to a child that exits without reading it survives as an `error` event or a clean resolution, never an uncaught exception", async () => {
+ // Mirrors the exact pattern in runEccHook: execFile + process.execPath, an
+ // `error` listener on child.stdin, and a try/catch around child.stdin.end(...).
+ // The child below exits immediately without ever reading stdin, so a payload
+ // larger than the OS pipe buffer (2MB) cannot be written synchronously and
+ // reliably reproduces the EPIPE this pattern exists to isolate.
+ const largePayload = "x".repeat(2 * 1024 * 1024)
+ const uncaughtExceptions = []
+ const onUncaughtException = error => uncaughtExceptions.push(error)
+ process.on("uncaughtException", onUncaughtException)
+
+ let outcome
+ try {
+ outcome = await new Promise((resolve, reject) => {
+ let stdinErrorSeen = false
+ let childErrorSeen = false
+ let writeThrew = false
+ // Safety net only, not a polling race: the assertions below depend on the
+ // uncaughtException listener, which fires synchronously with the offending
+ // event if it happens. This just stops the suite from hanging forever if
+ // the execFile callback never fires for an unrelated reason.
+ const safetyNet = setTimeout(
+ () => reject(new Error("execFile callback never fired within the 5.5s safety window")),
+ 5500
+ )
+
+ const child = execFile(
+ process.execPath,
+ ["-e", "process.exit(0)"],
+ { timeout: 5000, maxBuffer: 1024 * 1024 },
+ () => {
+ clearTimeout(safetyNet)
+ resolve({ stdinErrorSeen, childErrorSeen, writeThrew })
+ }
+ )
+
+ child.on("error", () => {
+ childErrorSeen = true
+ })
+
+ child.stdin.on("error", () => {
+ stdinErrorSeen = true
+ })
+
+ try {
+ child.stdin.end(largePayload)
+ } catch {
+ writeThrew = true
+ }
+ })
+ } finally {
+ process.off("uncaughtException", onUncaughtException)
+ }
+
+ assert.strictEqual(
+ uncaughtExceptions.length,
+ 0,
+ "expected writing a 2MB payload to a child that exits before reading stdin to " +
+ "never raise an uncaughtException; this is exactly the " +
+ 'EPIPE-crashes-the-Pi-session regression the child.stdin?.on("error", ...) ' +
+ "listener in runEccHook exists to prevent"
+ )
+ assert.ok(
+ outcome !== undefined,
+ "expected the execFile callback to fire and the parent process to survive " +
+ "writing to a child that never reads its stdin, instead of hanging or crashing"
+ )
+ }],
+
+ ["stale context is cleared at session_start before awaiting the hook, and again after injection in before_agent_start", () => {
+ const sessionStartIdx = extensionSource.indexOf('pi.on("session_start"')
+ assert.ok(
+ sessionStartIdx !== -1,
+ "expected .pi/extensions/index.ts to register a session_start handler via pi.on(...)"
+ )
+ const beforeAgentStartIdx = extensionSource.indexOf('pi.on("before_agent_start"', sessionStartIdx)
+ assert.ok(
+ beforeAgentStartIdx !== -1 && beforeAgentStartIdx > sessionStartIdx,
+ "expected a before_agent_start handler registered after session_start in .pi/extensions/index.ts"
+ )
+ const sessionShutdownIdx = extensionSource.indexOf('pi.on("session_shutdown"', beforeAgentStartIdx)
+ assert.ok(
+ sessionShutdownIdx !== -1 && sessionShutdownIdx > beforeAgentStartIdx,
+ "expected a session_shutdown handler registered after before_agent_start in .pi/extensions/index.ts"
+ )
+
+ const sessionStartSource = stripComments(extensionSource.slice(sessionStartIdx, beforeAgentStartIdx))
+ const clearIdx = sessionStartSource.indexOf("pendingContext = undefined")
+ const hookCallIdx = sessionStartSource.indexOf("await runEccHook(")
+ assert.ok(
+ clearIdx !== -1,
+ "expected the session_start handler in .pi/extensions/index.ts to clear " +
+ "pendingContext = undefined; without this, a new session start can replay " +
+ "context captured for a previous session"
+ )
+ assert.ok(
+ hookCallIdx !== -1,
+ "expected the session_start handler in .pi/extensions/index.ts to await runEccHook(...)"
+ )
+ assert.ok(
+ clearIdx < hookCallIdx,
+ "expected pendingContext = undefined to run BEFORE `await runEccHook(...)` in " +
+ "the session_start handler; if the clear happens after (or is skipped when " +
+ "the hook fails), a new session start begun while a previous SessionStart " +
+ "hook is still running -- or one whose hook later fails -- can replay stale " +
+ "context captured for the wrong project state"
+ )
+
+ const beforeAgentStartSource = stripComments(
+ extensionSource.slice(beforeAgentStartIdx, sessionShutdownIdx)
+ )
+ // Pin the guarantee (read the value, then clear it, then return) rather
+ // than one particular spelling of it. The handler injects the context
+ // inline inside its <ecc-session-context> block instead of copying it to
+ // a local first; both orders are equivalent in a synchronous handler.
+ const captureIdx = beforeAgentStartSource.indexOf("<ecc-session-context>")
+ const clearIdx2 = beforeAgentStartSource.indexOf("pendingContext = undefined")
+ const returnIdx = beforeAgentStartSource.indexOf("return {")
+ assert.ok(
+ captureIdx !== -1,
+ "expected the before_agent_start handler in .pi/extensions/index.ts to read " +
+ "pendingContext into an <ecc-session-context> block before clearing it"
+ )
+ assert.ok(
+ clearIdx2 !== -1,
+ "expected the before_agent_start handler in .pi/extensions/index.ts to still " +
+ "clear pendingContext = undefined after reading it for injection; without " +
+ "this, an already-injected context value would be replayed into a later agent turn"
+ )
+ assert.ok(
+ returnIdx !== -1,
+ "expected the before_agent_start handler in .pi/extensions/index.ts to return " +
+ "an object with an injected systemPrompt"
+ )
+ assert.ok(
+ captureIdx < clearIdx2,
+ "expected pendingContext to be read into the injected block BEFORE being " +
+ "cleared in before_agent_start; clearing first would lose the value before " +
+ "it can be injected into the system prompt"
+ )
+ assert.ok(
+ clearIdx2 < returnIdx,
+ "expected pendingContext = undefined to run BEFORE the return statement in " +
+ "before_agent_start; if the clear is removed or moved past the return it " +
+ "never executes, and a later agent turn would replay the same context again"
+ )
+ }],
+
+ ["companion package detection reads Pi's package list (source contract): require.resolve is gone, PI_CODING_AGENT_DIR is honored, and normalizePiPackageName's version-stripping guard is pinned", () => {
+ // require.resolve is legitimately named in the doc comment above
+ // listInstalledPiPackages to explain why it was replaced (the same
+ // "documentation, not a regression" case stripComments exists for --
+ // see its own jsdoc above). Strip comments first so this checks real
+ // code, not prose.
+ const withoutComments = stripComments(extensionSource)
+ assert.ok(
+ !withoutComments.includes("require.resolve"),
+ "found require.resolve(...) used as executable code in .pi/extensions/index.ts; " +
+ "Pi installs companion packages under its own config directory " +
+ "(~/.pi/agent/npm, overridable via PI_CODING_AGENT_DIR), which is not on " +
+ "Node's module resolution path from this file, so require.resolve reports " +
+ "every companion as missing no matter what the user actually installed -- " +
+ "this is the exact defect listInstalledPiPackages was introduced to replace"
+ )
+ assert.ok(
+ extensionSource.includes("PI_CODING_AGENT_DIR"),
+ "expected .pi/extensions/index.ts to honor the documented PI_CODING_AGENT_DIR " +
+ "override when locating Pi's config directory"
+ )
+
+ const normalizeStart = extensionSource.indexOf("function normalizePiPackageName")
+ assert.ok(
+ normalizeStart !== -1,
+ "expected .pi/extensions/index.ts to define a function named normalizePiPackageName"
+ )
+ const nextFunctionStart = extensionSource.indexOf("\nfunction ", normalizeStart + 1)
+ const normalizeSource =
+ nextFunctionStart === -1
+ ? extensionSource.slice(normalizeStart)
+ : extensionSource.slice(normalizeStart, nextFunctionStart)
+
+ assert.ok(
+ /typeof\s+entry\s*===\s*["'`]object["'`]\s*\?\s*\(entry\s+as\s*\{\s*source\?:\s*unknown\s*\}\)\.source/.test(
+ normalizeSource
+ ),
+ "expected normalizePiPackageName in .pi/extensions/index.ts to read `source` off " +
+ "an object entry before normalizing; Pi's settings accept both a bare source " +
+ 'string and an object carrying it ({ source: "npm:x", skills: [] }), and a ' +
+ "package filtered that way is just as installed as a plain one -- treating the " +
+ "object form as unrecognized makes /ecc-doctor report an installed companion as " +
+ "missing"
+ )
+ assert.ok(
+ /typeof\s+source\s*!==\s*["'`]string["'`]\s*\|\|\s*!\s*source\.startsWith\(\s*["'`]npm:["'`]\s*\)/.test(
+ normalizeSource
+ ),
+ "expected normalizePiPackageName in .pi/extensions/index.ts to return undefined " +
+ "for any source that is not a string starting with 'npm:' (git sources and " +
+ "filesystem paths carry no comparable package name)"
+ )
+ assert.ok(
+ /spec\s*=\s*source\.slice\(\s*["'`]npm:["'`]\.length\)/.test(normalizeSource),
+ 'expected normalizePiPackageName in .pi/extensions/index.ts to strip the "npm:" ' +
+ 'prefix via source.slice("npm:".length)'
+ )
+ assert.ok(
+ /versionAt\s*=\s*spec\.lastIndexOf\(\s*["'`]@["'`]\s*\)/.test(normalizeSource),
+ "expected normalizePiPackageName in .pi/extensions/index.ts to locate a " +
+ 'trailing @version with spec.lastIndexOf("@")'
+ )
+ assert.ok(
+ /versionAt\s*>\s*0\s*\?\s*spec\.slice\(0,\s*versionAt\)\s*:\s*spec/.test(normalizeSource),
+ "expected normalizePiPackageName in .pi/extensions/index.ts to only strip at " +
+ "versionAt when it is greater than 0 (versionAt > 0 ? ... : spec); a scoped " +
+ "package's leading '@' sits at index 0, so this is what keeps " +
+ "'@juicesharp/[email protected]' from being mangled into an empty name the way " +
+ 'a naive split("@")[0] would'
+ )
+ }],
+
+ ["companion package name normalization (behavioral mirror): strips a trailing version without breaking a scoped package name", () => {
+ assert.strictEqual(
+ normalizePiPackageName("npm:pi-subagents"),
+ "pi-subagents",
+ "expected a plain npm entry with no version to normalize to its bare package name"
+ )
+ assert.strictEqual(
+ normalizePiPackageName("npm:[email protected]"),
+ "pi-subagents",
+ "expected a plain npm entry with a version to have the version stripped"
+ )
+ assert.strictEqual(
+ normalizePiPackageName("npm:@juicesharp/rpiv-todo"),
+ "@juicesharp/rpiv-todo",
+ "expected a versionless scoped npm entry to normalize to its full scoped name"
+ )
+ assert.strictEqual(
+ normalizePiPackageName("npm:@juicesharp/[email protected]"),
+ "@juicesharp/rpiv-todo",
+ "expected a scoped npm entry WITH a version to strip only the trailing version " +
+ 'and keep the scope; a naive split("@")[0] gets this exact case wrong (it ' +
+ "would return an empty string because the scoped name's leading '@' is not " +
+ "the version separator)"
+ )
+ assert.strictEqual(
+ normalizePiPackageName("git:https://github.com/example/pi-plugin.git"),
+ undefined,
+ "expected a git source to normalize to undefined; it carries no comparable npm package name"
+ )
+ assert.strictEqual(
+ normalizePiPackageName("/Users/example/local-pi-plugin"),
+ undefined,
+ "expected a filesystem path entry to normalize to undefined"
+ )
+ assert.strictEqual(
+ normalizePiPackageName(42),
+ undefined,
+ "expected a non-string entry to normalize to undefined instead of throwing"
+ )
+ assert.strictEqual(
+ normalizePiPackageName(""),
+ undefined,
+ "expected an empty entry to normalize to undefined"
+ )
+ }],
+
+ ["companion package name normalization (behavioral mirror): an object entry with resource filters resolves to the same name as the bare source string", () => {
+ assert.strictEqual(
+ normalizePiPackageName({ source: "npm:pi-subagents", skills: [] }),
+ "pi-subagents",
+ "expected the object form Pi documents for filtered packages to resolve to the " +
+ "same name as the bare string; a user who narrows which resources pi-subagents " +
+ "contributes still has it installed, and /ecc-doctor exists to report exactly that"
+ )
+ assert.strictEqual(
+ normalizePiPackageName({ source: "npm:@juicesharp/[email protected]", prompts: ["prompts/review.md"] }),
+ "@juicesharp/rpiv-todo",
+ "expected an object entry to go through the same version-stripping path as a " +
+ "string entry, scope intact"
+ )
+ assert.strictEqual(
+ normalizePiPackageName({ source: "git:github.com/example/pi-plugin@v1" }),
+ undefined,
+ "expected an object entry wrapping a git source to stay unrecognized; the source " +
+ "type decides, not the entry shape"
+ )
+ assert.strictEqual(
+ normalizePiPackageName({ extensions: ["extensions/*.ts"] }),
+ undefined,
+ "expected an object entry with no source field to normalize to undefined instead " +
+ "of throwing"
+ )
+ assert.strictEqual(
+ normalizePiPackageName({ source: 42 }),
+ undefined,
+ "expected a non-string source to normalize to undefined instead of throwing"
+ )
+ assert.strictEqual(
+ normalizePiPackageName(null),
+ undefined,
+ "expected a null entry to normalize to undefined; typeof null is \"object\", so " +
+ "this is the case an unguarded object branch would throw on"
+ )
+ }],
+
+ ["companion package detection reads Pi's settings.json (real filesystem): npm entries are recognized, path/git entries are ignored, missing/malformed settings degrade to an empty set", () => {
+ const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-config-dir-test-"))
+ try {
+ const settingsFile = path.join(tmpDir, "settings.json")
+ fs.writeFileSync(
+ settingsFile,
+ JSON.stringify({
+ packages: [
+ "npm:@juicesharp/[email protected]",
+ "/Users/example/local-pi-plugin",
+ "git:https://github.com/example/pi-plugin.git",
+ ],
+ })
+ )
+
+ const installed = readInstalledPackageNames(settingsFile)
+ assert.strictEqual(
+ installed.size,
+ 2,
+ "expected only the two npm: entries to be recognized out of a mixed packages " +
+ `list (got: ${[...installed].join(", ")})`
+ )
+ assert.ok(
+ installed.has("pi-subagents"),
+ "expected the plain npm entry with a version to be recognized as pi-subagents"
+ )
+ assert.ok(
+ installed.has("@juicesharp/rpiv-todo"),
+ "expected the scoped npm entry with a version to be recognized as @juicesharp/rpiv-todo"
+ )
+ assert.ok(
+ !installed.has("/Users/example/local-pi-plugin"),
+ "expected the filesystem path entry to be ignored, not reported as an installed package"
+ )
+ assert.ok(
+ ![...installed].some(name => name.startsWith("git:")),
+ "expected the git: source entry to be ignored, not reported as an installed package"
+ )
+
+ const missingFile = path.join(tmpDir, "does-not-exist.json")
+ assert.deepStrictEqual(
+ readInstalledPackageNames(missingFile),
+ new Set(),
+ "expected a missing settings.json to yield an empty set instead of throwing"
+ )
+
+ const malformedFile = path.join(tmpDir, "malformed.json")
+ fs.writeFileSync(malformedFile, "{ this is not valid json")
+ assert.deepStrictEqual(
+ readInstalledPackageNames(malformedFile),
+ new Set(),
+ "expected a malformed settings.json to yield an empty set instead of throwing"
+ )
+ } finally {
+ fs.rmSync(tmpDir, { recursive: true, force: true })
+ }
+ }],
+
+ // ---- Group 4: engineering-rules injection -------------------------
+
+ ["PORTABLE_RULE_FILES lists exactly ECC's 7 Pi-portable rule files and excludes the 3 Claude-Code-only ones", () => {
+ const ruleFiles = parsePortableRuleFiles(extensionSource)
+ assert.ok(
+ ruleFiles.length > 0,
+ "expected to find and parse a PORTABLE_RULE_FILES array literal in .pi/extensions/index.ts"
+ )
+
+ assert.deepStrictEqual(
+ ruleFiles,
+ [
+ "coding-style.md",
+ "testing.md",
+ "security.md",
+ "git-workflow.md",
+ "patterns.md",
+ "development-workflow.md",
+ "code-review.md",
+ ],
+ "expected PORTABLE_RULE_FILES in .pi/extensions/index.ts to contain exactly these " +
+ `7 files (got: ${ruleFiles.join(", ")}); a drift here silently changes which ECC ` +
+ "engineering rules get injected into Pi's system prompt"
+ )
+
+ for (const excluded of ["agents.md", "hooks.md", "performance.md"]) {
+ assert.ok(
+ !ruleFiles.includes(excluded),
+ `found ${excluded} in PORTABLE_RULE_FILES in .pi/extensions/index.ts; ${excluded} ` +
+ "describes Claude Code primitives Pi does not have (Task/TodoWrite delegation, " +
+ "Claude Code hook event types, or thinking-budget toggles like Option+T), so " +
+ "injecting it into Pi's system prompt would instruct the model to use tools " +
+ "and behaviors that do not exist in Pi"
+ )
+ }
+ }],
+
+ ["engineering rules are read from rules/common/ joined onto the package root at runtime, and nothing is copied into .pi/", () => {
+ const withoutComments = stripComments(extensionSource)
+ assert.ok(
+ /path\.join\(\s*ECC_ROOT\s*,\s*["'`]rules["'`]\s*,\s*["'`]common["'`]/.test(withoutComments),
+ "expected .pi/extensions/index.ts to build the rules directory via " +
+ 'path.join(ECC_ROOT, "rules", "common", ...); rules must be read at runtime from ' +
+ "the canonical rules/common/ directory of the installed ECC package, which is " +
+ "the entire point of this adapter feature, not from a path baked in some other way"
+ )
+
+ const piDir = path.join(repoRoot, ".pi")
+ assert.ok(
+ fs.existsSync(piDir),
+ `expected a .pi/ directory to exist at ${piDir} for this check to be meaningful`
+ )
+ const piRulesDir = path.join(piDir, "rules")
+ assert.ok(
+ !fs.existsSync(piRulesDir),
+ `found ${piRulesDir} on disk; ECC's engineering rules must be read at runtime from ` +
+ "the canonical rules/common/ directory and never copied or generated into .pi/ -- " +
+ "a rules/ directory under .pi/ means that core constraint has been violated"
+ )
+ }],
+
+ ["every file named in PORTABLE_RULE_FILES actually exists under rules/common/ in this repo", () => {
+ const ruleFiles = parsePortableRuleFiles(extensionSource)
+ assert.ok(
+ ruleFiles.length > 0,
+ "expected to find and parse a PORTABLE_RULE_FILES array literal in .pi/extensions/index.ts"
+ )
+
+ const rulesCommonDir = path.join(repoRoot, "rules", "common")
+ for (const file of ruleFiles) {
+ const fullPath = path.join(rulesCommonDir, file)
+ assert.ok(
+ fs.existsSync(fullPath),
+ `expected ${fullPath} to exist because it is listed in PORTABLE_RULE_FILES; a ` +
+ "missing rule file makes loadPortableRules() silently skip it via its " +
+ "try/catch, so the adapter would inject less engineering-rule coverage into " +
+ "Pi's system prompt than intended, with no error or warning to notice it by"
+ )
+ }
+ }],
+
+ ["loadPortableRules() behavioral mirror: concatenates the real rules/common/ files, stays under the cap, and contains markers from several rule files", () => {
+ // Mirror of loadPortableRules() (read-trim-skip-cap-join loop), guarded by the
+ // source-text assertions in the two tests above (PORTABLE_RULE_FILES contents
+ // and the rules/common path) and by the parsed MAX_RULES_BYTES cap below, so a
+ // drift in the real function's shape fails those tests even if this mirror,
+ // run here against this repo's actual rule files, still looks correct.
+ const ruleFiles = parsePortableRuleFiles(extensionSource)
+ const maxRulesBytes = parseMaxRulesBytes(extensionSource)
+ assert.ok(
+ typeof maxRulesBytes === "number" && maxRulesBytes > 0,
+ "expected to parse a positive numeric MAX_RULES_BYTES constant out of .pi/extensions/index.ts"
+ )
+
+ const result = loadPortableRulesMirror(repoRoot, ruleFiles, maxRulesBytes)
+
+ assert.ok(
+ typeof result === "string" && result.length > 0,
+ "expected loadPortableRules() to return a non-empty string when run against this " +
+ "repo's real rules/common/ files; an empty result means the <ecc-engineering-rules> " +
+ "block would be silently omitted from Pi's system prompt on every turn"
+ )
+ assert.ok(
+ result.length < maxRulesBytes,
+ `expected the concatenated rules text (${result.length} chars) to stay under ` +
+ `MAX_RULES_BYTES (${maxRulesBytes} bytes); exceeding the cap means the ` +
+ "concatenation loop's stop-before-exceeding-cap guard is not doing its job, and a " +
+ "large rule-file edit could flood Pi's system prompt"
+ )
+
+ for (const marker of ["Immutability", "Minimum Test Coverage", "Secret Management"]) {
+ assert.ok(
+ result.includes(marker),
+ `expected the concatenated rules text to contain "${marker}" (a marker from one ` +
+ "of the real rules/common/ files); its absence means that file was skipped " +
+ "(missing, empty, or cut off by the cap) or its content changed in a way that " +
+ "dropped the section entirely"
+ )
+ }
+ }],
+
+ ["leakage guard: the text loadPortableRules() would inject contains no Claude-Code-only primitives Pi cannot use", () => {
+ const ruleFiles = parsePortableRuleFiles(extensionSource)
+ const maxRulesBytes = parseMaxRulesBytes(extensionSource)
+ const result = loadPortableRulesMirror(repoRoot, ruleFiles, maxRulesBytes)
+ assert.ok(
+ typeof result === "string" && result.length > 0,
+ "expected a non-empty mirrored rules result for this leakage check to be meaningful"
+ )
+
+ for (const leaked of ["TodoWrite", "Option+T", "PostToolUse", "alwaysThinkingEnabled"]) {
+ assert.ok(
+ !result.includes(leaked),
+ `found "${leaked}" in the text loadPortableRules() would inject into Pi's system ` +
+ "prompt; this is a Claude-Code-only primitive (a tool, hook event type, or " +
+ "thinking-budget toggle) that would instruct Pi's model to use something that " +
+ "does not exist in Pi -- exactly the leakage excluding agents.md/hooks.md/" +
+ "performance.md from PORTABLE_RULE_FILES exists to prevent"
+ )
+ }
+ }],
+
+ ["/ecc-doctor reports rule files actually loaded, not the allowlist length (source contract)", () => {
+ assert.ok(
+ /let\s+cachedRuleFileCount\s*=\s*0/.test(extensionSource),
+ "expected .pi/extensions/index.ts to track how many rule files actually loaded in a " +
+ "cachedRuleFileCount counter alongside cachedRules"
+ )
+ assert.ok(
+ /cachedRuleFileCount\s*=\s*sections\.length/.test(extensionSource),
+ "expected loadPortableRules in .pi/extensions/index.ts to set cachedRuleFileCount " +
+ "from sections.length, which is what survived the read failures, the empty-file " +
+ "skip, and the MAX_RULES_BYTES break"
+ )
+
+ const disabledBranch = extensionSource.slice(
+ extensionSource.indexOf("isDisabledByEnv(process.env.ECC_PI_RULES)"),
+ extensionSource.indexOf("const sections: string[] = []")
+ )
+ assert.ok(
+ /cachedRuleFileCount\s*=\s*0/.test(disabledBranch),
+ "expected the ECC_PI_RULES disable branch of loadPortableRules in " +
+ ".pi/extensions/index.ts to reset cachedRuleFileCount to 0, so the counter can " +
+ "never survive from a prior load into a disabled session"
+ )
+
+ const statusStart = extensionSource.indexOf("function describeRulesStatus")
+ assert.ok(
+ statusStart !== -1,
+ "expected .pi/extensions/index.ts to define a function named describeRulesStatus"
+ )
+ const nextFunctionStart = extensionSource.indexOf("\nfunction ", statusStart + 1)
+ const statusSource =
+ nextFunctionStart === -1
+ ? extensionSource.slice(statusStart)
+ : extensionSource.slice(statusStart, nextFunctionStart)
+
+ assert.ok(
+ /\$\{cachedRuleFileCount\}\/\$\{PORTABLE_RULE_FILES\.length\}\s+rule file/.test(statusSource),
+ "expected describeRulesStatus in .pi/extensions/index.ts to report the loaded count " +
+ "over the allowlist length (`${cachedRuleFileCount}/${PORTABLE_RULE_FILES.length} " +
+ "rule file(s)`); loadPortableRules silently skips unreadable and empty files and " +
+ "breaks out of the loop at MAX_RULES_BYTES, so reporting the allowlist length " +
+ "alone makes an install that loaded 3 of 7 report 7 -- and /ecc-doctor is the one " +
+ "place a user looks to find a partial install"
+ )
+ }],
+
+ ["isDisabledByEnv() behavioral mirror: recognizes 0/false/off/none/disabled case- and whitespace-insensitively, and the real function reads ECC_PI_RULES", () => {
+ for (const disabledValue of ["0", "false", "off", "none", "disabled"]) {
+ assert.strictEqual(
+ isDisabledByEnvMirror(disabledValue),
+ true,
+ `expected isDisabledByEnv("${disabledValue}") to be true`
+ )
+ assert.strictEqual(
+ isDisabledByEnvMirror(disabledValue.toUpperCase()),
+ true,
+ `expected isDisabledByEnv to be case-insensitive for "${disabledValue.toUpperCase()}"`
+ )
+ assert.strictEqual(
+ isDisabledByEnvMirror(` ${disabledValue} `),
+ true,
+ `expected isDisabledByEnv to ignore surrounding whitespace for " ${disabledValue} "`
+ )
+ }
+
+ assert.strictEqual(
+ isDisabledByEnvMirror(" OFF "),
+ true,
+ 'expected isDisabledByEnv(" OFF ") to be true (mixed case AND surrounding whitespace ' +
+ "at once); a user pasting ECC_PI_RULES=\" OFF \" into a shell profile must still " +
+ "disable injection"
+ )
+
+ for (const enabledValue of [undefined, "", "1", "true", "on", "yes", "TRUE ISH"]) {
+ assert.strictEqual(
+ isDisabledByEnvMirror(enabledValue),
+ false,
+ `expected isDisabledByEnv(${JSON.stringify(enabledValue)}) to be false; treating an ` +
+ "unrecognized value as disabled would silently turn off rule injection for anyone " +
+ "who sets ECC_PI_RULES to something other than the 5 documented off-values"
+ )
+ }
+
+ const withoutComments = stripComments(extensionSource)
+ assert.ok(
+ withoutComments.includes("process.env.ECC_PI_RULES"),
+ "expected .pi/extensions/index.ts to read process.env.ECC_PI_RULES as the env var " +
+ "that turns rule injection off; a different or renamed env var would silently break " +
+ "anyone's existing ECC_PI_RULES=off configuration"
+ )
+ }],
+
+ ["before_agent_start wraps rules and context in their tags, consumes pendingContext but never the rules, and returns early with no override when there is nothing to add", () => {
+ const beforeAgentStartIdx = extensionSource.indexOf('pi.on("before_agent_start"')
+ assert.ok(
+ beforeAgentStartIdx !== -1,
+ "expected .pi/extensions/index.ts to register a before_agent_start handler via pi.on(...)"
+ )
+ const sessionShutdownIdx = extensionSource.indexOf('pi.on("session_shutdown"', beforeAgentStartIdx)
+ assert.ok(
+ sessionShutdownIdx !== -1 && sessionShutdownIdx > beforeAgentStartIdx,
+ "expected a session_shutdown handler registered after before_agent_start in .pi/extensions/index.ts"
+ )
+
+ const handlerSource = stripComments(extensionSource.slice(beforeAgentStartIdx, sessionShutdownIdx))
+
+ assert.ok(
+ handlerSource.includes("<ecc-engineering-rules>"),
+ "expected the before_agent_start handler in .pi/extensions/index.ts to wrap " +
+ "injected rules in an <ecc-engineering-rules> tag"
+ )
+ assert.ok(
+ handlerSource.includes("<ecc-session-context>"),
+ "expected the before_agent_start handler in .pi/extensions/index.ts to wrap the " +
+ "session context in an <ecc-session-context> tag"
+ )
+
+ const contextPushIdx = handlerSource.indexOf("<ecc-session-context>")
+ const clearIdx = handlerSource.indexOf("pendingContext = undefined", contextPushIdx)
+ assert.ok(
+ contextPushIdx !== -1 && clearIdx !== -1 && clearIdx > contextPushIdx,
+ "expected before_agent_start to clear pendingContext = undefined after using it to " +
+ "build the <ecc-session-context> block; without this, the same one-shot session " +
+ "context would be replayed into every later agent turn instead of being consumed once"
+ )
+
+ assert.ok(
+ !/\bcachedRules\s*=\s*(undefined|null)/.test(handlerSource) &&
+ !/\brules\s*=\s*(undefined|null)/.test(handlerSource),
+ "found code in the before_agent_start handler that resets the loaded rules value; " +
+ "engineering rules describe standing policy and must be re-applied on EVERY turn " +
+ "(unlike the one-shot pendingContext), so nothing in this handler may consume or " +
+ "clear them the way pendingContext is consumed"
+ )
+
+ assert.ok(
+ /if\s*\(\s*additions\.length\s*===\s*0\s*\)\s*\{\s*return\s*\}/.test(handlerSource),
+ "expected before_agent_start to return early with a bare `return` (no systemPrompt " +
+ "override) when there is nothing to add; without this guard, a turn with no rules " +
+ "and no pending context would still return a rebuilt systemPrompt instead of " +
+ "leaving Pi's original systemPrompt untouched"
+ )
+
+ const earlyReturnIdx = handlerSource.indexOf("if (additions.length === 0)")
+ const overrideReturnIdx = handlerSource.indexOf("return { systemPrompt")
+ assert.ok(
+ earlyReturnIdx !== -1 && overrideReturnIdx !== -1 && earlyReturnIdx < overrideReturnIdx,
+ "expected the early-return-when-nothing-to-add guard to appear before the " +
+ "systemPrompt-override return in before_agent_start"
+ )
+ }],
+ ]
+
+ for (const [name, fn] of tests) {
+ if (await runTest(name, fn)) {
+ passed += 1
+ } else {
+ failed += 1
+ }
+ }
+
+ console.log(`\nPassed: ${passed}`)
+ console.log(`Failed: ${failed}`)
+ process.exit(failed > 0 ? 1 : 0)
+}
+
+main()
diff --git a/tests/pi/pi-package-manifest.test.js b/tests/pi/pi-package-manifest.test.js
new file mode 100644
index 000000000..35379e943
--- /dev/null
+++ b/tests/pi/pi-package-manifest.test.js
@@ -0,0 +1,335 @@
+/**
+ * Tests for the Pi coding agent package manifest (`pi` key in package.json)
+ * and the `.pi/` adapter directory.
+ *
+ * This is the regression guard for PR #2352, which generated ~440 copied
+ * files (skills/agents/prompts/commands) under `.pi/`. The Pi integration
+ * must stay a thin adapter: `.pi/` holds only adapter code, and the `pi`
+ * manifest points directly at ECC's canonical `skills/` and `commands/`
+ * directories rather than at duplicated copies.
+ */
+
+const assert = require("assert")
+const fs = require("fs")
+const path = require("path")
+const { execFileSync } = require("child_process")
+
+function runTest(name, fn) {
+ try {
+ fn()
+ console.log(` ✓ ${name}`)
+ return true
+ } catch (error) {
+ console.log(` ✗ ${name}`)
+ console.error(` ${error.message}`)
+ return false
+ }
+}
+
+function extractFrontmatter(content) {
+ const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+ return match ? match[1] : null
+}
+
+/**
+ * Manual recursive file walk. Node 18 (the repo's minimum supported version,
+ * see `engines` in package.json) does not support
+ * `fs.readdirSync(dir, { recursive: true })` — that option was only added in
+ * Node 20 — so this walk is done by hand instead.
+ */
+function walkFiles(dir) {
+ let files = []
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+ const fullPath = path.join(dir, entry.name)
+ if (entry.isDirectory()) {
+ files = files.concat(walkFiles(fullPath))
+ } else if (entry.isFile()) {
+ files.push(fullPath)
+ }
+ }
+ return files
+}
+
+const COPY_OR_GENERATE_WORD = /\b(copy|copies|copying|generate|generates|generated|generating)\b/i
+const PATH_UNDER_PI = /\.pi\//
+const NEGATION_WORD = /\b(no|not|never|nothing|without|isn't|aren't|don't|doesn't)\b/i
+const COPY_INTO_PI_SHAPE = /\b(copy|copies|copying|generate|generates|generating)\b[^.!?\n]*\.pi\//i
+
+/**
+ * Splits markdown text into sentence-ish chunks: paragraphs first, then each
+ * paragraph on sentence-ending punctuation. Good enough for this heuristic —
+ * it does not need to be a real sentence parser, only to stop treating an
+ * entire multi-sentence paragraph as one unit.
+ */
+function splitIntoSentences(text) {
+ return text
+ .split(/\n\s*\n/)
+ .flatMap((paragraph) => paragraph.split(/(?<=[.!?])\s+/))
+ .map((sentence) => sentence.trim())
+ .filter(Boolean)
+}
+
+/**
+ * Detects an actual imperative instruction to copy or generate files into
+ * `.pi/` (e.g. "Copy your skills into .pi/skills/ before installing."),
+ * while explicitly allowing negated phrasing that documents the opposite
+ * (e.g. "no generated copies", "Nothing is copied or generated under .pi/").
+ * A naive "copy/generate word AND .pi/ path in the same paragraph" proximity
+ * check flags that legitimate negated documentation as a violation; this
+ * requires copy/generate word and .pi/ path to appear in the same sentence
+ * with no negation word, which is what an actual instruction looks like.
+ */
+function findImperativeCopyIntoPiInstruction(text) {
+ return splitIntoSentences(text).some((sentence) => {
+ if (!COPY_OR_GENERATE_WORD.test(sentence) || !PATH_UNDER_PI.test(sentence)) {
+ return false
+ }
+ if (NEGATION_WORD.test(sentence)) {
+ return false
+ }
+ return COPY_INTO_PI_SHAPE.test(sentence)
+ })
+}
+
+function main() {
+ console.log("\n=== Testing Pi package manifest (pi key + .pi/ adapter) ===\n")
+
+ let passed = 0
+ let failed = 0
+
+ const repoRoot = path.join(__dirname, "..", "..")
+ const packageJson = JSON.parse(
+ fs.readFileSync(path.join(repoRoot, "package.json"), "utf8")
+ )
+
+ const tests = [
+ ["package.json pi key has exactly extensions, skills, prompts (not agents or chains)", () => {
+ assert.ok(
+ packageJson.pi && typeof packageJson.pi === "object",
+ "package.json must have a top-level `pi` key for Pi coding agent integration"
+ )
+ const keys = Object.keys(packageJson.pi).sort()
+ assert.deepStrictEqual(
+ keys,
+ ["extensions", "prompts", "skills"],
+ `pi manifest must contain exactly extensions, prompts, skills — got: ${keys.join(", ")}`
+ )
+ assert.ok(
+ !("agents" in packageJson.pi),
+ "pi.agents is not supported by Pi's core manifest — subagent conversion belongs to the pi-subagents companion package and would be silently ignored if placed here"
+ )
+ assert.ok(
+ !("chains" in packageJson.pi),
+ "pi.chains is not supported by Pi's core manifest — chains belong to the pi-subagents companion package and would be silently ignored if placed here"
+ )
+ }],
+
+ ["pi.extensions is exactly the single ECC adapter entry file, and it exists on disk", () => {
+ assert.deepStrictEqual(
+ packageJson.pi.extensions,
+ ["./.pi/extensions/index.ts"],
+ `pi.extensions must be exactly ["./.pi/extensions/index.ts"] — got ${JSON.stringify(packageJson.pi.extensions)}`
+ )
+ const extensionPath = path.join(repoRoot, ".pi", "extensions", "index.ts")
+ assert.ok(
+ fs.existsSync(extensionPath),
+ `${extensionPath} does not exist, but pi.extensions references it — Pi would fail to load the adapter`
+ )
+ }],
+
+ ["pi.skills and pi.prompts point at ECC's canonical top-level directories, never at .pi/", () => {
+ assert.deepStrictEqual(
+ packageJson.pi.skills,
+ ["./skills"],
+ `pi.skills must be exactly ["./skills"] (ECC's canonical skills directory) — got ${JSON.stringify(packageJson.pi.skills)}`
+ )
+ assert.deepStrictEqual(
+ packageJson.pi.prompts,
+ ["./commands"],
+ `pi.prompts must be exactly ["./commands"] (ECC's canonical commands directory) — got ${JSON.stringify(packageJson.pi.prompts)}`
+ )
+ for (const entry of [...packageJson.pi.skills, ...packageJson.pi.prompts]) {
+ assert.ok(
+ !entry.startsWith("./.pi") && !entry.includes(".pi/"),
+ `pi.skills/pi.prompts entry "${entry}" must not point under .pi/ — Pi must mount ECC's canonical assets directly, never a copy generated into the adapter directory`
+ )
+ }
+ }],
+
+ ["REGRESSION GUARD: .pi/ contains no generated resource directories (PR #2352 regenerated this)", () => {
+ const forbiddenDirs = [".pi/skills", ".pi/agents", ".pi/prompts", ".pi/chains", ".pi/commands", ".pi/rules"]
+ for (const relativeDir of forbiddenDirs) {
+ const fullPath = path.join(repoRoot, relativeDir)
+ assert.ok(
+ !fs.existsSync(fullPath),
+ `${relativeDir} must not exist — .pi/ may contain adapter code only; a generated resource directory here means canonical skills/agents/prompts were copied instead of referenced by the pi manifest (the PR #2352 regression)`
+ )
+ }
+ }],
+
+ ["REGRESSION GUARD: fewer than 10 files exist on disk under .pi/ (adapter code only)", () => {
+ // Authoritative check: walk .pi/ on disk so untracked files (e.g.
+ // regenerated skill copies that were never `git add`ed) cannot bypass
+ // this guard the way a git-only check would.
+ const piDir = path.join(repoRoot, ".pi")
+ const onDiskFiles = walkFiles(piDir)
+ assert.ok(
+ onDiskFiles.length < 10,
+ ".pi/ must contain only adapter code, never copies of canonical assets " +
+ `(skills/agents/prompts) — found ${onDiskFiles.length} files on disk: ` +
+ `${onDiskFiles.map((file) => path.relative(repoRoot, file)).join(", ")}`
+ )
+
+ // Additional signal only, not authoritative: git ls-files reports what
+ // is tracked, which is useful corroborating evidence but is silently
+ // bypassed by untracked files, so it never replaces the on-disk walk above.
+ let trackedFiles
+ try {
+ const output = execFileSync("git", ["ls-files", ".pi"], {
+ cwd: repoRoot,
+ encoding: "utf8",
+ })
+ trackedFiles = output.split("\n").filter(Boolean)
+ } catch (error) {
+ console.log(` (git signal skipped: git unavailable or \`git ls-files .pi\` failed: ${error.message})`)
+ }
+ if (trackedFiles) {
+ assert.ok(
+ trackedFiles.length < 10,
+ `.pi/ must contain only adapter code, never copies of canonical assets (skills/agents/prompts) — found ${trackedFiles.length} tracked files: ${trackedFiles.join(", ")}`
+ )
+ }
+ }],
+
+ ["package.json files array ships the .pi/ adapter and the canonical assets the manifest depends on", () => {
+ const files = packageJson.files
+ assert.ok(Array.isArray(files), "package.json must have a `files` array to control what npm publishes")
+ assert.ok(
+ files.includes(".pi/"),
+ "package.json files array must include \".pi/\" so the Pi adapter ships in the published npm package"
+ )
+ assert.ok(
+ files.includes("commands/"),
+ "package.json files array must include \"commands/\" — pi.prompts (\"./commands\") depends on this canonical directory being published"
+ )
+ assert.ok(
+ files.some((entry) => entry.startsWith("skills/")),
+ "package.json files array must include at least one skills/... entry — pi.skills (\"./skills\") depends on the canonical skills directory being published"
+ )
+ }],
+
+ ["canonical commands/ is Pi-compatible without transformation (prompt-template format)", () => {
+ const commandsDir = path.join(repoRoot, "commands")
+ const commandFiles = fs.readdirSync(commandsDir).filter((name) => name.endsWith(".md"))
+ assert.ok(
+ commandFiles.length >= 50,
+ `commands/ must contain at least 50 .md files for Pi's prompt-template format — found ${commandFiles.length}`
+ )
+
+ const planCommandPath = path.join(commandsDir, "plan.md")
+ const planCommand = fs.readFileSync(planCommandPath, "utf8")
+ const planFrontmatter = extractFrontmatter(planCommand)
+ assert.ok(
+ planFrontmatter !== null,
+ `${planCommandPath} must start with a --- YAML frontmatter block for Pi to parse it as a prompt template`
+ )
+ assert.ok(
+ /^description:/m.test(planFrontmatter),
+ `${planCommandPath} frontmatter must contain a description: field — Pi's prompt-template format requires it`
+ )
+ }],
+
+ ["canonical skills/ is Pi-compatible without transformation (Agent Skills standard)", () => {
+ const skillsDir = path.join(repoRoot, "skills")
+ const skillDirNames = fs.readdirSync(skillsDir, { withFileTypes: true })
+ .filter((entry) => entry.isDirectory())
+ .map((entry) => entry.name)
+ const skillDirsWithManifest = skillDirNames.filter((name) =>
+ fs.existsSync(path.join(skillsDir, name, "SKILL.md"))
+ )
+ assert.ok(
+ skillDirsWithManifest.length >= 100,
+ `skills/ must contain at least 100 subdirectories with a SKILL.md for Pi's Agent Skills implementation — found ${skillDirsWithManifest.length}`
+ )
+
+ const sampleSkillPath = path.join(skillsDir, "frontend-patterns", "SKILL.md")
+ const sampleSkill = fs.readFileSync(sampleSkillPath, "utf8")
+ const sampleFrontmatter = extractFrontmatter(sampleSkill)
+ assert.ok(
+ sampleFrontmatter !== null,
+ `${sampleSkillPath} must start with a --- YAML frontmatter block for Pi to parse it as an Agent Skill`
+ )
+ assert.ok(
+ /^name:/m.test(sampleFrontmatter),
+ `${sampleSkillPath} frontmatter must contain a name: field — the Agent Skills standard Pi implements requires it`
+ )
+ assert.ok(
+ /^description:/m.test(sampleFrontmatter),
+ `${sampleSkillPath} frontmatter must contain a description: field — the Agent Skills standard Pi implements requires it`
+ )
+ }],
+
+ [".pi/README.md documents the single-source-of-truth principle without instructing copies into .pi/", () => {
+ const readmePath = path.join(repoRoot, ".pi", "README.md")
+ assert.ok(
+ fs.existsSync(readmePath),
+ `${readmePath} must exist to document the adapter's single-source-of-truth design principle`
+ )
+ const readme = fs.readFileSync(readmePath, "utf8")
+ assert.ok(
+ readme.includes("skills/"),
+ ".pi/README.md must mention skills/ as the canonical directory Pi mounts directly"
+ )
+ assert.ok(
+ readme.includes("commands/"),
+ ".pi/README.md must mention commands/ as the canonical directory Pi mounts directly"
+ )
+
+ // Detects actual imperative instructions to copy/generate into .pi/,
+ // not mere word proximity — a naive "copy/generate word + .pi/ path in
+ // the same paragraph" check would flag legitimate negated documentation
+ // (e.g. "no generated copies", "Nothing is copied or generated under
+ // .pi/") as a violation. Verified against the current .pi/README.md
+ // content below (must pass) and the detector's own behavior further down.
+ assert.ok(
+ !findImperativeCopyIntoPiInstruction(readme),
+ ".pi/README.md must not instruct users to copy or generate files into .pi/ " +
+ "— that documentation would reintroduce the PR #2352 regression"
+ )
+
+ // Sanity-check the detector itself so the assertion above is not
+ // vacuously true: it must still catch a real instruction...
+ assert.ok(
+ findImperativeCopyIntoPiInstruction("Copy your skills into .pi/skills/ before installing."),
+ "the copy-into-.pi/ detector must flag an actual instruction to copy files " +
+ "into .pi/ (this checks the detector, not .pi/README.md itself)"
+ )
+ // ...and it must explicitly allow the negated phrasing named in the
+ // PR #2352 regression-guard rationale, rather than flagging it.
+ assert.ok(
+ !findImperativeCopyIntoPiInstruction("This adapter ships with no generated copies under `.pi/`."),
+ 'the copy-into-.pi/ detector must not flag negated phrasing (e.g. "no generated ' +
+ 'copies... .pi/") as an instruction (this checks the detector, not .pi/README.md itself)'
+ )
+ assert.ok(
+ !findImperativeCopyIntoPiInstruction("Nothing is copied or generated under `.pi/`."),
+ 'the copy-into-.pi/ detector must not flag negated phrasing (e.g. "Nothing is copied ' +
+ 'or generated under .pi/") as an instruction (this checks the detector, not .pi/README.md itself)'
+ )
+ }],
+ ]
+
+ for (const [name, fn] of tests) {
+ if (runTest(name, fn)) {
+ passed += 1
+ } else {
+ failed += 1
+ }
+ }
+
+ console.log(`\nPassed: ${passed}`)
+ console.log(`Failed: ${failed}`)
+ process.exit(failed > 0 ? 1 : 0)
+}
+
+main()