From 35ffc489fd4bb1351bc8e58be75420a35b950004 Mon Sep 17 00:00:00 2001
From: Tom Boucher <trekkie@nomorestars.com>
Date: Sat, 11 Jul 2026 13:14:15 -0400
Subject: [PATCH] docs(#2179): record the PLAN.md human-rendering rejection in
 .out-of-scope (#2180)

PLAN.md is a documented machine artifact ("Plans are prompts, not documents"),
consumed by gsd-executor/gsd-plan-checker/gsd-verifier and cross-AI reviewers,
with no documented human-review surface. Changing its <task>/<action> tag
convention to improve human GitHub rendering targets a non-goal and risks
silent extraction drift across ~6 surfaces. Rejected as wontfix.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 .out-of-scope/plan-md-human-rendering.md | 63 ++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 .out-of-scope/plan-md-human-rendering.md

diff --git a/.out-of-scope/plan-md-human-rendering.md b/.out-of-scope/plan-md-human-rendering.md
new file mode 100644
index 000000000..d73c1c0e9
--- /dev/null
+++ b/.out-of-scope/plan-md-human-rendering.md
@@ -0,0 +1,63 @@
+# Human-Readable Rendering of PLAN.md
+
+GSD does not change PLAN.md's structural tag convention (`<task>`, `<action>`,
+`<tasks>`, `<files>`, `<verify>`, etc.) to improve how a PLAN.md renders when a
+human opens the raw file in a markdown viewer on GitHub/GitLab.
+
+## Why this is out of scope
+
+PLAN.md is a **machine artifact**, not a human-facing document. The docs are
+explicit:
+
+- `docs/reference/plan-md.md` — a PLAN.md is *"an executable unit of work — a
+  structured document that tells an executor agent exactly what to build and how
+  to verify it was built correctly."*
+- `agents/gsd-planner.md` — *"Produce PLAN.md files that Claude executors can
+  implement without interpretation. Plans are prompts, not documents that become
+  prompts."*
+
+PLAN.md is produced by `gsd-planner` and consumed by `gsd-executor`,
+`gsd-plan-checker`, `gsd-verifier`, and cross-AI review agents. There is no
+documented step in which a human opens, reads, reviews, or signs off on a
+PLAN.md — unlike `SUMMARY.md` / `VERIFICATION.md`, which are produced for human
+validation.
+
+The reported symptom — alphabet-only tags like `<task>` / `<action>` tripping
+CommonMark's HTML-block rule so inner markdown renders as cramped run-on text —
+only manifests when a human views the raw file in a markdown renderer. It does
+**not** affect either machine consumer:
+
+- Tag location/extraction is regex-based (`extractTaggedBlocks` in
+  `src/markdown-sectionizer.cts`), operating on raw text, not rendered HTML.
+- Agents read the raw file content, not a rendered view.
+
+```js
+// The extraction contract is a raw-text regex, indifferent to CommonMark
+// HTML-block folding:
+new RegExp(`<${escapedTag}>([\\s\\S]*?)</${escapedTag}>`, 'g')
+```
+
+The proposed fixes (HTML-comment markers `<!-- task -->`, or underscored tag
+names `<task_node>`) would change a load-bearing machine convention that is
+duplicated across ~6 surfaces — the extractor regex, the `execute-plan` grep
+counter, `verify.cjs`, `decisions.cjs`, and the planner/executor schema docs. A
+drift between those surfaces silently breaks plan extraction (the executor finds
+zero tasks), which is a far worse failure than cosmetic rendering. The
+underscore option additionally increases token consumption on every plan read
+(longer tag names, repeated across every PLAN.md, read in full by the executor)
+and leaves the marker names visible as literal noise in any rendered view.
+Incurring that cost and risk to improve a rendering path that is not a
+documented use of PLAN.md does not align with the project's model of PLAN.md as
+an agent instruction set.
+
+The same reasoning covers the report's secondary point (unquoted `|` in PLAN.md
+frontmatter breaking rendered markdown tables): that too is a human-render
+concern for a machine artifact.
+
+**Revisit if** GSD ever introduces a human-review gate for PLAN.md — a step
+where a person reads and approves the plan before execution. At that point
+PLAN.md gains a documented human audience and its rendering becomes in-scope.
+
+## Prior requests
+
+- #2158 — "PLAN.md XML task tags trigger CommonMark HTML-block rule — task content renders as cramped run-on text"