@jaybeeuu/agent-cortex 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 2.4.0
+
+### Minor Changes
+
+- 0b72348: The extensions now load outside this checkout. `auto-name`, `notify`, `subagent` and `agent-modes`
+  value-imported `@earendil-works/pi-*`, which resolved only inside the repository, where pnpm had
+  installed each extension's own copy of pi's packages. The staged pi package carried no such
+  `node_modules`, so after `agent-cortex install pi` those four extensions failed to load for every
+  project outside this checkout — `subagent` included, which is the dispatcher ralph uses.
+
+  The runtime coupling is gone: frontmatter parsing, pi's user agent directory, the key helper and the
+  transcript components are now local, and the extensions declare no peer dependency on pi's packages. Two
+  callers lose their model-backed behaviour, since an extension has no completion API of its own:
+  `auto-name` names a session from its first prompt truncated (the fallback it already had) and
+  `notify` summarises with that same truncation. Subagent output renders as plain text instead of
+  markdown.
+
+  One bare runtime import remains: `typebox`. pi documents it as a host-provided module for
+  extensions and aliases it in its loader, so it resolves in the staged package. Everything imported
+  from `@earendil-works/*` is `import type`, which is erased. `test/pi-extensions-load.test.mjs`
+  stages the package and loads every extension from a temp directory with pi absent. A static scan in
+  the same file then rejects any value import from `@earendil-works/*` — including an unused one, which
+  tsx elides before the loader sees it.
+
+## 2.3.0
+
+### Minor Changes
+
+- 3dd1e20: Sync a behind branch by rebasing it onto its base branch, not by merging the base in. The
+  `git-workflow` skill previously told agents to merge the base in, which dragged every intervening
+  commit into the review diff and left a merge commit behind; rule 6 now says fetch, rebase onto
+  `origin/main` (or `epic/<id>` for a feature branch inside an epic), and force-push with
+  `--force-with-lease`. Rewritten commits are re-signed automatically by `commit.gpgsign`, so no
+  `--gpg-sign` and no `rebase.gpgSign` is needed. The rule is scoped to your own unmerged branch —
+  never `main`, never a branch someone else is working on — with one stated exception: a shared
+  integration branch that other branches are based on is synced by merging the base in, because
+  rewriting it would rewrite history under every branch based on it. Landing is unchanged:
+  squash-merge still governs how a branch reaches `main`, so the two decisions can no longer be read
+  as one rule. `AGENTS.md` splits its collapsed "Landing method" bullet into those two decisions
+  accordingly.
+
+### Patch Changes
+
+- 9944bca: Retire `docs/ideas/` now that ideas are `kind:idea` beads. The four remaining idea files that had
+  never been migrated were recorded as beads, and the directory was deleted, so ideas have a single
+  home. Live references to the deleted paths now cite the originating bead instead; `agent-cortex
+migrate` step v2 still reads `docs/ideas/` as a migration source, which is unchanged.
+
 ## 2.2.0
 
 ### Minor Changes

package/README.md

@@ -201,7 +201,7 @@ The staged package contains:
 | `package.json` | pi manifest — `keywords: ["pi-package"]`, `pi.extensions` + `pi.skills`; the version tracks the package |
 | `agents/` | composed flat agents (ralph, plan, ralph-plan, strategy) with `{{TOOL:...}}` / `{{PATH:...}}` substituted — the shipped `agent-modes` extension resolves them from the package root |
 | `skills/` | token-substituted skill copies (real files, never symlinks) |
-| `extensions/` | copy of the repo `extensions/` tree |
+| `extensions/` | copy of the repo `extensions/` tree — imports nothing from pi's runtime except the host-aliased `typebox`, so pi loads it from any directory |
 | `token-map.json` | the token map `agent-modes` reads from the package root |
 | `node_modules/` | the required third-party pi packages and their transitive closure |
 

package/bin/installers/pi.mjs

@@ -405,10 +405,13 @@ async function installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, wa
 /**
  * Copy the repo's extensions/ tree into the staged package verbatim.
  *
- * The extensions import `@earendil-works/*`, which pi's loader supplies, so no
- * dependency tree is needed. `node_modules` (pnpm workspace links) and symlinks
- * are never copied: the staged package owns its dependencies and must contain
- * real files only.
+ * The extensions import nothing from pi's runtime — only `import type`, which is
+ * erased, and the one module pi documents as host-provided (`typebox`) — so no
+ * dependency tree of their own is needed. A value import of `@earendil-works/*`
+ * would only resolve where pnpm installed it and would break the staged package
+ * everywhere else, which test/pi-extensions-load.test.mjs guards. `node_modules`
+ * (pnpm workspace links) and symlinks are never copied: the staged package owns
+ * its dependencies and must contain real files only.
  * @param {{ root: string, output: string, dryRun: boolean }} options
  * @returns {Promise<{ files: number, dir: string }>}
  */

package/extensions/agent-guardrails/package.json

@@ -12,8 +12,5 @@
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.78.1"
   }
 }

package/extensions/agent-modes/index.ts

@@ -23,7 +23,6 @@
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Key } from "@earendil-works/pi-tui";
 import { discoverAgents, DEFAULT_TOOLS, type AgentDef } from "./discover.ts";
 import type { ThemeColor } from "@earendil-works/pi-coding-agent";
 
@@ -196,8 +195,10 @@ export default function agentModesExtension(pi: ExtensionAPI): void {
       },
     });
 
