speccrew 0.1.12 → 0.2.1

package/.speccrew/skills/speccrew-fd-feature-design/SKILL.md

@@ -98,6 +98,38 @@ For each function, identify:
 
 Ask: "Here is the function breakdown with [EXISTING]/[MODIFIED]/[NEW] markers. Does this align with your understanding of the requirements?"
 
+### Checkpoint A Progress Update
+
+After user confirms the function breakdown:
+
+1. **Write/Update `.checkpoints.json`**:
+   - Path: `speccrew-workspace/iterations/{iteration-id}/02.feature-design/.checkpoints.json`
+   - Content:
+     ```json
+     {
+       "stage": "02_feature_design",
+       "checkpoints": {
+         "function_decomposition": {
+           "passed": true,
+           "confirmed_at": "{current_timestamp}",
+           "description": "Function decomposition confirmed"
+         },
+         "feature_spec_review": {
+           "passed": false,
+           "confirmed_at": null
+         },
+         "api_contract_joint": {
+           "passed": false,
+           "confirmed_at": null
+         }
+       }
+     }
+     ```
+
+2. If the file already exists, merge with existing content (preserve other checkpoints)
+
+3. Log: "✅ Checkpoint A (function_decomposition) passed and recorded"
+
 ## Step 4: Determine Output Structure
 
 Based on PRD structure, determine feature spec output structure:
@@ -398,6 +430,38 @@ Data Entities: {count} new, {count} modified
 4. Are all business rules and constraints captured?
 5. **[Master-Sub]** Is the module breakdown appropriate?
 
+### Checkpoint B Progress Update
+
+After user confirms the complete feature spec:
+
+1. **Update `.checkpoints.json`**:
+   - Path: `speccrew-workspace/iterations/{iteration-id}/02.feature-design/.checkpoints.json`
+   - Update content:
+     ```json
+     {
+       "stage": "02_feature_design",
+       "checkpoints": {
+         "function_decomposition": {
+           "passed": true,
+           "confirmed_at": "..."
+         },
+         "feature_spec_review": {
+           "passed": true,
+           "confirmed_at": "{current_timestamp}",
+           "description": "Feature specification confirmed"
+         },
+         "api_contract_joint": {
+           "passed": false,
+           "confirmed_at": null
+         }
+       }
+     }
+     ```
+
+2. Preserve `function_decomposition` checkpoint status when updating
+
+3. Log: "✅ Checkpoint B (feature_spec_review) passed and recorded"
+
 ## Step 10: Write Files
 
 ### 10.1 Determine Output Paths
@@ -473,6 +537,100 @@ Key requirements:
 
 After feature spec documents are complete, call `speccrew-fd-api-contract/SKILL.md` to generate API contract document.
 
