planflow-ai 1.3.4 → 1.4.1

package/.claude/resources/core/_index.md

@@ -5,8 +5,8 @@
 
 Core rules define the foundational coding standards that apply across the entire project. These include best practices to follow (allowed patterns), anti-patterns to avoid (forbidden patterns), and complexity scoring for implementation planning.
 
-**Total Files**: 22 files, ~3580 lines
-**Reference Codes**: COR-AP-1 through COR-DSA-3
+**Total Files**: 25 files, ~5550 lines
+**Reference Codes**: COR-AP-1 through COR-AC-3
 
 ---
 
@@ -177,6 +177,16 @@ Core rules define the foundational coding standards that apply across the entire
 | COR-DSA-2 | Return format schema and Codebase Analysis section template | discovery-sub-agents.md | 132-190 |
 | COR-DSA-3 | Coordinator behavior (spawn, collect, merge, error handling) | discovery-sub-agents.md | 192-240 |
 
+### Wave Execution (`wave-execution.md`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|---------|
+| COR-WAVE-1 | Architecture, dependency analysis rules, and declaration syntax | wave-execution.md | 14-80 |
+| COR-WAVE-2 | Wave grouping algorithm (topological sort, backward compatibility, example) | wave-execution.md | 82-140 |
+| COR-WAVE-3 | Parallel spawning rules and wave execution summary format | wave-execution.md | 142-195 |
+| COR-WAVE-4 | Wave coordinator behavior (per-wave processing, file conflict detection, failure handling, git commit ordering) | wave-execution.md | 197-270 |
+| COR-WAVE-5 | Configuration (flowconfig, interaction matrix, aggregation, rules) | wave-execution.md | 272-340 |
+
 ### Review Adaptive Depth (`review-adaptive-depth.md`)
 
 | Code | Description | Source | Lines |
@@ -186,6 +196,24 @@ Core rules define the foundational coding standards that apply across the entire
 | COR-AD-3 | Deep review mode (500+ lines) — categorization, passes, executive summary | review-adaptive-depth.md | 103-187 |
 | COR-AD-4 | Insertion points for review-code and review-pr skills | review-adaptive-depth.md | 189-205 |
 
+### Per-Task Verification (`per-task-verification.md`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| COR-PTV-1 | Purpose, architecture, and verify-diagnose-repair loop flow | per-task-verification.md | 3-40 |
+| COR-PTV-2 | Verify tag syntax, parsing rules, and debug sub-agent prompt/schema | per-task-verification.md | 42-130 |
+| COR-PTV-3 | Verification loop, retry behavior, and task_verifications return field | per-task-verification.md | 132-200 |
+| COR-PTV-4 | Configuration, error handling, wave mode interaction, and rules | per-task-verification.md | 202-260 |
+
+### Atomic Commits (`atomic-commits.md`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| COR-AC-1 | Purpose, commit format, and sequential mode behavior | atomic-commits.md | 3-80 |
+| COR-AC-2 | Wave mode behavior, JSON schema extension, and coordinator processing | atomic-commits.md | 82-210 |
+| COR-AC-3 | Interaction with phase isolation, wave execution, verification, and configuration | atomic-commits.md | 212-300 |
+
+---
 ---
 
 ## When to Expand
@@ -256,6 +284,18 @@ Core rules define the foundational coding standards that apply across the entire
 | COR-DSA-1 | Need discovery sub-agent definitions or prompt templates |
 | COR-DSA-2 | Need return format schema or Codebase Analysis section template |
 | COR-DSA-3 | Need coordinator spawn/collect/merge behavior or error handling |
+| COR-WAVE-1 | Need wave execution architecture or dependency declaration syntax |
+| COR-WAVE-2 | Need wave grouping algorithm or backward compatibility rules |
+| COR-WAVE-3 | Need parallel spawning rules or wave execution summary format |
+| COR-WAVE-4 | Need wave coordinator behavior, file conflict detection, or failure handling |
+| COR-WAVE-5 | Need wave execution configuration, interaction matrix, or aggregation rules |
+| COR-PTV-1 | Need per-task verification architecture or verify-diagnose-repair loop |
+| COR-PTV-2 | Need verify tag syntax, parsing rules, or debug sub-agent schema |
+| COR-PTV-3 | Need verification loop behavior, retry rules, or task_verifications return field |
+| COR-PTV-4 | Need per-task verification configuration, error handling, or wave mode interaction |
+| COR-AC-1 | Need atomic commits architecture, commit format, or sequential mode behavior |
+| COR-AC-2 | Need wave mode commit behavior, JSON schema extension, or coordinator processing |
+| COR-AC-3 | Need atomic commits interaction with phase isolation, wave execution, or config |
 
 ---
 
