diff --git a/build/markdown/AGENTS.md b/build/markdown/AGENTS.md new file mode 100644 index 0000000..b60dae6 --- /dev/null +++ b/build/markdown/AGENTS.md @@ -0,0 +1,103 @@ +# MIME TODO Specification — Agent Instructions + +This directory contains the MIME TODO specification, which defines the +canonical format for repository-root `TODO` issue tracker files. + +## Consuming the Specification + +The agent-consumable specification is located at: + +```default +build/markdown/ +``` + +Agents MUST read the specification from `build/markdown/` for programmatic +access. Do NOT parse the RST source under `src/` directly. + +If `build/markdown/` is not available locally, the specification +(including this `AGENTS.md`) can be retrieved from +`specs.code.tiararodney.com`: + +- Specification: `https://specs.code.tiararodney.com/mime-todo/markdown/README.md` +- Agent instructions: `https://specs.code.tiararodney.com/mime-todo/markdown/AGENTS.md` +- Index: `https://specs.code.tiararodney.com/mime-todo/markdown/` + +## What This Spec Defines + +- MIME envelope structure and preprocessing rules +- 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 +- 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) +mime-todo create --type feature --title "Title" --plan "Description" + +# Start work (must be on develop) +mime-todo start --acceptance-criteria "What must be true for this to be done" +# Then create the branch: git checkout -b / + +# Complete work (must be on /) +mime-todo done --acceptance "What was delivered against the criteria" + +# Hold or cancel +mime-todo hold --reason "Why" +mime-todo cancel --reason "Why" +``` + +### Querying + +```sh +mime-todo list # list all issues +mime-todo show # show issue details +mime-todo sprints # list sprints +mime-todo issues-in-sprint # issues in a sprint +``` + +### Bugzilla Integration + +```sh +mime-todo init # check products/components exist +mime-todo push # push commits to Bugzilla +mime-todo push --dry-run # preview +``` + +### What Agents MUST NOT Do + +- Edit the `TODO` file directly. +- Construct `todo(): ` commits manually. +- Modify issue fields other than `Status` (and only via the CLI). +- Push to Bugzilla outside of `mime-todo push`. +- Modify the specification files. + +## Rules for Agents + +- Do NOT modify the specification files. +- Do NOT modify the RST source under `src/`. +- Changes to this specification MUST be made upstream in the vendor + repository. + +## Maintaining This Repository + +If you are explicitly invoked to maintain this specification repository +(building, publishing, or managing URLs), see `CONTRIBUTING.md` for +instructions. diff --git a/build/markdown/CHANGELOG.md b/build/markdown/CHANGELOG.md new file mode 100644 index 0000000..10a9ad5 --- /dev/null +++ b/build/markdown/CHANGELOG.md @@ -0,0 +1,7 @@ +# 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* diff --git a/build/markdown/LICENSE b/build/markdown/LICENSE new file mode 100644 index 0000000..6c5a1fe --- /dev/null +++ b/build/markdown/LICENSE @@ -0,0 +1,392 @@ +Attribution-NoDerivatives 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + + +======================================================================= + +Creative Commons Attribution-NoDerivatives 4.0 International Public +License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution-NoDerivatives 4.0 International Public License ("Public +License"). To the extent this Public License may be interpreted as a +contract, You are granted the Licensed Rights in consideration of Your +acceptance of these terms and conditions, and the Licensor grants You +such rights in consideration of benefits the Licensor receives from +making the Licensed Material available under these terms and +conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + c. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + d. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + e. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + f. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + g. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + h. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + i. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + j. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce and reproduce, but not Share, Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material, You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + For the avoidance of doubt, You do not have permission under + this Public License to Share Adapted Material. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database, provided You do not Share + Adapted Material; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material; and + + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. diff --git a/build/markdown/README.md b/build/markdown/README.md new file mode 100644 index 0000000..1016fdb --- /dev/null +++ b/build/markdown/README.md @@ -0,0 +1,751 @@ +# 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: +``` + +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: ` +* `Range: ..` + +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: ` — unique module identifier. + +Optional keys: + +* `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: +Mappings: + - Module: + Product: + 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: ` — references a module name. +* `Product: ` — Bugzilla product name. +* `Component: ` — 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: `/src//TODO#` +* GitHub: `/blob//TODO#` +* GitLab: `/-/blob//TODO#` + +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-` (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 +**** + + + +[``]() +``` + +The commit URL format is host-dependent: + +* Bitbucket: `/commits/` +* GitHub: `/commit/` +* GitLab: `/-/commit/` + +## 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: +Type: +Title: +Status: +Priority: +Created: +Module: # OPTIONAL +Relationships: +DueStart: # OPTIONAL +DueEnd: # OPTIONAL +Description: + +AcceptanceCriteria: # OPTIONAL, set at in-progress + +Acceptance: # OPTIONAL, set at done + +``` + +### 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 +/ +``` + +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 `/`. +* 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(): + + +``` + +Where: + +* `` is the issue’s integer ID. +* `` is the new status value. +* `` 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 `/` may be created from + `develop`. + +**\`\`todo(): done\`\`** — Complete work. + +* Branch: MUST be on `/`. +* 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 `/`. +* Body: reason for holding. + +**\`\`todo(): cancelled\`\`** — Cancel issue. + +* Branch: MUST be on `develop` or `/`. +* 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: + + + ``` + + * 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(): 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 --acceptance-criteria "What must be true for this to be done" +``` + +This produces a `todo(): in-progress` commit. The +`--acceptance-criteria` text is stored in the issue’s +`AcceptanceCriteria` field and becomes the commit body. The issue branch +`/` may then be created by the user: + +```default +git checkout -b feature/ +``` + +Completing work (MUST be on `/`): + +```default +mime-todo done --acceptance "What was delivered against the criteria" +``` + +This produces a `todo(): 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 `/`): + +```default +mime-todo hold --reason "Blocked on dependency" +``` + +Cancelling an issue (MUST be on `develop` or `/`): + +```default +mime-todo cancel --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 # show full issue details +mime-todo sprints # list all sprints +mime-todo issues-in-sprint # 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-` 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/ +``` + +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*