Adopt Folder-Style Issue Specifications

[josecelano]

Parent EPIC: #2003

Goal: Make folder-style specifications the only layout for new issues and EPICs while retaining existing single-file specifications as historical artifacts unless a later issue has an independent reason to migrate one.

Scope:

• Create a root ADR that records the prospective folder-only policy and no-bulk-migration decision.
• Align issue creation, Markdown, and issue-lifecycle guidance.
• Remove single-file paths as a new-spec option while retaining accurate legacy references.
• Keep issue-local artifacts beside ISSUE.md or EPIC.md.

Boundary: Do not bulk-migrate legacy specs, build migration tooling, or change refactor-plan conventions without a separate decision.

Verification: Run linter all and cargo test --doc --workspace; exercise a new-folder and legacy-spec scenario.

[da2ce7]

One friction in the issue-specification conventions, found while aligning EPIC #2190 (PR #2193) with the guides; reported here because this issue owns the folder-style spec conventions.

F5 — drafts/README.md and the skill set a bar for "established parent" that nothing operationalizes

• docs/issues/drafts/README.md:20-25: "Do not infer a parent EPIC from related work; leave epic: null and use an unnumbered name until the relationship is established."
• create-issue/SKILL.md:68-70: "Do not infer a parent EPIC from related issues, ADRs, or topic overlap. If the parent is not explicitly established, use an unnumbered descriptive draft folder."

Symptom: neither document says what establishes the relationship. A maintainer assigning the child? A row in the parent's table? An argument from the parent's written scope? EPIC #2190 hands two drafts to EPIC #2003 on an argument from #2003's own stated In Scope and its stated exception — much stronger than topic overlap, and still not "explicit" by any stated test. The drafts were therefore prefixed 2003- and set epic: 2003 before #2003's maintainer had seen them, which the rule appears to forbid and which no reviewer can adjudicate.

Proposed resolution: name the establishing act. A workable test: the relationship is established when the parent EPIC's specification carries a row for the child, or a maintainer says so on the issue. Under that test EPIC #2190's two adoptions are established the moment #2003's table gains their rows — which is a concrete, checkable event, and the one PR #2193 now performs.

---

[da2ce7]

Two more frictions with folder-style specifications, found while drafting an unfiled specification with the create-issue skill.

F9 — An unfiled draft cannot satisfy the branch: key of the ISSUE template

Sources. docs/templates/ISSUE.md:9 fixes branch: "{issue-number}-{short-description}". The create-issue skill (Step 6, spec-only pull request) requires the key to name the -spec branch when the specification is submitted before implementation. A draft under docs/issues/drafts/ has no issue number yet, so it can satisfy neither form; the drafting flow the skill prescribes (draft, review, file, then move) produces a frontmatter value that is wrong until the last step. This is the ISSUE-template counterpart of F2 above, which reported the same key for the EPIC template.

Proposed resolution. State the draft convention in the template itself (keep the {issue-number} placeholder verbatim until filing, and note that a spec-only PR sets the -spec name), so a draft with the placeholder is correct by definition and the move step replaces it.

F10 — The line-wrapping rule for repository Markdown is not actionable

Sources. .github/skills/dev/planning/write-markdown-docs/SKILL.md:93 says, for .md files in the repository: "Follow repo config (MD013 disabled, but keep lines readable)". Every recent folder-style specification (for example docs/issues/open/2175-merge-tool-symlink-exceptions/ISSUE.md) is written one line per paragraph, which the same table prescribes explicitly for GitHub issue and PR bodies.

Symptom. "Keep lines readable" gives a contributor no rule to follow and a reviewer no rule to check, and it reads as permission to hard-wrap, which the examples do not do and which makes diffs of reflowed paragraphs unreadable.

Proposed resolution. State the rule for repository .md the way the GitHub-surface row already does: one line per paragraph and per list item, no hard wrapping; the viewer wraps.

[da2ce7]

