Spec 081: Executor docs, tests, and rename cleanup

.mindspec/docs/domains/execution/architecture.md

@@ -7,27 +7,29 @@
 The `Executor` interface separates enforcement ("what") from execution ("how"):
 
 ```
-Workflow Layer                    Execution Layer
-┌─────────────────┐              ┌──────────────────┐
-│ approve/         │──Executor──▶│ executor/git.go   │
-│ complete/        │   interface │ (GitExecutor)     │
-│ next/            │              │                  │
-│ specinit/        │              │ gitutil/         │
-│ cleanup/         │              │ (low-level ops)  │
-└─────────────────┘              └──────────────────┘
+Workflow Layer                    Execution Engine
+┌─────────────────┐              ┌─────────────────────────────┐
+│ approve/         │──Executor──▶│ executor/mindspec_executor.go│
+│ complete/        │   interface │ (MindspecExecutor)           │
+│ next/            │              │                             │
+│ spec/            │              │ gitutil/                    │
+│ cleanup/         │              │ (low-level ops)             │
+└─────────────────┘              └─────────────────────────────┘
 ```
 
-- **GitExecutor** — concrete implementation wrapping git+worktree operations
+- **MindspecExecutor** — concrete implementation wrapping git+worktree operations (dispatches beads to worktrees, merges completed bead branches, finalizes specs)
 - **MockExecutor** — test double for enforcement testing without git side effects
 - **DI wiring** — `cmd/mindspec/root.go` has `newExecutor(root)` factory
 
+The execution engine reads beads produced by the planning layer. Each bead is a self-contained work packet — requirements, context, dependencies, acceptance criteria — so a fresh agent can pick it up without session history. Beads are the substrate that makes the `Executor` interface pluggable: any orchestrator that can read a bead can dispatch work.
+
 ### withWorkingDir Safety
 
-Worktree removal and branch deletion require CWD to be outside the target worktree. `GitExecutor` uses `withWorkingDir(root, func)` to temporarily chdir to the repo root before destructive operations, then restores the original CWD. This prevents "cannot remove worktree: in use" errors.
+Worktree removal and branch deletion require CWD to be outside the target worktree. `MindspecExecutor` uses `withWorkingDir(root, func)` to temporarily chdir to the repo root before destructive operations, then restores the original CWD. This prevents "cannot remove worktree: in use" errors.
 
 ### Function Injection for Testability
 
-`GitExecutor` exposes function variables (`WorktreeRemoveFn`, `DeleteBranchFn`, `MergeBranchFn`, etc.) that can be replaced in tests. This avoids requiring a real git repository for unit tests while keeping the production code straightforward.
+`MindspecExecutor` exposes function variables (`WorktreeRemoveFn`, `DeleteBranchFn`, `MergeBranchFn`, etc.) that can be replaced in tests. This avoids requiring a real git repository for unit tests while keeping the production code straightforward.
 
 ### Branch Conventions
 

.mindspec/docs/domains/execution/interfaces.md