@@ -302,3 +342,6 @@ Core rules define the foundational coding standards that apply across the entire
 - `project-memory.md` is loaded on-demand - artifact tracking and 7-day session loading
 - `heartbeat.md` is loaded on-demand - scheduled task daemon configuration
 - `discovery-sub-agents.md` is loaded on-demand - parallel codebase exploration sub-agents during `/discovery-plan`
+- `wave-execution.md` is loaded on-demand - wave-based parallel phase execution during `/execute-plan`
+- `per-task-verification.md` is loaded on-demand - per-task verification with debug sub-agents during `/execute-plan`
+- `atomic-commits.md` is loaded on-demand - per-task commit format and coordinator behavior during `/execute-plan`

package/.claude/resources/core/atomic-commits.md

@@ -0,0 +1,380 @@
+
+# Atomic Commits Per Task
+
+## Purpose
+
+When `commit: true` in `flow/.flowconfig`, `/execute-plan` creates a **git commit after each individual task** completes (and passes verification, if applicable), rather than one commit per phase. This enables `git bisect` to pinpoint task-level regressions, independent reverts of specific task changes, and clearer git history.
+
+**Core principle**: Fine-grained commit history, tied to task completion.
+
+---
+
+## Commit Format
+
+All per-task commits follow a consistent format:
+
+```
+feat(phase-N.task-M): <description truncated to 50 chars> — <feature>
+```
+
+### Format Breakdown
+
+| Part | Example | Description |
+|------|---------|-------------|
+| **Type** | `feat` | Always `feat` for feature implementation (per plan-flow convention) |
+| **Scope** | `phase-1.task-2` | Phase number (N) and task number (M, 1-indexed within phase) |
+| **Description** | `Create user auth middleware` | Short description of what the task did, truncated to 50 characters |
+| **Feature** | `— user-auth-system` | Feature name from the plan, separated by ` — ` |
+
+### Example Commits
+
+```
+feat(phase-1.task-1): Define user and session types — user-auth-system
+feat(phase-1.task-2): Create user schema with Prisma — user-auth-system
+feat(phase-2.task-1): Implement authentication middleware — user-auth-system
+feat(phase-2.task-2): Add rate limiting to API routes — user-auth-system
+feat(phase-3.task-1): Update API documentation — user-auth-system
+```
+
+### Description Truncation
+
+- Truncate task descriptions to **50 characters maximum**
+- Preserve the most meaningful part of the task name
+- Use ellipsis (`...`) if truncation occurs: `Create user authentication middle...`
+- This keeps commit messages concise and readable in `git log`
+
+---
+
+## Sequential Mode Behavior
+
+In **sequential mode** (default, `wave_execution: false`), each phase runs in an **isolated Agent sub-agent**:
+
+```
+Coordinator (main session)
+    │
+    ├─ Spawn Phase sub-agent
+    │   │
+    │   ├─ Task 1: Implement → ✅ Pass verification → Commit immediately
+    │   ├─ Task 2: Implement → ✅ Pass verification → Commit immediately
+    │   └─ Task 3: Implement → ✅ Pass verification → Commit immediately
+    │
+    ├─ Receive JSON return with tasks_completed array
+    │
+    ├─ Process summary:
+    │   └─ Sub-agent commits are already in git
+    │       (files are in working dir from sub-agent context)
+    │
+    └─ Next phase...
+```
+
+### Sub-Agent Commit Behavior
+
+In sequential mode, the **phase sub-agent commits directly** after each task:
+
+1. Complete task implementation in isolation
+2. Run verification (if `<verify>` tag present)
+3. If verification passes: run `git add -A && git commit -m "feat(phase-N.task-M): ..."`
+4. Proceed to next task
+5. Return JSON summary with `tasks_completed` array
+
+The coordinator receives the JSON return and knows which tasks were completed by checking `tasks_completed`. File conflicts do not occur in sequential mode because only one sub-agent runs at a time.
+
+**Context template extension**: Add to phase sub-agent context:
+
+```markdown
+## Commit Instructions
+- After each task completes and verification passes (if applicable):
+  1. Stage changed files: `git add -A`
+  2. Create atomic commit: `git commit -m "feat(phase-N.task-M): <truncated description> — <feature>"`
+     - Use format: feat(phase-{phase_number}.task-{task_number_in_phase}): <description> — <feature>
+     - Truncate description to 50 chars
+     - Task numbers are 1-indexed within each phase
+  3. Continue to next task
+- Return `tasks_completed` array in JSON with files_created/files_modified per task
+- Do NOT create a final phase commit (coordinator will not create one either)
+```
+
+---
+
+## Wave Mode Behavior
+
+In **wave mode** (`wave_execution: true`), multiple sub-agents run in **parallel per wave**, and the **coordinator commits after the wave completes**:
+
+```
+Coordinator (main session)
+    │
+    ├─ For each Wave:
+    │   │
+    │   ├─ Spawn MULTIPLE Phase sub-agents IN PARALLEL:
+    │   │   ├─► Phase A sub-agent (runs tasks, NO commits)
+    │   │   └─► Phase B sub-agent (runs tasks, NO commits)
+    │   │
+    │   ├─ Wait for all to complete
+    │   │
+    │   ├─ Collect JSON returns with tasks_completed arrays
+    │   │
+    │   ├─ Post-wave processing (sequential, in phase order):
+    │   │   │
+    │   │   ├─ Detect file conflicts
+    │   │   │
+    │   │   ├─ For each phase (A, then B):
+    │   │   │   └─ For each task in phase (1, 2, 3, ...):
+    │   │   │       └─ Commit: git add -A && git commit -m "feat(phase-N.task-M): ..."
+    │   │   │
+    │   │   └─ Commit all tasks from Phase A, then all from Phase B
+    │   │
+    │   └─ Next Wave...
+    │
+    └─ Completion summary
+```
+
+### Sub-Agent Behavior in Wave Mode
+
+In wave mode, **sub-agents do NOT commit**. They implement all tasks and return a JSON summary:
+
+1. Implement all phase tasks
+2. Run per-task verification (if applicable)
+3. **Do NOT commit** — parallel git conflicts would occur
+4. Return JSON with `tasks_completed` array containing per-task metadata
+5. Exit
+
+The coordinator collects all JSON returns, detects file conflicts, then commits sequentially.
+
+**Context template extension**: Add to phase sub-agent context in wave mode:
+
+```markdown
+## Commit Instructions (Wave Mode)
+- Do NOT create any commits during task implementation
+- The coordinator will commit your changes after this wave completes
+- Return `tasks_completed` array with per-task file lists (see Return Format below)
+- Coordinator will iterate tasks and commit: feat(phase-N.task-M): ... per task
+```
+
+---
+
+## JSON Return Schema Extension
+
+The phase isolation return format is extended with a **`tasks_completed` array** for per-task file tracking:
+
+```json
+{
+  "status": "success",
+  "phase": "Phase 1: Create Core Resource",
+  "summary": "Implemented three core resource files...",
+  "files_created": [
+    ".claude/resources/core/atomic-commits.md",
+    ".claude/resources/core/_index.md"
+  ],
+  "files_modified": [],
+  "decisions": [],
+  "deviations": [],
+  "errors": [],
+  "patterns_captured": [],
+  "tasks_completed": [
+    {
+      "task_number": 1,
+      "task_name": "Create atomic-commits.md resource file",
+      "files_created": [".claude/resources/core/atomic-commits.md"],
+      "files_modified": []
+    },
+    {
+      "task_number": 2,
+      "task_name": "Update _index.md with reference entry",
+      "files_created": [],
+      "files_modified": [".claude/resources/core/_index.md"]
+    }
+  ]
+}
+```
+
+### tasks_completed Field
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `task_number` | number | 1-indexed task number within the phase |
+| `task_name` | string | Short task description from the plan |
+| `files_created` | string[] | Files created by this task (empty array if none) |
+| `files_modified` | string[] | Files modified by this task (empty array if none) |
+
+### When to Include
+
+- Always include `tasks_completed` if any tasks ran in the phase
+- Omit `tasks_completed` only if the phase has no tasks (edge case)
+- Include all tasks, even those without `<verify>` tags
+- Order entries by task_number (1, 2, 3, ...)
+
+---
+
+## Coordinator Processing: Sequential Mode
+
+After receiving the sub-agent JSON return in sequential mode:
+
+1. **Validate return**: Check `status` field
+2. **Verify commits exist**: The sub-agent has already created per-task commits
+3. **Update plan file**: Mark phase tasks as `[x]`
+4. **Accumulate file list**: Merge `files_created` and `files_modified` into running list
+5. **Buffer patterns**: Append `patterns_captured` entries
+6. **Display summary**: Show tasks completed with verification results
+7. **Do NOT create phase commit**: Sub-agent already created per-task commits
+8. **Proceed**: Move to next phase
+
+---
+
+## Coordinator Processing: Wave Mode
+
+After collecting all sub-agent JSON returns from a wave:
+
+1. **Validate all returns**: Check `status` field for each
+2. **Detect file conflicts**: Check `files_modified` overlap between phases (same as existing wave behavior)
+3. **For each phase** (in phase number order):
+   - **For each task** (in task_number order):
+     - Extract `task_name`, `files_created`, `files_modified` from `tasks_completed[i]`
+     - **Stage files**: `git add -A` (stages all task changes in working directory)
+     - **Create commit**: `git commit -m "feat(phase-N.task-M): <truncated task_name> — <feature>"`
+       - Truncate `task_name` to 50 chars if needed
+       - Use task_number from JSON (not computed)
+       - Use feature name from plan
+   - **Update plan file**: Mark phase tasks as `[x]` (after all phase tasks are committed)
+   - **Accumulate file list**: Merge task file lists into running list
+4. **Buffer patterns**: Collect `patterns_captured` from all phases
+5. **Display summary**: Show all phases and tasks completed, including verification results
+6. **Do NOT create wave commit**: Per-task commits already created
+7. **Proceed**: Next wave
+
+### Deterministic Commit Ordering
+
+Commits are created in **strict phase order, then task order**:
+
+```
+Wave 1 complete:
+  Phase A, Task 1 → commit
+  Phase A, Task 2 → commit
+  Phase A, Task 3 → commit
+  Phase B, Task 1 → commit
+  Phase B, Task 2 → commit
+```
+
+This ensures **deterministic git history** regardless of which sub-agent finished first.
+
+---
+
+## Interaction with Per-Task Verification
+
+Verification runs **before** the task's commit:
+
+```
+Phase sub-agent:
+  Task 1: Implement
+    ├─ Implementation complete
+    ├─ Run verification (if <verify> tag present)
+    ├─ If fail: debug sub-agent → repair loop → re-verify
+    ├─ If pass or fail (max retries): commit this task
+    └─ Continue to Task 2
+```
+
+**Rule**: A task commits even if verification failed (after max retries). The coordinator and user see the failure in `task_verifications[i].status == "fail"`.
+
+---
+
+## Interaction with Phase Isolation
+
+Atomic commits per task is **independent of phase isolation**:
+
+| phase_isolation | Behavior |
+|---|---|
+| `true` (default) | Sub-agent isolated with clean context; per-task commits work normally |
+| `false` (legacy) | Phases execute inline in main session; per-task commits still work but less clean context isolation |
+
+Per-task commits work the same way in both modes — the difference is context isolation, not commit behavior.
+
+---
+
+## Interaction with Wave Execution
+
+Atomic commits per task **requires wave execution to work correctly**:
+
+| wave_execution | Behavior |
+|---|---|
+| `true` (default) | Coordinator commits per-task after wave completes (no parallel git conflicts) |
+| `false` (sequential) | Sub-agent commits per-task directly (no coordinator involvement) |
+
+Per-task commits are the **only reason wave mode does NOT commit** in the sub-agent. Without per-task commits, we might revert to per-phase commits from the coordinator.
+
+---
+
+## Aggregated Phases
+
+When phases are aggregated (combined complexity ≤ 6), they run as **one sub-agent call** with all tasks from all aggregated phases. Commit format still uses **relative phase numbering**:
+
+```
+Phase 1 (aggregated with Phase 2):
+  Aggregated Phase tasks:
+    feat(phase-1.task-1): ...
+    feat(phase-1.task-2): ...
+    feat(phase-2.task-1): ...
+    feat(phase-2.task-2): ...
+```
+
+**Rule**: Use the **actual phase number** from the plan, not a computed aggregate phase number.
+
+---
+
+## Configuration
+
+### `.flowconfig` Setting
+
+Per-task commits are **not a separate feature flag**. They are **controlled by the existing `commit` setting**:
+
+```yaml
+commit: true    # Enable per-task commits (default: true)
+```
+
+- `true`: Create atomic per-task commits (this feature)
+- `false`: No commits during execution (existing behavior)
+
+No new `.flowconfig` setting is needed — `commit: true` automatically upgrades from per-phase to per-task commits.
+
+### Toggle via `/flow`
+
+```
+/flow commit=true
+/flow commit=false
+```
+
+---
+
+## Error Handling
+
+| Scenario | Behavior |
+|---|---|
+| Task implementation fails | Task does NOT commit; coordinator reports failure in `errors` array |
+| Verification fails (max retries) | Task commits anyway; coordinator shows failure in `task_verifications[i].status == "fail"` |
+| Git commit command fails | Coordinator reports error and asks user whether to retry, skip, or stop |
+| File conflict in wave mode | Same as existing wave conflict handling — present to user with options |
+
+---
+
+## Rules
+
+1. **Format is strict**: `feat(phase-N.task-M): <50 chars max> — <feature>`
+2. **Sequential mode**: Sub-agents commit; coordinator validates
+3. **Wave mode**: Sub-agents do NOT commit; coordinator commits in phase/task order
+4. **No final phase commit**: Replaced by per-task commits
+5. **Backward compatible**: When `commit: false`, no commits (existing behavior)
+6. **Verification before commit**: Tasks commit after passing verification
+7. **Failure still commits**: Failed verification after max retries still commits the task
+8. **Deterministic order**: Wave mode commits always in phase order, task order
+9. **Truncate descriptions**: 50 character max for readability
+10. **Task numbers reset per phase**: Phase 1 Task 1, Phase 2 Task 1 (not global numbering)
+
+---
+
+## Related Files
+
+| File | Purpose |
+|---|---|
+| `.claude/resources/core/phase-isolation.md` | Sub-agent context template, JSON return format (extended by this feature) |
+| `.claude/resources/core/wave-execution.md` | Wave coordinator behavior (changed to commit per-task after waves) |
+| `.claude/resources/core/per-task-verification.md` | Per-task verification (runs before task's commit) |
+| `.claude/resources/skills/execute-plan-skill.md` | Execute-plan skill (updated for per-task commit format) |
+| `.claude/commands/execute-plan.md` | Execute-plan command docs (updated for per-task format) |

package/.claude/resources/core/autopilot-mode.md

@@ -97,8 +97,9 @@ Check `flow/contracts/` for any relevant integration contracts. If found, note t
 5. If `commit: true`: auto-commit after each completed phase
 6. Run build + test verification at the end
 7. If `push: true` and build+test pass: auto-push
-8. Write transition summary
-9. **Auto-proceed** to Step 5
+8. If `pr: true` and push succeeds: create feature branch `feat/<feature>`, open PR via `gh pr create`, capture PR URL
+9. Write transition summary
+10. **Auto-proceed** to Step 5
 
 ### Step 5: Review Code
 

package/.claude/resources/core/compaction-guide.md

@@ -103,9 +103,23 @@ Open questions: retry policy, refund flow. Resume with remaining questions.
 
 ---
 
+## STATE.md Integration
+
+Before compaction, write current execution state to `flow/STATE.md` using the standard state format (skill, phase, status, decisions, errors). This ensures that even if the compaction summary loses detail, the full execution position is recoverable from the file.
+
+After compaction, re-read `flow/STATE.md` to restore execution context. This supplements the compaction summary with structured state that the summary format may not fully capture (phase numbers, file lists, decision references).
+
+**Workflow**:
+1. Before `/compact`: Update `flow/STATE.md` with current state (or create it if it doesn't exist)
+2. Run `/compact` with the summary
+3. After compaction: Re-read `flow/STATE.md` and the active plan file to restore full context
+
+---
+
 ## Rules
 
 1. **Never compact mid-phase** — only at phase boundaries
 2. **Always include enough context to resume** — the model after compaction should know exactly what to do next
 3. **After compaction, re-read the plan file** — don't rely on memory of plan contents
-4. **Default to preserving** — when in doubt, keep it. It's better to preserve something unnecessary than lose something critical.
+4. **After compaction, re-read STATE.md** — restore structured execution state that the summary may not fully capture
+5. **Default to preserving** — when in doubt, keep it. It's better to preserve something unnecessary than lose something critical.

package/.claude/resources/core/heartbeat.md

@@ -205,9 +205,77 @@ The project log (`flow/log.md`) is also linked into the vault at `~/plan-flow/br
 
 ---
 
+## Notification System
+
+The heartbeat daemon includes a notification system that provides visibility into background task execution.
+
+### Notification Channels
+
+| Channel | What Gets Written | When |
+|---------|------------------|------|
+| `flow/log.md` | Timestamped one-liners | All events (start, complete, fail, blocked) |
+| `flow/.heartbeat-events.jsonl` | Machine-readable JSON events | All events |
+| Desktop notification (node-notifier) | Pop-up alert | Failures and blocked tasks only |
+
+### Log Format (flow/log.md)
+
+```
+[2026-03-17 14:00] ✅ task-name: Started — description
+[2026-03-17 14:12] ✅ task-name: Phase 1/5 complete — description
+[2026-03-17 14:35] ❌ task-name: FAILED at Phase 3 — build error
+[2026-03-17 14:35] ⏸️ task-name: Paused — see .heartbeat-prompt.md
+```
+
+### Event Types
+
+| Type | Level | Desktop Notify |
+|------|-------|---------------|
+| `task_started` | info | No |
+| `phase_complete` | info | No |
+| `task_complete` | info | No |
+| `task_failed` | error | Yes |
+| `task_blocked` | error | Yes |
+
+### Exit Code Convention
+
+| Exit Code | Meaning | Daemon Action |
+|-----------|---------|---------------|
+| 0 | Success | Log ✅, continue |
+| 1 | Failure | Log ❌, desktop notify |
+| 2 | Needs input | Log ⏸️, write prompt file (if autopilot OFF), desktop notify |
+
+### Prompt File System
+
+When a task exits with code 2 and autopilot is OFF:
+1. Daemon writes `flow/.heartbeat-prompt.md` with task context
+2. Desktop notification alerts the user
+3. Task pauses until user responds
+4. On next session start, the prompt is auto-detected and presented
+5. After resolution, prompt is archived to `flow/archive/heartbeat-prompts/`
+
+When autopilot is ON: exit code 2 is logged as a warning but execution continues.
+
+### Session Start Integration
+
+Two behaviors activate on session start:
+1. **Heartbeat Log**: Reads `.heartbeat-events.jsonl`, compares against `.heartbeat-state.json` timestamp, summarizes unread events
+2. **Heartbeat Prompt**: Detects `.heartbeat-prompt.md` and presents pending questions immediately
+
+### Runtime Files
+
+| File | Purpose |
+|------|---------|
+| `flow/.heartbeat-events.jsonl` | Append-only event stream (one JSON per line) |
+| `flow/.heartbeat-state.json` | Tracks last-read timestamp for session start summaries |
+| `flow/.heartbeat-prompt.md` | Pending user input from blocked task (temporary) |
+| `flow/archive/heartbeat-prompts/` | Archived resolved prompt files |
+| `flow/.telegram-poll-state.json` | Telegram polling state (update offset, mode) |
+
+---
+
 ## Rules
 
-1. **No external dependencies**: Daemon uses only Node.js built-in modules
+1. **Minimal dependencies**: Daemon uses Node.js built-in modules plus `node-notifier` for desktop notifications
 2. **Graceful shutdown**: Always clean up timers and PID file on exit
 3. **Stale PID detection**: Verify PID is actually running before assuming daemon is alive
 4. **File-based config**: All configuration lives in `flow/heartbeat.md` — no CLI flags for task config
@@ -215,3 +283,63 @@ The project log (`flow/log.md`) is also linked into the vault at `~/plan-flow/br
 6. **Log rotation**: Keep `flow/.heartbeat.log` under 1000 lines by truncating oldest entries
 7. **One-shot cleanup**: After a one-shot task executes, auto-disable it and update the linked tasklist item
 8. **Vault sync**: Every heartbeat update MUST also update `~/plan-flow/brain/heartbeat.md` — see Vault Sync section
+
+---
+
+## Telegram Two-Way Polling
+
+When `telegram_bot_token` and `telegram_chat_id` are set in `flow/.flowconfig`, the heartbeat daemon enables two-way messaging with Telegram using the Bot API's `getUpdates` long-polling endpoint.
+
+### Adaptive Polling Modes
+
+| Mode | Interval | Trigger |
+|------|----------|---------|
+| Idle | 60 seconds | No pending prompts — lightweight keep-alive |
+| Conversation | 3 seconds | A task is blocked and waiting for user input |
+
+The daemon switches to **conversation mode** when it writes a prompt to Telegram (e.g., a task blocked with exit code 2). Once the user replies and the prompt is resolved, it drops back to **idle mode**.
+
+### State File
+
+Polling state is persisted in `flow/.telegram-poll-state.json`:
+
+```json
+{
+  "lastUpdateId": 123456789,
+  "mode": "idle",
+  "pendingPromptMessageId": null
+}
+```
+
+- `lastUpdateId`: Tracks the Telegram update offset to avoid processing duplicate messages
+- `mode`: Current polling mode (`idle` or `conversation`)
+- `pendingPromptMessageId`: The Telegram message ID of the last prompt sent, used to match replies
+
+### Two-Way Conversation Flow
+
+1. A heartbeat task blocks (exit code 2) and writes `flow/.heartbeat-prompt.md`
+2. The daemon detects the prompt file and sends it to Telegram via `sendMessage`
+3. Polling switches to **conversation mode** (3s interval)
+4. The user replies in Telegram
+5. The daemon detects the reply via `getUpdates`, writes the response to `flow/.heartbeat-prompt.md`
+6. The blocked task resumes with the user's input
+7. Polling switches back to **idle mode** (60s interval)
+
+### Configuration
+
+Set both values in `flow/.flowconfig`:
+
+```yaml
+telegram_bot_token: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
+telegram_chat_id: "5635356808"
+```
+
+Configure via `/flow`:
+
+```
+/flow telegram_bot_token=123456:ABC-DEF telegram_chat_id=5635356808
+```
+
+### Auto-Migration from webhook_url
+
+If `webhook_url` contains a Telegram `api.telegram.org` URL with a bot token and chat_id in the query string, the flowconfig parser automatically extracts and populates `telegram_bot_token` and `telegram_chat_id`. The original `webhook_url` is preserved for one-way notification compatibility.

package/.claude/resources/core/model-routing.md

@@ -7,7 +7,7 @@ Automatic model selection at phase boundaries during `/execute-plan`. Each phase
 
 **Scope**: `/execute-plan` only. Other skills (discovery, review, brainstorm) do not have pre-defined complexity scores and are not routed.
 
-**Config**: Controlled by `model_routing` key in `flow/.flowconfig` (default: `true`). Set `model_routing: false` to disable.
+**Config**: Controlled by `model_routing` key in `flow/.flowconfig` (default: `false`). Set `model_routing: true` to enable.
 
 ---
 
@@ -23,12 +23,16 @@ Automatic model selection at phase boundaries during `/execute-plan`. Each phase
 
 ## Platform Mappings
 
+Always use the **latest and most capable model** from each provider. Model names below are examples — always prefer the most recent version available at runtime.
+
 | Tier | Claude Code | Codex (OpenAI) | Cursor |
 |------|------------|----------------|--------|
 | Fast | `haiku` | `gpt-4.1-mini` | auto (fast) |
 | Standard | `sonnet` | `gpt-4.1` | auto (normal) |
 | Powerful | `opus` | `o3` | auto (max) |
 
+**Default model (when routing is OFF)**: Always use the most capable/recent model from the active provider — e.g., `opus` for Anthropic, `o3` for OpenAI. This is the default behavior.
+
 **Fallback rule**: If a platform doesn't support a tier, fall back to the next tier up (e.g., if no haiku equivalent, use Standard).
 
 ---
@@ -37,7 +41,7 @@ Automatic model selection at phase boundaries during `/execute-plan`. Each phase
 
 ### At Each Phase Boundary
 
-1. **Check config**: Read `model_routing` from `flow/.flowconfig`. If `false` or missing key, skip routing (use session default).
+1. **Check config**: Read `model_routing` from `flow/.flowconfig`. If `false`, missing key, or not set, skip routing (use the most capable session model — this is the default).
 2. **Read complexity**: Get the phase's complexity score from the plan file.
 3. **Look up tier**: Map score to tier using the table above.
 4. **Spawn subagent**: Use the Agent tool with `model={tier_model}` to implement the phase.