@bastani/atomic 0.8.25 → 0.8.26-alpha.10

package/docs/sdk.md

@@ -39,22 +39,29 @@ await session.prompt("What files are in the current directory?");
 
 ## Installation
 
-Choose npm, Bun, or pnpm:
+Install `@bastani/atomic` as a project dependency with npm, pnpm, or Bun:
+
+With npm:
 
 ```bash
-# npm
 npm install @bastani/atomic
+```
 
-# Bun
-bun add @bastani/atomic
+With pnpm:
 
-# pnpm
+```bash
 pnpm add @bastani/atomic
 ```
 
+With Bun:
+
+```bash
+bun add @bastani/atomic
+```
+
 Atomic does not require package install scripts. If you want to disable dependency lifecycle scripts during the Atomic install, you can add `--ignore-scripts` to the install command.
 
-The SDK is included in the main package. No separate installation needed.
+The SDK is included in the main package. No separate SDK package is needed.
 
 ## Core Concepts
 
@@ -116,8 +123,8 @@ interface AgentSession {
   // In-place tree navigation within the current session file
   navigateTree(targetId: string, options?: { summarize?: boolean; customInstructions?: string; replaceInstructions?: boolean; label?: string }): Promise<{ editorText?: string; cancelled: boolean }>;
 
-  // Compaction
-  compact(customInstructions?: string): Promise<CompactionResult>;
+  // Verbatim Compaction (deletion-only Context Compaction)
+  compact(): Promise<ContextCompactionResult>;
   abortCompaction(): void;
 
   // Abort current operation
@@ -128,6 +135,8 @@ interface AgentSession {
 }
 ```
 
+`compact()` accepts no custom summary instructions. It runs the same transcript-bound Verbatim Compaction planner as `/compact`: inspect transcript slices, record exact deletion targets, validate them locally, append a `context_compaction` entry, and rebuild active context with retained content unchanged.
+
 Session replacement APIs such as new-session, resume, fork, and import live on `AgentSessionRuntime`, not on `AgentSession`.
 
 ### createAgentSessionRuntime() and AgentSessionRuntime

package/docs/session-format.md

@@ -28,13 +28,11 @@ Existing sessions are automatically migrated to the current version (v3) when lo
 
 ## Source Files
 
-Source on GitHub ([pi-mono](https://github.com/earendil-works/pi-mono)):
-- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/session-manager.ts) - Session entry types and SessionManager
-- [`packages/coding-agent/src/core/messages.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/messages.ts) - Extended message types (BashExecutionMessage, CustomMessage, etc.)
-- [`packages/ai/src/types.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/types.ts) - Base message types (UserMessage, AssistantMessage, ToolResultMessage)
-- [`packages/agent/src/types.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/agent/src/types.ts) - AgentMessage union type
+Source on GitHub ([atomic](https://github.com/bastani-inc/atomic)):
+- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/session-manager.ts) - Session entry types and SessionManager
+- [`packages/coding-agent/src/core/messages.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/messages.ts) - Extended message types (BashExecutionMessage, CustomMessage, etc.)
 
-For TypeScript definitions in your project, inspect `node_modules/@bastani/atomic/dist/` and `node_modules/@earendil-works/pi-ai/dist/`.
+Base message and agent event types are provided by Atomic's installed runtime dependencies (`@earendil-works/pi-ai` and `@earendil-works/pi-agent-core`), not by separate `packages/ai` or `packages/agent` directories in this monorepo. For TypeScript definitions in your project, inspect `node_modules/@bastani/atomic/dist/`, `node_modules/@earendil-works/pi-ai/dist/`, and `node_modules/@earendil-works/pi-agent-core/dist/`.
 
 ## Message Types
 
@@ -69,7 +67,7 @@ interface ToolCall {
 }
 ```
 
-### Base Message Types (from pi-ai)
+### Base Message Types (from `@earendil-works/pi-ai`)
 
 ```typescript
 interface UserMessage {
@@ -116,7 +114,7 @@ interface Usage {
 }
 ```
 
-### Extended Message Types (from pi-coding-agent)
+### Extended Message Types (from Atomic coding-agent)
 
 ```typescript
 interface BashExecutionMessage {
@@ -225,7 +223,7 @@ Emitted when the user changes the thinking/reasoning level.
 
 ### CompactionEntry
 
-Created when context is compacted. Stores a summary of earlier messages.
+Legacy summary-compaction entry. Stores a generated summary of earlier messages for older APIs and extension hooks. Default `/compact` and auto-compaction now create `ContextCompactionEntry` records instead.
 
 ```json
 {"type":"compaction","id":"f6g7h8i9","parentId":"e5f6g7h8","timestamp":"2024-12-03T14:10:00.000Z","summary":"User discussed X, Y, Z...","firstKeptEntryId":"c3d4e5f6","tokensBefore":50000}
@@ -233,7 +231,17 @@ Created when context is compacted. Stores a summary of earlier messages.
 
 Optional fields:
 - `details`: Implementation-specific data (e.g., `{ readFiles: string[], modifiedFiles: string[] }` for default, or custom data for extensions)
-- `fromHook`: `true` if generated by an extension, `false`/`undefined` if pi-generated (legacy field name)
+- `fromHook`: `true` if generated by an extension, `false`/`undefined` if Atomic-generated (legacy field name)
+
+### ContextCompactionEntry
+
+Created by `/compact`, RPC compaction commands, and auto-compaction. Stores Atomic's default **Verbatim Compaction** data: validated logical deletion targets, not replacement text. The internal planner can search/read transcript slices and record exact entry/content-block targets with transcript-bound tools; Atomic validates those targets locally before saving. During `buildSessionContext()`, matching entries/content blocks are filtered from active LLM context while retained content remains verbatim. This deletion-only Context Compaction approach is informed by Morph's write-up at [Morph's Context Compaction](https://www.morphllm.com/context-compaction).
+
+```json
+{"type":"context_compaction","id":"ctx12345","parentId":"f6g7h8i9","timestamp":"2024-12-03T14:12:00.000Z","promptVersion":1,"deletedTargets":[{"kind":"entry","entryId":"b2c3d4e5"}],"protectedEntryIds":["a1b2c3d4"],"stats":{"objectsBefore":20,"objectsAfter":19,"objectsDeleted":1,"tokensBefore":50000,"tokensAfter":43000,"percentReduction":14},"backupPath":"/path/session.jsonl.2024-12-03T14-12-00-000Z.compact.bak"}
+```
+
+`deletedTargets` entries are either whole entries (`{ kind: "entry", entryId }`) or content blocks (`{ kind: "content_block", entryId, blockIndex }`). The JSONL file remains append-only; this is logical deletion for active context rebuild.
 
 ### BranchSummaryEntry
 
@@ -245,7 +253,7 @@ Created when switching branches via `/tree` with an LLM generated summary of the
 
 Optional fields:
 - `details`: File tracking data (`{ readFiles: string[], modifiedFiles: string[] }`) for default, or custom data for extensions
-- `fromHook`: `true` if generated by an extension, `false`/`undefined` if pi-generated (legacy field name)
+- `fromHook`: `true` if generated by an extension, `false`/`undefined` if Atomic-generated (legacy field name)
 
 ### CustomEntry
 
@@ -314,7 +322,8 @@ Entries form a tree:
    - Emits the summary first
    - Then messages from `firstKeptEntryId` to compaction
    - Then messages after compaction
-4. Converts `BranchSummaryEntry` and `CustomMessageEntry` to appropriate message formats
+4. Applies `ContextCompactionEntry` logical deletions recorded after the latest summary compaction
+5. Converts `BranchSummaryEntry` and `CustomMessageEntry` to appropriate message formats
 
 ## Parsing Example
 
@@ -336,6 +345,9 @@ for (const line of lines) {
     case "compaction":
       console.log(`[${entry.id}] Compaction: ${entry.tokensBefore} tokens summarized`);
       break;
+    case "context_compaction":
+      console.log(`[${entry.id}] Context compaction: ${entry.stats.objectsDeleted} objects deleted`);
+      break;
     case "branch_summary":
       console.log(`[${entry.id}] Branch from ${entry.fromId}`);
       break;
@@ -382,7 +394,8 @@ Key methods for working with sessions programmatically.
 - `appendMessage(message)` - Add message
 - `appendThinkingLevelChange(level)` - Record thinking change
 - `appendModelChange(provider, modelId)` - Record model change
-- `appendCompaction(summary, firstKeptEntryId, tokensBefore, details?, fromHook?)` - Add compaction
+- `appendCompaction(summary, firstKeptEntryId, tokensBefore, details?, fromHook?)` - Add summary compaction
+- `appendContextCompaction(deletedTargets, protectedEntryIds, stats, backupPath?)` - Add logical deletion compaction
 - `appendCustomEntry(customType, data?)` - Extension state (not in context)
 - `appendSessionInfo(name)` - Set session display name
 - `appendCustomMessageEntry(customType, content, display, details?)` - Extension message (in context)

package/docs/sessions.md

@@ -29,7 +29,7 @@ For the JSONL file format and SessionManager API, see [Session Format](/session-
 | `/tree` | Navigate the current session tree |
 | `/fork` | Create a new session from a previous user message |
 | `/clone` | Duplicate the current active branch into a new session |
-| `/compact [prompt]` | Summarize older context; see [Compaction](/compaction) |
+| `/compact` | Apply Verbatim Compaction with transcript-bound, validated logical deletions; see [Compaction](/compaction) |
 | `/export [file]` | Export session to HTML |
 | `/share` | Upload as private GitHub gist with shareable HTML link |
 
@@ -128,10 +128,10 @@ When prompted, choose one of:
 2. summarize with the default prompt
 3. summarize with custom focus instructions
 
-See [Compaction](/compaction) for branch summarization internals and extension hooks.
+See [Compaction](/compaction) for Verbatim Compaction, branch summarization internals, and extension hooks.
 
 ## Session Format
 
-Session files are JSONL and contain message entries, model changes, thinking-level changes, labels, compactions, branch summaries, and extension entries.
+Session files are JSONL and contain message entries, model changes, thinking-level changes, labels, summary compactions, context compactions, branch summaries, and extension entries.
 
 For parsers, extensions, SDK usage, and the full SessionManager API, see [Session Format](/session-format).

package/docs/settings.md

@@ -90,9 +90,9 @@ Set `ATOMIC_SKIP_VERSION_CHECK=1` to disable the Atomic version update check. Us
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `compaction.enabled` | boolean | `true` | Enable auto-compaction |
+| `compaction.enabled` | boolean | `true` | Enable automatic Verbatim Compaction |
 | `compaction.reserveTokens` | number | `16384` | Tokens reserved for LLM response |
-| `compaction.keepRecentTokens` | number | `20000` | Recent tokens to keep (not summarized) |
+| `compaction.keepRecentTokens` | number | `20000` | Legacy summary-compaction retained-token budget; default Verbatim Compaction protects recent entries structurally |
 
 ```json
 {

package/docs/skills.md

@@ -116,16 +116,9 @@ description: What this skill does and when to use it. Be specific.
 
 ## Setup
 
-Run once before first use (choose one):
+Run once before first use:
 ```bash
-# npm
-cd /path/to/skill && npm install
-
-# Bun
 cd /path/to/skill && bun install
-
-# pnpm
-cd /path/to/skill && pnpm install
 ```
 
 ## Usage
@@ -216,14 +209,7 @@ description: Web search and content extraction via Brave Search API. Use for sea
 ## Setup
 
 ```bash
-# npm
-cd /path/to/brave-search && npm install
-
-# Bun
 cd /path/to/brave-search && bun install
-
-# pnpm
-cd /path/to/brave-search && pnpm install
 ```
 
 ## Search

package/docs/termux.md

@@ -16,16 +16,11 @@ pkg update && pkg upgrade
 # Install dependencies
 pkg install nodejs termux-api git
 
-# Install Atomic (choose one package manager available in Termux)
-# npm is installed by `pkg install nodejs`; Bun and pnpm must be installed separately before using those commands.
-# npm
+# Install Atomic with npm (included with Termux's nodejs package)
 npm install -g @bastani/atomic
 
-# Bun
-bun install -g @bastani/atomic
-
-# pnpm
-pnpm add -g @bastani/atomic
+# If you have installed Bun separately in Termux, you can use Bun instead:
+# bun add -g @bastani/atomic
 
 # Create config directory
 mkdir -p ~/.atomic/agent
@@ -129,9 +124,13 @@ Run once to grant storage permissions:
 termux-setup-storage
 ```
 
-### Node.js installation issues
+### Package installation issues
+
+Termux does not currently provide an official `pkg install bun` package. On a fresh Termux install, use npm from the `nodejs` package; use Bun only if you installed it separately for your device.
+
+If npm fails, try clearing the cache before retrying:
 
-If npm fails, try clearing the cache:
 ```bash
 npm cache clean --force
+npm install -g @bastani/atomic
 ```

package/docs/themes.md

@@ -52,7 +52,7 @@ vim ~/.atomic/agent/themes/my-theme.json
 
 ```json
 {
-  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "$schema": "https://raw.githubusercontent.com/bastani-inc/atomic/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
   "name": "my-theme",
   "vars": {
     "primary": "#00aaff",
@@ -122,7 +122,7 @@ vim ~/.atomic/agent/themes/my-theme.json
 
 ```json
 {
-  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "$schema": "https://raw.githubusercontent.com/bastani-inc/atomic/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
   "name": "my-theme",
   "vars": {
     "blue": "#0066cc",

package/docs/tmux.md

@@ -1,6 +1,6 @@
 # tmux Setup
 
-Pi works inside tmux, but tmux strips modifier information from certain keys by default. Without configuration, `SHIFT+Enter` and `CTRL+Enter` are usually indistinguishable from plain `Enter`.
+Atomic works inside tmux, but tmux strips modifier information from certain keys by default. Without configuration, `SHIFT+Enter` and `CTRL+Enter` are usually indistinguishable from plain `Enter`.
 
 ## Recommended Configuration
 
@@ -18,7 +18,7 @@ tmux kill-server
 tmux
 ```
 
-Pi requests extended key reporting automatically when Kitty keyboard protocol is not available. With `extended-keys-format csi-u`, tmux forwards modified keys in CSI-u format, which is the most reliable configuration.
+Atomic requests extended key reporting automatically when Kitty keyboard protocol is not available. With `extended-keys-format csi-u`, tmux forwards modified keys in CSI-u format, which is the most reliable configuration.
 
 ## Why `csi-u` Is Recommended
 
@@ -40,7 +40,7 @@ With `extended-keys-format csi-u`, the same keys are forwarded as:
 - `CTRL+D` → `\x1b[100;5u`
 - `CTRL+Enter` → `\x1b[13;5u`
 
-Pi supports both formats, but `csi-u` is the recommended tmux setup.
+Atomic supports both formats, but `csi-u` is the recommended tmux setup.
 
 ## What This Fixes
 

package/docs/tui.md

@@ -4,7 +4,7 @@
 
 Extensions and custom tools can render custom TUI components for interactive user interfaces. This page covers the component system and available building blocks.
 
-**Source:** [`@earendil-works/pi-tui`](https://github.com/earendil-works/pi-mono/tree/main/packages/tui)
+**Source:** TUI components are provided by Atomic's installed `@earendil-works/pi-tui` runtime dependency (`node_modules/@earendil-works/pi-tui/dist/`).
 
 ## Component Interface
 
@@ -86,27 +86,18 @@ Without this propagation, typing with an IME (Chinese, Japanese, Korean, etc.) w
 
 ## Using Components
 
-**In extensions** via `ctx.ui.custom()`:
+Use `ctx.ui.custom()` with a component factory. The factory receives `done(result)`, and `ctx.ui.custom()` resolves with that result when the component finishes:
 
 ```typescript
 pi.on("session_start", async (_event, ctx) => {
-  const handle = ctx.ui.custom(myComponent);
-  // handle.requestRender() - trigger re-render
-  // handle.close() - restore normal UI
+  const result = await ctx.ui.custom((tui, theme, keybindings, done) => {
+    return new MyComponent(done);
+  });
+  ctx.ui.notify(`Selected: ${result}`, "info");
 });
 ```
 
-**In custom tools** via `pi.ui.custom()`:
-
-```typescript
-async execute(toolCallId, params, onUpdate, ctx, signal) {
-  const handle = pi.ui.custom(myComponent);
-  // ...
-  handle.close();
-}
-```
-
-Pass `{ signal }` to `ctx.ui.custom()` when the UI belongs to an abortable tool or operation. If the signal aborts, Atomic dismisses the custom UI and rejects the returned promise with the signal reason.
+Pass `{ signal }` to `ctx.ui.custom()` when the UI belongs to an abortable operation. If the signal aborts, Atomic dismisses the custom UI and rejects the returned promise with the signal reason. For overlays, use `options.onHandle` to receive an overlay handle for programmatic visibility control.
 
 ## Overlays
 
@@ -371,20 +362,15 @@ pi.registerCommand("pick", {
     const items = ["Option A", "Option B", "Option C"];
     const selector = new MySelector(items);
     
-    let handle: { close: () => void; requestRender: () => void };
-    
-    await new Promise<void>((resolve) => {
-      selector.onSelect = (item) => {
-        ctx.ui.notify(`Selected: ${item}`, "info");
-        handle.close();
-        resolve();
-      };
-      selector.onCancel = () => {
-        handle.close();
-        resolve();
-      };
-      handle = ctx.ui.custom(selector);
+    const selected = await ctx.ui.custom<string | undefined>((_tui, _theme, _keybindings, done) => {
+      selector.onSelect = (item) => done(item);
+      selector.onCancel = () => done(undefined);
+      return selector;
     });
+
+    if (selected) {
+      ctx.ui.notify(`Selected: ${selected}`, "info");
+    }
   }
 });
 ```
@@ -450,10 +436,11 @@ interface MyTheme {
 Set `PI_TUI_WRITE_LOG` to capture the raw ANSI stream written to stdout.
 
 ```bash
-# Upstream pi-tui debug env example
-PI_TUI_WRITE_LOG=/tmp/tui-ansi.log bunx tsx packages/tui/test/chat-simple.ts
+PI_TUI_WRITE_LOG=/tmp/tui-ansi.log atomic
 ```
 
+Atomic vendors TUI components through the installed `@earendil-works/pi-tui` dependency; this monorepo does not include the upstream TUI test source tree.
+
 ## Performance
 
 Cache rendered output when possible:
@@ -480,7 +467,7 @@ class CachedComponent {
 }
 ```
 
-Call `invalidate()` when state changes, then `handle.requestRender()` to trigger re-render.
+Call `invalidate()` when state changes, then `ctx.ui.requestRender()` from the extension context or `tui.requestRender()` from a `ctx.ui.custom()` factory to trigger re-render.
 
 ## Invalidation and Theme Changes
 

package/docs/usage.md

@@ -48,7 +48,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/tree` | Jump to any point in the session and continue from there |
 | `/fork` | Create a new session from a previous user message |
 | `/clone` | Duplicate the current active branch into a new session |
-| `/compact [prompt]` | Manually compact context, optionally with custom instructions |
+| `/compact` | Run Verbatim Compaction with transcript-bound deletion tools |
 | `/copy` | Copy last assistant message to clipboard |
 | `/export [file]` | Export session to HTML |
 | `/share` | Upload as private GitHub gist with shareable HTML link |
@@ -89,7 +89,7 @@ Useful session commands:
 - `/tree` navigates the in-file session tree and can summarize abandoned branches.
 - `/fork` creates a new session from an earlier user message.
 - `/clone` duplicates the current active branch into a new session file.
-- `/compact` summarizes older messages to free context.
+- `/compact` uses Verbatim Compaction: a fixed no-argument deletion-only planner searches/reads transcript slices, records exact deletion targets, and applies only locally validated logical deletions. Retained transcript content stays verbatim. Atomic's approach is informed by Morph's Context Compaction article: [Morph's Context Compaction](https://www.morphllm.com/context-compaction).
 
 See [Sessions](/sessions) and [Compaction](/compaction) for details.
 

package/docs/workflows.md

@@ -153,8 +153,8 @@ For the builtin result tables below, `deep-research-codebase`, `goal`, and `ralp
 |---|---|---|
 | `deep-research-codebase` | Scout + research-history chain → parallel specialist waves → aggregator. Indexes the whole repo and synthesizes findings. | Broad or cross-cutting research before you decide what to change. Prefer `/skill:research-codebase` for one subsystem. |
 | `goal` | Persisted goal ledger → bounded worker turns → receipts → three-reviewer gate → deterministic reducer → final report. | Small-to-medium scope changes when you can identify the work surface, state the exact outcome, and name the validation that proves it is done — for example tests, lint/typecheck, docs builds, or observable behavior. |
-| `ralph` | RFC planning → sub-agent orchestration → simplification → parallel review → PR handoff. | Larger migrations, broad refactors, multi-package changes, and spec-to-PR work where you want Atomic to plan the approach, delegate implementation through sub-agents, simplify, review, iterate, and prepare a pull-request report. |
-| `open-claude-design` | Design-system onboarding → reference import → HTML generation → impeccable-driven refinement → quality gate → rich HTML handoff. Renders a live `preview.html` you can iterate against (opens through `browser-use` when available). | UI, page, component, theme, or design-token work that benefits from generation + critique loops. |
+| `ralph` | RFC planning → sub-agent orchestration → simplification → parallel review → optional final-stage PR handoff. | Larger migrations, broad refactors, multi-package changes, and spec-to-reviewed-change work where you want Atomic to plan the approach, delegate implementation through sub-agents, simplify, review, iterate, and optionally allow only the final `pull-request` stage to attempt PR creation with `create_pr=true`. |
+| `open-claude-design` | Design-system onboarding → reference import → HTML generation → impeccable-driven refinement → quality gate → rich HTML handoff. Renders a live `preview.html` you can iterate against (opens through `browser` when available). | UI, page, component, theme, or design-token work that benefits from generation + critique loops. |
 
 ### `deep-research-codebase`
 
@@ -248,20 +248,21 @@ Inputs:
 
 | Input | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `prompt` | text | yes | — | Task, feature request, issue summary, or spec path to plan, execute, refine, review, and prepare for PR. |
-| `max_loops` | number | no | `10` | Maximum plan/orchestrate/review iterations before the workflow proceeds to PR handoff without reviewer approval. |
-| `base_branch` | string | no | `origin/main` | Branch reviewers and the PR-prep stage compare the current code delta against; also used to create a missing worktree. |
+| `prompt` | text | yes | — | Task, feature request, issue summary, or spec path to plan, execute, refine, and review. |
+| `max_loops` | number | no | `10` | Maximum plan/orchestrate/review iterations before the workflow completes or, when enabled, proceeds to final handoff without reviewer approval. |
+| `base_branch` | string | no | `origin/main` | Branch reviewers and the optional final stage compare the current code delta against; also used to create a missing worktree. |
 | `git_worktree_dir` | string | no | `""` | Optional reusable Git worktree root. Empty runs in the invoking checkout; non-empty values run Ralph stages in the created/reused worktree. |
+| `create_pr` | boolean | no | `false` | Safe-by-default PR creation flag. Omitted or `false` skips the final `pull-request` stage and omits `pr_report`; prompt text alone does not opt in, and only strict `true` authorizes the final `pull-request` stage to attempt provider-appropriate PR/MR/review creation. |
 
 Run examples:
 
 ```text
 /workflow ralph prompt="Plan and migrate the database layer to Drizzle" max_loops=3 base_branch=develop
-/workflow ralph prompt="Refactor authentication across the API, CLI, and web UI, then prepare the PR"
+/workflow ralph prompt="Refactor authentication across the API, CLI, and web UI" create_pr=true
 /workflow ralph prompt="Safely implement the API refactor" git_worktree_dir=../atomic-ralph-api-wt base_branch=main
 ```
 
-Each `ralph` iteration writes an RFC-style technical design document under `specs/`, initializes an OS-temp implementation notes file, delegates implementation through sub-agents, runs a behavior-preserving code simplifier, and asks two reviewers to inspect the patch directly against `base_branch`. Reviewers discover any needed repository infrastructure themselves while inspecting the actual diff; Ralph no longer runs separate `infra-*` discovery stages. The loop stops when every reviewer approves or `max_loops` is reached, then runs a pull-request preparation stage.
+Each `ralph` iteration writes an RFC-style technical design document under `specs/`, initializes an OS-temp implementation notes file, delegates implementation through sub-agents, runs a behavior-preserving code simplifier, and asks two reviewers to inspect the patch directly against `base_branch`. Reviewers discover any needed repository infrastructure themselves while inspecting the actual diff; Ralph no longer runs separate `infra-*` discovery stages. The loop stops when every reviewer approves or `max_loops` is reached. By default Ralph does not start the final `pull-request` stage, and `pr_report` is omitted. Prompt text alone does not opt in. Pass `create_pr=true` only when you explicitly want the final `pull-request` stage to inspect provider credentials and attempt provider-appropriate PR/MR/review creation, such as GitHub `gh`, Azure Repos `az repos pr create`, or Sapling/Phabricator tooling; Ralph's own PR-creation instructions live in that final stage.
 
 Set `git_worktree_dir` when you want Ralph's worker stages isolated in a reusable Git worktree. Relative paths resolve from the invoking repository root, existing same-repository worktree roots are reused, and missing paths are created from `base_branch`. Ralph preserves the invoking repo-relative cwd inside the worktree, so launching from `repo/packages/api` with `git_worktree_dir=../repo-wt` runs stages from `../repo-wt/packages/api`.
 
@@ -273,13 +274,13 @@ Result fields:
 | `plan` | Latest RFC-style plan text. |
 | `plan_path` | Path to the latest generated spec under `specs/`. |
 | `implementation_notes_path` | OS-temp notes file containing decisions, deviations, blockers, and validation notes. |
-| `pr_report` | Pull-request preparation report: diff review, PR status, commands, and follow-up steps. |
-| `approved` | Whether the reviewer loop approved before PR handoff. |
+| `pr_report` | Pull-request report emitted only when `create_pr=true` and the final `pull-request` stage runs. |
+| `approved` | Whether the reviewer loop approved before completion or optional final handoff. |
 | `iterations_completed` | Number of plan/orchestrate/review loops completed. |
 | `review_report` | Compact reference to the latest reviewer payload artifact. |
 | `review_report_path` | JSON artifact path for the latest Ralph review round. |
 
-A typical end-to-end flow is `/skill:research-codebase` → `/skill:create-spec` → `/workflow goal objective="Implement the researched rate-limit behavior, run the focused tests, and finish when the documented burst behavior is validated"` when you can identify the work surface, state the exact outcome, and name the validation that proves it is done. Keep using `/workflow ralph` for larger migrations, broad refactors, multi-package changes, and spec-to-PR work where you want Atomic to plan, delegate through sub-agents, simplify, review, iterate, and prepare a pull-request report.
+A typical end-to-end flow is `/skill:research-codebase` → `/skill:create-spec` → `/workflow goal objective="Implement the researched rate-limit behavior, run the focused tests, and finish when the documented burst behavior is validated"` when you can identify the work surface, state the exact outcome, and name the validation that proves it is done. Keep using `/workflow ralph` for larger migrations, broad refactors, multi-package changes, and spec-to-reviewed-change work where you want Atomic to plan, delegate through sub-agents, simplify, review, iterate, and optionally allow only the final `pull-request` stage to attempt PR creation with `create_pr=true`.
 
 ### `open-claude-design`
 
@@ -334,7 +335,7 @@ Use the goal workflow to implement specs/2026-03-rate-limit.md, run the focused
 ```
 
 ```text
-Use the ralph workflow to plan a database-layer migration, implement it, review it, and prepare a PR.
+Use the ralph workflow to plan a database-layer migration, implement it, review it, and set `create_pr=true` for final-stage PR handoff.
 ```
 
 ```text
@@ -378,7 +379,7 @@ If the task is only deterministic TypeScript with no LLM/session stage, use a sc
 |-----------|-----|
 | Run, inspect, attach to, pause, interrupt, resume, or check status for an existing workflow | `/workflow ...` or `workflow({ action: ... })` |
 | Implement a small-to-medium scope change with an identifiable work surface, exact outcome, and named validation | `/workflow goal objective="..."` so Atomic keeps the run bounded, captures receipts in a goal ledger, gates completion through reviewers, and stops as `complete`, `blocked`, or `needs_human` |
-| Plan and execute a larger migration, broad refactor, multi-package change, or spec-to-PR effort | `/workflow ralph prompt="..."` so Atomic can plan the approach, delegate implementation through sub-agents, simplify, review, iterate, and prepare a pull-request report |
+| Plan and execute a larger migration, broad refactor, multi-package change, or spec-to-reviewed-change effort | `/workflow ralph prompt="..."` so Atomic can plan the approach, delegate implementation through sub-agents, simplify, review, and iterate; prompt text alone does not opt in to PR creation, so add `create_pr=true` only when you want the final `pull-request` stage and `pr_report` |
 | Create or edit reusable automation | a TypeScript workflow definition exported from `defineWorkflow(...).compile()` |
 | Track one-off work without saving a workflow file | direct `workflow({ task })`, `workflow({ tasks })`, or `workflow({ chain })` calls |
 | Make a workflow robust | design the stage graph, context handoffs, artifacts, validation gates, model fallbacks, and human approval points before coding |
@@ -1019,6 +1020,25 @@ Builder basics:
 
 Author workflows to create at least one tracked stage by calling `ctx.task()`, `ctx.chain()`, `ctx.parallel()`, `ctx.stage()`, or `ctx.workflow()` in the run body so each run has graph nodes to inspect, attach to, interrupt, resume, and render.
 
+### Guiding Principles
+
+- Stage prompts should be locally scoped: describe only the current stage's objective, inputs, expected outputs, and success criteria.
+- Avoid references to other stages unless the current stage explicitly receives and needs that information.
+- Avoid workflow-specific or stage-specific vocabulary that is not explained inside the current prompt.
+- Use clear software engineering terminology in self-described prompts.
+- Avoid hard-coded regular expressions for condition matching when gating reviews or model outputs.
+- Prefer structured output schemas for review/gate decisions whenever model output needs to be evaluated.
+- Treat atomic workflow units as language model stages, not deterministic tools.
+- When deterministic gates are needed, create small dedicated stages that instruct a model to run a specific tool or perform a specific check. This keeps gates adaptive to the current codebase while preserving explicit workflow structure.
+
+### Context engineering guidance
+
+Workflow guidance should also cover the context passed between stages:
+
+- Prefer creating files or artifacts for substantial handoffs, then instruct the next stage to read the file, instead of dumping large text output directly into the next stage prompt or context.
+- Prefer forked context for non-reviewer stages so long-running implementation work can preserve coherency and continuity.
+- Prefer a clean context window for reviewer stages so earlier implementation stages do not bias the reviewer. Reviewers should evaluate the supplied artifacts, changed files, tests, and explicit criteria as independently as possible.
+
 ### Inputs
 
 Inputs are declared with TypeBox `Type.*` schemas passed to `.input(key, schema)`. `Type` is re-exported from `@bastani/workflows` (along with the `Static` and `TSchema` type helpers), so you do not import from `typebox` directly in workflow files. Workflow packages still declare `typebox` as a peer dependency so the SDK's shipped types resolve under `tsc` — see [Programmatic Usage](#programmatic-usage). Common input schemas map to picker kinds and accepted runtime values:
@@ -1219,7 +1239,7 @@ Common builtin import targets:
 |---|---|---|---|
 | `deep-research-codebase` | `deepResearchCodebase` | `@bastani/workflows/builtin/deep-research-codebase` | Gather broad repo research before planning, synthesis, or implementation. |
 | `goal` | `goal` | `@bastani/workflows/builtin/goal` | Run a bounded implementation/check loop with receipts and reviewer-gated completion. |
-| `ralph` | `ralph` | `@bastani/workflows/builtin/ralph` | Delegate a larger migration/refactor/spec-to-PR effort to Ralph's plan/orchestrate/review loop. |
+| `ralph` | `ralph` | `@bastani/workflows/builtin/ralph` | Delegate a larger migration/refactor/spec-to-reviewed-change effort to Ralph's plan/orchestrate/review loop; pass `create_pr=true` to authorize only the final PR-creation stage. |
 | `open-claude-design` | `openClaudeDesign` | `@bastani/workflows/builtin/open-claude-design` | Generate and refine a UI/design artifact and handoff spec. |
 
 Example parent workflow that runs builtin deep research, then chooses either `goal` or `ralph` as the nested implementation runner:
@@ -1234,7 +1254,7 @@ export default defineWorkflow("research-then-implement")
     "runner",
     Type.Union([Type.Literal("goal"), Type.Literal("ralph")], {
       default: "goal",
-      description: "Use goal for bounded changes or Ralph for broad spec-to-PR work.",
+      description: "Use goal for bounded changes or Ralph for broad spec-to-reviewed-change work.",
     }),
   )
   .output("research_doc_path", Type.Optional(Type.String({ description: "Path to the deep-research document used for implementation." })))
@@ -1253,7 +1273,8 @@ export default defineWorkflow("research-then-implement")
     if (String(ctx.inputs.runner) === "ralph") {
       const implementation = await ctx.workflow(ralph, {
         inputs: {
-          prompt: `Use the research document at ${String(research.outputs.research_doc_path)} to plan, implement, review, and prepare a PR for: ${topic}`,
+          prompt: `Use the research document at ${String(research.outputs.research_doc_path)} to plan, implement, and review: ${topic}`,
+          create_pr: true,
         },
         stageName: "ralph implementation",
       });
@@ -1478,6 +1499,20 @@ registry.get("alpha");
 
 A workflow is an information-flow system, not just a list of prompts. Most workflow failures come from missing, stale, oversized, or poorly-routed context. Design every stage boundary deliberately.
 
+### Locally Scoped Stage Prompts
+
+Stage prompts should be local contracts, not miniature descriptions of the entire workflow runtime. Write prompts as if the stage could be executed independently from a fresh session with only the listed inputs. Include:
+
+- the stage's current objective and what is out of scope for this stage
+- the exact files, artifacts, child outputs, or user inputs it may use
+- the expected output format or structured-output tool/schema it must return
+- the checks, tools, or deterministic commands it should run when relevant
+- the success criteria that let this stage stop
+
+Avoid unrelated workflow internals such as reducer algorithms, future PR stages, sibling reviewer names, loop implementation details, or project-specific nicknames unless they are explicitly part of the current stage contract. If a term such as a gate name, ledger field, or workflow nickname is necessary, define it in the prompt before using it.
+
+Choose context mode deliberately. Use `context: "fork"` or `forkFromSessionFile` for coherent long-running implementation stages that need continuity from their own earlier work. Use `context: "fresh"` for unbiased reviewer, evaluator, and gate stages so they inspect the current files and explicit artifacts rather than inheriting the implementer's assumptions. When continuity is needed across fresh stages, pass it explicitly through files, declared outputs, and `reads`.
+
 ### Context Fundamentals
 
 Treat context as a finite attention budget. Include only information needed for the current decision, place critical constraints near the beginning or end of prompts, and use progressive disclosure instead of loading every possible reference up front.
@@ -1521,6 +1556,8 @@ A good compressed handoff includes:
 
 Use `output`, `outputMode: "file-only"`, `reads`, and `chainDir` for large research bundles, logs, or reviewer outputs. Keep summaries compact and let downstream stages read full artifacts only when needed. In the downstream stage prompt, explicitly say something like `Read the file at ${artifactPath} before continuing.` Do not inject full session tails, all previous stage outputs, or every prior review round into later prompts by default; pass the latest relevant artifact paths and make older history discoverable from a ledger or index file.
 
+Substantial handoffs should travel through files or durable artifacts instead of hidden transcript assumptions. This keeps stage prompts small, makes review/audit possible, and lets later stages reread the authoritative material without depending on what a previous model happened to summarize.
+
 ```ts
 const researchPath = ".atomic/workflows/runs/context-demo/research.md";
 await ctx.task("researcher", {
@@ -1584,6 +1621,10 @@ Build validation into the workflow instead of waiting for a final manual check.
 - reviewer stages: fresh-context reviewers that inspect artifacts and current files
 - LLM-as-judge stages: direct scoring, pairwise comparison, or rubric-based grading for subjective outputs
 
+Prefer structured output schemas or structured-output tools for model review and gate decisions. Do not make correctness depend on brittle regular-expression matching against free-form prose such as “looks good”, “approved”, or “PASS”. A schema with explicit booleans/enums, findings arrays, confidence, evidence fields, and error reporting is easier to validate, replay, and safely default to “not approved” when malformed.
+
+Use small dedicated model stages for adaptive gates when deterministic code alone cannot decide what to check. For example, a stage can read an artifact, inspect the repo, run a named tool or command, and then emit a structured decision. Keep that stage's prompt narrow: tell it the specific check to perform, the files/tools it may use, and the structured decision it must return.
+
 When using LLM judges, mitigate bias by defining score anchors, asking for evidence, calibrating against examples, and keeping length/order effects in mind. Track pass rates and failures over time for reusable workflows.
 
 ### Tools, MCP, Memory, and Hosted Execution
@@ -1616,12 +1657,13 @@ Before implementing or shipping a non-trivial workflow, answer these questions:
 - **Inputs:** Which values should be declared as inputs? What is the narrowest schema type? Which defaults are safe?
 - **Starter pattern:** Which [workflow starter pattern](#workflow-starter-patterns) best matches the task, and where does the actual design intentionally diverge?
 - **Stage decomposition:** For each stage, what question does it answer, what context does it need, what output should it return, and what model/tool/MCP requirements does it have?
+- **Local stage contract:** Can this stage prompt stand alone with its current objective, inputs/artifacts, expected outputs, tools/checks, and success criteria, without unexplained workflow internals or future-stage assumptions?
 - **Information flow:** For every edge between stages, is `previous` enough, or should the handoff use structured returns, files, `reads`, `output`, or `outputMode`?
 - **Output contract:** Which outputs should be declared with `.output(...)`, which stage/task/child results should `.run()` return for those keys, and what runtime type must each value have? If another workflow may call this workflow as a child, which non-default outputs should the parent rely on?
 - **Context size:** Can downstream stages succeed from the handoff alone? Should large transcripts, logs, or research bundles be summarized or saved as artifacts?
 - **Control flow:** Should the workflow use `ctx.chain`, `ctx.parallel`, `ctx.ui`, bounded loops, `failFast`, or `fallbackModels`?
 - **User experience:** Are stage names readable in status and graph views? Is the final output compact? Are important artifacts saved with stable paths?
-- **Validation:** What success criteria, review gates, deterministic checks, or evaluator stages prove the workflow did the right thing?
+- **Validation:** What success criteria, review gates, deterministic checks, or evaluator stages prove the workflow did the right thing? Are model gates schema-backed instead of regex/prose-matched, and do adaptive gates run as focused model stages with explicit tool/check instructions?
 
 Good workflows are information-flow systems, not just prompt sequences. Keep stage prompts focused, preserve evidence with file paths or artifacts, and pass only the context each downstream stage needs.
 
@@ -1637,4 +1679,6 @@ Good workflows are information-flow systems, not just prompt sequences. Keep sta
 - Do not expect named workflow runs to block the chat turn; they are background tasks.
 - Do not call `kill` when the user asks to interrupt or pause resumably.
 - Keep stage names readable because they appear in workflow status and UI.
+- Do not write stage prompts that depend on hidden workflow-wide awareness; make each model stage locally scoped and self-described.
+- Do not parse model gate decisions from ad-hoc prose with regular expressions; use structured output schemas/tools or a focused checking stage that returns a structured decision.
 - Return compact structured output and save large artifacts to files.