agentic-orchestrator 0.1.28 → 0.2.0

package/docs/superpowers/specs/2026-03-23-reconcile-divergence-fix-design.md

@@ -0,0 +1,118 @@
+# Reconcile Mainline Divergence Detection Fix + Dashboard Notification
+
+**Date:** 2026-03-23
+**Status:** Approved
+
+## Problem
+
+Two issues with the current `repo.reconcile_mainline` tool:
+
+1. **False-positive divergence detection.** `checkRemoteLocalDivergence()` in `git-reconciliation-service.ts` compares local and remote HEAD SHAs directly (`localHead !== remoteHead`). When local/main is ahead of origin/main (all remote commits exist locally), the check incorrectly reports divergence and the tool fails with `remote_local_divergence`. This blocks features unnecessarily.
+
+2. **Silent failure on dashboard.** When `remote_local_divergence` occurs during an automated run, the error is logged to stderr by the tool runtime but never surfaces to the user. The `NotificationEvent` type does not include this error, no notification is emitted, and the feature does not transition to `BLOCKED`. The user sees nothing wrong on the dashboard.
+
+## Design
+
+### 1. Smarter divergence detection
+
+**File:** `apps/control-plane/src/application/services/git-reconciliation-service.ts`
+
+Replace the SHA comparison in `checkRemoteLocalDivergence()` with a `git merge-base --is-ancestor` check:
+
+```
+git merge-base --is-ancestor origin/<baseRef> <baseRef>
+```
+
+- **Exit code 0** -> remote HEAD is an ancestor of local HEAD -> no divergence (local is ahead or equal)
+- **Exit code 1** -> remote has commits that local does not -> true divergence
+
+The existing return type `RemoteLocalDivergenceResult` (`{ diverged: boolean; local_head: string; remote_head: string }`) gains an additional `local_ahead: boolean` field so callers can distinguish "local ahead" from "identical". No downstream signature changes are required since both kernel call sites only inspect `diverged`.
+
+**Logic:**
+
+```
+fetch origin <baseRef>
+localHead = rev-parse <baseRef>
+remoteResult = rev-parse origin/<baseRef>
+
+# Preserve existing fallback: if remote ref fails to resolve, treat as no divergence
+if remoteResult.code !== 0:
+  diverged = false, local_ahead = false, remoteHead = localHead
+  return early (skip merge-base call)
+
+remoteHead = remoteResult.stdout
+
+if localHead === remoteHead:
+  diverged = false, local_ahead = false
+else:
+  is_ancestor = merge-base --is-ancestor origin/<baseRef> <baseRef>
+  if is_ancestor (exit 0):
+    diverged = false, local_ahead = true
+  else:
+    diverged = true, local_ahead = false
+```
+
+**Note:** `--is-ancestor` exit code 1 covers both "remote strictly ahead" and "bidirectional divergence" (both sides have unique commits). For this fix, both cases correctly produce `diverged: true`. If a future feature needs to distinguish these, the result type can be extended then.
+
+### 2. New notification event
+
+**File:** `apps/control-plane/src/application/services/notifier-service.ts`
+
+- Add `'remote_local_divergence'` to the `NotificationEvent` union type.
+- Add entry in `EVENT_PRIORITY`: `remote_local_divergence: 'critical'` (requires human action to resolve).
+
+### 3. Feature blocked transition + notification
+
+**File:** `apps/control-plane/src/supervisor/run-coordinator.ts`
+
+**Error propagation context:** `ToolCaller.callTool()` returns `Promise<{ ok: true; data: TData }>` — it only returns successes. On failure, the runtime adapter throws an error. Currently, `prepareFeaturesForPhase()` (line 854) calls `callTool('orchestrator', TOOLS.REPO_RECONCILE_MAINLINE, ...)` with **no try/catch**, so a `remote_local_divergence` error crashes the entire feature eligibility loop.
+
+**Fix:** Wrap the `callTool` for `REPO_RECONCILE_MAINLINE` in `prepareFeaturesForPhase()` in a try/catch:
+
+1. **Catch the thrown error** and inspect its error code.
+2. **If `remote_local_divergence`:** Patch the feature to `BLOCKED` status via `callTool('orchestrator', TOOLS.FEATURE_STATE_PATCH, ...)` with `status_reason` set to the divergence details.
+3. **Emit the notification** via `this.notifier.notify('remote_local_divergence', ...)` with message: _"Local main diverges from origin/main for feature '<id>' — pull or sync remote changes to unblock."_
+4. **Continue the loop** — other features in the same phase must still be processed. The caught feature is excluded from the eligible list.
+5. **For non-divergence errors**, re-throw to preserve existing behavior.
+
+The existing `notifyStatusTransitions()` method (line 945) will then also detect the BLOCKED transition and handle dashboard status cache updates. However, `notifyStatusTransitions` currently maps BLOCKED to either `collision_detected` or `gate_failed`. We update it to check for `status_reason` containing the divergence code and emit `remote_local_divergence` instead when appropriate.
+
+This ensures:
+
+- The dashboard triage panel shows the feature as blocked.
+- Desktop/Slack/webhook notifications fire per the user's routing config.
+- The user has a clear, actionable message explaining what to do.
+- Other features in the same phase continue processing normally.
+- The notifier's 5-minute throttle window deduplicates repeated errors for the same feature.
+
+### 4. Tests
+
+| Test                                                | File                                 | Description                                                                                                       |
+| --------------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| Local-ahead returns no divergence                   | `git-reconciliation-service.spec.ts` | Mock `merge-base --is-ancestor` exit 0; assert `diverged: false, local_ahead: true`                               |
+| True divergence still detected                      | `git-reconciliation-service.spec.ts` | Mock `merge-base --is-ancestor` exit 1; assert `diverged: true`                                                   |
+| Identical SHAs short-circuit                        | `git-reconciliation-service.spec.ts` | Same local/remote SHA; assert `diverged: false, local_ahead: false`, no `merge-base` call                         |
+| Remote ref resolution failure fallback              | `git-reconciliation-service.spec.ts` | Mock `rev-parse origin/<base>` exit non-zero; assert `diverged: false`, no `merge-base` call                      |
+| Notification event routes as critical               | `notifier-service.spec.ts`           | Assert `remote_local_divergence` maps to `critical` priority                                                      |
+| Reconcile succeeds when local ahead                 | `kernel.coverage2.spec.ts`           | Update existing divergence test to cover local-ahead scenario                                                     |
+| Feature blocks on divergence error                  | `run-coordinator.spec.ts`            | Assert `prepareFeaturesForPhase` catches thrown error, patches feature to BLOCKED, emits notification             |
+| Other features still processed after one divergence | `run-coordinator.spec.ts`            | Assert that when one feature throws `remote_local_divergence`, remaining features in the loop are still evaluated |
+
+### 5. Files changed
+
+| File                                                                        | Change                                                                                 |
+| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `apps/control-plane/src/application/services/git-reconciliation-service.ts` | Replace SHA comparison with `--is-ancestor` check; add `local_ahead` to result type    |
+| `apps/control-plane/src/application/services/notifier-service.ts`           | Add `remote_local_divergence` event and `critical` priority mapping                    |
+| `apps/control-plane/src/supervisor/run-coordinator.ts`                      | Add try/catch in `prepareFeaturesForPhase`, patch to BLOCKED, emit notification        |
+| `apps/control-plane/src/core/kernel.ts`                                     | Verify — no changes needed, both call sites (lines 1060, 1267) only inspect `diverged` |
+| `apps/control-plane/test/git-reconciliation-service.spec.ts`                | Add local-ahead, identical SHA, and remote-ref-failure test cases                      |
+| `apps/control-plane/test/notifier-service.spec.ts`                          | Add event routing test                                                                 |
+| `apps/control-plane/test/kernel.coverage2.spec.ts`                          | Update divergence test for local-ahead                                                 |
+| `apps/control-plane/test/run-coordinator.spec.ts`                           | Add blocked transition, notification, and loop-continuation tests                      |
+
+## Out of scope
+
+- Automatic remote sync without user opt-in (the `--sync-remote auto` flag already exists for this).
+- Dashboard UI changes beyond what the existing triage panel provides for BLOCKED features.
+- Changes to `featureReadyToMerge` divergence check — it shares the same `checkRemoteLocalDivergence()` call, so the fix propagates automatically.

