@curdx/flow 2.3.11 → 3.0.0

package/hooks/scripts/subagent-statusline.sh

@@ -55,10 +55,16 @@ def active_spec(cwd):
     if not cwd:
         return ""
     try:
-        value = (Path(cwd) / ".flow" / ".active-spec").read_text(encoding="utf-8").strip()
+        current = Path(cwd).resolve()
     except Exception:
         return ""
-    return value[:40]
+    for candidate in [current, *current.parents]:
+        try:
+            value = (candidate / ".flow" / ".active-spec").read_text(encoding="utf-8").strip()
+        except Exception:
+            continue
+        return value[:40]
+    return ""
 
 
 def token_label(value):

package/hooks/scripts/task-lifecycle-guard.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/common.sh"
+
+INPUT="$(cat 2>/dev/null || echo "{}")"
+
+if ! has_python3; then
+  exit 0
+fi
+
+export CURDX_TASK_GUARD_INPUT="$INPUT"
+
+read_json_field() {
+  local field="$1"
+  python3 - "$field" <<'PY' 2>/dev/null
+import json
+import os
+import sys
+
+try:
+    data = json.loads(os.environ.get("CURDX_TASK_GUARD_INPUT", "{}"))
+except Exception:
+    data = {}
+
+field = sys.argv[1]
+value = data.get(field, "")
+if isinstance(value, str):
+    value = value.strip()
+elif value is None:
+    value = ""
+print(value)
+PY
+}
+
+HOOK_EVENT_NAME="$(read_json_field hook_event_name)"
+TASK_SUBJECT="$(read_json_field task_subject)"
+TASK_DESCRIPTION="$(read_json_field task_description)"
+
+FLOW_ROOT="$(resolve_flow_root 2>/dev/null || true)"
+[ -n "$FLOW_ROOT" ] || exit 0
+
+ACTIVE_SPEC="$(cat "$FLOW_ROOT/.flow/.active-spec" 2>/dev/null || true)"
+[ -n "$ACTIVE_SPEC" ] || exit 0
+
+TASKS_FILE="$FLOW_ROOT/.flow/specs/$ACTIVE_SPEC/tasks.md"
+[ -f "$TASKS_FILE" ] || exit 0
+
+extract_curdx_task_id() {
+  python3 <<'PY' 2>/dev/null
+import os
+import re
+
+subject = os.environ.get("CURDX_TASK_GUARD_SUBJECT", "").strip()
+patterns = [
+    r'^\[P\]\s+([0-9]+(?:\.([0-9]+|VF|X(\+[0-9]+)?))*)\b',
+    r'^\[VERIFY\]\s+([0-9]+(?:\.([0-9]+|VF|X(\+[0-9]+)?))*)\b',
+    r'^([0-9]+(?:\.([0-9]+|VF|X(\+[0-9]+)?))*)\b',
+]
+for pattern in patterns:
+    match = re.match(pattern, subject)
+    if match:
+        print(match.group(1))
+        break
+PY
+}
+
+export CURDX_TASK_GUARD_SUBJECT="$TASK_SUBJECT"
+CURDX_TASK_ID="$(extract_curdx_task_id)"
+[ -n "$CURDX_TASK_ID" ] || exit 0
+
+task_exists() {
+  local escaped_id
+  escaped_id="$(printf '%s' "$1" | sed 's/[.[\*^$()+?{|]/\\&/g')"
+  grep -Eq "^- \\[[ xX]\\] \\*\\*${escaped_id}\\*\\*" "$TASKS_FILE" 2>/dev/null
+}
+
+task_completed() {
+  local escaped_id
+  escaped_id="$(printf '%s' "$1" | sed 's/[.[\*^$()+?{|]/\\&/g')"
+  grep -Eq "^- \\[[xX]\\] \\*\\*${escaped_id}\\*\\*" "$TASKS_FILE" 2>/dev/null
+}
+
+if ! task_exists "$CURDX_TASK_ID"; then
+  printf '%s\n' "[CurDX-Flow task-lifecycle-guard] Native task '${TASK_SUBJECT}' references CurDX task ${CURDX_TASK_ID}, but ${TASKS_FILE} does not contain that task id. Rebuild native tasks from tasks.md before proceeding." >&2
+  exit 2
+fi
+
+case "$HOOK_EVENT_NAME" in
+  TaskCreated)
+    if [ -z "$TASK_DESCRIPTION" ]; then
+      printf '%s\n' "[CurDX-Flow task-lifecycle-guard] Native task '${TASK_SUBJECT}' is missing a description. Include a compact description derived from 'Done when' and 'Verify' so the task list mirrors tasks.md faithfully." >&2
+      exit 2
+    fi
+    ;;
+  TaskCompleted)
+    if ! task_completed "$CURDX_TASK_ID"; then
+      printf '%s\n' "[CurDX-Flow task-lifecycle-guard] Native task '${TASK_SUBJECT}' cannot be marked completed before ${TASKS_FILE} marks ${CURDX_TASK_ID} as [x]. Update tasks.md and disk-backed state first, then complete the native task." >&2
+      exit 2
+    fi
+    ;;
+esac
+
+exit 0

