diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5bed565 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,39 @@ +# 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: + +``` +dist/markdown/ +``` + +Agents MUST read the specification from `dist/markdown/` for programmatic +access. Do NOT parse the RST source under `src/` directly. + +If `dist/markdown/` is not available locally, the specification +(including this `AGENTS.md`) can be retrieved from +`specs.code.tiararodney.com`, which provides HTML indexes that can be +traversed to locate the applicable markdown files. + +## 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 +- Description block and body grammar +- Branch naming and lifecycle rules tied to issue Type and Status +- Sprint membership logic +- Preprocessor and parser requirements +- Error handling requirements + +## 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. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/Pipfile b/Pipfile index 8b0d4be..3438c1d 100644 --- a/Pipfile +++ b/Pipfile @@ -7,6 +7,7 @@ name = "pypi" sphinx = "==9.1.0" sphinx-last-updated-by-git = "*" sphinx-markdown-builder = "*" +myst-parser = "*" [dev-packages] @@ -15,4 +16,4 @@ python_version = "3.13" [scripts] build-html = "sphinx-build -b html src/ build/html" -build-md = "sphinx-build -M markdown src/ build/" +build-md = "sphinx-build -M markdown src/ build/" diff --git a/Pipfile.lock b/Pipfile.lock index 8728da3..19d9fb5 100644 --- a/Pipfile.lock +++ b/Pipfile.lock @@ -1,7 +1,7 @@ { "_meta": { "hash": { - "sha256": "a889c35529339553277566894ad1f7630f478a0a996bee97ad7e704e938b9146" + "sha256": "ce91be744fd5b85f6cd10a54b48d6377511e0f39905267dfd090b725d8e4691b" }, "pipfile-spec": 6, "requires": { @@ -191,6 +191,14 @@ "markers": "python_version >= '3.7'", "version": "==3.1.6" }, + "markdown-it-py": { + "hashes": [ + "sha256:87327c59b172c5011896038353a81343b6754500a08cd7a4973bb48c6d578147", + "sha256:cb0a2b4aa34f932c007117b194e945bd74e0ec24133ceb5bac59009cda1cb9f3" + ], + "markers": "python_version >= '3.10'", + "version": "==4.0.0" + }, "markupsafe": { "hashes": [ "sha256:0303439a41979d9e74d18ff5e2dd8c43ed6c6001fd40e5bf2e43f7bd9bbc523f", @@ -286,6 +294,31 @@ "markers": "python_version >= '3.9'", "version": "==3.0.3" }, + "mdit-py-plugins": { + "hashes": [ + "sha256:07a08422fc1936a5d26d146759e9155ea466e842f5ab2f7d2266dd084c8dab1f", + "sha256:f4918cb50119f50446560513a8e311d574ff6aaed72606ddae6d35716fe809c6" + ], + "markers": "python_version >= '3.10'", + "version": "==0.5.0" + }, + "mdurl": { + "hashes": [ + "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", + "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba" + ], + "markers": "python_version >= '3.7'", + "version": "==0.1.2" + }, + "myst-parser": { + "hashes": [ + "sha256:ab31e516024918296e169139072b81592336f2fef55b8986aa31c9f04b5f7211", + "sha256:f6f231452c56e8baa662cc352c548158f6a16fcbd6e3800fc594978002b94f3a" + ], + "index": "pypi", + "markers": "python_version >= '3.11'", + "version": "==5.0.0" + }, "packaging": { "hashes": [ "sha256:00243ae351a257117b6a241061796684b084ed1c516a08c48a3f7e147a9d80b4", @@ -302,6 +335,85 @@ "markers": "python_version >= '3.8'", "version": "==2.19.2" }, + "pyyaml": { + "hashes": [ + "sha256:00c4bdeba853cc34e7dd471f16b4114f4162dc03e6b7afcc2128711f0eca823c", + "sha256:0150219816b6a1fa26fb4699fb7daa9caf09eb1999f3b70fb6e786805e80375a", + "sha256:02893d100e99e03eda1c8fd5c441d8c60103fd175728e23e431db1b589cf5ab3", + "sha256:02ea2dfa234451bbb8772601d7b8e426c2bfa197136796224e50e35a78777956", + "sha256:0f29edc409a6392443abf94b9cf89ce99889a1dd5376d94316ae5145dfedd5d6", + "sha256:10892704fc220243f5305762e276552a0395f7beb4dbf9b14ec8fd43b57f126c", + "sha256:16249ee61e95f858e83976573de0f5b2893b3677ba71c9dd36b9cf8be9ac6d65", + "sha256:1d37d57ad971609cf3c53ba6a7e365e40660e3be0e5175fa9f2365a379d6095a", + "sha256:1ebe39cb5fc479422b83de611d14e2c0d3bb2a18bbcb01f229ab3cfbd8fee7a0", + "sha256:214ed4befebe12df36bcc8bc2b64b396ca31be9304b8f59e25c11cf94a4c033b", + "sha256:2283a07e2c21a2aa78d9c4442724ec1eb15f5e42a723b99cb3d822d48f5f7ad1", + "sha256:22ba7cfcad58ef3ecddc7ed1db3409af68d023b7f940da23c6c2a1890976eda6", + "sha256:27c0abcb4a5dac13684a37f76e701e054692a9b2d3064b70f5e4eb54810553d7", + "sha256:28c8d926f98f432f88adc23edf2e6d4921ac26fb084b028c733d01868d19007e", + "sha256:2e71d11abed7344e42a8849600193d15b6def118602c4c176f748e4583246007", + "sha256:34d5fcd24b8445fadc33f9cf348c1047101756fd760b4dacb5c3e99755703310", + "sha256:37503bfbfc9d2c40b344d06b2199cf0e96e97957ab1c1b546fd4f87e53e5d3e4", + "sha256:3c5677e12444c15717b902a5798264fa7909e41153cdf9ef7ad571b704a63dd9", + "sha256:3ff07ec89bae51176c0549bc4c63aa6202991da2d9a6129d7aef7f1407d3f295", + "sha256:41715c910c881bc081f1e8872880d3c650acf13dfa8214bad49ed4cede7c34ea", + "sha256:418cf3f2111bc80e0933b2cd8cd04f286338bb88bdc7bc8e6dd775ebde60b5e0", + "sha256:44edc647873928551a01e7a563d7452ccdebee747728c1080d881d68af7b997e", + "sha256:4a2e8cebe2ff6ab7d1050ecd59c25d4c8bd7e6f400f5f82b96557ac0abafd0ac", + "sha256:4ad1906908f2f5ae4e5a8ddfce73c320c2a1429ec52eafd27138b7f1cbe341c9", + "sha256:501a031947e3a9025ed4405a168e6ef5ae3126c59f90ce0cd6f2bfc477be31b7", + "sha256:5190d403f121660ce8d1d2c1bb2ef1bd05b5f68533fc5c2ea899bd15f4399b35", + "sha256:5498cd1645aa724a7c71c8f378eb29ebe23da2fc0d7a08071d89469bf1d2defb", + "sha256:5cf4e27da7e3fbed4d6c3d8e797387aaad68102272f8f9752883bc32d61cb87b", + "sha256:5e0b74767e5f8c593e8c9b5912019159ed0533c70051e9cce3e8b6aa699fcd69", + "sha256:5ed875a24292240029e4483f9d4a4b8a1ae08843b9c54f43fcc11e404532a8a5", + "sha256:5fcd34e47f6e0b794d17de1b4ff496c00986e1c83f7ab2fb8fcfe9616ff7477b", + "sha256:5fdec68f91a0c6739b380c83b951e2c72ac0197ace422360e6d5a959d8d97b2c", + "sha256:6344df0d5755a2c9a276d4473ae6b90647e216ab4757f8426893b5dd2ac3f369", + "sha256:64386e5e707d03a7e172c0701abfb7e10f0fb753ee1d773128192742712a98fd", + "sha256:652cb6edd41e718550aad172851962662ff2681490a8a711af6a4d288dd96824", + "sha256:66291b10affd76d76f54fad28e22e51719ef9ba22b29e1d7d03d6777a9174198", + "sha256:66e1674c3ef6f541c35191caae2d429b967b99e02040f5ba928632d9a7f0f065", + "sha256:6adc77889b628398debc7b65c073bcb99c4a0237b248cacaf3fe8a557563ef6c", + "sha256:79005a0d97d5ddabfeeea4cf676af11e647e41d81c9a7722a193022accdb6b7c", + "sha256:7c6610def4f163542a622a73fb39f534f8c101d690126992300bf3207eab9764", + "sha256:7f047e29dcae44602496db43be01ad42fc6f1cc0d8cd6c83d342306c32270196", + "sha256:8098f252adfa6c80ab48096053f512f2321f0b998f98150cea9bd23d83e1467b", + "sha256:850774a7879607d3a6f50d36d04f00ee69e7fc816450e5f7e58d7f17f1ae5c00", + "sha256:8d1fab6bb153a416f9aeb4b8763bc0f22a5586065f86f7664fc23339fc1c1fac", + "sha256:8da9669d359f02c0b91ccc01cac4a67f16afec0dac22c2ad09f46bee0697eba8", + "sha256:8dc52c23056b9ddd46818a57b78404882310fb473d63f17b07d5c40421e47f8e", + "sha256:9149cad251584d5fb4981be1ecde53a1ca46c891a79788c0df828d2f166bda28", + "sha256:93dda82c9c22deb0a405ea4dc5f2d0cda384168e466364dec6255b293923b2f3", + "sha256:96b533f0e99f6579b3d4d4995707cf36df9100d67e0c8303a0c55b27b5f99bc5", + "sha256:9c57bb8c96f6d1808c030b1687b9b5fb476abaa47f0db9c0101f5e9f394e97f4", + "sha256:9c7708761fccb9397fe64bbc0395abcae8c4bf7b0eac081e12b809bf47700d0b", + "sha256:9f3bfb4965eb874431221a3ff3fdcddc7e74e3b07799e0e84ca4a0f867d449bf", + "sha256:a33284e20b78bd4a18c8c2282d549d10bc8408a2a7ff57653c0cf0b9be0afce5", + "sha256:a80cb027f6b349846a3bf6d73b5e95e782175e52f22108cfa17876aaeff93702", + "sha256:b30236e45cf30d2b8e7b3e85881719e98507abed1011bf463a8fa23e9c3e98a8", + "sha256:b3bc83488de33889877a0f2543ade9f70c67d66d9ebb4ac959502e12de895788", + "sha256:b865addae83924361678b652338317d1bd7e79b1f4596f96b96c77a5a34b34da", + "sha256:b8bb0864c5a28024fac8a632c443c87c5aa6f215c0b126c449ae1a150412f31d", + "sha256:ba1cc08a7ccde2d2ec775841541641e4548226580ab850948cbfda66a1befcdc", + "sha256:bdb2c67c6c1390b63c6ff89f210c8fd09d9a1217a465701eac7316313c915e4c", + "sha256:c1ff362665ae507275af2853520967820d9124984e0f7466736aea23d8611fba", + "sha256:c2514fceb77bc5e7a2f7adfaa1feb2fb311607c9cb518dbc378688ec73d8292f", + "sha256:c3355370a2c156cffb25e876646f149d5d68f5e0a3ce86a5084dd0b64a994917", + "sha256:c458b6d084f9b935061bc36216e8a69a7e293a2f1e68bf956dcd9e6cbcd143f5", + "sha256:d0eae10f8159e8fdad514efdc92d74fd8d682c933a6dd088030f3834bc8e6b26", + "sha256:d76623373421df22fb4cf8817020cbb7ef15c725b9d5e45f17e189bfc384190f", + "sha256:ebc55a14a21cb14062aa4162f906cd962b28e2e9ea38f9b4391244cd8de4ae0b", + "sha256:eda16858a3cab07b80edaf74336ece1f986ba330fdb8ee0d6c0d68fe82bc96be", + "sha256:ee2922902c45ae8ccada2c5b501ab86c36525b883eff4255313a253a3160861c", + "sha256:efd7b85f94a6f21e4932043973a7ba2613b059c4a000551892ac9f1d11f5baf3", + "sha256:f7057c9a337546edc7973c0d3ba84ddcdf0daa14533c2065749c9075001090e6", + "sha256:fa160448684b4e94d80416c0fa4aac48967a969efe22931448d853ada8baf926", + "sha256:fc09d0aa354569bc501d4e787133afc08552722d3ab34836a80547331bb5d4a0" + ], + "markers": "python_version >= '3.8'", + "version": "==6.0.3" + }, "requests": { "hashes": [ "sha256:2462f94637a34fd532264295e186976db0f5d453d1cdd31473c85a6a161affb6", @@ -323,7 +435,7 @@ "sha256:6cd7b3897da8d6c9ffb968a6781fa6532dce9c3618a4b127d920dab764a19064", "sha256:6d5eeeec8e9f84d4d56b847692bacf79bc2c8e90c7f80ca4444ff8b6f2e52895" ], - "markers": "python_version not in '3.0, 3.1, 3.2'", + "markers": "python_version not in '3.0, 3.1, 3.2, 3.3'", "version": "==3.0.1" }, "sphinx": { diff --git a/dist/doctrees/AGENTS.doctree b/dist/doctrees/AGENTS.doctree new file mode 100644 index 0000000..8bdfec2 Binary files /dev/null and b/dist/doctrees/AGENTS.doctree differ diff --git a/dist/doctrees/README.doctree b/dist/doctrees/README.doctree new file mode 100644 index 0000000..12d1552 Binary files /dev/null and b/dist/doctrees/README.doctree differ diff --git a/dist/doctrees/environment.pickle b/dist/doctrees/environment.pickle new file mode 100644 index 0000000..5dc94bf Binary files /dev/null and b/dist/doctrees/environment.pickle differ diff --git a/dist/markdown/AGENTS.md b/dist/markdown/AGENTS.md new file mode 100644 index 0000000..f27ba41 --- /dev/null +++ b/dist/markdown/AGENTS.md @@ -0,0 +1,39 @@ +# 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 +dist/markdown/ +``` + +Agents MUST read the specification from `dist/markdown/` for programmatic +access. Do NOT parse the RST source under `src/` directly. + +If `dist/markdown/` is not available locally, the specification +(including this `AGENTS.md`) can be retrieved from +`specs.code.tiararodney.com`, which provides HTML indexes that can be +traversed to locate the applicable markdown files. + +## 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 +- Description block and body grammar +- Branch naming and lifecycle rules tied to issue Type and Status +- Sprint membership logic +- Preprocessor and parser requirements +- Error handling requirements + +## 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. diff --git a/dist/markdown/LICENSE b/dist/markdown/LICENSE new file mode 100644 index 0000000..6c5a1fe --- /dev/null +++ b/dist/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/dist/markdown/README.md b/dist/markdown/README.md new file mode 100644 index 0000000..cf57e27 --- /dev/null +++ b/dist/markdown/README.md @@ -0,0 +1,292 @@ +# Introduction + +This document defines the canonical format, semantics, and processing rules +for the repository-root `TODO` file. The file is a human-friendly, +append-only (allowing modifications) issue tracker that is parsed by TypeScript tooling using a MIME +envelope added at parse time. + +The raw `TODO` file is not a MIME document. A preprocessor wraps it into a +valid `multipart/mixed` MIME message before parsing. + +## Raw File Structure + +The raw `TODO` file consists of a sequence of *parts*, each beginning with: + +```default +--ISSUE +Content-Type: +``` + +Valid part types are: + +* `application/sprints` — defines sprint metadata +* `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. + +## 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/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: +Relationships: +DueStart: # OPTIONAL +DueEnd: # OPTIONAL +Description: + +``` + +### 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. +* **Relationships**: + \* Empty: + ```default + Relationships: + ``` + + * Or list: + ```default + Relationships: dependsOn:43, relatesTo:10 + ``` + * Valid kinds: `dependsOn`, `relatesTo`, `blocks`, `causedBy`. +* **DueStart / DueEnd**: + \* Optional. + \* If only one is present, the other is implicitly equal to it. + +### Description Block + +* The first line appears on the same line as `Description:`. +* Continuation lines: + \* Must begin with whitespace. + \* Must align indentation consistently. +* 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. + +## 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`. + +## 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) + \* All `application/issue` parts follow in original order +* 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/issue` → issue parser +* Enforce: + \* Field order + \* Required fields + \* Description indentation rules + \* Sprint entry grammar +* Produce a `TodoFile` object: + ```default + { + sprints: Sprint[], + issues: Issue[] + } + ``` + +## 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 +* Duplicate issue IDs + +Errors SHOULD include line numbers when possible. + +## Extensibility + +Future part types MAY be added using: + +```default +application/ +``` + +Examples: + +* `application/metadata` +* `application/changelog` +* `application/epilog` + +The preprocessor MUST preserve unknown part types but MUST NOT reorder them. diff --git a/src/AGENTS.rst b/src/AGENTS.rst new file mode 100644 index 0000000..5c51f88 --- /dev/null +++ b/src/AGENTS.rst @@ -0,0 +1,2 @@ +.. include:: ../AGENTS.md + :parser: myst_parser.sphinx_ diff --git a/src/README.rst b/src/README.rst index 1db5be9..2ea57b5 100644 --- a/src/README.rst +++ b/src/README.rst @@ -1,3 +1,8 @@ +.. toctree:: + :hidden: + + AGENTS + ############ Introduction ############ diff --git a/src/conf.py b/src/conf.py index dec17cd..c9ae813 100644 --- a/src/conf.py +++ b/src/conf.py @@ -8,6 +8,7 @@ extensions = [ 'sphinx.ext.todo', 'sphinx_last_updated_by_git', 'sphinx_markdown_builder', + 'myst_parser', ]