pi-soly 0.2.1

package/workflows-data/plan-phase.md

@@ -0,0 +1,199 @@
+# Plan Phase
+
+<purpose>Produce one or more PLAN.md files for a phase — each a self-contained contract (requirements, must_haves, tasks with runnable acceptance criteria) the executor can run standalone. Pre-compute wave numbers encoding the dependency graph. Update STATE.md.</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/docs/` (INTENT, 0-point) · `.soly/STATE.md` (current position) · `.soly/ROADMAP.md` (this phase's row) · `.soly/REQUIREMENTS.md` if exists · `<phase>-CONTEXT.md` if exists (user decisions from `soly discuss`) · `<phase>-RESEARCH.md` if exists (chosen libs/patterns) · up to 3 most recent prior `*-SUMMARY.md` (avoid re-implementing). If `.soly/` missing → stop + error.</read_first>
+
+<git_branch_invariant>
+**Do not create, rename, or switch git branches.** The branch was established at `soly discuss` and is owned by the user's git workflow. Verify the current branch matches expectations, but do NOT change it.
+</git_branch_invariant>
+
+<plan_frontmatter_spec>
+Every PLAN.md frontmatter (executor depends on it):
+
+```yaml
+---
+id: <NN>-<M>-<slug>     # padded-phase, plan-number, slug (matches filename)
+phase: <N>  plan: <M>
+title: "<short title>"
+wave: <W>                # 1 = first to run; 2 = depends on wave 1; etc.
+depends-on: [<id-1>, <id-2>, ...]
+requirements: [<REQ-ID-1>, <REQ-ID-2>, ...]
+tags: [be, api, auth]
+---
+```
+
+Body MUST include `## Must Haves`:
+
+```markdown
+## Must Haves
+### truths      — user-observable behaviors (incl. error paths)
+- [ ] <observable behavior>
+### artifacts   — files created/modified
+- `<path>` — <what>
+### key_links   — concrete file→file wirings the executor preserves
+- <src>:<symbol> → <consumer>:<symbol> — <wired>
+```
+
+Per-task structure (after Must Haves):
+
+```markdown
+### Task 1: <name>
+<task type="auto" tdd="false">
+
+**Read first:** `<path>` — <why> · `<path>` — <why>
+**Implementation:** <1–2 paragraphs>
+**Acceptance criteria:** (every one RUNNABLE — grep/file-check/test/HTTP-probe, NOT "works correctly")
+- [ ] <criterion>
+**Verification:** `<command>` → <expected>
+**Files to touch:** `<path>` — <change>
+**Commit:** `<type>(<plan-id>): <imperative>`
+</task>
+```
+
+Checkpoint task template (when user input is required mid-plan):
+
+```markdown
+### Task 3: <name> — checkpoint:human-verify
+<task type="checkpoint:human-verify">
+**Builds on Task 1+2.**
+**Verification steps for user:** 1. `<cmd>` should print `<expected>` · 2. Open `<URL>` and confirm `<behavior>`
+**What I need:** "approved" or specific issues to fix.
+</task>
+```
+</plan_frontmatter_spec>
+
+<process>
+
+**1. Initialize.** `bash` only (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
+# 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 EXISTING_PLANS < <(ls "$PHASE_DIR"/${PADDED_PHASE}-*-PLAN.md 2>/dev/null | sort)
+NEXT_PLAN_NUM=$((${#EXISTING_PLANS[@]} + 1))
+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)
+HAS_SUMMARIES=$(ls "$PHASE_DIR"/${PADDED_PHASE}-*-SUMMARY.md 2>/dev/null | wc -l | tr -d ' ')
+```
+
+| state | action |
+|---|---|
+| plans > 0 AND summaries > 0 | **Re-plan** — return `## Re-Plan Detected` to parent, ask user to confirm before overwriting |
+| plans > 0 AND summaries = 0 | draft plans exist; you may ADD plans using existing files as context. **Do NOT overwrite** existing PLAN.md unless user asks |
+| plans = 0 | fresh planning |
+
+**2. Read intent (0-POINT).** The iteration context file (path given in the task prompt) already contains the intent docs as a summary. Use that. If you need a specific doc in full, read it directly from its path (listed in section 0 of the bundle). Capture 3–5 intent bullets that bear on this phase. If intent and ROADMAP conflict, surface before writing plans.
+
+**3. Read phase context** (also in the iteration file) in priority order:
+1. `<phase>-CONTEXT.md` if exists — user decisions, honor them. Missing decision in an area you need to plan → surface in report.
+2. `<phase>-RESEARCH.md` if exists — chosen libs/patterns. Pitfalls → Must Haves or task body.
+3. `.soly/ROADMAP.md` — this phase's row: goal, requirements, deps on other phases.
+4. `.soly/REQUIREMENTS.md` if exists — full text + acceptance criteria for each `phase_req_ids`. Every requirement → some plan's `requirements:` array.
+5. Up to 3 most recent prior `*-SUMMARY.md` — what was already built.
+
+**4. Decompose into plans.**
+
+**Heuristic:** 1 plan ≈ 2–8 tasks, fits in one executor session without context overflow. > 8 tasks → split at natural seams (foundational → feature → polish; or BE → FE → integration).
+
+**Wave rules:**
+- Wave 1: no deps (or only on prior-phase plans already Complete).
+- Wave N: deps only on plans in waves 1..N-1 of this phase.
+- Graph MUST be acyclic.
+- Default split: wave 1 ≈ half the work; subsequent waves in dependency order.
+
+Internal accumulator:
+
+```
+PLAN STRUCTURE:
+- Plan 1: <title> (wave 1) — covers REQ-01, REQ-02
+- Plan 2: <title> (wave 1) — covers REQ-03
+- Plan 3: <title> (wave 2, deps: 1, 2) — covers REQ-04, REQ-05
+```
+
+**Coverage:** every requirement → exactly one plan. Uncoverable → `## Uncovered Requirements` in report.
+
+**5. Write plans.** Naming: `${PADDED_PHASE}-${M}-<slug>-PLAN.md` (slug = 3–5 kebab-case words). **Write the file at `${PHASE_DIR}/${PADDED_PHASE}-${M}-<slug>-PLAN.md`** — absolute path. Use the frontmatter spec above.
+
+**Content rules:**
+- Body must have `## Must Haves` (truths / artifacts / key_links).
+- Acceptance criteria must be RUNNABLE (grep, file-check, test, HTTP probe) — not "works correctly".
+- `must_haves.truths` = user-observable, not implementation details.
+- `must_haves.key_links` = concrete file→file wirings the executor preserves.
+- ≤ 8 tasks per plan (more → split).
+
+**6. Validate plan graph.**
+
+1. **Acyclic** — walk `depends-on:`. No plan depends on itself, transitively or directly. Cycle → restructure.
+2. **Waves consistent** — `plan.wave > max(wave of its deps)`. If not, fix.
+3. **Requirements covered** — every phase requirement → some plan's `requirements:`. If not, add a task or surface as `## Uncovered Requirements`.
+4. **Files plausible** — each `key_links` source exists OR is created in an earlier plan. Note if unsure, don't fail.
+
+**7. Commit plans:**
+
+```bash
+# Use absolute paths in the add — `git add` interprets them relative to cwd otherwise.
+cd "$PROJECT_ROOT" && git add "$PHASE_DIR"/${PADDED_PHASE}-*-PLAN.md
+git commit -m "chore(${PADDED_PHASE}): plan phase <N> — <M> plan(s)"
+```
+
+**8. Update STATE.md** (read + edit, no CLI):
+- Phase status → `Planned`, `current_plan` → 1.
+- `last_updated` → `date -u +"%Y-%m-%dT%H:%M:%SZ"`.
+- If STATE.md has `progress:`, increment `total_plans` by new plan count.
+- Keep < 150 lines — archive to `.soly/DECISIONS-INDEX.md` if it grows.
+
+**9. Report:**
+
+```
+## Plan Complete — Phase <N> (<slug>)
+### Plans Created
+- Plan 1: <title> (wave 1) — <N> reqs, <M> tasks
+- Plan 2: <title> (wave 1) — ...
+- Plan 3: <title> (wave 2, deps: 1, 2) — ...
+
+### Wave Breakdown
+- Wave 1: <count> plan(s) — <one-line summary>
+- Wave 2: <count> plan(s) — <one-line summary>
+
+### Coverage
+- Requirements: <N>/<M> covered<if uncovered: list>
+
+### Files
+- Plans: <paths> · STATE.md updated
+
+### Open Questions
+<none, or per-question needing user decision>
+
+### Next Step
+Parent summarizes + asks confirmation. On confirm: `soly execute-plan <N>` (or `soly execute <N>` for full phase).
+```
+
+</process>
+
+<hard_rules>
+- No production code. Planning only.
+- No subagents (you ARE one). No `.soly/rules/` edits. No `.soly/docs/` edits without surfacing to parent.
+- No git branch create/rename/switch.
+- `must_haves` (truths/artifacts/key_links) is NOT optional — executor relies on it for self-verification.
+- Every acceptance criterion is RUNNABLE — command/check/test, not "works correctly" or "feels right".
+- Wave numbers pre-computed; dependency graph acyclic.
+- Every phase requirement → some plan (coverage = 100% or surface).
+- Conventional Commits 1.0.0.
+- Return: created files, plan count, wave breakdown, open questions.
+</hard_rules>

package/workflows-data/plan-task.md

@@ -0,0 +1,185 @@
+# Plan Task Workflow
+
+# Всегда соблюдай правила проекта из .soly/rules/
+# Не используй shortcuts ради скорости
+
+<path_discipline>
+**All soly-managed files live under `.soly/`.** PLAN.md lives at `.soly/features/<feature>/tasks/<task-id>/PLAN.md`. Never write plan files 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, the feature README, prior task SUMMARYs, and the current task PLAN (for refinement). Read it FIRST.
+</path_discipline>
+
+<purpose>
+Create or refine PLAN.md for a single task. A task is a small atomic unit
+of work — a feature slice, a contract change, a single endpoint, a single
+UI page. Smaller than a phase plan; carries its own frontmatter so the
+executor can pick it up standalone.
+</purpose>
+
+<required_reading>
+Before any planning, read:
+1. .soly/docs/ — INTENT (0-point)
+2. .soly/STATE.md — current state
+3. .soly/ROADMAP.md — high-level requirements
+4. .soly/features/<feature>/README.md — feature context
+5. .soly/contracts/* — shared API schemas (if any)
+6. The task's existing PLAN.md (if refining) or relevant sibling tasks (if creating)
+
+If `.soly/features/` is empty for the target feature, error and stop.
+Do not invent feature paths.
+</required_reading>
+
+<task_frontmatter_spec>
+PLAN.md starts with a YAML frontmatter block. The executor depends on it.
+
+```yaml
+---
+id: auth-be-login-a3f9   # slug-4hex, must match the directory name
+kind: be                  # be | fe | infra | docs | integration
+feature: auth             # parent feature name (must match .soly/features/<feature>/)
+status: ready             # ready | in-progress | blocked | done
+priority: high            # high | medium | low
+parallelizable: true      # whether this task can run alongside other parallel tasks
+depends-on: []            # list of task ids; each must be status: done before this runs
+---
+
+# Task: <title>
+
+[body]
+```
+
+Defaults if unsure:
+- kind: pick from the values above based on the work being planned
+- priority: medium
+- parallelizable: false
+- depends-on: []  (only fill if you have a clear dep on an existing task)
+</task_frontmatter_spec>
+
+<process>
+
+<step name="verify_target" priority="first">
+Confirm what kind of planning this is:
+
+- **new-task** — create the dir + write PLAN.md from scratch
+- **existing-task** — refine an existing PLAN.md (do NOT rewrite from scratch;
+  preserve frontmatter, improve body)
+
+If unclear, error and ask the parent.
+</step>
+
+<step name="read_intent" priority="first">
+**0-POINT CHECK.** Re-read `.soly/docs/` (intent docs) before any planning.
+The task PLAN.md is the contract; intent docs are the WHY. If you find
+a conflict, flag it instead of silently choosing.
+
+The iteration context file (path given in the task prompt) bundles the
+intent docs as a summary, the feature README, and prior task SUMMARYs.
+Use that as your starting point. If you need a specific doc in full,
+read it directly from its path.
+</step>
+
+<step name="read_feature">
+Read `.soly/features/<feature>/README.md` for feature-level context.
+If missing, note it but proceed (the parent may not have written one yet).
+</step>
+
+<step name="check_contracts">
+If the task touches API surfaces (BE endpoints, FE request shapes, shared
+types), read `.soly/contracts/<feature>.openapi.yaml` or similar. Contracts
+are the synchronizing artifact between parallel BE and FE tasks.
+</step>
+
+<step name="check_siblings">
+For new-task: look at existing tasks in the same feature (if any) to
+match style and identify natural dependencies. If a sibling task already
+implements something this task depends on, add to `depends-on:`.
+
+For existing-task: read sibling tasks only if the plan needs to be aware
+of them (e.g., shared types, sequential ordering).
+</step>
+
+<step name="write_plan">
+For new-task, structure the PLAN.md body like:
+
+```
+# Task: <title>
+
+## What
+<1-2 paragraphs: what this task does, in plain language>
+
+## Why
+<1-2 sentences: what user-visible outcome / contract this enables>
+
+## Acceptance criteria
+- [ ] <criterion 1>
+- [ ] <criterion 2>
+- [ ] ...
+
+## Files to touch
+- <path> — <what changes>
+- ...
+
+## Edge cases
+- <edge case 1>
+- <edge case 2>
+
+## Out of scope
+- <explicitly NOT doing X>
+```
+
+For existing-task, preserve the frontmatter. Refine the body to make
+acceptance criteria testable, edge cases concrete, and "out of scope"
+explicit. Do NOT bloat — a tight plan is better than an exhaustive one.
+</step>
+
+<step name="commit">
+For new-task, commit the new PLAN.md:
+```
+# Use absolute path with `cd "$PROJECT_ROOT"` so git doesn't interpret
+# a bare relative path as cwd-relative.
+cd "$PROJECT_ROOT" && git add .soly/features/<feature>/tasks/<id>/PLAN.md
+git commit -m "chore(tasks): plan <id>"
+```
+
+For existing-task refinement, commit only if material change:
+```
+cd "$PROJECT_ROOT" && git add .soly/features/<feature>/tasks/<id>/PLAN.md
+git commit -m "chore(tasks): refine plan <id>"
+```
+
+If nothing material changed, do not commit.
+
+**Worker bash setup (when you do need it):**
+```bash
+PROJECT_ROOT="$(pwd)"  # worker inherits parent cwd = project root
+SOLY_DIR="$PROJECT_ROOT/.soly"
+```
+</step>
+
+<step name="report">
+Return to parent:
+- Created or refined path
+- Task id (for new-task)
+- Plan summary (1-3 bullets)
+- Any open questions / decisions needing parent approval
+- Any deps discovered (sibling tasks that should also be planned)
+</step>
+
+</process>
+
+<hard_rules>
+- Do not write production code. Planning only.
+- Preserve existing frontmatter on refinement. Only update if you find a bug.
+- For new-task, generate the id as `<slug>-<4hex>` (lowercase).
+- Commit messages follow Conventional Commits 1.0.0 — `chore(tasks): ...`.
+- Do not modify `.soly/rules/`.
+- Do not run subagents yourself.
+- **PATH DISCIPLINE:** PLAN.md goes to `.soly/features/<feature>/tasks/<id>/PLAN.md`. Never to the project root.
+- Return: created/refined path, task id, plan summary, open questions.
+</hard_rules>
+
+<dual_mode_note>
+Tasks are part of soly's dual-mode system. The project may also have
+`.soly/phases/` (phase-based layout, distinct from task-based). You are only planning a specific task.
+Do not touch phases. Do not modify ROADMAP.md or STATE.md.
+</dual_mode_note>