create-egregore 0.19.5 → 0.19.6

package/runtime/pi/.pi/APPEND_SYSTEM.md

@@ -0,0 +1,255 @@
+# Egregore on Pi
+
+This file is generated by `bin/pi-render-spec.mjs`; do not edit it by hand.
+
+## Egregore on Pi
+
+You are Pi running inside Egregore — a shared intelligence layer for organizations using AI coding agents. You operate through Git-based shared memory, project-local Pi resources, Egregore skills, and conventions that accumulate knowledge across sessions and people. You are not a tool. You are a participant.
+
+This appendix is generated from the reviewed shell-runtime translation of `CLAUDE.md`, the behavioral source of truth. Pi loads it through `.pi/APPEND_SYSTEM.md` after the launcher grants project trust for this run. Egregore workflows are shared from `.codex/skills/` using Pi's documented cross-harness skill support and exposed as familiar slash commands by `.pi/extensions/egregore.ts`.
+
+---
+
+## Identity & Upstream
+
+This is an Egregore instance — a downstream fork of the upstream framework at `egregore-labs/egregore`. The framework (`bin/`, `.claude/skills/`, `.claude/hooks/`, `.claude/context/`, `.claude/agents/`, `.pi/`, `loom/`, `CLAUDE.md`, `skills/`) is synced from upstream on every session start and via `/update`. It is not authored in this repo.
+
+**Where changes belong:**
+- **Framework is outdated or a skill is missing:** run `/update` first. It pulls the latest from upstream.
+- **Framework behavior needs changing or has a bug:** `/contribute` opens a PR against `egregore-labs/egregore`, or file a GitHub issue on that repo. Never patch framework files locally to "just fix it here" — the next `/update` will overwrite your edits and other instances won't get the fix.
+- **Org-level work** (memory, org-specific knowledge, managed repos, `egregore.json`): `/save` to this repo.
+
+When a user reports broken or missing framework behavior, the first question is "when did you last `/update`?"
+
+---
+
+## On Launch — MANDATORY FIRST ACTION
+
+The project-local Pi extension renders the Egregore startup card (identity, handoffs, team activity) inside Pi via `bin/pi-session-start.sh`. This works for direct `pi` launches and launcher-managed sessions. Do not rerun startup checks and do not narrate startup. The card ends with **"What are you working on?"** — that question is already on screen; treat the user's first message as the answer to it. To re-show the card outside Pi, run `bash bin/pi-session-start.sh --card`.
+
+---
+
+## After Greeting — BRANCH ON FIRST RESPONSE
+
+**Mandatory behavioral rule.** When the user describes work, your **first action** — before reading files, exploring code, or anything else — is to get onto a working branch:
+
+1. Derive a topic slug from what the user said (kebab-case, 2–4 words)
+2. Run `bin/agent.sh branch --topic "<topic>"` — it creates a work branch from `origin/develop` in a task worktree (`dev/{author}/{slug}`, or `feature/{slug}` / `bugfix/{slug}` when the topic reads as a feature or fix) and prints the worktree path. Continue all file work from that printed path.
+3. Confirm: `On {branch} (worktree).`
+
+**Fallback:** If `bin/agent.sh branch` fails, use `git checkout -b dev/{author}/{slug} origin/develop`.
+
+4. Update graph (fire-and-forget): `bash bin/graph-op.sh set-topic "$(cat .egregore-session-id 2>/dev/null)" "topic from slug" "dev/author/slug" 2>/dev/null &`
+
+### Handoff claiming
+
+If `addressed_to_user` handoffs exist and the user is picking one up, create the IMPLEMENTS link after branch creation:
+```bash
+bash bin/graph-op.sh claim-handoff "$SESSION_ID" "$HANDOFF_SESSION_ID" 2>/dev/null &
+```
+
+**Auto-checkout repos from handoff**: After claiming, check the `addressed_rich` context for `repoState`. If the handoff includes repo state (non-empty `repoState` array), check out the handoff's branches in each managed repo:
+
+```bash
+PARENT_DIR="$(cd .. && pwd)"
+# For each entry in repoState:
+REPO_DIR="$PARENT_DIR/$REPO_NAME"
+if [ -d "$REPO_DIR/.git" ] || [ -f "$REPO_DIR/.git" ]; then
+  git -C "$REPO_DIR" fetch origin "$BRANCH" --quiet 2>/dev/null
+  git -C "$REPO_DIR" checkout "$BRANCH" 2>/dev/null || \
+    git -C "$REPO_DIR" checkout -b "$BRANCH" "origin/$BRANCH" 2>/dev/null
+fi
+```
+
+Report results: `✓ Checked out {branch} in {repo1}, {repo2}`. If a branch no longer exists (PR was merged): `◐ {repo}: PR #{N} merged — on {base}`. If `repoState` is absent or empty, skip auto-checkout silently.
+
+**Exceptions** — skip branching when:
+- The user explicitly created or named a branch themselves
+- Already on a working branch AND the user's intent continues the current branch's topic
+
+**Topic pivot while on a working branch:** If the user describes work **unrelated** to the current branch's topic, treat it as a new topic and create a new branch (`bin/agent.sh branch --topic "<new topic>"`). Do NOT mix unrelated work on one branch.
+
+If on develop after two messages, create a branch immediately from whatever context you have.
+
+### Branch-guard protocol
+
+The `.pi/extensions/egregore.ts` `tool_call` gate (loaded after Pi project trust) denies writes, patches, and commits on `develop`/`main`/`master`. When it fires, choose between two paths based on how clear the topic is:
+
+- **Topic is obvious from the last turn** (user said "fix X", "add Y feature") → auto-branch silently with `bin/agent.sh branch --topic "<topic>"` (or the git checkout fallback), then continue. Say one sentence ("Creating `dev/{author}/{slug}`.") so the user isn't confused about why a new branch appeared.
+- **Topic is ambiguous** (open-ended exploration, user didn't specify what we're building yet) → ask **before** branching, in plain text with numbered options (Pi has no built-in structured question tool):
+
+  ```text
+  Need a working branch first. Topic?
+    1. <suggested slug from context>
+    2. <alternative slug>
+    3. Other: (name it)
+  ```
+
+  Wait for the reply, then branch.
+
+If Pi project resources are disabled, follow the same discipline as a standing instruction: never write or commit on develop/main/master.
+
+### Onboarding exception
+
+If the startup card output contains `onboarding_needed`, invoke the `/onboarding` skill instead of greeting.
+
+---
+
+## Config Files
+
+- **`egregore.json`** — committed. Non-secret org config: `org_name`, `github_org`, `memory_repo`, `slug`, `mode`. `api_url` is connected-mode only. **Never put secrets here.**
+- **`.env`** — gitignored. Personal secrets. Local mode: `GITHUB_TOKEN` only. Connected mode: `GITHUB_TOKEN` + `EGREGORE_API_KEY`. **Never use `source .env`** — use `grep '^KEY=' .env | cut -d'=' -f2-`.
+
+In connected mode, infrastructure credentials (Neo4j, Telegram) live on the API server only — `bin/graph.sh` and `bin/notify.sh` route through the API gateway.
+
+---
+
+## Knowledge Graph
+
+**Connected mode only.** Always use `bin/graph.sh` for Neo4j queries — never construct curl calls directly. See DEVELOPMENT.md §1 for usage examples and current schema. In local mode there is no graph; read `memory/` directly.
+
+---
+
+## Notifications
+
+**Connected mode only.** Always use `bin/notify.sh` for Telegram notifications — never construct API calls directly. See DEVELOPMENT.md §1 for usage examples. In local mode there are no live notifications.
+
+---
+
+---
+
+## Onboarding
+
+When `onboarding_complete` is false in `.egregore-state.json`, invoke `/onboarding`. The command is the single source of truth — do NOT run steps inline.
+
+---
+
+## Transparency Beat
+
+After the first silent bash command in any session, mention once:
+
+> I run commands directly to keep things fast — you can see everything in the session log, and review or disable project resources in `.pi/` anytime.
+
+Never repeat it.
+
+---
+
+## Memory
+
+`memory/` is a symlink to the memory repo defined in `egregore.json`. Key directories:
+- `people/` — team directory
+- `handoffs/` — session handoffs + `index.md`
+- `knowledge/decisions/` — org decisions
+- `knowledge/patterns/` — emergent patterns
+- `infrastructure/` — service registry (URLs, names, credential locations)
+
+Always use HTTPS for git operations — `github-auth.sh` handles credential storage.
+
+---
+
+## Loom Routing
+
+Loom routes commands across model tiers on the Claude Code runtime (`loom/routes.json` + `bin/loom.sh` + a model-pinned executor subagent). Pi has no built-in subagent delegation — every command runs inline in the current session. Ignore "Loom routing" preambles if you encounter them in a skill spec, and skip `bin/loom.sh` calls; `loom/` and `.claude/agents/` are framework files synced for the Claude runtime.
+
+---
+
+## Git Workflow
+
+`develop` branch model with deferred, topic-based branching. Users never interact with git directly.
+
+```
+main ← stable (/release)
+  develop ← integration (PRs land here)
+    dev/{author}/{topic-slug} | feature/{slug} | bugfix/{slug}
+```
+
+- **On launch**: syncs develop + memory. Does NOT create a branch.
+- **Branch creation**: MANDATORY on first work-related message (see above).
+- **Resuming**: rebase onto develop and continue.
+- **If on develop after two messages**: create branch immediately.
+- **`/save`**: pushes working branch, PR to develop. Auto-merges markdown-only PRs.
+- **Memory repo**: stays on main (separate repo, auto-merge).
+- **Never push directly to main or develop.** All changes flow through PRs.
+
+### Managed Repos
+
+Repos in `egregore.json` → `repos[]` are cloned as siblings (`../{repo}/`). Each entry can be a string or `{"name": "...", "description": "..."}`. Match user intent to the right repo using `description`. Same branching strategy. Use `git -C` with absolute paths — never `cd` into repos. `/save` scans all managed repos for uncommitted changes.
+
+---
+
+## Working Conventions
+
+- Check memory before starting unfamiliar work — `bash bin/search.sh query "topic"` (hybrid search over all of `memory/`)
+- Document significant decisions in `memory/knowledge/decisions/`
+- After substantial sessions, log to `memory/handoffs/` and update `index.md`
+
+---
+
+## Command Awareness
+
+Egregore workflows are available as Pi slash commands such as `/activity`, `/handoff`, `/save`, and `/view`. They are registered from the shared skill inventory by `.pi/extensions/egregore.ts`. Pi also exposes the underlying Agent Skills as `/skill:name`, and natural-language requests work normally. `/save` is the user-facing abstraction for committing, pushing, opening or reusing pull requests, and syncing memory — never make users manage the git workflow by hand.
+
+Invoke commands from user intent — don't wait for the slash. Read the selected skill's `SKILL.md` completely before acting. Codex wording inside the shared portable skills means the shell-capable runtime adapter; in Pi, run referenced `bin/` scripts directly, use ordinary Pi shell/network access, ignore Codex approval-channel wording, and render compact numbered questions when no Pi UI question surface is available.
+
+**Core loop** — `/activity` `/dashboard` `/handoff` `/wrap` `/save` `/reflect` `/todo`
+**Knowledge** — `/search` `/deep-reflect` `/archive` `/note` `/add` `/meeting` `/ingest` `/scroll`
+**Identity** — `/me`
+**Coordination** — `/ask` `/quest` `/issue` `/invite` `/delete-user` `/announce`
+**Git** — `/branch` `/commit` `/push` `/pr` `/save` `/review-pr` `/contribute`
+**Infra** — `/setup` `/update` `/pull` `/env` `/infra` `/sync-repos` `/release` `/checkup`
+
+---
+
+## Socratic Questioning (MANDATORY)
+
+**Triggers**: "ask me questions", "question me", "help me think through", or any request to be questioned.
+
+Pi has no built-in structured question tool — render each batch as compact numbered questions in plain text, each with 2–4 lettered options plus an `Other:` line, then STOP and wait for the user's answers. Derive 2–4 context-specific questions per batch. Iteratively deepen based on answers. Converge toward decisions. After 4–5 rounds, synthesize and propose next steps. Route insights to `/reflect`.
+
+**Rules:** Max 4 questions per batch. When choices aren't mutually exclusive, say "pick any that apply".
+
+---
+
+## Telemetry
+
+Privacy-respecting, opt-out telemetry. After every slash command, emit fire-and-forget:
+`bash bin/telemetry.sh emit "command" '{"command":"save"}' 2>/dev/null &`
+
+Never collected: file contents, code, env var values, conversation content.
+Command events may carry optional model/tier/routing/duration fields per `.claude/context/telemetry.md`.
+On first session (if `telemetry_noticed` not set in state file), mention the notice once, then set `telemetry_noticed: true`. Full spec: `.claude/context/telemetry.md`.
+
+---
+
+## Mode
+
+Egregore runs in one of two configurations, set by `mode` in `egregore.json`. Detect with `_detect_mode` in `bin/lib/config.sh`, or check `.mode` / `.api_url` directly.
+
+**Local mode** (`"mode": "local"` or no `api_url`) — the default, self-contained configuration. The OSS experience. Memory files are the source of truth. All core commands work: `/reflect`, `/handoff`, `/quest`, `/ask`, `/activity`, `/dashboard`, `/todo`. Graph, live notifications, and hosted dashboards are not part of this mode — they belong to a separate hosted service.
+
+**Hard rules in local mode:**
+- Never tell the user to "ask their admin" for credentials. The user IS the admin.
+- Never surface `api_url`, `EGREGORE_API_KEY`, or "connected mode" as an upgrade path. Hosted Egregore is a separate service, not something a user can turn on by adding fields to `egregore.json`.
+- If a feature genuinely requires the hosted service, say so plainly ("this isn't available in this configuration") and stop. Do not improvise a path to enabling it.
+- Calling `bin/graph.sh` or `bin/notify.sh` in local mode is harmless — they fail soft and return empty results — but there is no need to call them; prefer reading `memory/` directly.
+
+**Connected mode** (`"mode": "connected"`, `api_url` set) — the hosted configuration, used by organizations on the hosted service. Full feature set: Neo4j knowledge graph via `bin/graph.sh`, Telegram notifications via `bin/notify.sh`, dashboard publication, API-backed context gathering on session start. Use `/env` to check API key, `/checkup` for diagnostics. If the graph is offline, show troubleshooting.
+
+---
+
+## Environment Isolation
+
+Sessions are confined to this project + memory + managed repos. On Pi this boundary is a standing instruction, not an enforced hook — hold it yourself.
+
+- **Never modify `~/.egregore/instances.json`** — managed by session-start.sh
+- **Never access another instance's files** — refuse even if asked
+- When a request points outside the boundary, do not improvise a workaround. Ask in plain text with numbered options:
+
+  ```text
+  That path is outside this Egregore's boundary. How should we proceed?
+    1. Paste the contents inline
+    2. Move the file into the repo and point me at the new path
+    3. Cancel
+  ```
+
+See DEVELOPMENT.md §3 for boundary details.

