speccrew 0.7.34 → 0.7.36

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

@@ -54,7 +54,7 @@ Phase 4: API Contract Generation
 | ALL | ABORT ON FAILURE | If any skill invocation fails → STOP and report. Do NOT attempt to 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 |
 | ALL | NAME LOCK | After Phase 2 Feature List is confirmed, feature_name is immutable. All Skills MUST use the exact parameter value for output filenames. Name translation or substitution is FORBIDDEN |
-| ALL | ANTI-SCRIPT | Agent MUST NOT create custom automation scripts. DO NOT generate helper scripts (.sh, .ps1, .js) for batch processing or progress checking. Use ONLY the standard update-progress.js commands in documented workflow order. |
+| ALL | ANTI-SCRIPT | Agent MUST NOT create custom automation scripts. DO NOT generate helper scripts (.sh, .ps1, .js) for batch processing or progress checking. Use ONLY the standard update-progress.js commands in documented workflow order. If a required temp file (.tasks-temp.json) is missing, this indicates a workflow orchestration gap — follow the XML workflow's regeneration step, do NOT implement workarounds with ad-hoc commands. |
 
 ## MANDATORY WORKER ENFORCEMENT
 
@@ -742,7 +742,7 @@ Invoke API Contract skill directly:
   - `feature_spec_path`: Path to the Feature Spec document
   - `feature_id`: Feature ID (e.g., `F-CRM-01`)
   - `feature_type`: `Page+API` or `API-only`
-  - `output_path`: `{iterations_dir}/{iteration}/02.feature-design/{feature_id}-{feature-name-slug}-api-contract.md`
+  - `output_path`: `{iterations_dir}/{iteration}/03.api-contract/{feature_id}-{feature-name-slug}-api-contract.md`
 
 **Note**: Both `Page+API` and `API-only` Features require API Contract documents.
 
@@ -756,15 +756,33 @@ If **2+ Feature Specs** in registry:
 > Worker will read the skill's workflow.agentflow.xml for its execution plan.
 > See: MANDATORY: Worker Dispatch Prompt Format section above.
 
+### Phase 4: API Contract — Task File Management
+
+⚠️ **CRITICAL: .tasks-temp.json Regeneration**
+
+Phase 3 deletes `.tasks-temp.json` after init. Phase 4 MUST regenerate it before init:
+
+1. Read `{iteration_path}/02.feature-design/DISPATCH-PROGRESS.json` (Phase 3 results)
+2. Extract ALL task IDs from the tasks array
+3. Build flat JSON array: `[{"id":"F-M01-01"},{"id":"F-M01-02"},...]`
+4. Write to `{iteration_path}/03.api-contract/.tasks-temp.json`
+5. Run init: `node {workspace_path}/scripts/update-progress.js init --file {iteration_path}/03.api-contract/DISPATCH-PROGRESS.json --stage 02_feature_design_api_contract --tasks-file {iteration_path}/03.api-contract/.tasks-temp.json`
+6. Delete `.tasks-temp.json` after successful init
+
+**DO NOT**:
+- Run ad-hoc PowerShell/Bash commands to parse `.prd-feature-list.json`
+- Create custom scripts to build task lists
+- Skip the init step and manually edit DISPATCH-PROGRESS.json
+
 1. **Initialize DISPATCH-PROGRESS.json for API Contract stage**:
 
    > ⚠️ Use `--tasks-file` instead of `--tasks` to avoid PowerShell JSON parsing issues.
 
    ```bash
-   # Step 1: Write tasks JSON to temp file inside iteration directory
-   # Create .tasks-temp.json with the task array content
+   # Step 1: Read Phase 3 DISPATCH-PROGRESS.json and extract all task IDs
+   # Build flat JSON array: [{"id":"F-XXX"},...] and write to .tasks-temp.json
    # Step 2: Initialize with --tasks-file
-   node {update_progress_script} init --file {iterations_dir}/{iteration}/03.api-contract/DISPATCH-PROGRESS.json --stage 02_feature_design_api_contract --tasks-file {iterations_dir}/{iteration}/02.feature-design/.tasks-temp.json
+   node {update_progress_script} init --file {iterations_dir}/{iteration}/03.api-contract/DISPATCH-PROGRESS.json --stage 02_feature_design_api_contract --tasks-file {iterations_dir}/{iteration}/03.api-contract/.tasks-temp.json
    # Step 3: Delete .tasks-temp.json after successful init
    ```
 
