pi-soly 0.2.1

package/workflows-data/execute-plan.md

@@ -0,0 +1,251 @@
+# Execute Plan
+
+<purpose>Execute one PLAN.md, produce a matching SUMMARY.md, update STATE.md/ROADMAP.md. Single worker — no sub-subagents.</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, phase CONTEXT/RESEARCH, prior SUMMARYs, and (section 6) the current PLAN. Read it FIRST.
+</path_discipline>
+
+<read_first>`.soly/STATE.md` · `.soly/ROADMAP.md` · `PLAN.md` (the contract) · `<phase>-CONTEXT.md` if exists (honor user decisions) · `<phase>-RESEARCH.md` if exists (use chosen libs/patterns). If `.soly/` missing → stop + error.</read_first>
+
+<atomic_close_out>
+**Only legal close-out order:** `production-code commit(s) → SUMMARY commit → STATE/ROADMAP update`.
+The only legal half-state is mid-production-commits while still actively working. Once production commits exist, returning without a committed SUMMARY is an **illegal partial-plan state** — the next `soly execute-plan` must detect it before starting a new plan.
+</atomic_close_out>
+
+<process>
+
+**1. Init context + partial-plan check.** `bash` only (no SDK):
+
+```bash
+PHASE="$1"; PLAN="$2"  # PLAN optional — defaults to next unfinished
+# 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")
+mapfile -t ALL_PLANS < <(ls "$PHASE_DIR"/${PADDED_PHASE}-*-PLAN.md 2>/dev/null | sort)
+
+# Pick target plan
+if [ -n "$PLAN" ]; then
+  TARGET_PLAN="$PHASE_DIR/${PADDED_PHASE}-$PLAN-PLAN.md"
+else
+  for p in "${ALL_PLANS[@]}"; do
+    [ ! -f "${p/-PLAN.md/-SUMMARY.md}" ] && { TARGET_PLAN="$p"; break; }
+  done
+fi
+[ -z "$TARGET_PLAN" ] || [ ! -f "$TARGET_PLAN" ] && { echo "No unfinished PLAN.md" >&2; exit 1; }
+
+PLAN_NUM=$(basename "$TARGET_PLAN" | sed -E "s/^${PADDED_PHASE}-([0-9]+)-.*/\1/")
+EXPECTED_SUMMARY="${TARGET_PLAN/-PLAN.md/-SUMMARY.md}"
+COMMIT_COUNT=$(git log --oneline --all --grep="${PADDED_PHASE}-${PLAN_NUM}" 2>/dev/null | wc -l | tr -d ' ')
+SUMMARY_EXISTS=$([ -f "$EXPECTED_SUMMARY" ] && echo true || echo false)
+PARTIAL_PLAN=$([ "$COMMIT_COUNT" -gt 0 ] && [ "$SUMMARY_EXISTS" = false ] && echo true || echo false)
+```
+
+**If `PARTIAL_PLAN=true`** → return `## Partial Plan Detected` to parent and STOP. Do not silently overwrite. User decides: resume summary-write, rollback, or investigate.
+
+**2. Record start time.** `PLAN_START_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ")` · `PLAN_START_EPOCH=$(date +%s)`
+
+**3. Parse plan structure.** `grep -cE '^\s*<task' "$PLAN_PATH"` for task count; `grep -nE 'type="checkpoint|<acceptance_criteria>'` for hotspots. Execute all tasks yourself sequentially — no sub-subagent dispatch.
+
+**3.5. Seed pi-todo (cross-extension, optional).** If the `todo_update` tool is available in this session (the `pi-todo` extension is installed), call it NOW with one TodoItem per `<task>` from the plan, all `status: "pending"` with `activeForm` set to the present-continuous form of the task. Then set the first task to `in_progress` before starting work. This gives the user a live checklist in the footer. Clear the list (`todo_update({todos: []})`) after the SUMMARY is committed (step 12) when the plan is fully done.
+
+**4. Load the plan as contract.** Read PLAN.md fully. **If `<interfaces>` block exists → use those types directly, don't re-read source files. If per-task `<read_first>` exists → read every listed file BEFORE any edit (not optional — ground truth).**
+
+**5. Execute tasks in order.** Per task:
+
+1. **Read first** — open every `<read_first>` file.
+2. **Implement** — minimal correct change, follow project patterns. No speculative scaffolding. No `.soly/rules/` edits.
+3. **Verify acceptance criteria (HARD GATE):**
+   - Run the grep/file-check/CLI for each criterion in `<acceptance_criteria>`.
+   - Log PASS/FAIL with output. If ANY fails → fix immediately, re-run ALL.
+   - Loop until all pass. If can't pass after 2 fix attempts → log as deviation. **Do NOT silently skip.**
+4. **Run `<verification>`** commands (lint, typecheck, scoped tests).
+5. **Commit per task:**
+   ```bash
+   git add <files>
+   git commit -m "<type>(${PADDED_PHASE}-${PLAN_NUM}): <task summary>"
+   ```
+   `<type>` ∈ `feat | fix | refactor | test | chore | docs`. Track commit hash for summary.
+6. **On `type="checkpoint:*"`** → STOP, return Checkpoint block (step 6). Do NOT continue.
+7. **On `type="tdd"`** → RED (failing test, `test(...)`) → GREEN (impl, `feat(...)`) → REFACTOR (`refactor(...)`). Tests MUST fail before impl, MUST pass after.
+
+**6. Checkpoint protocol** (when you hit `type="checkpoint:*"` or auth gate — see step 7):
+
+Can't talk to user directly. Stop, return structured block, parent relays.
+
+```
+## Checkpoint Reached — Phase <P>, Plan <N>
+**Type:** <human-verify|decision|human-action>
+**Task:** <n> — <name>  **Progress:** <x>/<y>
+
+### Completed so far
+- Task 1: <name> (commit <hash>)
+- ...
+
+### Checkpoint Content
+<type-specific body>
+
+### What I Need From You
+<"approved" | "select: <option-id>" | "done" | <question>>
+
+### State Preserved At
+`<phase_dir>/.execute-checkpoint.json`
+```
+
+| Type | Body | Resume signal |
+|---|---|---|
+| `human-verify` (90%) | What was built + verification steps (commands/URLs) + expected | "approved" or specific issues |
+| `decision` (9%) | Decision + context + 2–3 options with pros/cons | "select: <option-id>" |
+| `human-action` (1%) | What was automated + ONE manual step + verify plan | "done" |
+
+**State preservation:** write `${PHASE_DIR}/.execute-checkpoint.json` with `completed_tasks[]`, `commit_hashes{}`, `next_task_index` for deterministic resume. Delete on clean close-out.
+
+**7. Authentication gates** are NOT failures — expected interaction points. Indicators: "Not authenticated", 401/403, "Please run {tool} login", "Set {ENV_VAR}". Protocol: recognize → STOP → write `.execute-checkpoint.json` with `type: "human-action"` + exact auth steps → return Checkpoint block → wait. Document in SUMMARY.md under `## Authentication Gates`, not as a deviation.
+
+**8. Deviation rules:**
+
+| Rule | Trigger | Action |
+|---|---|---|
+| 1 | Bug found while implementing | Auto-fix, test, verify, track as deviation |
+| 2 | Missing critical implementation detail | Auto-fix, test, verify, track as deviation |
+| 3 | Blocker in adjacent code | Auto-fix only if scope strictly bounded; else Rule 4 |
+| 4 | Architectural change, new dep, scope expansion | **STOP** — write `.execute-checkpoint.json` `type: "decision"`, return to parent. NEVER silently decide. |
+
+- **Scope boundary:** do NOT auto-fix pre-existing issues unrelated to current task — note in SUMMARY "Out-of-Scope Issues".
+- **Fix attempt limit:** max 3 retries per deviation before Rule 4.
+- **Priority:** Rule 4 (STOP) > Rules 1–3 (auto) > unsure → Rule 4.
+
+**9. Pre-commit hook failure:**
+1. `git commit` fails with hook error. 2. Read error — names hook + what failed. 3. Fix (type/lint/secret). 4. `git add` fixed. 5. Retry. 6. Budget 1–2 cycles per commit. If still failing → `type: "human-action"` checkpoint with hook output.
+**Do NOT use `--no-verify`** unless project's `.soly/docs/` or ROADMAP.md explicitly opts out.
+
+**10. Verification failure gate:** 1st retry (hooks flake) → 2nd retry (fix obvious cause) → 3rd retry (apply deviation rules) → 3+ fails → `type: "decision"` checkpoint, STOP.
+
+**11. Generate USER-SETUP** (only if PLAN.md frontmatter has `user_setup:`):
+
+```bash
+grep -A 50 "^user_setup:" "$PLAN_PATH" | head -50
+```
+
+Write `${PHASE_DIR}/${PADDED_PHASE}-${PLAN_NUM}-USER-SETUP.md`:
+
+```markdown
+---
+phase: <P>  plan: <N>  status: Incomplete  generated: <ISO8601>
+---
+
+# User Setup — Phase <P> Plan <N>
+
+## <service-name>
+- **Env vars:** `<VAR>` — <description, where to get it>
+- **Account setup:** <link + checklist>
+- **Dashboard config:** <link + steps>
+- **Local dev notes:** <how to verify locally>
+- **Verification:** `<command>` should print <expected>
+
+## Verification
+Run all verification commands. When all pass, change `status:` to `Complete`.
+```
+
+**12. Create SUMMARY.md** (atomic — NO narrative between `write` and `git commit`):
+
+```markdown
+---
+phase: <P>  plan: <N>  title: "<from PLAN>"  status: complete
+duration: "<Xh Ym>"  started: <ISO>  completed: <ISO>
+tasks_completed: <N>  files_modified: <N>
+tags: [<from PLAN frontmatter>]
+key-files:    { created: [<paths>],  modified: [<paths>] }
+key-decisions: [<d1>, <d2>]
+requirements-completed: [<from PLAN frontmatter, verbatim>]
+---
+
+# Phase <P> Plan <N>: <Title> Summary
+
+<one-line substantive — e.g. "JWT auth with refresh rotation using jose", not "Authentication implemented">
+
+## Duration  <duration> (<start> → <end>)
+
+## Tasks
+- Task 1: <name> (commit <hash>)
+- ...
+
+## Deviations from Plan
+If none: `None — plan executed exactly as written.`
+Per deviation:
+```
+**[Rule N — <Cat>] <Title>**
+- Found during: Task <X>
+- Issue: <what>   Fix: <what you did>
+- Files: <paths>   Verification: <how>   Commit: <hash>
+```
+End with: `**Total deviations:** <N> auto-fixed (Rules 1–3). **Out-of-scope:** <N>. **Escalated:** <N>.`
+
+## Authentication Gates
+<none or per-gate entries>
+
+## Out-of-Scope Issues
+<issues not in this plan's scope — future phase>
+
+## Verification
+<output of <verification> block, or "all criteria passed; see commits">
+
+## Files Touched  - Created: <n>  - Modified: <n>
+
+## Next
+<if more plans: "Ready for plan <N+1> — re-invoke `soly execute-plan <P>`">
+<if last: "Phase <P> complete. Consider `soly plan <P+1>` or `soly pause`.">
+```
+
+```bash
+git add "$EXPECTED_SUMMARY"
+git commit -m "chore(${PADDED_PHASE}-${PLAN_NUM}): complete plan <N>"
+```
+
+**13. Update STATE.md** (read + edit, no CLI):
+- Bump `current_plan` in "Current Position".
+- Add `key-decisions` to "Decisions" table (skip if trivial).
+- Update `last_updated`.
+- Keep < 150 lines — archive long-form to `.soly/DECISIONS-INDEX.md` if it grows.
+
+**Update ROADMAP.md** — phase's progress row: increment completed plan count; status → `In Progress` (more plans) or `Complete` (last) with date.
+
+**14. Update requirements** (only if PLAN.md has `requirements:`):
+
+```bash
+REQUIREMENTS=$(grep -A1 "^requirements:" "$PLAN_PATH" | tail -1 | sed -E 's/.*\[([^]]+)\].*/\1/' | tr ',' ' ')
+```
+
+For each ID, find line in `.soly/REQUIREMENTS.md`, flip status to `Complete`.
+
+**15. Return:**
+
+```
+## Plan Complete — Phase <P> Plan <N>
+**Title:** <t>  **Duration:** <d>  **Tasks:** <n>  **Files:** <m>  **Deviations:** <n> auto / <m> escalated
+<if USER_SETUP>
+## ⚠ User Setup Required
+<path> generated with <n> service(s) — complete before next plan's external checks.
+</if>
+### Next
+<if more plans: "Re-invoke `soly execute-plan <P>` for plan <N+1>.">
+<if last: "Phase <P> complete. Try `soly plan <P+1>` or `soly pause`.">
+```
+
+</process>
+
+<hard_rules>
+- No `.soly/rules/` edits. No `.soly/docs/` edits without explicit user decision in conversation.
+- No subagents (you ARE one). `maxSubagentDepth: 1` is enforced.
+- **Never skip `<acceptance_criteria>` HARD GATE.** Not optional.
+- **Never emit narrative between SUMMARY `write` and `git commit`** (truncation is a known failure mode).
+- **Never silently make architectural decisions** — use Rule 4 + checkpoint.
+- Commit messages: Conventional Commits 1.0.0. Per-task: `<type>(<plan-id>): <summary>`.
+- Return: SUMMARY path, plan summary, deviation count, next step.
+</hard_rules>

