You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Problem: discuss-phase SETS workflow.auto_advance config (lines 434-441), transition CLEARS it (lines 454-457). The --auto flag is supposed to be invocation-scoped but persists via config mutation.
Change auto-advance detection from config read to --auto flag check only
execute-phase.md lines 207-209 and 412-416
3D
Same flag-only check for auto-advance
plan-phase.md lines 366-368
Mechanism: Each workflow already passes --auto to the NEXT workflow when spawning. So the flag propagates through discuss→plan→execute→transition without config.
E6: Context Refresh Gate
File:workflows/plan-phase.md
Problem: If user wants to refine CONTEXT.md after seeing research results, they must restart the entire plan-phase.
Change
What
Where
6A
Insert "Research Review Gate" step between research return and planner spawn
plan-phase.md, new step 7.5 (between lines ~155 and ~170)
Logic:
Skip if --auto flag, --skip-research, or research was pre-existing (not fresh)
Display brief research summary (first 10 lines of ## Summary section)
Ask user: "Want to refine CONTEXT.md before planning?" (default: no)
If yes: display CONTEXT.md, let user describe changes, re-read from disk after edit
Problem:depends_on field exists in PLAN frontmatter but cmdPhasePlanIndex (line 1935) never extracts it. No orphan reference detection, no circular dependency detection, no wave ordering validation.
Change
What
Where
1A
Extract depends_on from each plan's frontmatter in cmdPhasePlanIndex
Add dependency_graph, dep_errors, dep_warnings to return object
gsd-tools.cjs line ~2032
1D
Add dependency validation to pre_flight_validation step — block on errors, warn on warnings
execute-phase.md lines 74-99
Validation logic (1B):
For each plan:
- Check all depends_on refs exist in allPlanIds → orphan errors
- Check depends_on refs are in earlier/same wave → wave ordering warnings
DFS cycle detection across full graph → circular dep errors
Tests (4):
depends_on extracted from frontmatter
orphan dependency detected (depends on nonexistent plan)
circular dependency detected (A→B→A)
wave ordering warning (wave 1 depends on wave 2)
E5: State Versioning & Conflict Detection
File:bin/gsd-tools.cjs
Problem: 9 STATE.md mutation functions (lines 1223-1501) use read→regex→write with no locking. Parallel agents can corrupt STATE.md.
Change
What
Where
5A
Add readStateWithVersion(statePath) helper — extracts **State Version:** N field
Problem: discovery-phase says "Called from plan-phase's mandatory_discovery step" but plan-phase doesn't actually call it. Two overlapping research mechanisms with no routing.
Change
What
Where
4A
Add depth auto-detection block before research step
plan-phase.md, before line 76
4B
Route to discovery-phase at detected depth, or fall through to research agent
plan-phase.md, within step 5
4C
Clarify invocation model in purpose section
discovery-phase.md lines 1-8
Depth detection logic (4A):
CONTEXT.md has "Claude's Discretion" with library/API choices → depth=standard
CONTEXT.md has architectural decisions needing validation → depth=deep
Simple phase, known stack (prior SUMMARYs cover it) → depth=verify (skip research agent)
No CONTEXT.md → existing research agent path (unchanged)
Routing (4B):
verify: Quick Context7 check, skip full research
standard/deep: Spawn discovery-phase at detected depth, skip research agent
No detection: Fall through to existing researcher agent
Problem: When user reports a bug at human-verify checkpoint, continuation executor tries to fix inline with no planning, no debug agents, no structured diagnosis. continuation-prompt.md (referenced at execute-phase.md line 232) doesn't exist. {resume_instructions} is never defined.
Change
What
Where
8A
Create continuation-prompt.md template with variables, prompt structure, and resume instructions per classification (approved/issue_report-minor/issue_report-major/decision)
NEW: templates/continuation-prompt.md
8B
Add response classification logic to checkpoint_handling step
execute-phase.md lines 231-237
8C
Add cmdClassifyCheckpointResponse(response, raw) — classifies as approved/issue_report/decision with severity
Problem: 4 verification points (plan-checker, pre-flight, verifier agent, spot-checks) with no chain of trust. Plans can diverge from requirements. Verification outcomes don't flow downstream.
Change
What
Where
7A
Add phase_req_ids extraction from ROADMAP.md to cmdInitExecutePhase return
gsd-tools.cjs line ~4292
7B
Add plan_seal_status to cmdInitExecutePhase return
gsd-tools.cjs line ~4310
7C
Record verification outcome to STATE.md after checker passes
plan-phase.md, after step 13
7D
Pass plan verification outcome + seal status + requirement IDs to verifier prompt
execute-phase.md verify_phase_goal step
Verification chain: plan-checker outcome → STATE.md → plan-seal → execute-phase init → verifier agent. Each link carries evidence from the previous.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
After installing GSD in the Claude CLI, did a update and enhance on GSD.
This is what was recommended by Claude.
up to you to implement or not.
GSD 5 Upgrades - Implementation State
Status: COMPLETE
Date completed: 2026-02-24
Transcript: C:\Users\Danie.claude\projects\C--Users-Danie--claude\3aacea47-443e-4bec-b4af-cd76bb65aa74.jsonl
Summary
5 upgrades to harden GSD: input validation, error recovery, context budget guards, integration tests, deduplication.
Execution Order (by dependency)
Files to Modify
bin/gsd-tools.cjs— main tool (upgrades 5, 1, 4)bin/gsd-tools.test.cjs— tests (upgrade 2)workflows/plan-phase.md— error recovery (upgrade 1)workflows/execute-phase.md— error recovery + context budget (upgrades 1, 4)references/git-planning-commit.md— dedup (upgrade 3)workflows/discovery-phase.md— dedup (upgrade 3)references/shared-patterns.md— dedup (upgrade 3)Step-by-Step Implementation Sequence (20 steps)
Upgrade 5: Input Validation & Security Hardening
gsd-tools.cjs: addexecFileSyncto imports (line ~124)gsd-tools.cjs: replaceisGitIgnored()withexecFileSyncversiongsd-tools.cjs: replaceexecGit()withexecFileSyncversiongsd-tools.cjs: addvalidatePhaseInput()afternormalizePhaseName()gsd-tools.cjs: add bounds checking inloadConfig()gsd-tools.cjs: add validation incmdFindPhase()gsd-tools.cjs: add validation incmdInitPlanPhase()+cmdInitExecutePhase()Upgrade 1: Error Recovery & Graceful Degradation
{error: true, message: "..."}instead ofprocess.exit(1)on validation failureverification_readyfield toinit plan-phaseoutput## EXECUTION BLOCKEDin execute-phase.mdUpgrade 4: Context Budget Guards
gsd-tools.cjs: addcmdContextEstimate()gsd-tools.cjs: add--limittocmdHistoryDigest()gsd-tools.cjs: update CLI router for new commandsUpgrade 2: Integration Tests
gsd-tools.test.cjs: add all 7 new test suites (~24 new tests)Upgrade 1 continued (workflow files)
workflows/plan-phase.md: structured verification loop outcomeworkflows/execute-phase.md: pre-flight validation + structured errors + context estimationUpgrade 3: Deduplication
references/git-planning-commit.md: consolidate to referenceworkflows/discovery-phase.md: convert to@referencesreferences/shared-patterns.mdfind-phase "../hack"andcontext-estimateVerification Commands
Key Implementation Details
validatePhaseInput(phase) returns {valid, error, normalized}
Rejects: empty, path traversal (..), shell metacharacters, null bytes, length >50, invalid format
cmdContextEstimate(cwd, filePaths, raw)
Returns: {total_chars, estimated_tokens, fits_budget, budget_pct, files: [...]}
Uses 4 chars/token ratio, 200k budget, 90% safe threshold
execGit replacement
Replace shell string concatenation with execFileSync('git', args) — eliminates shell injection
isGitIgnored replacement
Replace shell concatenation with execFileSync('git', ['check-ignore', '-q', '--', targetPath])
New test suites (7 suites, ~24 tests)
SECOND UPDATE
GSD Workflow Enhancements: 8 Upgrades Plan
Context
After implementing 5 hardening upgrades (input validation, error recovery, context budget, tests, dedup), analysis revealed 7 structural workflow gaps plus 1 critical checkpoint handling issue. These 8 enhancements address: missing dependency validation, no plan integrity verification, surprising auto-advance config mutation, overlapping discovery/research, unprotected state mutations, no context refresh opportunity, fragmented verification chain, and broken checkpoint continuation routing.
Dependency Graph
Execution Order
Test target: 107 existing + 15 new = 122 tests
E3: Unify --auto Handling
Files:
workflows/discuss-phase.md,workflows/transition.md,workflows/execute-phase.md,workflows/plan-phase.mdProblem: discuss-phase SETS
workflow.auto_advanceconfig (lines 434-441), transition CLEARS it (lines 454-457). The--autoflag is supposed to be invocation-scoped but persists via config mutation.config-set workflow.auto_advance truecallconfig-set workflow.auto_advance falsecall--autoflag check onlyMechanism: Each workflow already passes
--autoto the NEXT workflow when spawning. So the flag propagates through discuss→plan→execute→transition without config.E6: Context Refresh Gate
File:
workflows/plan-phase.mdProblem: If user wants to refine CONTEXT.md after seeing research results, they must restart the entire plan-phase.
Logic:
--autoflag,--skip-research, or research was pre-existing (not fresh)## Summarysection)E1: Dependency Pre-flight Check
Files:
bin/gsd-tools.cjs,workflows/execute-phase.mdProblem:
depends_onfield exists in PLAN frontmatter butcmdPhasePlanIndex(line 1935) never extracts it. No orphan reference detection, no circular dependency detection, no wave ordering validation.depends_onfrom each plan's frontmatter incmdPhasePlanIndexdependency_graphmap + validate: orphan refs, circular deps, wave orderingdependency_graph,dep_errors,dep_warningsto return objectpre_flight_validationstep — block on errors, warn on warningsValidation logic (1B):
Tests (4):
depends_on extracted from frontmatterorphan dependency detected(depends on nonexistent plan)circular dependency detected(A→B→A)wave ordering warning(wave 1 depends on wave 2)E5: State Versioning & Conflict Detection
File:
bin/gsd-tools.cjsProblem: 9 STATE.md mutation functions (lines 1223-1501) use read→regex→write with no locking. Parallel agents can corrupt STATE.md.
readStateWithVersion(statePath)helper — extracts**State Version:** NfieldwriteStateAtomic(statePath, content, expectedVersion)— temp file + rename, version increment, optimistic lockstate_versiontocmdStateSnapshotoutputAtomic write pattern:
Optimistic lock: Re-read version before write. If version changed since read, return
{error: 'version_conflict'}instead of corrupting.Tests (4):
state update increments versionstate version starts at 0 if field missingatomic write produces valid filestate-snapshot includes state_versionE2: Plan Hash Seal
Files:
bin/gsd-tools.cjs,workflows/plan-phase.md,workflows/execute-phase.mdProblem: Plans can change after plan-phase verification. Execute-phase has no way to detect drift.
cmdPlanSeal(cwd, phase, raw)— SHA-256 hash of all PLAN.md files, writes{phase_dir}/.plan-sealcmdPlanSealVerify(cwd, phase, raw)— reads seal, recomputes, comparesplan-sealandplan-seal-verifycases to CLI routerplan-sealplan-seal-verify. Warn on mismatch, proceed on no-sealSeal file format (
.plan-seal):{ "seal": "sha256_hex", "hashes": {"01-01-PLAN.md": "sha256_hex", ...}, "plan_count": 3, "created_at": "ISO8601" }Tests (3):
plan-seal creates seal file with correct hashplan-seal-verify passes for unmodified plansplan-seal-verify detects modificationE4: Consolidate Discovery into Plan-Phase
Files:
workflows/plan-phase.md,workflows/discovery-phase.mdProblem: discovery-phase says "Called from plan-phase's mandatory_discovery step" but plan-phase doesn't actually call it. Two overlapping research mechanisms with no routing.
Depth detection logic (4A):
depth=standarddepth=deepdepth=verify(skip research agent)Routing (4B):
verify: Quick Context7 check, skip full researchstandard/deep: Spawn discovery-phase at detected depth, skip research agentE8: Checkpoint Continuation Routing
Files:
templates/continuation-prompt.md(NEW),workflows/execute-phase.md,references/checkpoints.md,bin/gsd-tools.cjsProblem: When user reports a bug at human-verify checkpoint, continuation executor tries to fix inline with no planning, no debug agents, no structured diagnosis.
continuation-prompt.md(referenced at execute-phase.md line 232) doesn't exist.{resume_instructions}is never defined.continuation-prompt.mdtemplate with variables, prompt structure, and resume instructions per classification (approved/issue_report-minor/issue_report-major/decision)cmdClassifyCheckpointResponse(response, raw)— classifies as approved/issue_report/decision with severityResponse classification (8B/8C):
approvedissue_reportissue_report(major)decisionRouting by classification:
approved→ spawn continuation with proceed instructionsissue_report(minor) → spawn continuation with targeted fix instructions + Deviation Rule 1issue_report(major) → do NOT spawn continuation; present to user with suggestion:/gsd:debugor re-plandecision→ spawn continuation with chosen option appliedTests (2):
classifies "approved" correctlyclassifies issue description as issue_reportE7: Unified Verification Chain
Files:
bin/gsd-tools.cjs,workflows/plan-phase.md,workflows/execute-phase.mdProblem: 4 verification points (plan-checker, pre-flight, verifier agent, spot-checks) with no chain of trust. Plans can diverge from requirements. Verification outcomes don't flow downstream.
phase_req_idsextraction from ROADMAP.md tocmdInitExecutePhasereturnplan_seal_statustocmdInitExecutePhasereturnVerification chain: plan-checker outcome → STATE.md → plan-seal → execute-phase init → verifier agent. Each link carries evidence from the previous.
Tests (2):
init execute-phase returns phase_req_idsinit execute-phase returns plan_seal_statusStep-by-Step Implementation Sequence
Wave 1 (Workflow-only, zero code risk)
Wave 2 (Foundation code)
Wave 3 (Seal + Discovery)
Wave 4 (Checkpoint)
Wave 5 (Verification chain)
Final
node --test bin/gsd-tools.test.cjs— 122 pass, 0 fail--autopropagation without config mutationCritical Files
bin/gsd-tools.cjsbin/gsd-tools.test.cjsworkflows/execute-phase.mdworkflows/plan-phase.mdworkflows/discuss-phase.mdworkflows/transition.mdworkflows/discovery-phase.mdreferences/checkpoints.mdtemplates/continuation-prompt.mdBeta Was this translation helpful? Give feedback.
All reactions