Independent Submission V. Tyemirov Internet-Draft Marco Polo Research Lab Intended status: Informational 6 May 2026 Expires: 7 November 2026 The ISSUES.md Repository Planning Format draft-tyemirov-issues-md-format-00 Abstract This document defines the ISSUES.md repository planning format. The format uses a Markdown document with section-scoped identifiers, explicit status markers, priorities, dependencies, and issue bodies so planning state can be read and written by people, repository tools, CI systems, and AI agents. This document is intended as an Independent Stream Informational Internet-Draft. It does not define an Internet protocol. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 7 November 2026. Copyright Notice Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Tyemirov Expires 7 November 2026 [Page 1] Internet-Draft ISSUES.md Format May 2026 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 2 3. Document Shape . . . . . . . . . . . . . . . . . . . . . . . 3 4. Entry Syntax . . . . . . . . . . . . . . . . . . . . . . . . 4 5. Blocked Entries . . . . . . . . . . . . . . . . . . . . . . . 5 6. Validation Model . . . . . . . . . . . . . . . . . . . . . . 5 7. Interoperability Considerations . . . . . . . . . . . . . . . 6 8. Non-Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 6 9. Security Considerations . . . . . . . . . . . . . . . . . . . 6 10. Privacy Considerations . . . . . . . . . . . . . . . . . . . 6 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 12. Normative References . . . . . . . . . . . . . . . . . . . . 6 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 7 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 1. Introduction Repository planning information is often spread across issue trackers, chat logs, pull request comments, prompts, and local notes. This makes it difficult for humans and automation to agree on the current state of planned work. ISSUES.md is a small Markdown-based format for keeping issue state close to the source repository. The format is designed to remain readable in ordinary Markdown tools while carrying enough structure for parsers to identify issue status, priority, dependencies, section ownership, and blocked work. Implementation experience is available from the ISSUES.md repository at https://github.com/MarcoPoloResearchLab/ISSUES.md. 2. Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP14] (RFC2119) (RFC8174) when, and only when, they appear in all capitals, as shown here. Repository issue document A Markdown file, commonly named ISSUES.md or .mprlab/ISSUES.md, that contains the planning state for a repository or product surface. Section A level-2 Markdown heading that groups issue entries into one of the format's canonical buckets. Tyemirov Expires 7 November 2026 [Page 2] Internet-Draft ISSUES.md Format May 2026 Organization subheading A Markdown heading below a section heading, such as a level-3 heading, that groups entries for human readability without creating a new issue category. Recurring entry A normal entry whose identifier ends with an uppercase R. For example, M001R is the recurring form of M001. A recurring entry represents standing or repeated work that remains visible during cleanup instead of being removed after a single run. Entry A single Markdown list item that begins with an ISSUES.md status marker and identifier. Body Indented Markdown content attached to an entry. 3. Document Shape An ISSUES.md document MAY begin with a level-1 Markdown heading. It SHOULD contain the following level-2 section headings: 1. BugFixes 2. Improvements 3. Maintenance 4. Features 5. Planning Parsers SHOULD preserve non-issue Markdown outside these sections when round-tripping a document. Formatters SHOULD emit the canonical section order above unless a caller explicitly requests source-order preservation. A section MAY contain organization subheadings. An organization subheading MUST NOT create a new canonical issue category. Entries under an organization subheading inherit the nearest enclosing canonical level-2 section for identifier validation. Tyemirov Expires 7 November 2026 [Page 3] Internet-Draft ISSUES.md Format May 2026 Recurring or standing work MAY be grouped under an organization subheading named Recurring. The canonical representation of a recurring entry is still the identifier suffix described in Section 4. Parsers SHOULD treat entries under a Recurring organization subheading as recurring when normalizing a document. Scheduling such work is outside the scope of this format. 4. Entry Syntax Each issue entry is a Markdown list item using this shape: - [ ] [B001] (P1) Short title Body lines... STATE is one of the following status markers: [ ] Unresolved. [!] Blocked but unresolved. [x] Resolved. ID is REQUIRED and is scoped to the current section. The identifier MUST use a section letter followed by a three-digit sequence number and MAY append an uppercase R to mark the entry as recurring. B### BugFixes. I### Improvements. M### Maintenance. F### Features. P### Planning. Tyemirov Expires 7 November 2026 [Page 4] Internet-Draft ISSUES.md Format May 2026 A recurring entry uses the same section letter and sequence number rules with an uppercase R suffix inside the identifier. For example, M001R is a recurring Maintenance entry. A separate R token after the identifier is not part of this format. Parsers SHOULD accept a lowercase r suffix when reading and MUST emit the uppercase R suffix when writing canonical output. PRIORITY is OPTIONAL and, when present, MUST be one of (P0), (P1), or (P2). DEPS is OPTIONAL and, when present, MUST use comma-separated identifiers inside braces, for example {B001,I010}. The entry title is REQUIRED. The body is OPTIONAL and consists of Markdown lines indented so they remain attached to the list item. 5. Blocked Entries If an entry uses the [!] status marker, its body MUST include a line beginning with Blocked:. This line gives humans and tools a stable way to identify the reason an issue is not ready for execution. - [!] [B001] (P0) Fix startup race in issue refresh Blocked: waiting on production logs. 6. Validation Model Implementations SHOULD distinguish parse failures from validation failures. A parse failure indicates that an entry cannot be tokenized. A validation failure indicates that the entry is tokenized but violates a format rule. Validators SHOULD expose at least these profiles: legacy Accept historical documents and report compatibility warnings. strict Reject malformed identifiers, duplicate identifiers, and section mismatches. ci Apply strict validation for repository quality gates. Typical validation errors include MalformedIssueLine, InvalidIdentifier, InvalidDependency, MissingBlockedReason, and DuplicateIdentifier. Tyemirov Expires 7 November 2026 [Page 5] Internet-Draft ISSUES.md Format May 2026 7. Interoperability Considerations The format deliberately uses ordinary Markdown list items and headings. This lets implementations that do not understand ISSUES.md continue to display useful content while allowing conforming tools to extract a structured planning model. Implementations that rewrite documents SHOULD preserve user-authored body Markdown. Implementations MUST NOT silently drop issue entries that fail validation. 8. Non-Goals This document does not define a scheduler, timer syntax, job identifier, or portable recurrence expression. Systems that execute work on a schedule need to store those scheduling details outside the ISSUES.md document or in implementation-specific metadata. 9. Security Considerations ISSUES.md is a text format and does not require execution of embedded content. Implementations MUST NOT execute body content while parsing or validating a document. User interfaces that render Markdown bodies need to apply the same sanitization rules they would apply to any user-authored Markdown. A malicious issue body can contain links, images, or markup intended to mislead readers if rendered without appropriate controls. 10. Privacy Considerations ISSUES.md documents can contain implementation notes, customer details, personal data, or operational incidents. Tools that transmit issue bodies to external services, including AI systems, need explicit policy controls and user-visible disclosure. 11. IANA Considerations This document has no IANA actions. 12. Normative References [BCP14] Best Current Practice 14, . At the time of writing, this BCP comprises the following: Tyemirov Expires 7 November 2026 [Page 6] Internet-Draft ISSUES.md Format May 2026 Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . Examples - [ ] [B001] (P0) Fix startup race in issue refresh Blocked: waiting on production logs. Acknowledgments This draft is based on implementation experience from the ISSUES.md repository and its Markdown issue document parser. Author's Address V. Tyemirov Marco Polo Research Lab URI: https://github.com/MarcoPoloResearchLab/ISSUES.md Tyemirov Expires 7 November 2026 [Page 7]