@curdx/flow 2.3.10 → 3.0.0

package/settings.json

@@ -2,6 +2,7 @@
   "agent": "flow-orchestrator",
   "subagentStatusLine": {
     "type": "command",
-    "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/subagent-statusline.sh"
+    "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/subagent-statusline.sh",
+    "refreshInterval": 5
   }
 }

package/skills/implement/SKILL.md

@@ -19,6 +19,7 @@ for strategy-specific protocols:
 - `references/preflight.md`
 - `references/strategy-router.md`
 - `references/state-init.md`
+- `references/native-task-sync.md`
 - `references/linear-execution.md`
 - `references/subagent-execution.md`
 - `references/wave-execution.md`
@@ -53,6 +54,13 @@ signals. The runtime selector is:
 
 Use `references/state-init.md` before dispatching any execution protocol.
 
+## Native Task Sync
+
+Use `references/native-task-sync.md` to mirror CurDX execution into Claude's
+interactive task list when `TaskCreate` / `TaskUpdate` / `TaskList` are
+available. This is best-effort UX only; never let native task sync override the
+real `.flow` ledger.
+
 ## Run the Selected Execution Protocol
 
 - `linear`: stay inline in the main agent and execute the first unchecked task

package/skills/implement/references/linear-execution.md

@@ -7,11 +7,16 @@ needs maximum visibility in the main session.
 
 ```text
 for task in remaining tasks:
+    if native task sync is active:
+        reconcile obvious tasks.md/native drift
+        mark the current Claude task in_progress
     read task fields (Do / Files / Done when / Verify / Commit)
     execute the task inline in the current session
     run the task's Verify command
     make the atomic commit declared by the task
     mark the task [x] in tasks.md
+    if native task sync is active:
+        mark the current Claude task completed
     append the outcome to .progress.md
     print "✓ Task X.Y complete"
 ```
@@ -19,14 +24,20 @@ for task in remaining tasks:
 ## Execution Rules
 
 - Follow the `flow-executor` contract even though you stay inline
+- Treat `references/native-task-sync.md` as a mirror contract layered around
+  the inline loop, not a separate phase
 - Respect the declared `Files` scope; do not quietly expand task boundaries
 - Verification must pass before the task can be marked complete
 - One task, one atomic commit
 - If the task is too broad or unsafe, stop and surface `TASK_FAILED` semantics
   instead of improvising extra subtasks
+- If `TaskUpdate` fails for the current task, increment
+  `native_sync_failure_count`, keep `.flow` state authoritative, and continue
+  the inline run unless the real task itself failed
 
 ## Stop Conditions
 
 - Any git operation failure: stop immediately
 - Missing or invalid Verify command: stop and ask for a task regeneration
 - 3 consecutive `TASK_FAILED`: stop and require intervention
+- Native task sync failure alone is never a stop condition

package/skills/implement/references/native-task-sync.md

