update

AGENTS.md

@@ -28,11 +28,66 @@ If `dist/markdown/` is not available locally, the specification
 - Issue part format (`application/issue`): field ordering, field semantics,
   valid values for Type, Status, Priority, and Relationships
 - Sprint part format (`application/sprints`): entry grammar, date ranges
-- Description block and body grammar
+- Module part format (`application/modules`): module names and paths
+- Bugzilla tracker part format (`application/bugzilla`): product/component
+  mappings, sync model, comment format
+- Description block and body grammar (80-column wrap, column 14 indent)
+- Issue immutability rules
+- Status transition state machine and commit conventions
 - Branch naming and lifecycle rules tied to issue Type and Status
 - Sprint membership logic
 - Preprocessor and parser requirements
 - Error handling requirements
+- CLI reference for spec-compliant issue management
+
+## Interacting with the TODO File
+
+Agents MUST use the `@byteb4rb1e/mime-todo` CLI for all interactions
+with the `TODO` file. Do NOT edit the file directly or construct
+transition commits manually.
+
+### Issue Lifecycle
+
+```sh
+# Create an issue (must be on develop)
+todo create --type feature --title "Title" --plan "Description"
+
+# Start work (must be on develop)
+todo start <id> --plan "Planned approach"
+# Then create the branch: git checkout -b <type>/<id>
+
+# Complete work (must be on <type>/<id>)
+todo done <id> --summary "What was delivered"
+
+# Hold or cancel
+todo hold <id> --reason "Why"
+todo cancel <id> --reason "Why"
+```
+
+### Querying
+
+```sh
+todo list                     # list all issues
+todo show <id>                # show issue details
+todo sprints                  # list sprints
+todo issues-in-sprint <name>  # issues in a sprint
+```
+
+### Bugzilla Integration
+
+```sh
+todo init                     # check products/components exist
+todo push                     # push commits to Bugzilla
+todo push --dry-run           # preview
+```
+
+### What Agents MUST NOT Do
+
+- Edit the `TODO` file directly.
+- Construct `todo(<ID>): <status>` commits manually.
+- Modify issue fields other than `Status` (and only via the CLI).
+- Push to Bugzilla outside of `todo push`.
+- Modify the specification files.
 
 ## Rules for Agents
 

dist/markdown/AGENTS.md

@@ -28,11 +28,66 @@ If `dist/markdown/` is not available locally, the specification
 - Issue part format (`application/issue`): field ordering, field semantics,
   valid values for Type, Status, Priority, and Relationships
 - Sprint part format (`application/sprints`): entry grammar, date ranges
-- Description block and body grammar
+- Module part format (`application/modules`): module names and paths
+- Bugzilla tracker part format (`application/bugzilla`): product/component
+  mappings, sync model, comment format
+- Description block and body grammar (80-column wrap, column 14 indent)
+- Issue immutability rules
+- Status transition state machine and commit conventions
 - Branch naming and lifecycle rules tied to issue Type and Status
 - Sprint membership logic
 - Preprocessor and parser requirements
 - Error handling requirements
+- CLI reference for spec-compliant issue management
+
+## Interacting with the TODO File
+
+Agents MUST use the `@byteb4rb1e/mime-todo` CLI for all interactions
+with the `TODO` file. Do NOT edit the file directly or construct
+transition commits manually.
+
+### Issue Lifecycle
+
+```sh
+# Create an issue (must be on develop)
+todo create --type feature --title "Title" --plan "Description"
+
+# Start work (must be on develop)
+todo start <id> --plan "Planned approach"
+# Then create the branch: git checkout -b <type>/<id>
+
+# Complete work (must be on <type>/<id>)
+todo done <id> --summary "What was delivered"
+
+# Hold or cancel
+todo hold <id> --reason "Why"
+todo cancel <id> --reason "Why"
+```
+
+### Querying
+
+```sh
+todo list                     # list all issues
+todo show <id>                # show issue details
+todo sprints                  # list sprints
+todo issues-in-sprint <name>  # issues in a sprint
+```
+
+### Bugzilla Integration
+
+```sh
+todo init                     # check products/components exist
+todo push                     # push commits to Bugzilla
+todo push --dry-run           # preview
+```
+
+### What Agents MUST NOT Do
+
+- Edit the `TODO` file directly.
+- Construct `todo(<ID>): <status>` commits manually.
+- Modify issue fields other than `Status` (and only via the CLI).
+- Push to Bugzilla outside of `todo push`.
+- Modify the specification files.
 
 ## Rules for Agents
 

