specweave 0.22.12 → 0.22.14

package/src/templates/tasks.md.template

@@ -1,4 +1,15 @@
-# Implementation Tasks: {{INCREMENT_TITLE}}
+---
+total_tasks: {{TOTAL_TASKS}}
+completed: 0
+by_user_story:
+  {{#USER_STORIES}}
+  {{US_ID}}: {{TASK_COUNT}}
+  {{/USER_STORIES}}
+test_mode: {{TEST_MODE}}
+coverage_target: {{COVERAGE_TARGET}}
+---
+
+# Tasks: {{INCREMENT_TITLE}}
 
 **Increment**: {{INCREMENT_ID}}
 **Status**: Planning
@@ -6,149 +17,172 @@
 
 ---
 
-## Task Overview
-
-**Total Tasks**: {{TOTAL_TASKS}}
-**Estimated Duration**: {{ESTIMATED_DURATION}}
-**Priority**: {{PRIORITY}}
-
----
-
-## Task Template
+## Task Format (US-Task Linkage - v0.23.0)
 
-Use this template for each task:
+**NEW**: All tasks MUST explicitly link to their parent User Story and Acceptance Criteria.
 
+### Required Fields for Each Task:
 ```markdown
 ### T-XXX: Task Title
-**Priority**: P0 | P1 | P2 | P3
-**Estimate**: X hours
-**Status**: pending | in_progress | completed | blocked
-**AC-IDs**: AC-US-XXX-YY (links to spec.md acceptance criteria)
-**GitHub Issue**: #NNN (auto-populated after sync)
-**Assignee**: @username (optional)
-
-**Description**:
-Brief description of what this task accomplishes.
-
-**Implementation**:
-- [ ] Create/update ClassName with method()
-- [ ] Implement core feature logic
-- [ ] Add error handling for edge cases
-- [ ] Add JSDoc comments
-- [ ] Update related type definitions
 
-**Test Plan** (BDD):
-- **Given** [precondition describing initial state]
-- **When** [action or event that triggers behavior]
-- **Then** [expected result or outcome]
+**User Story**: US-XXX
+**Satisfies ACs**: AC-USXX-YY, AC-USXX-ZZ
+**Status**: [ ] pending | [x] completed | [~] in_progress | [-] canceled
+**Priority**: P0 (Critical) | P1 (Important) | P2 (Nice-to-have) | P3 (Future)
+**Estimated Effort**: X hours | X days
 
-**Test Cases**:
-- Unit (`class-name.test.ts`):
-  - method_withValidInput_returnsExpectedResult
-  - method_withInvalidInput_throwsError
-  - Coverage: >95%
-- Integration (`feature.integration.test.ts`):
-  - fullWorkflow_happyPath_succeeds
-  - Coverage: >85%
+**Description**: What this task accomplishes and why it's needed.
 
-**Files to Create** (if applicable):
-- `path/to/new/file.ts`
-- `path/to/another/file.md`
+**Implementation Steps**:
+1. Create/update file or component
+2. Implement core logic
+3. Add error handling
+4. Add tests
+5. Update documentation
 
-**Files to Modify** (if applicable):
-- `path/to/existing/file.ts`
-- `path/to/another/existing.md`
+**Test Plan**:
+- Unit tests: Specific test cases to write
+- Integration tests: End-to-end scenarios
+- Coverage target: 95% (unit), 85% (integration)
 
-**Code Examples** (optional - snippets for clarity):
-```typescript
-// Example implementation approach
-export function exampleFunction() {
-  // Code here
-}
-```
+**Files Affected**:
+- `path/to/file.ts` (create/modify)
+- `path/to/test.ts` (create)
+
+**Dependencies**: T-XXX (optional - tasks that must complete first)
 ```
 
-**Dependencies** (optional - tasks that must complete first):
-- T-001 (must complete first)
-- T-002 (must complete first)
+### Hierarchical Structure
 
-**Blocks** (optional - tasks waiting on this):
-- T-005 (waiting on this)
-- T-006 (waiting on this)
+Tasks are **grouped by User Story** for traceability:
+
+```markdown
+## User Story: US-001 - User Story Title
+
+**Linked ACs**: AC-US1-01, AC-US1-02, AC-US1-03
+**Tasks**: X total, Y completed
+
+### T-001: First task for this US
+**User Story**: US-001
+**Satisfies ACs**: AC-US1-01, AC-US1-02
+...
+
+### T-002: Second task for this US
+**User Story**: US-001
+**Satisfies ACs**: AC-US1-03
+...
 
 ---
+
+## User Story: US-002 - Another User Story
+
+**Linked ACs**: AC-US2-01, AC-US2-02
+**Tasks**: X total, Y completed
+
+### T-003: First task for US-002
+**User Story**: US-002
+**Satisfies ACs**: AC-US2-01
+...
 ```
 
 ---
 
-## Phase 1: Foundation (Week 1) - X tasks
+{{#USER_STORIES}}
+## User Story: {{US_ID}} - {{US_TITLE}}
 
-### T-001: Example Task
-**Priority**: P0
-**Estimate**: 2 hours
-**Status**: pending
-**AC-IDs**: AC-US1-01, AC-US1-02
-**GitHub Issue**: (will be populated after sync)
-**Assignee**: (assign in GitHub after sync)
+**Linked ACs**: {{AC_IDS}}
+**Tasks**: {{TASK_COUNT}} total, 0 completed
 
-**Description**:
-This is an example task showing the canonical template format following ADR-0047.
+{{#TASKS}}
+### {{TASK_ID}}: {{TASK_TITLE}}
+
+**User Story**: {{US_ID}}
+**Satisfies ACs**: {{SATISFIES_ACS}}
+**Status**: [ ] pending
+**Priority**: {{PRIORITY}}
+**Estimated Effort**: {{ESTIMATE}}
 
-**Implementation**:
-- [ ] Define ExampleInterface with id and name fields
-- [ ] Create ExampleClass implementing ExampleInterface
-- [ ] Add constructor with parameter properties
-- [ ] Add JSDoc comments for interface and class
-- [ ] Export both interface and class
+**Description**: {{DESCRIPTION}}
+
+**Implementation Steps**:
+{{#IMPLEMENTATION_STEPS}}
+- [ ] {{STEP}}
+{{/IMPLEMENTATION_STEPS}}
 
 **Test Plan** (BDD):
-- **Given** ExampleClass constructor receives valid id and name
-- **When** new ExampleClass('123', 'Test') is instantiated
-- **Then** instance has correct id and name properties
+- **Given** {{GIVEN}}
+- **When** {{WHEN}}
+- **Then** {{THEN}}
 
 **Test Cases**:
-- Unit (`example-class.test.ts`):
-  - constructor_withValidParams_createsInstance
-  - constructor_withEmptyId_throwsError
-  - interface_conformsToContract
+- Unit (`{{TEST_FILE}}`):
+  {{#UNIT_TESTS}}
+  - {{TEST_NAME}}
+  {{/UNIT_TESTS}}
   - Coverage: >95%
+{{#HAS_INTEGRATION_TESTS}}
+- Integration (`{{INTEGRATION_TEST_FILE}}`):
+  {{#INTEGRATION_TESTS}}
+  - {{TEST_NAME}}
+  {{/INTEGRATION_TESTS}}
+  - Coverage: >85%
+{{/HAS_INTEGRATION_TESTS}}
+
+**Files Affected**:
+{{#FILES_TO_CREATE}}
+- `{{FILE_PATH}}` (create)
+{{/FILES_TO_CREATE}}
+{{#FILES_TO_MODIFY}}
+- `{{FILE_PATH}}` (modify)
+{{/FILES_TO_MODIFY}}
+
+{{#HAS_DEPENDENCIES}}
+**Dependencies**: {{DEPENDENCIES}}
+{{/HAS_DEPENDENCIES}}
+
+---
+
+{{/TASKS}}
+{{/USER_STORIES}}
 
-**Files to Create**:
-- `src/example/new-file.ts`
-- `tests/unit/example/example-class.test.ts`
+## Validation Rules (v0.23.0)
 
-**Files to Modify**:
-- `src/example/existing-file.ts`
+Before closing this increment, the following MUST be true:
 
-**Code Examples**:
-```typescript
-export interface ExampleInterface {
-  id: string;
-  name: string;
-}
+1. **All tasks completed**: Every task marked `[x] completed`
+2. **All ACs covered**: Every AC-ID from spec.md has at least one task
+3. **No orphan tasks**: Every task has **Satisfies ACs** field
+4. **Valid linkage**: All US-IDs and AC-IDs exist in spec.md
 
-export class ExampleClass implements ExampleInterface {
-  constructor(public id: string, public name: string) {}
-}
+**Validation commands**:
+```bash
+# Check AC coverage and task linkage
+/specweave:validate {{INCREMENT_ID}}
+
+# Close increment (validates automatically)
+/specweave:done {{INCREMENT_ID}}
 ```
 
-**Dependencies**:
-None (foundation task)
+---
+
+## Progress Tracking
 
-**Blocks**:
-- T-003 (needs types from this task)
-- T-004 (needs interfaces from this task)
+**By User Story**:
+{{#USER_STORIES}}
+- {{US_ID}}: 0/{{TASK_COUNT}} tasks completed (0%)
+{{/USER_STORIES}}
+
+**Overall**: 0/{{TOTAL_TASKS}} tasks completed (0%)
 
 ---
 
-## Task Dependencies
+## Task Dependencies (Auto-Generated)
 
 ```mermaid
 graph TD
-    T001[T-001: Example Task] --> T003[T-003: Dependent Task]
-    T001 --> T004[T-004: Another Dependent]
-    T002[T-002: Another Foundation] --> T003
-    T003 --> T005[T-005: Higher Level Task]
+{{#TASK_DEPENDENCIES}}
+    {{FROM_TASK}}[{{FROM_TASK_TITLE}}] --> {{TO_TASK}}[{{TO_TASK_TITLE}}]
+{{/TASK_DEPENDENCIES}}
 ```
 
 ---
@@ -156,124 +190,69 @@ graph TD
 ## Testing Checklist
 
 **Unit Tests** (per component):
-- ✅ Component A
-- ✅ Component B
-- ✅ Component C
+{{#COMPONENTS}}
+- [ ] {{COMPONENT_NAME}}
+{{/COMPONENTS}}
 
 **Integration Tests**:
-- ✅ Full workflow (end-to-end)
-- ✅ Error handling
-- ✅ Edge cases
+- [ ] Full workflow (end-to-end)
+- [ ] Error handling
+- [ ] Edge cases
 
 **E2E Tests** (if applicable):
-- ✅ User workflow A
-- ✅ User workflow B
-
-**Performance Tests** (if applicable):
-- ✅ Load testing
-- ✅ Stress testing
-
----
-
-## Rollout Plan
-
-### Week 1: Foundation
-- Days 1-2: Tasks T-001 to T-003
-- Days 3-5: Tasks T-004 to T-006
-
-### Week 2: Core Implementation
-- Days 1-3: Tasks T-007 to T-010
-- Days 4-5: Tasks T-011 to T-012
-
-### Week 3: Integration & Testing
-- Days 1-2: Tasks T-013 to T-014
-- Days 3-5: Comprehensive testing and polish
+{{#E2E_TESTS}}
+- [ ] {{E2E_TEST_NAME}}
+{{/E2E_TESTS}}
 
 ---
 
 ## Success Criteria
 
-**Must Have**:
-- ✅ All tasks completed
-- ✅ All tests passing
-- ✅ Documentation updated
-- ✅ Code review approved
+**Must Have** (P0/P1):
+- [ ] All critical and important tasks completed
+- [ ] All tests passing (unit, integration, E2E)
+- [ ] 100% AC coverage validated
+- [ ] Documentation updated (CLAUDE.md, README.md)
+- [ ] Code review approved
 
-**Nice to Have** (for next increment):
-- Future enhancement 1
-- Future enhancement 2
+**Nice to Have** (P2/P3 - can defer):
+{{#NICE_TO_HAVE}}
+- [ ] {{FEATURE}}
+{{/NICE_TO_HAVE}}
 
 ---
 
-## GitHub Sync Instructions
-
-### Initial Sync
-
-After creating this tasks.md file, sync to GitHub:
-
-```bash
-# Sync all tasks to GitHub (creates epic + task issues)
-/specweave.github.sync-tasks {{INCREMENT_ID}}
-```
-
-This will:
-1. Create a GitHub Milestone (e.g., v0.4.0)
-2. Create an Epic Issue for the increment
-3. Create individual GitHub Issues for each task
-4. Link task issues to epic
-5. Update this file with GitHub issue numbers
-6. Store mapping in `.github-sync.yaml`
-
-### During Development
+## Rollout Plan
 
-As you work on tasks:
-- `/specweave.do` - Completes next task AND closes GitHub issue
-- Progress automatically syncs to epic issue
-- Subtasks sync as checkboxes in GitHub
+### Week 1: Foundation
+{{#WEEK_1_TASKS}}
+- Days {{DAYS}}: Tasks {{TASK_RANGE}}
+{{/WEEK_1_TASKS}}
 
-### Manual Operations
+### Week 2: Core Implementation
+{{#WEEK_2_TASKS}}
+- Days {{DAYS}}: Tasks {{TASK_RANGE}}
+{{/WEEK_2_TASKS}}
 
-```bash
-# Force re-sync (if drift detected)
-/specweave.github.sync-tasks {{INCREMENT_ID}} --force
+### Week 3: Integration & Testing
+{{#WEEK_3_TASKS}}
+- Days {{DAYS}}: Tasks {{TASK_RANGE}}
+{{/WEEK_3_TASKS}}
 
-# Check sync status
-/specweave.github.status {{INCREMENT_ID}}
+---
 
-# Manually create issue for specific task
-/specweave.github.create-issue {{INCREMENT_ID}} T-001
-```
+## Notes
 
----
+**Important**:
+- This tasks.md uses **hierarchical structure grouped by User Story** (v0.23.0+)
+- All tasks MUST link to parent US and ACs for traceability
+- Validation enforces 100% AC coverage before increment closure
+- Living docs sync automatically based on task-AC linkage
 
-## Field Reference
-
-### Required Fields
-- **Priority**: P0 (critical), P1 (high), P2 (medium), P3 (low)
-- **Estimate**: Hours or days (e.g., "2 hours", "3 days")
-- **Status**: pending, in_progress, completed, blocked
-- **AC-IDs**: Links to spec.md acceptance criteria (e.g., "AC-US1-01, AC-US1-02")
-- **Description**: What this task accomplishes
-- **Implementation**: Checkable technical steps to complete the task
-- **Test Plan (BDD)**: Given-When-Then test scenarios
-- **Test Cases**: Unit and integration test cases with coverage targets
-
-### Optional Fields (Enhanced for GitHub Sync)
-- **GitHub Issue**: Auto-populated after `/specweave.github.sync-tasks`
-- **Assignee**: GitHub username (assign in GitHub UI or via `@username`)
-- **Dependencies**: Tasks that must complete first (linked in GitHub via "depends on")
-- **Blocks**: Tasks waiting on this one (linked in GitHub via "blocks")
-- **Files to Create/Modify**: Context for reviewers and developers
-- **Code Examples**: Snippets showing implementation approach (TypeScript, pseudocode, etc.)
-
-### Task Status Lifecycle
-1. **pending** - Not started, in backlog
-2. **in_progress** - Currently being worked on
-3. **blocked** - Cannot proceed (dependency, blocker)
-4. **completed** - Done, tests passing, reviewed
+**See**: `CLAUDE.md` section "Task Format with US-Task Linkage" for detailed guide
 
 ---
 
-**Version**: 1.0
+**Version**: 2.0 (US-Task Linkage)
 **Last Updated**: {{LAST_UPDATED}}
 **Total Estimate**: {{TOTAL_HOURS}} hours ({{TOTAL_WEEKS}} weeks)