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

# Document

Version
: 0.2.1.dev2+g84ea63866

Status
: Draft

Author
: Tiara Rodney <[tiara@byteb4rb1e.me](mailto:tiara@byteb4rb1e.me)>

License
: [CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0/deed.en)

# 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:

```default
--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:

```default
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:

```default
--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:

```default
Sprints:
```

followed by one or more sprint entries.

### Sprint Entry Forms

Both compact and expanded forms are valid.

Compact form:

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

Expanded form:

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

### Sprint Entry Grammar

A sprint entry begins at a line matching:

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

Key–value lines inside an entry match:

```default
^\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:

```default
Modules:
```

followed by one or more module entries.

### Module Entry Forms

Compact form:

```default
- Name: Specification
  Path: src
```

Expanded form:

```default
-
  Name: Specification
  Path: src
```

A module without a path (logical grouping):

```default
- Name: Documentation
```

### Module Entry Grammar

A module entry begins at a line matching:

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

Key–value lines inside an entry match:

```default
^\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

```default
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:

```default
^\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):

```default
**<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:

```default
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:
  ```default
  Relationships:
  ```

  * Or list:
    ```default
    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:

```default
<Type>/<ID>
```

Examples:

```default
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:

```default
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(<ID>): 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(<ID>): 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(<ID>): 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(<ID>): hold\`\`** — Pause work.

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

**\`\`todo(<ID>): 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:

```default
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:
  ```default
  --ISSUE
  Content-Type: <type>

  <body>
  ```

  * Final boundary:
    ```default
    --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:
  ```default
  {
    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:

```default
npm install -g @byteb4rb1e/mime-todo
```

### Issue Lifecycle

Creating an issue (MUST be on `develop`):

```default
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`):

```default
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:

```default
git checkout -b feature/<id>
```

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

```default
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>`):

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

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

```default
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:

```default
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:

```default
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:

```default
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:

```default
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*