@@ -782,7 +800,7 @@ If **2+ Feature Specs** in registry:
        - `feature_id`: Feature ID (e.g., `F-CRM-01`)
        - `feature_name`: Feature name — **MUST be the exact value from .checkpoints.json, used verbatim for output filename**
        - `feature_type`: `Page+API` or `API-only`
-       - `output_path`: `{iterations_dir}/{iteration}/02.feature-design/{feature_id}-{feature-name-slug}-api-contract.md`
+       - `output_path`: `{iterations_dir}/{iteration}/03.api-contract/{feature_id}-{feature-name-slug}-api-contract.md`
 
 3. **Wait for batch completion**, update progress per worker:
    ```bash
@@ -846,7 +864,7 @@ After user confirms Joint Confirmation:
    node {update_progress_script} update-workflow \
      --file {iterations_dir}/{iteration}/WORKFLOW-PROGRESS.json \
      --stage 02_feature_design --status confirmed \
-     --output "02.feature-design/F-CRM-01-customer-list-feature-spec.md,02.feature-design/F-CRM-01-customer-list-api-contract.md,..."
+     --output "02.feature-design/F-CRM-01-customer-list-feature-spec.md,03.api-contract/F-CRM-01-customer-list-api-contract.md,..."
    ```
 
 2. **Confirm Transition**:
@@ -858,7 +876,7 @@ After user confirms Joint Confirmation:
 | Deliverable | Path | Notes |
 |-------------|------|-------|
 | Feature Spec | `{iterations_dir}/{iteration}/02.feature-design/{feature-id}-{feature-name}-feature-spec.md` | One document per Feature |
-| API Contract | `{iterations_dir}/{iteration}/02.feature-design/{feature-id}-{feature-name}-api-contract.md` | One document per Feature |
+| API Contract | `{iterations_dir}/{iteration}/03.api-contract/{feature-id}-{feature-name}-api-contract.md` | One document per Feature |
 
 ## Naming Convention
 

package/.speccrew/agents/speccrew-task-worker.md

@@ -65,6 +65,13 @@ When executing design or document generation skills:
 - Only output brief block execution announcements
 - This is especially critical in batch mode where multiple Workers run simultaneously
 
+### FILE ENCODING
+
+ALL file operations MUST use UTF-8 encoding explicitly:
+- When creating files via tools: ensure UTF-8 (most IDE tools default to UTF-8)
+- When writing via Node.js: always pass `'utf8'` as encoding parameter
+- NEVER rely on system default encoding — Chinese Windows defaults to GBK which corrupts Unicode characters
+
 **FORBIDDEN output in conversation during design tasks:**
 - ASCII wireframes / UI prototypes
 - Mermaid diagrams (these go in the file only)

package/.speccrew/skills/speccrew-fd-api-contract/SKILL.md

@@ -80,9 +80,9 @@ Complete definition for each API:
 1. **Read the template file**: `templates/API-CONTRACT-TEMPLATE.md`
 2. **Replace top-level placeholders** (feature name, date, feature_id if provided, etc.)
 3. **Create the document** using `create_file`:
-   - **新格式（当提供了 feature_id 时）**：`speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/{feature-id}-{feature-name}-api-contract.md`
+   - **新格式（当提供了 feature_id 时）**：`speccrew-workspace/iterations/{number}-{type}-{name}/03.api-contract/{feature-id}-{feature-name}-api-contract.md`
      - 示例：`F-CRM-01-customer-list-api-contract.md`
-   - **旧格式（向后兼容，未提供 feature_id 时）**：`speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-api-contract.md`
+   - **旧格式（向后兼容，未提供 feature_id 时）**：`speccrew-workspace/iterations/{number}-{type}-{name}/03.api-contract/[feature-name]-api-contract.md`
    - Content: Template with top-level placeholders replaced
 4. **Verify**: Document has complete section structure ready for filling
 
