mime-todo-spec/src/README.rst

.. toctree::
   :hidden:

   AGENTS

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

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.

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)

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:

.. list-table::
   :header-rows: 1
   :widths: 20 50

   * - 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 required description whose content depends on the
  transition.

Transition Details
------------------

**``todo(<ID>): open``** — Issue creation.

* Branch: MUST be on ``develop``.
* Body: description of what needs to be done (becomes the issue's
  ``Description`` field).

**``todo(<ID>): in-progress``** — Start work.

* Branch: MUST be on ``develop``.
* Body: high-level description of the planned approach.
* 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: high-level summary of what was delivered.
* 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::

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

    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.

Starting work (MUST be on ``develop``)::

    todo start <id> --plan "High-level approach description"

This produces a ``todo(<ID>): in-progress`` commit. The issue branch
``<Type>/<ID>`` may then be created by the user::

    git checkout -b feature/<id>

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

    todo done <id> --summary "Summary of what was delivered"

This produces a ``todo(<ID>): done`` commit. The issue branch may then be
merged into ``develop`` using ``--no-ff``.

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

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

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

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

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

Bugzilla Integration
--------------------

Initializing products and components::

    todo init                                         # check what exists
    todo init --dry-run                               # preview changes
    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::

    todo push              # push all unpushed commits
    todo push HEAD~3       # push only the last 3 commits
    todo push --dry-run    # preview without pushing
    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: ``todo create``
* Transitioning issues: ``todo start``, ``todo done``, ``todo hold``,
  ``todo cancel``
* Querying: ``todo list``, ``todo show``, ``todo sprints``
* Syncing to Bugzilla: ``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.