specweave 0.22.13 → 0.22.14

package/dist/src/living-docs/id-registry.js

@@ -0,0 +1,230 @@
+/**
+ * ID Registry - Atomic Feature ID registration with collision detection
+ *
+ * Provides thread-safe ID registration using file-based locking to prevent
+ * race conditions during concurrent imports.
+ *
+ * Features:
+ * - File-based locking for atomic updates
+ * - Collision detection (checks both FS-XXX and FS-XXXE)
+ * - JSON-based persistent storage
+ * - Automatic lock cleanup with timeout
+ */
+import fs from 'fs-extra';
+import path from 'path';
+/**
+ * ID Registry with atomic file-based locking
+ */
+export class IDRegistry {
+    constructor(projectRoot) {
+        this.lockTimeout = 30000; // 30 seconds
+        this.retryDelay = 100; // 100ms
+        this.registryPath = path.join(projectRoot, '.specweave/.id-registry.json');
+        this.lockPath = path.join(projectRoot, '.specweave/.id-registry.lock');
+    }
+    /**
+     * Register a new Feature ID atomically
+     *
+     * @param fsId - Feature ID to register (e.g., "FS-042E")
+     * @param entry - Registry entry metadata
+     * @throws Error if collision detected or lock acquisition fails
+     */
+    async registerID(fsId, entry) {
+        // Acquire lock with timeout
+        await this.acquireLock();
+        try {
+            // Read current registry
+            const registry = await this.readRegistry();
+            // Check for collision (exact match or variant)
+            const collision = this.detectCollision(fsId, registry);
+            if (collision) {
+                throw new Error(`ID collision: ${fsId} conflicts with ${collision}`);
+            }
+            // Add new entry
+            registry.entries[fsId] = {
+                id: fsId,
+                ...entry
+            };
+            registry.lastUpdated = new Date().toISOString();
+            registry.version++;
+            // Write atomically
+            await this.writeRegistry(registry);
+        }
+        finally {
+            // Always release lock
+            await this.releaseLock();
+        }
+    }
+    /**
+     * Check if ID exists in registry
+     *
+     * @param fsId - Feature ID to check
+     * @returns True if ID is registered
+     */
+    async hasID(fsId) {
+        const registry = await this.readRegistry();
+        return fsId in registry.entries;
+    }
+    /**
+     * Get registry entry
+     *
+     * @param fsId - Feature ID to retrieve
+     * @returns Registry entry or null if not found
+     */
+    async getEntry(fsId) {
+        const registry = await this.readRegistry();
+        return registry.entries[fsId] || null;
+    }
+    /**
+     * Get all registered IDs
+     *
+     * @returns Array of all registered Feature IDs
+     */
+    async getAllIDs() {
+        const registry = await this.readRegistry();
+        return Object.keys(registry.entries);
+    }
+    /**
+     * Acquire lock file with timeout and retry
+     *
+     * @throws Error if lock cannot be acquired within timeout
+     */
+    async acquireLock() {
+        const startTime = Date.now();
+        // Ensure lock directory exists
+        await fs.ensureDir(path.dirname(this.lockPath));
+        while (true) {
+            try {
+                // Try to create lock file exclusively
+                await fs.writeFile(this.lockPath, Date.now().toString(), { flag: 'wx' });
+                return; // Lock acquired
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST') {
+                    throw error; // Unexpected error
+                }
+                // Lock exists, check timeout
+                const elapsed = Date.now() - startTime;
+                if (elapsed > this.lockTimeout) {
+                    // Check if lock is stale
+                    const lockAge = await this.getLockAge();
+                    if (lockAge > this.lockTimeout) {
+                        // Stale lock, force remove
+                        await fs.remove(this.lockPath);
+                        continue; // Retry
+                    }
+                    throw new Error(`Lock acquisition timeout after ${elapsed}ms`);
+                }
+                // Wait and retry
+                await this.sleep(this.retryDelay);
+            }
+        }
+    }
+    /**
+     * Release lock file
+     */
+    async releaseLock() {
+        try {
+            await fs.remove(this.lockPath);
+        }
+        catch (error) {
+            // Ignore if lock doesn't exist (already released)
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+    }
+    /**
+     * Get lock file age in milliseconds
+     *
+     * @returns Lock age or Infinity if lock doesn't exist
+     */
+    async getLockAge() {
+        try {
+            const lockContent = await fs.readFile(this.lockPath, 'utf-8');
+            const lockTime = parseInt(lockContent, 10);
+            return Date.now() - lockTime;
+        }
+        catch (error) {
+            return Infinity; // Lock doesn't exist
+        }
+    }
+    /**
+     * Read registry from disk
+     *
+     * @returns Registry data
+     */
+    async readRegistry() {
+        try {
+            const content = await fs.readFile(this.registryPath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                // Registry doesn't exist, return empty
+                return {
+                    entries: {},
+                    lastUpdated: new Date().toISOString(),
+                    version: 1
+                };
+            }
+            throw error;
+        }
+    }
+    /**
+     * Write registry to disk atomically
+     *
+     * @param registry - Registry data to write
+     */
+    async writeRegistry(registry) {
+        await fs.ensureDir(path.dirname(this.registryPath));
+        // Write to temp file first
+        const tempPath = `${this.registryPath}.tmp`;
+        await fs.writeFile(tempPath, JSON.stringify(registry, null, 2));
+        // Atomic rename
+        await fs.rename(tempPath, this.registryPath);
+    }
+    /**
+     * Detect ID collision (exact match or variant)
+     *
+     * @param fsId - ID to check (e.g., "FS-042E")
+     * @param registry - Current registry
+     * @returns Conflicting ID or null if no collision
+     *
+     * @example
+     * // Given registry: {FS-042: {...}}
+     * detectCollision('FS-042E', registry) // Returns: 'FS-042'
+     * detectCollision('FS-043', registry)  // Returns: null
+     */
+    detectCollision(fsId, registry) {
+        // Exact match
+        if (fsId in registry.entries) {
+            return fsId;
+        }
+        // Extract numeric part
+        const match = fsId.match(/^FS-(\d{3,})E?$/);
+        if (!match) {
+            throw new Error(`Invalid FS-ID format: ${fsId}`);
+        }
+        const number = parseInt(match[1], 10);
+        const internalId = `FS-${String(number).padStart(3, '0')}`;
+        const externalId = `FS-${String(number).padStart(3, '0')}E`;
+        // Check variant
+        if (internalId !== fsId && internalId in registry.entries) {
+            return internalId;
+        }
+        if (externalId !== fsId && externalId in registry.entries) {
+            return externalId;
+        }
+        return null; // No collision
+    }
+    /**
+     * Sleep for specified milliseconds
+     *
+     * @param ms - Milliseconds to sleep
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=id-registry.js.map

package/dist/src/living-docs/id-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-registry.js","sourceRoot":"","sources":["../../../src/living-docs/id-registry.ts"],"names":[],"mappings":"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"}

package/dist/src/progress/us-progress-tracker.d.ts

@@ -0,0 +1,68 @@
+/**
+ * User Story Progress Tracking
+ *
+ * Calculates task completion statistics grouped by User Story.
+ * Provides per-US and aggregate completion percentages.
+ */
+import { type Task, type TasksByUserStory } from '../generators/spec/task-parser.js';
+/**
+ * Progress statistics for a single User Story
+ */
+export interface USProgress {
+    usId: string;
+    totalTasks: number;
+    completedTasks: number;
+    inProgressTasks: number;
+    pendingTasks: number;
+    percentage: number;
+    tasks: Task[];
+}
+/**
+ * Aggregate progress across all User Stories
+ */
+export interface AggregateProgress {
+    totalTasks: number;
+    completedTasks: number;
+    inProgressTasks: number;
+    pendingTasks: number;
+    percentage: number;
+    byUserStory: Map<string, USProgress>;
+    orphanTasks: Task[];
+}
+/**
+ * Calculate task completion statistics for a single User Story
+ */
+export declare function calculateUSProgress(usId: string, tasks: Task[]): USProgress;
+/**
+ * Calculate aggregate progress across all User Stories
+ */
+export declare function calculateAggregateProgress(tasksByUS: TasksByUserStory): AggregateProgress;
+/**
+ * Calculate progress from tasks.md file
+ */
+export declare function calculateProgressFromTasksFile(tasksPath: string): Promise<AggregateProgress>;
+/**
+ * Format US progress as string
+ */
+export declare function formatUSProgress(progress: USProgress, includePercentage?: boolean): string;
+/**
+ * Format aggregate progress as string
+ */
+export declare function formatAggregateProgress(progress: AggregateProgress): string;
+/**
+ * Get progress bar visualization
+ */
+export declare function getProgressBar(percentage: number, width?: number): string;
+/**
+ * Get color indicator based on percentage
+ */
+export declare function getProgressColor(percentage: number): 'green' | 'yellow' | 'red';
+/**
+ * Sort User Stories by completion percentage (descending)
+ */
+export declare function sortUSByCompletion(progressMap: Map<string, USProgress>): USProgress[];
+/**
+ * Sort User Stories by US-ID (ascending)
+ */
+export declare function sortUSByID(progressMap: Map<string, USProgress>): USProgress[];
+//# sourceMappingURL=us-progress-tracker.d.ts.map

package/dist/src/progress/us-progress-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"us-progress-tracker.d.ts","sourceRoot":"","sources":["../../../src/progress/us-progress-tracker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAsC,KAAK,IAAI,EAAE,KAAK,gBAAgB,EAAmB,MAAM,mCAAmC,CAAC;AAE1I;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,WAAW,EAAE,IAAI,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,UAAU,CAmB3E;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,gBAAgB,GAAG,iBAAiB,CA0CzF;AAED;;GAEG;AACH,wBAAsB,8BAA8B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAGlG;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,UAAU,EAAE,iBAAiB,GAAE,OAAc,GAAG,MAAM,CAGhG;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAE3E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,MAAM,CAI7E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAI/E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,UAAU,EAAE,CAErF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,UAAU,EAAE,CAM7E"}

package/dist/src/progress/us-progress-tracker.js

@@ -0,0 +1,120 @@
+/**
+ * User Story Progress Tracking
+ *
+ * Calculates task completion statistics grouped by User Story.
+ * Provides per-US and aggregate completion percentages.
+ */
+import { parseTasksWithUSLinks } from '../generators/spec/task-parser.js';
+/**
+ * Calculate task completion statistics for a single User Story
+ */
+export function calculateUSProgress(usId, tasks) {
+    const totalTasks = tasks.length;
+    const completedTasks = tasks.filter((t) => t.status === 'completed').length;
+    const inProgressTasks = tasks.filter((t) => t.status === 'in_progress').length;
+    const pendingTasks = tasks.filter((t) => t.status === 'pending' || t.status === 'transferred' || t.status === 'canceled').length;
+    const percentage = totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0;
+    return {
+        usId,
+        totalTasks,
+        completedTasks,
+        inProgressTasks,
+        pendingTasks,
+        percentage,
+        tasks,
+    };
+}
+/**
+ * Calculate aggregate progress across all User Stories
+ */
+export function calculateAggregateProgress(tasksByUS) {
+    const byUserStory = new Map();
+    let totalTasks = 0;
+    let completedTasks = 0;
+    let inProgressTasks = 0;
+    let pendingTasks = 0;
+    // Calculate per-US progress
+    for (const [usId, tasks] of Object.entries(tasksByUS)) {
+        if (usId === 'orphan' || usId === 'unknown')
+            continue; // Skip special keys
+        const usProgress = calculateUSProgress(usId, tasks);
+        byUserStory.set(usId, usProgress);
+        totalTasks += usProgress.totalTasks;
+        completedTasks += usProgress.completedTasks;
+        inProgressTasks += usProgress.inProgressTasks;
+        pendingTasks += usProgress.pendingTasks;
+    }
+    // Identify orphan tasks (tasks without userStory field)
+    const orphanTasks = tasksByUS['orphan'] || tasksByUS['unknown'] || [];
+    if (orphanTasks.length > 0) {
+        totalTasks += orphanTasks.length;
+        completedTasks += orphanTasks.filter((t) => t.status === 'completed').length;
+        inProgressTasks += orphanTasks.filter((t) => t.status === 'in_progress').length;
+        pendingTasks += orphanTasks.filter((t) => t.status === 'pending' || t.status === 'transferred' || t.status === 'canceled').length;
+    }
+    const percentage = totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0;
+    return {
+        totalTasks,
+        completedTasks,
+        inProgressTasks,
+        pendingTasks,
+        percentage,
+        byUserStory,
+        orphanTasks,
+    };
+}
+/**
+ * Calculate progress from tasks.md file
+ */
+export async function calculateProgressFromTasksFile(tasksPath) {
+    const tasksByUS = await parseTasksWithUSLinks(tasksPath);
+    return calculateAggregateProgress(tasksByUS);
+}
+/**
+ * Format US progress as string
+ */
+export function formatUSProgress(progress, includePercentage = true) {
+    const percentStr = includePercentage ? ` (${progress.percentage}%)` : '';
+    return `${progress.usId}: ${progress.completedTasks}/${progress.totalTasks} tasks${percentStr}`;
+}
+/**
+ * Format aggregate progress as string
+ */
+export function formatAggregateProgress(progress) {
+    return `Overall: ${progress.completedTasks}/${progress.totalTasks} tasks (${progress.percentage}%)`;
+}
+/**
+ * Get progress bar visualization
+ */
+export function getProgressBar(percentage, width = 20) {
+    const filledChars = Math.round((percentage / 100) * width);
+    const emptyChars = width - filledChars;
+    return '█'.repeat(filledChars) + '░'.repeat(emptyChars);
+}
+/**
+ * Get color indicator based on percentage
+ */
+export function getProgressColor(percentage) {
+    if (percentage >= 80)
+        return 'green';
+    if (percentage >= 50)
+        return 'yellow';
+    return 'red';
+}
+/**
+ * Sort User Stories by completion percentage (descending)
+ */
+export function sortUSByCompletion(progressMap) {
+    return Array.from(progressMap.values()).sort((a, b) => b.percentage - a.percentage);
+}
+/**
+ * Sort User Stories by US-ID (ascending)
+ */
+export function sortUSByID(progressMap) {
+    return Array.from(progressMap.values()).sort((a, b) => {
+        const aNum = parseInt(a.usId.replace('US-', ''));
+        const bNum = parseInt(b.usId.replace('US-', ''));
+        return aNum - bNum;
+    });
+}
+//# sourceMappingURL=us-progress-tracker.js.map

package/dist/src/progress/us-progress-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"us-progress-tracker.js","sourceRoot":"","sources":["../../../src/progress/us-progress-tracker.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "0.22.13",
+  "version": "0.22.14",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",

package/plugins/specweave/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "specweave",
   "description": "SpecWeave framework. Provides increment planning (PM, Architect, Tech Lead agents), specification generation, TDD workflow, living docs sync, and brownfield support. Essential for all SpecWeave projects.",
-  "version": "0.8.0",
+  "version": "0.22.14",
   "author": {
     "name": "SpecWeave Team",
     "url": "https://spec-weave.com"
@@ -18,5 +18,19 @@
     "pm",
     "architect",
     "living-docs"
-  ]
+  ],
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "TodoWrite",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-task-completion.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
 }