+### 10.5 Multi-Platform Dispatch Progress Management
+
+**For multi-platform feature design (multiple frontend platforms):**
+
+#### 10.5.1 Pre-Dispatch: Check Resume State
+
+Before dispatching to multiple platforms:
+
+1. **Read existing `DISPATCH-PROGRESS.json`**:
+   - Path: `speccrew-workspace/iterations/{iteration-id}/02.feature-design/DISPATCH-PROGRESS.json`
+   - If exists, analyze task status:
+     ```json
+     {
+       "stage": "02_feature_design",
+       "total": 3,
+       "completed": 2,
+       "failed": 0,
+       "pending": 1,
+       "tasks": [
+         {
+           "id": "fd-web-vue",
+           "platform": "web-vue",
+           "skill": "speccrew-fd-feature-design",
+           "status": "completed",
+           "started_at": "...",
+           "completed_at": "...",
+           "output": "02.feature-design/[feature]-web-vue-feature-spec.md",
+           "error": null
+         }
+       ]
+     }
+     ```
+
+2. **Resume Strategy**:
+   - Skip tasks with `status == "completed"`
+   - Re-execute tasks with `status == "failed"`
+   - Execute tasks with `status == "pending"`
+
+#### 10.5.2 Initialize/Update Dispatch Progress
+
+Create or update `DISPATCH-PROGRESS.json` before starting dispatch:
+
+```json
+{
+  "stage": "02_feature_design",
+  "total": {count},
+  "completed": 0,
+  "failed": 0,
+  "pending": {count},
+  "tasks": [
+    {
+      "id": "fd-{platform}",
+      "platform": "{platform}",
+      "skill": "speccrew-fd-feature-design",
+      "status": "pending",
+      "started_at": null,
+      "completed_at": null,
+      "output": null,
+      "error": null
+    }
+  ]
+}
+```
+
+#### 10.5.3 Update Task Status on Completion
+
+After each worker completes:
+
+1. **Read current `DISPATCH-PROGRESS.json`**
+
+2. **Update the corresponding task entry**:
+   - On success:
+     ```json
+     {
+       "status": "completed",
+       "completed_at": "{timestamp}",
+       "output": "{output_file_path}"
+     }
+     ```
+   - On failure:
+     ```json
+     {
+       "status": "failed",
+       "completed_at": "{timestamp}",
+       "error": "{error_message}"
+     }
+     ```
+
+3. **Update summary counters** (`completed`, `failed`, `pending`)
+
+4. **Write updated `DISPATCH-PROGRESS.json`**
+
+5. Log progress: "📊 Dispatch progress: {completed}/{total} completed, {failed} failed, {pending} pending"
+
 # Key Rules
 
 | Rule | Description |

package/.speccrew/skills/speccrew-knowledge-bizs-api-analyze/SKILL.md

@@ -76,8 +76,8 @@ This skill operates in **strict sequential execution mode**:
 
 **Generated Files:**
 1. `{{documentPath}}` - Controller documentation file
-2. `{{completed_dir}}/{{fileName}}.done.json` - Completion status marker
-3. `{{completed_dir}}/{{fileName}}.graph.json` - Graph data marker
+2. `{{completed_dir}}/{module}-{subpath}-{fileName}.done.json` - Completion status marker
+3. `{{completed_dir}}/{module}-{subpath}-{fileName}.graph.json` - Graph data marker
 
 **Return Value:**
 ```json
@@ -856,7 +856,7 @@ Or in case of failure:
 > **ASSUMPTION**: The `completed_dir` directory already exists (pre-created by dispatch Stage 2). If write fails, report error — do NOT attempt to create directories.
 
 ### Pre-write Checklist (VERIFY before writing each file):
-- [ ] Filename follows `{fileName}` pattern (Java class name only)
+- [ ] Filename follows `{module}-{subpath}-{fileName}` pattern (see naming convention below)
 - [ ] File content is valid JSON (not empty)
 - [ ] All required fields are present and non-empty
 - [ ] File is written with UTF-8 encoding
@@ -875,30 +875,57 @@ Or in case of failure:
 
 **✅ CORRECT Format - MUST USE:**
 ```
