golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(#2240): clarify PLAN.md <execution_context> is install-relative, record #2238 wontfix (#2241)

Browse Source 
The <execution_context> 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 <context>.
- .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) <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-07-13 11:58:02 -04:00
committed by GitHub
parent b5ce72f729
commit ffd353f080
2 changed files with 45 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/reference/plan-md.md
View File

@@ -118,7 +118,7 @@ Output: PostFeed and PostCard components wired to /api/feed.
### `<execution_context>`
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
<execution_context>
@@ -127,6 +127,8 @@ Lists workflow files the executor reads before starting. Always includes the exe
</execution_context>
```
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 `<context>` (below), whose repository-relative `@` paths resolve after a `git clone`.
### `<context>`
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: