Initial commit

skills/ln-320-story-validator/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: ln-320-story-validator
+description: Reviews Stories/Tasks against 2025 standards before approval (Backlog -> Todo). Auto-fixes issues, validates structure, optimizes via YAGNI/KISS/SOLID. Auto-discovers team/config.
+---
+
+# Story Verification Skill
+
+Critically review and auto-fix Stories and Tasks against 2025 standards and project architecture before execution.
+
+## Purpose & Scope
+
+- Validate Story plus child Tasks against industry standards and project patterns
+- Auto-fix detected issues (structure, solution, workflow, quality) before approval
+- Approve Story after fixes (Backlog -> Todo) and link any missing guides
+- Strip or re-home Non-Functional Requirements; keep only functional scope in Story/Tasks
+
+## When to Use
+
+- Reviewing Stories before approval (Backlog -> Todo)
+- Validating implementation path across Story and Tasks
+- Ensuring standards, architecture, and solution fit
+- Optimizing or correcting proposed approaches
+
+## Workflow Overview
+
+### Phase 1: Discovery & Loading
+- Auto-discover configuration: Team ID (docs/tasks/kanban_board.md), project docs (CLAUDE.md), epic from Story.project
+- Load metadata only: Story ID/title/status/labels, child Task IDs/titles/status/labels
+- Expect 3-8 implementation tasks; record parentId for filtering
+- Rationale: keep loading light; full descriptions arrive in Phase 2
+
+### Phase 2: Critical Solution Review
+- Load full Story description (all 8 sections) when analysis starts
+- Standards first (priority): Industry/RFCs -> Security -> 2025 best practices -> KISS/YAGNI/DRY within standards
+- Challenge approach: prefer proven standards over custom work; keep language as-is (EN/RU)
+- Documentation check and creation triggers (pattern keywords, package versions, technology choices); invoke ln-321-guide-creator / ln-323-manual-creator / ln-322-adr-creator if missing
+- Verify against codebase reality before edits; if Story is outdated, auto-correct via Linear update
+- Reporting rule: when principles are violated, explain why with best-practice references and propose concrete fixes, not just list names
+
+### Phase 3: Comprehensive Auto-Fix
+- Always auto-fix; no "Needs Work" path. Follow execution order: Structural (1-4) -> Solution (5-8) -> Workflow (9-12) -> Scope & Quality (13-16)
+- Use Auto-Fix Actions table below as the authoritative checklist; keep sequential task validation to avoid truncation
+- Test mention: ensure Test Strategy section exists but keep it empty here; do not plan coverage or execution at this stage
+
+### Phase 4: Approve & Notify
+- Set Story + all Tasks to Todo (Linear); update kanban_board.md with APPROVED marker and move items from Backlog to Todo keeping hierarchy
+- Add Linear comment summarizing fixes, created docs (paths), ADRs/manuals/guides, and any TODO warnings
+- Verification summary display: Story verdict (always Approved -> Todo), changes, linked docs, warnings; Tasks table with changes and guide links
+- Any principle violations in reports must include rationale, best-practice reference, and recommended remediation steps
+
+## Auto-Fix Actions Reference
+
+| # | What it checks | Auto-fix actions | Notes/Evidence |
+|---|----------------|------------------|----------------|
+|1 Story Structure|8 sections per story_template_universal.md in order|Add/reorder sections and subsections with TODO placeholders; update Linear; preserve language|Skip if Done/Canceled or older than 30 days|
+|2 Tasks Structure|Each Task has 7 sections in order|Load each Task full description sequentially; add/reorder sections with placeholders; update Linear and comment; preserve language|Sequential per task; skip if Done/Canceled or older than 30 days|
+|3 Story Statement|As a/I want/So that clarity|Rewrite using persona (Context), capability (Technical Notes), value (Success Metrics); update Linear and comment|-|
+|4 Acceptance Criteria|Given/When/Then, 3-5 items, edge/error coverage|Normalize AC to G/W/T; add missing edge/error cases; update Linear and comment|-|
+|5 Solution Optimization|2025-best approach aligned with prior patterns|Rewrite Technical Notes and Tasks if better approach exists; cite modern patterns/libs; reference prior Story context; add TODO for duplicates/conflicts|Log rationale in Linear|
+|6 Library & Version|Current stable versions; prefer built-ins|Update versions in Technical Notes/Tasks; replace custom helpers with built-ins; update Linear and comment|List versions checked|
+|7 Test Strategy|Section exists but remains empty now|Ensure Test Strategy section present; leave empty with note that testing is planned later by ln-350; do not add coverage details|Mention "testing handled later; not evaluated in this phase"|
+|8 Documentation Integration|No standalone doc tasks|Remove doc-only tasks; fold doc updates into implementation tasks and DoD; update Linear and comment|-|
+|9 Story Size & Granularity|3-8 tasks; 3-5h each|If <3 tasks invoke ln-310-story-decomposer; if >8 add TODO to split; flag tasks <3h or >8h with TODO; reload metadata and update kanban_board.md|Comment creation source|
+|10 Test Task Cleanup|No premature test tasks|Cancel/remove tasks labeled as tests or named test/comprehensive/final; remove from Story/kanban; comment that testing tasks appear later|Testing not executed now|
+|11 YAGNI|No premature features|Move speculative items to Out of Scope/Future; update Technical Notes/Tasks; comment rationale|-|
+|12 KISS|Simplest solution within standards|Replace over-engineered parts with simpler options unless standards require otherwise; update Linear with reasoning|Standard overrides simplicity|
+|13 Documentation Links|Technical Notes reference docs|Add "Related Documentation" subsection; link guides/manuals/ADRs by path; update Linear|Use created/existing paths|
+|14 Foundation-First Order|Task order DB -> Repo -> Service -> API -> Frontend|Reorder Implementation Tasks and note execution order; update Linear and comment|-|
+|15 Code Quality Basics|No magic values; config approach defined|Add TODOs for constants/config/env creds; describe config management in Technical Notes; update Linear|Warn in summary if TODOs remain|
+|16 Industry Standards|Compliance with RFCs/protocols|Check docs in guides/manuals/ADRs; if missing invoke creators; document compliance and links; if none apply, state explicit reason; update Linear|Evidence required: doc path or worker call; log skip reason if applicable|
+
+## Self-Audit Protocol (Mandatory)
+
+- Before marking any criterion, answer its Self-Audit question, provide concrete evidence (doc path, Linear comment link, worker result), and record in `checkpoints/{STORY_ID}_verification_log.md`. No evidence -> no completion.
+
+| # | Self-Audit Question | Required Evidence |
+|---|---------------------|-------------------|
+|1|Validated all 8 Story sections in order?|Section list|
+|2|Loaded full description for each Task?|Task validation count|
+|3|Statement in As a/I want/So that?|Quoted statement|
+|4|AC are G/W/T and testable?|AC count and format|
+|5|Challenged "best for 2025"?|Reasoning logged|
+|6|All versions current stable?|Version list checked|
+|7|Test Strategy kept empty for now?|Note that testing is deferred|
+|8|Docs integrated, no standalone tasks?|Integration evidence|
+|9|Task count 3-8 and 3-5h?|Task count/sizes|
+|10|No premature test tasks?|Search result|
+|11|Only current-scope features?|Scope review|
+|12|Simplest approach within standards?|Simplicity justification|
+|13|All relevant guides linked?|Guide paths|
+|14|Tasks ordered DB->Repo->Service->API?|Task order list|
+|15|Hardcoded values handled?|TODO/config evidence|
+|16|Standards verified via docs/worker?|Doc path or worker result|
+
+## Definition of Done
+
+- Verification log created from template with answered Self-Audit for all 16 criteria and evidence
+- Phase 1: auto-discovery done; Story + Tasks metadata loaded; task count checked
+- Phase 2: full Story parsed; standards researched; doc gaps filled via creators; codebase reality verified; reports explain violations with best-practice references and fixes
+- Phase 3: criteria 1-16 auto-fixed in order; Test Strategy section present but empty; test tasks removed; guide links inserted
+- Phase 4: Story/Tasks set to Todo; kanban_board.md updated with APPROVED marker and hierarchy; Linear comment added with fixes, docs, ADRs/manuals/guides, TODO warnings; summary table shown
+
+## Example Workflows
+
+- **Outdated library:** Detect old version, update to current stable in Technical Notes/Tasks, document change, approve.
+- **OAuth violation:** Replace custom endpoints with RFC-compliant `/token` flow, add spec reference, update Tasks/Technical Notes, approve.
+- **Missing tasks:** If <3 tasks, run ln-310-story-decomposer, reload tasks, reorder Foundation-First, update kanban and comments, approve.
+
+## Reference Files
+
+- Templates: `../ln-220-story-coordinator/references/story_template_universal.md`, `../ln-311-task-creator/references/task_template_implementation.md`
+- Checklists: `references/verification_checklist.md`, `references/verification_log_template.md`
+- Testing methodology (for later phases): `../ln-350-story-test-planner/references/risk_based_testing_guide.md`
+- Linear integration: `../ln-210-epic-coordinator/references/linear_integration.md`
+
+---
+
+Version: 12.1.0 (Condensed guidance, tabled auto-fix actions, clarified testing deferral and violation reporting)
+Last Updated: 2025-11-26