-{completed_dir}/{fileName}.done.json     ← Completion status marker (JSON format)
-{completed_dir}/{fileName}.graph.json    ← Graph data marker (JSON format)
+{completed_dir}/{module}-{subpath}-{fileName}.done.json     ← Completion status marker (JSON format)
+{completed_dir}/{module}-{subpath}-{fileName}.graph.json    ← Graph data marker (JSON format)
 ```
 
+**Naming Rule Explanation:**
+
+The marker filename MUST follow the composite naming pattern `{module}-{subpath}-{fileName}` to prevent conflicts between same-named source files.
+
+**How to Extract Each Component from `{{sourcePath}}`:**
+
+1. **module**: Use `{{module}}` input variable directly (e.g., `system`, `trade`, `ai`)
+
+2. **subpath**: Extract the middle path between the module package root and the controller file:
+   - For Java: Remove package prefix up to the business layer (e.g., `controller/admin/`, `controller/app/`)
+   - Remove the file name at the end
+   - Replace path separators (`/`) with hyphens (`-`)
+   - If the file is at the module root directory, subpath will be empty → omit from filename
+
+3. **fileName**: Use `{{fileName}}` input variable (Java class name WITHOUT `.java` extension)
+
 **Examples:**
-- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/UserController.done.json`
-- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/UserController.graph.json`
+
+| sourcePath | module | subpath | fileName | Marker Filename |
+|------------|--------|---------|----------|-----------------|
+| `yudao-module-system/yudao-module-system-biz/src/main/java/cn/iocoder/yudao/module/system/controller/admin/notify/NotifyMessageController.java` | `system` | `controller-admin-notify` | `NotifyMessageController` | `system-controller-admin-notify-NotifyMessageController.done.json` |
+| `yudao-module-system/yudao-module-system-biz/src/main/java/cn/iocoder/yudao/module/system/controller/admin/user/UserController.java` | `system` | `controller-admin-user` | `UserController` | `system-controller-admin-user-UserController.done.json` |
+| `yudao-module-ai/yudao-module-ai-biz/src/main/java/cn/iocoder/yudao/module/ai/controller/admin/chat/ChatConversationController.java` | `ai` | `controller-admin-chat` | `ChatConversationController` | `ai-controller-admin-chat-ChatConversationController.done.json` |
+
+**Special Case - Empty subpath:**
+- If the controller is directly in the controller root directory (no subpath), use format: `{module}-{fileName}.done.json`
+- Example: `.../controller/admin/SystemController.java` → `system-SystemController.done.json`
+
+**Full Path Examples:**
+- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/system-controller-admin-notify-NotifyMessageController.done.json`
+- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/ai-controller-admin-chat-ChatConversationController.graph.json`
 
 **❌ WRONG Format - NEVER USE:**
 ```
-{fileName}.completed.json    ← WRONG extension
-{fileName}.done              ← WRONG extension (missing .json)
-{fileName}.done.txt          ← WRONG extension
-{fileName}_done.json         ← WRONG separator and extension
-{fileName}-completed.json    ← WRONG separator and extension
+{fileName}.done.json              ← WRONG: missing module and subpath (causes conflicts)
+{fileName}.graph.json             ← WRONG: missing module and subpath (causes conflicts)
+{module}-{fileName}.done.json     ← WRONG: missing subpath (may still conflict)
+{fileName}.completed.json         ← WRONG extension
+{fileName}.done                   ← WRONG extension (missing .json)
+{fileName}_done.json              ← WRONG separator and extension
 ```
 
 **❌ WRONG Filename Examples - NEVER USE:**
+- `UserController.done.json` - WRONG: missing module and subpath (conflicts with other `UserController.java` files)
+- `system-UserController.done.json` - WRONG: missing subpath (if file is in `controller/admin/user/`)
 - `UserController.completed.json` - WRONG: uses `.completed.json` instead of `.done.json`
-- `UserController.done` - WRONG: uses `.done` instead of `.done.json`
-- `UserController.done.txt` - WRONG: uses `.done.txt` instead of `.done.json`
 - `UserController_done.json` - WRONG: uses underscore and wrong extension
-- `dict-UserController.done.json` - WRONG: has module prefix
-- `system-UserController.done.json` - WRONG: has module prefix
 
 ---
 
@@ -959,9 +986,9 @@ Or in case of failure:
 > {"fileName": "UserController", "status": "success", ...}
 > ```
 
-Use the Write tool to create file at `{{completed_dir}}/{{fileName}}.done.json`:
+Use the Write tool to create file at `{{completed_dir}}/{module}-{subpath}-{fileName}.done.json`:
 
