Merge pull request #7 from gmickel/chore/port-upstream-0.17.1

Port upstream flow-next 0.17.1

Author: gmickel

.opencode/bin/flowctl.py

@@ -140,7 +140,9 @@ $FLOWCTL opencode plan-review "$EPIC_ID" --receipt "$RECEIPT_PATH"
 # Output includes VERDICT=SHIP|NEEDS_WORK|MAJOR_RETHINK
 ```
 
-On NEEDS_WORK: fix plan via `$FLOWCTL epic set-plan`, then re-run (receipt enables session continuity).
+On NEEDS_WORK: fix plan via `$FLOWCTL epic set-plan` AND sync affected task specs via `$FLOWCTL task set-spec`, then re-run (receipt enables session continuity).
+
+**Note**: `opencode plan-review` automatically includes task specs in the review prompt.
 
 ### RepoPrompt Backend
 
@@ -153,8 +155,12 @@ $FLOWCTL cat <id>
 eval "$($FLOWCTL rp setup-review --repo-root "$REPO_ROOT" --summary "Review plan for <EPIC_ID>: <summary>")"
 # Outputs W=<window> T=<tab>. If fails → <promise>RETRY</promise>
 
-# Step 3: Augment selection
+# Step 3: Augment selection - add epic AND task specs
 $FLOWCTL rp select-add --window "$W" --tab "$T" .flow/specs/<epic-id>.md
+# Add all task specs for this epic
+for task_spec in .flow/tasks/${EPIC_ID}.*.md; do
+  [[ -f "$task_spec" ]] && $FLOWCTL rp select-add --window "$W" --tab "$T" "$task_spec"
+done
 
 # Step 4: Build and send review prompt (see workflow.md)
 $FLOWCTL rp chat-send --window "$W" --tab "$T" --message-file /tmp/review-prompt.md --new-chat --chat-name "Plan Review: <EPIC_ID>"
@@ -169,10 +175,22 @@ $FLOWCTL epic set-plan-review-status <EPIC_ID> --status ship --json
 If verdict is NEEDS_WORK, loop internally until SHIP:
 
 1. **Parse issues** from reviewer feedback
-2. **Fix plan** via `$FLOWCTL epic set-plan <EPIC_ID> --file /tmp/updated-plan.md`
-3. **Re-review**:
+2. **Fix epic spec** via `$FLOWCTL epic set-plan <EPIC_ID> --file /tmp/updated-plan.md`
+3. **Sync affected task specs** - If epic changes affect task specs, update them:
+   ```bash
+   $FLOWCTL task set-spec <TASK_ID> --file - --json <<'EOF'
+   <updated task spec content>
+   EOF
+   ```
+   Task specs need updating when epic changes affect:
+   - State/enum values referenced in tasks
+   - Acceptance criteria that tasks implement
+   - Approach/design decisions tasks depend on
+   - Lock/retry/error handling semantics
+   - API signatures or type definitions
+4. **Re-review**:
    - **OpenCode**: re-run reviewer subagent with updated plan
    - **RP**: `$FLOWCTL rp chat-send --window "$W" --tab "$T" --message-file /tmp/re-review.md` (NO `--new-chat`)
-4. **Repeat** until `<verdict>SHIP</verdict>`
+5. **Repeat** until `<verdict>SHIP</verdict>`
 
 **CRITICAL**: For RP, re-reviews must stay in the SAME chat so reviewer has context. Only use `--new-chat` on the FIRST review.

.opencode/skill/flow-next-opencode-plan-review/SKILL.md

@@ -158,14 +158,19 @@ Builder selects context automatically. Review and add must-haves:
 # See what builder selected
 $FLOWCTL rp select-get --window "$W" --tab "$T"
 
-# Always add the plan spec
+# Always add the epic spec
 $FLOWCTL rp select-add --window "$W" --tab "$T" .flow/specs/<epic-id>.md
 
+# Always add ALL task specs for this epic
+for task_spec in .flow/tasks/${EPIC_ID}.*.md; do
+  [[ -f "$task_spec" ]] && $FLOWCTL rp select-add --window "$W" --tab "$T" "$task_spec"
+done
+
 # Add PRD/architecture docs if found
 $FLOWCTL rp select-add --window "$W" --tab "$T" docs/prd.md
 ```
 