@@ -0,0 +1,107 @@
+# Native Task Sync — Mirror `.flow` Execution Into Claude's Task List
+
+Use this layer only as an interactive UX mirror. `.flow/specs/<name>/tasks.md`
+and `.state.json` remain the source of truth.
+
+## Availability Rule
+
+If the current session exposes `TaskCreate`, `TaskList`, and `TaskUpdate`, keep
+Claude's native task list aligned with the active spec. If those tools are not
+available (for example in headless or bare flows), skip all native sync work
+silently and continue with the disk-backed protocol.
+
+## State Fields
+
+Track best-effort sync state under `.state.json` `execute_state`:
+
+- `native_task_map`: `{ "<task-id>": "<claude-task-id>" }`
+- `native_sync_enabled`: `true | false`
+- `native_sync_failure_count`: integer
+
+Default behavior:
+
+- missing fields -> treat as first-run and initialize them
+- `native_sync_enabled = false` -> never attempt native task sync again in this
+  execution run unless the user explicitly resets state
+
+## First Sync
+
+After preflight and execute-state initialization:
+
+1. If native sync is available and `native_task_map` is empty, parse every task
+   row from `tasks.md`.
+2. Create one Claude native task per CurDX task.
+3. Use the CurDX task id in the subject:
+   - regular: `1.2 Add retry guard`
+   - parallel: `[P] 2.1 Build auth DTOs`
+   - verification: `[VERIFY] 3.VF Re-run original repro`
+4. Use a compact description built from:
+   - `Done when`
+   - `Verify`
+5. Immediately mark already-checked `[x]` tasks as `completed`.
+6. Persist the returned Claude task ids in `native_task_map`.
+
+When interactive hook support is available, CurDX also uses `TaskCreated` as a
+guardrail:
+
+- reject CurDX-shaped native tasks whose subject does not map to a real
+  `tasks.md` id
+- reject CurDX-shaped native tasks that omit the compact description derived
+  from `Done when` + `Verify`
+
+Do not block execution if task creation fails. Increment
+`native_sync_failure_count`, log one short note in `.progress.md`, and continue.
+
+## Rebuild Rule
+
+If a stored Claude task id no longer updates cleanly, assume the current
+session is attached to a different native task list:
+
+1. clear `native_task_map`
+2. recreate the native tasks from the current `tasks.md`
+3. keep `.flow` execution state unchanged
+
+This recovers from session changes without corrupting the real spec ledger.
+
+## Per-Task Sync
+
+Before dispatching the current task:
+
+1. reconcile `tasks.md` `[x]` rows against native task state when obvious drift
+   exists
+2. mark the current native task `in_progress`
+3. set `activeForm` to `Executing <task-id>`
+
+After `TASK_COMPLETE` and after disk-backed verification/state updates pass:
+
+1. mark that native task `completed`
+2. reset `native_sync_failure_count` toward zero on success
+
+When interactive hook support is available, `TaskCompleted` should also reject
+any CurDX-shaped native task completion that happens before `tasks.md` marks the
+same task id as checked.
+
+After `TASK_FAILED`:
+
+1. leave the current task visible
+2. update `activeForm` to `Retrying <task-id>` when the tool call is available
+3. never advance the native task to `completed`
+
+## Completion Rule
+
+When execute finishes:
+
+1. ensure every checked task in `tasks.md` is `completed` in the native list
+2. do not invent native tasks for verify/review phases here
+3. keep the final chat summary short; the native task list is only a progress
+   surface, not the evidence surface
+
+## Guardrails
+
+- Native sync is best-effort UX, not correctness.
+- Never trust the native task list over `tasks.md`.
+- Never stop a CurDX run solely because `TaskCreate` or `TaskUpdate` failed.
+- Native task lifecycle guards are allowed to reject malformed CurDX-native
+  tasks, but they must not interfere with unrelated non-CurDX task-list usage.
+- Do not use `TodoWrite` here; interactive Claude sessions should prefer the
+  current Task tool family.

package/skills/implement/references/progress-contract.md

@@ -13,6 +13,10 @@ Recent commits:
 ════════════════════
 ```
 
+If native task sync is active, the Claude task list should mirror this same
+progress state. Do not duplicate long task inventories in chat just because the
+task list UI exists.
+
 When all tasks are complete:
 
 ```text

package/skills/implement/references/state-init.md

@@ -24,6 +24,9 @@ s['execute_state'].setdefault('global_iteration', 1)
 s['execute_state'].setdefault('recovery_mode', recovery_mode)
 s['execute_state'].setdefault('max_fix_tasks_per_original', max_fix_tasks)
 s['execute_state'].setdefault('fix_task_map', {})
+s['execute_state'].setdefault('native_task_map', {})
+s['execute_state'].setdefault('native_sync_enabled', True)
+s['execute_state'].setdefault('native_sync_failure_count', 0)
 if QUICK:
     s['quickMode'] = True
 json.dump(s, open(p, 'w'), indent=2, ensure_ascii=False)

package/skills/implement/references/stop-hook-execution.md

@@ -6,11 +6,13 @@ naturally and the hook layer decides whether Claude continues.
 ## Protocol
 
 ```text
-1. Execute 1 task (inline or via flow-executor, then wait for completion)
-2. End the response naturally
-3. stop-watcher.sh evaluates transcript markers, .state.json, and tasks.md
-4. If unchecked tasks remain, the hook blocks stop and injects continuation
-5. Repeat until ALL_TASKS_COMPLETE or recovery forces a halt
+1. Initialize execute_state, including native sync fields
+2. Rebuild native_task_map if the current session cannot update stored task ids
+3. Execute 1 task (inline or via flow-executor, then wait for completion)
+4. End the response naturally
+5. stop-watcher.sh evaluates transcript markers, .state.json, and tasks.md
+6. If unchecked tasks remain, the hook blocks stop and injects continuation
+7. Repeat until ALL_TASKS_COMPLETE or recovery forces a halt
 ```
 
 ## Completion Invariant
@@ -23,6 +25,14 @@ Stop-hook completion is double-checked:
 If either side disagrees, the hook resumes the first unchecked task instead of
 allowing the session to stop cleanly.
 
+If native task sync is active during a continuation round:
+
+- `.flow/specs/<name>/tasks.md` stays the source of truth
+- checked rows should be mirrored back to the native task list before the next
+  task starts
+- a stale `native_task_map` should trigger the rebuild rule from
+  `references/native-task-sync.md`, not a run failure
+
 ## Prerequisites
 
 - `--quick` should be set; otherwise `AskUserQuestion` can stall the loop
