Skip to main content

Kanban → Versioning Integration Validation

Task: E4:S03:T02 – Validate Kanban → Versioning integration in dev-kit
Date: 2025-12-02
Author: AI Agent (Auto)
Status: ✅ COMPLETE

Executive Summary​

This report validates the integration between Kanban and Versioning systems in the dev-kit. The validation reveals a critical inconsistency in how version numbers are assigned: Tasks are not correctly mapping to the TASK component in versions. Instead, all Tasks within a Story are using TASK=1, with BUILD incrementing across Tasks. This violates the versioning schema rules.

Key Findings:

  • ✅ Epic/Story numbers correctly map to version EPIC/STORY components
  • ❌ CRITICAL: Task numbers are NOT correctly mapping to version TASK component
  • ⚠️ Version assignment happens at Task creation, but uses incorrect TASK number
  • ⚠️ Version file updates align with Kanban Task creation, but reflect incorrect mapping

1. Validation Methodology​

1.1 Test Cases​

Test Case 1: Epic 4, Story 1 (Dev Kit Kanban Implementation)

  • Tasks: E4:S01:T01 through E4:S01:T05
  • Expected versions: v0.4.1.1+1, v0.4.1.2+1, v0.4.1.3+1, v0.4.1.4+1, v0.4.1.5+1
  • Actual versions: v0.4.1.1+2, v0.4.1.1+3, v0.4.1.1+4, v0.4.1.1+5, v0.4.1.1+6

Test Case 2: Epic 2, Story 1 (RW Agent Execution & Docs)

  • Tasks: E2:S01:T01 through E2:S01:T04
  • Expected versions: v0.2.1.1+1, v0.2.1.2+1, v0.2.1.3+1, v0.2.1.4+1
  • Actual versions: v0.2.1.1+3, v0.2.1.1+4, v0.2.1.1+5, v0.2.1.1+2

Test Case 3: Epic 3, Story 1 (Dev Kit Alignment with Versioning Framework)

  • Tasks: E3:S01:T01 through E3:S01:T06
  • Expected versions: v0.3.1.1+1, v0.3.1.2+1, v0.3.1.3+1, v0.3.1.4+1, v0.3.1.5+1, v0.3.1.6+1
  • Actual versions: (to be verified)

2. Validation Results​

2.1 Epic/Story Number Mapping ✅​

Validation: Epic and Story numbers correctly map to version EPIC and STORY components.

Examples:

  • Epic 4, Story 1 → v0.4.1.x+x ✅
  • Epic 2, Story 1 → v0.2.1.x+x ✅
  • Epic 3, Story 1 → v0.3.1.x+x ✅

Status: ✅ PASS - Epic and Story numbers correctly map to version components.

2.2 Task Number Mapping ❌​

Validation: Task numbers are NOT correctly mapping to version TASK component.

Expected Behavior (per versioning policy):

  • Each new Task should increment TASK and reset BUILD to 1
  • Task 1 → TASK=1, BUILD=1
  • Task 2 → TASK=2, BUILD=1
  • Task 3 → TASK=3, BUILD=1

Actual Behavior:

  • All Tasks in a Story use TASK=1
  • BUILD increments across Tasks (2, 3, 4, 5, 6...)
  • Task 1 → TASK=1, BUILD=2
  • Task 2 → TASK=1, BUILD=3
  • Task 3 → TASK=1, BUILD=4

Evidence:

Epic 4, Story 1:

  • E4:S01:T01 → v0.4.1.1+2 ❌ (should be v0.4.1.1+1)
  • E4:S01:T02 → v0.4.1.1+3 ❌ (should be v0.4.1.2+1)
  • E4:S01:T03 → v0.4.1.1+4 ❌ (should be v0.4.1.3+1)
  • E4:S01:T04 → v0.4.1.1+5 ❌ (should be v0.4.1.4+1)
  • E4:S01:T05 → v0.4.1.1+6 ❌ (should be v0.4.1.5+1)

Epic 2, Story 1:

  • E2:S01:T01 → v0.2.1.1+3 ❌ (should be v0.2.1.1+1)
  • E2:S01:T02 → v0.2.1.1+4 ❌ (should be v0.2.1.2+1)
  • E2:S01:T03 → v0.2.1.1+5 ❌ (should be v0.2.1.3+1)
  • E2:S01:T04 → v0.2.1.1+2 ❌ (should be v0.2.1.4+1)