package/plugins/specweave/agents/architect/AGENT.md

@@ -885,7 +885,11 @@ Before marking your work complete, verify:
    - Use template: Context → Decision → Consequences
    - Explain WHY not just WHAT
    - Document alternatives considered
-   - Save to `.specweave/docs/internal/architecture/adr/###-decision-title.md`
+   - **CRITICAL**: Save to `.specweave/docs/internal/architecture/adr/XXXX-decision-title.md`
+     - ✅ CORRECT: `0007-github-first-task-sync.md` (4-digit number, kebab-case)
+     - ❌ WRONG: `adr-0007-github-first-task-sync.md` (NO `adr-` prefix!)
+     - ❌ WRONG: `ADR-0007-github-first-task-sync.md` (lowercase filename)
+     - **Why**: The `adr-` prefix is redundant (already in `/adr/` directory)
 
 3. **Design API Contracts**
    - RESTful API design (resources, verbs, status codes)
@@ -945,8 +949,13 @@ High-level description of the system.
 ```
 
 ### ADR Template
+
+**IMPORTANT**: Filename format vs. content header:
+- **Filename**: `XXXX-decision-title.md` (e.g., `0007-github-first-task-sync.md`)
+- **Header**: `# ADR-XXXX: Decision Title` (includes `ADR-` prefix for clarity in document)
+
 ```markdown
-# ADR-###: [Decision Title]
+# ADR-XXXX: [Decision Title]
 
 **Date**: YYYY-MM-DD
 **Status**: [Proposed | Accepted | Deprecated | Superseded]

package/plugins/specweave/agents/test-aware-planner/AGENT.md

@@ -73,17 +73,24 @@ The test-aware-planner agent is responsible for generating `tasks.md` with **emb
 
 ---
 
-## Task Format (NEW - With Embedded Tests)
+## Task Format (NEW - v0.23.0: Hierarchical US-Task Linkage)
+
+**CRITICAL**: v0.23.0+ requires hierarchical structure grouped by User Story.
 
 Each task in `tasks.md` follows this format:
 
 ```markdown