-    // Ctrl+Shift+A to cycle agents (A = Agent)
-    pi.registerShortcut(Key.ctrlShift("a"), {
+    // Ctrl+Shift+A to cycle agents (A = Agent). Spelled out rather than built
+    // with pi-tui's Key helper: a value import of pi-tui stops the extension
+    // loading outside the agent-cortex checkout (test/pi-extensions-load.test.mjs).
+    pi.registerShortcut("ctrl+shift+a", {
       description: "Next agent mode",
       handler: async (ctx) => {
         const next = (activeAgentIndex + 1) % (agents.length + 1);

package/extensions/agent-modes/package.json

@@ -9,12 +9,8 @@
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.78.1",
-    "@earendil-works/pi-tui": "^0.78.1",
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.78.1"
   }
-}
+}

package/extensions/auto-name.ts

@@ -1,30 +1,29 @@
 /**
- * Auto-name sessions using a tiny side-agent LLM.
+ * Auto-name sessions from the first user prompt.
  *
- * On the first user prompt of a new session, calls a cheap configured model
- * (default: opencode/mimo-v2.5-free) to generate a concise session title,
- * then sets it via pi.setSessionName(). Falls back to simple truncation if
- * the LLM call fails.
+ * On the first prompt of a new session, names the session with a trimmed
+ * version of that prompt, then sets it via pi.setSessionName(). Existing names
+ * (set via --name or /name) are never overwritten.
+ *
+ * The name used to come from a cheap side-model, which needed pi-ai's
+ * `complete()` — a value import that stopped this extension loading outside the
+ * agent-cortex checkout (see test/pi-extensions-load.test.mjs). The truncation
+ * that already served as its fallback is now the only path; `tinyModel.enabled`
+ * still turns naming off entirely.
  *
  * Config (in settings.json under `tinyModel`):
  * ```json
  * {
  *   "tinyModel": {
- *     "model": "opencode/mimo-v2.5-free",
+ *     "enabled": true,
  *     "maxNameLength": 50
  *   }
  * }
  * ```
- *
- * Existing names (set via --name or /name) are never overwritten.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import {
-  loadTinyModelConfig,
-  parseModelString,
-  generateNameFromPrompt,
-} from "./lib/tiny-model.js";
+import { loadTinyModelConfig } from "./lib/tiny-model.js";
 import type { TinyModelConfig } from "./lib/tiny-model.js";
 
 export default function (pi: ExtensionAPI) {
@@ -41,7 +40,7 @@ export default function (pi: ExtensionAPI) {
     }
   });
 
-  pi.on("input", async (event, ctx) => {
+  pi.on("input", async (event, _ctx) => {
     if (!config.enabled || hasNamed) return;
     if (event.source === "rpc") return;
     if (pi.getSessionName()) {
@@ -51,46 +50,14 @@ export default function (pi: ExtensionAPI) {
     if (!event.text?.trim()) return;
 
     hasNamed = true;
-
-    // Fire the LLM call asynchronously — don't block the agent
-    (async () => {
-      try {
-        const { provider, id } = parseModelString(config.model);
-        const model = ctx.modelRegistry.find(provider, id);
-        if (!model) {
-          // Model not found; fall back to truncation
-          fallbackName(event.text, config.maxNameLength, pi);
-          return;
-        }
-
-        const { apiKey, headers } =
-          await ctx.modelRegistry.getApiKeyAndHeaders(model);
-
-        const name = await generateNameFromPrompt(
-          model,
-          apiKey,
-          headers,
-          event.text,
-          config.maxNameLength,
-        );
-
-        if (name) {
-          pi.setSessionName(name);
-        } else {
-          fallbackName(event.text, config.maxNameLength, pi);
-        }
-      } catch (err) {
-        console.warn("[auto-name] LLM call failed, falling back:", err);
-        fallbackName(event.text, config.maxNameLength, pi);
-      }
-    })();
+    nameFromPrompt(event.text, config.maxNameLength, pi);
   });
 }
 
 /**
- * Fallback: truncate the first line of the prompt to use as a session name.
+ * Name the session with the first line of the prompt, truncated to `maxLength`.
  */
-function fallbackName(
+function nameFromPrompt(
   text: string,
   maxLength: number,
   pi: ExtensionAPI,

package/extensions/lib/tiny-model.ts

@@ -1,43 +1,45 @@
 /**
- * Shared helpers for making cheap LLM calls from extensions.
+ * The `tinyModel` config block shared by the extensions that used to call a
+ * cheap side-model: session naming (auto-name) and response summaries (notify).
  *
- * Reads a `tinyModel` config key from settings.json (global + project merged)
- * and provides functions for session naming and response summarization using
- * the configured model — typically the tiniest free model available.
- *
- * Config (in ~/.pi/agent/settings.json or .pi/settings.json):
+ * Reads the key from settings.json (global + project merged):
  * ```json
  * {
  *   "tinyModel": {
- *     "model": "opencode/mimo-v2.5-free",
+ *     "enabled": true,
  *     "maxNameLength": 50,
  *     "maxSummaryLength": 100
  *   }
  * }
  * ```
+ *
+ * The model call itself is gone. It went through pi-ai's `complete()`, a value
+ * import of pi's runtime, and that import stopped the extension loading outside
+ * the agent-cortex checkout (see test/pi-extensions-load.test.mjs). The
+ * ExtensionAPI promises no completion call. Newer hosts (pi 1.4.0) expose
+ * `ModelRegistry.complete`, but the installed host (0.73.1) does not. Calling it
+ * would need an untyped cast to a method that exists on one version only.
+ * Extensions also make no internal LLM calls (AGENTS.md), so this feature stays
+ * off. Both callers fall back to the truncation they already used when the model
+ * failed. The `model` key is no longer read and is ignored if present.
  */
 
-import { complete } from "@earendil-works/pi-ai";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { readFileSync, existsSync } from "node:fs";
-import type { Model, Api } from "@earendil-works/pi-ai";
 
 /* ── Types ── */
 
 export interface TinyModelConfig {
-  /** Provider/id string, e.g. "opencode/mimo-v2.5-free" */
-  model: string;
   /** Global on/off toggle */
   enabled: boolean;
-  /** Max characters for auto-generated session names */
+  /** Max characters for generated session names */
   maxNameLength: number;
   /** Max characters for response summaries in notifications */
   maxSummaryLength: number;
 }
 
 const DEFAULT_CONFIG: TinyModelConfig = {
-  model: "opencode/mimo-v2.5-free",
   enabled: true,
   maxNameLength: 40,
   maxSummaryLength: 100,
@@ -72,141 +74,3 @@ export function loadTinyModelConfig(cwd?: string): TinyModelConfig {
 
   return { ...DEFAULT_CONFIG, ...merged } as TinyModelConfig;
 }
-
-/**
- * Parse a "provider/id" string into its parts.
- */
-export function parseModelString(modelStr: string): {
-  provider: string;
-  id: string;
-} {
-  const slash = modelStr.indexOf("/");
-  if (slash === -1) return { provider: "opencode", id: modelStr };
-  return {
-    provider: modelStr.slice(0, slash),
-    id: modelStr.slice(slash + 1),
-  };
-}
-
-/* ── LLM helpers ── */
-
-type ModelAny = Model<Api>;
-type CompleteOptions = Record<string, any>;
-
-/**
- * Generate a concise session title from the user's first prompt.
- *
- * Calls the configured tiny model with a system prompt tuned for naming.
- * Returns null on failure (caller should fall back to truncation).
- */
-export async function generateNameFromPrompt(
-  model: ModelAny,
-  apiKey: string | undefined,
-  headers: Record<string, string> | undefined,
-  prompt: string,
-  maxLength: number,
-): Promise<string | null> {
-  const systemPrompt = [
-    "You are a session naming assistant. Generate a concise title for a coding session.",
-    "",
-    "Rules:",
-    "- Output ONLY the title, no quotes, no prefix, no explanation",
-    `- Maximum ${maxLength} characters`,
-    "- Summarize intent, do not copy verbatim",
-    "- Keep it short (3\u20135 words), capture the general theme",
-    "- If the message mentions files or modules, keep the key names brief",
-  ].join("\n");
-
-  const truncated = prompt.length > 2000 ? prompt.slice(0, 2000) + "..." : prompt;
-
-  try {
-    const options: CompleteOptions = { maxTokens: 64 };
-    if (apiKey) options.apiKey = apiKey;
-    if (headers) options.headers = headers;
-
-    const result = await complete(model, {
-      systemPrompt,
-      messages: [{ role: "user", content: truncated, timestamp: Date.now() }],
-    }, options);
-
-    const text = result.content
-      ?.filter((b: any): b is { type: "text"; text: string } => b.type === "text")
-      ?.map((b) => b.text)
-      ?.join("")
-      ?.trim() ?? "";
-
-    return cleanTitle(text, maxLength);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Summarize an assistant response into a one-line summary.
- *
- * Calls the configured tiny model. Returns null on failure.
- */
-export async function summarizeResponseText(
-  model: ModelAny,
-  apiKey: string | undefined,
-  headers: Record<string, string> | undefined,
-  responseText: string,
-  maxLength: number,
-): Promise<string | null> {
-  const systemPrompt = [
-    "Summarize what the AI assistant did in this coding session response.",
-    "Be concise — one short sentence or phrase.",
-    `Maximum ${maxLength} characters.`,
-    "Focus on what changed or was accomplished.",
-    "Output ONLY the summary, no quotes, no prefix, no explanation.",
-  ].join("\n");
-
-  const truncated =
-    responseText.length > 2000 ? responseText.slice(0, 2000) + "..." : responseText;
-
-  try {
-    const options: CompleteOptions = { maxTokens: 64 };
-    if (apiKey) options.apiKey = apiKey;
-    if (headers) options.headers = headers;
-
-    const result = await complete(model, {
-      systemPrompt,
-      messages: [{ role: "user", content: truncated, timestamp: Date.now() }],
-    }, options);
-
-    const text = result.content
-      ?.filter((b: any): b is { type: "text"; text: string } => b.type === "text")
-      ?.map((b) => b.text)
-      ?.join("")
-      ?.trim() ?? "";
-
-    return text || null;
-  } catch {
-    return null;
-  }
-}
-
-/* ── Internal helpers ── */
-
-function cleanTitle(raw: string, maxLength: number): string | null {
-  let name = raw.trim();
-  if (!name) return null;
-
-  // Strip surrounding quotes if present
-  if (
-    (name.startsWith('"') && name.endsWith('"')) ||
-    (name.startsWith("'") && name.endsWith("'"))
-  ) {
-    name = name.slice(1, -1);
-  }
-
-  // Collapse newlines
-  name = name.replace(/\n/g, " ").trim();
-
-  // Truncate
-  if (name.length > maxLength) {
-    name = name.slice(0, maxLength - 3) + "...";
-  }
-
-  return name || null;
-}

package/extensions/notify/index.ts

@@ -5,13 +5,16 @@
  * multiline notification showing:
  *   Line 1: working directory path
  *   Line 2: session name (if set)
- *   Line 3: LLM-generated summary of what the agent did
+ *   Line 3: truncated summary of what the agent did
  *
  * The notification title is the tmux session:window.pane identifier (when
  * available) or "pi".
  *
- * Response summarization uses the tiny model configured in settings.json
- * under the `tinyModel` key.
+ * The summary used to come from a cheap side-model, which needed pi-ai's
+ * `complete()` — a value import that stopped this extension loading outside the
+ * agent-cortex checkout (see test/pi-extensions-load.test.mjs). The truncation
+ * that already served as its fallback is now the only path; `maxSummaryLength`
+ * still sets its length.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -19,11 +22,7 @@ import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import { execSync } from "node:child_process";
 import { homedir } from "node:os";
 
-import {
-  loadTinyModelConfig,
-  parseModelString,
-  summarizeResponseText,
-} from "../lib/tiny-model.js";
+import { loadTinyModelConfig } from "../lib/tiny-model.js";
 import type { TinyModelConfig } from "../lib/tiny-model.js";
 
 /* ── Context helpers ── */
@@ -215,20 +214,10 @@ export default function (pi: ExtensionAPI) {
     const sessionName = pi.getSessionName();
     if (sessionName) sections.push(sessionName);
 
-    // Section 2: LLM-generated summary of the assistant's response
+    // Section 2: truncated summary of the assistant's response
     const responseText = extractAssistantText(event.messages);
     if (responseText) {
-      try {
-        const summary = await summarizeResponseWithFallback(
-          ctx,
-          responseText,
-          config,
-        );
-        sections.push(summary);
-      } catch {
-        // If summary fails (e.g. config not loaded), just show raw text
-        sections.push(responseText.slice(0, config?.maxSummaryLength ?? 100).replace(/\s+/g, ' ').trim());
-      }
+      sections.push(truncateToOneLine(responseText, config?.maxSummaryLength ?? 100));
     }
 
     // Desktop notification
@@ -239,45 +228,6 @@ export default function (pi: ExtensionAPI) {
   });
 }
 
-/**
- * Summarize response text using the configured tiny model, falling back
- * to simple truncation if the LLM call fails or is disabled.
- */
-async function summarizeResponseWithFallback(
-  ctx: any,
-  responseText: string,
-  config: TinyModelConfig,
-): Promise<string> {
-  if (!config.enabled) {
-    return truncateToOneLine(responseText, config.maxSummaryLength);
-  }
-
-  try {
-    const { provider, id } = parseModelString(config.model);
-    const model = ctx.modelRegistry.find(provider, id);
-    if (!model) {
-      return truncateToOneLine(responseText, config.maxSummaryLength);
-    }
-
-    const { apiKey, headers } =
-      await ctx.modelRegistry.getApiKeyAndHeaders(model);
-
-    const summary = await summarizeResponseText(
-      model,
-      apiKey,
-      headers,
-      responseText,
-      config.maxSummaryLength,
-    );
-
-    if (summary) return summary;
-  } catch (err) {
-    console.warn("[notify] LLM summary failed, falling back:", err);
-  }
-
-  return truncateToOneLine(responseText, config.maxSummaryLength);
-}
-
 /**
  * Truncate text to roughly `maxLen` characters on a single line,
  * breaking at a word boundary.

package/extensions/output-style/README.md

@@ -2,7 +2,7 @@
 
 Appends the always-on reply shape to the PI system prompt once per user prompt.
 
-This is the second slice of `docs/ideas/improve-pi-system-prompt.md`: the first
+This is the second slice of the "Improve PI System Prompt" idea (bead `agnt-ctx-s5hn`): the first
 (`agent-guardrails`) stops wasted work; this one stops the answer getting buried in
 it. The extension injects a stable block via the `before_agent_start` hook — which
 fires once per user prompt, before the agent loop — so the rules apply to every

package/extensions/output-style/index.ts

@@ -3,8 +3,8 @@
  *
  * Appends the always-on reply shape to the PI system prompt on every turn: lead
  * with the action, write in Simplified Technical English (ASD-STE100), restate the
- * context the reader cannot remember (the second slice of
- * docs/ideas/improve-pi-system-prompt.md).
+ * context the reader cannot remember (the second slice of the "Improve PI
+ * System Prompt" idea, bead `agnt-ctx-s5hn`).
  *
  * The block is stable text appended after any chained system-prompt changes, so it
  * keeps the prompt-cache prefix intact while remaining authoritative for the model.

package/extensions/output-style/output-style.ts

@@ -1,8 +1,8 @@
 /**
  * Output style for the PI system prompt.
  *
- * The second slice of docs/ideas/improve-pi-system-prompt.md: the reply shape, not
- * the task discipline. Three concerns, in order — lead with the action, write in
+ * The second slice of the "Improve PI System Prompt" idea (bead `agnt-ctx-s5hn`): the reply
+ * shape, not the task discipline. Three concerns, in order — lead with the action, write in
  * Simplified Technical English, restate the context the reader cannot remember.
  *
  * The prose lives in output-style.md so one file feeds both harnesses: this

package/extensions/output-style/package.json

@@ -12,8 +12,5 @@
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.78.1"
   }
 }

package/extensions/session-start/package.json

@@ -12,8 +12,5 @@
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.78.1"
   }
 }

package/extensions/skill-stats/package.json

@@ -12,8 +12,5 @@
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.78.1"
   }
 }

package/extensions/subagent/README.md

@@ -7,7 +7,7 @@ Delegate tasks to specialized subagents with isolated context windows.
 - **Isolated context**: Each subagent runs in a separate `pi` process
 - **Streaming output**: See tool calls and progress as they happen
 - **Parallel streaming**: All parallel tasks stream updates simultaneously
-- **Markdown rendering**: Final output rendered with proper formatting (expanded view)
+- **Plain-text output**: Final output wrapped to the terminal width (expanded view)
 - **Usage tracking**: Shows turns, tokens, cost, and context usage per agent
 - **Abort support**: Ctrl+C propagates to kill subagent processes
 
@@ -125,7 +125,7 @@ pending `wait_for_agents` returns immediately with whatever is known so far.
 **Expanded view** (Ctrl+O):
 - Full task text
 - All tool calls with formatted arguments
-- Final output rendered as Markdown
+- Final output rendered as width-wrapped plain text
 - Per-task usage (for chain/parallel)
 
 **Parallel mode streaming**:

package/extensions/subagent/agents.ts

@@ -3,9 +3,10 @@
  */
 
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { parseFrontmatter } from "./frontmatter.ts";
 
 export type AgentScope = "user" | "project" | "both";
 
@@ -145,6 +146,21 @@ function isRenderedAgentsTree(agentsDir: string): boolean {
 	return !entries.some((entry) => entry.isDirectory() && fs.existsSync(path.join(agentsDir, entry.name, "agent.md")));
 }
 
+/**
+ * pi's user config directory, which holds pi's own `agents/` directory.
+ *
+ * Read here rather than through `getAgentDir()` from
+ * `@earendil-works/pi-coding-agent`: a value import of pi's runtime makes this
+ * extension fail to load outside the agent-cortex checkout
+ * (test/pi-extensions-load.test.mjs). Same contract — `PI_CODING_AGENT_DIR`
+ * wins when set, otherwise `~/.pi/agent`.
+ */
+function getAgentDir(): string {
+	const override = process.env.PI_CODING_AGENT_DIR;
+	if (override) return path.resolve(override.replace(/^~(?=$|[\\/])/, os.homedir()));
+	return path.join(os.homedir(), ".pi", "agent");
+}
+
 /**
  * Directories the "user" scope discovers agents from, in precedence order.
  *

package/extensions/subagent/components.test.ts

@@ -0,0 +1,111 @@
+/**
+ * The local transcript components pi's renderers draw for the subagent tool.
+ *
+ * pi-tui's own components are unreachable from an installed extension, so these
+ * implement pi's `Component` contract directly. The contract that matters is the
+ * width: pi-tui reports a rendered line wider than the terminal as an error, so
+ * every line these return must fit the width they are given, with SGR colour
+ * sequences still intact.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { Container, Spacer, Text } from "./components.ts";
+
+const RESET = "\x1b[0m";
+const GREEN = "\x1b[32m";
+
+/** Visible column count, ignoring SGR sequences. */
+function visibleWidth(line: string): number {
+	return line.replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+
+/**
+ * Visible terminal-cell count, ignoring SGR sequences and counting a wide or
+ * astral character as two cells. `String.length` counts a wide character as one
+ * unit, so a width assertion built on it misses the overflow this guards.
+ */
+function cellWidth(line: string): number {
+	return [...line.replace(/\x1b\[[0-9;]*m/g, "")].reduce((cells, character) => {
+		const codePoint = character.codePointAt(0) ?? 0;
+		const wide =
+			codePoint > 0xffff ||
+			(codePoint >= 0x1100 &&
+				(codePoint <= 0x115f ||
+					(codePoint >= 0x2e80 && codePoint <= 0xa4cf) ||
+					(codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+					(codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+					(codePoint >= 0xfe30 && codePoint <= 0xfe6f) ||
+					(codePoint >= 0xff00 && codePoint <= 0xff60) ||
+					(codePoint >= 0xffe0 && codePoint <= 0xffe6)));
+		return cells + (wide ? 2 : 1);
+	}, 0);
+}
+
+describe("Text", () => {
+	it("wraps a long line to the width it is given", () => {
+		const lines = new Text("alpha beta gamma delta").render(11);
+
+		assert.deepEqual(lines, ["alpha beta", "gamma delta"]);
+		assert.ok(lines.every((line) => visibleWidth(line) <= 11));
+	});
+
+	it("hard-wraps a word longer than the width instead of overflowing", () => {
+		const lines = new Text("abcdefghij").render(4);
+
+		assert.deepEqual(lines, ["abcd", "efgh", "ij"]);
+	});
+
+	it("keeps a colour sequence intact and carries it onto the wrapped line", () => {
+		const lines = new Text(`${GREEN}alpha beta gamma${RESET}`).render(11);
+
+		assert.equal(lines.length, 2);
+		for (const line of lines) assert.ok(visibleWidth(line) <= 11, `width of ${JSON.stringify(line)}`);
+		assert.ok(lines[0].endsWith(RESET), "a line cut inside a colour span closes it");
+		assert.ok(lines[1].startsWith(GREEN), "the continuation reopens the colour");
+		assert.equal(lines.map((line) => line.replace(/\x1b\[[0-9;]*m/g, "")).join(" "), "alpha beta gamma");
+	});
+
+	it("pads and separates lines with the padding it is given", () => {
+		const lines = new Text("body", 1, 1).render(10);
+
+		assert.deepEqual(lines, ["  ", " body ", "  "]);
+	});
+
+	it("keeps an empty line and renders blank text as one empty line", () => {
+		assert.deepEqual(new Text("a\n\nb").render(10), ["a", "", "b"]);
+		assert.deepEqual(new Text().render(10), [""]);
+	});
+
+	it("counts a wide character as two cells so it cannot overflow the width", () => {
+		// Each of these characters occupies two terminal cells but one string unit.
+		assert.deepEqual(new Text("日本語").render(4), ["日本", "語"]);
+
+		const lines = new Text("日本語のテキストは全角文字です。これは折り返しのテストです。").render(20);
+		assert.ok(lines.length > 1, "wide text must wrap");
+		for (const line of lines) assert.ok(cellWidth(line) <= 20, `width of ${JSON.stringify(line)}`);
+	});
+
+	it("counts an astral character as two cells", () => {
+		assert.deepEqual(new Text("🚀🚀🚀").render(4), ["🚀🚀", "🚀"]);
+	});
+});
+
+describe("Spacer", () => {
+	it("renders the blank lines it was asked for", () => {
+		assert.deepEqual(new Spacer(2).render(10), ["", ""]);
+		assert.deepEqual(new Spacer().render(10), [""]);
+	});
+});
+
+describe("Container", () => {
+	it("draws its children in order, each at the given width", () => {
+		const container = new Container();
+		container.addChild(new Text("alpha beta"));
+		container.addChild(new Spacer(1));
+		container.addChild(new Text("gamma"));
+
+		assert.deepEqual(container.render(5), ["alpha", "beta", "", "gamma"]);
+	});
+});

package/extensions/subagent/components.ts

@@ -0,0 +1,182 @@
+/**
+ * Transcript components for the subagent tool's renderers.
+ *
+ * pi-tui's `Text`, `Container` and `Spacer` are not reachable from an installed
+ * extension: a value import of `@earendil-works/pi-tui` makes the extension fail
+ * to load outside the agent-cortex checkout (test/pi-extensions-load.test.mjs).
+ * These are the local equivalents, implementing the `Component` contract pi's
+ * transcript renderer calls: `render(width)` returns lines that fit `width`, and
+ * `invalidate()` drops cached layout.
+ *
+ * Two deliberate limits, because reimplementing pi-tui is not this change:
+ * markdown is drawn as plain text, and only SGR colour sequences (`ESC[…m`) are
+ * measured and carried across a wrapped line. Other escapes — OSC-8 hyperlinks,
+ * images — count as visible characters, the same way a naive strip does.
+ * Width is measured in terminal cells: a wide (East Asian) character, and any
+ * astral character such as an emoji, counts as two.
+ */
+
+/** Lines to draw at a given width — what pi's transcript renderer calls. */
+export interface Component {
+  render(width: number): string[];
+  invalidate(): void;
+}
+
+const SGR = /\x1b\[[0-9;]*m/g;
+const SGR_AT = /\x1b\[[0-9;]*m/y;
+const RESET = "\x1b[0m";
+
+/** A block of text, word-wrapped to the width it is drawn at. */
+export class Text implements Component {
+  readonly #text: string;
+  readonly #paddingX: number;
+  readonly #paddingY: number;
+
+  constructor(text = "", paddingX = 0, paddingY = 0) {
+    this.#text = text;
+    this.#paddingX = paddingX;
+    this.#paddingY = paddingY;
+  }
+
+  render(width: number): string[] {
+    const available = Math.max(1, width - this.#paddingX * 2);
+    const indent = " ".repeat(this.#paddingX);
+    const blank = indent.repeat(2);
+    const body = this.#text.split("\n").flatMap((line) => wrapLine(line, available));
+
+    return [
+      ...emptyLines(this.#paddingY, blank),
+      ...body.map((line) => `${indent}${line}${indent}`),
+      ...emptyLines(this.#paddingY, blank),
+    ];
+  }
+
+  invalidate(): void {}
+}
+
+/** Blank lines. */
+export class Spacer implements Component {
+  readonly #lines: number;
+
+  constructor(lines = 1) {
+    this.#lines = lines;
+  }
+
+  render(_width: number): string[] {
+    return emptyLines(this.#lines, "");
+  }
+
+  invalidate(): void {}
+}
+
+/** A vertical stack of components. */
+export class Container implements Component {
+  readonly #children: Component[] = [];
+
+  addChild(child: Component): void {
+    this.#children.push(child);
+  }
+
+  render(width: number): string[] {
+    return this.#children.flatMap((child) => child.render(width));
+  }
+
+  invalidate(): void {
+    for (const child of this.#children) child.invalidate();
+  }
+}
+
+/** `count` blank lines, each filled with `filler` (padding keeps the width). */
+function emptyLines(count: number, filler: string): string[] {
+  return Array.from({ length: Math.max(0, count) }, () => filler);
+}
+
+/** Visible cell count of a line: everything except SGR sequences, wide characters as two. */
+function visibleWidth(line: string): number {
+  let cells = 0;
+  for (const character of line.replace(SGR, "")) cells += cellWidth(character.codePointAt(0) ?? 0);
+  return cells;
+}
+
+/**
+ * Terminal cells one character occupies. Wide East Asian characters and astral
+ * characters (emoji included) occupy two; every other character occupies one.
+ * Counting in `String.length` units would let a wide character overflow: it is
+ * one unit but two cells.
+ */
+function cellWidth(codePoint: number): number {
+  if (codePoint > 0xffff) return 2;
+  return codePoint >= 0x1100 &&
+    (codePoint <= 0x115f ||
+      (codePoint >= 0x2e80 && codePoint <= 0xa4cf) ||
+      (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+      (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+      (codePoint >= 0xfe30 && codePoint <= 0xfe6f) ||
+      (codePoint >= 0xff00 && codePoint <= 0xff60) ||
+      (codePoint >= 0xffe0 && codePoint <= 0xffe6))
+    ? 2
+    : 1;
+}
+
+/**
+ * Wrap one line to `width` visible columns without cutting an SGR sequence. A
+ * cut inside a coloured span closes the line and reopens the same colour on the
+ * continuation, so broken escapes never reach the terminal.
+ */
+function wrapLine(line: string, width: number): string[] {
+  const lines: string[] = [];
+  let rest = line;
+
+  while (visibleWidth(rest) > width) {
+    const cut = breakIndex(rest, width);
+    if (cut <= 0) break;
+
+    const head = rest.slice(0, cut);
+    const colour = lastColour(head);
+    lines.push(colour === "" ? head : `${head}${RESET}`);
+    // A break taken at a space consumes it, so the continuation starts with its word.
+    rest = `${colour}${rest.slice(rest[cut] === " " ? cut + 1 : cut)}`;
+  }
+
+  lines.push(rest);
+  return lines;
+}
+
+/**
+ * Index at which to cut `text` so its visible width stays within `width`:
+ * the last space at or before the limit, or the limit itself when the line has
+ * no usable space.
+ */
+function breakIndex(text: string, width: number): number {
+  let visible = 0;
+  let lastSpace = -1;
+  let index = 0;
+
+  while (index < text.length) {
+    SGR_AT.lastIndex = index;
+    const escape = SGR_AT.exec(text);
+    if (escape !== null) {
+      index += escape[0].length;
+      continue;
+    }
+
+    const codePoint = text.codePointAt(index) ?? 0;
+    const character = String.fromCodePoint(codePoint);
+    if (character === " ") lastSpace = index;
+    if (visible + cellWidth(codePoint) > width) return lastSpace > 0 ? lastSpace : index;
+
+    visible += cellWidth(codePoint);
+    index += character.length;
+  }
+
+  return lastSpace > 0 ? lastSpace : index;
+}
+
+/** The colour sequence left open at the end of `text`, or "" when none is. */
+function lastColour(text: string): string {
+  let colour = "";
+  for (const [sequence] of text.matchAll(SGR)) {
+    colour = sequence === RESET || sequence === "\x1b[m" ? "" : sequence;
+  }
+  return colour;
+}

package/extensions/subagent/frontmatter.test.ts

@@ -0,0 +1,74 @@
+/**
+ * The local frontmatter reader for agent files.
+ *
+ * pi's `parseFrontmatter` is unreachable from an installed extension, so this
+ * parser reads the subset agent files use. Agents are user-authored files at a
+ * system edge: a field this parser mishandles silently changes an agent's name,
+ * description or tool list, and an exception here would break discovery of every
+ * other agent, so both the parsing and the tolerance are covered.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { parseFrontmatter } from "./frontmatter.ts";
+
+describe("parseFrontmatter", () => {
+	it("splits fields from the body and trims the body", () => {
+		const { frontmatter, body } = parseFrontmatter(`---\nname: ralph\ndescription: d\n---\n\n# ralph\n`);
+
+		assert.deepEqual(frontmatter, { name: "ralph", description: "d" });
+		assert.equal(body, "# ralph");
+	});
+
+	it("reads a quoted scalar, unescaping it", () => {
+		const { frontmatter } = parseFrontmatter(`---\nname: "a: b\\"c\\n"\n---\n`);
+
+		assert.equal(frontmatter.name, 'a: b"c\n');
+	});
+
+	it("reads a flow sequence of quoted items", () => {
+		const { frontmatter } = parseFrontmatter(`---\ntools: ["bash", "read"]\n---\n`);
+
+		assert.deepEqual(frontmatter.tools, ["bash", "read"]);
+	});
+
+	it("reads a block sequence", () => {
+		const { frontmatter } = parseFrontmatter(`---\ntools:\n  - bash\n  - read\n---\n`);
+
+		assert.deepEqual(frontmatter.tools, ["bash", "read"]);
+	});
+
+	it("keeps a comma-separated tool list as one scalar", () => {
+		const { frontmatter } = parseFrontmatter(`---\ntools: "bash, read"\n---\n`);
+
+		assert.equal(frontmatter.tools, "bash, read");
+	});
+
+	it("separates fields from a following block sequence", () => {
+		const { frontmatter } = parseFrontmatter(`---\nname: ralph\ntools:\n  - bash\nmodel: fast\n---\n`);
+
+		assert.deepEqual(frontmatter, { name: "ralph", tools: ["bash"], model: "fast" });
+	});
+
+	it("normalises CRLF line endings", () => {
+		const { frontmatter, body } = parseFrontmatter(`---\r\nname: ralph\r\n---\r\n\r\nbody\r\n`);
+
+		assert.deepEqual(frontmatter, { name: "ralph" });
+		assert.equal(body, "body");
+	});
+
+	it("returns the whole document as body when there is no frontmatter", () => {
+		const { frontmatter, body } = parseFrontmatter("# just markdown\n");
+
+		assert.deepEqual(frontmatter, {});
+		assert.equal(body, "# just markdown\n");
+	});
+
+	it("treats an unclosed block as body rather than throwing", () => {
+		const { frontmatter, body } = parseFrontmatter(`---\nname: ralph\n`);
+
+		assert.deepEqual(frontmatter, {});
+		assert.equal(body, "---\nname: ralph\n");
+	});
+});

package/extensions/subagent/frontmatter.ts

@@ -0,0 +1,105 @@
+/**
+ * Read the YAML frontmatter block of a markdown document.
+ *
+ * pi's own `parseFrontmatter` is not reachable from an installed extension: a
+ * value import of `@earendil-works/pi-coding-agent` makes the extension fail to
+ * load outside the agent-cortex checkout (test/pi-extensions-load.test.mjs).
+ * This module is the subset agent files use — top-level `key: value` pairs,
+ * plain and quoted scalars, flow sequences (`[a, b]`) and block sequences
+ * (`- a`).
+ *
+ * Deliberately outside the subset: nested maps and block scalars (`|`, `>`) keep
+ * their literal text as the value. No construct throws — an unreadable block
+ * yields empty frontmatter — so one malformed agent file cannot break discovery
+ * of the others.
+ */
+
+/** A parsed document: its frontmatter fields and the markdown body. */
+export interface ParsedFrontmatter<T extends Record<string, unknown>> {
+  frontmatter: T;
+  body: string;
+}
+
+const FENCE = "---";
+
+/**
+ * Split a markdown document into frontmatter fields and body, matching pi's
+ * contract: the document must open with `---` and close the block with a line
+ * that starts with `---`; the body is trimmed.
+ */
+export function parseFrontmatter<T extends Record<string, unknown>>(content: string): ParsedFrontmatter<T> {
+  const normalized = content.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
+  const end = normalized.startsWith(FENCE) ? normalized.indexOf(`\n${FENCE}`, FENCE.length) : -1;
+  if (end === -1) return { frontmatter: {} as T, body: normalized };
+
+  return {
+    frontmatter: parseBlock(normalized.slice(FENCE.length + 1, end)) as T,
+    body: normalized.slice(end + FENCE.length + 1).trim(),
+  };
+}
+
+/** Parse the `key: value` lines of a frontmatter block. */
+function parseBlock(block: string): Record<string, unknown> {
+  const fields: Record<string, unknown> = {};
+  const lines = block.split("\n");
+
+  for (let index = 0; index < lines.length; index++) {
+    const match = /^([\w.-]+):(?:[ \t]+(.*))?$/.exec(lines[index]);
+    if (match === null) continue;
+
+    const [, key, inlineValue] = match;
+    if (inlineValue !== undefined && inlineValue.trim() !== "") {
+      fields[key] = parseValue(inlineValue.trim());
+      continue;
+    }
+
+    const { items, consumed } = readBlockSequence(lines, index + 1);
+    index += consumed;
+    fields[key] = items.length > 0 ? items : null;
+  }
+
+  return fields;
+}
+
+/**
+ * Read the indented `- item` lines that follow a `key:` line with no inline
+ * value. Returns the items and how many lines were consumed.
+ */
+function readBlockSequence(lines: string[], start: number): { items: string[]; consumed: number } {
+  const items: string[] = [];
+  let consumed = 0;
+
+  for (let index = start; index < lines.length; index++) {
+    const match = /^[ \t]+-[ \t]+(.*)$/.exec(lines[index]);
+    if (match === null) break;
+
+    const value = parseValue(match[1].trim());
+    items.push(typeof value === "string" ? value : String(value));
+    consumed++;
+  }
+
+  return { items, consumed };
+}
+
+/** Parse one scalar or flow sequence. */
+function parseValue(raw: string): unknown {
+  if (raw.startsWith("[") && raw.endsWith("]")) {
+    return raw
+      .slice(1, -1)
+      .split(",")
+      .map((item) => item.trim())
+      .filter(Boolean)
+      .map(parseValue);
+  }
+  if (raw.startsWith('"')) return unquote(raw, '"', (text) => text.replace(/\\(["\\/nrt])/g, (_, escape: string) => {
+    return escape === "n" ? "\n" : escape === "r" ? "\r" : escape === "t" ? "\t" : escape;
+  }));
+  if (raw.startsWith("'")) return unquote(raw, "'", (text) => text.replace(/''/g, "'"));
+  return raw;
+}
+
+/** Strip a matching quote pair and unescape the content; an unterminated quote keeps the raw text. */
+function unquote(raw: string, quote: string, unescape: (text: string) => string): string {
+  if (raw.length < 2 || !raw.endsWith(quote)) return raw;
+  return unescape(raw.slice(1, -1));
+}

package/extensions/subagent/index.ts

@@ -21,8 +21,13 @@ import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { Message } from "@earendil-works/pi-ai";
 import { type AgentConfig, type AgentScope, discoverAgents } from "./agents.ts";
 import { waitForAgents } from "./wait.ts";
-import { type ExtensionAPI, getMarkdownTheme, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
-import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Container, Spacer, Text } from "./components.ts";
+// `typebox` is the one bare runtime import an extension may make: pi documents
+// it as host-provided and its loader aliases it (pi's docs/packages.md), so it
+// resolves in the staged package too. Every `@earendil-works/*` import here is
+// `import type`, which is erased; a value import of pi's runtime breaks the
+// package outside this checkout (test/pi-extensions-load.test.mjs).
 import { Type } from "typebox";
 
 
@@ -236,9 +241,8 @@ async function writePromptToTempFile(agentName: string, prompt: string): Promise
 	const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-subagent-"));
 	const safeName = agentName.replace(/[^\w.-]+/g, "_");
 	const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
-	await withFileMutationQueue(filePath, async () => {
-		await fs.promises.writeFile(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
-	});
+	// No mutation queue: the directory is fresh per call, so nothing else writes this file.
+	await fs.promises.writeFile(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
 	return { dir: tmpDir, filePath };
 }
 
@@ -746,8 +750,6 @@ export default function (pi: ExtensionAPI) {
 				return new Text(text?.type === "text" ? text.text : "(no output)", 0, 0);
 			}
 
-			const mdTheme = getMarkdownTheme();
-
 			const renderDisplayItems = (items: DisplayItem[], limit?: number) => {
 				const toShow = limit ? items.slice(-limit) : items;
 				const skipped = limit && items.length > limit ? items.length - limit : 0;
@@ -798,7 +800,7 @@ export default function (pi: ExtensionAPI) {
 						}
 						if (finalOutput) {
 							container.addChild(new Spacer(1));
-							container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
+							container.addChild(new Text(finalOutput.trim(), 0, 0));
 						}
 					}
 					const usageStr = formatUsageStats(r.usage, r.model);
@@ -880,10 +882,10 @@ export default function (pi: ExtensionAPI) {
 							}
 						}
 
-						// Show final output as markdown
+						// Show final output as plain text
 						if (finalOutput) {
 							container.addChild(new Spacer(1));
-							container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
+							container.addChild(new Text(finalOutput.trim(), 0, 0));
 						}
 
 						const stepUsage = formatUsageStats(r.usage, r.model);
@@ -965,10 +967,10 @@ export default function (pi: ExtensionAPI) {
 							}
 						}
 
-						// Show final output as markdown
+						// Show final output as plain text
 						if (finalOutput) {
 							container.addChild(new Spacer(1));
-							container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
+							container.addChild(new Text(finalOutput.trim(), 0, 0));
 						}
 
 						const taskUsage = formatUsageStats(r.usage, r.model);

package/extensions/subagent/package.json

@@ -4,20 +4,19 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "test": "node --test --import tsx/esm wait.test.ts agents.test.ts",
+    "test": "node --test --import tsx/esm wait.test.ts agents.test.ts frontmatter.test.ts components.test.ts",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
     "@earendil-works/pi-agent-core": "^0.78.1",
     "@earendil-works/pi-ai": "^0.78.1",
     "@earendil-works/pi-coding-agent": "^0.78.1",
-    "@earendil-works/pi-tui": "^0.78.1",
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typebox": "^1.1.38",
     "typescript": "^5.0.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.78.1"
+    "typebox": "*"
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"

package/skills/workflow/git-workflow/SKILL.md

@@ -90,39 +90,41 @@ git pull
 
 This avoids avoidable merge conflicts.
 
-### 6. Bring a behind branch up to date — merge, don't rebase
+### 6. Bring a behind branch up to date — rebase, don't merge
 
-When the base branch moves and the PR reports `BEHIND` or `CONFLICTING`, update
-the branch before anything else:
+When the base branch moves and the PR reports `BEHIND` or `CONFLICTING`, rebase
+your branch onto its base branch before anything else — never merge the base in:
 
 ```bash
 git fetch origin
-git merge origin/main
+git rebase origin/main        # or epic/<id> for a feature branch inside an epic
+git push --force-with-lease
 ```
 
-**Never rebase a branch that contains a merge commit.** `git rebase` drops merge
-commits and the patches they carry, so rebasing a branch that already merged the
-base silently reverts what that merge resolved — the conflict resolutions, and
-any fix from the base the merge brought in. The result usually looks like a
-regression in your own change. `--rebase-merges` preserves the structure, but
-it re-opens the same conflicts; only worth it when the branch's history is
-itself the deliverable.
-
-Rebase only a **linear branch that has not been reviewed yet**. Rewriting
-commits under review discards the review context and invalidates approvals, and
-it requires `git push --force-with-lease` — never `--force`, which overwrites
-work you have not seen.
-
-Which one you owe the repository depends on its landing method, not on taste:
-
-- **Squash merge**: the branch is collapsed on landing, so its shape never
-  reaches the base branch. Merge the base in and move on — rebasing here is
-  cosmetic, and the risky kind of cosmetic.
-- **Rebase-and-merge**: a linear branch is mandatory, so rebase *before* the
-  first review. Once a merge has landed on the branch, that option is gone.
-
-After any update, re-run the checks. A merge that resolved conflicts by hand is
-not verified by the base branch's green CI.
+A merge from the base drags every intervening commit into the review diff and,
+under a squash-merge landing method, contributes nothing that reaches the base
+branch. Landing is still a squash merge; rebasing only reshapes *your* branch
+before it lands, so these are separate decisions, not rivals. Keeping the branch
+linear is what makes the rebase safe: `git rebase` drops merge commits and the
+patches they resolved, so never rebase a branch that already merged the base.
+
+One exception: an **integration branch** that other branches are based on
+(`main`, or an `epic/<id>` branch) is not yours to rewrite. Sync it by merging
+the base in — under squash-merge that merge never reaches the landing diff, and
+the branches based on it stay linear by rebasing onto it.
+
+Rewritten commits are re-signed automatically when `commit.gpgsign` is set. Pass
+no `--gpg-sign`, and do not set `rebase.gpgSign` — both are redundant.
+
+Scope: rebase only your **own unmerged feature branch**. Never rebase `main` or an
+`epic/<id>` branch others are based on, and never rebase a branch another person
+or agent is working on — it discards their context and invalidates review.
+Force-push with `--force-with-lease`, never `--force`, which overwrites work you
+have not seen. Rewriting a reviewed branch discards the review context and
+invalidates approvals, so re-request review after a sync.
+
+After any update, re-run the checks: a conflict resolved by hand is not verified
+by the base branch's green CI.
 
 ### 7. Worktree lifecycle