-**Why this matters:** Chat only sees selected files.
+**Why this matters:** Chat only sees selected files. Reviewer needs both epic spec AND task specs to check for consistency.
 
 ---
 
@@ -199,6 +204,18 @@ If you cannot find `<file_contents>`, ask for the files to be re-attached before
 ## Review Focus
 [USER'S FOCUS AREAS]
 
+## Review Scope
+
+You are reviewing:
+1. **Epic spec** - The high-level plan
+2. **Task specs** - Individual task breakdowns
+
+**CRITICAL**: Check for consistency between epic and tasks. Flag if:
+- Task specs contradict or miss epic requirements
+- Task acceptance criteria don't align with epic acceptance criteria
+- Task approaches would need to change based on epic design decisions
+- Epic mentions states/enums/types that tasks don't account for
+
 ## Review Criteria
 
 Conduct a John Carmack-level review:
@@ -210,6 +227,7 @@ Conduct a John Carmack-level review:
 5. **Risks** - Blockers identified? Security gaps? Mitigation?
 6. **Scope** - Right-sized? Over/under-engineering?
 7. **Testability** - How will we verify this works?
+8. **Consistency** - Do task specs align with epic spec?
 
 ## Output Format
 
@@ -291,7 +309,20 @@ If verdict is NEEDS_WORK:
    $FLOWCTL checkpoint restore --epic <EPIC_ID> --json
    ```
 
-4. **Re-review with fix summary** (only AFTER step 3):
+4. **Sync affected task specs** - If epic changes affect task specs, update them:
+   ```bash
+   $FLOWCTL task set-spec <TASK_ID> --file - --json <<'EOF'
+   <updated task spec content>
+   EOF
+   ```
+   Task specs need updating when epic changes affect:
+   - State/enum values referenced in tasks
+   - Acceptance criteria that tasks implement
+   - Approach/design decisions tasks depend on
+   - Lock/retry/error handling semantics
+   - API signatures or type definitions
+
+5. **Re-review with fix summary** (only AFTER steps 3-4):
 
    **IMPORTANT**: Do NOT re-add files already in the selection. RepoPrompt auto-refreshes
    file contents on every message. Only use `select-add` for NEW files created during fixes:
@@ -315,12 +346,14 @@ If verdict is NEEDS_WORK:
 
    $FLOWCTL rp chat-send --window "$W" --tab "$T" --message-file /tmp/re-review.md
    ```
-5. **Repeat** until Ship
+6. **Repeat** until Ship
 
 **Anti-pattern**: Re-adding already-selected files before re-review. RP auto-refreshes; re-adding can cause issues.
 
 **Anti-pattern**: Re-reviewing without calling `epic set-plan` first. This wastes reviewer time and loops forever.
 
+**Anti-pattern**: Updating epic spec without syncing affected task specs. Causes reviewer to flag consistency issues again.
+
 ---
 
 ## Failure Recovery

.opencode/skill/flow-next-opencode-plan-review/workflow.md

@@ -22,6 +22,8 @@ Task tracking for AI agents. All state lives in `.flow/`.
 └── meta.json           # Project metadata
 ```
 
+Runtime state (status, assignee, evidence) is stored in `.git/flow-state/` (not tracked).
+
 ## IDs
 
 - Epics: `fn-N` (e.g., fn-1, fn-2)
@@ -46,6 +48,8 @@ Task tracking for AI agents. All state lives in `.flow/`.
 # Status
 .flow/bin/flowctl ready --epic fn-1  # What's ready to work on
 .flow/bin/flowctl validate --all     # Check structure
+.flow/bin/flowctl state-path         # Show runtime state directory
+.flow/bin/flowctl migrate-state --clean  # Optional migration + cleanup
 
 # Create
 .flow/bin/flowctl epic create --title "..."

.opencode/skill/flow-next-opencode-setup/templates/usage.md

@@ -1 +1 @@
-0.2.4
+0.2.5

.opencode/version

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+**Restores parity with upstream Claude Code plugin (flow-next 0.17.0 + 0.17.1).**
+
+### Ported from upstream 0.17.0 → 0.17.1
+
+- **Runtime state store** — Task runtime fields move to `.git/flow-state/` (worktree-safe)
+- **StateStore with locking** — fcntl-based per-task locks for race-safe updates
+- **New commands** — `flowctl state-path` + `flowctl migrate-state [--clean]`
+- **Checkpoint schema v2** — Includes runtime state in save/restore
+- **Plan review includes task specs** — Both RP and OpenCode review epic + task specs for consistency
+- **Plan review consistency checks** — New criteria + anti-pattern: update epic without syncing tasks
+- **Task spec full replacement** — `flowctl task set-spec --file` (supports stdin)
+
 **Restores parity with upstream Claude Code plugin (flow-next 0.12.10 + 0.13.0).**
 
 ### Planning Workflow Changes (ported from upstream 0.13.0)

CHANGELOG.md

@@ -288,6 +288,39 @@ Teams can work in parallel branches without coordination servers:
 * **Actor resolution**: Auto-detects from git email,  `FLOW_ACTOR` env, or `$USER`
 * **Local validation**: `flowctl validate --all` catches issues before commit
 
+### Parallel Worktrees
+
+Multiple agents can work simultaneously in different git worktrees, sharing task state:
+
+```bash
+# Main repo
+git worktree add ../feature-a fn-1-branch
+git worktree add ../feature-b fn-2-branch
+
+# Both worktrees share task state via .git/flow-state/
+cd ../feature-a && flowctl start fn-1.1   # Agent A claims task
+cd ../feature-b && flowctl start fn-2.1   # Agent B claims different task
+```
+
+**How it works:**
+- Runtime state (status, assignee, evidence) lives in `.git/flow-state/` — shared across worktrees
+- Definition files (title, description, deps) stay in `.flow/` — tracked in git
+- Per-task `fcntl` locking prevents race conditions
+
+**State directory resolution:**
+1. `FLOW_STATE_DIR` env (explicit override)
+2. `git --git-common-dir` + `/flow-state` (worktree-aware)
+3. `.flow/state` fallback (non-git or old git)
+
+**Commands:**
+```bash
+flowctl state-path                # Show resolved state directory
+flowctl migrate-state             # Migrate existing repo (optional)
+flowctl migrate-state --clean     # Migrate + remove runtime from tracked files
+```
+
+**Backward compatible** — existing repos work without migration. The merged read path automatically falls back to definition files when no state file exists.
+
 ### Zero Dependencies
 
 Everything is bundled:
@@ -515,6 +548,8 @@ This creates a complete audit trail: what was planned, what was done, how it was
     └── decisions.md
 ```
 
+Runtime state (status, assignee, evidence) is stored in `.git/flow-state/` (not tracked).
+
 ### ID Format
 
 * **Epic**: `fn-N-xxx` where `xxx` is a 3-character alphanumeric suffix
@@ -540,6 +575,7 @@ flowctl epic close fn-1
 flowctl task create --epic fn-1 --title "..." --deps fn-1.2,fn-1.3 --priority 10
 flowctl task set-description fn-1.1 --file desc.md
 flowctl task set-acceptance fn-1.1 --file accept.md
+flowctl task set-spec fn-1.1 --file spec.md
 
 flowctl dep add fn-1.3 fn-1.2
 
@@ -555,6 +591,9 @@ flowctl cat fn-1
 flowctl validate --epic fn-1
 flowctl validate --all
 
+flowctl state-path
+flowctl migrate-state --clean
+
 flowctl review-backend            # Get configured review backend (ASK if not set)
 flowctl config set review.backend opencode  # Set default backend
 ```

README.md

@@ -7,7 +7,7 @@ CLI for `.flow/` task tracking. Agents must use flowctl for all writes.
 ## Available Commands
 
 ```
-init, detect, epic, task, dep, show, epics, tasks, list, cat, ready, next, start, done, block, validate, config, memory, prep-chat, rp, opencode, codex, checkpoint, status
+init, detect, epic, task, dep, show, epics, tasks, list, cat, ready, next, start, done, block, validate, config, memory, prep-chat, rp, opencode, codex, checkpoint, status, state-path, migrate-state
 ```
 
 ## Multi-User Safety
@@ -21,6 +21,23 @@ Works out of the box for parallel branches. No setup required.
 
 **Optional**: Add CI gate with `docs/ci-workflow-example.yml` to block bad PRs.
 
+## Runtime State (Worktrees)
+
+Runtime task state (status, assignee, evidence) lives in `.git/flow-state/` and is shared across worktrees.
+Definition files (title, deps, specs) remain in `.flow/` and are tracked in git.
+
+State directory resolution:
+1. `FLOW_STATE_DIR` env (override)
+2. `git --git-common-dir` + `/flow-state` (worktree-aware)
+3. `.flow/state` fallback (non-git)
+
+Useful commands:
+```bash
+flowctl state-path            # Show resolved state directory
+flowctl migrate-state         # Migrate existing repo (optional)
+flowctl migrate-state --clean # Migrate + remove runtime from tracked files
+```
+
 ## File Structure
 
 ```
@@ -37,6 +54,8 @@ Works out of the box for parallel branches. No setup required.
 └── usage.md           # (optional) CLI reference via /flow-next:setup
 ```
 
+Runtime state (status, assignee, evidence) is stored in `.git/flow-state/` (not tracked).
+
 Flowctl accepts schema v1 and v2; new fields are optional and defaulted.
 
 New fields:
@@ -147,13 +166,19 @@ flowctl task set-acceptance fn-1.2 --file accept.md [--json]
 
 ### task set-spec
 
-Set description and acceptance in one call (fewer writes).
+Set task spec (full replacement or section patches).
 
+Full replacement:
+```bash
+flowctl task set-spec fn-1.2 --file spec.md [--json]
+```
+
+Section patches:
 ```bash
 flowctl task set-spec fn-1.2 --description desc.md --acceptance accept.md [--json]
 ```
 
-Both `--description` and `--acceptance` are optional; supply one or both.
+`--description` and `--acceptance` are optional; supply one or both. Use `--file -` for stdin.
 
 ### task reset
 
@@ -554,7 +579,7 @@ References: src/middleware.py:45 (calls authenticate), tests/test_auth.py:12
 
 | Review | Criteria |
 |--------|----------|
-| Plan | Completeness, Feasibility, Clarity, Architecture, Risks, Scope, Testability |
+| Plan | Completeness, Feasibility, Clarity, Architecture, Risks, Scope, Testability, Consistency |
 | Impl | Correctness, Simplicity, DRY, Architecture, Edge Cases, Tests, Security |
 
 **Receipt schema (Ralph-compatible):**
@@ -586,7 +611,7 @@ flowctl checkpoint restore --epic fn-1 [--json]
 flowctl checkpoint delete --epic fn-1 [--json]
 ```
 
-Checkpoints preserve full epic + task state. Useful when compaction occurs during plan-review cycles.
+Checkpoints preserve full epic + task state (including runtime state). Useful when compaction occurs during plan-review cycles.
 
 ### status
 
@@ -603,6 +628,35 @@ Output:
 
 Human-readable output shows epic/task counts and any active Ralph runs.
 
+### state-path
+
+Show resolved runtime state directory (worktree-aware).
+
+```bash
+flowctl state-path [--json]
+flowctl state-path --task fn-1.2 [--json]
+```
+
+Example output:
+```json
+{"success": true, "state_dir": "/repo/.git/flow-state", "task_state_path": "/repo/.git/flow-state/tasks/fn-1.2.state.json"}
+```
+
+### migrate-state
+
+Migrate runtime state from tracked task definitions into the shared state directory.
+
+```bash
+flowctl migrate-state [--clean] [--json]
+```
+
+What it does:
+1. Scans `.flow/tasks/*.json` for runtime fields
+2. Writes runtime state to `.git/flow-state/tasks/*.state.json`
+3. Optional `--clean` removes runtime fields from tracked task JSONs
+
+Backward compatible: repos work without migration. Use `--clean` only if you want a clean diff.
+
 ## Ralph Receipts
 
 Review receipts are **not** managed by flowctl. They are written by the review skills when `REVIEW_RECEIPT_PATH` is set (Ralph sets this env var).