Status: ❌ FAIL - Task numbers are NOT correctly mapping to version TASK component.

Impact:

  • Version numbers do not reflect actual Task progression
  • Cannot distinguish between Tasks using version numbers alone
  • Violates versioning schema rules
  • Breaks forensic traceability (version → Task mapping is incorrect)

2.3 Version Assignment at Task Creation ⚠️​

Validation: Version assignment happens at Task creation, but uses incorrect TASK number.

Process:

  1. Task is created in Story document
  2. Version is assigned using current version.py values
  3. version.py is updated with new version
  4. RW increments BUILD when Task is completed

Issue:

  • Version assignment uses VERSION_TASK from version.py
  • VERSION_TASK is not updated when moving to a new Task
  • VERSION_TASK stays at 1, and VERSION_BUILD increments instead

Status: ⚠️ PARTIAL - Version assignment happens, but uses incorrect TASK number.

2.4 Version File Updates ⚠️​

Validation: Version file updates align with Kanban Task creation, but reflect incorrect mapping.

Current version.py Structure:

VERSION_EPIC = 4      # Epic number (Epic 4: Kanban Framework)
VERSION_STORY = 3     # Story number (Story 3: Kanban + Versioning + RW Integration)
VERSION_TASK = 1      # Task number (Task 1: Review existing integration documentation)
VERSION_BUILD = 1     # Build number (increments per release within task, bumped by RW)

Issue:

  • VERSION_TASK is manually set and not automatically updated when moving to a new Task
  • VERSION_BUILD increments across Tasks instead of resetting to 1 for each new Task
  • No automatic mechanism to update VERSION_TASK when a new Task is created

Status: ⚠️ PARTIAL - Version file updates align with Task creation, but reflect incorrect TASK mapping.

3. Root Cause Analysis​

3.1 Why This Happened​

Root Cause: The Release Workflow (RW) increments BUILD for each release, but does not update TASK when moving to a new Task. The TASK component is only updated manually in version.py, and this manual update is not happening when new Tasks are created.

Contributing Factors:

  1. Manual TASK Updates: VERSION_TASK must be manually updated in version.py when starting a new Task
  2. BUILD Increments: RW automatically increments BUILD, which masks the need to update TASK
  3. No Validation: No validation checks that TASK matches the active Task number
  4. Documentation Gap: Intake guides mention version assignment but don't emphasize TASK updates

3.2 Schema Violation​

Versioning Policy Rule (from dev-kit-versioning-policy.md):

"Moving to Task 2 within the same Story:

  • 0.1.1.2+1 – First dev build for Task 2"

Current Practice:

  • Moving to Task 2 → 0.1.1.1+2 (TASK stays 1, BUILD increments)

Violation: This violates the versioning schema rules defined in the policy.

4. Gaps and Inconsistencies​

4.1 Critical Gaps​

  1. No Automatic TASK Updates:

    • When a new Task is created, VERSION_TASK is not automatically updated
    • Manual update required, but not consistently done

  2. BUILD Increments Across Tasks:

    • BUILD should reset to 1 for each new Task
    • Currently, BUILD increments across Tasks (2, 3, 4, 5, 6...)

  3. No Validation:

    • No validation that VERSION_TASK matches the active Task number
    • No validation that BUILD resets when TASK changes

  4. Documentation Gap:

    • Intake guides mention version assignment but don't emphasize TASK updates
    • No clear process for updating VERSION_TASK when starting a new Task

4.2 Inconsistencies​

  1. Version Numbers Don't Match Tasks:

    • v0.4.1.1+2 is labeled as "Task 1" but BUILD=2 suggests it's the second release
    • v0.4.1.1+3 is labeled as "Task 2" but TASK=1 and BUILD=3

  2. Forensic Markers Are Misleading:

    • Forensic markers show v0.4.1.1+2 for Task 1, but this doesn't clearly indicate it's Task 1
    • Multiple Tasks share the same TASK number, making traceability difficult

5. Recommendations​

