diff --git a/build/doctrees/AGENTS.doctree b/build/doctrees/AGENTS.doctree deleted file mode 100644 index d5df0c2..0000000 Binary files a/build/doctrees/AGENTS.doctree and /dev/null differ diff --git a/build/doctrees/CHANGELOG.doctree b/build/doctrees/CHANGELOG.doctree deleted file mode 100644 index b9b8113..0000000 Binary files a/build/doctrees/CHANGELOG.doctree and /dev/null differ diff --git a/build/doctrees/README.doctree b/build/doctrees/README.doctree deleted file mode 100644 index d54dd82..0000000 Binary files a/build/doctrees/README.doctree and /dev/null differ diff --git a/build/doctrees/environment.pickle b/build/doctrees/environment.pickle deleted file mode 100644 index 0a2aeb3..0000000 Binary files a/build/doctrees/environment.pickle and /dev/null differ diff --git a/build/markdown/AGENTS.md b/build/markdown/AGENTS.md deleted file mode 100644 index b60dae6..0000000 --- a/build/markdown/AGENTS.md +++ /dev/null @@ -1,103 +0,0 @@ -# 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 deleted file mode 100644 index 836abc7..0000000 --- a/build/markdown/CHANGELOG.md +++ /dev/null @@ -1,11 +0,0 @@ -# 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* -* **chore: update CLI changes** by *Tiara Rodney* at *2026-03-15 04:11:01* - - body is redundant as it is the descritpion of issue -* **update** by *Tiara Rodney* at *2026-03-15 03:39:06* diff --git a/build/markdown/LICENSE b/build/markdown/LICENSE deleted file mode 100644 index 6c5a1fe..0000000 --- a/build/markdown/LICENSE +++ /dev/null @@ -1,392 +0,0 @@ -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 deleted file mode 100644 index 28fe19e..0000000 --- a/build/markdown/README.md +++ /dev/null @@ -1,755 +0,0 @@ -# Document - -Version -: 0.2.0 - -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* -* **chore: update CLI changes** by *Tiara Rodney* at *2026-03-15 04:11:01* - - body is redundant as it is the descritpion of issue -* **update** by *Tiara Rodney* at *2026-03-15 03:39:06*