@@ -127,7 +127,7 @@ Feature 设计阶段交付物已准备就绪：
 
 📄 文档清单：
    - Feature Spec: speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/{feature-id}-{feature-name}-feature-spec.md
-   - API Contract: speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/{feature-id}-{feature-name}-api-contract.md
+   - API Contract: speccrew-workspace/iterations/{number}-{type}-{name}/03.api-contract/{feature-id}-{feature-name}-api-contract.md
 
 请确认以下关键点：
 1. 当前 Feature 的技术方案是否可行？
@@ -146,7 +146,7 @@ Feature 设计阶段交付物已准备就绪：
 ```
 Feature design phase deliverables are ready:
 - Feature Spec: speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-feature-spec.md
-- API Contract: speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-api-contract.md
+- API Contract: speccrew-workspace/iterations/{number}-{type}-{name}/03.api-contract/[feature-name]-api-contract.md
 
 Please confirm the following key points:
 1. Is the overall technical solution feasible?
@@ -249,7 +249,7 @@ Update `WORKFLOW-PROGRESS.json` to reflect current feature/module status.
           "confirmed_at": "{current_timestamp}",
           "outputs": [
             "02.feature-design/{feature-id}-{feature-name}-feature-spec.md",
-            "02.feature-design/{feature-id}-{feature-name}-api-contract.md"
+            "03.api-contract/${feature_id}-${feature_name}-api-contract.md"
           ]
         }
       }
@@ -274,7 +274,7 @@ Update `WORKFLOW-PROGRESS.json` to reflect current feature/module status.
       "confirmed_at": "{current_timestamp}",
       "outputs": [
         "02.feature-design/[feature-name]-feature-spec.md",
-        "02.feature-design/[feature-name]-api-contract.md"
+        "03.api-contract/${feature_name}-api-contract.md"
       ]
     }
   }

package/.speccrew/skills/speccrew-fd-api-contract/workflow.agentflow.xml

@@ -81,21 +81,21 @@
         - {Feature ID} → ${feature_id}
         - {Date} → current date
       </field>
-      <field name="output_path">${iteration_path}/02.feature-design/${feature_id}-${feature_name}-api-contract.md</field>
-      <field name="fallback_path">${iteration_path}/02.feature-design/${feature_name}-api-contract.md</field>
+      <field name="output_path">${iteration_path}/03.api-contract/${feature_id}-${feature_name}-api-contract.md</field>
+      <field name="fallback_path">${iteration_path}/03.api-contract/${feature_name}-api-contract.md</field>
       <field name="output" var="document_created"/>
     </block>
 
     <!-- Checkpoint: Verify document created -->
     <block type="checkpoint" id="CP1" name="document-created" desc="Verify API contract document created">
-      <field name="file" value="${iteration_path}/02.feature-design/${feature_id}-${feature_name}-api-contract.md"/>
-      <field name="verify" value="file_exists(${iteration_path}/02.feature-design/${feature_id}-${feature_name}-api-contract.md)"/>
+      <field name="file" value="${iteration_path}/03.api-contract/${feature_id}-${feature_name}-api-contract.md"/>
+      <field name="verify" value="file_exists(${iteration_path}/03.api-contract/${feature_id}-${feature_name}-api-contract.md)"/>
     </block>
 
     <!-- Step 4b: Fill API List Overview Section -->
     <block type="task" id="B5" action="edit-file" desc="Fill API List Overview section">
-      <field name="path">${iteration_path}/02.feature-design/${feature_id}-${feature_name}-api-contract.md</field>
-      <field name="fallback_path">${iteration_path}/02.feature-design/${feature_name}-api-contract.md</field>
+      <field name="path">${iteration_path}/03.api-contract/${feature_id}-${feature_name}-api-contract.md</field>
+      <field name="fallback_path">${iteration_path}/03.api-contract/${feature_name}-api-contract.md</field>
       <field name="operation">search_replace</field>
       <field name="search">## API List Overview
 
@@ -123,8 +123,8 @@ ${api_list.table}</field>
       </block>
 
       <block type="task" id="B7" action="edit-file" desc="Fill API contract section">
-        <field name="path">${iteration_path}/02.feature-design/${feature_id}-${feature_name}-api-contract.md</field>
-        <field name="fallback_path">${iteration_path}/02.feature-design/${feature_name}-api-contract.md</field>
+        <field name="path">${iteration_path}/03.api-contract/${feature_id}-${feature_name}-api-contract.md</field>
+        <field name="fallback_path">${iteration_path}/03.api-contract/${feature_name}-api-contract.md</field>
         <field name="operation">search_replace</field>
         <field name="search">### ${api.name}
 
@@ -137,8 +137,8 @@ ${api_contract_details.content}</field>
 
     <!-- Step 6: Fill Error Code Summary -->
     <block type="task" id="B8" action="edit-file" desc="Fill Error Code Summary section">
-      <field name="path">${iteration_path}/02.feature-design/${feature_id}-${feature_name}-api-contract.md</field>
-      <field name="fallback_path">${iteration_path}/02.feature-design/${feature_name}-api-contract.md</field>
+      <field name="path">${iteration_path}/03.api-contract/${feature_id}-${feature_name}-api-contract.md</field>
+      <field name="fallback_path">${iteration_path}/03.api-contract/${feature_name}-api-contract.md</field>
       <field name="operation">search_replace</field>
       <field name="search">## Error Code Summary
 
@@ -161,7 +161,7 @@ Feature Name: ${feature_name}
 
 Documents:
 - Feature Spec: ${iteration_path}/02.feature-design/${feature_id}-${feature_name}-feature-spec.md
-- API Contract: ${iteration_path}/02.feature-design/${feature_id}-${feature_name}-api-contract.md
+- API Contract: ${iteration_path}/03.api-contract/${feature_id}-${feature_name}-api-contract.md
 
 Please confirm:
 1. Is the technical solution feasible?
@@ -175,7 +175,7 @@ After confirmation, API Contract becomes the sole baseline for frontend-backend
         <block type="event" id="E2" action="confirm" title="Feature Design Confirmation" type="yesno" desc="Request user confirmation">
           <field name="preview">Feature design phase deliverables ready:
 - Feature Spec: ${iteration_path}/02.feature-design/${feature_name}-feature-spec.md
-- API Contract: ${iteration_path}/02.feature-design/${feature_name}-api-contract.md
+- API Contract: ${iteration_path}/03.api-contract/${feature_name}-api-contract.md
 
 Please confirm:
 1. Is the overall technical solution feasible?
@@ -197,12 +197,12 @@ After confirmation, API Contract becomes the sole baseline for frontend-backend
     <block type="gateway" id="G4" mode="exclusive" desc="Update progress based on mode">
       <branch test="${feature_id} != null" name="Feature mode">
         <block type="task" id="B10" action="run-script" desc="Update workflow progress for feature">
-          <field name="command">node "${workspace_path}/scripts/update-progress.js" update-task --file "${iteration_path}/WORKFLOW-PROGRESS.json" --task-id "${feature_id}" --status confirmed --outputs '["02.feature-design/${feature_id}-${feature_name}-feature-spec.md","02.feature-design/${feature_id}-${feature_name}-api-contract.md"]'</field>
+          <field name="command">node "${workspace_path}/scripts/update-progress.js" update-task --file "${iteration_path}/WORKFLOW-PROGRESS.json" --task-id "${feature_id}" --status confirmed --outputs '["02.feature-design/${feature_id}-${feature_name}-feature-spec.md","03.api-contract/${feature_id}-${feature_name}-api-contract.md"]'</field>
         </block>
       </branch>
       <branch default="true" name="Module mode">
         <block type="task" id="B11" action="run-script" desc="Update workflow progress for module">
-          <field name="command">node "${workspace_path}/scripts/update-progress.js" update-stage --file "${iteration_path}/WORKFLOW-PROGRESS.json" --stage 02_feature_design --status confirmed --outputs '["02.feature-design/${feature_name}-feature-spec.md","02.feature-design/${feature_name}-api-contract.md"]'</field>
+          <field name="command">node "${workspace_path}/scripts/update-progress.js" update-stage --file "${iteration_path}/WORKFLOW-PROGRESS.json" --stage 02_feature_design --status confirmed --outputs '["02.feature-design/${feature_name}-feature-spec.md","03.api-contract/${feature_name}-api-contract.md"]'</field>
         </block>
       </branch>
     </block>
@@ -213,7 +213,7 @@ After confirmation, API Contract becomes the sole baseline for frontend-backend
        Output Results
        ============================================================ -->
   <block type="output" id="O1" desc="Workflow output results">
-    <field name="api_contract_path" value="${iteration_path}/02.feature-design/${feature_id}-${feature_name}-api-contract.md" type="string" desc="Path to generated API contract"/>
+    <field name="api_contract_path" value="${iteration_path}/03.api-contract/${feature_id}-${feature_name}-api-contract.md" type="string" desc="Path to generated API contract"/>
     <field name="feature_spec_path" value="${iteration_path}/02.feature-design/${feature_id}-${feature_name}-feature-spec.md" type="string" desc="Path to Feature Spec"/>
     <field name="api_count" from="${api_list.count}" type="number" desc="Number of APIs documented"/>
     <field name="confirmation_status" value="confirmed" type="string" desc="User confirmation status"/>

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

@@ -341,7 +341,7 @@
             feature_id: ${feature_list.modules[0].features[0].feature_id}
             feature_name: ${feature_list.modules[0].features[0].feature_name}
             feature_type: ${feature_list.modules[0].features[0].feature_type}
-            output_path: ${iteration_path}/02.feature-design/${feature_id}-${feature_name}-api-contract.md
+            output_path: ${iteration_path}/03.api-contract/${feature_id}-${feature_name}-api-contract.md
           </field>
           <field name="output" var="api_contract_result"/>
         </block>
@@ -355,9 +355,15 @@
           <field name="text">DO NOT invoke speccrew-fd-api-contract directly</field>
         </block>
 
+        <!-- Phase 4.1a: Regenerate tasks file from Phase 3 completed features -->
+        <block type="task" id="P4-B1c" action="analyze" status="pending" desc="Build API Contract task list from Phase 3 DISPATCH-PROGRESS.json">
+          <field name="text">Read ${iteration_path}/02.feature-design/DISPATCH-PROGRESS.json. Extract all task IDs (regardless of status). Build a flat JSON array: [{"id":"F-M01-01"},{"id":"F-M01-02"},...]. Write this array to ${iteration_path}/03.api-contract/.tasks-temp.json</field>
+          <field name="output" var="api_contract_tasks_file"/>
+        </block>
+
         <!-- Initialize DISPATCH-PROGRESS.json for API Contract stage -->
         <block type="task" id="P4-B2" action="run-script" status="pending" desc="Initialize API contract dispatch">
-          <field name="command">node ${workspace_root}/scripts/update-progress.js init --file ${iteration_path}/03.api-contract/DISPATCH-PROGRESS.json --stage 02_feature_design_api_contract --tasks-file ${iteration_path}/02.feature-design/.tasks-temp.json</field>
+          <field name="command">node ${workspace_root}/scripts/update-progress.js init --file ${iteration_path}/03.api-contract/DISPATCH-PROGRESS.json --stage 02_feature_design_api_contract --tasks-file ${iteration_path}/03.api-contract/.tasks-temp.json</field>
         </block>
 
         <!-- MANDATORY: Dispatch prompt must contain ONLY skill path + context data parameters.
@@ -376,7 +382,7 @@
               feature_id: ${item.feature_id}
               feature_name: ${item.feature_name}
               feature_type: ${item.feature_type}
-              output_path: ${iteration_path}/02.feature-design/${item.feature_id}-${item.feature_name}-api-contract.md
+              output_path: ${iteration_path}/03.api-contract/${item.feature_id}-${item.feature_name}-api-contract.md
             </field>
           </block>
 

package/.speccrew/skills/speccrew-pm-sub-prd-generate/SKILL.md

@@ -201,6 +201,14 @@ IF verification fails:
 > **Purpose:** Separate feature data from dispatch plan into dedicated `.prd-feature-list.json` file.
 > Each Sub-PRD Worker writes its module's features upon completion.
 
+> **CRITICAL: UTF-8 Encoding**
+> 
+> When writing ANY file (JSON, Markdown, or other text files), you MUST ensure UTF-8 encoding:
+> - Use `create_file` tool (which defaults to UTF-8) for file creation
+> - If using Node.js scripts: `fs.writeFileSync(path, content, 'utf8')`
+> - NEVER rely on system default encoding (may be GBK on Chinese Windows)
+> - This applies to ALL output files including `.prd-feature-list.json`
+
 ### 5.1 Determine Feature List File Path
 
 ```