5.1 Immediate Fixes​

  1. Update Version Assignment Process:

    • When creating a new Task, VERSION_TASK MUST be updated to match the Task number
    • VERSION_BUILD MUST reset to 1 for each new Task
    • Document this requirement in intake guides

  2. Add Validation:

    • Create validation script to check that VERSION_TASK matches active Task number
    • Add validation to RW Step 2 (Bump Version) to verify TASK matches active Task

  3. Fix Existing Versions (Optional):

    • Consider whether to retroactively fix version numbers for completed Tasks
    • If fixing, update all forensic markers and changelog entries
    • Document the correction in versioning policy

5.2 Process Improvements​

  1. Automate TASK Updates:

    • When RW detects a new Task (different Task number), automatically update VERSION_TASK
    • Reset VERSION_BUILD to 1 when VERSION_TASK changes

  2. Enhance Intake Guides:

    • Add explicit step: "Update VERSION_TASK in version.py to match Task number"
    • Add validation checklist: "Verify VERSION_TASK matches Task number"

  3. Update Documentation:

    • Update versioning policy to emphasize TASK updates
    • Update intake guides to include TASK update step
    • Add examples showing correct version progression

5.3 Long-Term Solutions​

  1. Version File Management:

    • Consider automatic version file updates during Task creation
    • Integrate version file updates into intake process

  2. Validation Integration:

    • Add version validation to RW Step 1 (Branch Safety Check)
    • Add version validation to intake process

  3. Tooling:

    • Create script to automatically update VERSION_TASK when Task is created
    • Create script to validate version numbers match active Task

6. Correct Version Progression Examples​

6.1 Correct Behavior​

Epic 4, Story 1 (Corrected):

  • E4:S01:T01 → v0.4.1.1+1 ✅ (Epic 4, Story 1, Task 1, Build 1)
  • E4:S01:T02 → v0.4.1.2+1 ✅ (Epic 4, Story 1, Task 2, Build 1)
  • E4:S01:T03 → v0.4.1.3+1 ✅ (Epic 4, Story 1, Task 3, Build 1)
  • E4:S01:T04 → v0.4.1.4+1 ✅ (Epic 4, Story 1, Task 4, Build 1)
  • E4:S01:T05 → v0.4.1.5+1 ✅ (Epic 4, Story 1, Task 5, Build 1)

Epic 2, Story 1 (Corrected):

  • E2:S01:T01 → v0.2.1.1+1 ✅ (Epic 2, Story 1, Task 1, Build 1)
  • E2:S01:T02 → v0.2.1.2+1 ✅ (Epic 2, Story 1, Task 2, Build 1)
  • E2:S01:T03 → v0.2.1.3+1 ✅ (Epic 2, Story 1, Task 3, Build 1)
  • E2:S01:T04 → v0.2.1.4+1 ✅ (Epic 2, Story 1, Task 4, Build 1)

6.2 BUILD Increments Within Task​

If Task 1 has multiple releases:

  • E4:S01:T01, Release 1 → v0.4.1.1+1 ✅
  • E4:S01:T01, Release 2 → v0.4.1.1+2 ✅ (same Task, BUILD increments)
  • E4:S01:T01, Release 3 → v0.4.1.1+3 ✅ (same Task, BUILD increments)

Moving to Task 2:

  • E4:S01:T02, Release 1 → v0.4.1.2+1 ✅ (new Task, TASK increments, BUILD resets to 1)

7. Conclusion​

The Kanban → Versioning integration has a critical inconsistency: Task numbers are not correctly mapping to the version TASK component. All Tasks within a Story are using TASK=1, with BUILD incrementing across Tasks. This violates the versioning schema rules and breaks forensic traceability.

Status:

  • ✅ Epic/Story mapping: CORRECT
  • ❌ Task mapping: INCORRECT
  • ⚠️ Version assignment: PARTIAL (happens but uses wrong TASK)
  • ⚠️ Version file updates: PARTIAL (align but reflect wrong mapping)

Next Steps:

  1. Fix version assignment process to update VERSION_TASK when creating new Tasks
  2. Add validation to ensure VERSION_TASK matches active Task number
  3. Update intake guides to include TASK update step
  4. Consider retroactive fixes for existing version numbers (optional)

References​

  • docs/architecture/standards-and-adrs/dev-kit-versioning-policy.md (versioning policy)
  • packages/frameworks/numbering & versioning/versioning-policy.md (framework policy)
  • packages/frameworks/kanban/FR_BR_INTAKE_GUIDE.md (intake process)
  • src/fynd_deals/version.py (current version file)

End of Kanban → Versioning Integration Validation