mime-todo-spec/dist/markdown

Introduction

This document defines the canonical format, semantics, and processing rules for the repository-root TODO file. The file is a human-friendly, append-only (allowing modifications) issue tracker that is parsed by TypeScript tooling using a MIME envelope added at parse time.

The raw TODO file is not a MIME document. A preprocessor wraps it into a valid multipart/mixed MIME message before parsing.

Raw File Structure

The raw TODO file consists of a sequence of parts, each beginning with:

--ISSUE
Content-Type: <mime-type>

Valid part types are:

• application/sprints — defines sprint metadata
• application/issue — defines a single issue

Parts may appear in any order in the raw file. The preprocessor will reorder them so that the application/sprints part appears first.

MIME Envelope (Added by Preprocessor)

Before parsing, the preprocessor wraps the raw file into a MIME multipart message.

Prolog added by the preprocessor:

MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="ISSUE"

Each raw --ISSUE boundary becomes a MIME boundary. The preprocessor extracts each part’s Content-Type and body, reorders parts, and emits a final closing boundary:

--ISSUE--

The resulting MIME message is parsed using a standard MIME parser.

Part: application/sprints

This part defines sprint metadata.

The body MUST begin with:

Sprints:

followed by one or more sprint entries.

Sprint Entry Forms

Both compact and expanded forms are valid.

Compact form:

- Name: Sprint 1
  Range: 2026-02-01..2026-02-14

Expanded form:

-
  Name: Sprint 1
  Range: 2026-02-01..2026-02-14

Sprint Entry Grammar

A sprint entry begins at a line matching:

^\s*-\s*(Name:.*)?$

Key–value lines inside an entry match:

^\s+[A-Za-z][A-Za-z0-9]*:\s*(.*)$

Required keys:

• Name: <string>
• Range: <YYYY-MM-DD>..<YYYY-MM-DD>

The Range defines a closed interval [start, end].

Part: application/issue

Each issue is represented as a structured block with strict field ordering.

Required Field Order

The following fields MUST appear in exactly this order:

ID: <integer>
Type: <feature|bugfix|hotfix>
Title: <short title>
Status: <open|in-progress|done|hold|cancelled>
Priority: <low|medium|high>
Created: <YYYY-MM-DD>
Relationships: <comma-separated list or empty>
DueStart: <YYYY-MM-DD>        # OPTIONAL
DueEnd: <YYYY-MM-DD>          # OPTIONAL
Description: <first line>
             <continuation lines>

Field Semantics

• ID: unique integer, strictly increasing.

• Type: one of feature, bugfix, hotfix. * feature and bugfix issues target the integration branch (develop). * hotfix issues target the stable branch (main or master).

• Status: one of open, in-progress, done, hold, cancelled.

• Priority: one of low, medium, high.

• Created: ISO date.

• Relationships: * Empty:

  Relationships:
  

  • Or list:

    Relationships: dependsOn:43, relatesTo:10
    

  • Valid kinds: dependsOn, relatesTo, blocks, causedBy.

• DueStart / DueEnd: * Optional. * If only one is present, the other is implicitly equal to it.

Description Block

• The first line appears on the same line as Description:.
• Continuation lines: * Must begin with whitespace. * Must align indentation consistently.
• No blank lines allowed inside the description block.

Body

Any lines after the description block are considered free-form body text. The body MUST NOT contain another ID: field or a MIME boundary.

Git Workflow Rules

Branch Naming

Branches for issues MUST follow:

<Type>/<ID>

Examples:

feature/12
bugfix/7

Modification Rules

• All edits to TODO MUST occur on develop.
• Feature/bugfix/hotfix branches MUST rebase changes from develop.

Branch Lifecycle

• A branch MUST NOT exist before its issue is created.
• A branch MUST be named exactly <Type>/<ID>.
• A branch MAY merge only when the issue status is done.

Sprint Membership Logic

Given:

• Sprint interval [S_start, S_end]
• Issue interval [I_start, I_end]

Normalization

• Only DueEnd → I_start = I_end = DueEnd
• Only DueStart → I_start = I_end = DueStart
• Neither → issue is not sprint-bound

Membership Condition

An issue belongs to a sprint if:

I_start ≤ S_end AND I_end ≥ S_start

Current Sprint for Date D

1. All sprints where S_start ≤ D ≤ S_end.
2. If multiple match, choose the one with the latest S_start.
3. If none match, no active sprint.

Preprocessor Requirements

The preprocessor MUST:

• Read the raw TODO file.

• Split into parts using --ISSUE.

• Extract each part’s Content-Type and body.

• Reorder parts so that: * application/sprints appears first (if present) * All application/issue parts follow in original order

• Emit a MIME message with: * MIME-Version: 1.0 * Content-Type: multipart/mixed; boundary="ISSUE" * Each part wrapped as:

  --ISSUE
  Content-Type: <type>
  
  <body>
  

  • Final boundary:

    --ISSUE--
    

Parser Requirements

The parser MUST:

• Use a MIME parser to extract parts.
• Dispatch based on Content-Type: * application/sprints → sprint parser * application/issue → issue parser
• Enforce: * Field order * Required fields * Description indentation rules * Sprint entry grammar
• Produce a TodoFile object:

  {
    sprints: Sprint[],
    issues: Issue[]
  }
  

Error Handling

The parser MUST reject:

• Missing or malformed Content-Type headers
• Unknown MIME types
• Missing required issue fields
• Incorrect field order
• Invalid sprint ranges
• Invalid date formats
• Multiple application/sprints parts
• Duplicate issue IDs

Errors SHOULD include line numbers when possible.

Extensibility

Future part types MAY be added using:

application/<subtype>

Examples:

• application/metadata
• application/changelog
• application/epilog

The preprocessor MUST preserve unknown part types but MUST NOT reorder them.