dist/markdown/README.md

@@ -20,10 +20,14 @@ 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 the `application/sprints` part appears first.
+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)
 
@@ -99,6 +103,155 @@ Required keys:
 
 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.
@@ -114,6 +267,7 @@ 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
@@ -130,6 +284,9 @@ Description: <first line>
 * **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
@@ -140,7 +297,11 @@ Description: <first line>
     ```default
     Relationships: dependsOn:43, relatesTo:10
     ```
-  * Valid kinds: `dependsOn`, `relatesTo`, `blocks`, `causedBy`.
+  * 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.
@@ -148,9 +309,10 @@ Description: <first line>
 ### Description Block
 
 * The first line appears on the same line as `Description:`.
-* Continuation lines:
-  \* Must begin with whitespace.
-  \* Must align indentation consistently.
+* `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
@@ -158,6 +320,20 @@ Description: <first line>
 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
@@ -186,6 +362,83 @@ bugfix/7
 * 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 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:
@@ -222,7 +475,10 @@ The preprocessor MUST:
 * 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"`
@@ -246,17 +502,26 @@ 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 rules
+  \* 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[]
+    issues: Issue[],
+    modules?: Module[],
+    bugzilla?: BugzillaTracker
   }
   ```
 
@@ -271,22 +536,159 @@ The parser MUST reject:
 * 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
+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`):
+
+```default
+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:
+
+```default
+git checkout -b feature/<id>
+```
+
+Completing work (MUST be on `<Type>/<ID>`):
+
+```default
+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>`):
+
+```default
+todo hold <id> --reason "Blocked on dependency"
+```
+
+Cancelling an issue (MUST be on `develop` or `<Type>/<ID>`):
+
+```default
+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
+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:
+
+```default
+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:
+
+```default
+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:
 
 ```default
 application/<subtype>
 ```
 
-Examples:
-
-* `application/metadata`
-* `application/changelog`
-* `application/epilog`
-
 The preprocessor MUST preserve unknown part types but MUST NOT reorder them.
+Unknown types are placed after all defined types.

src/README.rst

@@ -27,10 +27,14 @@ The raw ``TODO`` file consists of a sequence of *parts*, each beginning with::
 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 the ``application/sprints`` part appears first.
+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)
@@ -99,6 +103,148 @@ Required keys:
 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``
 ===========================
 
@@ -115,6 +261,7 @@ The following fields MUST appear in exactly this order::
     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
@@ -131,6 +278,9 @@ Field Semantics
 * **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::
 
@@ -140,7 +290,11 @@ Field Semantics
 
         Relationships: dependsOn:43, relatesTo:10
 
-  * Valid kinds: ``dependsOn``, ``relatesTo``, ``blocks``, ``causedBy``.
+  * 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.
@@ -149,9 +303,10 @@ Description Block
 -----------------
 
 * The first line appears on the same line as ``Description:``.
-* Continuation lines:
-  * Must begin with whitespace.
-  * Must align indentation consistently.
+* ``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
@@ -160,6 +315,21 @@ 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
 ==================
@@ -190,6 +360,96 @@ Branch Lifecycle
 * 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
 =======================
 
@@ -213,7 +473,7 @@ 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``.
@@ -230,7 +490,10 @@ The preprocessor MUST:
 * 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"``
@@ -254,17 +517,26 @@ 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 rules
+  * 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[]
+        issues: Issue[],
+        modules?: Module[],
+        bugzilla?: BugzillaTracker
       }
 
 
@@ -280,22 +552,145 @@ The parser MUST reject:
 * 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>
 
-Examples:
-
-* ``application/metadata``
-* ``application/changelog``
-* ``application/epilog``
-
 The preprocessor MUST preserve unknown part types but MUST NOT reorder them.
+Unknown types are placed after all defined types.