+## User Story: US-001 - User Story Title
+
+**Linked ACs**: AC-US1-01, AC-US1-02, AC-US1-03
+**Tasks**: X total, 0 completed
+
 ### T-001: Implement Feature X
 
-**User Story**: US1
-**Acceptance Criteria**: AC-US1-01, AC-US1-02
-**Priority**: P1
-**Estimate**: 4 hours
+**User Story**: US-001
+**Satisfies ACs**: AC-US1-01, AC-US1-02
+**Priority**: P0 (Critical) | P1 (Important) | P2 (Nice-to-have)
+**Estimated Effort**: 4 hours
 **Status**: [ ] pending
 
 **Test Plan**:
@@ -667,44 +674,88 @@ If TDD mode is enabled (check frontmatter: `test_mode: TDD`), add TDD workflow s
 
 ### Phase 3: File Generation
 
-**Step 3.1: Generate tasks.md Frontmatter**
+**Step 3.1: Generate tasks.md Frontmatter (v0.23.0+)**
 
 ```markdown
 ---
-increment: {increment-id}
 total_tasks: {count}
-completed_tasks: 0
-test_mode: {TDD|standard}
-coverage_target: {percentage}%
+completed: 0
+by_user_story:
+  US-001: {count_for_us1}
+  US-002: {count_for_us2}
+  US-003: {count_for_us3}
+test_mode: {TDD|test-after}
+coverage_target: {percentage}
 ---
 
-# Implementation Tasks
+# Tasks: {Increment Title}
 ```
 
