From e368f9f8ccb2b1b387fa875cfcad79e131d6e8c4 Mon Sep 17 00:00:00 2001
From: catlog22 <catlog22@github.com>
Date: Sat, 7 Mar 2026 18:17:10 +0800
Subject: [PATCH] fix(ddd): address critical issues from code review

Critical fixes for DDD artifact structure enhancements:

TASK-003 (links{} navigation):
- Fixed relative path calculation in plan.md
- Changed doc_index path from ../../.doc-index/doc-index.json to ../../../doc-index.json
- Changed feature_maps path from ../../.doc-index/feature-maps/auth.md to ../../../feature-maps/auth.md
- Paths now correctly resolve from .workflow/.doc-index/planning/{session}/.task/

TASK-006 (schema versioning):
- Implemented schema_version check in plan.md Phase 1.0
- Implemented schema_version check in sync.md Phase 0.1
- Both commands now validate doc-index schema compatibility before processing
- Enables safe schema evolution and migration detection

TASK-005 (overview docs):
- Made sessions/_index.md update explicit in sync.md Phase 4.4
- Changed vague "Update _index.md files" to explicit "Update sessions/_index.md with new planning sessions"
- Ensures sessions index is properly maintained during sync operations

Session structure:
- Added .process/ directory to session folder structure documentation
- Clarifies where doc-context-package.json is stored
- Prevents first-run failures due to missing directory

All fixes maintain backward compatibility and follow graceful degradation patterns.
---
 .claude/commands/ddd/plan.md | 23 +++++++++++++++++++++--
 .claude/commands/ddd/sync.md | 20 +++++++++++++++++++-
 2 files changed, 40 insertions(+), 3 deletions(-)

diff --git a/.claude/commands/ddd/plan.md b/.claude/commands/ddd/plan.md
index 92459e4b..beabafdf 100644
--- a/.claude/commands/ddd/plan.md
+++ b/.claude/commands/ddd/plan.md
@@ -39,6 +39,8 @@ Full planning pipeline for document-driven development. Unlike simple context lo
 ├── explorations-manifest.json      # Exploration index
 ├── plan.json                       # Plan overview (Phase 4)
 ├── planning-context.md             # Legacy context package (Phase 0+1 combined)
+├── .process/
+│   └── doc-context-package.json    # Bundled doc_context (Phase 1.8)
 └── .task/
     ├── TASK-001.json
     └── TASK-002.json
@@ -78,6 +80,23 @@ Assess task complexity based on:
 
 ## Phase 1: Doc-Index Query
 
+### 1.0 Schema Version Check (TASK-006)
+
+Before querying doc-index, verify schema compatibility:
+
+```javascript
+const docIndex = JSON.parse(Read('.workflow/.doc-index/doc-index.json'));
+const schemaVersion = docIndex.schema_version || '0.0'; // Default for legacy
+
+if (schemaVersion !== '1.0') {
+  console.warn(`Schema version mismatch: found ${schemaVersion}, expected 1.0`);
+  console.warn('Consider running schema migration or regenerating doc-index with /ddd:scan');
+  // Continue with degraded functionality - may encounter missing fields
+}
+```
+
+**Graceful degradation**: If version mismatch detected → log warning → continue with caution (some features may not work as expected).
+
 ### 1.1 Feature Search
 
 ```
@@ -406,9 +425,9 @@ Add links{} navigation block to each TASK-*.json for improved discoverability:
 {
   "links": {
     "plan": "../plan.json",
-    "doc_index": "../../.doc-index/doc-index.json",
+    "doc_index": "../../../doc-index.json",
     "feature_maps": [
-      "../../.doc-index/feature-maps/auth.md"
+      "../../../feature-maps/auth.md"
     ],
     "related_tasks": [
       "TASK-002.json",
diff --git a/.claude/commands/ddd/sync.md b/.claude/commands/ddd/sync.md
index 4723051a..2d748fa2 100644
--- a/.claude/commands/ddd/sync.md
+++ b/.claude/commands/ddd/sync.md
@@ -39,6 +39,23 @@ After completing a development task, synchronize the document index with actual
 
 ## Phase 1: Change Detection
 
+### 0.1 Schema Version Check (TASK-006)
+
+Before processing changes, verify doc-index schema compatibility:
+
+```javascript
+const docIndex = JSON.parse(Read('.workflow/.doc-index/doc-index.json'));
+const schemaVersion = docIndex.schema_version || '0.0'; // Default for legacy
+
+if (schemaVersion !== '1.0') {
+  console.warn(`Schema version mismatch: found ${schemaVersion}, expected 1.0`);
+  console.warn('Consider running schema migration or regenerating doc-index with /ddd:scan');
+  // Continue with degraded functionality - may encounter missing fields
+}
+```
+
+**Graceful degradation**: If version mismatch detected → log warning → continue with caution (some features may not work as expected).
+
 ### 1.0 Data Source Selection
 
 ```
@@ -307,7 +324,8 @@ ccw cli -p "PURPOSE: Update project overview docs after feature changes
 TASK:
 • Update README.md feature list
 • Update ARCHITECTURE.md if new components added
-• Update _index.md files with new entries
+• Update sessions/_index.md with new planning sessions
+• Update other _index.md files with new entries
 MODE: write
 CONTEXT: @.workflow/.doc-index/feature-maps/*.md @.workflow/.doc-index/doc-index.json
 EXPECTED: Updated overview docs with current project state