TASK-345 - Configurable ID prefix system (task-, custom-)

[MrLesk]

Greptile Summary

This PR implements a configurable ID prefix system that allows tasks to use task- (default) or custom prefixes (e.g., JIRA-, issue-), while drafts use draft- prefix. IDs are now uppercase (TASK-123, DRAFT-5) while filenames remain lowercase (task-123.md, draft-5.md).

Major changes:

• Created src/utils/prefix-config.ts with comprehensive prefix utilities (normalizeId, generateNextId, buildGlobPattern, etc.)
• Added EntityType enum to support type-aware ID generation across tasks, drafts, docs, and decisions
• Implemented one-time migration (src/core/prefix-migration.ts) that renames legacy task-*.md files in drafts folder to draft-*.md
• Updated promote/demote operations to reassign IDs (draft → new task ID, task → new draft ID) rather than just moving files
• Added --task-prefix option to backlog init command (first-time only, read-only after)
• Updated file system operations, task loaders, search service, and UI components for prefix awareness
• Renamed all draft files in backlog/drafts/ from task-X to draft-X format

Test coverage:

• 370+ lines of prefix-config tests covering all edge cases
• 299+ lines of migration tests
• All filesystem, CLI, and integration tests updated for new prefix system

Issue found:

• src/cli.ts:2149 uses EntityType.Task instead of EntityType.Draft for draft creation, with an outdated TODO comment claiming file operations aren't ready (they are)

Confidence Score: 4/5

• This PR is well-implemented with comprehensive tests, but has one logic bug in draft creation that needs fixing
• Score reflects excellent architecture (EntityType abstraction, comprehensive prefix utilities, proper migration), thorough test coverage (669 new test lines), and systematic refactoring across all layers. However, the draft creation bug (using wrong EntityType) prevents a score of 5, as it would cause drafts to generate TASK-X IDs instead of DRAFT-X IDs when created via CLI
• Pay close attention to src/cli.ts:2149 - the draft creation logic uses wrong EntityType which will cause runtime behavior mismatch

Important Files Changed

Filename	Overview
src/cli.ts	CLI updated for prefix config support; outdated TODO comment at line 2149 should be removed as draft operations are already updated
src/utils/prefix-config.ts	New comprehensive utility module for prefix handling with extensive helper functions; well-structured and thoroughly tested
src/core/prefix-migration.ts	One-time migration for draft files from task- to draft- prefix; handles edge cases cleanly with proper error handling
src/core/backlog.ts	Core logic updated for entity-type-based ID generation; properly integrates prefix config with cross-branch task handling
src/file-system/operations.ts	File operations updated for configurable prefixes; promote/demote now correctly reassign IDs as designed
src/core/init.ts	Init command enhanced to support custom task prefix configuration during first initialization

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI
    participant Core
    participant PrefixConfig
    participant FileSystem
    participant Migration

    Note over User,Migration: First-time initialization with custom prefix
    User->>CLI: backlog init --task-prefix JIRA
    CLI->>Core: initializeProject(config)
    Core->>FileSystem: ensureBacklogStructure()
    Core->>FileSystem: saveConfig({prefixes: {task: "JIRA", draft: "draft"}})
    Core-->>CLI: Project initialized
    CLI-->>User: Success

    Note over User,Migration: Existing project load (migration check)
    User->>CLI: backlog task list
    CLI->>Core: ensureConfigLoaded()
    Core->>FileSystem: loadConfig()
    Core->>Migration: needsDraftPrefixMigration(config)
    alt No prefixes section in config
        Migration-->>Core: true
        Core->>Migration: migrateDraftPrefixes(fs)
        Migration->>FileSystem: listDrafts()
        FileSystem-->>Migration: [task-1.md, task-2.md]
        loop For each task-*.md file
            Migration->>FileSystem: parseTask(content)
            Migration->>PrefixConfig: generateNextId(existingIds, "draft")
            PrefixConfig-->>Migration: DRAFT-1
            Migration->>FileSystem: saveDraft({id: "DRAFT-1", ...})
            Migration->>FileSystem: unlink(task-1.md)
        end
        Migration->>FileSystem: saveConfig({prefixes: {...}})
    else Has prefixes section
        Migration-->>Core: false
    end

    Note over User,Migration: Creating a draft
    User->>CLI: backlog draft create "New Feature"
    CLI->>Core: generateNextId(EntityType.Draft)
    Core->>PrefixConfig: getPrefixForType(Draft)
    PrefixConfig-->>Core: "draft"
    Core->>FileSystem: listDrafts()
    Core->>PrefixConfig: generateNextId(existingIds, "draft")
    PrefixConfig-->>Core: DRAFT-5
    CLI->>Core: createDraft({id: "DRAFT-5", ...})
    Core->>FileSystem: saveDraft(task)
    FileSystem->>PrefixConfig: normalizeId("DRAFT-5", "draft")
    PrefixConfig-->>FileSystem: DRAFT-5
    FileSystem->>PrefixConfig: idForFilename("DRAFT-5")
    PrefixConfig-->>FileSystem: draft-5
    FileSystem-->>Core: draft-5 - New Feature.md
    Core-->>User: Created draft DRAFT-5

    Note over User,Migration: Promoting draft to task
    User->>CLI: backlog draft promote DRAFT-5
    CLI->>Core: promoteDraft("DRAFT-5")
    Core->>FileSystem: loadDraft("DRAFT-5")
    FileSystem->>PrefixConfig: normalizeId("DRAFT-5", "draft")
    FileSystem-->>Core: {id: "DRAFT-5", ...}
    Core->>FileSystem: listTasks()
    Core->>PrefixConfig: generateNextId(existingIds, "JIRA")
    PrefixConfig-->>Core: JIRA-123
    Core->>FileSystem: saveTask({id: "JIRA-123", ...})
    FileSystem->>PrefixConfig: idForFilename("JIRA-123")
    PrefixConfig-->>FileSystem: jira-123
    Core->>FileSystem: unlink(draft-5.md)
    Core-->>User: Promoted to JIRA-123

Loading

[greptile-apps]

_{90 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 121fd60627

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".