package/hooks/scripts/teammate-idle-guard.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# CurDX-Flow TeammateIdle Hook
+# Keeps artifact-producing CurDX teammates from idling before their disk artifact lands.
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/common.sh"
+
+INPUT="$(cat 2>/dev/null || echo "{}")"
+FLOW_ROOT="$(resolve_flow_root 2>/dev/null || true)"
+
+[ -n "$FLOW_ROOT" ] || exit 0
+has_python3 || exit 0
+
+export CURDX_TEAMMATE_IDLE_INPUT="$INPUT"
+
+read_json_field() {
+  local field="$1"
+  python3 - "$field" <<'PY' 2>/dev/null
+import json
+import os
+import sys
+
+try:
+    data = json.loads(os.environ.get("CURDX_TEAMMATE_IDLE_INPUT", "{}"))
+except Exception:
+    data = {}
+
+value = data.get(sys.argv[1], "")
+if isinstance(value, str):
+    value = value.strip()
+elif value is None:
+    value = ""
+print(value)
+PY
+}
+
+TEAM_NAME="$(read_json_field team_name)"
+TEAMMATE_NAME="$(read_json_field teammate_name)"
+
+[ -n "$TEAM_NAME" ] || exit 0
+[ -n "$TEAMMATE_NAME" ] || exit 0
+
+TEAM_CONFIG="${HOME}/.claude/teams/${TEAM_NAME}/config.json"
+[ -f "$TEAM_CONFIG" ] || exit 0
+
+export CURDX_TEAM_CONFIG="$TEAM_CONFIG"
+export CURDX_TEAMMATE_NAME="$TEAMMATE_NAME"
+
+AGENT_TYPE="$(python3 <<'PY' 2>/dev/null
+import json
+import os
+
+try:
+    data = json.load(open(os.environ["CURDX_TEAM_CONFIG"]))
+except Exception:
+    raise SystemExit(0)
+
+name = os.environ["CURDX_TEAMMATE_NAME"]
+for member in data.get("members", []) or []:
+    if isinstance(member, dict) and (member.get("name") or "").strip() == name:
+        print((member.get("agent_type") or "").strip())
+        break
+PY
+)"
+
+[ -n "$AGENT_TYPE" ] || exit 0
+
+curdx_resolve_artifact_contract "$AGENT_TYPE" "" "$FLOW_ROOT" || exit 0
+
+artifact_target="$CURDX_ARTIFACT_TARGET"
+minimum_size="$CURDX_ARTIFACT_MIN_SIZE"
+
+if [ -f "$artifact_target" ]; then
+  size="$(wc -c < "$artifact_target" 2>/dev/null | tr -d ' ')"
+  if [ "${size:-0}" -ge "$minimum_size" ]; then
+    exit 0
+  fi
+fi
+
+printf '%s\n' "[CurDX-Flow teammate-idle-guard] Teammate '${TEAMMATE_NAME}' (${AGENT_TYPE}) is about to go idle, but ${artifact_target} is missing or too small. Write the required CurDX artifact to disk before idling." >&2
+exit 2

package/knowledge/claude-code-runtime-contracts.md

