Skip to main content

Epic 7, Story 1: Codebase Maintenance Tasks

Status: IN PROGRESS
Priority: HIGH
Last updated: 2026-03-31 (v0.7.1.9+3 — UXR-005 Implementing Task wiring; prior BUILD 2 validate_branch_context)
Estimated Effort: [TBD]
Actual Effort: [TBD]
Started: 2025-12-09
Completed: [Reopened – TBD]
Version: v0.7.1.9+1
Code: E7S01

Task Checklist​

  • E7:S01:T01 – PERPETUAL: Address IDE-Flagged Error, Warning, and Info level problems - PERPETUAL
  • E7:S01:T02 – Create maintenance task prioritization framework - ✅ COMPLETE (v0.7.1.2+1 – Maintenance task prioritization framework created with severity, impact, effort dimensions, scoring formula, and Kanban integration)
  • E7:S01:T03 – Document maintenance workflow processes - ✅ COMPLETE (v0.7.1.3+1 – Maintenance workflow processes documented: IDE-flagged issues workflow, prioritized maintenance workflow, scheduled maintenance workflow, emergency maintenance workflow, with Kanban and tool integration)
  • E7:S01:T04 – Integrate maintenance tasks with Kanban framework - ✅ COMPLETE (v0.7.1.4+1 – Maintenance tasks integrated with Kanban framework: task creation, prioritization mapping, lifecycle tracking, Epic 4 integration, examples, and best practices documented)
  • E7:S01:T05 – Markdown Maintenance (Perpetual Task) - PERPETUAL (v0.7.1.5+1 – Perpetual task established for markdown maintenance across all documentation files)
  • E7:S01:T06 – Implement Update Changelog Workflow (UCW) - TODO (v0.7.1.5+6 – FR-057 defines UCW scope for latest-only changelog policy, archival automation, and RW integration)
  • E7:S01:T07 – Markdown Maintenance Workflow (MMW) - TODO (v0.7.1.6+2 – FR-058 defines workflow for resolving markdown lint blockers and coordinating perpetual maintenance cycles)
  • E7:S01:T08 – Task Doc Naming Standardization - IN PROGRESS (v0.7.1.6+2 – Establishes EddSddTdd-[title].md canonical naming and migration plan)
  • E7:S01:T09 – Kanban Template Governance & UXR Ownership - TODO (v0.7.1.9+3 – UXR-005 Implementing Task in UXR doc; UXR-005 ACs still open — see task doc)

Format: Exx:Sxx:Txx (Epic, Story, Task with 2-digit zero padding, e.g., E7:S01:T01, E7:S01:T02)
Forensic Marker Format: ✅ COMPLETE (vRC.E.S.T+B) (e.g., ✅ COMPLETE (v0.7.1.3+1))
Perpetual Tasks: Tasks marked as PERPETUAL are ongoing maintenance tasks that never truly "complete" but are continuously worked on. Track progress with version markers for each maintenance cycle or batch of work completed. Release Workflow Requirement: When Release Workflow (RW) Step 4 updates Epic documentation, it MUST update ALL sections:

  • Epic header Last updated field
  • Epic Story Checklist (status and version markers)
  • Epic detailed story sections (Status, Last updated, task checkboxes)
  • Story file Task Checklist (this section)
  • Story file detailed task sections
  • Any other references to this story/task

Consistency Check: After each RW, verify that Story file, Epic header, Epic Story Checklist, and Epic detailed sections all match.

Overview​

This story establishes systematic processes for addressing IDE-flagged issues and organizing codebase maintenance work. It provides the foundation for maintaining codebase health through systematic attention to IDE-flagged errors, warnings, and info-level issues.

Goals​

  • Establish perpetual task for addressing IDE-flagged issues
  • Create framework for prioritizing maintenance tasks
  • Document maintenance workflow processes
  • Integrate maintenance tasks with Kanban framework

Tasks​

E7:S01:T01 – PERPETUAL: Address IDE-Flagged Error, Warning, and Info level problems​

Format: Always use full Exx:Sxx:Txx format (e.g., E7:S01:T01, not T01 alone)

Type: PERPETUAL (ongoing maintenance task)
Input: IDE-flagged issues (errors, warnings, info) from development environment
Deliverable: Continuous resolution of IDE-flagged issues, maintaining codebase health
Dependencies: None
Blocker: None
Parallel Development Candidacy: Safe (can develop independently)

Status: PERPETUAL (ongoing)
Priority: HIGH
Last Maintenance Cycle: [Track each maintenance cycle with version markers]