Three more frictions in the same format, found while filing a folder-style specification (#2195) and its spec-only pull request through the create-issue and open-pull-request skills.

F11 — The PR title examples bracket the issue number; every live spec-only PR does not

Sources. .github/skills/dev/git-workflow/open-pull-request/SKILL.md:73-78 says "use Conventional Commit style, include issue reference" and its only examples are of the form feat(tracker-core): [#42] … and docs(agents): [#1697] …. The open spec-only pull requests #2187, #2193 and #2194 are all titled docs(issues): add specification for #NNNN, with a trailing bare number.

Symptom. A contributor following the skill produces a bracketed title that does not match its neighbours in the PR list; one following the examples departs from the skill's only stated form. The merge tool copies the title into the merge subject, so the inconsistency lands in history.

Proposed resolution. The skill states the spec-PR form explicitly, either as a third example (docs(issues): add specification for #N) or with one sentence saying the bracketed form is for implementation PRs that carry the [#N] tag.

F12 — Step 4 of create-issue names three of the frontmatter fields that change at filing, not all of them

Sources. .github/skills/dev/planning/create-issue/SKILL.md:209-231 (Step 4) says to update spec-path, "all internal artifact references", and "any issue number placeholders". Every filed spec (for example docs/issues/open/2183-adopt-calendar-msrv-policy/ISSUE.md:4,7,11) also changed status: draft → open, github-issue: null → the number, and last-updated-utc; the branch value's -spec form is stated only in Step 6 item 2.

Symptom. The fields that must change at filing are discoverable only by diffing an example; a spec filed by following Step 4 literally still reads status: draft and github-issue: null.

Proposed resolution. Step 4 enumerates the fields: status, github-issue (bare number, the form all filed specs use), spec-path, last-updated-utc, and a cross-reference to Step 6 item 2 for branch.

F13 — Filed specs disagree on what the first workflow checkpoint records after the move

Sources. docs/issues/open/2175-merge-tool-symlink-exceptions/ISSUE.md keeps "drafted in docs/issues/drafts/…" after filing; docs/issues/open/2183-adopt-calendar-msrv-policy/ISSUE.md rewrites it to "drafted and moved to docs/issues/open/2183-…/ISSUE.md". docs/templates/ISSUE.md carries only the drafts form.

Symptom. One convention leaves a dead path in every filed spec (the drafts folder no longer exists after the move, so link checkers and readers both hit a path that resolves to nothing); the other rewrites history the checkpoint was recording. Two live examples, no rule.

Proposed resolution. The template's first checkpoint reads "drafted and moved to docs/issues/open/{number}-{short-description}/ISSUE.md", or Step 4 states the rewrite; #2195 follows the 2183 form.

[da2ce7]

Frictions F14–F15 from the review of #2207 (archive of 19 closed specifications), 2026-09-11 — both about the frontmatter contract this issue owns.

• F14 — dev/planning/cleanup-completed-issues step 6 ("confirm that every changed Markdown frontmatter block is valid YAML") is too weak to protect the edit the skill mandates. In chore(issues): archive closed issue specifications #2207 the open/→closed/ reference repair left one related-artifacts item indented two spaces deeper than its siblings in five files. That is valid YAML: the over-indented line folds into the preceding scalar, so the parse succeeds and the list silently loses an entry (the 1588 spec goes from 12 entries to 11, with the closed-1586 path glued onto the task-inventory path). The check should compare the parsed item count against the raw - line count, or reject a sequence item indented deeper than its predecessor.
• F15 — no gate covers spec-frontmatter semantics at all. linter markdown, linter cspell and linter lychee all pass on a tree with corrupted related-artifacts blocks, and develop already carries three of them from earlier edits: docs/issues/closed/999-1978-optional-database-configuration/persistence-unavailable-scenarios.md line 12, tests/AGENTS.md line 8, and docs/issues/drafts/1488-si-11-migrate-http-tracker-token-lifecycle/ISSUE.md line 23 (an item at indent 7 following siblings at indent 5 in each). A linter frontmatter subcommand that parses every spec's block and checks list shape and the spec-path/status/github-issue fields would catch both this and the drift the folder-style migration is trying to remove.

[da2ce7]

Friction F30 from round r3 of #2207 (2026-09-11), about the frontmatter contract this issue owns.

• F30 — dev/planning/cleanup-completed-issues Step 4 states two rules that collide on the same file without saying which governs. Lines 195–197: "Do not rewrite immutable historical records (for example, past PR review summaries) merely because they accurately record the path that existed at the time. Update them only when they function as a live navigational reference." A past PR review summary such as docs/copilot-pr-reviews/pr-2153-copilot-suggestions.md is both: its body table records where a file sat when the thread was opened (historical), while its frontmatter semantic-links.related-artifacts is the document's machine-readable pointer at the artifacts it relates to (live navigation the moment anything walks the links). chore(issues): archive closed issue specifications #2207 resolved it the right way in 5bf2ff44 — frontmatter repaired, body left alone — but only after a review round was spent on the ambiguity, and the step gives a later editor no reason to land on the same split. One sentence would settle it: frontmatter semantic-links are always repaired; body text recording a path at a point in time is never rewritten. This is the same file class F14 covers, seen from the other side: F14 is about the repair being silently wrong, F30 about the rule being silent on whether to repair.