-**Rules:**
-- `increment`: Use increment ID from folder name
+**Rules (v0.23.0+)**:
 - `total_tasks`: Count all generated tasks
-- `completed_tasks`: Always starts at 0
-- `test_mode`: TDD if user requested, standard otherwise
-- `coverage_target`: Overall target (typically 80-90%)
+- `completed`: Always starts at 0
+- `by_user_story`: Map of US-ID → task count (REQUIRED for progress tracking)
+- `test_mode`: TDD or test-after (no "standard")
+- `coverage_target`: Number without % (e.g., 85, not 85%)
 
-**Step 3.2: Assemble All Tasks**
+**Example**:
+```yaml
+---
+total_tasks: 22
+completed: 0
+by_user_story:
+  US-001: 4
+  US-002: 3
+  US-003: 5
+  US-004: 3
+  US-005: 4
+  US-006: 3
+test_mode: test-after
+coverage_target: 90
+---
+```
 
-Combine all generated tasks in sequence:
+**Step 3.2: Assemble All Tasks (v0.23.0+: Hierarchical by User Story)**
+
+**CRITICAL**: Tasks MUST be grouped by User Story with section headers:
 
 ```markdown
-### T-001: [Task 1]
+## User Story: US-001 - User Story Title
+
+**Linked ACs**: AC-US1-01, AC-US1-02, AC-US1-03
+**Tasks**: 4 total, 0 completed
+
+### T-001: [First task for US-001]
+**User Story**: US-001
+**Satisfies ACs**: AC-US1-01, AC-US1-02
 [Full task format from Phase 2]
 
-### T-002: [Task 2]
+### T-002: [Second task for US-001]
+**User Story**: US-001
+**Satisfies ACs**: AC-US1-03
 [Full task format from Phase 2]
 
-...
+---
 
-### T-{N}: [Last task]
+## User Story: US-002 - Another User Story Title
+
+**Linked ACs**: AC-US2-01, AC-US2-02
+**Tasks**: 3 total, 0 completed
+
+### T-003: [First task for US-002]
+**User Story**: US-002
+**Satisfies ACs**: AC-US2-01
 [Full task format from Phase 2]
+
+...
 ```
 
