feat: 更新工作流执行文档，增强任务跟踪和状态映射规则

2026-02-04 01:40:45 +08:00 · 2025-12-15 15:16:16 +08:00
parent 0fe16963cd
commit ee0886fc48
1 changed files with 99 additions and 38 deletions
--- a/.codex/prompts/workflow/execute.md
+++ b/.codex/prompts/workflow/execute.md
@@ -13,19 +13,48 @@ argument-hint: SESSION=<path-to-session-folder>

 Session folder path via `$SESSION` (e.g., `.workflow/active/WFS-auth-system`)

+## Task Tracking (JSON Source of Truth + Codex TODO Tool)
+
+- **Source of truth**: Task state MUST be read from and written to `$SESSION/.task/IMPL-*.json`.
+- **Markdown views**: `$SESSION/TODO_LIST.md` and `$SESSION/IMPL_PLAN.md` are views; use them for ordering and display, but do NOT trust them for status.
+- **Codex TODO tool**: Mirror the workflow into the built-in `update_plan` tool so progress is visible and consistent.
+
+### Status mapping (Task JSON → `update_plan`)
+
+- Task JSON uses workflow statuses (source of truth): `pending`, `in_progress`, `completed` (optionally also `blocked`, `cancelled`, `container`).
+- `update_plan` only supports: `pending`, `in_progress`, `completed`.
+- Map as:
+  - `pending|blocked|cancelled|container` → `pending`
+  - `in_progress` → `in_progress`
+  - `completed` → `completed`
+
+### `update_plan` rules (must follow)
+
+1. At most ONE step can be `in_progress` at a time.
+2. Do NOT jump `pending → completed`; always go through `in_progress`.
+3. Do NOT batch-complete steps after the fact; update as you go.
+4. If the plan changes (new tasks, re-order, merge/split), call `update_plan` with an `explanation`.
+5. After calling `update_plan`, do NOT repeat the full plan in chat; only output a short progress line.
+6. Keep each `step` short and stable (ID-first), e.g. `IMPL-1.1 - Add JWT middleware`.
+
 ## Autonomous Execution Loop

 ```
 INIT: Validate session folder structure

 WHILE tasks remain:
-  1. Read TODO_LIST.md → Get task statuses
-  2. Find FIRST pending task with met dependencies
-  3. Read task JSON from .task/{task-id}.json
-  4. Execute task fully (pre-analysis → implementation → verification)
-  5. Update task JSON status to "completed"
-  6. Output progress: "[X/N] ✓ {task.title}"
-  7. CONTINUE to next task (DO NOT STOP)
+  1. Read TODO_LIST.md → Get ordered task IDs (ignore checkbox status)
+  2. For each task ID, read $SESSION/.task/{task-id}.json → Get true status + deps
+  3. Find FIRST eligible task:
+     - status != "completed"
+     - deps = taskJson.depends_on OR taskJson.context.depends_on (source of truth)
+     - deps all completed (from JSON)
+     - task is executable (skip status="container" or tasks with subtasks)
+  4. Mark task JSON status to "in_progress" (immediately)
+  5. Mirror status to `update_plan` (exactly one in_progress)
+  6. Execute task fully (pre-analysis → implementation → verification)
+  7. Mark task JSON status to "completed" (immediately after verification)
+  8. Mirror completion to `update_plan`, output progress line, CONTINUE (DO NOT STOP)

 WHEN all tasks completed:
  Output final summary
@@ -47,8 +76,9 @@ If missing, report error and stop.

 ### Step 2: Parse TODO_LIST.md

-Extract task list with current statuses:
+Extract the ordered task list (IDs + titles). Do not treat checkbox states as authoritative.
 ```markdown
+- ▸ **IMPL-1**: Parent task (container)
 - [x] IMPL-1: Task 1 title (completed)
 - [ ] IMPL-1.1: Task 2 title (pending) ← Execute this
 - [ ] IMPL-2: Task 3 title (pending, depends on IMPL-1.1)
@@ -59,11 +89,13 @@ Extract task list with current statuses:
 ```javascript
 // Sequential scan for first eligible task
 for (task of todoList) {
-  if (task.completed) continue
-  
-  // Check dependencies from task JSON
  taskJson = read(`$SESSION/.task/${task.id}.json`)
-  if (taskJson.depends_on?.every(dep => isCompleted(dep))) {
+  if (taskJson.status === "completed") continue
+  if (taskJson.status === "container") continue
+  
+  // Check dependencies from task JSON (source of truth)
+  const deps = taskJson.depends_on || taskJson.context?.depends_on || []
+  if (deps.every(dep => read(`$SESSION/.task/${dep}.json`).status === "completed")) {
    return task  // Execute this one
  }
 }
@@ -80,9 +112,28 @@ cat $SESSION/.task/$TASK_ID.json
 cat $SESSION/.process/context-package.json
 ```

-### Step 5: Execute Task
+### Step 5: Initialize Task Tracking (Codex TODO tool)

