From ffd353f080a27e9f3309a2590a6ee980c01a4d8f Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Mon, 13 Jul 2026 11:58:02 -0400 Subject: [PATCH] docs(#2240): clarify PLAN.md is install-relative, record #2238 wontfix (#2241) The reference presented @~/.claude/gsd-core/... as canonical and described the paths as files "the executor reads before starting". Both are misleading: the prefix is install- and runtime-relative (Claude global vs Cursor .cursor/gsd-core vs an absolute --local path), so a committed plan is not clone-portable, and /gsd-execute-phase loads the workflow from its own installed copy rather than gating on the committed block. - docs/reference/plan-md.md: describe the install-relative, non-clone-portable nature of the block and contrast it with repository-relative . - .out-of-scope/plan-md-execution-context-portability.md: record the #2238 wontfix decision (PLAN.md is a machine artifact; #2158 precedent) with a revisit-if condition. Refs #2238. Closes #2240. Co-authored-by: Claude Opus 4.8 (1M context) --- .../plan-md-execution-context-portability.md | 42 +++++++++++++++++++ docs/reference/plan-md.md | 4 +- 2 files changed, 45 insertions(+), 1 deletion(-) create mode 100644 .out-of-scope/plan-md-execution-context-portability.md diff --git a/.out-of-scope/plan-md-execution-context-portability.md b/.out-of-scope/plan-md-execution-context-portability.md new file mode 100644 index 000000000..e5989acd6 --- /dev/null +++ b/.out-of-scope/plan-md-execution-context-portability.md @@ -0,0 +1,42 @@ +# Clone-Portable `` in Committed PLAN.md + +GSD does not make the `` block in committed `PLAN.md` files +clone-portable — it does not rewrite the planner's install-relative +`@…/gsd-core/…` references into repository-relative or install-neutral paths so +that a committed plan reads identically across developers, machines, or runtimes. + +## Why this is out of scope + +PLAN.md is a **machine artifact**, not a human- or clone-facing document — the +same principle that governs [plan-md-human-rendering.md](./plan-md-human-rendering.md) +(from #2158). A committed PLAN.md is a per-run agent instruction set, produced by +`gsd-planner` and consumed in place by `gsd-executor`, `gsd-plan-checker`, and +`gsd-verifier`. There is no documented step in which a plan is read on another +machine after `git clone` without a local GSD install. + +Under that model, ``'s `@` references point at the reader's +own local GSD install (Claude `~/.claude/gsd-core/…`, Cursor `.cursor/gsd-core/…`, +or an absolute path for a `--local` install). They are install-relative by design, +and the executor loads those workflows from its own installed copy — it never +consumes the paths a *different* machine wrote into a committed plan. +`/gsd-execute-phase` builds its own `` inline from the +orchestrator's installed workflow (`workflows/execute-phase.md`), so the block a +planner writes into a committed plan does not gate execution anywhere. + +Making committed plans clone-portable would treat PLAN.md as a shared +cross-developer document — the boundary #2158 declined to cross — for a block that +no consumer reads across machines. + +**Revisit if** GSD introduces a documented cross-developer / cross-machine contract +for committed PLAN.md — a human- or teammate-facing use where plans are read after +`git clone` without a local install — at which point `` +portability becomes in scope. + +## Prior requests + +- #2238 — "Planner embeds machine-specific gsd-core paths in committed PLAN.md execution_context" + +## Related + +- `.out-of-scope/plan-md-human-rendering.md` — #2158, the governing "PLAN.md is a machine artifact" precedent. +- `docs/reference/plan-md.md` — the `` reference, which describes the install-relative behaviour. diff --git a/docs/reference/plan-md.md b/docs/reference/plan-md.md index 38982e2d8..a76197027 100644 --- a/docs/reference/plan-md.md +++ b/docs/reference/plan-md.md @@ -118,7 +118,7 @@ Output: PostFeed and PostCard components wired to /api/feed. ### `` -Lists workflow files the executor reads before starting. Always includes the execute-plan workflow; adds the checkpoints reference when the plan contains checkpoint tasks: +Lists the workflow files associated with executing the plan. Always includes the execute-plan workflow; adds the checkpoints reference when the plan contains checkpoint tasks: ```xml @@ -127,6 +127,8 @@ Lists workflow files the executor reads before starting. Always includes the exe ``` +These `@` paths point at the local GSD install, not at repository files. The prefix shown here (`~/.claude/gsd-core/…`) is the Claude global-install location; other runtimes and local installs resolve to their own install directory — for example `.cursor/gsd-core/…`, or an absolute project path for a `--local` install. Because the prefix is install-relative, this block is not clone-portable: a committed plan carries whichever prefix the authoring install had. Execution does not depend on it — `/gsd-execute-phase` loads the execute-plan workflow from its own installed copy — so the block records the execution context rather than resolvable repository references. Contrast `` (below), whose repository-relative `@` paths resolve after a `git clone`. + ### `` References source files the executor needs to read. Includes project-level planning docs and any source files whose patterns or types the plan must replicate. Prior plan `SUMMARY.md` files are included only when there is a genuine dependency (imported types, shared decision) — not reflexively: