@haaaiawd/anws 2.2.6 → 2.4.0

package/templates_en/.agents/skills/task-planner/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: task-planner
+description: Use WBS to decompose system design into an execution list (05A_TASKS.md) and a verification plan (05B_VERIFICATION_PLAN.md), with dependency analysis, traceability, and evidence ownership.
+---
+
+# Task Planner
+
+You are the task decomposition and verification orchestration skill.
+
+Outputs:
+- `.anws/v{N}/05A_TASKS.md` (execution list)
+- `.anws/v{N}/05B_VERIFICATION_PLAN.md` (verification plan)
+
+---
+
+## Fast Flow
+
+1. Read `01_PRD.md` and `02_ARCHITECTURE_OVERVIEW.md`.
+2. Read `03_ADR/` and `04_SYSTEM_DESIGN/` when available.
+3. If ADR provides testing strategy or quality gates, follow them first.
+4. Extract public contracts (HTTP API, CLI, config, format, error semantics, persistence, cross-system interfaces).
+5. Generate WBS tasks to 05A.
+6. Generate verification anchors and evidence ownership to 05B.
+
+---
+
+## Split Responsibilities
+
+### 05A_TASKS.md (Execution Track)
+
+- WBS task definitions
+- dependencies and estimates
+- sprint roadmap
+- INT milestone tasks
+- progress checkboxes
+- User Story Overlay
+
+### 05B_VERIFICATION_PLAN.md (Verification Track)
+
+- verification layering strategy
+- risk-category coverage rules
+- Task-by-Task verification plan
+- Contract Coverage Overlay
+- Testing Coverage Overlay
+- Verification Traceability Matrix
+
+> [!IMPORTANT]
+> The following three sections are mandatory in 05B and must not be removed:
+> - Contract Coverage Overlay
+> - Testing Coverage Overlay
+> - Verification Traceability Matrix
+
+---
+
+## 05A Task Structure
+
+```markdown
+- [ ] **T{System}.{Phase}.{Seq}** [REQ-XXX]: Task title
+  - **Description**: what to build (not how)
+  - **Input**: design references + predecessor outputs (must include at least one design document reference)
+  - **Output**: files/components/interfaces/artifacts
+  - **Contract Ownership**: public contract implemented or verified by this task, or "None"
+  - **Reference**: ADR/System Design section if applicable
+  - **Acceptance Criteria**:
+    - Given ...
+    - When ...
+    - Then ...
+    - (Clear Done When is allowed only for pure technical foundation tasks)
+  - **Verification Type**: Unit Test | API Interface Functional Test | Integration Test | E2E Test | Smoke Test | Regression Test | Manual Verification | Build Check | Lint Check
+  - **Verification Summary**: verification scope and boundary only
+  - **Verification Reference**: `05B_VERIFICATION_PLAN.md#t-x-y-z`
+  - **Evidence Output**: `tests/...`, `reports/...`, `screenshots/...`, `logs/...`
+  - **Estimate**: Xh
+  - **Dependencies**: T{A}.{B}.{C}
+  - **Priority**: P0 | P1 | P2
+```
+
+---
+
+## 05B Verification Structure
+
+### Task-by-Task Entry
+
+```markdown
+### T{X}.{Y}.{Z}
+- Related Requirement:
+- Related Contract:
+- Risk Category:
+- Unit Test Coverage:
+- API Interface Functional Test Coverage:
+- Integration/E2E/Smoke Coverage:
+- Preconditions/Test Data:
+- Assertions:
+- Evidence:
+```
+
+### Traceability Matrix
+
+```markdown
+## Verification Traceability Matrix
+| REQ/Contract | Task | Verification | Test Material | Evidence | Status |
+|---|---|---|---|---|---|
+```
+
+---
+
+## Verification Type Selection Logic
+
+Follow the "lightest sufficient proof" principle:
+
+1. Local logic / pure algorithm / state transition / exception handling -> Unit Test
+2. HTTP API / CLI API / permission boundary / error semantics / data-changing endpoint -> API Interface Functional Test
+3. Cross-module or cross-service collaboration -> Integration Test
+4. Critical end-user journey -> E2E Test or Manual Verification
+5. Sprint milestone gate -> Smoke Test (prefer binding to `INT-S{N}`)
+6. Changes that may impact existing critical behavior -> Regression Test
+7. Config or scaffolding tasks -> Build Check / Lint Check / Manual Verification
+
+Selection rules:
+- do not upgrade to E2E by default
+- for public API changes, verification must include normal and representative invalid request paths
+- data-changing endpoints must include before/after assertions
+- auth/role/permission changes must include permission-denied scenarios
+
+### E2E Execution Boundary (Hard Rule)
+
+- `task-planner` only records E2E trigger assumptions, coverage scope, and expected evidence in `05A_TASKS.md` / `05B_VERIFICATION_PLAN.md`
+- planning phase must not call or execute `e2e-testing-guide`
+- actual E2E guide generation and real-browser validation are executed by `/forge` when triggered by tasks
+
+---
+
+## Hard Testing Constraints
+
+> [!IMPORTANT]
+> Project acceptance must include both Unit Tests and API Interface Functional Tests.
+
+### Unit Test Responsibilities
+
+- normal, boundary, and invalid input
+- critical state transitions (create, execute, fail, retry style)
+- exception handling (null, out-of-range, invalid state) with stable behavior
+
+### API Interface Functional Test Responsibilities
+
+- normal request path
+- missing parameter, malformed parameter, and permission-denied scenarios
+- expected error code and error message semantics
+- before/after assertions for data-changing interfaces
+
+### Anti-Bloat Policy
+
+- close risk categories, do not maximize raw test counts
+- prefer equivalence classes, boundary values, representative invalid samples, parameterized or table-driven tests
+- avoid full Cartesian-product enumeration
+- keep E2E focused on key user chains
+
+---
+
+## Contract Coverage Rules
+
+> [!IMPORTANT]
+> If task outputs include or modify public contracts, explicit verification ownership is mandatory.
+
+Public contract coverage is mandatory whenever tasks create or modify externally observable behavior.
+
+Rules:
+- each public contract needs at least one implementation owner task
+- each high-risk public contract needs at least one verification owner point
+- implementation-only is not contract closure
+- foundational low-dependency logic defaults to Unit Test ownership
+- external interfaces (HTTP API / CLI API) default to explicit API Interface Functional Test evaluation
+- error semantics and before/after data state are observable contract parts and cannot be skipped
+
+---
+
+## WBS Method
+
+### Three Levels
+
+```text
+Level 1: System  <- system list from Architecture Overview
+Level 2: Phase   <- Foundation / Core / Integration / Polish
+Level 3: Task    <- concrete tasks, typically 2h-2d granularity
+```
+
+### Sprint Roadmap Format
+
+```markdown
+## Sprint Roadmap
+
+| Sprint | Codename | Core Work | Exit Criteria | Estimate |
+|--------|----------|-----------|---------------|----------|
+| S1     | Hello World | Infrastructure + core data | headless run passes + basic rendering visible | 3-4d |
+```
+
+Exit criteria requirements:
+- objectively verifiable (screenshots / recordings / logs)
+- describe observable behavior for users or developers
+- include cross-system integration signals
+
+### Integration Verification Task (`INT-S{N}`)
+
+```markdown
+- [ ] **INT-S{N}** [MILESTONE]: S{N} integration verification — {codename}
+  - **Description**: verify S{N} exit criteria
+  - **Input**: outputs from all S{N} tasks
+  - **Output**: integration verification report (pass/fail + bug list)
+  - **Acceptance Criteria**:
+    - Given all S{N} tasks are completed
+    - When each exit criterion check is executed
+    - Then all pass -> sprint closes; any failure -> bug is recorded
+  - **Verification Notes**: execute checks item by item against exit criteria, confirm with screenshots/recordings/logs
+  - **Estimate**: 2-4h
+  - **Dependencies**: last task in S{N}
+```
+
+`INT` is the sprint closing gate. A sprint must not be marked complete before its `INT` task passes.
+
+---
+
+## Task Quality Rules
+
+### Granularity
+
+- keep single tasks in the 2h-2d range when possible; split further when over 2d
+- merge tiny tasks when they are below roughly 2h
+
+### Input/Output Traceability
+
+> [!IMPORTANT]
+> Task inputs and outputs must align.
+>
+> If Task B depends on Task A, Task B input must reference concrete artifacts from Task A output (file path, interface name, or data format).
+
+### Acceptance Criteria
+
+- default to Given / When / Then
+- clear Done When lists are allowed only for pure technical foundation work (config / scaffolding)
+
+---
+
+## Output Quality Checklist
+
+- both 05A and 05B generated
+- every 05A task includes `Verification Reference` and `Evidence Output`
+- 05B includes Task-by-Task plan and traceability matrix
+- User Story Overlay is in 05A
+- Contract Coverage Overlay, Testing Coverage Overlay, and Verification Traceability Matrix are in 05B
+- smoke checks are centered on `INT-S{N}`
+- no E2E abuse pattern

package/templates_en/.agents/skills/task-planner/references/TASK_TEMPLATE_05A.md

@@ -0,0 +1,109 @@
+# 05A_TASKS.md Template Reference
+
+> This file is the format reference for `05A_TASKS.md`.
+> `05A` is execution-only and must not carry detailed verification design.
+> Detailed verification planning belongs to `05B_VERIFICATION_PLAN.md`.
+
+---
+
+## Document Header
+
+```markdown
+# 05A_TASKS.md - Execution Task List
+
+> Version: v{N}
+> Generated by: /blueprint
+> Last updated: {Today}
+>
+> Verification plan: 05B_VERIFICATION_PLAN.md (every task links through Verification Reference)
+```
+
+---
+
+## Dependency Overview
+
+```markdown
+## Dependency Overview
+
+\`\`\`mermaid
+graph TD
+    T1.1.1[Project setup] --> T2.1.1[Implement core logic]
+    T2.1.1 --> T2.1.2[Implement API endpoint]
+    T3.1.1[Database schema] --> T2.1.1
+    T2.1.2 --> T1.2.1[Frontend integration]
+\`\`\`
+
+```
+
+---
+
+## Sprint Roadmap
+
+```markdown
+## Sprint Roadmap
+
+| Sprint | Codename | Core Tasks | Exit Criteria | Estimate |
+|--------|----------|------------|---------------|----------|
+| S1 | Hello World | foundation + core data | headless run succeeds + visible baseline behavior | 3-4d |
+| S2 | Feature Shape | core business + APIs | complete flow is demoable | 5-6d |
+```
+
+---
+
+## Task Structure
+
+```markdown
+- [ ] **T{System}.{Phase}.{Seq}** [REQ-XXX]: Task title
+  - **Description**: what to do (not how)
+  - **Input**: design references + predecessor outputs (must include at least one design-doc reference)
+  - **Output**: files/components/interfaces/artifacts
+  - **Contract Ownership**: contract implemented/verified by this task, or "None"
+  - **Reference**: ADR / System Design section (if applicable)
+  - **Acceptance Criteria**:
+    - Given ...
+    - When ...
+    - Then ...
+    - (Done When only for pure technical foundation tasks)
+  - **Verification Type**: Unit Test | API Interface Functional Test | Integration Test | E2E Test | Smoke Test | Regression Test | Manual Verification | Build Check | Lint Check
+  - **E2E Trigger Assumption**: if E2E is needed, define trigger conditions and key user journey (planning placeholder only; no E2E execution in blueprint/planner stage)
+  - **Verification Summary**: objective and boundary only
+  - **Verification Reference**: `05B_VERIFICATION_PLAN.md#t-x-y-z`
+  - **Evidence Output**: `tests/...`, `reports/...`, `logs/...`, `screenshots/...`
+  - **Estimate**: Xh
+  - **Dependencies**: T{A}.{B}.{C}
+  - **Priority**: P0 | P1 | P2
+```
+
+---
+
+## INT Milestone Task Format
+
+```markdown
+- [ ] **INT-S{N}** [MILESTONE]: S{N} integration validation - {codename}
+  - **Description**: verify sprint exit criteria and cross-system collaboration
+  - **Input**: outputs of all S{N} tasks
+  - **Output**: integration report (pass/fail + bug list)
+  - **Acceptance Criteria**:
+    - Given all S{N} tasks are complete
+    - When every exit-criteria check is executed
+    - Then all pass -> sprint complete; failures -> bugs recorded
+  - **Verification Type**: Integration Test / Smoke Test
+  - **Verification Notes**: run checks one by one, keep logs/screenshots, add minimal regression checks if needed
+  - **Estimate**: 2-4h
+  - **Dependencies**: all S{N} tasks
+```
+
+---
+
+## User Story Overlay (append near end)
+
+```markdown
+## User Story Overlay
+
+### US-001: [Title] (P0)
+**Tasks**: T1.1.1 -> T1.2.1 -> T2.1.1
+**Critical Path**: T1.1.1 -> T1.2.1
+**Independently Testable**: Demoable by end of S1
+**Coverage Status**: Complete
+```
+

package/templates_en/.agents/skills/task-planner/references/TASK_TEMPLATE_05B.md

@@ -0,0 +1,176 @@
+# 05B_VERIFICATION_PLAN.md Template Reference
+
+> This file is the format reference for `05B_VERIFICATION_PLAN.md`.
+> `05B` is verification-only and must not include execution-track task ownership.
+> The execution track belongs to `05A_TASKS.md`.
+
+---
+
+## Document Header
+
+```markdown
+# 05B_VERIFICATION_PLAN.md - Verification Plan
+
+> Version: v{N}
+> Generated by: /blueprint
+> Last updated: {Today}
+>
+> Execution list: 05A_TASKS.md (each verification entry maps to a task ID)
+```
+
+---
+
+## Section Structure Overview
+
+```text
+1. Scope and Goal
+2. Verification Layering Strategy
+3. Risk Category Coverage Principles
+4. Test Material and Evidence Requirements
+5. Task-by-Task Verification Plan
+6. Contract Coverage Overlay
+7. Testing Coverage Overlay
+8. Verification Traceability Matrix
+```
+
+> [!IMPORTANT]
+> Sections 6/7/8 are mandatory and must not be deleted or merged away:
+>
+> - Contract Coverage Overlay (who implements and who verifies each contract)
+> - Testing Coverage Overlay (which test method closes which risk category)
+> - Verification Traceability Matrix (auditable chain: REQ/Contract -> Task -> Verification -> Evidence)
+
+---
+
+## Sections 1-4: Strategy Format
+
+```markdown
+## 1. Scope and Goal
+
+This plan covers all P0/P1 tasks in v{N}, and ensures:
+- correctness, stability, and robustness of core functionality, critical logic, and exception handling
+- project acceptance includes both Unit Test and API Interface Functional Test
+
+## 2. Verification Layering Strategy
+
+| Layer | Responsibility | Typical Tooling |
+|------|----------------|-----------------|
+| Unit Test | local logic, state transitions, exception paths | Jest / pytest / go test |
+| API Interface Functional Test | HTTP API contracts, error semantics, data-changing behaviors | Postman / httpie / pytest |
+| Integration Test | cross-module/cross-service collaboration | integration frameworks |
+| E2E Test | key end-user journeys | Playwright / Cypress |
+| Smoke Test | sprint exit gate key paths | executed with INT-S{N} |
+| Regression Test | ensure changes do not break completed critical capability | reuse targeted existing suites |
+
+## 3. Risk Category Coverage Principles
+
+- close risk categories, do not maximize test count
+- prefer equivalence classes, boundary values, representative negative samples
+- avoid Cartesian-product enumeration across all fields/parameters
+- Unit Test owns fine-grained logic, API Interface Functional Test owns external contracts, E2E stays on key user journeys only
+
+## 4. Test Material and Evidence Requirements
+
+| Verification Type | Test Material Location | Evidence Form |
+|------------------|------------------------|---------------|
+| Unit Test | `tests/unit/` | test run report / CI logs |
+| API Interface Functional Test | `tests/api/` | HTTP response records / test reports |
+| Integration Test | `tests/integration/` | integration reports |
+| E2E Test | `tests/e2e/` | screenshots / recordings |
+| Smoke Test | bound to INT-S{N} | key-path screenshots / logs |
+```
+
+---
+
+## Section 5: Task-by-Task Verification Format
+
+Every task in 05A should map to one detailed verification entry here:
+
+```markdown
+## 5. Task-by-Task Verification Plan
+
+### T1.2.1
+- **Related Requirement**: REQ-001 (User Login)
+- **Related Contract**: `POST /auth/login` HTTP API contract
+- **Risk Category**: API contract / auth logic / error semantics
+- **Unit Test Coverage**:
+  - JWT signing: valid input returns valid token (normal)
+  - JWT signing: empty secret throws ConfigurationError (exception path)
+  - password compare: hash-match true, mismatch false (boundary)
+- **API Interface Functional Test Coverage**:
+  - normal request: valid username + password -> 200 + JWT token
+  - missing parameter: no `password` in body -> 400 + `MISSING_PARAM`
+  - malformed parameter: empty `username` -> 400 + `INVALID_PARAM`
+  - permission denied: invalid credential -> 401 + `INVALID_CREDENTIALS`
+  - before/after state: N/A for login endpoint (no data mutation)
+- **Integration/E2E/Smoke Coverage**: bind to INT-S1 smoke check for end-to-end login usability
+- **Preconditions/Test Data**: test user `user@test.com` exists in DB with hashed password
+- **Assertions**:
+  - 200 response body contains `token` field in valid JWT format
+  - 401 response body contains `error.code === "INVALID_CREDENTIALS"`
+  - 400 response body contains expected `error.code` for each invalid case
+- **Evidence**: `tests/unit/jwt.test.ts`, `tests/api/auth.test.ts`, CI report
+
+### INT-S1
+- **Related Requirement**: S1 exit criteria
+- **Related Contract**: public contracts completed in S1
+- **Risk Category**: system availability / sprint gate
+- **Unit Test Coverage**: N/A (INT does not add new unit tests)
+- **API Interface Functional Test Coverage**: N/A
+- **Integration/E2E/Smoke Coverage**: execute sprint exit checks as smoke tests
+- **Preconditions/Test Data**: all S1 tasks completed with usable outputs
+- **Assertions**: each observable behavior in exit criteria passes
+- **Evidence**: screenshots / recordings / integration report
+```
+
+---
+
+## Section 6: Contract Coverage Overlay Format
+
+> Mandatory. Must not be removed.
+
+```markdown
+## 6. Contract Coverage Overlay
+
+| Contract | Type | Implementation Owner | Verification Owner | Status |
+|----------|------|----------------------|--------------------|:------:|
+| `POST /auth/login` HTTP API | HTTP API | T1.2.1 | T1.2.1 API Interface Functional Test | ⬜ |
+| JWT token signing semantics | operation contract | T1.2.1 | T1.2.1 Unit Test | ⬜ |
+| `INVALID_CREDENTIALS` error semantics | error semantics | T1.2.1 | T1.2.1 API Interface Functional Test | ⬜ |
+| users table persistence structure | persistence structure | T3.1.1 | T3.1.1 Integration Test | ⬜ |
+```
+
+---
+
+## Section 7: Testing Coverage Overlay Format
+
+> Mandatory. Must not be removed.
+
+```markdown
+## 7. Testing Coverage Overlay
+
+| Test Responsibility | Risk Category | Coverage Method | Task Owner | Test Material | Status |
+|--------------------|---------------|-----------------|------------|---------------|:------:|
+| JWT signing: normal/boundary/exception | business logic | Unit Test + parameterized cases | T1.2.1 | `tests/unit/jwt.test.ts` | ⬜ |
+| `POST /auth/login` missing/malformed/permission-denied | API contract | API Interface Functional Test + representative invalid samples | T1.2.1 | `tests/api/auth.test.ts` | ⬜ |
+| user state active/inactive/locked | state transition | Unit Test + table-driven state cases | T1.2.2 | `tests/unit/user.test.ts` | ⬜ |
+| password change endpoint before/after consistency | data consistency | API Interface Functional Test + before/after assertions | T1.2.3 | `tests/api/password.test.ts` | ⬜ |
+```
+
+---
+
+## Section 8: Verification Traceability Matrix Format
+
+> Mandatory. Must not be removed.
+
+```markdown
+## 8. Verification Traceability Matrix
+
+| REQ/Contract | Task | Verification | Test Material | Evidence | Status |
+|---|---|---|---|---|---|
+| REQ-001 User Login | T1.2.1 | Unit Test + API Interface Functional Test | `tests/unit/jwt.test.ts`, `tests/api/auth.test.ts` | CI report | ⬜ |
+| `POST /auth/login` contract | T1.2.1 | API Interface Functional Test | `tests/api/auth.test.ts` | HTTP response records | ⬜ |
+| users table persistence structure | T3.1.1 | Integration Test | `tests/integration/db.test.ts` | integration report | ⬜ |
+| S1 exit criteria | INT-S1 | Smoke Test | sprint smoke scripts | screenshots / verification report | ⬜ |
+```
+