# Harness Migration (Gap E/F) Implementation Plan

> **For agentic workers:** both tasks below target files OUTSIDE this git repo (`~/.claude/skills/`) — apply inline, no dispatch. Not executable via `ship`/`sdd` subagent worktree flow.

**Goal:** `brainstorm` emits harness-native plan JSONL by default (Gap E); `handoff` branches correctly on schema presence (Gap F).

**Architecture:** two small prose edits to global skill docs. No code, no schema change to the harness engine itself.

**Tech Stack:** Markdown (SKILL.md prose).

---

## Wave Plan

| Wave | Tasks | Files touched | Safe to parallelize? |
|------|-------|----------------|----------------------|
| 1 | Task 1, Task 2 | `~/.claude/skills/brainstorm/SKILL.md`, `~/.claude/skills/handoff/SKILL.md` | ✅ no overlap |

## Task 1: brainstorm emits harness-native plans by default (Gap E)

**Wave:** 1
**Blocks:** —
**Blocked by:** —
**Apply inline (cross-repo target, not worktree-dispatchable), no dispatch.**

**Files:**
- Modify: `~/.claude/skills/brainstorm/SKILL.md` checklist step 8 (currently: "**Invoke plan skill → route to executor** — auto after advisor approves; immediately after plan saves its doc, populate section 9 from the wave/phase table, then route: …")

**Contract:** insert one explicit trigger line into step 8, immediately after "populate section 9 from the wave/phase table, then route:" and before the existing "Multi-wave/multi-phase" bullet:

```
   - **Target engine: harness-native (default) unless an earlier `direction` record in this session implies Workflow-controller/subagent-dispatch execution (e.g. "dispatch each task to its own subagent", "use the orchestrator") — no per-run question, no content-based heuristic beyond that lookup.** Harness-native → serialize section 9 per the harness-native schema below (no `schema` key on the `meta` line) instead of `session-state/v1`. Workflow-controller found → existing `session-state/v1` serialization, unchanged.
```

Then add a new subsection right after the existing "Compact-Proof Session File" section (same heading level, `##`), titled `## Harness-Native Session File (when step 8 selects it)`, containing VERBATIM the schema block from `docs/specs/2026-07-01-harness-migration-design.md` §2 "Schema (harness-native session file, brainstorm-authored)" through its "Field rules" subsection (the fenced `jsonl` block + the 5 field-rule bullets: `id`, `wave`, `seat`, `tier`, `preset`, `desc`, `requires_decision`). Copy the field-rule text verbatim from the spec — do not paraphrase, this is a required literal format other tooling depends on.

**Behavior:**
- Existing `session-state/v1` emission path (used for Workflow-controller-targeted plans) is completely unchanged — this is additive, a new branch, not a replacement.
- `run-plan`'s existing schema-key-based routing (already shipped) requires zero changes — it already discriminates on presence/absence of `schema` on the `meta` line.

**Acceptance (one executable check):**
- Run: `grep -c "Target engine: harness-native" ~/.claude/skills/brainstorm/SKILL.md`
- Expected: `1`
- Run: `grep -c "Harness-Native Session File" ~/.claude/skills/brainstorm/SKILL.md`
- Expected: `1`

- [ ] Apply the step 8 insertion + new subsection per the contract above
- [ ] Run both acceptance checks → expected output above
- [ ] Commit: (this repo has nothing to commit for this task — `~/.claude/skills/` is a separate location outside this git repo; no `git add`/`git commit` here)

## Task 2: handoff branches on schema presence (Gap F)

**Wave:** 1
**Blocks:** —
**Blocked by:** —
**Apply inline (cross-repo target, not worktree-dispatchable), no dispatch.**

**Files:**
- Modify: `~/.claude/skills/handoff/SKILL.md` § "2. Session-state JSONL (when handing off resumable execution work)", specifically its "Procedure" numbered list (items 1-3).

**Contract:** insert one new step 0 before the existing "Procedure:" numbered list (renumber nothing else — existing items 1-3 stay as-is, describing the `session-state/v1` path):

```
**Procedure:**
0. **Read the JSONL's first line first.** No `schema` key on the `meta` line (harness-native format) → SKIP steps 1-3 entirely (no `exec_mode` write, no per-task `status` reconciliation — the harness engine's own journal at `runstate/<slug>.jsonl` is already durable resume ground truth). Surface to the user instead: `"Session slug: <slug> — resume with bin/runplan <slug> --preset <preset> --resume (harness engine; the runstate journal is the resume source of truth, not this plan file)."` Then stop — do not continue to step 3's "Surface the slug" either, this replaces it for this branch.
   `"schema":"session-state/v1"` present → continue to step 1 below, unchanged.
```

**Behavior:**
- Harness-native JSONL: `handoff` performs zero writes to the plan file. It only reads the first line to classify, then emits the one surfacing message above.
- `session-state/v1` JSONL: existing steps 1-3 (reconcile-existing / create-new / surface-slug) run exactly as today — no behavior change on that path.

**Acceptance (one executable check):**
- Run: `grep -c "Read the JSONL's first line first" ~/.claude/skills/handoff/SKILL.md`
- Expected: `1`

- [ ] Apply the step 0 insertion per the contract above
- [ ] Run the acceptance check → expected output above
- [ ] Commit: (nothing to commit in this repo — same cross-repo note as Task 1)