@@ -34,3 +44,7 @@ allowing the session to stop cleanly.
 During a stop-hook continuation, `stop_hook_active=true` is only a hint. The
 hook still checks transcript signals, `.state.json`, and `tasks.md` parity
 before deciding whether to continue or stop.
+
+Native task sync is session-local UX. Continuations may resume into a different
+Claude-native task list, so recovery must prefer rebuilding the UI mirror over
+mutating `.flow` state.

package/skills/implement/references/subagent-execution.md

@@ -5,6 +5,12 @@ task, but the backlog is not parallel-safe enough for waves.
 
 ## Dispatch Contract
 
+Before each dispatch, if native task sync is active:
+
+- reconcile obvious `tasks.md` vs native-task drift
+- mark the outgoing task `in_progress`
+- set the native active form to `Executing <task-id>` when available
+
 Dispatch one `flow-executor` at a time with a uniform prompt:
 
 ```text
@@ -32,12 +38,20 @@ When all tasks are done output: ALL_TASKS_COMPLETE
 
 After the agent completes, read the output marker:
 
-- `TASK_COMPLETE` -> mark progress and dispatch the next task
-- `TASK_FAILED` -> increment failure tracking and enter recovery
+- `TASK_COMPLETE` -> mark progress, mark the native task `completed`, and
+  dispatch the next task
+- `TASK_FAILED` -> increment failure tracking, keep the native task open, and
+  enter recovery
 - `ALL_TASKS_COMPLETE` -> mark execute complete and move to verify
 
+If a stored Claude task id no longer updates, rebuild `native_task_map` from
+the current `tasks.md`, then continue serial dispatch. Do not rewrite
+`.state.json` task cursor or `tasks.md` just because the UI task list changed.
+
 ## Guardrails
 
 - This strategy is serial; a single Agent dispatch is not parallel execution
 - Do not batch multiple independent tasks into one `flow-executor` prompt
 - Do not trust narrative summaries over the end marker
+- Native task sync belongs to the coordinator around the dispatch loop, not to
+  the `flow-executor` subagent itself

package/skills/implement/references/wave-execution.md

@@ -50,6 +50,12 @@ If the planner mis-tagged `[P]` (modifies the same file), split the wave automat
 
 ## Step 3: Dispatch a Single Wave (key: within a single response)
 
+Before dispatching the wave, if native task sync is active:
+
+- reconcile obvious `tasks.md` vs native-task drift
+- mark every task in the upcoming wave `in_progress`
+- set the active form to `Executing Wave <n>: <task ids>` when available
+
 ```
 # List multiple Agent tool calls in one response of the main agent:
 Agent(description="Execute 1.1", prompt=<...flow-executor + task_id=1.1...>)
@@ -106,6 +112,14 @@ for task in completed:
         warn(f"Task {task.id} modified undeclared files: {unexpected}")
 ```
 
+After aggregation, if native task sync is active:
+
+- mark each `completed` task `completed`
+- leave each `failed` task open for retry/recovery
+- if any `TaskUpdate` call reports a stale or missing Claude task id, rebuild
+  `native_task_map` from `tasks.md` and continue with `.flow` as source of
+  truth
+
 ## Step 5: Wave Failure Handling
 
 ```
@@ -137,6 +151,10 @@ failed_attempts >= 3 (cumulative):
 ▶ Wave 3/5 starting (VERIFY)...
 ```
 
+When native task sync is active, the Claude task list is the short-form UI
+surface for the same wave progress. Keep chat feedback compact instead of
+relisting the whole backlog after every wave.
+
 ## Configuration
 
 `.flow/config.json`:

package/skills/status/references/gather-contract.md

@@ -19,6 +19,9 @@ Gather read-only state in this order:
    - `execute_state.total_tasks`
    - `execute_state.failed_attempts`
    - `execute_state.global_iteration`
+   - `execute_state.native_sync_enabled`
+   - `execute_state.native_sync_failure_count`
+   - `execute_state.native_task_map` size
 5. If `tasks.md` exists, count:
    - completed tasks: lines matching `- [x] **`
    - open tasks: lines matching `- [ ] **`

package/skills/status/references/output-contract.md

@@ -15,6 +15,7 @@ Phase: <phase | unknown>
 Strategy: <strategy | auto>
 Tasks: <done>/<total from tasks.md> checked, state cursor <task_index>/<total_tasks>
 Failures: <failed_attempts>, rounds: <global_iteration>
+Native sync: <on|off>, mapped tasks: <count>, sync failures: <native_sync_failure_count>
 Artifacts: [x] research [x] requirements [x] design [x] tasks [ ] verify [ ] review
 Health: OK | NEEDS_ATTENTION
 Recovery: <one concrete next command>