+**Rules**:
+- Group tasks by User Story using `## User Story: US-XXX - Title` headers
+- Each section shows linked ACs and task count
+- Tasks within section MUST link to that User Story
+- Use `---` separator between User Story sections
+
 **Step 3.3: Write tasks.md**
 
 Save the complete file to:
@@ -719,9 +770,14 @@ Save the complete file to:
 
 Before finalizing, validate the generated tasks.md:
 
-**Validation Checklist:**
+**Validation Checklist (v0.23.0+)**:
 
-- [ ] **AC-ID Coverage**: Every AC-ID from spec.md is referenced in at least one task
+- [ ] **AC-ID Coverage**: Every AC-ID from spec.md is referenced in at least one task (100% coverage required)
+- [ ] **US-Task Linkage**: Every task has **User Story** field linking to valid US-ID
+- [ ] **AC Linkage**: Every task has **Satisfies ACs** field with valid AC-IDs
+- [ ] **Hierarchical Structure**: Tasks grouped by User Story with section headers
+- [ ] **by_user_story Map**: Frontmatter includes by_user_story with correct counts
+- [ ] **No Orphan Tasks**: All tasks link to at least one AC
 - [ ] **Task Format**: Each task follows the standard format (header, test plan, test cases, implementation)
 - [ ] **Test Plans**: All testable tasks have Given/When/Then
 - [ ] **Test Cases**: Test file paths follow project conventions
@@ -731,7 +787,7 @@ Before finalizing, validate the generated tasks.md:
 - [ ] **TDD Workflow**: Included if test_mode is TDD
 - [ ] **Estimates**: Realistic (2-8 hours typical per task)
 - [ ] **Dependencies**: Tasks ordered by dependencies
-- [ ] **Frontmatter**: Correct increment ID, task count, test mode
+- [ ] **Frontmatter**: Correct total_tasks, by_user_story map, test_mode, coverage_target
 
 **Validation Script Example:**