ffd353f080
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>
2.3 KiB
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
(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.