skills/ln-320-story-validator/diagram.html

@@ -0,0 +1,84 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>ln-320-story-validator - State Diagram</title>
+    <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
+    <link rel="stylesheet" href="../shared/css/diagram.css">
+</head>
+<body>
+    <div class="container">
+        <header>
+            <h1>✅ ln-320-story-validator</h1>
+            <p class="subtitle">Story Verifier - State Diagram</p>
+        </header>
+        <div class="info-box">
+            <h3>📋 Overview</h3>
+            <ul>
+                <li><strong>Purpose:</strong> Auto-fix and approve Stories (8 sections) and Tasks (7 sections) against industry standards</li>
+                <li><strong>Verdict:</strong> ALWAYS approves after auto-fixing ALL 16 verification criteria (no "Needs Work" path)</li>
+                <li><strong>State Transition:</strong> Backlog → Todo (Story + ALL Tasks)</li>
+                <li><strong>Structure:</strong> 4 phases (Discovery & Loading → Critical Review → Auto-Fix Groups A/B/C/D → Approve & Notify)</li>
+            </ul>
+        </div>
+        <div class="diagram-container">
+            <div class="mermaid">
+graph TD
+    Start([Start: Verify Story]) --> Phase1[Phase 1: Discovery & Loading<br/>Team ID + project docs<br/>Load Story FULL + Tasks metadata<br/>Validate task breakdown 3-8 tasks]
+
+    Phase1 --> Phase2[Phase 2: Critical Solution Review<br/>Standards Hierarchy PRIORITY 1-4]
+
+    subgraph Standards [Standards Compliance & Solution Review]
+        S1[Check industry standards FIRST<br/>OAuth 2.0 REST OpenAPI RFCs<br/>PRIORITY 1]
+        S1 --> S2[Challenge approach<br/>Best way in 2025?<br/>Research best practices]
+        S2 --> S3{Documentation<br/>gaps detected?}
+
+        S3 -->|None| S9[Continue to Phase 3]
+        S3 -->|Pattern<br/>trigger| S6[Auto-create Guide<br/>ln-321-guide-creator<br/>HOW to implement]
+        S3 -->|Package+version<br/>trigger| S7[Auto-create Manual<br/>ln-323-manual-creator<br/>HOW to use library]
+        S3 -->|Decision<br/>trigger| S8[Auto-create ADR<br/>ln-322-adr-creator<br/>WHY we decided]
+
+        S6 --> S10[Save doc paths<br/>for Phase 3 #13]
+        S7 --> S10
+        S8 --> S10
+        S9 --> Phase3
+        S10 --> Phase3
+    end
+
+    Phase2 --> S1
+
+    Phase3[Phase 3: Comprehensive Auto-Fix<br/>16 Verification Criteria #1-#16]
+
+    subgraph FixGroups [Auto-Fix Groups A → B → C → D]
+        GA[Group A: Structural Fixes<br/>#1 Story Structure 8 sections<br/>#2 Tasks Structure 7 sections sequential<br/>#3 Story Statement As a/I want/So that<br/>#4 Acceptance Criteria Given/When/Then]
+        GA --> GB[Group B: Solution Optimization<br/>#5 Industry Standards RFC compliance<br/>#6 Solution 2025 best practices<br/>#7 Library & Version current stable<br/>#13 Documentation Links insertion]
+        GB --> GC[Group C: Workflow Optimization<br/>#9 Test Strategy Risk-Based<br/>#10 Test Task Cleanup remove premature<br/>#11 Documentation Integration<br/>#12 Foundation-First Execution]
+        GC --> GD[Group D: Scope & Quality<br/>#13 Story Size 3-8 tasks x-task-manager<br/>#14 YAGNI Violations<br/>#15 KISS Violations<br/>#16 Code Quality config management]
+    end
+
+    Phase3 --> GA
+    GD --> Phase4
+
+    Phase4[Phase 4: Approve & Notify<br/>Story + ALL Tasks → Todo<br/>kanban_board.md ✅ APPROVED<br/>Approval comment + optional warning<br/>Summary table display]
+
+    Phase4 --> End([End: Story ALWAYS Approved])
+
+    classDef discovery fill:#E3F2FD,stroke:#1976D2,stroke-width:2px
+    classDef processing fill:#FFF9C4,stroke:#F57C00,stroke-width:2px
+    classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
+
+    class Phase1 discovery
+    class Phase2,S1,S2,S3,Phase3,GA,GB,GC,GD processing
+    class Phase4 action
+            </div>
+        </div>
+        <footer>
+            <p>ln-320-story-validator v10.0.0 | 4 phases · 16 auto-fix criteria · NO "Needs Work" path - ALWAYS approves after fixes</p>
+        </footer>
+    </div>
+    <script>
+        mermaid.initialize({ startOnLoad: true, theme: 'default', flowchart: { useMaxWidth: true, htmlLabels: true, curve: 'basis' } });
+    </script>
+</body>
+</html>

skills/ln-320-story-validator/references/verification_checklist.md

@@ -0,0 +1,457 @@
+# Story Verification Checklist
+
+Complete checklist for verifying Story and all its Tasks before approval.
+
+**CRITICAL PRINCIPLE:** This skill ALWAYS auto-fixes all issues detected. Never leave Story in Backlog with feedback - fix and approve.
+
+## Mandatory Checks (Auto-Fix Actions)
+
+### 1. Story Structure Format (Template Compliance)
+**Check:** Story description follows template structure
+
+⚠️ **Important:** Request FULL Story description from Linear (not truncated) to validate all 8 sections.
+
+**Required Sections (in order):**
+1. **Story** (As a / I want / So that)
+2. **Context** (Current Situation + Desired Outcome)
+3. **Acceptance Criteria** (Given-When-Then: Main Scenarios + Edge Cases + Error Handling)
+4. **Implementation Tasks** (List with links including final test task)
+5. **Test Strategy** (Unit 70% / Integration 20% / E2E 10%)
+6. **Technical Notes** (Architecture Considerations + Integration Points + Performance & Security)
+7. **Definition of Done** (Functionality + Testing + Code Quality)
+8. **Dependencies** (Depends On + Blocks)
+
+✅ All 8 sections present in correct order
+✅ Each section has non-empty content
+✅ Required subsections present (Context: Current Situation/Desired Outcome)
+❌ Missing sections → Add with template placeholders
+❌ Sections out of order → Reorder to match template
+❌ Empty sections → Add placeholder text
+
+**Fix Actions:**
+When structure violations detected:
+1. Parse current Story description
+2. Identify missing/misplaced sections
+3. Restructure:
+   - Add missing sections with placeholders (_TODO: Fill this section_)
+   - Reorder sections to match template
+   - Add missing subsections (Current Situation, Desired Outcome, etc.)
+4. Update Linear issue via `mcp__linear-server__update_issue`
+5. Add comment to Linear explaining changes
+
+**Template Reference:** `../../ln-220-story-coordinator/references/story_template_universal.md` (v5.0.0)
+
+**Skip Fix When:**
+- Story in Done/Canceled status
+- Story older than 30 days (legacy, don't touch)
+
+### 2. Tasks Structure Format (Template Compliance - EVERY Task)
+**Check:** All child Task descriptions follow template structure
+
+**Equally Critical:** This check is as important as Story validation (#1). EVERY Task must comply with task_template_universal.md.
+
+⚠️ **Important:** Request FULL Task description from Linear (not truncated) for EACH Task to validate all 7 sections.
+
+**Required Sections (in order for EACH Task):**
+1. **Context** (Current State + Desired State)
+2. **Implementation Plan** (Phase 1-3 with checkboxes)
+3. **Technical Approach** (Recommended + Why + Patterns + Alternatives)
+4. **Acceptance Criteria** (Given-When-Then with checkboxes)
+5. **Affected Components** (Implementation + Documentation)
+6. **Existing Code Impact** (Refactoring + Tests to Update + Documentation to Update)
+7. **Definition of Done** (Checklist)
+
+> [!NOTE]
+
+> Test Strategy removed from Tasks - all tests in Story's final task
+
+✅ All 7 sections present in correct order in EVERY Task
+✅ Each section has non-empty content in every Task
+✅ Required subsections present in every Task
+❌ Missing sections in any Task → Add with template placeholders
+❌ Sections out of order in any Task → Reorder to match template
+
+**Fix Actions:**
+For each Task with structure violations:
+1. Parse Task description
+2. Identify missing/misplaced sections
+3. Restructure each Task
+4. Update Linear issue for each Task via `mcp__linear-server__update_issue`
+5. Add comment to Linear for each fixed Task
+
+**Template Reference:** `../../ln-311-task-creator/references/task_template_implementation.md` (v5.0.0)
+
+**Skip Fix When:**
+- Task in Done/Canceled status
+- Task older than 30 days (legacy, don't touch)
+
+### 3. Story Statement
+**Check:** Clear, specific, user-focused (As a / I want / So that)
+
+✅ "As a API client, I want to authenticate with OAuth2 tokens, So that users can securely access their data"
+❌ "Improve authentication" (vague, no user context)
+
+### 4. Acceptance Criteria (Story Level)
+**Check:** Specific, testable, Given/When/Then format covering Story goal
+
+✅ "Given valid OAuth2 token, When API request sent, Then user authenticated and data returned"
+✅ "Given invalid token, When API request sent, Then 401 error returned"
+❌ "Authentication should work correctly" (not testable)
+
+### 5. Technical Approach (Story Level)
+**Check:** Follows project architecture patterns, not over-engineered, consistent with previous Story
+
+✅ "Use OAuth2 library (authlib 1.3+) for token validation, integrate with existing User model"
+❌ "Implement custom JWT parser and validation" (library exists, YAGNI violation)
+
+**Questions:**
+- Does standard library solve Story goal?
+- Is there simpler architectural approach? (KISS)
+- Does Story duplicate existing functionality? (DRY)
+- Which guide covers this architectural pattern?
+- Are all layers properly involved? (API → Service → Repository)
+
+**If previous Story context loaded (Phase 2 step 7):**
+- ✅ Current Story uses same guides as previous Story (consistency)
+- ✅ Current Story reuses components from previous Story (no reinvention)
+- ✅ Current Story integrations compatible with previous Story
+- ❌ Current Story creates duplicate component that exists in previous Story → Add TODO
+- ❌ Current Story conflicts with previous Story integrations → Add TODO
+
+**Auto-fix actions:**
+- Add missing guides from previous Story to Technical Notes
+- Add TODO if duplicate components detected
+- Add TODO if conflicting integrations detected
+- Add context reference: "Related to previous Story [US00X]"
+
+### 6. Library & Version Research (Story Level)
+**Check:** Story Technical Notes contain Library Research table populated by ln-220-story-coordinator Phase 3
+
+✅ Library Research subsection present in Technical Notes
+✅ Library Research table filled with: Library name, Version (v[X.Y.Z]), Purpose, Docs URL
+✅ Key APIs listed (2-5 method signatures with purpose)
+✅ Key constraints documented (async support, memory limitations, multi-process caveats, compatibility)
+✅ Standards compliance documented (RFC/spec references if applicable, e.g., "RFC 6749 OAuth 2.0")
+✅ Latest stable versions specified (prefer LTS, avoid alpha/beta/RC)
+✅ Tasks reference library specs from Story (not duplicating research)
+
+❌ Library Research subsection missing → **Auto-fix:** Research via MCP Context7 + Ref, populate table, update Story in Linear
+❌ Library Research table empty or incomplete → **Auto-fix:** Research and fill missing fields
+❌ Outdated library versions (> 6 months old stable release) → **Auto-fix:** Update to current stable via MCP Context7
+❌ Missing Key APIs → **Auto-fix:** Research via MCP Context7 and add 2-5 key methods
+❌ Missing constraints/limitations → **Auto-fix:** Research via MCP Ref and add known issues
+❌ Bleeding edge versions (alpha/beta/RC) when stable exists → **Auto-fix:** Downgrade to latest stable
+❌ Tasks implement custom helpers when library provides built-in methods → **Auto-fix:** Update Task Technical Approach to use library methods
+❌ No guide for external package in `docs/guides/` → **Flag for guide creation** (handled by Phase 3)
+
+**NOTE:** Library research should be performed in ln-220-story-coordinator Phase 3. This check validates it happened and updates if needed. If Library Research subsection is completely missing, it indicates Phase 3 was skipped (rare case).
+
+**Auto-fix actions (#6):**
+1. **If Library Research table missing:**
+   - Research via `mcp__context7__resolve-library-id()` + `mcp__context7__get-library-docs()`
+   - Research via `mcp__Ref__ref_search_documentation()` for best practices and standards
+   - Populate full table (libraries, versions, purpose, docs, key APIs, constraints, standards)
+   - Update Story description in Linear via `mcp__linear-server__update_issue()`
+   - Add comment in Linear: "Library research added (Phase 3 was skipped initially)"
+
+2. **If versions outdated:**
+   - Research latest stable via MCP Context7
+   - Update version numbers in table
+   - Update Story description in Linear
+   - Add comment: "Library versions updated to 2025 standards"
+
+3. **If Key APIs or constraints missing:**
+   - Research via MCP Context7 (library docs) + MCP Ref (best practices)
+   - Add missing sections to table
+   - Update Story description in Linear
+   - Add comment: "Library technical details completed"
+
+**Tools:**
+- MCP Context7: `mcp__context7__resolve-library-id()`, `mcp__context7__get-library-docs()`
+- MCP Ref: `mcp__Ref__ref_search_documentation()`
+- WebSearch (fallback if library not in Context7/Ref)
+- Linear: `mcp__linear-server__update_issue()` for Story updates
+
+### 7. Tests Integration (Story Level)
+**Check:** Story has Test Strategy section, final Task dedicated to tests
+
+✅ Story has Test Strategy section (Risk-Based Testing: 2-5 E2E, 3-8 Integration, 5-15 Unit, 10-28 total, Priority ≥15) focusing on business logic (not frameworks/libraries/trivial getters)
+✅ Final Task in Implementation Tasks list is test task
+✅ Story DoD includes: "All tests passing (Unit/Integration/E2E)"
+✅ Test Strategy specifies E2E type (API or UI based on application)
+✅ No duplicate test coverage - Each behavior tested once at appropriate level
+❌ Story missing Test Strategy section
+❌ No final test task planned
+❌ Implementation Tasks include test sections (should be test-free)
+
+### 8. Documentation Integration (Story + Tasks Level)
+**Check:** Docs integrated across Story Tasks, not separate
+
+✅ Story DoD includes: "Documentation updated"
+✅ Tasks include doc updates in Affected Components
+❌ Separate Task: "Document Story implementation" (creates stale docs)
+❌ Story without documentation plan in Tasks
+
+### 9. Story Size
+**Check:** Reasonable scope (3-8 Tasks, ~1-2 weeks) AND each task is optimal size (3-5 hours)
+
+**Story-level check:**
+✅ 4-6 Tasks covering API → Service → Repository → Tests
+❌ Too large: "Implement complete auth + authorization + audit" → Split into multiple Stories
+❌ Too small: Single trivial change → Combine or make it a standalone Task
+
+**Task-level check (granularity):**
+✅ Each task 3-5 hours development time (atomic, testable unit)
+✅ Task: "Implement token validation middleware" (~4 hours: logic + error handling + integration)
+❌ Too granular (< 3h): "Add import statement", "Create empty function" → Combine with related work
+❌ Too large (> 8h): "Implement complete OAuth2 flow" → Decompose into smaller tasks (generation + validation + refresh + revocation)
+
+**Red flags:**
+- Tasks with overly detailed decomposition (< 3h each) - sign of over-planning
+- Tasks with vague scope (> 8h estimated) - needs further breakdown
+
+### 10. YAGNI Compliance (Story Level)
+**Check:** Story delivers only what is needed NOW
+
+✅ "OAuth2 token authentication" (current requirement)
+❌ "Add multi-factor authentication" (not in current requirements)
+❌ "Support 5 OAuth providers" (only 1 provider needed now)
+
+### 11. KISS Compliance (Story Level)
+**Check:** Simplest architectural solution that delivers Story goal
+
+✅ "Use existing OAuth2 library with standard flow" (simple, proven)
+❌ "Implement distributed auth microservice with event sourcing" (over-engineered for auth)
+
+### 12. Guide References (Story Level)
+**Check:** Story Technical Notes reference existing guides or propose new
+
+✅ "Follow [Guide 05: Authentication Pattern](link) for OAuth2 flow"
+✅ "Create new guide: Multi-Tenant Authentication Strategy"
+❌ No guide references in Story Technical Notes (architectural pattern not documented)
+
+### 13. Foundation-First Execution Order (Story Level)
+**Check:** Story implements foundation before consumers (for testability)
+
+✅ Task order: 1. Token Repository (database) → 2. Auth Service → 3. API endpoint (consumer)
+✅ Each layer is testable when built (no mocks needed for lower layers)
+❌ Task order: 1. API endpoint → 2. Auth Service → 3. Token Repository (can't test without DB)
+
+**Detection Keywords:**
+- Database/Foundation: repository, database, schema, migration, entity
+- Service: service, business logic, use case
+- Consumer: endpoint, route, controller, API, UI component
+
+**Exceptions:** Foundation layer, standard infrastructure, generic utilities
+
+### 14. Code Quality Fundamentals (Story Level)
+**Check:** Story Tasks avoid hardcoded values and use proper configuration management
+
+✅ "Store API timeout in config: `config.api.timeout = 5000`" (configurable)
+✅ "Use environment variable: `const maxRetries = process.env.MAX_RETRY_COUNT || 3`"
+✅ "Named constant with explanation: `const BUFFER_SIZE = 1024 // Optimal for 4KB page size`"
+❌ "Set timeout to 5000ms in code" (magic number without explanation)
+❌ "`const API_URL = 'https://api.example.com'`" (hardcoded URL, should be env var)
+❌ "`const MAX_ITEMS = 100`" (magic number without WHY explanation)
+
+**Must check:**
+- Magic numbers extracted to named constants or configuration
+- Hardcoded paths/URLs moved to config files or environment variables
+- API keys and credentials use environment variables (never in code)
+- Timeouts, limits, thresholds are configurable
+- Named constants have explanatory comments (WHY this value)
+
+> [!NOTE]
+
+> This check is performed at Story level (review Technical Notes and Implementation Tasks descriptions), not code inspection.
+
+### 15. Industry Standards Compliance (Story Level)
+**Check:** Story solution follows industry standards and RFCs (checked BEFORE applying KISS/YAGNI)
+
+**Hierarchy:** Industry Standards (Level 1) > Security Standards (Level 2) > KISS/YAGNI/DRY (Level 3)
+
+✅ "Implement POST /auth/token with grant_type parameter per OAuth 2.0 RFC 6749" (standard-compliant)
+✅ "Use OpenAPI 3.1 spec for API documentation" (follows industry standard)
+✅ "REST API follows RESTful principles (resource-based URLs, proper HTTP methods)" (standard design)
+✅ "WebSocket handshake per RFC 6455" (protocol compliance)
+❌ "Create separate /tokens and /refresh endpoints for simplicity" (non-standard OAuth flow, KISS conflicts with RFC 6749)
+❌ "Custom authentication flow instead of OAuth 2.0" (reinventing standard, integration issues)
+❌ "Non-RESTful API design (e.g., GET /api/deleteUser)" (violates REST principles)
+
+**Common standards to check (examples - not exhaustive):**
+- **OAuth 2.0:** RFC 6749 compliance (unified /token endpoint, grant_type parameter, standard flows)
+- **REST API:** RESTful principles (resource-based URLs, proper HTTP methods, status codes)
+- **OpenAPI:** API documentation follows OpenAPI 3.x specification
+- **Protocols:** HTTP/HTTPS, WebSocket, GraphQL standards compliance
+- **Data formats:** JSON (RFC 8259), XML, YAML standard compliance
+
+---
+
+### Evidence-Based Verification (MANDATORY)
+
+**Trigger conditions (when this criterion applies):**
+- Story involves protocols, APIs, authentication, data formats
+- Story references external integrations or library usage
+- Task implementation path not documented in existing guides/manuals
+
+**REQUIRED actions (cannot mark ✅ without evidence):**
+
+1. **Check existing documentation FIRST:**
+   - Scan `docs/guides/` for relevant implementation patterns
+   - Scan `docs/manuals/` for library/API references
+   - Scan `docs/adrs/` for architectural decisions
+
+2. **IF documentation gap found → MUST invoke workers:**
+   - Missing pattern guide → MUST invoke `ln-321-guide-creator`
+   - Missing library manual → MUST invoke `ln-323-manual-creator`
+   - Missing architectural decision → MUST invoke `ln-322-adr-creator`
+   - Workers perform research via MCP Ref/Context7 internally
+
+3. **Document compliance (REQUIRED evidence):**
+   - Document path (existing or created): `docs/guides/XX-pattern.md`
+   - OR Worker invocation result: "Created via ln-321-guide-creator"
+   - OR Explicit skip reason: "No applicable standards - Story is internal refactoring only"
+
+4. **IF no applicable standards:**
+   - MUST explicitly state reason in Verification Log
+   - CANNOT leave blank or assume "not applicable"
+
+**Self-Audit Question (MUST answer before marking ✅):**
+> "Did I verify implementation path via docs/worker? Evidence: ___"
+
+If answer is blank or generic → CANNOT mark ✅ → MUST perform verification first
+
+---
+
+**Red Flags:**
+❌ Custom implementation when industry standard exists (OAuth, REST, OpenAPI)
+❌ Non-standard endpoints/flows for "simplicity" (KISS overriding RFC compliance)
+❌ "Proprietary" protocols when standard protocol available
+❌ Non-compliant API design (e.g., mixing REST and RPC styles)
+❌ **Marking ✅ without documented evidence** (fake verification)
+
+**Auto-fix actions (#15):**
+- Check existing docs in `docs/guides/`, `docs/manuals/`, `docs/adrs/`
+- IF gap found → Invoke ln-321/ln-322/ln-323 workers (they perform research internally)
+- Add document links to Story Technical Notes
+- Update Tasks with standard-compliant implementation
+- Add RFC/spec references in Technical Notes
+- Update Linear issues
+- Add comment: "Standards verified via [document path] OR created via [worker name]"
+
+**Verification Log:** Document evidence in `checkpoints/{STORY_ID}_verification_log.md`
+
+---
+
+## Quick Verification Matrix
+
+| Criterion | Pass | Notes | Evidence Required |
+|-----------|------|-------|-------------------|
+| Story follows template? | ☐ | 8 sections in order | Section list |
+| All Tasks follow template? | ☐ | 7 sections each | Task validation count |
+| Clear Story statement? | ☐ | As a/I want/So that | Quote statement |
+| Testable AC? | ☐ | Given/When/Then at Story level | AC count |
+| Test Strategy present? | ☐ | Risk-Based Testing (2-5 E2E, 3-8 Int, 5-15 Unit) | Test counts |
+| Final test task planned? | ☐ | Last task in Implementation Tasks | Task list |
+| **Standards compliant?** | ☐ | **OAuth 2.0, REST, RFCs - checked FIRST** | **Doc path OR worker call** |
+| Follows patterns? | ☐ | References guides in Technical Notes | Guide links |
+| Library research? | ☐ | Latest versions, no reinventing | Version list |
+| Docs integrated? | ☐ | Story DoD + Tasks include docs | Integration proof |
+| Size 3-8 Tasks? | ☐ | Not too small/large | Task count |
+| YAGNI? | ☐ | No premature features | Scope review |
+| KISS? | ☐ | Simplest solution (within standards) | Simplicity reason |
+| Guides referenced? | ☐ | Links to patterns | Guide paths |
+| Foundation-first? | ☐ | Task order: DB→Repo→Service→API | Task order |
+| No hardcoded values? | ☐ | Config management, no magic numbers | TODO placeholders |
+
+---
+
+## Evidence-Based Verification Protocol
+
+**MANDATORY:** Before marking ANY criterion as ✅, agent MUST:
+
+1. **Answer Self-Audit Question** for that criterion (not blank)
+2. **Provide concrete evidence** (document path, tool result, or explicit reason)
+3. **Document in Verification Log:** `checkpoints/{STORY_ID}_verification_log.md`
+
+**If evidence missing → CANNOT mark ✅ → MUST perform required action first**
+
+**Template:** `verification_log_template.md`
+
+---
+
+**Result:** ALL criteria auto-fixed → ALWAYS Approve → Todo
+
+> [!NOTE]
+> No "Keep in Backlog" path exists - all issues auto-fixed before approval
+
+> [!WARNING]
+> Marking ✅ without documented evidence = INVALID verification
+
+**Hierarchy:** Industry Standards (#15) checked BEFORE KISS/YAGNI (#11/#10)
+
+---
+
+## Common Issues & Auto-Fix Actions
+
+**All issues are AUTO-FIXED automatically. No manual intervention required.**
+
+1. **Incorrect Story Structure** - Missing/misplaced sections
+   - **Auto-fix:** Restructure Story per template, add missing sections with placeholders, reorder sections, update Linear
+
+2. **Incorrect Task Structure** - Missing/misplaced sections in Tasks
+   - **Auto-fix:** Restructure each Task per template, add missing sections with placeholders, update Linear for each Task
+
+3. **Vague Story** - "Improve X" instead of As a/I want/So that
+   - **Auto-fix:** Extract persona from Context, identify capability from Technical Notes, rewrite Story statement, update Linear
+
+4. **Non-Testable AC** - Vague acceptance criteria
+   - **Auto-fix:** Convert to Given/When/Then format, add edge cases from Context, ensure 3-5 AC, update Linear
+
+5. **Outdated Solution** - Not using 2025 best practices
+   - **Auto-fix:** Rewrite Story Technical Notes with modern approach, update Tasks with optimized plan, update Linear
+
+6. **Outdated Libraries** - Old package versions
+   - **Auto-fix:** Replace with current stable versions, update Story Technical Notes and Tasks, update Linear
+
+7. **Missing Test Strategy** - No Risk-Based Testing section
+   - **Auto-fix:** Add Test Strategy section (2-5 E2E, 3-8 Integration, 5-15 Unit, 10-28 total, Priority ≥15), update Story DoD, update Linear
+
+8. **Standalone Doc Task** - Separate documentation task
+   - **Auto-fix:** Remove doc task, integrate docs into Affected Components of implementation tasks, update Linear
+
+9. **Wrong Story/Task Size** - Too large (> 8 tasks) or too small (< 3 tasks), wrong task granularity (> 8h or < 3h)
+   - **Auto-fix:** Add TODO placeholders flagging size issues for user review, update Linear
+
+10. **YAGNI Violations** - Premature features in scope
+    - **Auto-fix:** Move to Story "Out of Scope" or "Future Enhancements", remove from Tasks, update Linear
+
+11. **KISS Violations** - Over-engineered solution
+    - **Auto-fix:** Simplify architectural approach in Technical Notes, update Tasks with simplified implementation, update Linear
+
+12. **Missing Guide Links** - No guides referenced
+    - **Auto-fix:** Insert auto-created and existing guide links in Story Technical Notes "Related Guides:" subsection, update Linear
+
+13. **Provider-First Tasks** - Wrong task order
+    - **Auto-fix:** Reorder Tasks (Consumer → Service → Provider), update Story Implementation Tasks section, update Linear
+
+14. **Hardcoded Values** - Magic numbers, hardcoded URLs/paths, credentials in code
+    - **Auto-fix:** Add TODO placeholders for extracting magic numbers, moving URLs to config, using env vars for credentials, update Linear
+
+15. **Non-standard Implementations** - Custom solutions when industry standards exist (OAuth, REST, RFCs)
+    - **Auto-fix:** Research RFC/standard via MCP Ref, rewrite Story Technical Notes to comply with standard, update Tasks with standard-compliant implementation, add RFC/spec references, update Linear, add comment with standard name and RFC/spec number
+
+---
+
+## Post-Verification (Always Approve)
+
+**Result:** ALWAYS Approve → Todo (after ALL auto-fixes applied)
+- Story: Backlog → Todo
+- All child Tasks: Backlog → Todo
+- kanban_board.md: Updated
+- Optional warning comment if TODO placeholders exist (user review needed but don't block execution)
+
+---
+
+**Version:** 7.0.0 (Added Evidence-Based Verification Protocol, Self-Audit Questions, Verification Log requirement)
+**Last Updated:** 2025-11-23