@@ -32,6 +32,11 @@ When a behavior is unclear, prefer the official docs and `claude plugin validate
 - `PreToolUse` also supports `hookSpecificOutput.permissionDecision = "defer"` for deferred tool handling in `-p` / SDK-style flows; do not assume deny/allow are the only valid permission outcomes.
 - `PermissionDenied` can return `{ "retry": true }` to let Claude try a different approach after an auto-mode classifier denial.
 - Hooks must fail open when runtime prerequisites are missing (`python3`, malformed stdin JSON, absent `.flow/` state). The exception is an explicit, success-looking subagent completion with a missing required artifact.
+- Hook and monitor scripts must not assume the current working directory is the repo root. Official `CwdChanged` exists, and users often work from nested package/app directories, so CurDX-Flow runtime scripts should prefer `CLAUDE_PROJECT_DIR` and otherwise walk upward until they find the project `.flow/` root.
+- CurDX-Flow may use `CwdChanged` + `FileChanged` to maintain dynamic watch paths for `.flow/.active-spec`, the active spec `.state.json`, and `tasks.md`. Treat that watch layer as reactive context plumbing, not as a replacement for the monitor or disk-backed truth.
+- `TaskCreated` / `TaskCompleted` can be used as native-task-sync guardrails, but only for CurDX-shaped task subjects. Never let those hooks break unrelated user task-list workflows that happen outside an active CurDX spec.
+- `ConfigChange` can block project/local settings updates from taking effect in the running session. CurDX-Flow may use that to reject mid-execute changes that would disable hooks or reroute the main thread away from `flow-orchestrator`.
+- `TeammateIdle` has less context than `SubagentStop`, so CurDX-Flow should resolve `teammate_name -> agent_type` through `~/.claude/teams/<team-name>/config.json` before enforcing artifact gates for team-mode workers.
 
 ## Subagent Artifact Discipline
 
@@ -52,10 +57,22 @@ Guarded artifact targets:
 | `flow-edge-hunter` | `.flow/specs/<active>/edge-cases.md` |
 | `flow-adversary` | `.flow/specs/<active>/adversarial-review.md` |
 | `flow-ui-researcher` | `.flow/specs/<active>/ui-research.md` |
+| `flow-ux-designer` | `.flow/specs/<active>/ui-sketch/index.html` |
+| `flow-triage-analyst` | `.flow/_epics/<epic-name>/epic.md` |
 | `flow-brownfield-analyst` | `.flow/codebase-index.md` |
 
 `flow-executor` is marker-driven rather than report-driven: it must update task state and end with `TASK_COMPLETE: <task_id>` or `TASK_FAILED: <task_id>`.
 
+## Background Subagent Policy
+
+- Official background subagents keep the main conversation free while the worker runs, but any `AskUserQuestion` call inside that worker auto-denies instead of surfacing an interactive clarification prompt.
+- CurDX-Flow should therefore reserve `background: true` for agents that are:
+  - artifact-producing or evidence-gathering
+  - long-running enough to justify concurrency
+  - not dependent on `AskUserQuestion` for normal operation
+- Do not set `background: true` by default on `flow-executor`, `flow-debugger`, `flow-qa-engineer`, `flow-product-designer`, `flow-security-auditor`, `flow-triage-analyst`, or `flow-ux-designer` without a tighter clarification/permission contract.
+- If those same agent definitions are reused as teammates, `TeammateIdle` quality gates should reuse the same disk-artifact contract as subagent completion whenever the agent is artifact-bearing.
+
 ## Agent Teams Compatibility
 
 - Official `agent-teams` behavior differs from regular subagent invocation in one critical way: when a subagent definition runs as a teammate, its `skills` and `mcpServers` frontmatter fields are not applied.
@@ -69,6 +86,9 @@ Guarded artifact targets:
 - Use forked context and a named agent only when the skill's work benefits from isolation or a specialized role.
 - Avoid preloading broad tool access. Prefer the smallest useful tool set per skill/agent.
 - Do not make bundled skills or agents implicitly depend on runtime-gated tools such as `SendMessage`, `TeamCreate`, `TeamDelete`, or `ToolSearch` unless CurDX-Flow also ships the matching feature-flag/setup contract.
+- Interactive Claude sessions expose the Task tool family (`TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`) while headless / SDK flows use `TodoWrite`. Any CurDX native task-list sync must therefore be optional UX, not a correctness dependency.
+- Official interactive-mode docs also support `CLAUDE_CODE_TASK_LIST_ID` for sharing a native task list across sessions. CurDX-Flow may use that later as an optimization, but current execution must still recover correctly when the native task list changes or disappears.
+- If CurDX uses task lifecycle hooks, `TaskCreated` should reject orphan CurDX-native tasks that do not map to `tasks.md`, and `TaskCompleted` should reject UI completion that happens before `tasks.md` is updated.
 
 ## Plugin Settings
 
@@ -85,6 +105,7 @@ Guarded artifact targets:
 
 - CurDX-Flow ships a plugin monitor at `${CLAUDE_PLUGIN_ROOT}/monitors/monitors.json` to surface `.flow` state changes back into the active Claude session.
 - Monitors run only when the Claude `Monitor` tool is available, and only in interactive CLI sessions.
+- The monitor must keep working even when Claude's cwd moves below the repo root; `.flow` discovery should be project-root aware rather than cwd-fragile.
 - CurDX-Flow `userConfig` values are exported to plugin subprocesses as `CLAUDE_PLUGIN_OPTION_<KEY>`.
 - Current runtime knobs:
   - `autonomous_blocking`: lets users disable stop-hook continuation without editing plugin files.

package/monitors/scripts/flow-state-monitor.sh

@@ -2,6 +2,9 @@
 
 set -u
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/../../hooks/scripts/common.sh"
+
 interval="${CLAUDE_PLUGIN_OPTION_MONITOR_INTERVAL_SECONDS:-8}"
 case "$interval" in
   ''|*[!0-9]*)
@@ -13,15 +16,15 @@ if [ "$interval" -lt 3 ] 2>/dev/null; then
 fi
 
 build_snapshot() {
-  if [ ! -d ".flow" ]; then
-    return 0
-  fi
+  local flow_root=""
+  flow_root="$(resolve_flow_root 2>/dev/null || true)"
+  [ -n "$flow_root" ] || return 0
 
   local active=""
-  active="$(cat .flow/.active-spec 2>/dev/null || true)"
+  active="$(cat "$flow_root/.flow/.active-spec" 2>/dev/null || true)"
   [ -z "$active" ] && return 0
 
-  local spec_dir=".flow/specs/$active"
+  local spec_dir="$flow_root/.flow/specs/$active"
   [ ! -d "$spec_dir" ] && return 0
 
   local state_file="$spec_dir/.state.json"

package/output-styles/curdx-fast-mode.md

@@ -0,0 +1,42 @@
+---
+name: CurdX Fast Mode
+description: Low-ceremony style for /curdx-flow:fast and small surgical work. Skip preamble, ship the change, validate, stop.
+keep-coding-instructions: true
+---
+
+# CurdX Fast Mode
+
+You are still Claude Code. Keep the default coding workflow, safety rules,
+tool usage behavior, and verification discipline. This style strips ceremony
+for small, well-bounded tasks.
+
+## When this style fits
+
+Use during `/curdx-flow:fast` runs or any task that is obviously small,
+surgical, low-ambiguity, and not worth a full spec workflow.
+
+## Response priorities
+
+1. State the change in one sentence before the first edit.
+2. Make the smallest correct edit — do not refactor surrounding code, do
+   not introduce abstractions, do not "improve" unrelated lines.
+3. Run the smallest verification that proves the change works (one test,
+   one command, one curl). State it explicitly.
+4. End with a one-line status: `Validated` (with evidence), `Unvalidated`
+   (with reason), or `Blocked` (with the blocker).
+5. If you find scope creep — a second bug, a desired refactor, an unclear
+   interface — stop and surface it instead of expanding silently.
+
+## Hard rules
+
+- No spec scaffolding, no phase narration, no "let me think step by step".
+- No defensive validation, no fallback paths, no try/except for impossible
+  cases.
+- No new files unless the change inherently requires one.
+- No follow-on TODOs in the diff. Surface them in the reply, not the code.
+
+## Format
+
+- Plain prose with one diff or one command per paragraph.
+- Bullets only when listing more than two parallel items.
+- No section headers under three lines of content.

package/output-styles/curdx-spec-mode.md

@@ -0,0 +1,46 @@
+---
+name: CurdX Spec Mode
+description: Spec-driven verbose style for multi-phase work. Lead with the active phase, cite artifact paths, and never claim done without an evidence block.
+keep-coding-instructions: true
+---
+
+# CurdX Spec Mode
+
+You are still Claude Code. Keep the default coding workflow, safety rules,
+tool usage behavior, and verification discipline. This style adds spec-driven
+discipline on top of the defaults.
+
+## When this style fits
+
+Use this style during multi-phase CurDX-Flow work — research / requirements /
+design / tasks / execute / verify — when the user wants a clear paper trail
+across phases.
+
+## Response priorities
+
+1. State the active spec and phase explicitly. If no spec is active, say so.
+2. Lead with the artifact you produced or modified, including its full path
+   under `.flow/specs/<active>/`.
+3. Quote the smallest concrete decision that drove the change (one or two
+   lines). Do not repeat the full artifact body.
+4. End every reply with one of: `Validated`, `Unvalidated`, `Blocked`. State
+   what evidence backs the label.
+5. When proposing a next step, name the exact CurDX-Flow surface that should
+   run it (`/curdx-flow:spec --phase=design`, `flow-verifier`, etc.).
+
+## Hard rules
+
+- Never claim a phase is complete without referencing the produced artifact
+  on disk and the gate it passed.
+- Never produce a long architecture essay in chat — that belongs in the
+  spec artifact. The reply should point to the file and call out the
+  decision taken.
+- Never advance phase state from chat narrative. The phase counter in
+  `.state.json` is the source of truth; only the corresponding skill or
+  agent is allowed to advance it.
+
+## Format
+
+- Short headers only when they aid scanning.
+- Bullets for status, prose only for the decision rationale.
+- Match the user's language.

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@curdx/flow",
-  "version": "2.3.11",
+  "version": "3.0.0",
   "description": "Skill-first discipline layer and CLI installer for Claude Code",
   "type": "module",
   "bin": {
     "curdx-flow": "bin/curdx-flow.js"
   },
   "scripts": {
+    "test": "node --test test/*.test.mjs",
     "validate:contracts": "node scripts/validate-plugin-contracts.mjs",
-    "test": "node --test test/*.test.js",
-    "prepublishOnly": "npm run validate:contracts && node --test test/*.test.js && node bin/curdx-flow.js --version"
+    "validate:contracts:strict": "node scripts/validate-plugin-contracts.mjs --strict",
+    "lint": "echo 'lint placeholder; wired in P5'",
+    "prepublishOnly": "npm run validate:contracts && npm test"
   },
   "files": [
     "bin/",

package/schemas/agent-frontmatter.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://curdx-flow.dev/schemas/agent-frontmatter.schema.json",
   "title": "CurdX-Flow Agent Frontmatter",
-  "description": "Supported YAML frontmatter fields for agents/*.md plugin subagent definitions.",
+  "description": "Supported YAML frontmatter fields for agents/*.md plugin subagent definitions. Tracks the canonical field list documented at https://code.claude.com/docs/en/sub-agents.md#supported-frontmatter-fields. The fields `hooks`, `mcpServers`, and `permissionMode` are canonical for non-plugin agents but are silently ignored when an agent is loaded from a plugin (Claude Code security boundary), so this schema intentionally omits them — `additionalProperties: false` rejects them and surfaces the mistake at validation time instead of at runtime.",
   "type": "object",
   "required": ["name", "description"],
   "additionalProperties": false,
@@ -55,6 +55,9 @@
       "type": "string",
       "enum": ["worktree"]
     },
+    "initialPrompt": {
+      "type": "string"
+    },
     "color": {
       "type": "string",
       "enum": ["red", "blue", "green", "yellow", "purple", "orange", "pink", "cyan"]

package/schemas/spec-state.schema.json

@@ -98,6 +98,24 @@
               "last_error": { "type": "string" }
             }
           }
+        },
+        "native_task_map": {
+          "type": "object",
+          "description": "Best-effort mapping from CurDX task ids (for example 1.2 or 4.VF) to Claude native task ids for interactive task-list sync.",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "native_sync_enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "When false, execution skips Claude native task-list sync and relies only on tasks.md plus state.json."
+        },
+        "native_sync_failure_count": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0,
+          "description": "Consecutive best-effort native task sync failures during the current execute run."
         }
       }
     },

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)