golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions 4 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

42
.out-of-scope/plan-md-execution-context-portability.md Normal file
View File

@@ -0,0 +1,42 @@
# Clone-Portable `<execution_context>` in Committed PLAN.md
GSD does not make the `<execution_context>` 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, `<execution_context>`'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 `<execution_context>` 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 `<execution_context>`
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 `<execution_context>` reference, which describes the install-relative behaviour.

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: