mime-todo-spec/build/markdown/README.md

Document

Version

0.2.1.dev2+g84ea63866

Status

Draft

Author

Tiara Rodney <tiara@byteb4rb1e.me>

License

CC BY-ND 4.0

Abstract

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.

Specification

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/modules — defines the repository module structure
• application/bugzilla — defines Bugzilla product/component mappings
• application/issue — defines a single issue

Parts may appear in any order in the raw file. The preprocessor will reorder them so that application/sprints appears first, followed by application/modules, then application/bugzilla, then all application/issue parts in original order.

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/modules

This part defines the repository’s logical module structure. Each module maps a name to an optional repository-relative path.

At most one application/modules part MAY appear. Multiple application/modules parts MUST be rejected.

The body MUST begin with:

Modules:

followed by one or more module entries.

Module Entry Forms

Compact form:

- Name: Specification
  Path: src

Expanded form:

-
  Name: Specification
  Path: src

A module without a path (logical grouping):

- Name: Documentation

Module Entry Grammar

A module 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> — unique module identifier.

Optional keys:

• Path: <repo-relative-path> — path relative to repository root. If omitted, the module is a logical grouping without a fixed location.

Part: application/bugzilla

This part defines a unidirectional mapping from repository modules to Bugzilla products and components. The TODO file is the source of truth; Bugzilla is a downstream mirror.

At most one application/bugzilla part MAY appear. Multiple application/bugzilla parts MUST be rejected.

An application/bugzilla part MUST NOT appear unless an application/modules part is also present.

Required Fields

URL: <bugzilla-rest-api-url>
Mappings:
        - Module: <module-name>
          Product: <bugzilla-product>
          Component: <bugzilla-component>

• URL: the base URL to the Bugzilla REST API.
• Mappings: one or more entries mapping a module name to a Bugzilla product and component. Every Module value MUST reference a module defined in the application/modules part.

Product and component names containing spaces or special characters are permitted; tooling MUST URL-encode them when constructing API requests.

Mapping Entry Grammar

A mapping entry begins at a line matching:

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

Required keys:

• Module: <string> — references a module name.
• Product: <string> — Bugzilla product name.
• Component: <string> — Bugzilla component name.

Sync Model

Synchronization is unidirectional: TODO → Bugzilla. The TODO file is the canonical source of truth.

When a Bugzilla bug is created for a TODO issue, the bug’s url field MUST be set to a resolvable URL pointing to the TODO file on the integration branch. The URL format is host-dependent:

• Bitbucket: <repo-url>/src/<branch>/TODO#<issue-id>
• GitHub: <repo-url>/blob/<branch>/TODO#<issue-id>
• GitLab: <repo-url>/-/blob/<branch>/TODO#<issue-id>

The branch in the URL MUST be the integration branch (develop), regardless of which branch the push is initiated from.

Transition commit messages are pushed as Bugzilla comments. Each comment is tagged with git-<short-hash> (first 7 characters of the commit hash) to prevent duplicate pushes. A comment tag is applied only after the comment and any associated status update have both succeeded.

Work commits from issue branches are also pushed as Bugzilla comments, forming a threaded work log. Work comments:

• MUST NOT be pushed unless the issue status is in-progress.
• MUST NOT follow a done transition comment.

Comment format (Markdown):

**<commit-subject>**

<commit-body>

[`<short-hash>`](<commit-url>)

The commit URL format is host-dependent:

• Bitbucket: <repo-url>/commits/<hash>
• GitHub: <repo-url>/commit/<hash>
• GitLab: <repo-url>/-/commit/<hash>

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>
Module: <module-name>             # OPTIONAL
Relationships: <comma-separated list or empty>
DueStart: <YYYY-MM-DD>           # OPTIONAL
DueEnd: <YYYY-MM-DD>             # OPTIONAL
Description: <first line>
             <continuation lines>
AcceptanceCriteria: <first line>  # OPTIONAL, set at in-progress
                    <continuation lines>
Acceptance: <first line>          # OPTIONAL, set at done
            <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.

• Module: optional. When present, MUST reference a module name defined in the application/modules part. If no application/modules part exists, the field is ignored.

• Relationships: * Empty:

  Relationships:
  

  • Or list:

    Relationships: dependsOn:43, relatesTo:10
    

  • Valid kinds: dependsOn, relatesTo, blocks.
  • All relationship target IDs MUST reference existing issue IDs in the same TODO file. A target that does not exist MUST be rejected.
  • A relationship targeting a cancelled issue SHOULD produce a warning (stale reference).

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

• AcceptanceCriteria: * Optional. Set when transitioning to in-progress. * Defines what must be true for the issue to be considered done. * Follows the same indentation rules as Description. * AcceptanceCriteria: occupies 20 characters. Content begins at column 21. * Continuation lines MUST be indented with 20 spaces. * Immutable after being set.

• Acceptance: * Optional. Set when transitioning to done. * Records what was delivered against the acceptance criteria. * Follows the same indentation rules as Description. * Acceptance: occupies 12 characters. Content begins at column 13. * Continuation lines MUST be indented with 12 spaces. * Immutable after being set.

Description Block

• The first line appears on the same line as Description:.
• Description: occupies 13 characters. Content begins at column 14.
• Continuation lines MUST be indented with 13 spaces, aligning with column 14.
• Lines MUST NOT exceed 80 columns. Long text MUST be word-wrapped at the 80-column boundary by the serializer.
• 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.

Issue Immutability

The Description field is immutable after the issue is created. To change the scope of an issue, the issue MUST be cancelled and a new issue created.

Fields that MAY change after creation:

• Status (via transition commits)
• AcceptanceCriteria (set once at in-progress transition, immutable after)
• Acceptance (set once at done transition, immutable after)

Fields that MUST NOT change after creation:

• ID, Type, Title, Priority, Created, Description, Module

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.

Status Transition Rules

Valid Transitions

Not all status changes are permitted. The following table defines the complete set of valid transitions:

From	Allowed transitions
open	in-progress, hold, cancelled
in-progress	done, hold, open, cancelled
hold	open, in-progress, cancelled
done	open
cancelled	open

Any transition not listed MUST be rejected. A no-op transition (same status) is permitted.

Transition Commits

Each status transition MUST be recorded as a dedicated commit that modifies only the TODO file. The commit message MUST follow this format:

todo(<ID>): <status>

<body>

Where:

• <ID> is the issue’s integer ID.
• <status> is the new status value.
• <body> is a description whose content depends on the transition. The body is required for all transitions except open, where it is optional (see Transition Details).

Transition Details

``todo(): open`` — Issue creation.

• Branch: MUST be on develop.
• Body: optional. If provided, it MUST match the issue’s Description field. Because the description is already recorded in the TODO file itself, the body MAY be omitted to avoid duplication. When omitted, the commit consists of only the header line.

``todo(): in-progress`` — Start work.

• Branch: MUST be on develop.
• Body: the acceptance criteria for the issue.
• The AcceptanceCriteria field on the issue is set from the body of this commit. It defines what must be true for the issue to be considered done.
• After this commit, the issue branch <Type>/<ID> may be created from develop.

``todo(): done`` — Complete work.

• Branch: MUST be on <Type>/<ID>.
• Body: acceptance statement — what was delivered against the acceptance criteria.
• The Acceptance field on the issue is set from the body of this commit.
• After this commit, the issue branch may be merged into develop using --no-ff.

``todo(): hold`` — Pause work.

• Branch: MUST be on <Type>/<ID>.
• Body: reason for holding.

``todo(): cancelled`` — Cancel issue.

• Branch: MUST be on develop or <Type>/<ID>.
• Body: reason for cancellation.
• If the issue is open (no branch exists), the commit is on develop.
• If the issue is in-progress or hold (branch exists), the commit may be on the issue branch.

Transition-Only Constraint

A transition commit MUST modify only the TODO file. No other files may be included in the commit. This ensures that every transition is independently auditable.

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) * application/modules appears second (if present) * application/bugzilla appears third (if present) * All application/issue parts follow in original order * Unknown part types are preserved in original order after issues

• 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/modules → module parser * application/bugzilla → Bugzilla tracker parser * application/issue → issue parser
• Enforce: * Field order * Required fields * Description indentation and column rules * Sprint entry grammar * Module entry grammar * Module references: if application/modules is present, every issue Module field MUST reference a defined module name * Bugzilla mapping references: if application/bugzilla is present, every mapping Module value MUST reference a defined module name * Relationship targets: every target ID MUST reference an existing issue ID * Stale relationships: a relationship targeting a cancelled issue SHOULD produce a warning
• Produce a TodoFile object:

  {
    sprints: Sprint[],
    issues: Issue[],
    modules?: Module[],
    bugzilla?: BugzillaTracker
  }
  

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
• Multiple application/modules parts
• Multiple application/bugzilla parts
• application/bugzilla without application/modules
• Issue Module referencing undefined module
• Bugzilla mapping Module referencing undefined module
• Relationship target referencing non-existent issue ID
• Invalid status transition
• Duplicate issue IDs