@@ -13,7 +13,7 @@ type Executor interface {
     FinalizeEpic(epicID, specID, specBranch string) (FinalizeResult, error)
     Cleanup(specID string, force bool) error
 
-    // Epic handoff (notification hook — no-op for GitExecutor)
+    // Epic handoff (notification hook — no-op for MindspecExecutor)
     HandoffEpic(epicID, specID string, beadIDs []string) error
 
     // Query methods
@@ -26,7 +26,7 @@ type Executor interface {
 
 ### GitUtil Helpers (`internal/gitutil/gitutil.go`)
 
-Low-level git operations used only by `GitExecutor`:
+Low-level git operations used only by `MindspecExecutor`:
 
 | Function | Purpose |
 |:---------|:--------|
@@ -49,5 +49,5 @@ Low-level git operations used only by `GitExecutor`:
 
 | Type | Package | Purpose |
 |:-----|:--------|:--------|
-| `GitExecutor` | `internal/executor/git.go` | Production: real git+worktree operations |
+| `MindspecExecutor` | `internal/executor/mindspec_executor.go` | Production: real git+worktree operations |
 | `MockExecutor` | `internal/executor/mock.go` | Testing: records calls, returns configured errors |

.mindspec/docs/domains/execution/overview.md

@@ -2,7 +2,7 @@
 
 ## What This Domain Owns
 
-The **execution** domain owns all git, worktree, and filesystem operations — the "how" layer that performs operations delegated by the workflow layer.
+The **execution engine** owns all git, worktree, and filesystem operations — the "how" layer that implements operations delegated by the workflow layer. It dispatches beads to worktrees, executes code changes, merges results, and finalizes specs.
 
 - **Git operations** — branching, merging, diffstat, commit counting, push/PR creation
 - **Worktree lifecycle** — creating, removing, and switching between isolated workspaces
@@ -14,6 +14,7 @@ The **execution** domain owns all git, worktree, and filesystem operations — t
 Execution does **not** own:
 - Lifecycle phase derivation or mode enforcement (workflow)
 - Approval gates or validation logic (workflow)
+- Plan decomposition or quality assessment (workflow)
 - Beads integration or epic/bead queries (workflow)
 - CLI infrastructure or project health checks (core)
 
@@ -23,9 +24,9 @@ Execution **receives** instructions from the workflow layer via the `Executor` i
 
 | Package | Purpose |
 |:--------|:--------|
-| `internal/executor/` | `Executor` interface + `GitExecutor` + `MockExecutor` |
-| `internal/gitutil/` | Low-level git helpers (branch, merge, PR, diffstat) |
+| `internal/executor/` | `Executor` interface + `MindspecExecutor` (production) + `MockExecutor` (testing) |
+| `internal/gitutil/` | Low-level git helpers (branch, merge, PR, diffstat) — used only by `MindspecExecutor` |
 
 ## Import Rule
 
-Workflow packages (`internal/approve/`, `internal/complete/`, `internal/next/`, `internal/cleanup/`, `internal/specinit/`) MUST call `executor.Executor` methods. They MUST NOT import `internal/gitutil/` directly. This boundary is enforced by convention and checked by `mindspec doctor`.
+Workflow packages (`internal/approve/`, `internal/complete/`, `internal/next/`, `internal/cleanup/`, `internal/spec/`) MUST call `executor.Executor` methods. They MUST NOT import `internal/gitutil/` directly. This boundary is enforced by convention and checked by `mindspec doctor`.

.mindspec/docs/domains/workflow/architecture.md

@@ -13,7 +13,11 @@ Each mode gates:
 - **Required context** — what must be reviewed before proceeding
 - **Transition gates** — what conditions must hold to advance
 
-### Beads as Single State Store (ADR-0023)
+### Beads as Substrate (ADR-0023)
+
+Beads is both the single state store and the **contract between the planning and execution layers**. Each bead is a self-contained work packet that encapsulates requirements, context (impacted domains, ADR citations), dependencies, and acceptance criteria. A fresh agent picking up a bead doesn't need session history — the bead carries everything it needs.
+
+This is what makes execution pluggable: any orchestrator that can read beads can dispatch work. The planning layer writes beads; the execution engine reads them.
 
 All lifecycle state is derived from Beads — no filesystem state files (no `focus`, no `lifecycle.yaml`):
 
@@ -46,7 +50,19 @@ approve/impl.go   ──▶ exec.FinalizeEpic()
 cleanup/          ──▶ exec.Cleanup()
 ```
 
-**Import rule**: Workflow packages (`approve/`, `complete/`, `next/`, `cleanup/`, `specinit/`) call `executor.Executor` methods. They MUST NOT import `internal/gitutil/` directly.
+**Import rule**: Workflow packages (`approve/`, `complete/`, `next/`, `cleanup/`, `spec/`) call `executor.Executor` methods. They MUST NOT import `internal/gitutil/` directly.
+
+### Plan Quality Responsibility
+
+The workflow layer ensures plans are well-decomposed before handoff to the execution engine. This is critical because AI agents perform significantly better on well-structured, bitesize tasks than on vague or monolithic ones (see [arXiv:2512.08296](https://arxiv.org/abs/2512.08296)).
+
+Workflow enforces:
+- **Bead decomposition** — each bead must be a focused, independently completable unit of work
+- **Clear acceptance criteria** — every bead has verifiable completion conditions
+- **Dependency ordering** — beads declare dependencies so the execution engine dispatches them in the right order
+- **Validation gates** — `internal/validate/` checks structural requirements and ADR compliance before plan approval
+
+The execution engine trusts that approved plans are well-decomposed and simply executes them — it does not assess plan quality.
 
 ### ADR Governance
 

.mindspec/docs/domains/workflow/overview.md

@@ -29,7 +29,7 @@ Workflow **uses** context packs (from context-system) to provide mode-appropriat
 | `internal/approve/` | Spec, plan, and impl approval enforcement |
 | `internal/complete/` | Bead close-out orchestration |
 | `internal/next/` | Work selection, claiming, worktree dispatch |
-| `internal/specinit/` | Spec creation (worktree-first flow) |
+| `internal/spec/` | Spec creation (worktree-first flow) |
 | `internal/cleanup/` | Post-lifecycle worktree/branch cleanup |
 | `internal/phase/` | Phase derivation from beads (ADR-0023) |
 | `internal/resolve/` | Target spec resolution and prefix matching |