package/docs/superpowers/specs/2026-03-28-ordering-agent-spec-audit-design.md

@@ -0,0 +1,50 @@
+# Design: Ordering Agent Spec Audit & Defect Fixes
+
+**Date:** 2026-03-28
+**Status:** Applied
+**Target:** `spec-files/outstanding/agentic_orchestrator_spec_ordering_agent_spec.md` (v1.1 → v1.2)
+
+---
+
+## Summary
+
+Critical audit of the ordering agent spec (M54) against the actual codebase. Found 11 defects — 3 critical, 3 high, 5 moderate. All fixed in-place via targeted patches to preserve spec review history.
+
+## Defects Found and Fixed
+
+### Critical
+
+| ID  | Defect                                                                                                            | Fix                                                                                                                          |
+| :-- | :---------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- |
+| D1  | Per-request `schedule()` interface vs batch backlog analysis — spec didn't clarify how the two-speed design works | Added §4.2 paragraph explaining batch sidecar → artifact → per-request adapter lookup separation                             |
+| D2  | No terminal-state trigger — deferred features never re-evaluated when blocking deps merge                         | Added explicit `notifyNewRequestHint()` requirement on terminal transitions in §4.5; added artifact expiry backstop trigger  |
+| D3  | Artifact lifecycle underspecified — no atomic writes, staleness detection, or corruption handling                 | Added `completion_status`, `backlog_fingerprint`, `expires_at` fields; atomic write requirement; fallback conditions in §4.4 |
+
+### High
+
+| ID  | Defect                                                                                 | Fix                                                                                                  |
+| :-- | :------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- |
+| D4  | No JSON schema for ordering artifact                                                   | Added `organizer-ordering-artifact.schema.json` to §5 file targets                                   |
+| D5  | `concurrency_groups` undefined semantics and no consumer                               | Removed from artifact and ordering strategy; ready_set already serves concurrency purpose            |
+| D6  | Terminal states listed as `merged, deleted` — `deleted` doesn't exist in state machine | Replaced with actual `ENROLLMENT_TERMINAL_STATUSES`: `merged, failed, paused_budget, ready_to_merge` |
+
+### Moderate
+
+| ID  | Defect                                                          | Fix                                                                                        |
+| :-- | :-------------------------------------------------------------- | :----------------------------------------------------------------------------------------- |
+| D7  | §7.2 reference inaccuracy — class name is in §3.1, not §7.2     | Corrected citation in §1 and §2.4                                                          |
+| D8  | Error handling underspecified for adapter fallback              | Added 5 explicit fallback conditions with logging requirement in §4.4                      |
+| D9  | Intra-request dependency ordering undefined                     | Noted as addressed by batch sidecar design — sidecar sees all features across all requests |
+| D10 | `PromptBundle` type and `prompt-bundle-loader.ts` not mentioned | Added both to §5 file targets                                                              |
+| D11 | `SupervisorRuntimeState.organizerSessionId` not mentioned       | Added to §5 file targets alongside `RuntimeSessionsSnapshot`                               |
+
+## Additional Fixes (Same Session)
+
+| Item                      | Description                                                                                      |
+| :------------------------ | :----------------------------------------------------------------------------------------------- |
+| `review-tab.spec.tsx:122` | Test expected `>Approve<` but component renders `Approve & Merge` — updated assertion            |
+| Divergence fix formatting | Verified all 5 implementation commits merged; remaining working tree changes are formatting-only |
+
+## Approach
+
+Targeted patch (Approach A) — fixed all defects in-place within the existing spec structure. The two-layer architecture (sidecar + adapter) is sound; defects were in missing details, incorrect references, and underspecified interactions.