-#### 5A: Pre-Analysis (if flow_control.pre_analysis exists)
+Before executing the first task, initialize `update_plan` from the ordered task list:
+- Only include executable tasks (skip containers) to avoid non-actionable TODO items.
+- `step`: Use a stable ID-first label like `IMPL-1.1 - {title}`.
+- `status`: Map from task JSON status using the rules above.
+
+Keep this plan updated throughout execution (see rules above).
+
+Example initialization:
+```javascript
+update_plan({
+  plan: [
+    { step: "IMPL-1.1 - Task title", status: "pending" },
+    { step: "IMPL-2 - Task title", status: "pending" }
+  ]
+})
+```
+
+### Step 6: Execute Task
+
+#### 6A: Pre-Analysis (if flow_control.pre_analysis exists)
 ```markdown
 ## Pre-Analysis for: [task.title]

@@ -92,45 +143,50 @@ Execute each step:
 3. [Load dependencies]
 ```

-#### 5B: Implementation
+#### 6B: Implementation
 ```markdown
 ## Implementing: [task.title]

-**Objective**: [context.objective]
+**Requirements**:
+- [context.requirements[0]]
+- ...

 **Steps**:
-1. [flow_control.execution_steps[0]]
-2. [flow_control.execution_steps[1]]
+1. [flow_control.implementation_approach[0].step] - [flow_control.implementation_approach[0].action]
+2. [flow_control.implementation_approach[1].step] - [flow_control.implementation_approach[1].action]
 ...

-**Deliverables**:
- [ ] [context.deliverables[0]]
- [ ] [context.deliverables[1]]
+**Focus Paths**:
+- [context.focus_paths[0]]
+- ...
 ```

-#### 5C: Verification
+#### 6C: Verification
 ```markdown
 ## Verifying: [task.title]

 **Acceptance Criteria**:
- [x] [context.acceptance_criteria[0]]
- [x] [context.acceptance_criteria[1]]
+- [x] [context.acceptance[0]]
+- [x] [context.acceptance[1]]

 All criteria met: YES → Mark completed
 ```

-### Step 6: Update Status
+### Step 7: Update Status
+
+Update task JSON with correct transitions:
+- Before executing: `pending → in_progress`
+- After verification: `in_progress → completed`

-Update task JSON:
 ```json
 {
  "id": "IMPL-1.1",
-  "status": "completed",  // Changed from "pending"
+  "status": "completed",
  "completed_at": "2025-12-15T..."
 }
 ```

-### Step 7: Continue Immediately
+### Step 8: Continue Immediately

 **DO NOT STOP. Return to Step 2 to find next task.**

@@ -146,19 +202,23 @@ Output progress:
 {
  "id": "IMPL-1.1",
  "title": "Task Title",
-  "status": "pending|completed",
+  "status": "pending|in_progress|completed|blocked|cancelled|container",
  "meta": {
    "type": "feature|test|docs",
-    "execution_group": "group-id"
+    "agent": "code-developer|test-fix-agent|..."
  },
  "context": {
-    "objective": "What to achieve",
-    "deliverables": ["output 1", "output 2"],
-    "acceptance_criteria": ["check 1", "check 2"]
+    "requirements": ["Requirement 1", "Requirement 2"],
+    "focus_paths": ["src/module/"],
+    "acceptance": ["Criterion 1", "Criterion 2"],
+    "depends_on": ["IMPL-1"]
  },
  "flow_control": {
    "pre_analysis": ["step 1", "step 2"],
-    "execution_steps": ["impl step 1", "impl step 2"]
+    "implementation_approach": [
+      { "step": "Step 1", "action": "Do X" },
+      { "step": "Step 2", "action": "Do Y" }
+    ]
  },
  "depends_on": ["IMPL-1"]
 }
@@ -169,9 +229,10 @@ Output progress:
 1. **Never stop mid-workflow** - Continue until all tasks complete
 2. **One task at a time** - Fully complete before moving on
 3. **Respect dependencies** - Skip blocked tasks, find next eligible
-4. **Update status immediately** - Mark completed right after verification
+4. **Update status immediately** - Mark `in_progress` on start, `completed` right after verification
 5. **Self-verify** - All acceptance criteria must pass before marking done
-6. **Handle blocked state** - If all remaining tasks blocked, report and stop
+6. **Handle blocked state** - If all remaining tasks have unmet deps, report and stop
+7. **Keep tracking in sync** - Task JSON is truth; `update_plan` must reflect the same state

 ## Final Summary

@@ -208,5 +269,5 @@ When ALL tasks completed:
 | Task JSON not found | Error, skip task, continue |
 | Task blocked (deps not met) | Skip, find next eligible task |
 | All tasks blocked | Report circular dependency, stop |
-| Execution error | Report, mark task failed, continue to next |
-| Verification failed | Retry once, then report and continue |
+| Execution error | Report, set task JSON back to `pending`, continue to next eligible task |
+| Verification failed | Retry once; if still failing, set back to `pending` and continue |