package/workflows-data/execute-task.md

@@ -0,0 +1,116 @@
+# Execute Task
+
+<purpose>Execute ONE task (atomic unit — a feature slice, one endpoint, one page, one contract wire). Produce SUMMARY.md. Tasks live under `.soly/features/<feature>/tasks/<task-id>/` with PLAN.md as the contract.</purpose>
+
+<path_discipline>
+**All soly-managed files live under `.soly/`.** Never write PLAN.md, SUMMARY.md, iteration files, or handoffs to the project root. Task files go in `.soly/features/<feature>/tasks/<task-id>/`. Use absolute paths — 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, the feature README, prior task SUMMARYs, and the current task PLAN. Read it FIRST.
+</path_discipline>
+
+<read_first>`.soly/STATE.md` · `.soly/docs/` (INTENT, 0-point) · `.soly/features/<feature>/README.md` · `PLAN.md` (the contract) · `.soly/contracts/*` if PLAN.md references it. If `.soly/features/` or task dir missing → error + stop, do not invent paths.</read_first>
+
+<task_frontmatter>
+PLAN.md frontmatter (executor must respect all fields; **flag** incomplete ones in your report, don't silently fill):
+
+```yaml
+---
+id: auth-be-login-a3f9   # slug-4hex, must match the directory name
+kind: be                  # be | fe | infra | docs | integration
+feature: auth             # parent feature
+status: ready             # ready | in-progress | blocked | done
+priority: high            # high | medium | low
+parallelizable: true
+depends-on: []            # list of task ids; each must be status: done
+---
+```
+</task_frontmatter>
+
+<atomic_close_out>
+Only legal order: `production-code commit(s) → SUMMARY.md commit → PLAN.md frontmatter status: done → report`.
+Once production commits exist, returning without a committed SUMMARY is an illegal partial-task state.
+</atomic_close_out>
+
+<process>
+
+**1. Verify ready.** `TASK_DIR` from worker args. Parse `status` from frontmatter:
+
+```bash
+TASK_DIR="$1"
+[ -d "$TASK_DIR" ] && [ -f "$TASK_DIR/PLAN.md" ] || { echo "task dir or PLAN.md missing" >&2; exit 1; }
+STATUS=$(awk '/^---$/{c++; next} c==1{print}' "$TASK_DIR/PLAN.md" | grep -E '^status:' | awk '{print $2}' | tr -d '"')
+```
+
+- `status` is `ready` (or `in-progress` for resume).
+- Every task in `depends-on:` has `status: done` (its SUMMARY.md is committed).
+
+If not → return `## Blocker` to parent, stop. Do NOT start a blocked task.
+
+**2. Read intent + feature context.** **0-POINT CHECK** — the iteration context file (path given in the task prompt) already contains the intent docs as a summary, the feature README, prior task SUMMARYs, and the current task PLAN. Use that. If intent and PLAN.md conflict, flag it. Read `.soly/contracts/*` (if it exists) only if the task touches API surfaces.
+
+**3. Execute** with standard worker self-audit:
+
+1. Write code.
+2. Run build / typecheck / lint — **0 warnings**.
+3. Cross-check diff against `.soly/rules/coding/*` (or `.editorconfig`).
+4. **Rule gap?** Invoke the project's rule-authoring skill (`analyzer-coach` or equivalent) — it proposes an `.editorconfig` entry, a coding-rule doc addition, or a custom-analyzer rule. Loop until clean, max 3 iterations.
+5. Commit production-code changes (one or more commits).
+
+Do NOT skip the audit. "I think I'm fine" is not a check.
+
+**4. Write `SUMMARY.md`** at the absolute path `${TASK_DIR}/SUMMARY.md` (the task dir is the iteration context's `task` frontmatter field, plus the feature subdir). Never a bare relative name:
+
+```markdown
+---
+id: <task-id>  title: "<from PLAN>"  status: done
+started: <ISO>  completed: <ISO>  duration: "<Xm>"
+feature: <feature>
+---
+
+# <task-id> Summary
+
+<1–2 sentences: what was done>
+
+## Changed files
+- `<path>` — <what>
+
+## Validation
+- `<cmd>` → exit 0 (output: ...)
+- `<cmd>` → exit 0 (output: ...)
+
+## Rule gaps discovered
+<none, or per-gap: which skill proposed, which rule added>
+
+## Decisions needing approval
+<none, or per-decision: rationale + recommendation>
+```
+
+**5. Close out** — atomic, do NOT skip or reorder:
+
+```bash
+cd "$PROJECT_ROOT" && git add "$TASK_DIR/SUMMARY.md"
+git commit -m "chore(tasks): summary for <task-id>"
+cd "$PROJECT_ROOT" && git add "$TASK_DIR/PLAN.md"   # flip status → done
+git commit -m "chore(tasks): mark <task-id> done"
+```
+
+You may combine into one commit, but the SUMMARY must be on disk before the frontmatter flip. **Do not flip status without a committed SUMMARY.**
+
+**6. Report** to parent: task id, SUMMARY path, commits, validation results, decisions needing approval.
+
+</process>
+
+<hard_rules>
+- No `.soly/rules/` edits. No subagents (you ARE one).
+- No starting tasks with un-`done` `depends-on:`.
+- If rule gap → add via the rule-authoring skill. **No silent workarounds** (`#pragma`, `severity = none`).
+- Return: changed files, commands + exit codes, validation evidence, surprises, decisions needing parent approval.
+</hard_rules>
+
+<interactive_rules_out_of_scope>
+- `interactive: true` rules (describe the conversation, not execution). You're in execute mode, not discuss — surface genuine blockers in the report, don't ask the user.
+</interactive_rules_out_of_scope>
+
+<dual_mode_note>
+Project may also have `.soly/phases/` (phase-based layout, distinct from task-based). You are only responsible for this task. Don't touch phases. Don't modify ROADMAP.md or STATE.md beyond what your close-out requires (typically nothing for tasks — the parent updates those).
+</dual_mode_note>

package/workflows-data/pause-work.md

@@ -0,0 +1,142 @@
+# Pause Work
+
+<purpose>Create `.soly/HANDOFF.json` (machine-readable) and a `.continue-here.md` (human-readable) to preserve work state across sessions. `soly resume` consumes both.</purpose>
+
+<read_first>.soly/STATE.md (current position) · the most recent `.soly/phases/*/SUMMARY.md` if any</read_first>
+
+<process>
+
+**1. Detect context.** First match wins; nothing detectable → `.soly/.continue-here.md` (note ambiguity in `<current_state>`).
+
+```bash
+phase=$(ls -t .soly/phases/*/PLAN.md 2>/dev/null | head -1)
+phase_slug=$(echo "$phase" | grep -oP 'phases/\K[^/]+')
+spike=$(ls -td .soly/spikes/*/ 2>/dev/null | head -1)
+sketch=$(ls -td .soly/sketches/*/ 2>/dev/null | head -1)
+deliberation=$(ls .soly/deliberations/*.md 2>/dev/null | head -1)
+```
+
+| detected | handoff path |
+|---|---|
+| phase_slug | `.soly/phases/<phase_slug>/.continue-here.md` |
+| spike | `.soly/spikes/<spike_slug>/.continue-here.md` |
+| sketch | `.soly/sketches/<sketch_slug>/.continue-here.md` |
+| deliberation | `.soly/deliberations/.continue-here.md` |
+| (notes only) | `.soly/.continue-here.md` |
+
+**2. Gather state.** Walk the conversation + recent diffs. Collect: current position (phase/plan/task + paths), work done this session (artifacts, not aspirations), work remaining, decisions (only those future-you must not re-litigate), blockers, human actions pending (API keys, approvals, manual tests), background processes, uncommitted files (`git status --porcelain`), and blocking constraints (anti-patterns discovered through actual failure — each tagged `blocking` or `advisory`).
+
+If anything is ambiguous, return a `## Clarifications Needed` block — do not invent.
+
+**3. Check for false completions.** `grep -l "To be filled\|placeholder\|TBD" .soly/phases/*/*.md 2>/dev/null` — report matches as incomplete.
+
+**4. Write `.soly/HANDOFF.json`.** Timestamp via `date -u +"%Y-%m-%dT%H:%M:%SZ"` (no SDK).
+
+```json
+{
+  "version": "1.0",
+  "timestamp": "<ts>",
+  "phase": <n|null>, "phase_name": "<str|null>", "phase_dir": "<path|null>",
+  "plan": <n|null>, "task": <n|null>, "total_tasks": <n|null>,
+  "status": "paused",
+  "completed_tasks":   [{"id": 1, "name": "<n>", "status": "done", "commit": "<hash>"},
+                        {"id": 2, "name": "<n>", "status": "in_progress", "progress": "<what>"}],
+  "remaining_tasks":   [{"id": 3, "name": "<n>", "status": "not_started"}],
+  "blockers":          [{"description": "<x>", "type": "technical|human_action|external", "workaround": "<if any>"}],
+  "human_actions_pending": [{"action": "<x>", "context": "<why>", "blocking": true}],
+  "decisions":         [{"decision": "<x>", "rationale": "<why>", "phase": <n|null>}],
+  "uncommitted_files": [],
+  "next_action": "<specific first action when resuming>",
+  "context_notes": "<mental state, approach>"
+}
+```
+
+Use JSON `null`, never the string `"null"`.
+
+**5. Write `<handoff-path>/.continue-here.md`:**
+
+```markdown
+---
+context: <phase|spike|sketch|deliberation|research|default>
+phase: <slug-or-empty>  task: <n>  total_tasks: <m>
+status: in_progress  last_updated: <ts>
+---
+
+# BLOCKING CONSTRAINTS — read first
+> Each was discovered through actual failure. Acknowledge before proceeding.
+- [ ] CONSTRAINT: <name> — <what> — <structural mitigation>
+
+_If none, remove this section._
+
+## Critical Anti-Patterns
+| Pattern | What + how it manifested | Severity | Structural prevention |
+|---|---|---|---|
+| <name> | <desc> | blocking | <mechanism — not just acknowledgment> |
+| <name> | <desc> | advisory | <guidance> |
+
+`blocking` rows are enforced by discuss-phase / execute-phase as a mandatory understanding check.
+
+<current_state><immediate context, paths, last commits></current_state>
+
+<completed_work>
+- Task 1: <name> - done (commit <h>)
+- Task 2: <name> - in_progress, <what's done>
+</completed_work>
+
+<remaining_work>
+- Task 3: <what's left>
+- Task 4: not started
+</remaining_work>
+
+<decisions_made>
+- <decision>: <rationale>
+</decisions_made>
+
+<blockers>
+- <blocker>: <status/workaround>
+</blockers>
+
+## Required Reading (in order)
+1. <doc> — <why>
+2. `.soly/METHODOLOGY.md` if it exists — project lenses
+
+## Infrastructure State
+- <service/env>: <state>
+
+## Pre-Execution Critique Required
+<!-- only if pausing between design and execution -->
+- Design artifact: <path>
+- Critique focus: <questions>
+- Gate: do NOT execute until critique complete + design revised
+
+<context><mental state, plan, what you were thinking></context>
+<next_action>Start with: <specific first action></next_action>
+```
+
+Specific enough that a fresh worker can resume without re-deriving from git history.
+
+**6. Commit:**
+```bash
+git add .soly/HANDOFF.json <handoff-md-path>
+git commit -m "chore(soly): pause work — create handoff"
+```
+
+**7. Return:**
+```
+Handoff created:
+  - .soly/HANDOFF.json
+  - <handoff-md-path>
+State: <context>, <location>, task <x>/<m>, in_progress, <n> blockers (<m> human)
+Resume: `soly resume`
+```
+
+</process>
+
+<hard_rules>
+- No production code. Handoff only.
+- A summary with `TBD`/`placeholder`/`To be filled` is incomplete — report it.
+- `null` is JSON `null`, not the string `"null"`.
+- Do not modify `.soly/rules/`. Do not run subagents (you ARE one).
+- Commit message: `chore(soly): pause work — create handoff`.
+- Return: paths, state summary, blocker count, `soly resume` command.
+</hard_rules>