Approach:

  1. Monitor IDE Flags: Regularly review IDE-flagged issues across the codebase

    • Errors (highest priority - must be addressed)
    • Warnings (high priority - should be addressed)
    • Info (medium priority - address when convenient)

  2. Prioritize Issues:

    • Address errors first (blocking issues)
    • Address warnings next (quality issues)
    • Address info-level issues as time permits (nice-to-have improvements)

  3. Batch Work:

    • Group related issues for efficient resolution
    • Create version markers for each batch of work completed
    • Track progress in this task's maintenance history

  4. Document Resolution:

    • Document fixes in changelog when appropriate
    • Update this task with version markers for each maintenance cycle
    • Note any patterns or systemic issues discovered

  5. Continuous Monitoring:

    • Set up regular reviews (e.g., weekly, bi-weekly)
    • Integrate with development workflow
    • Prevent accumulation of technical debt

Maintenance History:

  • Track each maintenance cycle with version markers
  • Example: v0.7.1.1+1 - Addressed 15 IDE errors, 8 warnings in packages/frameworks
  • Example: v0.7.1.1+2 - Resolved linting issues in validation scripts

Success Criteria:

  • IDE-flagged errors are addressed promptly (within 1-2 development cycles)
  • IDE-flagged warnings are addressed regularly (within 2-4 development cycles)
  • Info-level issues are addressed as time permits
  • Codebase health metrics show improvement over time
  • No accumulation of critical errors

Files to Monitor:

  • All source files in the project
  • Focus on active development areas
  • Prioritize framework packages and core functionality

Integration Points:

  • Epic 4 (Kanban Framework): Track maintenance work through Kanban tasks
  • Epic 6 (BR Implementation): Convert complex IDE issues to Bug Reports when appropriate
  • Epic 2 (Workflow Management): May use workflows for automated issue detection

Notes:

  • This is a PERPETUAL task - it never truly "completes" but is continuously worked on
  • Track progress with version markers for each maintenance cycle
  • Focus on maintaining codebase health rather than achieving "zero issues"
  • Some info-level issues may be acceptable if they don't impact functionality

E7:S01:T02 – Create maintenance task prioritization framework​

Input: Current maintenance task patterns and IDE-flagged issues
Deliverable: Prioritization framework for maintenance tasks
Dependencies: E7:S01:T01 (perpetual task provides context)
Blocker: None
Parallel Development Candidacy: Safe (can develop independently)

Approach:

  1. Analyze current maintenance task patterns
  2. Define prioritization criteria (severity, impact, effort)
  3. Create prioritization framework document
  4. Integrate with Kanban framework

Acceptance Criteria:

  • Prioritization framework documented
  • Criteria clearly defined (severity, impact, effort)
  • Integration with Kanban framework established
  • Examples demonstrate framework usage

E7:S01:T03 – Document maintenance workflow processes​

Input: Current maintenance practices and workflows
Deliverable: Documented maintenance workflow processes
Dependencies: E7:S01:T02 (prioritization framework)
Blocker: None
Parallel Development Candidacy: Safe (can develop independently)

Approach:

  1. Document current maintenance practices
  2. Define standard maintenance workflows
  3. Create workflow documentation
  4. Integrate with Kanban framework

Acceptance Criteria:

  • Maintenance workflow processes documented
  • Standard workflows defined
  • Integration with Kanban framework established
  • Examples demonstrate workflow usage

E7:S01:T04 – Integrate maintenance tasks with Kanban framework​

Input: Maintenance task patterns and Kanban framework
Deliverable: Integrated maintenance task tracking in Kanban
Dependencies: E7:S01:T01, E7:S01:T02, E7:S01:T03
Blocker: None
Parallel Development Candidacy: Safe (can develop independently)

Approach:

  1. Review Kanban framework integration points
  2. Design maintenance task tracking in Kanban
  3. Implement Kanban integration
  4. Document integration usage

Acceptance Criteria:

  • Maintenance tasks tracked in Kanban
  • Integration with Epic 4 (Kanban Framework) established
  • Documentation updated with integration details
  • Examples demonstrate Kanban usage for maintenance

E7:S01:T06 – Implement Update Changelog Workflow (UCW)​

Input: FR-057 Update Changelog Workflow, FR-025/FR-026 archival policies, RW validator contract
Deliverable: UCW workflow (docs + scripts) that trims CHANGELOG.md, archives older entries, and integrates with Release Workflow validation
Dependencies: FR-057, FR-025, FR-026
Blocker: None
Parallel Development Candidacy: Safe

Status: TODO
Priority: HIGH
Version Marker: v0.7.1.5+6 (RW-k filing)

Approach:

  1. Author UCW workflow assets (README, YAML, config) under workflow management package.
  2. Implement UCW runner (update_changelog_docs.py) enforcing retention + archival policy.
  3. Integrate UCW invocation into RW (post-step 3) and document SOP in release runbook and CHANGELOG policy section.
  4. Add regression tests covering retention thresholds, ordering, archive integrity, duplicate detection, and dry-run previews.
  5. Execute UCW to trim CHANGELOG.md, generate archive entries, and verify validators pass.
  6. Wire UCW outputs back into Kanban docs (epic/story/board) and perpetual changelog maintenance logs.