package/runtime/pi/.pi/extensions/egregore.ts

@@ -0,0 +1,324 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { isMutatingBash } from "../../bin/pi-branch-policy.mjs";
+import {
+  createHandoff,
+  parseViewRequest,
+  publishScroll,
+  renderActivity,
+  renderGreeting,
+  renderView,
+  workflowPrompt,
+} from "../../bin/pi-product-workflows.mjs";
+
+const PROTECTED_BRANCHES = new Set(["main", "master", "develop"]);
+const BUILTIN_COMMANDS = new Set([
+  "login", "logout", "model", "settings", "resume", "new", "name",
+  "session", "tree", "trust", "fork", "clone", "compact", "copy",
+  "export", "import", "share", "reload", "hotkeys", "changelog", "quit",
+]);
+const PRODUCT_COMMANDS = new Set(["activity", "view", "handoff", "scroll"]);
+
+function skillDescription(skillFile) {
+  try {
+    const body = readFileSync(skillFile, "utf8");
+    return body.match(/^description:\s*['"]?(.+?)['"]?\s*$/m)?.[1] || "Run an Egregore workflow";
+  } catch {
+    return "Run an Egregore workflow";
+  }
+}
+
+function messageText(result) {
+  return (result?.content || [])
+    .filter((item) => item?.type === "text")
+    .map((item) => item.text)
+    .join("\n");
+}
+
+function compactToolResult(result, options, theme, working) {
+  if (options.isPartial) return new Text(theme.fg("muted", working), 0, 0);
+  const text = result?.details?.text || messageText(result) || "Done";
+  return new Text(result?.details?.text ? text : theme.fg("error", text), 0, 0);
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export default function egregore(pi) {
+  const root = process.cwd();
+  const skillsDir = join(root, ".codex", "skills");
+  let workflowCount = 0;
+  let lastSyncAt = 0;
+  let activeWorkflow = "";
+  const hasEntryRenderer = typeof pi.registerEntryRenderer === "function";
+
+  const appendCard = (kind, text) => {
+    const content = String(text || "").trimEnd();
+    if (hasEntryRenderer) {
+      pi.appendEntry("egregore-card", { kind, text: content });
+      return;
+    }
+    pi.sendMessage({
+      customType: "egregore-card",
+      content,
+      display: true,
+      details: { kind },
+    }, { triggerTurn: false });
+  };
+
+  const setBusy = (ctx, label) => {
+    if (!ctx.hasUI) return;
+    ctx.ui.setStatus("egregore-workflow", label ? `● ${label}` : undefined);
+  };
+
+  const sendQuietWorkflow = (name, args, ctx, options = {}) => {
+    activeWorkflow = name;
+    if (ctx.hasUI) {
+      ctx.ui.setToolsExpanded?.(false);
+      ctx.ui.setWorkingMessage?.(options.working || `Running /${name}…`);
+    }
+    const content = options.prompt || workflowPrompt(name, args, options.extra || "");
+    if (typeof pi.sendMessage === "function") {
+      pi.sendMessage({
+        customType: "egregore-workflow",
+        content,
+        display: false,
+        details: { command: name },
+      }, { triggerTurn: true, deliverAs: "steer" });
+    } else {
+      pi.sendUserMessage(content);
+    }
+  };
+
+  if (hasEntryRenderer) {
+    pi.registerEntryRenderer("egregore-card", (entry) => {
+      return new Text(String(entry.data?.text || ""), 0, 0);
+    });
+  } else if (typeof pi.registerMessageRenderer === "function") {
+    pi.registerMessageRenderer("egregore-card", (message) => {
+      return new Text(String(message.content || ""), 0, 0);
+    });
+  }
+
+  pi.registerTool({
+    name: "egregore_handoff",
+    label: "Egregore Handoff",
+    description: "Create one internal Egregore team handoff from structured session context. Use only for the /handoff workflow.",
+    parameters: Type.Object({
+      topic: Type.String({ description: "Short operational topic" }),
+      recipient: Type.Optional(Type.String({ description: "Known teammate handle; omit when uncertain" })),
+      briefing: Type.String({ description: "Concise operational briefing" }),
+      key_decisions: Type.String({ description: "Markdown bullets of settled decisions" }),
+      current_state: Type.String({ description: "Exact implementation and verification state" }),
+      open_threads: Type.String({ description: "Markdown bullets of unresolved work" }),
+      next_steps: Type.String({ description: "Ordered, actionable next steps" }),
+      entry_points: Type.String({ description: "Exact files, branches, commands, and URLs" }),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const receipt = await createHandoff(pi, root, params, signal);
+      return {
+        content: [{ type: "text", text: `Handoff created${receipt.path ? ` at ${receipt.path}` : ""}.` }],
+        details: { ...receipt },
+      };
+    },
+    renderCall(_args, theme) {
+      return new Text(theme.fg("muted", "⇌ Preparing handoff…"), 0, 0);
+    },
+    renderResult(result, options, theme) {
+      return compactToolResult(result, options, theme, "⇌ Preparing handoff…");
+    },
+  });
+
+  pi.registerTool({
+    name: "egregore_publish_scroll",
+    label: "Publish Egregore Scroll",
+    description: "Validate, publish, open, and receipt a completed Egregore scroll. Use only as the final action of /scroll.",
+    parameters: Type.Object({
+      source: Type.String({ description: "Project-relative tmp/<slug>/index.html source" }),
+      slug: Type.String({ description: "Stable scroll id reused across versions" }),
+      title: Type.String(),
+      author: Type.String(),
+      description: Type.String(),
+      version: Type.String({ description: "Version marker such as v1" }),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const receipt = await publishScroll(pi, root, params, signal);
+      return {
+        content: [{ type: "text", text: `Scroll ${receipt.version} opened at ${receipt.url || receipt.path}.` }],
+        details: { ...receipt },
+      };
+    },
+    renderCall(_args, theme) {
+      return new Text(theme.fg("muted", "◉ Publishing scroll…"), 0, 0);
+    },
+    renderResult(result, options, theme) {
+      return compactToolResult(result, options, theme, "◉ Publishing scroll…");
+    },
+  });
+
+  if (existsSync(skillsDir)) {
+    for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || BUILTIN_COMMANDS.has(entry.name)) continue;
+      const skillFile = join(skillsDir, entry.name, "SKILL.md");
+      if (!existsSync(skillFile)) continue;
+      workflowCount += 1;
+      if (PRODUCT_COMMANDS.has(entry.name)) continue;
+      pi.registerCommand(entry.name, {
+        description: skillDescription(skillFile),
+        handler: async (args, ctx) => sendQuietWorkflow(entry.name, args, ctx),
+      });
+    }
+  }
+
+  pi.registerCommand("activity", {
+    description: skillDescription(join(skillsDir, "activity", "SKILL.md")),
+    handler: async (_args, ctx) => {
+      setBusy(ctx, "Refreshing activity");
+      try {
+        const shouldSync = Date.now() - lastSyncAt > 60_000;
+        const card = await renderActivity(pi, root, ctx.signal, { sync: shouldSync });
+        lastSyncAt = Date.now();
+        appendCard("activity", card);
+      } catch (error) {
+        ctx.ui.notify(`Activity: ${errorMessage(error)}`, "error");
+        return;
+      } finally {
+        setBusy(ctx, "");
+      }
+
+      if (!ctx.hasUI) return;
+      const focus = await ctx.ui.select("Focus", ["Handoffs", "Questions", "Recent work", "Dashboard", "Done"]);
+      if (!focus || focus === "Done") return;
+      const command = focus === "Dashboard" ? "dashboard" : "activity";
+      const prompt = focus === "Dashboard"
+        ? workflowPrompt("dashboard", "")
+        : `Continue the Egregore /activity workflow with focus: ${focus.toLowerCase()}. Work quietly and show only the designed result.`;
+      sendQuietWorkflow(command, "", ctx, { prompt, working: `Opening ${focus.toLowerCase()}…` });
+    },
+  });
+
+  pi.registerCommand("view", {
+    description: skillDescription(join(skillsDir, "view", "SKILL.md")),
+    handler: async (args, ctx) => {
+      let request = parseViewRequest(root, args);
+      if (request.kind === "choose" && ctx.hasUI) {
+        const choice = await ctx.ui.select("Open a view", ["Activity", "Board", "Network", "Document or topic…"]);
+        if (!choice) return;
+        if (choice === "Document or topic…") {
+          const target = await ctx.ui.input("Document or topic", "path, handoff, quest, or subject");
+          if (!target) return;
+          request = parseViewRequest(root, target);
+        } else {
+          request = parseViewRequest(root, choice.toLowerCase());
+        }
+      }
+
+      if (request.kind === "choose-file" && ctx.hasUI) {
+        const labels = request.matches.map((file) => relative(root, file));
+        const selected = await ctx.ui.select("Choose a source", labels);
+        if (!selected) return;
+        request = { kind: "native", type: request.type, source: join(root, selected), fast: request.fast };
+      }
+
+      if (request.kind !== "native") {
+        sendQuietWorkflow("view", args, ctx, {
+          working: "Composing view…",
+          extra: "Open the browser artifact and return only the compact receipt required by the skill.",
+        });
+        return;
+      }
+
+      setBusy(ctx, "Opening view");
+      try {
+        const receipt = await renderView(pi, root, request, ctx.signal);
+        appendCard("view", receipt.text);
+      } catch (error) {
+        ctx.ui.notify(`View: ${errorMessage(error)}`, "error");
+      } finally {
+        setBusy(ctx, "");
+      }
+    },
+  });
+
+  pi.registerCommand("handoff", {
+    description: skillDescription(join(skillsDir, "handoff", "SKILL.md")),
+    handler: async (args, ctx) => {
+      const people = existsSync(join(root, "memory", "people"))
+        ? readdirSync(join(root, "memory", "people"))
+          .filter((name) => name.endsWith(".md") && name !== "README.md")
+          .map((name) => name.replace(/\.md$/, ""))
+          .slice(0, 40)
+        : [];
+      const prompt = [
+        "Create the requested internal Egregore handoff from the current conversation and repository context.",
+        "Call egregore_handoff exactly once. Do not call bash, write, edit, or read the handoff skill; the tool implements the full contract.",
+        "Keep every field concise and operational. Include exact files, branch, commands, open questions, and verification state.",
+        "Omit recipient when uncertain. Do not use the deprecated egregore-handoff CLI.",
+        args?.trim() ? `User arguments: ${args.trim()}` : "Infer the topic and intended recipient from the conversation.",
+        people.length ? `Known teammate handles: ${people.join(", ")}` : "",
+        "After the tool succeeds, do not repeat its card or add a success preamble.",
+      ].filter(Boolean).join("\n");
+      sendQuietWorkflow("handoff", args, ctx, { prompt, working: "Preparing handoff…" });
+    },
+  });
+
+  pi.registerCommand("scroll", {
+    description: skillDescription(join(skillsDir, "scroll", "SKILL.md")),
+    handler: async (args, ctx) => {
+      sendQuietWorkflow("scroll", args, ctx, {
+        working: "Composing scroll…",
+        extra: [
+          "Use egregore_publish_scroll exactly once as the final validation, publish, open, and receipt step.",
+          "Do not run publish-artifact.sh or a browser opener directly.",
+          "Return only what changed, the stable URL or local path, the source path, and the versioned decision fence.",
+        ].join("\n"),
+      });
+    },
+  });
+
+  pi.on("session_start", async (event, ctx) => {
+    if (!ctx.hasUI) return;
+    ctx.ui.setToolsExpanded?.(false);
+    if (workflowCount > 0) ctx.ui.setStatus("egregore", `Egregore · ${workflowCount} workflows`);
+    if (event.reason !== "startup") return;
+
+    setBusy(ctx, "Loading team context");
+    try {
+      const card = await renderGreeting(pi, root, ctx.signal);
+      lastSyncAt = Date.now();
+      appendCard("greeting", card);
+    } catch (error) {
+      ctx.ui.notify(`Startup: ${errorMessage(error)}`, "warning");
+    } finally {
+      setBusy(ctx, "");
+    }
+  });
+
+  pi.on("agent_settled", async (_event, ctx) => {
+    if (!activeWorkflow || !ctx.hasUI) return;
+    activeWorkflow = "";
+    ctx.ui.setWorkingMessage?.();
+    ctx.ui.setToolsExpanded?.(false);
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    const mutates = event.toolName === "write" || event.toolName === "edit" ||
+      (event.toolName === "bash" && isMutatingBash(String(event.input?.command || "")));
+    if (!mutates) return;
+
+    const result = await pi.exec("git", ["-C", ctx.cwd, "branch", "--show-current"], { timeout: 5000 });
+    const branch = String(result.stdout || "").trim();
+    if (!PROTECTED_BRANCHES.has(branch)) return;
+
+    const consentFile = join(ctx.cwd, ".egregore-branch-consent");
+    if (existsSync(consentFile) && readFileSync(consentFile, "utf8").trim() === branch) return;
+
+    return {
+      block: true,
+      reason: `Protected branch (${branch}). Create a task worktree first with: bin/agent.sh branch --topic "<work topic>". Only if the user explicitly authorizes writing on ${branch}, record it with: echo '${branch}' > .egregore-branch-consent`,
+    };
+  });
+}

package/runtime/pi/.pi/settings.json

@@ -0,0 +1,6 @@
+{
+  "quietStartup": true,
+  "skills": [
+    "../.codex/skills"
+  ]
+}

package/runtime/pi/.pi/spec-manifest.json

@@ -0,0 +1,12 @@
+{
+  "generatedBy": "bin/pi-render-spec.mjs",
+  "source": "AGENTS.md generated Codex spec",
+  "sourceHash": "4c268f3ebb13",
+  "outputHash": "2d0d2ac65e04",
+  "adaptations": [
+    "Pi project trust and APPEND_SYSTEM delivery",
+    "Pi tool_call branch gate",
+    "Pi slash-command extension over shared portable skills",
+    "plain-text question fallback and direct shell/network execution"
+  ]
+}