package/.speccrew/skills/speccrew-pm-sub-prd-generate/workflow.agentflow.xml

@@ -190,6 +190,7 @@
 
     <block type="task" id="B17" action="write-file" desc="Update feature list file">
       <field name="path" value="${feature_list_path}"/>
+      <field name="encoding">utf8</field>
       <field name="merge">true</field>
       <field name="entry" value="${feature_list_entry}"/>
       <field name="output" var="feature_list_updated"/>

package/package.json

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

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

@@ -65,6 +65,14 @@
  *      --features-dir <dir>    Directory containing features-*.json files (required)
  *      --force                 Overwrite existing file
  *
+ * 8. 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)
+ *      --dir <path>            Output directory absolute path (required)
+ *      --suffix <suffix>       File suffix to match, e.g., -api-contract.md (required)
+ *      --strict                Also mark completed tasks as pending if file is missing
+ *
  * Output Format:
  *   Success: {"success": true, "message": "...", "data": {...}}
  *   Failure: {"success": false, "error": "..."} (output to stderr, exit code 1)
@@ -254,7 +262,10 @@ function parseArgs() {
         featuresDir: null,
         platforms: null,
         force: false,
-        metadata: null
+        metadata: null,
+        dir: null,
+        suffix: null,
+        strict: false
     };
 
     // First argument is the command