Acceptance Criteria:

  • Latest-only main changelog enforced (configurable retention, default 20 entries).
  • Archived entries gain backlinks and RW validator passes immediately after UCW run.
  • CLI supports --retention, --dry-run, --auto flags with clear reporting.
  • Documentation clearly distinguishes UCW vs UKW responsibilities and provides SOP.
  • Tests cover retention boundaries, ordering, duplicates, archive write failures, and dry-run safety.
  • Task tracked via T06-update-changelog-workflow.md with evidence of UCW execution logs.

E7:S01:T07 – Markdown Maintenance Workflow (MMW)​

Input: FR-058 Markdown Maintenance Workflow, E7:S01:T05 perpetual markdown task, documentation validator outputs
Deliverable: Deterministic workflow + tooling that triages RW markdown validation failures, distinguishes regressions vs legacy debt, and drives remediation cycles with auditable evidence
Dependencies: FR-058, Documentation Policy Framework, Release Runbook RW Step 8
Blocker: None
Parallel Development Candidacy: Safe

Status: TODO
Priority: HIGH
Version Marker: v0.7.1.6+2 (FR filing)

Approach:

  1. Author ICW artifacts (spec/test/plan) describing MMW phases, roles, CI hook contract, and evidence requirements.
  2. Extend documentation validator to emit scoped vs baseline findings; integrate with RW + MMW decision tree.
  3. Build checklist + log template under docs/maintenance/logs/mmw/ and wire to RW Step 8 fallback path.
  4. Execute initial MMW maintenance cycle targeting representative backlog slice; capture diff + log.
  5. Update Release Runbook, Kanban board, and Story references to include MMW instructions and status reporting.
  6. Coordinate with T05 to ensure perpetual markdown maintenance metrics get updated per cycle.
  7. Create a dedicated MMW Perpetual Task (E7:S01:T08 placeholder) that RW teams can update/run against whenever markdown debt blocks a release, ensuring each RW has an up-to-date maintenance checkpoint.

Acceptance Criteria:

  • Validator supports scoped/baseline modes with documented CLI usage.
  • RW runbook defines MMW trigger + evidence requirements; CI hook blocks releases lacking MMW log when baseline debt remains.
  • docs/maintenance/logs/mmw/ contains checklist/log entries for first maintenance cycle with before/after stats.
  • Kanban Story + task docs reference FR-058 and include completion markers once workflow is operational.
  • Perpetual markdown maintenance Task (T05) includes pointers to MMW cycle outputs as ongoing maintenance mechanism.

E7:S01:T08 – Task Doc Naming Standardization​

Input: User directive (2026-03-16) to adopt EddSddTdd-[Task Title].md naming, Documentation Policy Framework, Kanban board structure
Deliverable: Canonical naming standard applied to all task docs plus migration tooling/checklist to keep Release Workflow and Kanban references consistent
Dependencies: Documentation Policy Framework updates, Release Runbook references, Story/Epic file cross-links
Blocker: None
Parallel Development Candidacy: Safe

Status: TODO
Priority: HIGH
Version Marker: v0.7.1.6+3

Approach:

  1. Update Documentation Policy + Kanban board guide to codify the EddSddTdd-[title].md format (with 3-digit Task exception).
  2. Inventory all existing task files; generate mapping old→new names with traceability log.
  3. Build/execute rename plan (script or documented steps) ensuring links in Story/Epic/FR/kanban board update atomically.
  4. Add validator or lint rule to flag future deviations.
  5. Provide RW guidance describing how task renames impact step 4 updates + evidence storage.
  6. Publish migration completion log under docs/maintenance/logs/mmw/ or similar for audit.

Acceptance Criteria:

  • Documentation policy + runbook explicitly reference the new naming scheme and exceptions.
  • All task files under docs/project-management/kanban/epics/** follow the new naming format (or are queued with migration checklist).
  • Kanban board/task references resolve correctly after renames; validator confirms no broken links.
  • A lint/validation hook exists to prevent regressions.
  • Migration summary captured (versions, files renamed, blockers) for future audits.

Acceptance Criteria​

  • Perpetual task established for IDE-flagged issues
  • Maintenance task prioritization framework created
  • Maintenance workflow processes documented
  • Integration with Epic 4 (Kanban Framework) established

Dependencies​

Coordinates With:

  • Epic 4 (Kanban Framework): Uses Kanban for tracking maintenance tasks
  • Epic 2 (Workflow Management): May use workflows for maintenance automation
  • Epic 6 (BR Implementation): May convert IDE-flagged issues to Bug Reports when appropriate

References​

  • packages/frameworks/kanban/templates/CANONICAL_EPICS.md - Canonical epic definitions
  • docs/project-management/kanban/epics/Epic-7/Epic-7.md - Epic 7 overview
  • docs/project-management/kanban/epics/Epic-4/Epic-4.md - Kanban Framework epic

Last updated: 2026-03-15 (v0.7.1.5+6 – Story reopened for UCW workflow task)