2f86278b5e
* test(#3003): failing-first suite for declared deletions in cleanup-wave Binds the guard's opt-in before it exists, so the suite is RED against next. The rows that carry the weight are the over-authorization set: a directory declaration must not authorize its children, a glob declaration must authorize nothing, and a declaration must not act as a string prefix of another path. Each of those BLOCKS, and each would PASS under a prefix, glob, or startsWith matcher — which is how a path list quietly degrades into the boolean opt-in #3003 explicitly rejected. The glob row matters most: declaredScopePrefix already returns null ("matches everything") for a glob-leading pattern, correct for the advisory it serves and catastrophic for a gate. Also pinned: a failed deletion check blocks on its own reason rather than being filtered into a pass; the block detail names only the undeclared residue so the operator is not misdirected by paths that were fine; an entry with no declaration blocks exactly as before; junk and non-array declarations do not authorize; and a blocked entry still isolates rather than aborting the wave (#2852, which must stay fixed). Two advisory rows cover an interaction found while designing: git diff --name-only includes deleted paths, so without unioning the declaration into the #2596 scope check, authorizing a deletion would raise SCOPE_OUT_OF_DECLARED against the very path just authorized. A seeded property states the whole invariant the three over-authorization rows sample: a deletion merges iff its normalized path is in the declared set. * feat(#3003): declared deletions opt-in for the cleanup-wave guard The deletions guard blocked the merge-back of any executor branch whose diff removed a file, with no way to say a removal was intended. A plan that folded one test file into a sibling could not be merged by the tool meant to merge it, forcing a manual --no-ff outside the tool -- strictly less safe than what the guard protects against. A plan now declares removals in its own frontmatter (files_deleted), and that list rides the same path files_modified already travels: plan-document parse -> phase plan JSON -> the per-plan worktree gate -> record-agent/create --deletions -> declared_deletions on the manifest entry -> the guard. The guard blocks only the deletions NOT in that list. A path list rather than a boolean, per the pinned decision: a boolean disarms the guard for the whole entry, so an unexpected deletion riding along with a declared one would pass unnoticed. Matching is exact after the module's shared normalizer -- never a prefix, never a glob. Both would let one declaration authorize a whole set, which is the mass-deletion accident the guard exists to catch. That also means declaredScopePrefix is deliberately NOT reused here: it returns null ("matches everything") for a glob-leading pattern, which is right for the advisory it serves and would silently disarm a gate. The block detail now carries only the undeclared residue, so an operator is not sent looking at paths that were fine. A failed deletion check still blocks on its own reason and is never filtered into a pass. A blocked entry still isolates rather than aborting the wave (#2852). The #2596 scope advisory unions the declaration into its declared set -- git diff --name-only includes deleted paths, so without that, authorizing a deletion would immediately warn that the same path was out of declared scope. Optional and additive throughout: files_deleted is absent from PLAN_REQUIRED_FIELDS, a manifest entry without declared_deletions keeps the original unconditional block, and omitting --deletions leaves the on-disk entry shape untouched. Supersedes the spent #2856 emitted-drift ack entry for execute-phase.md, the same supersede that entry performed on #3370 and #3370 on #3324. * fix(#3003): wire --deletions on every dispatch surface, not just one Review found the feature inert on two of three dispatch paths. execute-phase.md (harness inline) passed --deletions, but the orchestrator-worktree path (executor-isolation-dispatch.md, worktree.create) and the Fleet-parallel batch path (capabilities/claude-orchestration/fragments/execute-wave-pre.md, worktree.record-agent) still passed only --files. A plan declaring files_deleted would have merged on one path and been blocked on the other two -- the exact bug #3003 exists to fix, left unfixed where most of the isolation actually runs. Worse, per-plan-worktree-gate.md already claimed --deletions was passed 'on the same worktree.record-agent / worktree.create calls', which was false for both untouched sites. A doc asserting coverage that does not exist is how a gap survives review. All four surfaces now pass the flag, verified by sweeping every .md under gsd-core/, capabilities/, commands/, skills/ and agents/ that invokes worktree.record-agent or worktree.create: each one that passes --files now also passes --deletions. The isolation-dispatch note explains why this flag, unlike --files, is not advisory -- omitting it does not skip a check, it blocks a merge the plan declared. Regenerates capability-registry.cjs, which the fragment edit made stale. Neither newly-grown file needs an emitted-drift ack: executor-isolation-dispatch.md sits under workflows/execute-phase/steps/ and execute-wave-pre.md under capabilities/, both outside currentSizes()'s non-recursive scan of gsd-core/workflows/ and agents/. * docs(#3003): document files_deleted where a plan author will actually find it The feature's entire user surface is one plan-frontmatter field, and the canonical reference for that frontmatter -- docs/reference/plan-md.md, the table that documents every other key -- never mentioned it. A field nobody can discover ships as a field nobody uses. Adds the files_deleted row and an example entry in all five locales (en, ja-JP, zh-CN, ko-KR, pt-BR), stating the property that makes the opt-in safe: matching is exact per path after separator normalization, with no globs and no directory prefixes, so a declaration can never authorize more than it literally lists, and omitting the field keeps the guard's original unconditional block. Also corrects two claims in the scope-conformance how-to that this change made false. Its opening paragraph described the recorded declared scope as files_modified alone; declared_deletions is now unioned into that comparison. Its "Renames are not detected specially" bullet asserted the deletions guard blocks any entry whose diff contains a deletion, full stop -- which was the whole point of #3003 and is no longer true. Reworked to say what now decides a rename's fate: declare the old path in files_deleted and both halves become ordinary paths for the advisory check, which is also why the old path needs no separate files_modified entry. Documentation that describes the pre-change behavior of the thing being changed is worse than no documentation, because a reader trusts it. * fix(#3003): close every review finding on the declared-deletions opt-in Two independent isolated reviewers, correctness and security. Neither found a blocker; both found real defects, and the directive treats a finding at any severity as blocking. All of them are fixed here. MAJOR -- the submodule worktree gate could not see a deletion-only plan. per-plan-worktree-gate.md intersected $SUBMODULE_PATHS against $PLAN_FILES alone, while $PLAN_DELETIONS was extracted and then never used. Before files_deleted existed, a path had to appear in files_modified to be planned at all, so the gate saw it; the new field plus the new docs telling authors a deleted path needs no files_modified entry opened a hole where a plan whose only submodule touch is a removal kept worktree isolation on -- the exact case #2772 disabled it for. Both channels now feed the intersection. Note the posture is deliberately the OPPOSITE of the cleanup-wave guard: there the channels stay apart because a deletion AUTHORIZATION must never be inferred; here they merge because a safety fallback must never MISS a touch. MAJOR -- same-wave conflict detection could not see a deletion. The planner's implicit-dependency rule compared files_modified only, so plan A editing src/x.ts and plan B declaring files_deleted: [src/x.ts] scored as conflict-free and ran in parallel: one branch removing what the other is writing, which is the sharpest conflict there is. Overlap is now computed across both channels. MINOR (both reviewers, one root cause) -- the advisory union gave one field two matching rules. declared_deletions was unioned into the scope list handed to planWaveScopeConformance, which reads it with prefix-and-glob semantics. So a field that is exact-match-only at the gate silently became wider at the advisory: ["*.md"], inert at the gate, yielded a null prefix meaning "matches everything" and muted the advisory completely, and ["src"] muted all of src/. The union also activated the advisory on plans that declared no modification scope at all, warning on every modified path. Replaced with subtraction from the findings, gated on files_modified alone. One field, one rule, everywhere. MINOR -- core.quotepath made the feature silently inert for non-ASCII paths. git emits "tests/\303\251.ts" C-escaped and quoted, which never equals the declared plain path, so a correctly declared deletion of tests/é.ts would block forever with nothing pointing at the encoding. Both diffs now pass -c core.quotepath=false. NIT -- flag() consumed a following flag as a value, so --deletions --files x swallowed --files and dropped both. Now treated as a missing declaration, which fails closed. Fixed at both call sites; the helper is duplicated verbatim in cmdWorktreeRecordAgent and cmdWorktreeCreate and leaving one would reintroduce it. TEST -- one test passed for the wrong reason. "a declared deletion is in scope for the advisory" asserted only that warnings omit the deleted path; under a full revert the entry blocks first, warnings come back empty, and the negative assertion passes anyway. It now asserts the entry actually merged, which is the load-bearing half. Four regressions added, one per fix above. Docs corrected rather than extended. The rename bullet in the scope-conformance how-to claimed a rename whose delete side is undeclared never reaches the advisory. Verified false: git's rename detection is on by default, so a pure rename is a single R entry that appears in no --diff-filter=D output and was never gated, before or after #3003. Only a rename that edits enough to fall below the similarity threshold decomposes into add+delete. The pre-existing sentence made the same wrong claim; this restates it correctly instead of sharpening the error. The localized plan-md.md reference edits are reverted: the PR template requires docs content added here to be English, and the translations already lag by three fields, so English-only is the repo's standing posture, not an oversight. Agent-file size caps respected: gsd-planner.md is XL-tier by bytes but carries a separate 49152-LF-CHAR cap asserted by four suites, so its edit is deliberately terse and lands at 49141 with 11 chars of headroom, with the rationale moved to docs/reference/plan-md.md, which has no cap. gsd-plan-checker.md lands at 49107 bytes, 45 under the LARGE cap. Both acks merged into the existing fragments that already name those paths, since two ack sources may never name the same path. * fix(#3003): decode git's path quoting instead of changing the git argv The previous commit's non-ASCII fix turned the remote suite red: 44 failures, 42 of them "unexpected git call: -c core.quotepath=false diff --diff-filter=D --name-only ...". The suite's git mocks match on exact argv, so adding two flags to the deletions diff and the advisory diff invalidated every existing fixture in tests/worktree-safety.test.cjs. Rewriting dozens of fixtures to accommodate one flag would be paying a large Hyrum's-law bill to fix a small defect. Both execGit calls are reverted to their original argv. The C-quoting is now decoded in normalizeScopePath instead, via a new decodeGitQuotedPath helper. That is the better fix on its own merits, not merely the cheaper one: the git argv is untouched so no fixture moves, the decode lands on the ONE normalizer already applied to both sides of the comparison so the declared and reported paths cannot disagree, and it holds regardless of the user's own core.quotepath setting rather than only when we remember to override it. A value not wrapped in a leading AND trailing quote is returned completely untouched, so the plain-ASCII path -- the overwhelmingly common case -- is byte-identical to before. Escapes decode to BYTES collected into a Buffer and UTF-8 decoded only at the end, because \303\251 is two bytes forming one character and decoding them separately yields mojibake. Malformed input never throws: a trailing lone backslash or a short octal escape degrades to the literal character, since one bad path must not take down a cleanup wave. Caught while reviewing the helper: the non-escape branch pushed a UTF-16 code unit rather than UTF-8 bytes. Git always escapes non-ASCII so its own output was fine, but this normalizer runs on the DECLARED side too, and an author may write a quoted path holding a literal é -- pushing 0xE9 alone is invalid UTF-8, so the declaration would decode to a replacement character and silently stop matching. That is precisely the failure this change removes, reintroduced on the other side of the comparison. Now converts whole code points, surrogate pairs intact. The other 2 failures: tests/parallel-dependent-plans.test.cjs pins the exact unbackticked substring "files_modified overlap" in gsd-planner.md, and rewording that comment to "declared-scope overlap" deleted it. The comment is restored verbatim and the files_deleted change rides in the pseudocode and the Rule sentence instead. Recorded in the ack fragment so the next contributor does not rediscover it the same way. Four regression tests cover the decode through the public cleanup-wave seam (the helper is module-private): a declared non-ASCII deletion merges against a C-quoted git report, the symmetric case where the DECLARATION is the quoted form, an undeclared non-ASCII deletion still blocks with the residue naming the decoded path an operator can act on, and a path merely containing a quote is left alone. Plain ASCII was already covered and is not duplicated. * fix(#3003): revert the leading-dash flag guard, the review nit was wrong The remote suite came back with 2 failures, down from 44, and both point at the same thing: tests/worktree-safety.test.cjs:7045 already pins the opposite contract, deliberately. test('a flag-shaped --files value is not re-parsed as a flag', ...) recordAgent(['--files', '--branch']) -> files_modified === ['--branch'] -> branch === 'worktree-agent-a1' ("the real --branch value must be untouched") So consuming the next argv element positionally, whatever its shape, is the tested intent of this parser, not an oversight. The security reviewer's nit claimed --deletions --files x would "swallow --files and drop both". It does not: each flag runs its own indexOf, so --deletions records the literal '--files' while --files independently still resolves to x. And that literal is a path git never reports as deleted, so it authorizes nothing -- already fail-closed with no guard at all. The guard bought no safety and silently changed --files behavior along the way, outside this issue's scope. Reverted at both call sites, which are byte-identical again, along with the test asserting the reverted behavior and the docs sentence describing it. The nit is recorded as REJECTED in the review artifact with the reasoning above, rather than as fixed -- a finding that turns out to be wrong should leave a trace of why, or the next reviewer files it again. docs/CLI-TOOLS.md now states the positional-read behavior plainly instead, so the next person meets it as documented intent rather than rediscovering it through a red suite. * chore(#3003): backfill changeset pr number to 3757 * test(#3003): cover parsePlanDocument's filesDeleted branch to clear the mutation gate CI's Stryker shard for plan-document failed at 73.28 against a break threshold of 75: 170 killed, 62 survived, 232 total. Eight of those survivors are the filesDeleted block this issue added to parsePlanDocument, which shipped with no direct coverage at all -- the field was exercised end to end through the cleanup-wave tests, but the parser itself was never called with a plan that declares it, so every mutant in the block lived. Four tests, each pinned to specific mutants rather than written for coverage percentage: - absent key yields exactly [] -- kills the array-literal seed (["Stryker was here"]) and the `fmDeleted = true` conditional, which would otherwise produce ["true"] - a scalar underscore `files_deleted:` wraps into a one-element array -- kills `fmDeleted = false`, the `&&` logical-operator swap, the `fm[""]` string mutation on the first operand, the emptied if-block, and the ternary's non-array branch - an array-valued hyphenated `files-deleted:` maps element-wise -- kills the `fm[""]` mutation on the SECOND operand (only reachable when the legacy hyphen alias is the one carrying the value) and the ternary's array branch - an empty list yields [] -- boundary case, and a genuinely distinct one from the absent key: [] is truthy in JS so it ENTERS the if, and only Array.isArray's true branch mapping over nothing produces the same [] Threshold arithmetic: 174 of 232 are needed for 75%, and these take it to about 178, so the shard clears with margin rather than landing on the line. Every expected value was confirmed by executing the built parser before being asserted, not inferred from reading the source. --------- Co-authored-by: sim <sim@local>
24 KiB
24 KiB
PLAN.md schema reference
A per-plan PLAN.md is GSD Core's executable unit of work — a structured document that tells an executor agent exactly what to build and how to verify it was built correctly. This page documents its structure. See docs index.
Overview
Plans live inside phase directories at:
.planning/phases/<NN>-<slug>/<NN>-<PP>-PLAN.md
For example: .planning/phases/03-post-feed/03-02-PLAN.md (Phase 3, Plan 2).
Plans are produced by the gsd-planner agent (spawned by /gsd-plan-phase) and consumed by execute-phase. A phase typically contains between one and four plans; plans within a phase are assigned to execution waves so that independent work runs in parallel.
YAML frontmatter
Every PLAN.md opens with a YAML frontmatter block between --- delimiters.
Annotated example
---
phase: 03-post-feed
plan: 02
type: execute
wave: 2
depends_on: ["03-01"]
files_modified:
- src/components/PostFeed.tsx
- src/components/PostCard.tsx
- src/app/feed/page.tsx
files_deleted:
- src/components/LegacyFeed.tsx
autonomous: true
requirements: ["FEED-01", "FEED-03"]
user_setup: []
must_haves:
truths:
- "User can scroll through posts from followed accounts"
- "Each post shows author avatar, name, timestamp, and content"
- "Empty state appears when no posts exist"
artifacts:
- path: "src/components/PostFeed.tsx"
provides: "Scrollable post list"
min_lines: 40
- path: "src/components/PostCard.tsx"
provides: "Individual post card"
exports: ["PostCard"]
key_links:
- from: "src/components/PostFeed.tsx"
to: "src/app/api/feed/route.ts"
via: "fetch in useEffect — calls /api/feed endpoint"
pattern: "fetch.*api/feed"
---
Frontmatter field reference
| Field | Required | Type | Purpose |
|---|---|---|---|
phase |
Yes | string | Phase identifier, e.g. 03-post-feed. |
plan |
Yes | string | Plan number within the phase, e.g. 02. |
type |
Yes | execute or tdd |
execute for standard plans; tdd for test-driven plans where tests are written before implementation. |
wave |
Yes | integer | Execution wave. Plans in wave 1 run in parallel (no dependencies). Plans in wave 2+ wait for all plans in the previous wave to complete. Pre-computed at plan time by gsd-planner. |
depends_on |
Yes | array of plan IDs | Plans this plan must wait for. Empty array = wave 1. Example: ["03-01"] means this plan runs after Plan 01 in Phase 3. |
files_modified |
Yes | array of paths | Every file this plan creates or modifies. Used by the plan-checker to detect same-wave file conflicts and by execute-phase for merge tracking. |
files_deleted |
No | array of paths | Every file this plan deliberately removes. The post-wave cleanup gauntlet blocks the merge of any executor branch whose diff deletes a file — a net against a mass-deletion accident — and this field is the opt-in that names the exceptions. Matching is exact per path after separator normalization: a declared path merges, an undeclared one still blocks that plan's entry (and only that entry). There are no globs and no directory prefixes, so a declaration can never authorize more than it literally lists. Omit the field and the guard's original unconditional block stays in force, which is why absence is always the safe default (#3003). Counts toward same-wave conflict detection alongside files_modified: a plan deleting a file another plan in the same wave is editing is the sharpest conflict there is — one branch removes what the other is writing — so the two plans are pushed into different waves regardless of which side holds the deletion. |
autonomous |
Yes | boolean | true when all tasks are type auto. false when the plan contains any checkpoint:* task that requires human interaction. |
requirements |
Yes | array of IDs | Requirement IDs from ROADMAP.md that this plan addresses. Every phase requirement ID must appear in at least one plan's requirements field. Empty arrays are a BLOCKER. |
user_setup |
No | array of objects | External-service setup steps that Claude cannot automate (account creation, secret retrieval, dashboard configuration). When present, execute-phase generates a USER-SETUP.md checklist for the developer. |
status |
No | superseded |
Marks a plan that was deliberately reassigned or abandoned mid-phase and will never be executed. A status: superseded plan is excluded from the phase's plan and summary counts, so it never holds the phase below 100%. See Superseded plans. Any other value (or the field's absence) has no effect on counting. |
estimate |
No | object | Projected execution cost: {tokens, raw_tokens, tasks, confidence} (#2631, ADR-2629). tokens is an estimateTokens-scale projection with the project's calibration factor already applied (which is why the plan-checker passes --calibrated to estimate-check — re-applying it would square the correction); confidence (low/med/high) is derived from the calibration sample count, never self-rated. Additive and optional — a plan without it behaves exactly as before. A plan estimated above workflow.smart_zone_tokens is flagged with a split recommendation at plan time; the flag is advisory and never blocks. |
must_haves |
Yes | object | Goal-backward verification criteria. See below. |
agent_hint |
No | string | Per-plan specialist executor routing (#1689). Name of a subagent that shares the gsd-executor execution contract (reads execute-plan.md, atomic-commit protocol). When the named agent resolves on the active runtime (an agent file exists in the runtime's agent dir), execute-phase dispatches it instead of gsd-executor. Unset/unresolved → gsd-executor, byte-identical to today. Default-on via workflow.agent_hint_routing; set false to disable. See Per-plan executor routing. |
gap_closure |
Only in gap-closure mode | string, exact match | Must be exactly the literal lowercase true — validated as a string comparison, not a YAML boolean, so True, TRUE, yes, and 1 are all rejected. Required on every plan generated by /gsd-plan-phase --gaps, checked by the plan-gap-closure schema (src/frontmatter.cts) rather than plan. /gsd-execute-phase --gaps-only filters strictly on this field, so an omitted or wrong-valued gap_closure on a gap-closure plan means it is silently skipped — zero executors spawned, no error (#2847). Standard and reviews-mode plans validate against the unmodified plan schema, which neither requires nor checks this field (nothing rejects it as an extra field either, if present). |
Per-plan executor routing
A plan can opt into a specialist executor by setting agent_hint: to the name of a subagent that shares the gsd-executor execution contract — it reads execute-plan.md, follows the atomic-commit protocol, and carries Read/Edit/Write/Bash. A Flutter specialist, for example:
---
agent_hint: well-me-flutter-engineer
---
At dispatch, execute-phase resolves the hint against the active runtime's agent directory (both project-local and user-global, across the runtime's filename variants — .md, .agent.md, .toml, …) and dispatches the named subagent via subagent_type. If the field is absent, blank, or the named agent does not resolve, the plan dispatches to gsd-executor — byte-identical to behavior without the field. Routing is gated by workflow.agent_hint_routing (default-on; see CONFIGURATION).
The specialist agent is an ordinary agent file (e.g. agents/well-me-flutter-engineer.md on Claude Code); there is no separate registration manifest.
Superseded plans
A phase reads complete when every *-PLAN.md has a matching *-SUMMARY.md. When a plan is reassigned or dropped mid-phase — its work folded into a later plan — it will never gain a summary, and without a marker it would pin the phase below 100% forever (the plan-level analogue of a retired phase). Add status: superseded to that plan's frontmatter to exclude it from both the plan count (denominator) and the summary count (numerator):
---
phase: 05-api
plan: "12"
type: execute
status: superseded
---
A phase with 13 plans, two of them superseded, then reads 11/11 → complete — no fabricated summary required. The match is case-insensitive. Plans without the marker are counted exactly as before.
must_haves field
must_haves captures what must be observably true for the phase goal to be achieved. It is derived during planning and verified after execution by the gsd-verifier agent.
Sub-fields
| Sub-field | Type | Purpose |
|---|---|---|
truths |
array of strings | Observable behaviours from the user's perspective. Each must be verifiable. Example: "User can send a message", not "WebSocket library installed". |
artifacts |
array of objects | Files that must exist with substantive implementation (not stubs). |
artifacts[].path |
string | File path relative to project root. |
artifacts[].provides |
string | What capability this file delivers. |
artifacts[].min_lines |
integer (optional) | Minimum line count to be considered non-stub. |
artifacts[].exports |
array of strings (optional) | Expected named exports to verify. |
artifacts[].contains |
string (optional) | Regex or literal pattern that must appear in the file. |
key_links |
array of objects | Critical connections between artifacts — the wiring that makes the system work end-to-end. |
key_links[].from |
string | Source file (relative path from project root). Must be a literal file path — describe components or symbols in via:. |
key_links[].to |
string | Target file (relative path from project root). Must be a literal file path — describe endpoints, modules, or APIs in via:. |
key_links[].via |
string | Description of how they connect, including any endpoint, component, or symbol name (e.g. fetch in useEffect — calls /api/feed, Prisma query via prisma.message, import). |
key_links[].pattern |
string (optional) | Regex to verify the connection exists in source. |
Body structure
After frontmatter, the plan body uses named XML-style blocks read by the executor agent.
<objective>
States what the plan delivers and why it matters for the project:
<objective>
Implement the post feed as a scrollable card list.
Purpose: Core display feature for the social feed phase.
Output: PostFeed and PostCard components wired to /api/feed.
</objective>
<execution_context>
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:
<execution_context>
@~/.claude/gsd-core/workflows/execute-plan.md
@~/.claude/gsd-core/templates/summary.md
</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:
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@src/components/UserCard.tsx
</context>
<tasks>
Contains one or more <task> elements. Every task element must carry <name>, <files>, <read_first>, <action>, <verify>, <acceptance_criteria>, and <done> for type="auto" and type="tracer" tasks. Optional <precondition> (see Preconditions) and <reversibility> (see Reversibility) elements may sit between <name> and <files>.
Preconditions
<precondition> is an optional element on <task> (issue #1949, The Pragmatic Programmer Topic 23 — Design by Contract). It states, in a single line of runnable/checkable prose, what must already be true for the task to begin safely. It closes the front-of-task side of the contract triad — preconditions (before) ↔ postconditions (<verify>/<done>/<acceptance_criteria>, after) ↔ invariants (must_haves.truths, across the whole plan).
<task type="auto">
<name>Add /reveal endpoint handler</name>
<precondition>server bootstraps and responds to GET /health (from the tracer slice)</precondition>
<files>server/reveal.ts</files>
<action>…</action>
<verify>curl /reveal?path=… opens the OS file manager</verify>
<done>Endpoint committed and manually verified</done>
</task>
Optional and back-compat: a plan that omits <precondition> on every task behaves exactly as today — the executor skips the check with no visible change. Adding <precondition> to a task tells the executor to assert it before any other task work (read-only checks only: file existence, env var presence, idempotent health pings; no side-effecting checks — halt and surface a checkpoint if one seems required) and halt (returning a checkpoint:human-verify, no partial commit) on an unmet precondition. Plans that include <precondition> pass verify plan-structure unchanged — the structural validator checks for the presence of required tags and does not reject unknown optional tags.
Emission cases (planner-side): emit <precondition> only when a task relies on state the plan's own depends_on ordering does not already guarantee. Three cases cover every legitimate use:
- External service setup (
user_setupfrontmatter) — the consuming task ties a specific setup step to itself so the executor halts if the setup was skipped. - Prior-phase artifact dependency — a generated schema, a migration's dist output, a contract file from an earlier phase. Cross-phase
depends_ondoes not cross phase boundaries, so<precondition>is the explicit pointer. - Environment variable / runtime configuration — a tool, API, or script the task invokes requires an env var or runtime config that exists now, not at plan time.
Full emission rules, anti-patterns ("the system is ready" is not checkable; do not use <precondition> for intra-plan sequencing — that is what depends_on is for), and the contract triad mapping: see gsd-core/references/planner-preconditions.md.
Reversibility
<reversibility> is an optional element on <task> (issue #1951, The Pragmatic Programmer Topic 15 — "Reversibility"). It records how costly the decision the task implements would be to undo, so a one-way-door choice gets a human beat before the agent walks through it. The rating attribute carries the classification; the body carries a one-line rationale.
<task type="auto">
<name>Define the on-disk event log format</name>
<reversibility rating="one-way">Phases 4-6 read this file; changing the
format after they land requires a migration for every existing project.</reversibility>
<files>src/event-log.cts</files>
<action>…</action>
<verify><automated>npm run test:unit -- event-log</automated></verify>
<done>Format documented and written by the writer under test</done>
</task>
| Rating | Meaning | Effect on the plan |
|---|---|---|
reversible |
Undo is local and cheap. | None. This is the default when no rating is given. |
costly |
Undo touches many call sites or needs a coordinated change. | Flagged in the plan so the reader sees the weight. Never blocks. |
one-way |
Undo requires a migration, breaks a published contract, or is impossible. | The planner inserts a checkpoint:decision immediately before the dependent task. |
Optional and back-compat: a plan that omits <reversibility> on every task behaves exactly as today — no flag, no checkpoint. Plans that include it pass verify plan-structure unchanged; the structural validator checks for the presence of required tags and does not reject unknown optional tags.
Autonomy: inserting a checkpoint:decision means the plan contains a checkpoint, so its frontmatter must set autonomous: false.
Override: /gsd-plan-phase --no-reversibility-gates (REVERSIBILITY_GATES=false) suppresses checkpoint insertion for intentionally-unattended runs. Ratings are still recorded and costly items are still flagged — the override changes what stops the run, not what the plan remembers.
Full taxonomy, emission rules, and anti-patterns (chiefly: rating everything one-way produces checkpoint fatigue; prefer removing irreversibility over gating it): see gsd-core/references/planner-reversibility.md.
Task types
| Type | Use | Autonomy |
|---|---|---|
auto |
Everything the executor can do independently. | Fully autonomous. |
tracer |
The leading thin end-to-end slice a plan starts with by default (tracer-first) — production-quality, wired through every layer, with a real end-to-end <verify>. |
Fully autonomous; after committing, the executor runs the tracer's <verify> as an early integration gate — autonomous runs halt on failure before expansion, interactive runs present a checkpoint:human-verify. |
checkpoint:human-verify |
Visual or functional verification that requires a human to look at a running UI or service. | Pauses execution; presents to the developer; resumes on approval. |
checkpoint:decision |
Implementation choices that arose during execution and require the developer's input. | Pauses execution; presents options; resumes on selection. |
checkpoint:human-action |
Truly unavoidable manual steps (account creation, hardware interaction). Used sparingly. | Pauses execution; resumes on confirmation. |
Plans that contain any checkpoint task must set autonomous: false in frontmatter.
auto task structure
<task type="auto">
<name>Task 1: Create PostCard component</name>
<files>src/components/PostCard.tsx</files>
<read_first>src/components/UserCard.tsx, src/types/post.ts</read_first>
<action>Create PostCard component accepting a Post prop (id, authorId, content, createdAt,
reactionCount). Render author avatar using UserAvatar from UserCard pattern. Show timestamp
using date-fns formatDistanceToNow. Export as named export PostCard.</action>
<verify>npx tsc --noEmit</verify>
<acceptance_criteria>
- src/components/PostCard.tsx exports named export PostCard
- PostCard.tsx contains "reactionCount" prop usage
- npx tsc --noEmit exits 0
</acceptance_criteria>
<done>PostCard renders post content with author and timestamp</done>
</task>
Required fields for auto tasks
| Field | Rule |
|---|---|
<files> |
Every file the task creates or modifies. The executor writes only these files. |
<read_first> |
Files the executor must read before touching anything — the file being modified, any source-of-truth pattern file, any file whose types or conventions must be replicated. |
<action> |
Concrete instructions with exact identifiers, file paths, function signatures, and expected values. Never says "align X with Y" without specifying the target state. Never contains fenced code blocks or full implementations. |
<verify> |
A runnable command or check that proves the task succeeded. Must distinguish pass from fail — echo "done" is not valid. |
<acceptance_criteria> |
Verifiable conditions: grep-verifiable strings, command exit codes, observable behaviours. No subjective language ("looks correct", "properly configured"). Negative greps (! grep -Eq 'PAT' file) are file-scoped — region-scope them (sed -n/awk range, then grep) when a sibling task needs the construct elsewhere in the same file (#968). |
<done> |
A short measurable statement of the completed outcome. |
Plan quality dimensions
The gsd-plan-checker agent reviews every PLAN.md across 12 dimensions before execution begins. A plan that fails any BLOCKER-severity check is returned to gsd-planner for revision (up to 3 iterations):
| Dimension | What it checks |
|---|---|
| 1 — Requirement Coverage | Every phase requirement ID from ROADMAP.md appears in at least one plan's requirements frontmatter field and has covering task(s). |
| 2 — Task Completeness | Every auto task carries all required fields (<files>, <action>, <verify>, <acceptance_criteria>, <done>). No vague or empty fields. |
| 3 — Dependency Correctness | depends_on references are valid, acyclic, and consistent with wave numbers. Wave N plan depends only on plans in waves < N. |
| 4 — Key Links Planned | Artifacts in must_haves.key_links have corresponding tasks that implement the wiring — not just the artifact creation. |
| 5 — Scope Sanity | Plans stay within context budget: 2–3 tasks per plan (4 = warning, 5+ = BLOCKER), ≤ 8–10 files per plan (15+ = BLOCKER). |
| 6 — Verification Derivation | must_haves.truths are user-observable behaviours, not implementation details. Artifacts map to truths. Key links cover critical wiring. |
| 7 — Context Compliance | Every D-NN decision from CONTEXT.md is addressed by at least one task. No task implements anything from <deferred>. |
| 7b — Scope Reduction Detection | Task actions do not silently reduce a locked decision to a "v1", "stub", or "future enhancement" without delivering the full decision scope. Always a BLOCKER when found. |
| 7c — Architectural Tier Compliance | Tasks assign capabilities to the correct tier per the RESEARCH.md Architectural Responsibility Map (when present). Security-sensitive capabilities in the wrong tier are BLOCKERs. |
| 8 — Nyquist Compliance | When workflow.nyquist_validation is enabled and RESEARCH.md exists, every task has an <automated> verify command, no consecutive window of 3 tasks lacks coverage, and VALIDATION.md is present. |
| 9 — Cross-Plan Data Contracts | When plans share data pipelines, their transformations are compatible — no plan strips data that another plan needs in original form. |
| 10 — CLAUDE.md Compliance | Plans respect project-specific conventions, forbidden patterns, required tools, and security requirements from ./CLAUDE.md. |
| 11 — Research Resolution | When RESEARCH.md exists, its ## Open Questions section is marked (RESOLVED) before planning proceeds. |
| 12 — Pattern Compliance | When PATTERNS.md exists, tasks reference the correct analog patterns for each new or modified file. |
Wave execution model
Wave numbers are pre-computed during planning. Execute-phase groups plans by wave number and runs each wave's plans in parallel:
Wave 1: Plan 01, Plan 02, Plan 03 (all run simultaneously — no dependencies)
Wave 2: Plan 04 (waits for Wave 1 to complete)
Wave 3: Plan 05 (waits for Wave 2 to complete)
Plans within a wave that modify overlapping files must not be in the same wave — the plan-checker's Dimension 3 flags this as a BLOCKER.
Plan output
After a plan executes successfully, the executor writes a SUMMARY.md at:
.planning/phases/<NN>-<slug>/<NN>-<PP>-SUMMARY.md
The SUMMARY.md is the canonical record of what was built. Subsequent plans in the same phase may reference it when they have a genuine dependency on its types or decisions.