@@ -363,6 +374,18 @@ function parseArgs() {
             case '-Metadata':
                 result.metadata = args[++i];
                 break;
+            case '--dir':
+            case '-Dir':
+                result.dir = args[++i];
+                break;
+            case '--suffix':
+            case '-Suffix':
+                result.suffix = args[++i];
+                break;
+            case '--strict':
+            case '-Strict':
+                result.strict = true;
+                break;
         }
     }
 
@@ -1039,6 +1062,186 @@ function cmdInitKnowledgeTasks(args) {
     }
 }
 
+/**
+ * Command: sync - Sync task status with actual output files
+ * Scans directory for files matching suffix, extracts task IDs from filenames,
+ * and updates task status accordingly.
+ */
+function cmdSync(args) {
+    if (!args.file) { outputError('--file is required'); process.exit(1); }
+    if (!args.dir) { outputError('--dir is required'); process.exit(1); }
+    if (!args.suffix) { outputError('--suffix is required'); process.exit(1); }
+
+    const filePath = path.resolve(args.file);
+    const dirPath = path.resolve(args.dir);
+    
+    let lockPath = null;
+
+    try {
+        lockPath = acquireLock(filePath);
+        
+        const data = readJsonFile(filePath);
+        if (!data || !data.tasks) { outputError('Invalid progress file'); process.exit(1); }
+
+        // Check if directory exists
+        if (!fs.existsSync(dirPath)) {
+            outputError(`Directory not found: ${dirPath}`);
+        }
+
+        // Scan directory for matching files
+        const files = fs.readdirSync(dirPath).filter(f => f.endsWith(args.suffix));
+
+        // Extract task IDs from filenames
+        // Format: {task-id}-{feature-name}{suffix}
+        // task-id pattern: F-Mxx-xx (starts with F-, contains module and feature number)
+        const fileTaskIds = new Set();
+        const fileMap = {};
+        for (const file of files) {
+            // Extract task ID: match F-M followed by digits, dash, digits
+            const match = file.match(/^(F-M\d+-\d+)/);
+            if (match) {
+                fileTaskIds.add(match[1]);
+                fileMap[match[1]] = file;
+            }
+        }
+
+        let synced = 0;
+        let alreadyCorrect = 0;
+        let missing = 0;
+        const now = getTimestamp();
+
+        for (const task of data.tasks) {
+            const taskId = task.id;
+            if (fileTaskIds.has(taskId)) {
+                if (task.status !== 'completed') {
+                    task.status = 'completed';
+                    task.output = fileMap[taskId];
+                    task.completed_at = now;
+                    task.updated_at = now;
+                    synced++;
+                } else {
+                    alreadyCorrect++;
+                }
+            } else {
+                if (task.status === 'completed' && args.strict) {
+                    task.status = 'pending';
+                    delete task.output;
+                    delete task.completed_at;
+                    task.updated_at = now;
+                    missing++;
+                }
+            }
+        }
+
+        // Recalculate counts
+        data.counts = calculateCounts(data.tasks);
+        data.updated_at = now;
+
+        // Atomic write
+        atomicWriteJson(filePath, data);
+
+        outputSuccess('Sync completed', {
+            scanned_files: files.length,
+            synced: synced,
+            already_correct: alreadyCorrect,
+            missing_files: missing,
+            counts: data.counts
+        });
+    } 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,
+ * and updates task status accordingly.
+ */
+function cmdSync(args) {
+    if (!args.file) { outputError('--file is required'); process.exit(1); }
+    if (!args.dir) { outputError('--dir is required'); process.exit(1); }
+    if (!args.suffix) { outputError('--suffix is required'); process.exit(1); }
+
+    const filePath = path.resolve(args.file);
+    const dirPath = path.resolve(args.dir);
+    
+    let lockPath = null;
+
+    try {
+        lockPath = acquireLock(filePath);
+        
+        const data = readJsonFile(filePath);
+        if (!data || !data.tasks) { outputError('Invalid progress file'); process.exit(1); }
+
+        // Check if directory exists
+        if (!fs.existsSync(dirPath)) {
+            outputError(`Directory not found: ${dirPath}`);
+        }
+
+        // Scan directory for matching files
+        const files = fs.readdirSync(dirPath).filter(f => f.endsWith(args.suffix));
+
+        // Extract task IDs from filenames
+        // Format: {task-id}-{feature-name}{suffix}
+        // task-id pattern: F-Mxx-xx (starts with F-, contains module and feature number)
+        const fileTaskIds = new Set();
+        const fileMap = {};
+        for (const file of files) {
+            // Extract task ID: match F-M followed by digits, dash, digits
+            const match = file.match(/^(F-M\d+-\d+)/);
+            if (match) {
+                fileTaskIds.add(match[1]);
+                fileMap[match[1]] = file;
+            }
+        }
+
+        let synced = 0;
+        let alreadyCorrect = 0;
+        let missing = 0;
+        const now = getTimestamp();
+
+        for (const task of data.tasks) {
+            const taskId = task.id;
+            if (fileTaskIds.has(taskId)) {
+                if (task.status !== 'completed') {
+                    task.status = 'completed';
+                    task.output = fileMap[taskId];
+                    task.completed_at = now;
+                    task.updated_at = now;
+                    synced++;
+                } else {
+                    alreadyCorrect++;
+                }
+            } else {
+                if (task.status === 'completed' && args.strict) {
+                    task.status = 'pending';
+                    delete task.output;
+                    delete task.completed_at;
+                    task.updated_at = now;
+                    missing++;
+                }
+            }
+        }
+
+        // Recalculate counts
+        data.counts = calculateCounts(data.tasks);
+        data.updated_at = now;
+
+        // Atomic write
+        atomicWriteJson(filePath, data);
+
+        outputSuccess('Sync completed', {
+            scanned_files: files.length,
+            synced: synced,
+            already_correct: alreadyCorrect,
+            missing_files: missing,
+            counts: data.counts
+        });
+    } finally {
+        if (lockPath) releaseLock(lockPath);
+    }
+}
+
 /**
  * Command: init-tasks - Scan feature-design directory to generate task list
  */
@@ -1207,6 +1410,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('  sync             Sync task status with actual output files');
         console.error('');
         console.error('Run "node update-progress.js <command> --help" for more information.');
         process.exit(1);
@@ -1239,6 +1443,9 @@ function main() {
             case 'init-knowledge-tasks':
                 cmdInitKnowledgeTasks(args);
                 break;
+            case 'sync':
+                cmdSync(args);
+                break;
             default:
                 outputError(`Unknown command: ${args.command}`);
         }