pi-soly 0.2.1

package/workflows-data/discuss-phase.md

@@ -0,0 +1,292 @@
+# Discuss Phase
+
+<purpose>Reference document for the **interactive** `soly discuss <N>` flow. The
+discussion is now driven by the interactive LLM (you) directly — no subagent.
+You use the `soly_ask_user` tool to ask questions one at a time via a real
+UI picker, and `soly_finish_discuss` to write the canonical CONTEXT.md. This
+markdown is background context, not a strict protocol.</purpose>
+
+<path_discipline>
+**All soly-managed files live under `.soly/`.** CONTEXT.md, RESEARCH.md, and the discuss checkpoint all go in `.soly/phases/<NN>-<slug>/`. Never write these to the project root. Use absolute paths.
+
+The iteration context file (path given by the parent in the task prompt) is your single source of truth for intent, STATE, ROADMAP, and any existing phase artifacts. Read it FIRST.
+</path_discipline>
+
+<interactive_flow>
+**The flow is now interactive, not subagent-based.** The parent (extension) hands you a detailed prompt with the UX protocol. You drive the discussion in the same session:
+
+1. **Read the iteration context file** (path given in the task prompt). It's the single source of truth — do NOT re-read STATE.md, ROADMAP.md, CONTEXT.md separately.
+
+2. **Generate 3-5 phase-specific gray areas** grounded in the intent + ROADMAP row. For each, prepare a question with 2-3 CONCRETE options, ⭐ first = recommended answer, with 1-sentence rationale.
+
+3. **Pick a picker** (the parent's prompt tells you which one is preferred):
+   - **`ask_pro`** (from the separate `pi-ask` extension, if installed) — multi-question tabbed picker. **PREFERRED**: call ONCE with all questions, returns all answers in one shot. Supports `allowOther: true` for free-text input per question.
+   - **`soly_ask_user`** (always available as fallback) — single-question picker. Call N times, one per question. No `allowOther` support.
+
+4. **Save a checkpoint after each answer** with `soly_save_discuss_checkpoint` so the user can quit and resume. The final `soly_finish_discuss` will delete the checkpoint and write CONTEXT.md.
+
+5. **After all questions captured**, call `soly_finish_discuss` with all decisions. It writes `<phase>-CONTEXT.md` and deletes the checkpoint.
+
+6. **Tell the user the next step**: `soly plan <N>`.
+
+**Resume:** if a checkpoint file exists, the parent detects it and tells you to resume from where the prior session left off. Acknowledge locked decisions at the top of your output, then continue with the next un-answered gray area.
+</interactive_flow>
+
+<read_first>`.soly/docs/` (INTENT, 0-point) · `.soly/STATE.md` · `.soly/ROADMAP.md` · `${PHASE_DIR}/*-CONTEXT.md` if exists (refine, don't re-derive) · `${PHASE_DIR}/*-DISCUSS-CHECKPOINT.json` if exists (resume from `areas_completed`)</read_first>
+
+<philosophy>
+**User = visionary. Worker = builder.** The user knows: how it should feel, what's essential vs nice-to-have, specific references. The user doesn't know (don't ask): codebase patterns, technical risks, implementation approach, success metrics.
+
+Ask about vision and implementation choices. Capture for downstream.
+</philosophy>
+
+<scope_guardrail>
+**No scope creep.** Phase boundary from `ROADMAP.md` is FIXED. Clarify HOW, never WHETHER.
+- **Allowed:** "How should posts display?" · "What happens on empty?" · "Pull-to-refresh or manual?"
+- **Not allowed:** "Should we also add comments?" · "What about search?" — new capability, its own phase.
+
+If the user suggests scope creep: `"[X] would be a new capability — its own phase. Want me to note it for the backlog? For now, focus on [phase domain]."` Capture in `<deferred_ideas>`.
+</scope_guardrail>
+
+<gray_area_identification>
+Gray areas are implementation decisions the user cares about — could go multiple ways, would change the result.
+
+1. Read phase goal from `ROADMAP.md`.
+2. Identify the domain (something users SEE/CALL/RUN/READ/ORGANIZE).
+3. Generate phase-specific gray areas — **not** generic (UI/UX/Behavior).
+
+Examples:
+- Auth → Session handling · Error responses · Multi-device policy · Recovery flow
+- Photo library → Grouping · Duplicates · Naming · Folder structure
+- DB backup CLI → Output format · Flag design · Progress · Error recovery
+- API docs → Structure · Example depth · Versioning · Interactivity
+
+**Don't ask about:** implementation details, architecture, performance, scope (roadmap defines).
+</gray_area_identification>
+
+<output_protocol>
+The `soly_ask_user` tool handles the user interaction. Each call is one round:
+
+- **Picker shows:** title + question + rationale + numbered options. User navigates with ↑/↓/j/k, Enter to confirm, Esc to cancel.
+- **Recommended option** (⭐ first) is visually marked so the user can pick it with one keystroke.
+- **Rationale** is shown above the picker — this is the most important UX element, it shows the user that you've thought about the trade-off.
+- **After answer**: tool returns the chosen option text. You acknowledge, save a checkpoint, and call `soly_ask_user` for the next question.
+
+When all questions are captured, call `soly_finish_discuss` with all the collected decisions. It writes the canonical `<phase>-CONTEXT.md` per the schema below and deletes the checkpoint file.
+
+The OLD subagent output protocol (with `## Gray Areas — Round N`, etc.) is **no longer used**. The picker replaces it.
+</output_protocol>
+
+<process>
+
+**1. Initialize.** Compute state via `bash` (no SDK):
+
+```bash
+PHASE=$1
+# Worker subagent inherits the parent's cwd (the project root), so
+# `pwd` IS the project root. The previous `cd .. && pwd` was a bug.
+PROJECT_ROOT="$(pwd)"
+SOLY_DIR="$PROJECT_ROOT/.soly"
+PHASE_DIR=$(ls -d "$SOLY_DIR/phases/"*"-$PHASE-"* 2>/dev/null | head -1) || { echo "Phase $PHASE not found" >&2; exit 1; }
+PADDED_PHASE=$(printf "%02d" "$(echo "$PHASE" | grep -oE '^[0-9]+' | sed 's/^0*//')")
+PHASE_SLUG=$(basename "$PHASE_DIR")
+HAS_CONTEXT=$([ -f "$PHASE_DIR/${PADDED_PHASE}-CONTEXT.md" ] && echo true || echo false)
+HAS_RESEARCH=$([ -f "$PHASE_DIR/${PADDED_PHASE}-RESEARCH.md" ] && echo true || echo false)
+PLAN_COUNT=$(ls "$PHASE_DIR"/${PADDED_PHASE}-*-PLAN.md 2>/dev/null | wc -l | tr -d ' ')
+HAS_CHECKPOINT=$([ -f "$PHASE_DIR/${PADDED_PHASE}-DISCUSS-CHECKPOINT.json" ] && echo true || echo false)
+ROADMAP_EXISTS=$([ -f "$SOLY_DIR/ROADMAP.md" ] && echo true || echo false)
+```
+
+If `ROADMAP_EXISTS=false` → stop, tell parent "project must be initialized with a roadmap first."
+
+**2. Check blocking anti-patterns.** Read `${PHASE_DIR}/.continue-here.md` if it exists; parse its Critical Anti-Patterns table for `severity = blocking`. For each, include in the next round's output:
+
+```
+## Blocking Anti-Patterns (from .continue-here.md)
+> Resume agent must demonstrate understanding before proceeding.
+
+### <pattern name>
+1. **What is it?** ...
+2. **How did it manifest?** ...
+3. **Structural prevention:** ...
+```
+
+If you cannot answer from `.continue-here.md`, return `## Clarifications Needed` and stop.
+
+**3. Check SPEC.md.** `ls "$PHASE_DIR"/*-SPEC.md 2>/dev/null | grep -v AI-SPEC | head -1`. If exists: read, count `## Requirements`, treat as locked — do NOT re-ask WHAT/WHY, only HOW. Add to `## Decisions Locked`.
+
+**4. Resume / continue / fresh.**
+
+| state | action |
+|---|---|
+| checkpoint exists | parse `decisions` + `areas_completed`; acknowledge locked; continue from first un-answered area |
+| CONTEXT.md exists, no checkpoint | "refine" mode — list existing decisions, surface only uncovered gray areas |
+| PLANs exist, no CONTEXT.md | warn in round 1: `## Heads Up — <N> plan(s) exist without user context. Decisions here won't affect them unless you replan. To proceed anyway, just answer. To abort, stop here.` |
+| (none) | fresh — initialize phases 5–9 from scratch |
+
+**5. Load prior context.** Read in this order, deduplicating:
+
+```bash
+[ -f "$SOLY_DIR/PROJECT.md" ] && echo "PROJECT.md"
+[ -f "$SOLY_DIR/REQUIREMENTS.md" ] && echo "REQUIREMENTS.md"
+[ -f "$SOLY_DIR/STATE.md" ] && echo "STATE.md"
+[ -f "$SOLY_DIR/DECISIONS-INDEX.md" ] && echo "DECISIONS-INDEX.md (prefer over per-phase if present)"
+```
+
+Most-recent 3 prior `*-CONTEXT.md` files (prefer DECISIONS-INDEX if present). Extract `<decisions>`, `<specifics>`, and patterns (e.g., "user prefers minimal UI"). If `.soly/spikes/MANIFEST.md` or `.soly/sketches/MANIFEST.md` exist with `WRAPPED: true` frontmatter, read as validated findings.
+
+**6. Cross-reference todos.** (Worker doesn't have `soly_todos`; use `bash` + `grep` with phase-domain keywords.)
+
+```bash
+KEYWORDS="<phase-domain-keywords>"  # e.g. "auth|login|session"
+grep -rnE "TODO|FIXME|XXX" --include="*.ts" --include="*.tsx" --include="*.py" --include="*.go" "$PROJECT_ROOT" 2>/dev/null \
+  | grep -iE "$KEYWORDS" | head -20
+```
+
+Present matches; user picks folded (→ CONTEXT.md `<folded_todos>`) vs reviewed-not-folded (→ `<reviewed_todos>`).
+
+**7. Scout codebase.** (No SDK; pure bash/find/grep.)
+
+```bash
+ls "$SOLY_DIR/codebase/" 2>/dev/null
+find "$PROJECT_ROOT/src" -maxdepth 3 -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.py" \) 2>/dev/null | head -20
+```
+
+Build a small `<codebase_context>` block (≤ 10 lines) of reusable assets/patterns. Use to annotate gray areas ("you already have a Card component with shadow/rounded variants — reusing it keeps the app consistent").
+
+**8. Analyze phase.** Grounded in `<prior_decisions>`, `<codebase_context>`, `<locked_requirements>`. Produce:
+- **Domain boundary** — what this phase delivers, what it does NOT.
+- **Canonical refs accumulator** — every doc/spec/ADR the planner will need (ROADMAP refs, REQUIREMENTS, anything the user references). Full relative paths. MANDATORY in CONTEXT.md.
+- **Already-decided gray areas** — skip from `<prior_decisions>` + `<locked_requirements>`.
+- **Gray areas** — 1–2 specific ambiguities per relevant category.
+- **Skip assessment** — if no meaningful gray areas remain, jump to step 11 with `<no_discussion_needed: true>`.
+
+**9. Present gray areas.** Output `## Gray Areas — Round <N>` per output protocol. **3–5 areas/round sweet spot; > 5 → defer the rest to next round.** No "skip" / "you decide" options — give real choices.
+
+**10. Discuss (interactive, one question at a time).**
+
+**PREFERRED** (if `ask_pro` tool is available from the `pi-ask` extension): call `ask_pro` ONCE with all questions as tabs. Returns all answers in one shot. Per question: `header`, `question`, `options[2-4]`, optional `multiSelect`, optional `allowOther` (text input for custom answer).
+
+**FALLBACK** (if `ask_pro` is not available): call `soly_ask_user` once per question, one at a time. Pattern:
+
+```
+soly_ask_user({
+  title: "Q1: <category>",
+  question: "<one short sentence>",
+  options: [
+    "⭐ <recommended option> — <1 sentence why>",
+    "<alternative 1>",
+    "<alternative 2>",
+  ],
+  rationale: "<1–2 sentence note>",
+})
+```
+
+After each answer (or once after all answers, for `ask_pro`), call `soly_save_discuss_checkpoint({phase_number, decisions, areas_total, areas_completed})` to enable resume. The user can quit mid-discussion and the next `soly discuss <N>` will pick up from the checkpoint.
+
+If the user cancels a picker (Esc), defer that question and move on — never loop on the same question.
+
+When all questions captured, call `soly_finish_discuss` with all decisions. It writes the canonical CONTEXT.md and deletes the checkpoint.
+
+**11. Write CONTEXT.md** when all areas decided (or explicitly deferred):
+
+```markdown
+---
+phase: <N>  phase_slug: <slug>  generated: <ISO8601>
+areas_completed: <N>  areas_deferred: <N>
+---
+
+# <N>: <Name> — Discussion Context
+
+<domain>What this phase delivers, 1–2 paragraphs grounded in ROADMAP + intent.</domain>
+
+<spec_lock><!-- only if SPEC.md was loaded -->
+Requirements locked by SPEC.md. Do not re-litigate.
+- <req 1>
+</spec_lock>
+
+<decisions>
+### <Category>
+- **Decision:** <what>
+  **Rationale:** <why / "user discretion">
+  **Source:** Round <N> of `soly discuss <N>`
+</decisions>
+
+<canonical_refs> <!-- MANDATORY -->
+- `.soly/docs/<file>` — <why>
+- `.soly/features/<feat>/README.md` — <why>
+- `.soly/contracts/<file>` — <why>
+- (no external docs referenced) <!-- only if literally none -->
+</canonical_refs>
+
+<code_context>
+Reusable assets/patterns the planner should know:
+- <path> — <what, why reuse>
+</code_context>
+
+<deferred_ideas>Scope-creep items for future phases.</deferred_ideas>
+
+<folded_todos><!-- only if matches found --></folded_todos>
+<reviewed_todos><!-- only if matches found --></reviewed_todos>
+```
+
+If `spec_lock` present, do NOT duplicate requirements into `<decisions>` — only implementation decisions.
+
+**12. Report.**
+
+- All decided:
+  ```
+  ## Discussion Complete — Phase <N>
+  Created: <path>
+  ### Decisions Captured
+  - <Cat>: <one-liner>
+  ### Deferred
+  - <idea> — future phase
+  ### Next Step
+  `soly plan <N>`
+  ```
+- More rounds needed:
+  ```
+  ## Round <N> Complete — Phase <N>
+  ### Decisions Captured This Round
+  - <Cat>: <one-liner>
+  ### Open Questions (<M> remaining)
+  - <Area>: <ambiguity>
+  ### Next Step
+  Re-invoke `soly discuss <N>` to continue. Your next free-text message will be parsed for answers.
+  ```
+
+</process>
+
+<checkpoint_schema>
+`${PHASE_DIR}/${PADDED_PHASE}-DISCUSS-CHECKPOINT.json`:
+
+```json
+{
+  "version": "1.0",
+  "phase": <N>, "padded_phase": "<NN>", "phase_slug": "<slug>", "phase_dir": "<path>",
+  "round": <N>,
+  "areas_total": <M>,
+  "areas_completed": [<index>, ...],
+  "areas_deferred":  [<index>, ...],
+  "decisions": [
+    {"area": "<n>", "category": "<c>", "choice": "<what>", "rationale": "<why / 'user discretion'>", "round": <N>}
+  ],
+  "canonical_refs":   ["<path>", ...],
+  "codebase_context": ["<line>", ...],
+  "deferred_ideas":   ["<idea>", ...],
+  "next_action": "await_user_answers | write_context | no_discussion_needed"
+}
+```
+
+Update after every round. Delete after `write_context` succeeds.
+</checkpoint_schema>
+
+<hard_rules>
+- No production code. Discussion/planning only.
+- No PLAN.md from this workflow — that's `soly plan`.
+- Don't assume missing intent. If `.soly/docs/` is silent, ask.
+- No scope creep. Deferred ideas → `<deferred_ideas>`, not decisions.
+- No subagents (you ARE one). No `.soly/rules/` edits.
+- Return: structured output per output_protocol + checkpoint updates. Parent relays to user.
+</hard_rules>

package/workflows-data/execute-phase.md

@@ -0,0 +1,200 @@
+# Execute Phase
+
+<purpose>Execute all plans in a phase, wave by wave. Per plan, follow `execute-plan.md` inline. Update STATE.md between plans. Generate a phase-level VERIFICATION.md at the end. You ARE the executor (`maxSubagentDepth: 1` is enforced — no sub-sub-agents). Checkpoint requests return a structured block; parent relays to user; next `soly execute <N>` resumes from `.execute-checkpoint.json`.</purpose>
+
+<path_discipline>
+**All soly-managed files live under `.soly/`.** Never write PLAN.md, CONTEXT.md, RESEARCH.md, SUMMARY.md, iteration files, or handoffs to the project root. All phase files go in `.soly/phases/<NN>-<slug>/`. Use absolute paths (or paths starting with `$SOLY_DIR`) — never bare relative names that could land in cwd.
+
+The iteration context file (path given by the parent in the task prompt) is your single source of truth for intent, STATE, ROADMAP, and any existing phase artifacts. Read it FIRST, before any of your own `read` or `ls` calls.
+</path_discipline>
+
+<read_first>`.soly/STATE.md` (single source of truth for "where am I") · `.soly/ROADMAP.md` (phase goal + reqs) · `.soly/docs/` (INTENT, re-read before each plan) · the phase directory: list PLAN.md sorted, plus any SUMMARY.md / CONTEXT.md / RESEARCH.md / `.execute-checkpoint.json`. If `.soly/` missing → stop + error.</read_first>
+
+<core_principle>
+**Orchestrate, don't re-specify.** Each PLAN.md is the contract; `execute-plan.md` is the per-plan protocol. This file adds: wave grouping, state transitions between plans, phase-level aggregation (VERIFICATION.md), safe resumption from partial state. The full per-plan steps live in `execute-plan.md` — read it once, then apply per plan.
+</core_principle>
+
+<process>
+
+**1. Parse args.** `PHASE` (required) plus optional `--plan <M>`, `--wave <W>`, `--from <M>`. If `--plan` is set, `PLAN_MODE=true` — skip wave grouping (defer to `execute-plan.md`).
+
+**2. Initialize.** `bash` only:
+
+```bash
+PHASE="$1"
+# Worker subagent inherits the parent's cwd (the project root), so
+# `pwd` IS the project root. The previous `cd .. && pwd` was a bug
+# that sent files to the parent of the project (and then the worker
+# would fall back to the `write` tool with a relative path, polluting
+# the project root).
+PROJECT_ROOT="$(pwd)"
+SOLY_DIR="$PROJECT_ROOT/.soly"
+PHASE_DIR=$(ls -d "$SOLY_DIR/phases/"*"-$PHASE-"* 2>/dev/null | head -1) || { echo "Phase $PHASE not found" >&2; exit 1; }
+PADDED_PHASE=$(printf "%02d" "$(echo "$PHASE" | grep -oE '^[0-9]+' | sed 's/^0*//')")
+PHASE_SLUG=$(basename "$PHASE_DIR")
+mapfile -t ALL_PLANS < <(ls "$PHASE_DIR"/${PADDED_PHASE}-*-PLAN.md 2>/dev/null | sort)
+mapfile -t ALL_SUMMARIES < <(ls "$PHASE_DIR"/${PADDED_PHASE}-*-SUMMARY.md 2>/dev/null | sort)
+COMPLETED=$(for p in "${ALL_PLANS[@]}"; do [ -f "${p/-PLAN.md/-SUMMARY.md}" ] && echo 1; done | wc -l)
+HAS_CHECKPOINT=$([ -f "$PHASE_DIR/.execute-checkpoint.json" ] && echo true || echo false)
+```
+
+If `HAS_CHECKPOINT=true` → read it, resume from `next_task_index`, surface `## Resuming From Checkpoint` in your first output.
+
+**3. Safe-resume gate** (detect illegal partial state BEFORE any new work):
+
+```bash
+for p in "${ALL_PLANS[@]}"; do
+  s="${p/-PLAN.md/-SUMMARY.md}"
+  [ -f "$s" ] && continue
+  PLAN_ID=$(basename "$p" | sed -E "s/^${PADDED_PHASE}-([0-9]+)-.*/\1/")
+  if git log --oneline --all --grep="${PADDED_PHASE}-${PLAN_ID}" 2>/dev/null | grep -q .; then
+    echo "PARTIAL: $p has production commits but no SUMMARY"
+  fi
+done
+```
+
+If any partial state detected → return `## Partial Plans Detected` listing them, **stop**. Do not silently re-execute; user chooses resume-summary-write / rollback / investigate.
+
+**4. Check blocking anti-patterns.** Read `${PHASE_DIR}/.continue-here.md` if it exists; parse its Critical Anti-Patterns table for `severity = blocking`. For each, output `## Blocking Anti-Patterns` with the 3-question format (what / how manifested / structural prevention). If unanswerable from `.continue-here.md` → return `## Clarifications Needed` and stop.
+
+**5. Discover + group plans.** Parse frontmatter of each PLAN.md for `wave:`, `depends-on:`, `requirements:`. Group by wave (1, 2, ...). Within a wave, dependency-driven order; file-name sort for unconstrained ties.
+
+**Validate wave graph:**
+
+| check | rule |
+|---|---|
+| Acyclic | walk `depends-on:` — no plan depends on itself, transitively or directly |
+| Wave-consistent | `plan.wave > max(wave of its deps)` |
+| External deps | any `depends-on:` outside this phase points to prior-phase work already Complete in STATE.md |
+
+If validation fails → return `## Wave Graph Invalid`, stop.
+
+**6. Execute waves.** For each wave:
+
+1. List plans in dependency-safe order.
+2. For each plan, **run the per-plan loop** (step 7).
+3. After the wave, run wave gates (step 8).
+4. If `--wave <W>` set and we're past W, stop.
+
+Within a wave, plans are "parallel" in name but you do the work sequentially in this worker context. **Skip rule:** if a plan already has SUMMARY.md, skip — it's done from a prior invocation. Update `completed` count.
+
+**7. Per-plan loop** (apply `execute-plan.md` inline — don't re-specify its steps):
+
+```
+For plan P:
+  1. record_start_time
+  2. parse_plan (count tasks, find acceptance criteria, checkpoints)
+  3. load_prompt (read PLAN.md fully; honor CONTEXT.md, RESEARCH.md)
+  4. execute tasks sequentially: read read_first → implement → verify
+     acceptance criteria (HARD GATE) → commit per task
+  5. if checkpoint:* reached → write .execute-checkpoint.json,
+     return Checkpoint block to parent, STOP
+  6. create_summary + commit SUMMARY.md (atomic — no narrative between;
+     write to `${PHASE_DIR}/${PADDED_PHASE}-${M}-<slug>-SUMMARY.md` — absolute path)
+  7. update_state: bump current_plan in STATE.md; mark plan row in
+     ROADMAP.md
+  8. update_requirements if PLAN.md has `requirements:`
+  9. delete .execute-checkpoint.json (if any)
+ 10. record result for wave aggregation
+```
+
+**8. Wave gates (after each wave).**
+
+**Regression check** — run the project's test suite (`npm test` / `bun test` / `dotnet test` / `pytest` / `go test ./...`). All previously-passing tests must still pass.
+
+- Regression detected → STOP, return `## ⚠ Regression Detected` (failing tests, wave that introduced them, recommendation: revert / fix / continue with acknowledged breakage).
+- Regression in CONTEXT.md as "expected" (e.g., "Wave 2 breaks test X; fixed in Wave 3") → continue.
+
+**Cross-plan wiring check** — for each `must_haves.key_links` in each plan's SUMMARY, spot-check the link exists. If missing, log in wave summary; do NOT fail the wave.
+
+These gates are intentionally lighter than a full external verifier — soly on pi trusts the executor's `acceptance_criteria` HARD GATE.
+
+**9. Checkpoint handling.** When a plan hits `type="checkpoint:*"` or auth gate → follow `execute-plan.md`'s checkpoint protocol: write `.execute-checkpoint.json`, return `## Checkpoint` to parent. Parent presents, gathers response, re-invokes `soly execute <N>`. Next invocation picks up from the JSON.
+
+**10. Aggregate + VERIFICATION.md.** After all waves:
+
+```
+## Phase <N>: <Name> Execution Complete
+### Plans
+- Plan 1: <title> — <duration> — <tasks>/<total> — <files mod> — <commit range>
+### Wave Summary
+- Wave 1: <n> plan(s), <dur>, <f> files · Wave 2: ...
+### Total  Plans <X>/<Y> · Duration <T> · Files <N> created, <M> modified · Deviations <K>
+### Issues Encountered  <aggregated from each SUMMARY "Issues Encountered">
+### Next  `soly status` · `<project verify cmd>` · `soly plan <N+1>` or `soly pause`
+```
+
+Write `${PHASE_DIR}/${PADDED_PHASE}-VERIFICATION.md` (the canonical "did the phase deliver what ROADMAP said" check). Use the absolute path — never a bare relative name.
+
+```markdown
+---
+phase: <N>  phase_slug: <slug>  status: pending  generated: <ISO>
+---
+
+# Phase <N>: <Name> — Verification
+
+## Phase Goal
+<one-line from ROADMAP.md>
+
+## Requirements Coverage
+| Req ID | Plan | Status | Notes |
+|---|---|---|---|
+| REQ-01 | Plan 2 | complete | see SUMMARY § Verification |
+
+## Test Results
+- <verify cmd> → <result>
+
+## Manual Verification
+<URLs to open, behaviors to confirm>
+
+## Gaps
+- [ ] <not yet verified>
+- [ ] <another gap>
+
+## Status
+`pending` until the user (or a verifier) flips to `passed` / `failed`. Phase is "Complete" when this file exists AND `status: passed`.
+```
+
+**Do NOT flip status to `passed` yourself** — that decision belongs to the user or a verifier.
+
+**11. Update ROADMAP.md** (read + edit at `${SOLY_DIR}/ROADMAP.md` — absolute path):
+- Phase row status → `Complete` if VERIFICATION.md `status: passed`, else `In Progress`.
+- Update `completed_plans` count.
+
+**12. Update STATE.md** (at `${SOLY_DIR}/STATE.md` — absolute path):
+- Phase status → `Complete` (if VERIFICATION passed) or `Needs Review` (if not).
+- Reset `current_plan` → 0. Update `last_updated`. Update `progress:` block.
+- Keep < 150 lines.
+
+**13. Return:**
+
+- Complete:
+  ```
+  ## ✓ Phase <N>: <Name> Complete
+  ### What Shipped  <2–3 sentences>
+  ### Stats  Plans: <n> · Files: <c> created / <m> modified · Reqs: <c>/<t> · Deviations: <d>
+  ### Verification  <path> created (status: pending — flip after smoke test)
+  ### Next  `soly plan <N+1>` · `soly status` · `soly pause`
+  ```
+- Incomplete (some plans unshipped / checkpoint pending):
+  ```
+  ## ⚠ Phase <N>: <Name> Incomplete
+  ### Shipped
+  - Plan 1: <title> — <dur>
+  ### Outstanding
+  - Plan 3: <title> — checkpoint reached, awaiting user input
+  - Plan 5: <title> — not started
+  ### Next  Re-invoke `soly execute <N>` to continue.
+  ```
+
+</process>
+
+<hard_rules>
+- No `.soly/rules/` edits. No subagents (`maxSubagentDepth: 1`).
+- No silent skip of partial-state plans — surface and stop.
+- No flipping VERIFICATION.md to `passed` yourself.
+- No silent architectural decisions — use `execute-plan.md`'s Rule 4 + checkpoint.
+- Wave graph acyclic; validate before executing.
+- Conventional Commits 1.0.0. Per-plan: `<type>(<plan-id>): <summary>`.
+- Return: phase summary, per-plan rollup, verification status, next step.
+</hard_rules>