diff --git a/AGENTS.md b/AGENTS.md index 475d30b..7a99c72 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,11 +28,66 @@ If `dist/markdown/` is not available locally, the specification - Issue part format (`application/issue`): field ordering, field semantics, valid values for Type, Status, Priority, and Relationships - Sprint part format (`application/sprints`): entry grammar, date ranges -- Description block and body grammar +- Module part format (`application/modules`): module names and paths +- Bugzilla tracker part format (`application/bugzilla`): product/component + mappings, sync model, comment format +- Description block and body grammar (80-column wrap, column 14 indent) +- Issue immutability rules +- Status transition state machine and commit conventions - Branch naming and lifecycle rules tied to issue Type and Status - Sprint membership logic - Preprocessor and parser requirements - Error handling requirements +- CLI reference for spec-compliant issue management + +## Interacting with the TODO File + +Agents MUST use the `@byteb4rb1e/mime-todo` CLI for all interactions +with the `TODO` file. Do NOT edit the file directly or construct +transition commits manually. + +### Issue Lifecycle + +```sh +# Create an issue (must be on develop) +todo create --type feature --title "Title" --plan "Description" + +# Start work (must be on develop) +todo start --plan "Planned approach" +# Then create the branch: git checkout -b / + +# Complete work (must be on /) +todo done --summary "What was delivered" + +# Hold or cancel +todo hold --reason "Why" +todo cancel --reason "Why" +``` + +### Querying + +```sh +todo list # list all issues +todo show # show issue details +todo sprints # list sprints +todo issues-in-sprint # issues in a sprint +``` + +### Bugzilla Integration + +```sh +todo init # check products/components exist +todo push # push commits to Bugzilla +todo push --dry-run # preview +``` + +### What Agents MUST NOT Do + +- Edit the `TODO` file directly. +- Construct `todo(): ` commits manually. +- Modify issue fields other than `Status` (and only via the CLI). +- Push to Bugzilla outside of `todo push`. +- Modify the specification files. ## Rules for Agents diff --git a/dist/doctrees/AGENTS.doctree b/dist/doctrees/AGENTS.doctree index dec042e..86dc549 100644 Binary files a/dist/doctrees/AGENTS.doctree and b/dist/doctrees/AGENTS.doctree differ diff --git a/dist/doctrees/README.doctree b/dist/doctrees/README.doctree index 6970444..2656856 100644 Binary files a/dist/doctrees/README.doctree and b/dist/doctrees/README.doctree differ diff --git a/dist/doctrees/environment.pickle b/dist/doctrees/environment.pickle index df258b0..449954c 100644 Binary files a/dist/doctrees/environment.pickle and b/dist/doctrees/environment.pickle differ diff --git a/dist/markdown/AGENTS.md b/dist/markdown/AGENTS.md index e3e2e27..f5c827f 100644 --- a/dist/markdown/AGENTS.md +++ b/dist/markdown/AGENTS.md @@ -28,11 +28,66 @@ If `dist/markdown/` is not available locally, the specification - Issue part format (`application/issue`): field ordering, field semantics, valid values for Type, Status, Priority, and Relationships - Sprint part format (`application/sprints`): entry grammar, date ranges -- Description block and body grammar +- Module part format (`application/modules`): module names and paths +- Bugzilla tracker part format (`application/bugzilla`): product/component + mappings, sync model, comment format +- Description block and body grammar (80-column wrap, column 14 indent) +- Issue immutability rules +- Status transition state machine and commit conventions - Branch naming and lifecycle rules tied to issue Type and Status - Sprint membership logic - Preprocessor and parser requirements - Error handling requirements +- CLI reference for spec-compliant issue management + +## Interacting with the TODO File + +Agents MUST use the `@byteb4rb1e/mime-todo` CLI for all interactions +with the `TODO` file. Do NOT edit the file directly or construct +transition commits manually. + +### Issue Lifecycle + +```sh +# Create an issue (must be on develop) +todo create --type feature --title "Title" --plan "Description" + +# Start work (must be on develop) +todo start --plan "Planned approach" +# Then create the branch: git checkout -b / + +# Complete work (must be on /) +todo done --summary "What was delivered" + +# Hold or cancel +todo hold --reason "Why" +todo cancel --reason "Why" +``` + +### Querying + +```sh +todo list # list all issues +todo show # show issue details +todo sprints # list sprints +todo issues-in-sprint # issues in a sprint +``` + +### Bugzilla Integration + +```sh +todo init # check products/components exist +todo push # push commits to Bugzilla +todo push --dry-run # preview +``` + +### What Agents MUST NOT Do + +- Edit the `TODO` file directly. +- Construct `todo(): ` commits manually. +- Modify issue fields other than `Status` (and only via the CLI). +- Push to Bugzilla outside of `todo push`. +- Modify the specification files. ## Rules for Agents diff --git a/dist/markdown/README.md b/dist/markdown/README.md index cf57e27..1d324f4 100644 --- a/dist/markdown/README.md +++ b/dist/markdown/README.md @@ -20,10 +20,14 @@ 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 the `application/sprints` part appears first. +them so that `application/sprints` appears first, followed by +`application/modules`, then `application/bugzilla`, then all +`application/issue` parts in original order. ## MIME Envelope (Added by Preprocessor) @@ -99,6 +103,155 @@ Required keys: The `Range` defines a closed interval `[start, end]`. +## Part: `application/modules` + +This part defines the repository’s logical module structure. Each module maps +a name to an optional repository-relative path. + +At most one `application/modules` part MAY appear. Multiple +`application/modules` parts MUST be rejected. + +The body MUST begin with: + +```default +Modules: +``` + +followed by one or more module entries. + +### Module Entry Forms + +Compact form: + +```default +- Name: Specification + Path: src +``` + +Expanded form: + +```default +- + Name: Specification + Path: src +``` + +A module without a path (logical grouping): + +```default +- Name: Documentation +``` + +### Module Entry Grammar + +A module entry begins at a line matching: + +```default +^\s*-\s*(Name:.*)?$ +``` + +Key–value lines inside an entry match: + +```default +^\s+[A-Za-z][A-Za-z0-9]*:\s*(.*)$ +``` + +Required keys: + +* `Name: ` — 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. @@ -114,9 +267,10 @@ Title: Status: Priority: Created: +Module: # OPTIONAL Relationships: -DueStart: # OPTIONAL -DueEnd: # OPTIONAL +DueStart: # OPTIONAL +DueEnd: # OPTIONAL Description: ``` @@ -130,6 +284,9 @@ Description: * **Status**: one of `open`, `in-progress`, `done`, `hold`, `cancelled`. * **Priority**: one of `low`, `medium`, `high`. * **Created**: ISO date. +* **Module**: optional. When present, MUST reference a module name defined in + the `application/modules` part. If no `application/modules` part exists, + the field is ignored. * **Relationships**: \* Empty: ```default @@ -140,7 +297,11 @@ Description: ```default Relationships: dependsOn:43, relatesTo:10 ``` - * Valid kinds: `dependsOn`, `relatesTo`, `blocks`, `causedBy`. + * Valid kinds: `dependsOn`, `relatesTo`, `blocks`. + * All relationship target IDs MUST reference existing issue IDs in the + same `TODO` file. A target that does not exist MUST be rejected. + * A relationship targeting a `cancelled` issue SHOULD produce a warning + (stale reference). * **DueStart / DueEnd**: \* Optional. \* If only one is present, the other is implicitly equal to it. @@ -148,9 +309,10 @@ Description: ### Description Block * The first line appears on the same line as `Description:`. -* Continuation lines: - \* Must begin with whitespace. - \* Must align indentation consistently. +* `Description:` occupies 13 characters. Content begins at column 14. +* Continuation lines MUST be indented with 13 spaces, aligning with column 14. +* Lines MUST NOT exceed 80 columns. Long text MUST be word-wrapped at the + 80-column boundary by the serializer. * No blank lines allowed inside the description block. ### Body @@ -158,6 +320,20 @@ Description: Any lines after the description block are considered free-form body text. The body MUST NOT contain another `ID:` field or a MIME boundary. +### Issue Immutability + +The `Description` field is immutable after the issue is created. To change +the scope of an issue, the issue MUST be cancelled and a new issue created. + +Fields that MAY change after creation: + +* `Status` (via transition commits) + +Fields that MUST NOT change after creation: + +* `ID`, `Type`, `Title`, `Priority`, `Created`, `Description`, + `Module` + ## Git Workflow Rules ### Branch Naming @@ -186,6 +362,83 @@ bugfix/7 * A branch MUST be named exactly `/`. * 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 required description whose content depends on the + transition. + +### Transition Details + +**\`\`todo(): open\`\`** — Issue creation. + +* Branch: MUST be on `develop`. +* Body: description of what needs to be done (becomes the issue’s + `Description` field). + +**\`\`todo(): in-progress\`\`** — Start work. + +* Branch: MUST be on `develop`. +* Body: high-level description of the planned approach. +* After this commit, the issue branch `/` may be created from + `develop`. + +**\`\`todo(): done\`\`** — Complete work. + +* Branch: MUST be on `/`. +* Body: high-level summary of what was delivered. +* 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: @@ -222,7 +475,10 @@ The preprocessor MUST: * Extract each part’s `Content-Type` and body. * Reorder parts so that: \* `application/sprints` appears first (if present) + \* `application/modules` appears second (if present) + \* `application/bugzilla` appears third (if present) \* All `application/issue` parts follow in original order + \* Unknown part types are preserved in original order after issues * Emit a MIME message with: \* `MIME-Version: 1.0` \* `Content-Type: multipart/mixed; boundary="ISSUE"` @@ -246,17 +502,26 @@ The parser MUST: * Use a MIME parser to extract parts. * Dispatch based on `Content-Type`: \* `application/sprints` → sprint parser + \* `application/modules` → module parser + \* `application/bugzilla` → Bugzilla tracker parser \* `application/issue` → issue parser * Enforce: \* Field order \* Required fields - \* Description indentation rules + \* Description indentation and column rules \* Sprint entry grammar + \* Module entry grammar + \* Module references: if `application/modules` is present, every issue `Module` field MUST reference a defined module name + \* Bugzilla mapping references: if `application/bugzilla` is present, every mapping `Module` value MUST reference a defined module name + \* Relationship targets: every target ID MUST reference an existing issue ID + \* Stale relationships: a relationship targeting a `cancelled` issue SHOULD produce a warning * Produce a `TodoFile` object: ```default { sprints: Sprint[], - issues: Issue[] + issues: Issue[], + modules?: Module[], + bugzilla?: BugzillaTracker } ``` @@ -271,22 +536,159 @@ The parser MUST reject: * Invalid sprint ranges * Invalid date formats * Multiple `application/sprints` parts +* Multiple `application/modules` parts +* Multiple `application/bugzilla` parts +* `application/bugzilla` without `application/modules` +* Issue `Module` referencing undefined module +* Bugzilla mapping `Module` referencing undefined module +* Relationship target referencing non-existent issue ID +* Invalid status transition * Duplicate issue IDs +The parser SHOULD warn on: + +* Relationship targeting a `cancelled` issue (stale reference) + Errors SHOULD include line numbers when possible. +## CLI Reference + +The `@byteb4rb1e/mime-todo` CLI is the reference implementation of this +specification. It enforces all format, validation, transition, and commit +rules defined above. Both developers and automated agents MUST use the CLI +to interact with the `TODO` file rather than editing it manually. + +Install: + +```default +npm install -g @byteb4rb1e/mime-todo +``` + +### Issue Lifecycle + +Creating an issue (MUST be on `develop`): + +```default +todo create --type feature --title "Add login" --plan "Implement OAuth2 flow" +``` + +This produces a `todo(): open` commit modifying only the `TODO` file. +The `--plan` text becomes the issue’s `Description` field. + +Starting work (MUST be on `develop`): + +```default +todo start --plan "High-level approach description" +``` + +This produces a `todo(): in-progress` commit. The issue branch +`/` may then be created by the user: + +```default +git checkout -b feature/ +``` + +Completing work (MUST be on `/`): + +```default +todo done --summary "Summary of what was delivered" +``` + +This produces a `todo(): done` commit. The issue branch may then be +merged into `develop` using `--no-ff`. + +Holding an issue (MUST be on `/`): + +```default +todo hold --reason "Blocked on dependency" +``` + +Cancelling an issue (MUST be on `develop` or `/`): + +```default +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 +todo list # list all issues +todo show # show full issue details +todo sprints # list all sprints +todo issues-in-sprint # list issues in a sprint +``` + +### Bugzilla Integration + +Initializing products and components: + +```default +todo init # check what exists +todo init --dry-run # preview changes +todo init --confirm --assignee user@example.com # create missing items +``` + +The `init` command reads the `application/bugzilla` part and ensures all +referenced products and components exist on the Bugzilla server. + +Pushing commits to Bugzilla: + +```default +todo push # push all unpushed commits +todo push HEAD~3 # push only the last 3 commits +todo push --dry-run # preview without pushing +todo push --strategy full # re-scan all bugs +``` + +On issue branches, `push` posts work commits as Bugzilla comments. Work +comments are only permitted when the issue is `in-progress` and no +`done` transition has been recorded. + +On `develop`, `push` posts transition commits as Bugzilla comments and +updates the bug’s status accordingly. + +Each comment includes a clickable link to the commit and is tagged with +`git-` for idempotency. Running `push` multiple times is +safe. + +### Agent Usage + +Agents MUST use the CLI for all `TODO` file interactions: + +* Creating issues: `todo create` +* Transitioning issues: `todo start`, `todo done`, `todo hold`, + `todo cancel` +* Querying: `todo list`, `todo show`, `todo sprints` +* Syncing to Bugzilla: `todo push` + +Agents MUST NOT: + +* Edit the `TODO` file directly. +* Construct transition commits manually. +* Modify issue fields other than `Status` (and only via the CLI). +* Push to Bugzilla outside of the CLI’s `push` command. + ## Extensibility +Defined part types: + +* `application/sprints` — sprint metadata +* `application/modules` — repository module structure +* `application/bugzilla` — Bugzilla product/component mappings +* `application/issue` — single issue + Future part types MAY be added using: ```default application/ ``` -Examples: - -* `application/metadata` -* `application/changelog` -* `application/epilog` - The preprocessor MUST preserve unknown part types but MUST NOT reorder them. +Unknown types are placed after all defined types. diff --git a/src/README.rst b/src/README.rst index 2ea57b5..a33a21b 100644 --- a/src/README.rst +++ b/src/README.rst @@ -27,10 +27,14 @@ The raw ``TODO`` file consists of a sequence of *parts*, each beginning with:: Valid part types are: * ``application/sprints`` — defines sprint metadata +* ``application/modules`` — defines the repository module structure +* ``application/bugzilla`` — defines Bugzilla product/component mappings * ``application/issue`` — defines a single issue Parts may appear in any order in the raw file. The preprocessor will reorder -them so that the ``application/sprints`` part appears first. +them so that ``application/sprints`` appears first, followed by +``application/modules``, then ``application/bugzilla``, then all +``application/issue`` parts in original order. MIME Envelope (Added by Preprocessor) @@ -99,6 +103,148 @@ Required keys: The ``Range`` defines a closed interval ``[start, end]``. +Part: ``application/modules`` +============================== + +This part defines the repository's logical module structure. Each module maps +a name to an optional repository-relative path. + +At most one ``application/modules`` part MAY appear. Multiple +``application/modules`` parts MUST be rejected. + +The body MUST begin with:: + + Modules: + +followed by one or more module entries. + +Module Entry Forms +------------------ + +Compact form:: + + - Name: Specification + Path: src + +Expanded form:: + + - + Name: Specification + Path: src + +A module without a path (logical grouping):: + + - Name: Documentation + +Module Entry Grammar +-------------------- + +A module entry begins at a line matching:: + + ^\s*-\s*(Name:.*)?$ + +Key–value lines inside an entry match:: + + ^\s+[A-Za-z][A-Za-z0-9]*:\s*(.*)$ + +Required keys: + +* ``Name: `` — 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 +--------------- + +:: + + 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:: + + ^\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):: + + **** + + + + [``]() + +The commit URL format is host-dependent: + +* Bitbucket: ``/commits/`` +* GitHub: ``/commit/`` +* GitLab: ``/-/commit/`` + + Part: ``application/issue`` =========================== @@ -115,9 +261,10 @@ The following fields MUST appear in exactly this order:: Status: Priority: Created: + Module: # OPTIONAL Relationships: - DueStart: # OPTIONAL - DueEnd: # OPTIONAL + DueStart: # OPTIONAL + DueEnd: # OPTIONAL Description: @@ -131,6 +278,9 @@ Field Semantics * **Status**: one of ``open``, ``in-progress``, ``done``, ``hold``, ``cancelled``. * **Priority**: one of ``low``, ``medium``, ``high``. * **Created**: ISO date. +* **Module**: optional. When present, MUST reference a module name defined in + the ``application/modules`` part. If no ``application/modules`` part exists, + the field is ignored. * **Relationships**: * Empty:: @@ -140,7 +290,11 @@ Field Semantics Relationships: dependsOn:43, relatesTo:10 - * Valid kinds: ``dependsOn``, ``relatesTo``, ``blocks``, ``causedBy``. + * Valid kinds: ``dependsOn``, ``relatesTo``, ``blocks``. + * All relationship target IDs MUST reference existing issue IDs in the + same ``TODO`` file. A target that does not exist MUST be rejected. + * A relationship targeting a ``cancelled`` issue SHOULD produce a warning + (stale reference). * **DueStart / DueEnd**: * Optional. * If only one is present, the other is implicitly equal to it. @@ -149,9 +303,10 @@ Description Block ----------------- * The first line appears on the same line as ``Description:``. -* Continuation lines: - * Must begin with whitespace. - * Must align indentation consistently. +* ``Description:`` occupies 13 characters. Content begins at column 14. +* Continuation lines MUST be indented with 13 spaces, aligning with column 14. +* Lines MUST NOT exceed 80 columns. Long text MUST be word-wrapped at the + 80-column boundary by the serializer. * No blank lines allowed inside the description block. Body @@ -160,6 +315,21 @@ Body Any lines after the description block are considered free-form body text. The body MUST NOT contain another ``ID:`` field or a MIME boundary. +Issue Immutability +------------------ + +The ``Description`` field is immutable after the issue is created. To change +the scope of an issue, the issue MUST be cancelled and a new issue created. + +Fields that MAY change after creation: + +* ``Status`` (via transition commits) + +Fields that MUST NOT change after creation: + +* ``ID``, ``Type``, ``Title``, ``Priority``, ``Created``, ``Description``, + ``Module`` + Git Workflow Rules ================== @@ -190,6 +360,96 @@ Branch Lifecycle * A branch MAY merge only when the issue status is ``done``. +Status Transition Rules +======================= + +Valid Transitions +----------------- + +Not all status changes are permitted. The following table defines the +complete set of valid transitions: + +.. list-table:: + :header-rows: 1 + :widths: 20 50 + + * - From + - Allowed transitions + * - ``open`` + - ``in-progress``, ``hold``, ``cancelled`` + * - ``in-progress`` + - ``done``, ``hold``, ``open``, ``cancelled`` + * - ``hold`` + - ``open``, ``in-progress``, ``cancelled`` + * - ``done`` + - ``open`` + * - ``cancelled`` + - ``open`` + +Any transition not listed MUST be rejected. A no-op transition (same status) +is permitted. + +Transition Commits +------------------ + +Each status transition MUST be recorded as a dedicated commit that modifies +only the ``TODO`` file. The commit message MUST follow this format:: + + todo(): + + + +Where: + +* ```` is the issue's integer ID. +* ```` is the new status value. +* ```` is a required description whose content depends on the + transition. + +Transition Details +------------------ + +**``todo(): open``** — Issue creation. + +* Branch: MUST be on ``develop``. +* Body: description of what needs to be done (becomes the issue's + ``Description`` field). + +**``todo(): in-progress``** — Start work. + +* Branch: MUST be on ``develop``. +* Body: high-level description of the planned approach. +* After this commit, the issue branch ``/`` may be created from + ``develop``. + +**``todo(): done``** — Complete work. + +* Branch: MUST be on ``/``. +* Body: high-level summary of what was delivered. +* 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 ======================= @@ -213,7 +473,7 @@ An issue belongs to a sprint if:: I_start ≤ S_end AND I_end ≥ S_start Current Sprint for Date D -------------------------- +-------------------------- 1. All sprints where ``S_start ≤ D ≤ S_end``. 2. If multiple match, choose the one with the latest ``S_start``. @@ -230,7 +490,10 @@ The preprocessor MUST: * Extract each part's ``Content-Type`` and body. * Reorder parts so that: * ``application/sprints`` appears first (if present) + * ``application/modules`` appears second (if present) + * ``application/bugzilla`` appears third (if present) * All ``application/issue`` parts follow in original order + * Unknown part types are preserved in original order after issues * Emit a MIME message with: * ``MIME-Version: 1.0`` * ``Content-Type: multipart/mixed; boundary="ISSUE"`` @@ -254,17 +517,26 @@ The parser MUST: * Use a MIME parser to extract parts. * Dispatch based on ``Content-Type``: * ``application/sprints`` → sprint parser + * ``application/modules`` → module parser + * ``application/bugzilla`` → Bugzilla tracker parser * ``application/issue`` → issue parser * Enforce: * Field order * Required fields - * Description indentation rules + * Description indentation and column rules * Sprint entry grammar + * Module entry grammar + * Module references: if ``application/modules`` is present, every issue ``Module`` field MUST reference a defined module name + * Bugzilla mapping references: if ``application/bugzilla`` is present, every mapping ``Module`` value MUST reference a defined module name + * Relationship targets: every target ID MUST reference an existing issue ID + * Stale relationships: a relationship targeting a ``cancelled`` issue SHOULD produce a warning * Produce a ``TodoFile`` object:: { sprints: Sprint[], - issues: Issue[] + issues: Issue[], + modules?: Module[], + bugzilla?: BugzillaTracker } @@ -280,22 +552,145 @@ The parser MUST reject: * Invalid sprint ranges * Invalid date formats * Multiple ``application/sprints`` parts +* Multiple ``application/modules`` parts +* Multiple ``application/bugzilla`` parts +* ``application/bugzilla`` without ``application/modules`` +* Issue ``Module`` referencing undefined module +* Bugzilla mapping ``Module`` referencing undefined module +* Relationship target referencing non-existent issue ID +* Invalid status transition * Duplicate issue IDs +The parser SHOULD warn on: + +* Relationship targeting a ``cancelled`` issue (stale reference) + Errors SHOULD include line numbers when possible. +CLI Reference +============= + +The ``@byteb4rb1e/mime-todo`` CLI is the reference implementation of this +specification. It enforces all format, validation, transition, and commit +rules defined above. Both developers and automated agents MUST use the CLI +to interact with the ``TODO`` file rather than editing it manually. + +Install:: + + npm install -g @byteb4rb1e/mime-todo + +Issue Lifecycle +--------------- + +Creating an issue (MUST be on ``develop``):: + + todo create --type feature --title "Add login" --plan "Implement OAuth2 flow" + +This produces a ``todo(): open`` commit modifying only the ``TODO`` file. +The ``--plan`` text becomes the issue's ``Description`` field. + +Starting work (MUST be on ``develop``):: + + todo start --plan "High-level approach description" + +This produces a ``todo(): in-progress`` commit. The issue branch +``/`` may then be created by the user:: + + git checkout -b feature/ + +Completing work (MUST be on ``/``):: + + todo done --summary "Summary of what was delivered" + +This produces a ``todo(): done`` commit. The issue branch may then be +merged into ``develop`` using ``--no-ff``. + +Holding an issue (MUST be on ``/``):: + + todo hold --reason "Blocked on dependency" + +Cancelling an issue (MUST be on ``develop`` or ``/``):: + + 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:: + + todo list # list all issues + todo show # show full issue details + todo sprints # list all sprints + todo issues-in-sprint # list issues in a sprint + +Bugzilla Integration +-------------------- + +Initializing products and components:: + + todo init # check what exists + todo init --dry-run # preview changes + todo init --confirm --assignee user@example.com # create missing items + +The ``init`` command reads the ``application/bugzilla`` part and ensures all +referenced products and components exist on the Bugzilla server. + +Pushing commits to Bugzilla:: + + todo push # push all unpushed commits + todo push HEAD~3 # push only the last 3 commits + todo push --dry-run # preview without pushing + todo push --strategy full # re-scan all bugs + +On issue branches, ``push`` posts work commits as Bugzilla comments. Work +comments are only permitted when the issue is ``in-progress`` and no +``done`` transition has been recorded. + +On ``develop``, ``push`` posts transition commits as Bugzilla comments and +updates the bug's status accordingly. + +Each comment includes a clickable link to the commit and is tagged with +``git-`` for idempotency. Running ``push`` multiple times is +safe. + +Agent Usage +----------- + +Agents MUST use the CLI for all ``TODO`` file interactions: + +* Creating issues: ``todo create`` +* Transitioning issues: ``todo start``, ``todo done``, ``todo hold``, + ``todo cancel`` +* Querying: ``todo list``, ``todo show``, ``todo sprints`` +* Syncing to Bugzilla: ``todo push`` + +Agents MUST NOT: + +* Edit the ``TODO`` file directly. +* Construct transition commits manually. +* Modify issue fields other than ``Status`` (and only via the CLI). +* Push to Bugzilla outside of the CLI's ``push`` command. + + Extensibility ============= +Defined part types: + +* ``application/sprints`` — sprint metadata +* ``application/modules`` — repository module structure +* ``application/bugzilla`` — Bugzilla product/component mappings +* ``application/issue`` — single issue + Future part types MAY be added using:: application/ -Examples: - -* ``application/metadata`` -* ``application/changelog`` -* ``application/epilog`` - The preprocessor MUST preserve unknown part types but MUST NOT reorder them. +Unknown types are placed after all defined types.