chore: regenerate markdown

2026-03-22 02:26:09 +01:00 · 2026-03-22 02:26:09 +01:00 · 79cbeb0e36
commit 79cbeb0e36
parent 84ea638661
4 changed files with 1253 additions and 0 deletions
--- a/build/markdown/README.md
+++ 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: <mime-type>
+```
+
+Valid part types are:
+
+* `application/sprints` — defines sprint metadata
+* `application/modules` — defines the repository module structure
+* `application/bugzilla` — defines Bugzilla product/component mappings
+* `application/issue` — defines a single issue
+
+Parts may appear in any order in the raw file. The preprocessor will reorder
+them so that `application/sprints` appears first, followed by
+`application/modules`, then `application/bugzilla`, then all
+`application/issue` parts in original order.
+
+## MIME Envelope (Added by Preprocessor)
+
+Before parsing, the preprocessor wraps the raw file into a MIME multipart
+message.
+
+Prolog added by the preprocessor:
+
+```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: <string>`
+* `Range: <YYYY-MM-DD>..<YYYY-MM-DD>`
+
+The `Range` defines a closed interval `[start, end]`.
+
+## Part: `application/modules`
+
+This part defines the repository’s logical module structure. Each module maps
+a name to an optional repository-relative path.
+
+At most one `application/modules` part MAY appear. Multiple
+`application/modules` parts MUST be rejected.
+
+The body MUST begin with:
+
+```default
+Modules:
+```
+
+followed by one or more module entries.
+
+### Module Entry Forms
+
+Compact form:
+
+```default
+- Name: Specification
+  Path: src
+```
+
+Expanded form:
+
+```default
+-
+  Name: Specification
+  Path: src
+```
+
+A module without a path (logical grouping):
+
+```default
+- Name: Documentation
+```
+
+### Module Entry Grammar
+
+A module entry begins at a line matching:
+
+```default
+^\s*-\s*(Name:.*)?$
+```
+
+Key–value lines inside an entry match:
+
+```default
+^\s+[A-Za-z][A-Za-z0-9]*:\s*(.*)$
+```
+
+Required keys:
+
+* `Name: <string>` — unique module identifier.
+
+Optional keys:
+
+* `Path: <repo-relative-path>` — path relative to repository root.
+  If omitted, the module is a logical grouping without a fixed location.
+
+## Part: `application/bugzilla`
+
+This part defines a unidirectional mapping from repository modules to
+Bugzilla products and components. The `TODO` file is the source of truth;
+Bugzilla is a downstream mirror.
+
+At most one `application/bugzilla` part MAY appear. Multiple
+`application/bugzilla` parts MUST be rejected.
+
+An `application/bugzilla` part MUST NOT appear unless an
+`application/modules` part is also present.
+
+### Required Fields
+
+```default
+URL: <bugzilla-rest-api-url>
+Mappings:
+        - Module: <module-name>
+          Product: <bugzilla-product>
+          Component: <bugzilla-component>
+```
+
+* **URL**: the base URL to the Bugzilla REST API.
+* **Mappings**: one or more entries mapping a module name to a Bugzilla
+  product and component. Every `Module` value MUST reference a module
+  defined in the `application/modules` part.
+
+Product and component names containing spaces or special characters are
+permitted; tooling MUST URL-encode them when constructing API requests.
+
+### Mapping Entry Grammar
+
+A mapping entry begins at a line matching:
+
+```default
+^\s*-\s*(Module:.*)?$
+```
+
+Required keys:
+
+* `Module: <string>` — references a module name.
+* `Product: <string>` — Bugzilla product name.
+* `Component: <string>` — Bugzilla component name.
+
+### Sync Model
+
+Synchronization is unidirectional: `TODO` → Bugzilla. The `TODO` file is
+the canonical source of truth.
+
+When a Bugzilla bug is created for a `TODO` issue, the bug’s `url` field
+MUST be set to a resolvable URL pointing to the `TODO` file on the
+integration branch. The URL format is host-dependent:
+
+* Bitbucket: `<repo-url>/src/<branch>/TODO#<issue-id>`
+* GitHub: `<repo-url>/blob/<branch>/TODO#<issue-id>`
+* GitLab: `<repo-url>/-/blob/<branch>/TODO#<issue-id>`
+
+The branch in the URL MUST be the integration branch (`develop`),
+regardless of which branch the push is initiated from.
+
+Transition commit messages are pushed as Bugzilla comments. Each comment is
+tagged with `git-<short-hash>` (first 7 characters of the commit hash) to
+prevent duplicate pushes. A comment tag is applied only after the comment
+and any associated status update have both succeeded.
+
+Work commits from issue branches are also pushed as Bugzilla comments,
+forming a threaded work log. Work comments:
+
+* MUST NOT be pushed unless the issue status is `in-progress`.
+* MUST NOT follow a `done` transition comment.
+
+Comment format (Markdown):
+
+```default
+**<commit-subject>**
+
+<commit-body>
+
+[`<short-hash>`](<commit-url>)
+```
+
+The commit URL format is host-dependent:
+
+* Bitbucket: `<repo-url>/commits/<hash>`
+* GitHub: `<repo-url>/commit/<hash>`
+* GitLab: `<repo-url>/-/commit/<hash>`
+
+## Part: `application/issue`
+
+Each issue is represented as a structured block with strict field ordering.
+
+### Required Field Order
+
+The following fields MUST appear in exactly this order:
+
+```default
+ID: <integer>
+Type: <feature|bugfix|hotfix>
+Title: <short title>
+Status: <open|in-progress|done|hold|cancelled>
+Priority: <low|medium|high>
+Created: <YYYY-MM-DD>
+Module: <module-name>             # OPTIONAL
+Relationships: <comma-separated list or empty>
+DueStart: <YYYY-MM-DD>           # OPTIONAL
+DueEnd: <YYYY-MM-DD>             # OPTIONAL
+Description: <first line>
+             <continuation lines>
+AcceptanceCriteria: <first line>  # OPTIONAL, set at in-progress
+                    <continuation lines>
+Acceptance: <first line>          # OPTIONAL, set at done
+            <continuation lines>
+```
+
+### Field Semantics
+
+* **ID**: unique integer, strictly increasing.
+* **Type**: one of `feature`, `bugfix`, `hotfix`.
+  \* `feature` and `bugfix` issues target the integration branch (`develop`).
+  \* `hotfix` issues target the stable branch (`main` or `master`).
+* **Status**: one of `open`, `in-progress`, `done`, `hold`, `cancelled`.
+* **Priority**: one of `low`, `medium`, `high`.
+* **Created**: ISO date.
+* **Module**: optional. When present, MUST reference a module name defined in
+  the `application/modules` part. If no `application/modules` part exists,
+  the field is ignored.
+* **Relationships**:
+  \* Empty:
+  ```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
+<Type>/<ID>
+```
+
+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 `<Type>/<ID>`.
+* A branch MAY merge only when the issue status is `done`.
+
+## Status Transition Rules
+
+### Valid Transitions
+
+Not all status changes are permitted. The following table defines the
+complete set of valid transitions:
+
+| From          | Allowed transitions                 |
+|---------------|-------------------------------------|
+| `open`        | `in-progress`, `hold`, `cancelled`  |
+| `in-progress` | `done`, `hold`, `open`, `cancelled` |
+| `hold`        | `open`, `in-progress`, `cancelled`  |
+| `done`        | `open`                              |
+| `cancelled`   | `open`                              |
+
+Any transition not listed MUST be rejected. A no-op transition (same status)
+is permitted.
+
+### Transition Commits
+
+Each status transition MUST be recorded as a dedicated commit that modifies
+only the `TODO` file. The commit message MUST follow this format:
+
+```default
+todo(<ID>): <status>
+
+<body>
+```
+
+Where:
+
+* `<ID>` is the issue’s integer ID.
+* `<status>` is the new status value.
+* `<body>` is a 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(<ID>): 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(<ID>): 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 `<Type>/<ID>` may be created from
+  `develop`.
+
+**\`\`todo(<ID>): done\`\`** — Complete work.
+
+* Branch: MUST be on `<Type>/<ID>`.
+* 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(<ID>): hold\`\`** — Pause work.
+
+* Branch: MUST be on `<Type>/<ID>`.
+* Body: reason for holding.
+
+**\`\`todo(<ID>): cancelled\`\`** — Cancel issue.
+
+* Branch: MUST be on `develop` or `<Type>/<ID>`.
+* Body: reason for cancellation.
+* If the issue is `open` (no branch exists), the commit is on `develop`.
+* If the issue is `in-progress` or `hold` (branch exists), the commit
+  may be on the issue branch.
+
+### Transition-Only Constraint
+
+A transition commit MUST modify only the `TODO` file. No other files may
+be included in the commit. This ensures that every transition is
+independently auditable.
+
+## Sprint Membership Logic
+
+Given:
+
+* Sprint interval `[S_start, S_end]`
+* Issue interval `[I_start, I_end]`
+
+### Normalization
+
+* Only `DueEnd` → `I_start = I_end = DueEnd`
+* Only `DueStart` → `I_start = I_end = DueStart`
+* Neither → issue is not sprint-bound
+
+### Membership Condition
+
+An issue belongs to a sprint if:
+
+```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: <type>
+
+  <body>
+  ```
+
+  * 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(<ID>): 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 <id> --acceptance-criteria "What must be true for this to be done"
+```
+
+This produces a `todo(<ID>): in-progress` commit. The
+`--acceptance-criteria` text is stored in the issue’s
+`AcceptanceCriteria` field and becomes the commit body. The issue branch
+`<Type>/<ID>` may then be created by the user:
+
+```default
+git checkout -b feature/<id>
+```
+
+Completing work (MUST be on `<Type>/<ID>`):
+
+```default
+mime-todo done <id> --acceptance "What was delivered against the criteria"
+```
+
+This produces a `todo(<ID>): 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 `<Type>/<ID>`):
+
+```default
+mime-todo hold <id> --reason "Blocked on dependency"
+```
+
+Cancelling an issue (MUST be on `develop` or `<Type>/<ID>`):
+
+```default
+mime-todo cancel <id> --reason "Superseded by issue #5"
+```
+
+The CLI validates the current branch and the status transition before
+committing. Invalid transitions or wrong branches are rejected with an
+error.
+
+### Read-Only Commands
+
+These commands do not modify the `TODO` file and may be run from any
+branch:
+
+```default
+mime-todo list                     # list all issues
+mime-todo show <id>                # show full issue details
+mime-todo sprints                  # list all sprints
+mime-todo issues-in-sprint <name>  # 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-<short-hash>` 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/<subtype>
+```
+
+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*