package/docs/superpowers/specs/2026-03-29-drop-zone-and-provider-optimization-design.md

@@ -0,0 +1,254 @@
+# Drop Zone File Loading & Provider-Specific Agent Optimization
+
+## Overview
+
+Two enhancements in one spec:
+
+1. **Bulk drag-and-drop file loading** — extend the Launch Workspace UI with a full-page drop zone that accepts `.md` files and folders (recursively extracting `.md` files from folders)
+2. **Provider-specific agent optimization** — a prompt overlay system that tailors agent behavior per provider (e.g., Claude's planner uses `/plan` mode, builders reference staged plan artifacts), plus an artifact stager that copies specs and plans into the builder's worktree
+
+## Scope
+
+- Launch Workspace drop zone (frontend only — `packages/web-dashboard/`)
+- Prompt overlay resolver (control plane — `cli-worker-provider.ts`)
+- Artifact stager service (control plane — new service in `supervisor/`)
+- Initial overlay files for Claude and Codex (planner + builder roles)
+- `agents.yaml` schema update for `prompt_overlay_dir`
+
+Out of scope: QA/reconciler/organizer overlays, push-to-remote behavior, provider capability flags.
+
+---
+
+## Section 1: Drag-and-Drop File Loading
+
+### Current State
+
+The Launch Workspace (`packages/web-dashboard/src/app/launch/page.tsx`) supports click-to-upload multiple `.md` files via a hidden `<input type="file">`. Files are read as text and converted to draft cards with markdown content preserved. The existing `handleFileSelection(files: FileList)` function handles the conversion.
+
+### Design
+
+Add HTML5 drag-and-drop event handlers to the `LaunchPageContent` component's root element.
+
+**Drop zone overlay:**
+
+- Full-page overlay appears on `dragenter` event
+- Semi-transparent green background with dashed border
+- Existing content dims behind the overlay
+- Overlay disappears on `dragleave` (with counter to handle child element events) or `drop`
+- Prompt text: "Drop .md files or folders" with subtitle "Folders will be scanned for .md files"
+
+**File handling on drop:**
+
+- Direct `.md` files: read via `File.text()`, create draft via existing `createDraft(name, markdown, 'upload')` path
+- Folders: use `DataTransferItem.webkitGetAsEntry()` to get `FileSystemDirectoryEntry`, then recursively walk with `createReader().readEntries()` collecting all `.md` files
+- Non-`.md` files dropped directly (not inside a folder) trigger a status banner: "Skipped N non-markdown files"
+- Non-`.md` files inside folders are silently skipped
+- Status banner after processing: "Added N drafts from drop"
+
+**Browser fallback:**
+
+- If `webkitGetAsEntry()` is not available (rare — unsupported in some older Firefox builds), folders are ignored and a toast explains: "Folder drop not supported in this browser — use the Upload button instead"
+- Individual `.md` file drops work in all modern browsers
+
+**Utility extraction:**
+
+- Extract folder traversal into a pure async function: `collectMarkdownFiles(entries: FileSystemEntry[]): Promise<File[]>`
+- This function recursively walks directory entries and collects `.md` files
+- Testable independently of DOM events
+
+**State flow:**
+All new drafts feed into the existing `setDrafts()` pipeline via `setState`, triggering the preview debounce automatically. No changes to the preview or submission APIs.
+
+**New state:**
+
+- `dragActive: boolean` — controls overlay visibility
+- `dragCounter: number` — ref to handle nested `dragenter`/`dragleave` events (increment on enter, decrement on leave, show overlay when > 0)
+
+---
+
+## Section 2: Prompt Overlay System
+
+### Current State
+
+Role prompts live in `config/agentic/orchestrator/prompts/` (e.g., `planner.system.md`, `builder.system.md`). They are provider-agnostic. `PromptBundleLoader` reads them from disk and caches them. The final prompt is assembled in `cli-worker-provider.ts`'s `buildWorkerPrompt()` function, which already has access to the provider name.
+
+### Design
+
+**New directory:** `config/agentic/orchestrator/prompts/overrides/`
+
+**Naming convention:** `<role>.<provider>.md` — e.g.:
+
+- `planner.claude.md`
+- `builder.claude.md`
+- `builder.codex.md`
+- `planner.codex.md`
+
+**Resolution location:** In `cli-worker-provider.ts`'s `buildWorkerPrompt()` function. This is where the provider name is already known and the system prompt is being assembled. This avoids changing the `PromptBundleLoader` interface (which would need per-role provider information it doesn't currently have, since different roles can use different providers via `role_provider_overrides`).
+
+**Resolution logic:**
+
+1. After loading the base system prompt, check if `<overlayDir>/<role>.<provider>.md` exists
+2. If it exists, read the file and append to the base prompt with separator: `\n\n---\n\n## Provider-Specific Instructions\n\n<overlay content>`
+3. If not, use the base prompt unchanged
+4. Cache the resolved overlay per `(role, provider)` pair to avoid repeated disk reads
+
+**`agents.yaml` schema change:**
+Add an optional `prompt_overlay_dir` field under `runtime`:
+
+```yaml
+runtime:
+  prompt_overlay_dir: config/agentic/orchestrator/prompts/overrides
+```
+
+Default value: `config/agentic/orchestrator/prompts/overrides` (relative to repo root). If the directory doesn't exist, overlay resolution is silently skipped.
+
+**Where the overlay dir config is read:**
+The `cli-worker-provider.ts` receives the repo root and agents config through its constructor dependencies. It resolves the overlay directory path as `path.join(repoRoot, agentsConfig.runtime.prompt_overlay_dir ?? 'config/agentic/orchestrator/prompts/overrides')`.
+
+---
+
+## Section 3: Artifact Staging for Builders
+
+### Current State
+
+In interactive mode, the builder works in a git worktree. The builder's prompt mentions on-disk files (`state.md`, `plan.md`, `plan.json`, `evidence/`) that live in `.aop/features/<id>/` in the main repo. The builder must navigate to these paths to read them.
+
+### Design
+
+**New service: `ArtifactStager`** — a small, focused service called by `build-wave-executor.ts` before dispatching the builder in interactive mode.
+
+**What it copies into the worktree:**
+
+| Source (canonical)                      | Destination (worktree)                        |
+| --------------------------------------- | --------------------------------------------- |
+| `.aop/features/<id>/spec.md`            | `.aop/context/spec.md`                        |
+| `.aop/features/<id>/plan.md`            | `.aop/context/plan.md`                        |
+| `.aop/features/<id>/plan.json`          | `.aop/context/plan.json`                      |
+| `.aop/features/<id>/qa_test_index.json` | `.aop/context/qa_test_index.json` (if exists) |
+
+**Additional file created:**
+
+- `.aop/context/README.md` — explains what each file is and that these are read-only copies staged for the builder's reference
+
+**Lifecycle:**
+
+1. `build-wave-executor.ts` calls `artifactStager.stage(featureId, worktreePath)` before dispatching the worker
+2. Stager reads artifacts from canonical `.aop/features/<id>/` paths
+3. Creates `.aop/context/` directory in worktree if it doesn't exist
+4. Copies files (atomic: write to temp, rename)
+5. After the builder finishes, no explicit cleanup — worktree cleanup handles it
+
+**Deterministic mode:** Staging is skipped. The context bundle already includes the full plan/spec inline in the prompt.
+
+**Builder prompt update:**
+The on-disk file guidance in `buildInteractiveWorkerPrompt()` is updated to include the staged artifacts:
+
+```
+.aop/context/spec.md             — Original feature specification (read this first)
+.aop/context/plan.md             — Human-readable implementation plan
+.aop/context/plan.json           — Structured plan with tasks and acceptance criteria
+.aop/context/qa_test_index.json  — Test expectations (if available)
+```
+
+This replaces the current builder file guidance (which points to `.aop/features/<id>/` paths) with the simpler `.aop/context/` paths.
+
+**Service interface:**
+
+```typescript
+interface ArtifactStager {
+  stage(featureId: string, worktreePath: string): Promise<void>;
+}
+```
+
+Dependencies: `repoRoot` (to resolve canonical paths), filesystem access. No kernel or state dependencies.
+
+---
+
+## Section 4: Provider-Specific Prompt Content
+
+### Initial Overlay Files
+
+**`planner.claude.md`:**
+
+- Instruct the planner to use Claude Code's `/plan` mode when formulating implementation plans
+- Leverage extended thinking for complex architectural decisions
+- Create a structured plan document that maps directly to the `PLAN_SUBMISSION` format
+- Reference `.aop/context/spec.md` as the source of truth for requirements
+
+**`planner.codex.md`:**
+
+- Instruct the planner to use Codex's structured task decomposition model
+- Emphasize file-level granularity in plan tasks (Codex works well with explicit file lists)
+
+**`builder.claude.md`:**
+
+- Instruct the builder to read `.aop/context/plan.md` and `.aop/context/plan.json` before starting work
+- Treat the plan as a task checklist — work through tasks sequentially, committing after each
+- Read `.aop/context/spec.md` to understand the "why" behind each task
+- Use Claude Code's native file editing tools rather than emitting raw patches
+- Acceptance criteria from the plan are the definition of done
+
+**`builder.codex.md`:**
+
+- Same artifact references (`.aop/context/` files)
+- Use Codex's apply-patch model for changes
+- Emphasize working within `allowed_areas` from the plan
+
+**No overlays needed initially for:** QA, reconciler, organizer. These roles are already well-structured and provider-agnostic. Overlays can be added later if needed.
+
+---
+
+## Section 5: Testing Strategy
+
+### Drag-and-Drop (Frontend)
+
+- **Unit test:** Extract `collectMarkdownFiles(entries)` into a testable utility. Test with mock `FileSystemEntry` objects: single `.md` file, nested folder with mixed files, empty folder, deeply nested `.md` files.
+- **Manual test matrix:** Drag single `.md`, drag multiple `.md` files, drag folder with mixed files, drag non-`.md` file (should show skip banner), drag folder in browser without `webkitGetAsEntry()` support (should show fallback toast).
+
+### Prompt Overlay Resolver
+
+- **Unit test:** Given provider `claude` and role `builder`, resolves `prompts/overrides/builder.claude.md` and appends to base prompt after separator.
+- **Unit test:** Given provider `codex` and role `builder` with no overlay file present, returns base prompt unchanged.
+- **Unit test:** Overlay content is appended after `---\n\n## Provider-Specific Instructions\n\n` separator, not prepended.
+- **Unit test:** Overlay resolution is cached — second call for same `(role, provider)` doesn't re-read disk.
+- **Unit test:** Missing overlay directory doesn't cause errors (silently skipped).
+
+### Artifact Stager
+
+- **Unit test:** `stage(featureId, worktreePath)` copies expected files to `.aop/context/`.
+- **Unit test:** Missing optional files (e.g., no `qa_test_index.json`) don't cause errors — only available files are copied.
+- **Unit test:** `.aop/context/README.md` is created with descriptive content.
+- **Unit test:** Staging is idempotent — calling twice overwrites cleanly.
+
+### Schema Validation
+
+- **Unit test:** `agents.yaml` with `prompt_overlay_dir` field validates against updated schema.
+- **Unit test:** `agents.yaml` without `prompt_overlay_dir` field validates (field is optional, default applies).
+
+---
+
+## File Map
+
+### New Files
+
+| File                                                              | Purpose                                               |
+| ----------------------------------------------------------------- | ----------------------------------------------------- |
+| `packages/web-dashboard/src/lib/drop-zone-utils.ts`               | `collectMarkdownFiles()` utility for folder traversal |
+| `apps/control-plane/src/supervisor/artifact-stager.ts`            | Copies spec/plan artifacts to builder worktree        |
+| `config/agentic/orchestrator/prompts/overrides/planner.claude.md` | Claude planner overlay                                |
+| `config/agentic/orchestrator/prompts/overrides/planner.codex.md`  | Codex planner overlay                                 |
+| `config/agentic/orchestrator/prompts/overrides/builder.claude.md` | Claude builder overlay                                |
+| `config/agentic/orchestrator/prompts/overrides/builder.codex.md`  | Codex builder overlay                                 |
+| `apps/control-plane/test/artifact-stager.spec.ts`                 | Artifact stager unit tests                            |
+| `apps/control-plane/test/prompt-overlay.spec.ts`                  | Prompt overlay resolver unit tests                    |
+
+### Modified Files
+
+| File                                                       | Change                                                                        |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `packages/web-dashboard/src/app/launch/page.tsx`           | Add drag-and-drop event handlers, drop zone overlay, `dragActive` state       |
+| `packages/web-dashboard/src/styles/dashboard.module.css`   | Add `.dropZoneOverlay`, `.dropZoneActive` styles                              |
+| `apps/control-plane/src/providers/cli-worker-provider.ts`  | Add overlay resolution in `buildWorkerPrompt()`, update builder file guidance |
+| `apps/control-plane/src/supervisor/build-wave-executor.ts` | Call `artifactStager.stage()` before builder dispatch in interactive mode     |
+| `config/agentic/orchestrator/agents.yaml`                  | Add optional `prompt_overlay_dir` field                                       |
+| `agentic/orchestrator/schemas/agents.schema.json`          | Add `prompt_overlay_dir` property to runtime object                           |

