speccrew 0.7.58 → 0.7.60

package/.speccrew/agents/speccrew-system-designer.md

@@ -36,7 +36,10 @@ Phase 4: Generate DESIGN-OVERVIEW.md (WORKER-DISPATCH + HARD STOP)
         ↓
 Phase 5: Dispatch Per-Platform Skills
   ├── Single Feature + Single Platform → Direct skill invocation
-  └── Multi-Feature or Multi-Platform → Worker dispatch (batch of 6)
+  └── Multi-Feature or Multi-Platform → Worker dispatch (batch of 6, skip_confirmation + skip_index_generation)
+        ↓
+Phase 5.5: Generate Platform INDEX.md (WORKER-DISPATCH)
+  └── Dispatch worker per platform with index_only=true to generate INDEX.md
         ↓
 Phase 6: Joint Confirmation (HARD STOP)
   └── Present all designs → User confirms → Finalize stage
@@ -59,6 +62,7 @@ This agent is an **orchestrator/dispatcher**. For system design execution (Phase
 This agent MAY directly create/modify ONLY the following files:
 - ✅ `DISPATCH-PROGRESS.json` (via update-progress.js script only)
 - ✅ `.checkpoints.json` (via update-progress.js script only)
+- ✅ `INDEX.md` per platform directory (generated by worker dispatched with `index_only: true` after all Feature×Platform workers complete)
 - ✅ Progress summary messages to user
 
 > Note: `framework-evaluation.md` is generated **ONLY** by the `speccrew-sd-framework-evaluate` skill.
@@ -74,7 +78,7 @@ This agent MAY directly create/modify ONLY the following files:
 3. ❌ DO NOT invoke `speccrew-sd-mobile` skill directly
 4. ❌ DO NOT invoke `speccrew-sd-desktop` skill directly
 5. ❌ DO NOT generate `*-design.md` files yourself
-6. ❌ DO NOT generate platform `INDEX.md` files yourself
+6. ❌ DO NOT generate INDEX.md directly — MUST dispatch worker with `index_only: true` in Phase 5.5 (WORKER-DISPATCH)
 7. ❌ DO NOT create design document content as fallback if worker fails
 
 ### Violation Recovery
@@ -128,6 +132,8 @@ This agent MUST execute tasks continuously without unnecessary interruptions.
 | Phase 3 | HARD STOP | User must confirm framework decisions before proceeding to Phase 4 |
 | Phase 4 | WORKER-DISPATCH + HARD STOP | DESIGN-OVERVIEW.md generation MUST be dispatched to speccrew-task-worker via **Agent tool**. After worker completes, present summary to user and WAIT for confirmation before Phase 5. |
 | Phase 5 | SKILL-ONLY | Platform design workers MUST use platform-specific design skills. Agent MUST NOT write design documents itself |
+| Phase 5 | SKIP-CONFIRMATION | Batch dispatch MUST include `skip_confirmation: true` and `skip_index_generation: true` in worker context. Workers skip Checkpoint A and Step 5 in batch mode |
+| Phase 5.5 | WORKER-DISPATCH-INDEX | After all workers complete, dispatch ONE worker per platform with `index_only: true` to generate INDEX.md. Orchestrator MUST NOT generate INDEX.md directly |
 | Phase 6 | HARD STOP | User must confirm all designs before finalizing |
 | ALL | ABORT ON FAILURE | If any skill invocation fails → STOP and report. Do NOT generate content manually as fallback |
 | ALL | SCRIPT ENFORCEMENT | All .checkpoints.json and WORKFLOW-PROGRESS.json updates via update-progress.js script. Manual JSON creation FORBIDDEN |
@@ -790,15 +796,17 @@ All workers execute simultaneously to maximize efficiency.
 > 1. **ONE Worker per Feature×Platform combination** — DO NOT group
 > 2. Use **Agent tool** to create `speccrew-task-worker` for each task
 > 3. Pass `skill_path`: `${ide_skills_dir}/${skill_name}/SKILL.md` (platform-specific skill)
-> 4. Pass context: task_id, feature_id, feature_name, platform_id, feature_spec_path, api_contract_path, techs_knowledge_paths, framework_decisions, output_base_path
+> 4. Pass context: task_id, feature_id, feature_name, platform_id, feature_spec_path, api_contract_path, techs_knowledge_paths, framework_decisions, output_base_path, **skip_confirmation: true**, **skip_index_generation: true**
 > 5. Dispatch ALL Workers in the same batch **SIMULTANEOUSLY** in a single turn
 > 6. **Wait** for ALL Workers in the batch to complete before dispatching next batch
 > 7. Update DISPATCH-PROGRESS.json after each Worker completes
+> 8. After ALL workers complete, dispatch ONE worker per platform with `index_only: true` to generate INDEX.md (WORKER-DISPATCH — see Phase 5.5 in orchestration SKILL.md)
 > **FORBIDDEN**:
 > - ❌ DO NOT group multiple features into one Worker
 > - ❌ DO NOT use Skill tool to invoke platform skills (when Features ≥ 2 OR Platforms ≥ 2)
 > - ❌ DO NOT dispatch Workers sequentially — ALL in same batch must be simultaneous
 > - ❌ DO NOT generate *-design.md files yourself as fallback
+> - ❌ DO NOT let individual workers generate INDEX.md in batch mode — set `skip_index_generation: true`; INDEX.md is generated in Phase 5.5 by separate worker with `index_only: true`
 
 ### 5.5 Update DISPATCH-PROGRESS.json
 
@@ -1088,6 +1096,7 @@ Otherwise
 - DO NOT create or manually edit DISPATCH-PROGRESS.json, .checkpoints.json, or WORKFLOW-PROGRESS.json — use update-progress.js script only
 - DO NOT update WORKFLOW-PROGRESS.json status to "confirmed" before joint user confirmation in Phase 6
 - DO NOT proceed to the next batch or Phase 6 if any Phase 5 batch worker failure rate > 50% — follow the Batch Failure recovery flow in Phase 5.6
+- DO NOT generate INDEX.md directly — set `skip_index_generation: true` in Feature×Platform worker context; dispatch separate worker with `index_only: true` in Phase 5.5 (WORKER-DISPATCH)
 - DO NOT skip backward compatibility checks for old format Feature Specs
 - DO NOT automatically transition to or invoke the next stage agent — user starts next stage in a new conversation
 

package/.speccrew/skills/speccrew-sd-backend/SKILL.md

@@ -30,10 +30,15 @@ tools: Read, Write, Glob, Grep
 
 ## Step 1: Read Inputs
 
+> **Conditional Execution**: If `index_only` = `true`, **skip Steps 1-4** and jump directly to Step 5 to generate INDEX.md.
+
 **Input Parameters** (from agent context):
 - `feature_id` (optional): Feature identifier, e.g., `F-CRM-01`. If provided, use new naming format.
 - `feature_name`: Feature name, e.g., `customer-list`.
 - `platform_id`: Target platform, e.g., `backend-spring`, `backend-nestjs`.
+- `skip_confirmation` (optional, boolean): When `true`, skip Checkpoint A user confirmation (used in batch dispatch mode)
+- `skip_index_generation` (optional, boolean): When `true`, skip Step 5 INDEX.md generation (INDEX.md will be generated by orchestrator after all workers complete)
+- `index_only` (optional, boolean): When `true`, skip Steps 1-4 and ONLY execute Step 5 (INDEX.md generation). Used after all platform workers complete.
 
 Read in order:
 
@@ -88,7 +93,11 @@ Mark each function as:
 | `[MODIFIED]` | Modify existing implementation |
 | `[NEW]` | Create brand new implementation |
 
-**Checkpoint A: Present function list with markers to user for confirmation before proceeding.**
+**Checkpoint A**:
+- If `skip_confirmation` = `true`: Log the function list with markers and **proceed automatically** without waiting for user confirmation.
+- If `skip_confirmation` is not set or `false`: Present function list with markers to user and **wait for explicit confirmation** before proceeding.
+
+> ⚠️ **FORBIDDEN**: Worker MUST NOT self-decide to skip confirmation. Only the `skip_confirmation` parameter from dispatch context controls this behavior.
 
 ## Step 4: Generate Module Design Documents
 
@@ -160,6 +169,10 @@ Verify the completed design document:
 
 ## Step 5: Generate Platform INDEX.md
 
+> **Conditional Execution**:
+> - If `skip_index_generation` = `true`, **skip this entire Step 5**.
+> - If `index_only` = `true`, this step is the ONLY step to execute (Steps 1-4 are skipped).
+
 After all module designs are complete:
 
 ### 5.1 Read Index Template
@@ -311,7 +324,7 @@ When generating Mermaid diagrams, follow compatibility guidelines:
 - [ ] Feature Spec and API Contract read and understood
 - [ ] Existing codebase structure analyzed (Glob/Grep)
 - [ ] Function extraction completed with [EXISTING]/[MODIFIED]/[NEW] markers
-- [ ] Checkpoint A passed: function list confirmed with user
+- [ ] Checkpoint A passed: function list confirmed (or skipped via skip_confirmation)
 - [ ] Every API in API Contract has a corresponding implementation design
 - [ ] Database entities cover all data requirements from Feature Spec
 - [ ] Transaction boundaries defined for multi-step operations

package/.speccrew/skills/speccrew-sd-frontend/SKILL.md

@@ -30,10 +30,15 @@ tools: Read, Write, Glob, Grep
 
 ## Step 1: Read Inputs
 
+> **Conditional Execution**: If `index_only` = `true`, **skip Steps 1-4** and jump directly to Step 5 to generate INDEX.md.
+
 **Input Parameters** (from agent context):
 - `feature_id` (optional): Feature identifier, e.g., `F-CRM-01`. If provided, use new naming format.
 - `feature_name`: Feature name, e.g., `customer-list`.
 - `platform_id`: Target platform, e.g., `frontend-vue`, `frontend-react`.
+- `skip_confirmation` (optional, boolean): When `true`, skip Checkpoint A user confirmation (used in batch dispatch mode)
+- `skip_index_generation` (optional, boolean): When `true`, skip Step 5 INDEX.md generation (INDEX.md will be generated by orchestrator after all workers complete)
+- `index_only` (optional, boolean): When `true`, skip Steps 1-4 and ONLY execute Step 5 (INDEX.md generation). Used after all platform workers complete.
 
 Read in order:
 
@@ -86,7 +91,11 @@ Mark each function's components as:
 | `[MODIFIED]` | Enhance/change existing | `[MODIFIED] OrderTable - add new column` |
 | `[NEW]` | Create brand new | `[NEW] ProductDetailDrawer` |
 
-**Checkpoint A: Present function extraction summary to user for confirmation.**
+**Checkpoint A**:
+- If `skip_confirmation` = `true`: Log the function extraction summary and **proceed automatically** without waiting for user confirmation.
+- If `skip_confirmation` is not set or `false`: Present function extraction summary to user and **wait for explicit confirmation** before proceeding.
+
+> ⚠️ **FORBIDDEN**: Worker MUST NOT self-decide to skip confirmation. Only the `skip_confirmation` parameter from dispatch context controls this behavior.
 
 ## Step 4: Generate Module Design Documents
 
@@ -143,6 +152,10 @@ Verify the completed design document:
 
 ## Step 5: Generate Platform INDEX.md
 
+> **Conditional Execution**:
+> - If `skip_index_generation` = `true`, **skip this entire Step 5**.
+> - If `index_only` = `true`, this step is the ONLY step to execute (Steps 1-4 are skipped).
+
 After all module designs are complete:
 
 ### 5.1 Read Template
@@ -286,7 +299,7 @@ After completing all steps, output a structured completion report for the System
 - [ ] Directory structure follows conventions-design.md
 - [ ] INDEX.md generated with complete module list
 - [ ] All files written to correct paths under 03.system-design/{platform_id}/
-- [ ] Checkpoint A passed: function extraction confirmed with user
+- [ ] Checkpoint A passed: function extraction confirmed (or skipped via skip_confirmation)
 - [ ] **No TODO/FIXME placeholders** — all components and methods have complete pseudocode
 - [ ] **API routes match API Contract exactly** — verified route-by-route
 - [ ] **Cross-Feature dependencies explicitly marked** — all `[DEPENDENCY: F-XXX-NNN]` tags present with degradation strategy

package/.speccrew/skills/speccrew-sd-mobile/SKILL.md

@@ -30,6 +30,16 @@ tools: Read, Write, Glob, Grep
 
 ## Step 1: Read Inputs
 
+> **Conditional Execution**: If `index_only` = `true`, **skip Steps 1-4** and jump directly to Step 5 to generate INDEX.md.
+
+**Input Parameters** (from agent context):
+- `feature_id` (optional): Feature identifier, e.g., `F-CRM-01`.
+- `feature_name`: Feature name, e.g., `customer-list`.
+- `platform_id`: Target platform, e.g., `mobile-uniapp`, `mobile-flutter`.
+- `skip_confirmation` (optional, boolean): When `true`, skip Checkpoint A user confirmation (used in batch dispatch mode)
+- `skip_index_generation` (optional, boolean): When `true`, skip Step 5 INDEX.md generation (INDEX.md will be generated by orchestrator after all workers complete)
+- `index_only` (optional, boolean): When `true`, skip Steps 1-4 and ONLY execute Step 5 (INDEX.md generation). Used after all platform workers complete.
+
 Read in order:
 
 1. **Feature Spec document(s)**: `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-feature-spec.md`
@@ -80,7 +90,11 @@ Mark each function's screens/widgets as:
 | `[MODIFIED]` | Enhance/change existing | `[MODIFIED] OrderList - add pull-to-refresh` |
 | `[NEW]` | Create brand new | `[NEW] ProductDetailPage` |
 
-**Checkpoint A: Present function extraction summary to user for confirmation.**
+**Checkpoint A**:
+- If `skip_confirmation` = `true`: Log the function extraction summary and **proceed automatically** without waiting for user confirmation.
+- If `skip_confirmation` is not set or `false`: Present function extraction summary to user and **wait for explicit confirmation** before proceeding.
+
+> ⚠️ **FORBIDDEN**: Worker MUST NOT self-decide to skip confirmation. Only the `skip_confirmation` parameter from dispatch context controls this behavior.
 
 ## Step 4: Generate Module Design Documents
 
@@ -136,6 +150,10 @@ Verify the completed design document:
 
 ## Step 5: Generate Platform INDEX.md
 
+> **Conditional Execution**:
+> - If `skip_index_generation` = `true`, **skip this entire Step 5**.
+> - If `index_only` = `true`, this step is the ONLY step to execute (Steps 1-4 are skipped).
+
 After all module designs are complete:
 
 ### 5.1 Read Template
@@ -279,7 +297,7 @@ After completing all steps, output a structured completion report for the System
 - [ ] App lifecycle handling documented
 - [ ] INDEX.md generated with complete module list
 - [ ] All files written to correct paths under 03.system-design/{platform_id}/
-- [ ] **Checkpoint A passed**: function extraction confirmed with user
+- [ ] **Checkpoint A passed**: function extraction confirmed (or skipped via skip_confirmation)
 - [ ] **No TODO/FIXME placeholders** — all screens and methods have complete pseudocode
 - [ ] **API routes match API Contract exactly** — verified route-by-route
 - [ ] **Cross-Feature dependencies explicitly marked** — all `[DEPENDENCY: F-XXX-NNN]` tags present with degradation strategy

package/.speccrew/skills/speccrew-system-designer-orchestration/SKILL.md

@@ -130,14 +130,38 @@ This skill MUST execute tasks continuously without unnecessary interruptions.
 4. Compute batch plan (batch size = 6)
 5. For each batch:
    a. Use **Agent tool** to create `speccrew-task-worker` agents for ALL tasks in the batch **SIMULTANEOUSLY**
-   b. Each Worker receives: `skill_path` (platform-specific skill), `task_id`, `feature_id`, `feature_name`, `platform_id`, `feature_spec_path`, `api_contract_path`, `techs_knowledge_paths`, `framework_decisions`, `output_base_path`
+   b. Each Worker receives: `skill_path` (platform-specific skill), `task_id`, `feature_id`, `feature_name`, `platform_id`, `feature_spec_path`, `api_contract_path`, `techs_knowledge_paths`, `framework_decisions`, `output_base_path`, `skip_confirmation: true`, `skip_index_generation: true`
    c. **Wait** for ALL Workers in the batch to complete
    d. Update DISPATCH-PROGRESS.json for each completed Worker
    e. Log batch progress
 6. After all batches complete, read final progress summary
+7. Dispatch worker per platform with `index_only: true` to generate INDEX.md (see Phase 5.5)
 
 **CRITICAL**: Each Worker handles exactly ONE feature on ONE platform. DO NOT group multiple features or platforms into a single Worker.
 
+**Batch Dispatch Context Parameters**: When dispatching Workers in batch mode, the following parameters MUST be included in each Worker's context:
+- `skip_confirmation: true` — Workers skip Checkpoint A user confirmation (not feasible in batch mode)
+- `skip_index_generation: true` — Workers skip Step 5 INDEX.md generation (INDEX.md will be generated by orchestrator after all workers complete)
+
+### Phase 5.5: INDEX.md Generation (WORKER-DISPATCH)
+
+After ALL Feature×Platform workers complete successfully, dispatch ONE worker per platform to generate INDEX.md. Each worker receives `index_only: true` and `skip_index_generation: false`, executing ONLY Step 5 of the platform skill.
+
+**Dispatch parameters per platform**:
+- `agent`: speccrew-task-worker
+- `skill`: speccrew-sd-${platform.type}
+- `skill_path`: ${ide_skills_dir}/speccrew-sd-${platform.type}/SKILL.md
+- `context`:
+  - `index_only: true`
+  - `skip_index_generation: false`
+  - `platform_id`: ${platform.id}
+  - `output_dir`: ${iterations_dir}/${current_iteration}/03.system-design/${platform.id}
+  - `completed_documents`: ${platform.completed_documents}
+  - `techs_knowledge_dir`: ${techs_knowledge_dir}
+  - `workspace_path`: ${workspace_path}
+
+**FORBIDDEN**: Orchestrator generating INDEX.md directly. INDEX.md MUST be generated by worker.
+
 **Example** (5 features × 3 platforms = 15 workers, 3 batches of 6/6/3):
 - Batch 1: Workers 1-6 (parallel)
 - Batch 2: Workers 7-12 (parallel, after batch 1 completes)
@@ -148,6 +172,7 @@ This skill MUST execute tasks continuously without unnecessary interruptions.
 This workflow has **mandatory HARD STOP** checkpoints at:
 - **Phase 3.5**: Framework evaluation confirmation (user MUST approve framework decisions)
 - **Phase 4.5**: Design overview confirmation (user MUST approve DESIGN-OVERVIEW.md before Phase 5 dispatch)
+- **Phase 5.5**: (No HARD STOP — INDEX.md generation is automatic after all workers complete)
 - **Phase 6.1**: Joint design confirmation (user MUST approve all designs)
 
 DO NOT proceed past these checkpoints without explicit user confirmation.
@@ -168,6 +193,7 @@ DO NOT proceed past these checkpoints without explicit user confirmation.
 - **DO NOT generate framework-evaluation.md yourself** — Only workers generate it
 - **DO NOT create scripts for batch analysis** — Workers handle this via their own skill
 - **DO NOT fallback to inline execution if worker fails** — ABORT instead
+- **DO NOT let individual workers generate INDEX.md in batch mode** — `skip_index_generation: true` must be set; INDEX.md is generated in Phase 5.5 by separate worker with `index_only: true`
 - **DO NOT skip reading workflow.agentflow.xml** — XML is the execution authority
 - **DO NOT generate DESIGN-OVERVIEW.md yourself** — Dispatch speccrew-task-worker with speccrew-sd-design-overview-generate skill
 - **DO NOT use Skill tool for Phase 4 design overview generation** — Skill tool executes inline, Agent tool creates a worker

package/.speccrew/skills/speccrew-system-designer-orchestration/workflow.agentflow.xml

@@ -389,7 +389,9 @@
                 api_contract_path: ${task.api_contract_path},
                 techs_knowledge_paths: ${task.techs_knowledge_paths},
                 framework_decisions: ${framework_result.decisions},
-                output_base_path: ${iterations_dir}/${current_iteration}/03.system-design
+                output_base_path: ${iterations_dir}/${current_iteration}/03.system-design,
+                skip_confirmation: true,
+                skip_index_generation: true
               </field>
               <field name="output" var="worker_result_${task.id}"/>
             </block>
@@ -421,6 +423,37 @@
       </branch>
     </block>
 
+    <!-- batch-update is available via: node update-progress.js batch-update --file <progress.json> --tasks-file <tasks.json> -->
+    <!-- Use when orchestrator needs to batch-update multiple task statuses at once -->
+
+    <!-- Phase 5.5: Generate Platform INDEX.md (WORKER-DISPATCH) -->
+    <block type="rule" id="P5-IDX-R1" level="mandatory" desc="INDEX.md Generation via Worker Dispatch">
+      <field name="text">
+        After ALL Feature×Platform workers complete, dispatch ONE worker per platform to generate INDEX.md.
+        - Each worker receives index_only=true, skip_index_generation=false
+        - Worker executes ONLY Step 5 of the platform skill
+        - FORBIDDEN: Orchestrator generating INDEX.md directly (must use worker)
+      </field>
+    </block>
+    <block type="loop" id="P5-IDX-L1" over="${platforms}" as="platform">
+      <block type="task" id="P5-IDX-DISPATCH" action="dispatch-to-worker" status="pending"
+             desc="Dispatch worker to generate INDEX.md for ${platform.id}">
+        <field name="agent">speccrew-task-worker</field>
+        <field name="skill">speccrew-sd-${platform.type}</field>
+        <field name="skill_path">${ide_skills_dir}/speccrew-sd-${platform.type}/SKILL.md</field>
+        <field name="context">
+          index_only: true
+          skip_index_generation: false
+          platform_id: ${platform.id}
+          output_dir: ${iterations_dir}/${current_iteration}/03.system-design/${platform.id}
+          completed_documents: ${platform.completed_documents}
+          techs_knowledge_dir: ${techs_knowledge_dir}
+          workspace_path: ${workspace_path}
+        </field>
+      </block>
+    </block>
+    <block type="gateway" id="P5-IDX-GW1" mode="wait" desc="Wait for all INDEX.md workers to complete"/>
+
     <!-- Step 5.5: Read final dispatch progress -->
     <block type="task" id="P5-B5" action="run-script" status="pending"
            desc="Read final dispatch progress summary">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speccrew",
-  "version": "0.7.58",
+  "version": "0.7.60",
   "description": "Spec-Driven Development toolkit for AI-powered IDEs",
   "author": "charlesmu99",
   "repository": {

package/workspace-template/scripts/update-progress.js

@@ -65,7 +65,14 @@
  *      --features-dir <dir>    Directory containing features-*.json files (required)
  *      --force                 Overwrite existing file
  *
- * 8. sync - Sync task status with actual output files
+ * 8. batch-update - Batch update multiple task statuses from a JSON file
+ *    node update-progress.js batch-update --file <path> --tasks-file <path>
+ *    Options:
+ *      --file <path>           Progress file path (required)
+ *      --tasks-file <path>     JSON file with task updates (required)
+ *                               Format: [{"id": "task-id", "status": "completed", ...}]
+ *
+ * 9. sync - Sync task status with actual output files
  *    node update-progress.js sync --file <path> --dir <dir> --suffix <suffix> [--strict]
  *    Options:
  *      --file <path>           Progress file path (required)
@@ -1146,6 +1153,152 @@ function cmdInitKnowledgeTasks(args) {
     }
 }
 
+/**
+ * Command: batch-update - Batch update multiple task statuses from a JSON file
+ *
+ * Reads a list of task updates from a JSON file and applies them to the progress file.
+ * This avoids long command lines that can crash PSReadLine.
+ *
+ * Tasks file format:
+ * [
+ *   {"id": "task-1", "status": "completed"},
+ *   {"id": "task-2", "status": "failed", "error": "error message"},
+ *   {"id": "task-3", "status": "completed", "output": "result info"}
+ * ]
+ */
+function cmdBatchUpdate(args) {
+    if (!args.file || !args.tasksFile) {
+        outputError('Usage: batch-update --file <path> --tasks-file <path>');
+    }
+
+    const filePath = path.resolve(args.file);
+    const tasksFilePath = path.resolve(args.tasksFile);
+
+    // Read tasks file
+    let updates;
+    try {
+        updates = readJsonFile(tasksFilePath);
+    } catch (e) {
+        outputError(`Failed to read tasks file: ${e.message}`);
+    }
+
+    // Validate updates is an array
+    if (!Array.isArray(updates)) {
+        outputError('Tasks file must contain a JSON array of task updates');
+    }
+
+    if (updates.length === 0) {
+        outputError('Tasks file is empty — no updates to apply');
+    }
+
+    // Validate each update entry
+    const validStatuses = ['pending', 'in_progress', 'partial', 'completed', 'failed', 'confirmed'];
+    for (let i = 0; i < updates.length; i++) {
+        if (!updates[i].id) {
+            outputError(`Update entry at index ${i} is missing required "id" field`);
+        }
+        if (!updates[i].status) {
+            outputError(`Update entry at index ${i} (id: ${updates[i].id}) is missing required "status" field`);
+        }
+        if (!validStatuses.includes(updates[i].status)) {
+            outputError(`Invalid status "${updates[i].status}" for task ${updates[i].id}. Must be one of: ${validStatuses.join(', ')}`);
+        }
+    }
+
+    let lockPath = null;
+    try {
+        lockPath = acquireLock(filePath);
+        const data = readJsonFile(filePath);
+
+        const now = getTimestamp();
+        let updated = 0;
+        let notFound = 0;
+        let skipped = 0;
+        const notFoundIds = [];
+
+        // Build a lookup map for tasks (support both flat and nested structures)
+        // Flat structure: data.tasks array
+        if (data.tasks && Array.isArray(data.tasks)) {
+            for (const update of updates) {
+                const taskIndex = data.tasks.findIndex(t => t.id === update.id);
+                if (taskIndex === -1) {
+                    notFound++;
+                    notFoundIds.push(update.id);
+                    continue;
+                }
+
+                const task = data.tasks[taskIndex];
+
+                // Skip if already in target status
+                if (task.status === update.status) {
+                    skipped++;
+                    continue;
+                }
+
+                // Apply status update
+                task.status = update.status;
+                task.updated_at = now;
+
+                // Set timestamps based on status
+                if (update.status === 'in_progress') {
+                    task.started_at = now;
+                } else if (update.status === 'completed') {
+                    task.completed_at = now;
+                    if (update.output) {
+                        task.output = update.output;
+                    }
+                } else if (update.status === 'confirmed') {
+                    task.confirmed_at = now;
+                } else if (update.status === 'failed') {
+                    task.completed_at = now;
+                    if (update.error) {
+                        task.error = update.error;
+                    }
+                    if (update.error_category) {
+                        task.error_category = update.error_category;
+                    }
+                } else if (update.status === 'partial') {
+                    if (!task.started_at) {
+                        task.started_at = now;
+                    }
+                    if (update.output) {
+                        task.output = update.output;
+                    }
+                }
+
+                updated++;
+            }
+
+            // Recalculate counts
+            data.counts = calculateCounts(data.tasks);
+        } else {
+            // No flat tasks array — cannot batch update
+            outputError('Progress file does not contain a tasks array — batch-update only supports flat task structure');
+        }
+
+        data.updated_at = now;
+
+        // Atomic write
+        atomicWriteJson(filePath, data);
+
+        const result = {
+            total_updates_requested: updates.length,
+            updated: updated,
+            skipped_already_current: skipped,
+            not_found: notFound,
+            counts: data.counts
+        };
+
+        if (notFoundIds.length > 0) {
+            result.not_found_ids = notFoundIds;
+        }
+
+        outputSuccess(`Batch update completed: ${updated} tasks updated, ${skipped} skipped, ${notFound} not found`, result);
+    } finally {
+        if (lockPath) releaseLock(lockPath);
+    }
+}
+
 /**
  * Command: sync - Sync task status with actual output files
  * Scans directory for files matching suffix, extracts task IDs from filenames,
@@ -1494,6 +1647,7 @@ function main() {
         console.error('  update-workflow  Update a workflow stage status');
         console.error('  init-tasks       Generate tasks from feature-spec files');
         console.error('  init-knowledge-tasks  Generate knowledge initialization tasks from matcher results');
+        console.error('  batch-update     Batch update multiple task statuses from a JSON file');
         console.error('  sync             Sync task status with actual output files');
         console.error('');
         console.error('Run "node update-progress.js <command> --help" for more information.');
@@ -1527,6 +1681,9 @@ function main() {
             case 'init-knowledge-tasks':
                 cmdInitKnowledgeTasks(args);
                 break;
+            case 'batch-update':
+                cmdBatchUpdate(args);
+                break;
             case 'sync':
                 cmdSync(args);
                 break;