-**Full path example:** `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/UserController.done.json`
+**Full path example:** `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/system-controller-admin-user-UserController.done.json`
 
 **Complete JSON Template (ALL fields required):**
 ```json
@@ -998,12 +1025,13 @@ Use the Write tool to create file at `{{completed_dir}}/{{fileName}}.done.json`:
 
 > **⚠️ CRITICAL**: The `documentPath` field is MANDATORY. It MUST match the `{{documentPath}}` variable from Step 5a. This is used to verify the document was created successfully.
 
-⚠️ **CRITICAL NAMING RULE:** Filename MUST be `{fileName}.done.json`, where `fileName` is the Java class name (e.g., `UserController`, `AiKnowledgeDocumentCreateListReqVO`).
-- ✅ CORRECT: `UserController.done.json` (using Java class name directly)
-- ✅ CORRECT: `AiKnowledgeDocumentCreateListReqVO.done.json` (using Java class name directly)
+⚠️ **CRITICAL NAMING RULE:** Filename MUST be `{module}-{subpath}-{fileName}.done.json` to prevent conflicts between same-named files.
+- ✅ CORRECT: `system-controller-admin-user-UserController.done.json` (full composite naming)
+- ✅ CORRECT: `ai-controller-admin-chat-ChatConversationController.done.json` (full composite naming)
+- ✅ CORRECT: `system-SystemController.done.json` (when subpath is empty, controller at root)
+- ❌ WRONG: `UserController.done.json` (missing module and subpath - will conflict)
 - ❌ WRONG: `UserController.done` (missing .json extension)
-- ❌ WRONG: `dict-UserController.done.json` (using old featureId format)
-- ❌ WRONG: `system-UserController.done.json` (using module prefix)
+- ❌ WRONG: `system-UserController.done.json` (missing subpath when controller is in nested package)
 
 ⚠️ **CRITICAL:** The file MUST contain valid JSON content. Empty files or files with only whitespace will cause processing failures.
 
@@ -1011,9 +1039,9 @@ Use the Write tool to create file at `{{completed_dir}}/{{fileName}}.done.json`:
 
 > **⚠️ CRITICAL FORMAT REQUIREMENT**: The `.graph.json` file MUST be valid JSON and **MUST include the root-level `module` field**. Do NOT rely on scripts to infer the module from `.done` file - the `module` field MUST be explicitly present at the root level of `.graph.json`.
 
-Use the Write tool to create file at `{{completed_dir}}/{{fileName}}.graph.json`:
+Use the Write tool to create file at `{{completed_dir}}/{module}-{subpath}-{fileName}.graph.json`:
 
-**Full path example:** `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/UserController.graph.json`
+**Full path example:** `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/system-controller-admin-user-UserController.graph.json`
 
 ```json
 {
@@ -1045,11 +1073,13 @@ Use the Write tool to create file at `{{completed_dir}}/{{fileName}}.graph.json`
 > - Do NOT assume scripts will fall back to reading from `.done` file
 > - Missing `module` field will cause the graph merge pipeline to reject this file
 
-⚠️ **CRITICAL NAMING RULE:** Filename MUST be `{fileName}.graph.json`, where `fileName` is the Java class name (e.g., `UserController`, `AiKnowledgeDocumentCreateListReqVO`).
-- ✅ CORRECT: `UserController.graph.json` (using Java class name directly)
-- ✅ CORRECT: `AiKnowledgeDocumentCreateListReqVO.graph.json` (using Java class name directly)
+⚠️ **CRITICAL NAMING RULE:** Filename MUST be `{module}-{subpath}-{fileName}.graph.json` to prevent conflicts between same-named files.
+- ✅ CORRECT: `system-controller-admin-user-UserController.graph.json` (full composite naming)
+- ✅ CORRECT: `ai-controller-admin-chat-ChatConversationController.graph.json` (full composite naming)
+- ✅ CORRECT: `system-SystemController.graph.json` (when subpath is empty, controller at root)
+- ❌ WRONG: `UserController.graph.json` (missing module and subpath - will conflict)
 - ❌ WRONG: `dict-UserController.graph.json` (using old featureId format)
-- ❌ WRONG: `system-UserController.graph.json` (using module prefix)
+- ❌ WRONG: `system-UserController.graph.json` (missing subpath when controller is in nested package)
 
 ⚠️ **CRITICAL:** The file MUST contain valid JSON content. Empty files or files with only whitespace will cause processing failures.
 

package/.speccrew/skills/speccrew-knowledge-bizs-dispatch/SKILL.md

@@ -426,30 +426,52 @@ Example: If batch has 5 features → create and launch 5 Worker Tasks simultaneo
 
 **✅ CORRECT Format - MUST USE:**
 ```
-{completed_dir}/{fileName}.done.json     ← Completion status marker (JSON format)
-{completed_dir}/{fileName}.graph.json    ← Graph data marker (JSON format)
+{completed_dir}/{module}-{subpath}-{fileName}.done.json     ← Completion status marker (JSON format)
+{completed_dir}/{module}-{subpath}-{fileName}.graph.json    ← Graph data marker (JSON format)
 ```
 
+**Naming Rule Explanation:**
+
+The marker filename MUST follow the composite naming pattern `{module}-{subpath}-{fileName}` to prevent conflicts between same-named source files.
+
+**How Workers Generate the Filename:**
+
+1. **module**: Use the `{{module}}` input variable directly
+
+2. **subpath**: Extract from `{{sourcePath}}`:
+   - For UI (Vue/React): Middle path between `views/` or `pages/` and the file name
+   - For API (Java): Middle path between controller root and the file name
+   - Replace path separators (`/`) with hyphens (`-`)
+   - Omit if file is at module root (empty subpath)
+
+3. **fileName**: Use `{{fileName}}` input variable (file name WITHOUT extension)
+
 **Examples:**
-- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/UserController.done.json`
-- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/UserController.graph.json`
+
+| Source File | module | subpath | fileName | Marker Filename |
+|-------------|--------|---------|----------|-----------------|
+| `yudao-ui/.../views/system/notify/message/index.vue` | `system` | `notify-message` | `index` | `system-notify-message-index.done.json` |
+| `yudao-ui/.../views/system/user/index.vue` | `system` | `user` | `index` | `system-user-index.done.json` |
+| `yudao-module-system/.../controller/admin/user/UserController.java` | `system` | `controller-admin-user` | `UserController` | `system-controller-admin-user-UserController.done.json` |
+
+**Full Path Examples:**
+- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/system-notify-message-index.done.json`
+- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/system-controller-admin-user-UserController.graph.json`
 
 **❌ WRONG Format - NEVER USE:**
 ```
-{fileName}.completed.json    ← WRONG extension
-{fileName}.done              ← WRONG extension (missing .json)
-{fileName}.done.txt          ← WRONG extension
-{fileName}_done.json         ← WRONG separator and extension
-{fileName}-completed.json    ← WRONG separator and extension
+{fileName}.done.json              ← WRONG: missing module and subpath (causes conflicts)
+{fileName}.graph.json             ← WRONG: missing module and subpath (causes conflicts)
+{fileName}.completed.json         ← WRONG extension
+{fileName}.done                   ← WRONG extension (missing .json)
+{fileName}_done.json              ← WRONG separator and extension
 ```
 
 **❌ WRONG Filename Examples - NEVER USE:**
+- `index.done.json` - WRONG: missing module and subpath (conflicts with other `index.vue` files)
+- `UserController.done.json` - WRONG: missing module and subpath (conflicts with other controllers)
 - `UserController.completed.json` - WRONG: uses `.completed.json` instead of `.done.json`
-- `UserController.done` - WRONG: uses `.done` instead of `.done.json`
-- `UserController.done.txt` - WRONG: uses `.done.txt` instead of `.done.json`
 - `UserController_done.json` - WRONG: uses underscore and wrong extension
-- `dict-UserController.done.json` - WRONG: has module prefix
-- `system-UserController.done.json` - WRONG: has module prefix
 
 ---
 
@@ -508,8 +530,8 @@ Example: If batch has 5 features → create and launch 5 Worker Tasks simultaneo
 
 | Marker Type | File Name Format | Example |
 |-------------|------------------|---------|
-| Completion marker | `{fileName}.done.json` | `index.done.json`, `UserController.done.json`, `AiKnowledgeDocumentCreateListReqVO.done.json` |
-| Graph data | `{fileName}.graph.json` | `index.graph.json`, `UserController.graph.json`, `AiKnowledgeDocumentCreateListReqVO.graph.json` |
+| Completion marker | `{module}-{subpath}-{fileName}.done.json` | `system-notify-message-index.done.json`, `system-controller-admin-user-UserController.done.json` |
+| Graph data | `{module}-{subpath}-{fileName}.graph.json` | `system-notify-message-index.graph.json`, `system-controller-admin-user-UserController.graph.json` |
 
 **Worker Completion Requirements:**
 

package/.speccrew/skills/speccrew-knowledge-bizs-dispatch/STATUS-FORMATS.md

@@ -6,6 +6,32 @@ This document defines the status tracking formats for the bizs pipeline.
 
 ---
 
+## Marker File Naming Convention
+
+Marker files (`.done.json` and `.graph.json`) use a composite naming pattern to prevent conflicts between same-named source files.
+
+**Format:** `{module}-{subpath}-{fileName}.{type}.json`
+
+**Components:**
+- **module**: Business module name (e.g., `system`, `ai`, `bpm`, `trade`)
+- **subpath**: Middle path extracted from sourcePath, with `/` replaced by `-` (e.g., `notify-message`, `controller-admin-user`)
+- **fileName**: Source file name without extension (e.g., `index`, `UserController`)
+- **type**: `done` or `graph`
+
+**Examples:**
+
+| Source File | Marker Filename |
+|-------------|-----------------|
+| `yudao-ui/.../views/system/notify/message/index.vue` | `system-notify-message-index.done.json` |
+| `yudao-ui/.../views/system/user/index.vue` | `system-user-index.done.json` |
+| `yudao-module-system/.../controller/admin/user/UserController.java` | `system-controller-admin-user-UserController.done.json` |
+
+**Special Case:** If subpath is empty (file at module root), use format: `{module}-{fileName}.{type}.json`
+
+**Legacy Format Support:** The processing scripts support both new format (`{module}-{subpath}-{fileName}`) and legacy format (`{fileName}`) for backward compatibility.
+
+---
+
 ## Feature Status Tracking (Stage 2)
 
 Feature analysis status is tracked directly in `features-{platform}.json` files located at:
@@ -61,11 +87,10 @@ Module summarization status is determined by aggregating feature statuses from `
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `features[].id` | string | Unique feature identifier (used for marker file naming) |
-| `features[].fileName` | string | Feature file name |
-| `features[].sourcePath` | string | Source code file path |
+| `features[].fileName` | string | Feature file name (without extension) - used as part of marker file naming |
+| `features[].sourcePath` | string | Source code file path - used to extract subpath for marker file naming |
 | `features[].documentPath` | string | Generated documentation path |
-| `features[].module` | string | Module code_name |
+| `features[].module` | string | Module code_name - used as prefix for marker file naming |
 | `features[].analyzed` | boolean | Whether feature has been analyzed |
 | `features[].status` | string | `pending`, `in_progress`, `completed`, `failed` |
 | `features[].startedAt` | string | ISO timestamp when analysis started |

package/.speccrew/skills/speccrew-knowledge-bizs-dispatch/scripts/process-batch-results.js

@@ -11,6 +11,53 @@ const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
 
+// Helper: Parse marker filename to extract components
+// New format: {module}-{subpath}-{fileName}.done.json
+// Legacy format: {fileName}.done.json
+function parseMarkerFilename(markerFile, fileType) {
+    // fileType: 'done' or 'graph'
+    const ext = `.${fileType}.json`;
+    if (!markerFile.endsWith(ext)) {
+        return null;
+    }
+    
+    const baseName = markerFile.slice(0, -ext.length);
+    const parts = baseName.split('-');
+    
+    // New format: must have at least 3 parts (module-subpath-fileName)
+    // But subpath can be empty, so minimum is 2 parts (module-fileName)
+    if (parts.length >= 2) {
+        // Try to identify if this is new format or legacy format
+        // New format has module prefix (known modules are usually short names like 'system', 'ai', 'bpm', 'trade')
+        // Legacy format is just fileName (e.g., 'index', 'UserController')
+        
+        // Heuristic: if first part is a known module-like name and there are more parts,
+        // treat it as new format
+        // For now, we'll return both possible interpretations and let the caller decide
+        return {
+            baseName: baseName,
+            parts: parts,
+            // For new format: fileName is the last part
+            newFormatFileName: parts[parts.length - 1],
+            // For new format: module is the first part
+            newFormatModule: parts[0],
+            // For new format: subpath is everything in between
+            newFormatSubpath: parts.length > 2 ? parts.slice(1, -1).join('-') : '',
+            // For legacy format: fileName is the entire baseName
+            legacyFileName: baseName,
+            // Detect likely format based on pattern
+            isLikelyNewFormat: parts.length > 1 && parts[0].length < 20 // module names are usually short
+        };
+    }
+    
+    return {
+        baseName: baseName,
+        parts: parts,
+        legacyFileName: baseName,
+        isLikelyNewFormat: false
+    };
+}
+
 // Helper: Validate and normalize .done.json file content
 function validateAndNormalizeDoneContent(content, doneFile) {
     // Strip file extensions from fileName if present
@@ -371,12 +418,16 @@ function main() {
 
     // Fallback: recover minimal info from filename and context when .done.json is non-JSON
     function recoverDoneFileFromContext(doneFile, completedDir, syncStatePath) {
-        const fileName = doneFile.replace(/\.done\.json$/, '');
+        const parseResult = parseMarkerFilename(doneFile, 'done');
+        
+        // Determine fileName: prefer content from .done.json, fall back to filename parsing
+        let fileName = parseResult ? parseResult.legacyFileName : doneFile.replace(/\.done\.json$/, '');
+        
         console.warn(`[WARN] .done.json file is not valid JSON: ${doneFile}. Attempting recovery from filename...`);
-
+        
         // Try to get module from same-named .graph.json
         let module = 'unknown';
-        const graphFilePath = path.join(completedDir, fileName + '.graph.json');
+        const graphFilePath = path.join(completedDir, doneFile.replace('.done.json', '.graph.json'));
         if (fs.existsSync(graphFilePath)) {
             try {
                 const graphContent = JSON.parse(fs.readFileSync(graphFilePath, 'utf8'));
@@ -387,6 +438,11 @@ function main() {
                 // Ignore parse errors
             }
         }
+        
+        // If module is still unknown, try to extract from new-format filename
+        if (module === 'unknown' && parseResult && parseResult.isLikelyNewFormat) {
+            module = parseResult.newFormatModule;
+        }
 
         // Try to match sourceFile from features-*.json files
         let sourceFile = 'unknown';
@@ -399,7 +455,18 @@ function main() {
                 try {
                     const content = JSON.parse(fs.readFileSync(filePath, 'utf8'));
                     if (content.features && Array.isArray(content.features)) {
-                        const found = content.features.find(feat => feat.fileName === fileName);
+                        // Try both new format and legacy format matching
+                        let found = content.features.find(feat => feat.fileName === fileName);
+                        
+                        // If not found with legacy fileName and we have new format info,
+                        // try matching with newFormatFileName
+                        if (!found && parseResult && parseResult.isLikelyNewFormat) {
+                            found = content.features.find(feat => feat.fileName === parseResult.newFormatFileName);
+                            if (found) {
+                                fileName = parseResult.newFormatFileName;
+                            }
+                        }
+                        
                         if (found) {
                             sourceFile = f;
                             break;