The parser SHOULD warn on:

• Relationship targeting a cancelled issue (stale reference)

Errors SHOULD include line numbers when possible.

CLI Reference

The @byteb4rb1e/mime-todo CLI is the reference implementation of this specification. It enforces all format, validation, transition, and commit rules defined above. Both developers and automated agents MUST use the CLI to interact with the TODO file rather than editing it manually.

Install:

npm install -g @byteb4rb1e/mime-todo

Issue Lifecycle

Creating an issue (MUST be on develop):

mime-todo create --type feature --title "Add login" --plan "Implement OAuth2 flow"

This produces a todo(<ID>): open commit modifying only the TODO file. The --plan text becomes the issue’s Description field. The commit has no body because the description is already recorded in the issue itself.

Starting work (MUST be on develop):

mime-todo start <id> --acceptance-criteria "What must be true for this to be done"

This produces a todo(<ID>): in-progress commit. The --acceptance-criteria text is stored in the issue’s AcceptanceCriteria field and becomes the commit body. The issue branch <Type>/<ID> may then be created by the user:

git checkout -b feature/<id>

Completing work (MUST be on <Type>/<ID>):

mime-todo done <id> --acceptance "What was delivered against the criteria"

This produces a todo(<ID>): done commit. The --acceptance text is stored in the issue’s Acceptance field and becomes the commit body. The issue branch may then be merged into develop using --no-ff.

Holding an issue (MUST be on <Type>/<ID>):

mime-todo hold <id> --reason "Blocked on dependency"

Cancelling an issue (MUST be on develop or <Type>/<ID>):

mime-todo cancel <id> --reason "Superseded by issue #5"

The CLI validates the current branch and the status transition before committing. Invalid transitions or wrong branches are rejected with an error.

Read-Only Commands

These commands do not modify the TODO file and may be run from any branch:

mime-todo list                     # list all issues
mime-todo show <id>                # show full issue details
mime-todo sprints                  # list all sprints
mime-todo issues-in-sprint <name>  # list issues in a sprint

Bugzilla Integration

Initializing products and components:

mime-todo init                                         # check what exists
mime-todo init --dry-run                               # preview changes
mime-todo init --confirm --assignee user@example.com   # create missing items

The init command reads the application/bugzilla part and ensures all referenced products and components exist on the Bugzilla server.

Pushing commits to Bugzilla:

mime-todo push              # push all unpushed commits
mime-todo push HEAD~3       # push only the last 3 commits
mime-todo push --dry-run    # preview without pushing
mime-todo push --strategy full   # re-scan all bugs

On issue branches, push posts work commits as Bugzilla comments. Work comments are only permitted when the issue is in-progress and no done transition has been recorded.

On develop, push posts transition commits as Bugzilla comments and updates the bug’s status accordingly.

Each comment includes a clickable link to the commit and is tagged with git-<short-hash> for idempotency. Running push multiple times is safe.

Agent Usage

Agents MUST use the CLI for all TODO file interactions:

• Creating issues: mime-todo create
• Transitioning issues: mime-todo start, mime-todo done, mime-todo hold, mime-todo cancel
• Querying: mime-todo list, mime-todo show, mime-todo sprints
• Syncing to Bugzilla: mime-todo push

Agents MUST NOT:

• Edit the TODO file directly.
• Construct transition commits manually.
• Modify issue fields other than Status (and only via the CLI).
• Push to Bugzilla outside of the CLI’s push command.

Extensibility

Defined part types:

• application/sprints — sprint metadata
• application/modules — repository module structure
• application/bugzilla — Bugzilla product/component mappings
• application/issue — single issue

Future part types MAY be added using:

application/<subtype>

The preprocessor MUST preserve unknown part types but MUST NOT reorder them. Unknown types are placed after all defined types.

Changelog

• chore: update document meta by Tiara Rodney at 2026-03-22 02:18:32
• Merge branch ‘bugfix/12’ by Tiara Rodney at 2026-03-22 01:42:38
• fix: replace todo with mime-todo in all CLI references by Tiara Rodney at 2026-03-22 01:42:32
• Merge branch ‘feature/10’ by Tiara Rodney at 2026-03-22 01:38:33
• spec: define AcceptanceCriteria and Acceptance fields on issues by Tiara Rodney at 2026-03-22 01:38:29