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.
This commit is contained in:
catlog22
2026-03-07 18:17:10 +08:00
parent eaaadcd164
commit e368f9f8cc
2 changed files with 40 additions and 3 deletions

View File

@@ -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",

View File

@@ -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