package/docs/superpowers/specs/2026-03-29-merge-target-feature-branch-design.md

@@ -0,0 +1,152 @@
+# Merge Target: Feature Branch Mode — Design Spec
+
+**Date:** 2026-03-29
+**Status:** Draft
+**Scope:** Add a `merge_target` policy field that controls whether features merge directly to the base branch or to a new `aop/<feature-id>` branch for PR-based workflows.
+
+## 1. Context
+
+Currently, when a feature reaches `ready_to_merge`, the merge service always merges it directly into the configured base branch (e.g. `main`). This works for fully automated workflows but doesn't fit teams that want the tool to do the development work while keeping final integration under human control via pull requests.
+
+This spec adds a `merge_target` policy field with two modes:
+
+- `base_branch` (default): Current behavior — merge directly to main.
+- `feature_branch`: Create a new `aop/<feature-id>` branch off main, merge the feature worktree into that branch. Main is untouched. The user can then push the branch and create a PR through their normal workflow.
+
+## 2. Policy Configuration
+
+### 2.1 New field: `merge_target`
+
+Added to `merge_policy` in `policy.yaml`:
+
+```yaml
+merge_policy:
+  require_user_approval: true
+  allowed_strategies:
+    - merge_commit
+    - squash
+    - rebase
+  merge_target: feature_branch # or "base_branch" (default)
+```
+
+### 2.2 Values
+
+- **`base_branch`** (default): Merges directly to the configured `worktree.base_branch`. Current behavior, fully backward compatible.
+- **`feature_branch`**: Creates a new branch `aop/<feature-id>` from the base branch head, then merges the feature worktree into that branch. The base branch is never checked out or modified.
+
+### 2.3 Branch naming
+
+Fixed convention: `aop/<feature-id>`. Not configurable.
+
+## 3. Merge Service Changes
+
+### 3.1 Current flow (merge_target: base_branch)
+
+1. Stage and commit feature worktree changes
+2. Verify feature branch has material changes
+3. `git checkout <baseBranch>`
+4. `git merge --no-ff <featureId>` (or squash/rebase variant)
+5. Record merge SHA on base branch
+6. Update status to MERGED
+7. Cleanup (optional)
+
+### 3.2 New flow (merge_target: feature_branch)
+
+1. Stage and commit feature worktree changes (unchanged)
+2. Verify feature branch has material changes (unchanged)
+3. `git branch aop/<featureId> <baseBranch>` — create target branch from base branch head
+4. `git checkout aop/<featureId>`
+5. `git merge --no-ff <featureId>` (or squash/rebase variant) — merge into target branch
+6. Record merge SHA on `aop/<featureId>`
+7. Update status to MERGED
+8. Cleanup — remove feature worktree and feature branch, but **preserve** `aop/<featureId>` (the deliverable)
+
+### 3.3 Branch collision
+
+If `aop/<featureId>` already exists (e.g. from a previous failed merge attempt), delete it before creating the new one. This is safe because the branch is a derived artifact, not user work.
+
+### 3.4 Validation phases
+
+All pre-merge validation is identical for both modes: gate checks, approval token verification, staging, committing. The only difference is which branch receives the merge.
+
+### 3.5 Merge evidence
+
+The merge evidence recorded after completion includes a `target_branch` field:
+
+- `base_branch` mode: `target_branch` is the base branch name (e.g. `main`)
+- `feature_branch` mode: `target_branch` is `aop/<featureId>`
+
+### 3.6 Cleanup behavior
+
+When `merge_target: feature_branch`:
+
+- The feature worktree is removed (same as today)
+- The feature branch (`<featureId>`) is deleted (same as today)
+- The target branch (`aop/<featureId>`) is **NOT** deleted — the user needs it for their PR
+
+## 4. Schema Changes
+
+### 4.1 policy.schema.json
+
+Add `merge_target` to the `merge_policy` object properties:
+
+```json
+"merge_target": {
+  "type": "string",
+  "enum": ["base_branch", "feature_branch"],
+  "description": "Where to land the merge. 'base_branch' merges directly to the base branch (e.g. main). 'feature_branch' creates an aop/<feature-id> branch off the base branch and merges there, leaving the base branch untouched."
+}
+```
+
+Not added to `required` — defaults to `base_branch` when omitted.
+
+### 4.2 policy.user.schema.json
+
+Add the same `merge_target` field to the user-facing schema so lean policy authors can set it.
+
+### 4.3 policy.defaults.yaml
+
+Add to the `merge_policy` section:
+
+```yaml
+merge_policy:
+  merge_target: base_branch
+```
+
+## 5. Init Command Changes
+
+Add `merge_target: base_branch` to both `generateLeanPolicyYaml()` and `generateFullPolicyYaml()` in the `merge_policy` block of `init-command-handler.ts`.
+
+## 6. File Map
+
+| File                                                           | Action        | Description                              |
+| :------------------------------------------------------------- | :------------ | :--------------------------------------- |
+| `apps/control-plane/src/application/services/merge-service.ts` | Modify        | Branch creation and merge target routing |
+| `agentic/orchestrator/schemas/policy.schema.json`              | Modify        | Add `merge_target` enum                  |
+| `agentic/orchestrator/schemas/policy.user.schema.json`         | Modify        | Add `merge_target` enum                  |
+| `agentic/orchestrator/defaults/policy.defaults.yaml`           | Modify        | Add `merge_target: base_branch`          |
+| `apps/control-plane/src/cli/init-command-handler.ts`           | Modify        | Add `merge_target` to policy generators  |
+| `apps/control-plane/test/` (merge tests)                       | Modify/Create | Tests for feature_branch merge target    |
+
+## 7. Testing Strategy
+
+### 7.1 Unit tests
+
+1. GIVEN merge_target is base_branch WHEN feature merges THEN merges directly to main.
+2. GIVEN merge_target is feature_branch WHEN feature merges THEN creates aop/<featureId> branch from main and merges there.
+3. GIVEN merge_target is feature_branch WHEN merge completes THEN main is untouched.
+4. GIVEN merge_target is feature_branch WHEN cleanup runs THEN aop/<featureId> branch is preserved.
+5. GIVEN merge_target is feature_branch WHEN cleanup runs THEN feature worktree and feature branch are removed.
+6. GIVEN merge_target omitted WHEN feature merges THEN defaults to base_branch behavior.
+7. GIVEN merge_target is feature_branch with squash strategy WHEN feature merges THEN squash merge lands on aop/<featureId>.
+
+### 7.2 Schema validation tests
+
+Verify `merge_target` accepts `base_branch` and `feature_branch`, rejects invalid values.
+
+## 8. Out of Scope
+
+- Pushing the target branch to remote (user does this manually).
+- Auto-creating PRs via SCM provider.
+- Configurable branch naming patterns (fixed `aop/<feature-id>` convention).
+- Changes to kernel.ts (policy is passed through to merge service).