gsdd-cli 0.27.0 → 0.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/README.md +53 -22
  2. package/agents/DISTILLATION.md +2 -2
  3. package/agents/README.md +4 -4
  4. package/agents/approach-explorer.md +4 -4
  5. package/agents/executor.md +20 -20
  6. package/agents/integration-checker.md +2 -2
  7. package/agents/planner.md +10 -26
  8. package/agents/researcher.md +2 -2
  9. package/agents/roadmapper.md +6 -6
  10. package/agents/synthesizer.md +18 -18
  11. package/agents/verifier.md +3 -3
  12. package/bin/adapters/agents.mjs +3 -3
  13. package/bin/adapters/claude.mjs +16 -14
  14. package/bin/adapters/opencode.mjs +15 -12
  15. package/bin/gsdd.mjs +16 -13
  16. package/bin/lib/{models.mjs → config.mjs} +23 -16
  17. package/bin/lib/control-map.mjs +17 -488
  18. package/bin/lib/health-truth.mjs +8 -13
  19. package/bin/lib/health.mjs +25 -39
  20. package/bin/lib/init-flow.mjs +44 -38
  21. package/bin/lib/init-prompts.mjs +3 -3
  22. package/bin/lib/init-runtime.mjs +11 -30
  23. package/bin/lib/lifecycle-preflight.mjs +97 -410
  24. package/bin/lib/lifecycle-state.mjs +2 -1
  25. package/bin/lib/next.mjs +243 -20
  26. package/bin/lib/phase.mjs +706 -280
  27. package/bin/lib/plan-constants.mjs +0 -5
  28. package/bin/lib/rendering.mjs +64 -44
  29. package/bin/lib/runtime-freshness.mjs +18 -15
  30. package/bin/lib/state-dir.mjs +45 -0
  31. package/bin/lib/templates.mjs +59 -22
  32. package/bin/lib/work-context.mjs +12 -1
  33. package/bin/lib/workflows.mjs +0 -1
  34. package/bin/lib/workspace-root.mjs +11 -6
  35. package/distilled/DESIGN.md +89 -31
  36. package/distilled/EVIDENCE-INDEX.md +18 -5
  37. package/distilled/README.md +23 -33
  38. package/distilled/SKILL.md +9 -10
  39. package/distilled/templates/agents.block.md +5 -5
  40. package/distilled/templates/approach.md +3 -3
  41. package/distilled/templates/auth-matrix.md +2 -2
  42. package/distilled/templates/brownfield-change/CHANGE.md +1 -1
  43. package/distilled/templates/delegates/approach-explorer.md +5 -5
  44. package/distilled/templates/delegates/mapper-arch.md +3 -3
  45. package/distilled/templates/delegates/mapper-concerns.md +4 -4
  46. package/distilled/templates/delegates/mapper-quality.md +3 -3
  47. package/distilled/templates/delegates/mapper-tech.md +3 -3
  48. package/distilled/templates/delegates/plan-checker.md +18 -19
  49. package/distilled/templates/delegates/researcher-architecture.md +3 -3
  50. package/distilled/templates/delegates/researcher-features.md +3 -3
  51. package/distilled/templates/delegates/researcher-pitfalls.md +3 -3
  52. package/distilled/templates/delegates/researcher-stack.md +3 -3
  53. package/distilled/templates/delegates/researcher-synthesizer.md +7 -7
  54. package/distilled/templates/research/architecture.md +1 -1
  55. package/distilled/templates/research/pitfalls.md +1 -1
  56. package/distilled/templates/research/stack.md +1 -1
  57. package/distilled/templates/roadmap.md +4 -4
  58. package/distilled/templates/spec.md +2 -2
  59. package/distilled/templates/ui-proof.md +81 -181
  60. package/distilled/workflows/audit-milestone.md +23 -23
  61. package/distilled/workflows/complete-milestone.md +35 -35
  62. package/distilled/workflows/execute.md +34 -35
  63. package/distilled/workflows/map-codebase.md +30 -30
  64. package/distilled/workflows/new-milestone.md +18 -18
  65. package/distilled/workflows/new-project.md +45 -45
  66. package/distilled/workflows/pause.md +15 -15
  67. package/distilled/workflows/plan.md +106 -114
  68. package/distilled/workflows/progress.md +40 -39
  69. package/distilled/workflows/quick.md +49 -50
  70. package/distilled/workflows/resume.md +23 -22
  71. package/distilled/workflows/verify-work.md +7 -7
  72. package/distilled/workflows/verify.md +26 -26
  73. package/docs/BROWNFIELD-PROOF.md +1 -1
  74. package/docs/RUNTIME-SUPPORT.md +13 -13
  75. package/docs/USER-GUIDE.md +26 -21
  76. package/docs/claude/context-monitor.md +1 -1
  77. package/docs/proof/consumer-node-cli/README.md +1 -1
  78. package/package.json +3 -3
  79. package/bin/lib/closeout-report.mjs +0 -318
  80. package/bin/lib/evidence-contract.mjs +0 -325
  81. package/bin/lib/provenance.mjs +0 -390
  82. package/bin/lib/session-fingerprint.mjs +0 -223
  83. package/bin/lib/ui-proof.mjs +0 -1007
  84. package/distilled/workflows/plan-milestone-gaps.md +0 -204
@@ -7,25 +7,25 @@ Scope boundary: you are NOT resume.md. You do not wait for user input, clean up
7
7
  </role>
8
8
 
9
9
  <control_map>
10
- At the start of status reporting, run `node .planning/bin/gsdd.mjs control-map --json` when the local helper exists. Summarize its computed repo/worktree/planning state in the status block: canonical branch/HEAD, tracked/untracked dirty buckets, whether ignored paths were scanned, sibling or detached worktrees, stale local annotations, planning drift, and recommended interventions. Use `--with-ignored` before making a clean-workspace claim that includes ignored or generated surfaces. Treat the command output as read-only computed evidence. Local annotations under `.planning/.local/` explain intent but never outrank repo truth, planning artifacts, or checkpoint reconciliation.
10
+ At the start of status reporting, run `node .work/bin/gsdd.mjs control-map --json` when the local helper exists. Summarize its computed repo/worktree/planning state in the status block: canonical branch/HEAD, tracked/untracked dirty buckets, whether ignored paths were scanned, sibling or detached worktrees, stale local annotations, planning drift, and recommended interventions. Use `--with-ignored` before making a clean-workspace claim that includes ignored or generated surfaces. Treat the command output as read-only computed evidence. Local annotations under `.work/.local/` explain intent but never outrank repo truth, planning artifacts, or checkpoint reconciliation.
11
11
  </control_map>
12
12
 
13
13
  <prerequisites>
14
- `.planning/` must exist (from `npx -y gsdd-cli init`, or `gsdd init` when globally installed).
14
+ `.work/` must exist (from `npx -y gsdd-cli init`, or `gsdd init` when globally installed).
15
15
 
16
- This is a read-only workflow. No files are created, modified, or deleted. If `.planning/` does not exist, tell the user to run `npx -y gsdd-cli init` and stop.
16
+ This is a read-only workflow. No files are created, modified, or deleted. If `.work/` does not exist, tell the user to run `npx -y gsdd-cli init` and stop.
17
17
  </prerequisites>
18
18
 
19
19
  <repo_root_helper_contract>
20
- All `node .planning/bin/gsdd.mjs ...` helper references below assume the current working directory is the repo root. If the runtime launched from a subdirectory, change to the repo root before acting on them.
20
+ All `node .work/bin/gsdd.mjs ...` helper references below assume the current working directory is the repo root. If the runtime launched from a subdirectory, change to the repo root before acting on them.
21
21
  </repo_root_helper_contract>
22
22
 
23
23
  <lifecycle_boundary>
24
24
  `progress` stays read-only.
25
25
 
26
26
  - Derive lifecycle posture from repo truth only; do not mutate phase or milestone state from this workflow.
27
- - Do not call `node .planning/bin/gsdd.mjs phase-status` here.
28
- - If you recommend a next step that crosses a lifecycle boundary, the downstream mutating workflow must rerun its own `node .planning/bin/gsdd.mjs lifecycle-preflight ...` gate before acting.
27
+ - Do not call `node .work/bin/gsdd.mjs phase-status` here.
28
+ - If you recommend a next step that crosses a lifecycle boundary, the downstream mutating workflow must rerun its own `node .work/bin/gsdd.mjs lifecycle-preflight ...` gate before acting.
29
29
  </lifecycle_boundary>
30
30
 
31
31
  <process>
@@ -33,12 +33,13 @@ All `node .planning/bin/gsdd.mjs ...` helper references below assume the current
33
33
  <check_existence>
34
34
  Check for project artifacts in order:
35
35
 
36
- 1. **No `.planning/` directory** — tell the user to run `npx -y gsdd-cli init`. Stop.
37
- 2. **If `.planning/brownfield-change/CHANGE.md` exists** — treat this as the active medium-scope brownfield continuity state. Go to Branch F.
38
- 3. **No `.planning/ROADMAP.md` AND no `.planning/SPEC.md`** check for non-phase brownfield artifacts:
39
- - if `.planning/codebase/` has substantive map documents, or `.planning/quick/` has LOG/task artifacts, treat this as a non-phase brownfield state. Go to Branch F.
36
+ 1. **No `.work/` directory** — tell the user to run `npx -y gsdd-cli init`. Stop.
37
+ 2. **If `.work/brownfield-change/CHANGE.md` exists and `Current posture` is not `closed`** — treat this as the active medium-scope brownfield continuity state. Go to Branch F.
38
+ - If `Current posture` is `closed`, keep the file as historical context only and continue checking ROADMAP/SPEC state.
39
+ 3. **No `.work/ROADMAP.md` AND no `.work/SPEC.md`** check for non-phase brownfield artifacts:
40
+ - if `.work/codebase/` has substantive map documents, or `.work/quick/` has LOG/task artifacts, treat this as a non-phase brownfield state. Go to Branch F.
40
41
  - otherwise the project has no artifacts. Suggest running the `/gsdd-new-project` workflow. Stop.
41
- 4. **No `.planning/ROADMAP.md` BUT `.planning/SPEC.md` exists** — this is a between-milestones state (milestone was completed and archived). Go to Branch F.
42
+ 4. **No `.work/ROADMAP.md` BUT `.work/SPEC.md` exists** — this is a between-milestones state (milestone was completed and archived). Go to Branch F.
42
43
  5. **Both exist** — proceed to derive status, including whether a retained `ROADMAP.md` already represents an archived milestone rather than an audit-ready one.
43
44
  </check_existence>
44
45
 
@@ -46,27 +47,27 @@ Check for project artifacts in order:
46
47
  Read the following and extract state:
47
48
 
48
49
  **Project identity:**
49
- - If `.planning/SPEC.md` exists, read it and extract the project name from the first heading.
50
- - If `.planning/SPEC.md` does not exist, derive the project name from the repo root directory name.
50
+ - If `.work/SPEC.md` exists, read it and extract the project name from the first heading.
51
+ - If `.work/SPEC.md` does not exist, derive the project name from the repo root directory name.
51
52
 
52
53
  **Non-phase brownfield state:**
53
- If `.planning/ROADMAP.md` does not exist, determine whether the repo is currently in one of these Branch F states:
54
- - `active_brownfield_change` — `.planning/brownfield-change/CHANGE.md` exists; read `CHANGE.md` first as the canonical operational anchor, then read `HANDOFF.md` for judgment-only context
55
- - `between_milestones` — `.planning/SPEC.md` exists
56
- - `codebase_only` — `.planning/codebase/` has substantive map documents but `.planning/SPEC.md` does not exist
57
- - `quick_lane` — `.planning/quick/LOG.md` or quick task directories exist but `.planning/SPEC.md` and `.planning/ROADMAP.md` do not
54
+ If `.work/ROADMAP.md` does not exist, determine whether the repo is currently in one of these Branch F states:
55
+ - `active_brownfield_change` — `.work/brownfield-change/CHANGE.md` exists and `Current posture` is not `closed`; read `CHANGE.md` first as the canonical operational anchor, then read `HANDOFF.md` for judgment-only context
56
+ - `between_milestones` — `.work/SPEC.md` exists
57
+ - `codebase_only` — `.work/codebase/` has substantive map documents but `.work/SPEC.md` does not exist
58
+ - `quick_lane` — `.work/quick/LOG.md` or quick task directories exist but `.work/SPEC.md` and `.work/ROADMAP.md` do not
58
59
 
59
60
  For `active_brownfield_change`, `codebase_only`, and `quick_lane`, there is no active phase count. Record the non-phase state instead of trying to infer current milestone progress.
60
61
 
61
62
  **Active brownfield change:**
62
- If `.planning/brownfield-change/CHANGE.md` exists, extract:
63
+ If `.work/brownfield-change/CHANGE.md` exists and is not closed, extract:
63
64
  - change title from the first heading
64
65
  - current posture from `## Current Status`
65
66
  - current branch / integration surface from `## Current Status`
66
67
  - next action from `## Next Action`
67
68
  - declared write scope from `## PR Slice Ownership` when present
68
69
 
69
- If `.planning/brownfield-change/HANDOFF.md` exists, read it as judgment-only context:
70
+ If `.work/brownfield-change/HANDOFF.md` exists, read it as judgment-only context:
70
71
  - active constraints
71
72
  - unresolved uncertainty
72
73
  - decision posture
@@ -75,7 +76,7 @@ If `.planning/brownfield-change/HANDOFF.md` exists, read it as judgment-only con
75
76
  Do not treat `HANDOFF.md` as a co-equal status source. It explains the active change; `CHANGE.md` remains the operational anchor.
76
77
 
77
78
  **Phase statuses:**
78
- If `.planning/ROADMAP.md` exists, read it and parse phase statuses:
79
+ If `.work/ROADMAP.md` exists, read it and parse phase statuses:
79
80
  - `[ ]` = not started
80
81
  - `[-]` = in progress
81
82
  - `[x]` = done
@@ -89,29 +90,29 @@ Determine:
89
90
  **Archived milestone evidence:**
90
91
  If `ROADMAP.md` exists and all phases in the current milestone are `[x]`, determine whether this is still audit-ready or already archived-with-`ROADMAP.md`:
91
92
  - derive the current milestone/version from the active milestone heading in `ROADMAP.md`
92
- - check `.planning/MILESTONES.md` for a shipped entry matching that same milestone/version
93
- - check for the matching archived milestone audit artifact for that same milestone/version (for example `.planning/v1.1-MILESTONE-AUDIT.md`)
93
+ - check `.work/MILESTONES.md` for a shipped entry matching that same milestone/version
94
+ - check for the matching archived milestone audit artifact for that same milestone/version (for example `.work/v1.1-MILESTONE-AUDIT.md`)
94
95
  - if both the shipped ledger entry and the matching archived audit artifact exist, treat the retained `ROADMAP.md` as archived milestone evidence and route to Branch F instead of Branch E
95
96
  - if either one is missing, keep the milestone in the audit-ready Branch E state
96
97
 
97
98
  **Checkpoint:**
98
- Check if `.planning/.continue-here.md` exists. If yes, note the `workflow` and `phase` frontmatter and the `next_action` section.
99
+ Check if `.work/.continue-here.md` exists. If yes, note the `workflow` and `phase` frontmatter and the `next_action` section.
99
100
  - Treat checkpoint routing classes explicitly:
100
101
  - `phase` and `quick` checkpoints remain blocking resume-owned surfaces for routing only when there is no active brownfield change, or when a shared strict-match rule proves they still describe the active execution surface.
101
102
  - `generic` checkpoints are informational-only for this read-only reporter: show the checkpoint and its `next_action`, but keep evaluating the real lifecycle recommendation instead of routing Branch A back through `/gsdd-resume`.
102
- - If `.planning/brownfield-change/CHANGE.md` also exists, apply one shared strict-match rule before letting a surviving `phase` or `quick` checkpoint outrank the operational anchor:
103
+ - If `.work/brownfield-change/CHANGE.md` also exists, apply one shared strict-match rule before letting a surviving `phase` or `quick` checkpoint outrank the operational anchor:
103
104
  - branch alignment: the checkpoint branch, `CHANGE.md` integration surface, and current git branch all match
104
105
  - scope alignment: the live dirty tree stays inside the declared brownfield write scope
105
106
  - still-active execution state: the checkpoint still points at live unfinished `phase` or `quick` work
106
107
  - If any one of those checks fails, keep the checkpoint visible in the status block but continue routing from the active brownfield change instead of bouncing Branch A back through `/gsdd-resume`.
107
108
 
108
109
  **Incomplete work:**
109
- If `.planning/phases/` exists, scan it for:
110
+ If `.work/phases/` exists, scan it for:
110
111
  - PLAN files without a matching SUMMARY file (incomplete execution)
111
- - SUMMARY files without a matching VERIFICATION file (unverified, only relevant if `workflow.verifier` is enabled in `.planning/config.json`; if config.json cannot be read, assume verifier is disabled)
112
+ - SUMMARY files without a matching VERIFICATION file (unverified, only relevant if `workflow.verifier` is enabled in `.work/config.json`; if config.json cannot be read, assume verifier is disabled)
112
113
 
113
114
  **Quick task log:**
114
- If `.planning/quick/LOG.md` exists, check the last entry for a non-terminal status.
115
+ If `.work/quick/LOG.md` exists, check the last entry for a non-terminal status.
115
116
 
116
117
  **Artifact-versus-worktree mismatch:**
117
118
  If an active brownfield change exists, compare `CHANGE.md` to live git/worktree truth:
@@ -129,7 +130,7 @@ Run `git log main..HEAD --oneline` to detect commits on the current branch that
129
130
  </derive_status>
130
131
 
131
132
  <recent_work>
132
- Scan `.planning/phases/` for the 2-3 most recent SUMMARY.md files (by directory name or file modification time).
133
+ Scan `.work/phases/` for the 2-3 most recent SUMMARY.md files (by directory name or file modification time).
133
134
 
134
135
  For each, extract:
135
136
  - Phase name from the directory name (e.g., `01-setup` → "Phase 1: Setup")
@@ -256,7 +257,7 @@ Suggested next action:
256
257
  ```
257
258
 
258
259
  **Branch E: Audit milestone (all phases [x], not yet archived)**
259
- Condition: All phases in the current milestone are marked `[x]`, and the current roadmap milestone/version does **not** yet have both a shipped entry in `.planning/MILESTONES.md` and the matching archived milestone audit artifact.
260
+ Condition: All phases in the current milestone are marked `[x]`, and the current roadmap milestone/version does **not** yet have both a shipped entry in `.work/MILESTONES.md` and the matching archived milestone audit artifact.
260
261
 
261
262
  ```
262
263
  Suggested next action:
@@ -266,26 +267,26 @@ Suggested next action:
266
267
 
267
268
  **Branch F: Non-phase state (no active roadmap, or retained roadmap already archived)**
268
269
  Condition:
269
- - `.planning/brownfield-change/CHANGE.md` exists, **or**
270
- - `.planning/SPEC.md` exists but `.planning/ROADMAP.md` does not, **or**
271
- - `.planning/codebase/` or `.planning/quick/` exists while both `.planning/SPEC.md` and `.planning/ROADMAP.md` are absent, **or**
272
- - `.planning/ROADMAP.md` still exists, but the current roadmap milestone/version already has both a shipped entry in `.planning/MILESTONES.md` and the matching archived milestone audit artifact — this is the archived-with-`ROADMAP.md` state, not a second trip through audit
270
+ - `.work/brownfield-change/CHANGE.md` exists, **or**
271
+ - `.work/SPEC.md` exists but `.work/ROADMAP.md` does not, **or**
272
+ - `.work/codebase/` or `.work/quick/` exists while both `.work/SPEC.md` and `.work/ROADMAP.md` are absent, **or**
273
+ - `.work/ROADMAP.md` still exists, but the current roadmap milestone/version already has both a shipped entry in `.work/MILESTONES.md` and the matching archived milestone audit artifact — this is the archived-with-`ROADMAP.md` state, not a second trip through audit
273
274
 
274
- Check `.planning/MILESTONES.md`:
275
+ Check `.work/MILESTONES.md`:
275
276
  - If MILESTONES.md exists and has at least one milestone entry → this is a subsequent milestone
276
277
  - If MILESTONES.md does not exist or is empty → this is the first milestone setup
277
278
 
278
279
  ```
279
280
  Suggested next action (active brownfield change):
280
- Run /gsdd-resume to restore the active brownfield change context from `.planning/brownfield-change/CHANGE.md`
281
- Also available: inspect `.planning/brownfield-change/HANDOFF.md`, /gsdd-progress (refresh after the artifact or worktree changes), /gsdd-new-project (only if you intentionally want to widen this bounded change into the first milestone), /gsdd-new-milestone (only if the repo already has shipped milestone history and you intentionally want to widen this change into the next milestone cycle)
281
+ Run /gsdd-resume to restore the active brownfield change context from `.work/brownfield-change/CHANGE.md`
282
+ Also available: inspect `.work/brownfield-change/HANDOFF.md`, /gsdd-progress (refresh after the artifact or worktree changes), /gsdd-new-project (only if you intentionally want to widen this bounded change into the first milestone), /gsdd-new-milestone (only if the repo already has shipped milestone history and you intentionally want to widen this change into the next milestone cycle)
282
283
 
283
284
  Suggested next action (subsequent milestone):
284
285
  Run /gsdd-new-milestone to start the next milestone cycle (gather goals, define requirements, create ROADMAP.md)
285
286
  Also available: /gsdd-progress (refresh after milestone setup)
286
287
 
287
288
  Suggested next action (incomplete milestone state — SPEC.md exists but no milestone archived yet):
288
- Inspect .planning/ manually — a milestone is likely still in progress.
289
+ Inspect .work/ manually — a milestone is likely still in progress.
289
290
  If a ROADMAP.md was deleted prematurely, re-run /gsdd-new-milestone to restore it.
290
291
  Do NOT run /gsdd-new-project — SPEC.md already exists and re-running would overwrite it.
291
292
 
@@ -314,7 +315,7 @@ Handle compound states:
314
315
  - **Active brownfield change + non-matching `phase`/`quick` checkpoint:** Show the checkpoint as surviving context, but let the active brownfield change stay primary unless branch alignment, scope alignment, and still-active execution state all match.
315
316
  - **All phases complete + checkpoint:** All phases `[x]` but a checkpoint exists. If the checkpoint is `phase` or `quick`, mention both and suggest `/gsdd-resume` before continuing. If the checkpoint is `generic`, keep it visible as informational context and still route the primary recommendation to milestone audit.
316
317
  - **Phase done but next unplanned:** Current phase has both PLAN and SUMMARY, but the next phase has no PLAN. Show the current phase as complete and suggest planning the next phase (Branch C targeting the next phase).
317
- - **No matching condition:** If the project state does not match any branch, report it clearly and suggest the user inspect `.planning/` manually.
318
+ - **No matching condition:** If the project state does not match any branch, report it clearly and suggest the user inspect `.work/` manually.
318
319
  </edge_cases>
319
320
 
320
321
  </process>
@@ -16,13 +16,13 @@ They reuse the same planner, executor, and verifier roles but skip research and
16
16
  </anti_patterns>
17
17
 
18
18
  <prerequisites>
19
- `.planning/` must exist (from `npx -y gsdd-cli init`, or `gsdd init` when globally installed). ROADMAP.md is NOT required -- quick tasks work during any project phase.
19
+ `.work/` must exist (from `npx -y gsdd-cli init`, or `gsdd init` when globally installed). ROADMAP.md is NOT required -- quick tasks work during any project phase.
20
20
 
21
- If `.planning/` does not exist, stop and tell the user to run `npx -y gsdd-cli init` first.
21
+ If `.work/` does not exist, stop and tell the user to run `npx -y gsdd-cli init` first.
22
22
  </prerequisites>
23
23
 
24
24
  <repo_root_helper_contract>
25
- All `node .planning/bin/gsdd.mjs ...` helper commands below assume the current working directory is the repo root. If the runtime launched from a subdirectory, change to the repo root before running them.
25
+ All `node .work/bin/gsdd.mjs ...` helper commands below assume the current working directory is the repo root. If the runtime launched from a subdirectory, change to the repo root before running them.
26
26
  </repo_root_helper_contract>
27
27
 
28
28
  <process>
@@ -37,17 +37,17 @@ Store the response as `$DESCRIPTION`. If empty, re-prompt.
37
37
 
38
38
  ## Step 2: Initialize
39
39
 
40
- 1. Read `.planning/config.json` for workflow toggles and git protocol.
41
- 2. Scan `.planning/quick/` for existing task directories. Calculate `$NEXT_NUM` as the next 3-digit number (001, 002, ...).
40
+ 1. Read `.work/config.json` for workflow toggles and git protocol.
41
+ 2. Scan `.work/quick/` for existing task directories. Calculate `$NEXT_NUM` as the next 3-digit number (001, 002, ...).
42
42
  3. Generate `$SLUG` from `$DESCRIPTION` (lowercase, hyphens, max 40 chars).
43
- 4. Create `.planning/quick/$NEXT_NUM-$SLUG/`.
44
- 5. If `.planning/brownfield-change/CHANGE.md` exists, read it first as the current bounded brownfield continuity anchor. Capture the active goal, current posture, next action, and declared write scope as `$BROWNFIELD_CONTEXT`. If `.planning/brownfield-change/HANDOFF.md` exists, read it as supporting judgment context only. Do not let `/gsdd-new-project` become the default fallback when this active change already defines a concrete bounded lane.
45
- 6. If `.planning/codebase/` exists, read whichever of `.planning/codebase/ARCHITECTURE.md`, `.planning/codebase/STACK.md`, `.planning/codebase/CONVENTIONS.md`, and `.planning/codebase/CONCERNS.md` are present. Summarize key findings from available docs in <=500 words as `$CODEBASE_CONTEXT`, emphasizing: safest surfaces to touch, risky zones to avoid, must-know conventions/traps, and what must be re-verified after change. Note any missing docs in the summary.
46
- 7. If `.planning/codebase/` does not exist, build a just-enough inline brownfield baseline instead of stopping. Read the repo root guidance that is cheap and stable (`README.md`, root manifest such as `package.json` / `pyproject.toml` / `Cargo.toml` when present, top-level app entrypoints, and any obviously relevant config or module files surfaced by `$DESCRIPTION`). Summarize the findings in <=500 words as `$CODEBASE_CONTEXT`, explicitly labeling it as a provisional baseline and calling out unknowns. Emphasize: likely implementation surface, likely dependency boundaries, conventions already visible, risky areas to avoid touching blindly, and what must be re-verified after the change. If the repo is still too unclear after this pass, keep that uncertainty explicit so Step 3.6 can recommend `/gsdd-map-codebase`.
47
- 8. **Session-boundary fallback:** If `.planning/.continue-here.bak` exists, read its `<judgment>` section. Use `<active_constraints>` and `<anti_regression>` rules as task-scoping context (do not violate active constraints; do not regress on listed invariants). After reading, run `node .planning/bin/gsdd.mjs file-op delete .planning/.continue-here.bak --missing ok` (auto-clean).
48
- 9. Inspect the live branch/worktree surface separately from checkpoint or planning artifacts. Run `node .planning/bin/gsdd.mjs control-map --json` when available and use its computed repo/worktree/planning truth to identify stale/spent branches, dirty tracked/untracked/ignored buckets, sibling or detached worktrees, local annotations, and cleanup obligations. This is advisory for quick tasks unless the mismatch makes the task description materially misleading; local annotations are intent hints, not product truth.
43
+ 4. Create `.work/quick/$NEXT_NUM-$SLUG/`.
44
+ 5. If `.work/brownfield-change/CHANGE.md` exists, read it first as the current bounded brownfield continuity anchor. Capture the active goal, current posture, next action, and declared write scope as `$BROWNFIELD_CONTEXT`. If `.work/brownfield-change/HANDOFF.md` exists, read it as supporting judgment context only. Do not let `/gsdd-new-project` become the default fallback when this active change already defines a concrete bounded lane.
45
+ 6. If `.work/codebase/` exists, read whichever of `.work/codebase/ARCHITECTURE.md`, `.work/codebase/STACK.md`, `.work/codebase/CONVENTIONS.md`, and `.work/codebase/CONCERNS.md` are present. Summarize key findings from available docs in <=500 words as `$CODEBASE_CONTEXT`, emphasizing: safest surfaces to touch, risky zones to avoid, must-know conventions/traps, and what must be re-verified after change. Note any missing docs in the summary.
46
+ 7. If `.work/codebase/` does not exist, build a just-enough inline brownfield baseline instead of stopping. Read the repo root guidance that is cheap and stable (`README.md`, root manifest such as `package.json` / `pyproject.toml` / `Cargo.toml` when present, top-level app entrypoints, and any obviously relevant config or module files surfaced by `$DESCRIPTION`). Summarize the findings in <=500 words as `$CODEBASE_CONTEXT`, explicitly labeling it as a provisional baseline and calling out unknowns. Emphasize: likely implementation surface, likely dependency boundaries, conventions already visible, risky areas to avoid touching blindly, and what must be re-verified after the change. If the repo is still too unclear after this pass, keep that uncertainty explicit so Step 3.6 can recommend `/gsdd-map-codebase`.
47
+ 8. **Session-boundary fallback:** If `.work/.continue-here.bak` exists, read its `<judgment>` section. Use `<active_constraints>` and `<anti_regression>` rules as task-scoping context (do not violate active constraints; do not regress on listed invariants). After reading, run `node .work/bin/gsdd.mjs file-op delete .work/.continue-here.bak --missing ok` (auto-clean).
48
+ 9. Inspect the live branch/worktree surface separately from checkpoint or planning artifacts. Run `node .work/bin/gsdd.mjs control-map --json` when available and use its computed repo/worktree/planning truth to identify stale/spent branches, dirty tracked/untracked/ignored buckets, sibling or detached worktrees, local annotations, and cleanup obligations. This is advisory for quick tasks unless the mismatch makes the task description materially misleading; local annotations are intent hints, not product truth.
49
49
 
50
- If `.planning/quick/` does not exist, create it along with an empty `LOG.md`:
50
+ If `.work/quick/` does not exist, create it along with an empty `LOG.md`:
51
51
 
52
52
  ```markdown
53
53
  # Quick Task Log
@@ -60,7 +60,7 @@ If `.planning/quick/` does not exist, create it along with an empty `LOG.md`:
60
60
 
61
61
  ## Step 2.5: Approach clarification (conditional)
62
62
 
63
- Read `.planning/config.json`.
63
+ Read `.work/config.json`.
64
64
  - If `workflow.discuss` is `false` (or key missing): set `$APPROACH_CONTEXT` to empty, skip to Step 3.
65
65
  - If `workflow.discuss` is `true`: evaluate `$DESCRIPTION` for ambiguity signals.
66
66
 
@@ -102,14 +102,14 @@ Delegate to the planner role in quick mode.
102
102
 
103
103
  <delegate>
104
104
  **Identity:** Planner (quick mode)
105
- **Instruction:** Read `.planning/templates/roles/planner.md` for your role contract, then create a plan for this quick task.
105
+ **Instruction:** Read `.work/templates/roles/planner.md` for your role contract, then create a plan for this quick task.
106
106
 
107
107
  **Context to provide:**
108
108
  - Task description: `$DESCRIPTION`
109
109
  - Approach context: `$APPROACH_CONTEXT` (user-confirmed decisions from Step 2.5 — treat as locked constraints, do not revisit)
110
110
  - Codebase context: `$CODEBASE_CONTEXT` (existing brownfield codebase summary from codebase maps when they exist, otherwise the inline brownfield baseline from Step 2 — use for orientation and risk awareness, not as hard constraints)
111
111
  - Mode: quick (single plan, 1-3 tasks, no research phase)
112
- - Output path: `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md`
112
+ - Output path: `.work/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md`
113
113
 
114
114
  **Constraints:**
115
115
  - If `$APPROACH_CONTEXT` is non-empty, implement the user's confirmed choices — do not substitute alternatives
@@ -118,21 +118,20 @@ Delegate to the planner role in quick mode.
118
118
  - No research phase, no ROADMAP requirements
119
119
  - Do NOT extract phase requirement IDs — there is no active phase
120
120
  - Derive must-haves directly from the task description
121
- - If the quick task is UI-sensitive, include proportional `ui_proof_slots` with slot_id, claim, route_state, required_evidence_kinds, minimum_observations, expected_artifact_types, validation_command, environment, viewport, manual_acceptance_required, and claim_limit; otherwise include a short `no_ui_proof_rationale`
122
- - UI proof slots must be matchable to exact observed evidence later: claim, route/state, observation, evidence kind, artifact path or manual step, privacy metadata, result, and claim limit. Discovery hints from source comments, AST/cAST, semantic search, or Semble-like retrieval do not satisfy proof.
123
- - Observed artifact metadata must include `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; raw screenshots, traces, videos, DOM snapshots, and reports are local-only/unsafe by default. Use `gsdd ui-proof validate <path>` or `gsdd health` when a bundle exists; add `--claim <...>` only for public, publication, tracked, delivery, or release proof use.
121
+ - If the quick task is UI-sensitive, include proportional `browser_proof_required: true`, a short `browser_proof_rationale`, and a plain Browser Proof Plan naming route/state, viewport, runtime path, evidence kind, evidence command or narrowed no-command rationale, observations, artifacts, and claim limit; otherwise set `browser_proof_required: false` with a short rationale.
122
+ - Browser proof must be matchable to exact observed evidence later: route/state, viewport, observation, evidence kind, artifact path or manual step, privacy/safety note, result, and claim limit. Discovery hints from source comments, AST/cAST, semantic search, or Semble-like retrieval do not satisfy proof.
124
123
  - For live rendered UI proof, default to `agent-browser` snapshots/refs, interactions, screenshots, and relevant console/network observations. If unavailable, state the availability constraint and closest project-native interactive browser fallback before narrowing the claim. Existing Playwright/package-script browser tests remain the canonical repeatable regression path when present. The viewport set is plan-owned, but under-specified viewport coverage is weak proof; explain the chosen viewport(s) or narrow the claim limit.
125
- - Keep UI proof proportional: do not scaffold Playwright, Cypress, Cucumber, Storybook, CI, browser MCP, or visual-regression tooling by default
124
+ - Keep browser proof proportional: do not scaffold Playwright, Cypress, Cucumber, Storybook, CI, browser MCP, or visual-regression tooling by default.
126
125
  - Ignore <planning_process> Step 1 requirement extraction; use inline goal-backward planning only
127
126
  - Target minimal context usage
128
127
 
129
- **Output:** `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md`
128
+ **Output:** `.work/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md`
130
129
  **Return:** Plan file path and task count.
131
130
  </delegate>
132
131
 
133
132
  After the planner returns:
134
133
 
135
- **STOP. Verify that `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md` exists on disk before proceeding to execution. If the file does not exist, report the error to the user and do NOT proceed. A plan that exists only in conversation context will be lost.**
134
+ **STOP. Verify that `.work/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md` exists on disk before proceeding to execution. If the file does not exist, report the error to the user and do NOT proceed. A plan that exists only in conversation context will be lost.**
136
135
 
137
136
  ### Quick Plan Self-Check
138
137
 
@@ -147,23 +146,23 @@ This is a self-check, not an independent plan-check. Failures are noted but do N
147
146
 
148
147
  ## Step 3.5: Independent plan check (conditional)
149
148
 
150
- Read `.planning/config.json`.
149
+ Read `.work/config.json`.
151
150
  - If `workflow.planCheck` is `false` (or key missing): skip to Step 3.6.
152
151
  - If `workflow.planCheck` is `true`: delegate to the plan-checker with quick-scoped dimensions.
153
152
 
154
153
  <delegate>
155
154
  **Identity:** Plan Checker (quick mode)
156
- **Instruction:** Read `.planning/templates/delegates/plan-checker.md` for your role contract, then check this quick task plan.
155
+ **Instruction:** Read `.work/templates/delegates/plan-checker.md` for your role contract, then check this quick task plan.
157
156
 
158
157
  **Context to provide:**
159
158
  - Task description: `$DESCRIPTION` (treat as the phase goal equivalent)
160
- - Plan: `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md`
159
+ - Plan: `.work/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md`
161
160
  - Mode: quick
162
161
 
163
162
  **Constraints:**
164
163
  - Check 5 dimensions by default: `requirement_coverage`, `task_completeness`, `dependency_correctness`, `scope_sanity`, `must_have_quality`
165
- - If the quick plan contains `ui_proof_slots` or a rendered UI claim, also check `closure_honesty` so weak UI proof slots block execution
166
- - Skip: `key_link_completeness`, `context_compliance`, `goal_achievement`, `approach_alignment`
164
+ - If the quick plan contains a rendered UI claim, check `goal_achievement` so weak browser proof blocks execution.
165
+ - Skip: `key_link_completeness`, `context_compliance`, and `approach_alignment`; skip `goal_achievement` only when the quick plan has no rendered UI claim
167
166
  - Maximum 1 revision cycle (if blockers found, send back to planner once, then accept result)
168
167
  - Blocker threshold: only block on `task_completeness` or `scope_sanity` violations
169
168
  - Warnings for other dimensions are noted but do not block
@@ -190,8 +189,8 @@ Evaluate the plan against quick-scope boundaries. Read the plan file and check:
190
189
  | Files modified | >8 distinct files in plan | "This task touches {N} files — consider `/gsdd-plan` for full ceremony." |
191
190
  | Architecture keywords in `$DESCRIPTION` | contains: `refactor`, `migration`, `security`, `auth`, `API design`, `schema`, `database` | "This looks like architectural work — consider `/gsdd-plan` for approach exploration." |
192
191
  | New public APIs | Plan tasks create new route files, API endpoints, or exported interfaces | "New public surface area detected — consider `/gsdd-plan` for approach exploration." |
193
- | Orientation gap | No `.planning/codebase/` exists AND the inline brownfield baseline still cannot name a clear implementation surface, dependency boundary, or safe-to-touch module | "This repo still needs deeper orientation — consider `/gsdd-map-codebase` before changing code." |
194
- | Undefined bounded change | `$DESCRIPTION` still does not identify a concrete bug, feature, target surface, or observable outcome after clarification | "This does not yet describe a bounded change — use `/gsdd-new-project` to define the work first. If `.planning/brownfield-change/CHANGE.md` already defines a concrete bounded lane, treat `/gsdd-new-project` as an intentional widen path rather than the default fallback." |
192
+ | Orientation gap | No `.work/codebase/` exists AND the inline brownfield baseline still cannot name a clear implementation surface, dependency boundary, or safe-to-touch module | "This repo still needs deeper orientation — consider `/gsdd-map-codebase` before changing code." |
193
+ | Undefined bounded change | `$DESCRIPTION` still does not identify a concrete bug, feature, target surface, or observable outcome after clarification | "This does not yet describe a bounded change — use `/gsdd-new-project` to define the work first. If `.work/brownfield-change/CHANGE.md` already defines a concrete bounded lane, treat `/gsdd-new-project` as an intentional widen path rather than the default fallback." |
195
194
 
196
195
  If any signals fire, concatenate the matching advisory text in the listed order as `$SCOPE_WARNING`. If the undefined bounded change signal fires, keep that advisory first so the routing recommendation stays explicit.
197
196
  If no signals fire, `$SCOPE_WARNING` is empty.
@@ -256,11 +255,11 @@ Delegate to the executor role.
256
255
 
257
256
  <delegate>
258
257
  **Identity:** Executor
259
- **Instruction:** Read `.planning/templates/roles/executor.md` for your role contract, then execute the quick task plan.
258
+ **Instruction:** Read `.work/templates/roles/executor.md` for your role contract, then execute the quick task plan.
260
259
 
261
260
  **Context to provide:**
262
- - Plan file: `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md`
263
- - Project conventions: `.planning/config.json` (git protocol section)
261
+ - Plan file: `.work/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md`
262
+ - Project conventions: `.work/config.json` (git protocol section)
264
263
  - Quick task -- do NOT update ROADMAP.md
265
264
 
266
265
  **Constraints:**
@@ -268,52 +267,52 @@ Delegate to the executor role.
268
267
  - Follow advisory git protocol from config.json
269
268
  - Skip the <state_updates> section of your role contract entirely
270
269
  - Do NOT update ROADMAP.md phase status or SPEC.md current state
271
- - Create summary at: `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-SUMMARY.md`
272
- - If the quick plan defines `ui_proof_slots`, create or update `.planning/quick/$NEXT_NUM-$SLUG/UI-PROOF.md` with fenced JSON containing required top-level fields: `proof_bundle_version`, `scope`, `route_state`, `environment`, `viewport`, `evidence_inputs`, `commands_or_manual_steps`, `observations`, `artifacts`, `privacy`, `result`, and `claim_limits`
273
- - For live UI proof, record `agent-browser` in `evidence_inputs.tools_used` when used, the exact commands or manual ref-based steps, screenshot/report artifact paths, and any relevant console/network observations. If `agent-browser` was unavailable, record that availability constraint and fallback tool explicitly. If existing Playwright tests supplied regression evidence, record the package command and result separately from the `agent-browser` runtime observation.
270
+ - Create summary at: `.work/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-SUMMARY.md`
271
+ - If the quick plan requires browser proof, create or update `.work/quick/$NEXT_NUM-$SLUG/UI-PROOF.md` as a plain observation record with route/state, viewport, runtime path, evidence command or narrowed no-command rationale, observations, artifacts, privacy/safety note, result, and claim limit.
272
+ - For live browser proof, record `agent-browser` when used, the exact commands or manual ref-based steps, screenshot/report artifact paths, and any relevant console/network observations. If `agent-browser` was unavailable, record that availability constraint and fallback tool explicitly. If existing Playwright tests supplied regression evidence, record the package command and result separately from the runtime observation.
274
273
  - Human approval for visual taste, accessibility judgment, baseline acceptance, subjective polish/layout quality, or privacy publication does not replace required `code`, `test`, `runtime`, or `delivery` evidence
275
274
 
276
- **Output:** `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-SUMMARY.md`
275
+ **Output:** `.work/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-SUMMARY.md`
277
276
  **Return:** Summary file path and completion status.
278
277
  </delegate>
279
278
 
280
279
  After the executor returns:
281
280
 
282
- **STOP. Verify the SUMMARY file exists at `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-SUMMARY.md` on disk. If it does not exist, report the write failure. Do NOT proceed to verification or LOG.md update without a persisted summary.**
281
+ **STOP. Verify the SUMMARY file exists at `.work/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-SUMMARY.md` on disk. If it does not exist, report the write failure. Do NOT proceed to verification or LOG.md update without a persisted summary.**
283
282
 
284
283
  ---
285
284
 
286
285
  ## Step 5: Verify (conditional)
287
286
 
288
- Read `.planning/config.json`.
287
+ Read `.work/config.json`.
289
288
  - If `workflow.verifier` is `false`, skip to Step 6.
290
289
  - If `workflow.verifier` is `true`, delegate to the verifier role:
291
290
 
292
291
  <delegate>
293
292
  **Identity:** Verifier (quick mode)
294
- **Instruction:** Read `.planning/templates/roles/verifier.md` for your role contract, then verify the quick task.
293
+ **Instruction:** Read `.work/templates/roles/verifier.md` for your role contract, then verify the quick task.
295
294
 
296
295
  **Context to provide:**
297
296
  - Task description: `$DESCRIPTION`
298
- - Plan: `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md`
299
- - Summary: `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-SUMMARY.md`
297
+ - Plan: `.work/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md`
298
+ - Summary: `.work/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-SUMMARY.md`
300
299
 
301
300
  **Constraints:**
302
301
  - Verify goal achievement against the task description
303
302
  - Quick scope -- do not check ROADMAP alignment or cross-phase integration
304
- - Write report to: `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-VERIFICATION.md`
303
+ - Write report to: `.work/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-VERIFICATION.md`
305
304
 
306
- **Output:** `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-VERIFICATION.md`
305
+ **Output:** `.work/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-VERIFICATION.md`
307
306
  **Return:** Verification status (passed | gaps_found | human_needed).
308
307
  </delegate>
309
308
 
310
- **STOP. Verify the VERIFICATION file exists at `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-VERIFICATION.md` on disk (when verifier ran). If it does not exist, report the write failure. Do NOT proceed to LOG.md update without a persisted verification report.**
309
+ **STOP. Verify the VERIFICATION file exists at `.work/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-VERIFICATION.md` on disk (when verifier ran). If it does not exist, report the write failure. Do NOT proceed to LOG.md update without a persisted verification report.**
311
310
 
312
311
  ---
313
312
 
314
313
  ## Step 6: Update LOG.md
315
314
 
316
- Append a row to `.planning/quick/LOG.md`:
315
+ Append a row to `.work/quick/LOG.md`:
317
316
 
318
317
  ```markdown
319
318
  | $NEXT_NUM | $DESCRIPTION | $DATE | $STATUS | [$NEXT_NUM-$SLUG](./$NEXT_NUM-$SLUG/) |
@@ -339,8 +338,8 @@ Report to the user:
339
338
  <success_criteria>
340
339
  - [ ] User provided a task description
341
340
  - [ ] Approach clarification ran (only if workflow.discuss is true AND ambiguity detected)
342
- - [ ] `.planning/quick/` directory exists (created if needed)
343
- - [ ] Task directory created at `.planning/quick/NNN-slug/`
341
+ - [ ] `.work/quick/` directory exists (created if needed)
342
+ - [ ] Task directory created at `.work/quick/NNN-slug/`
344
343
  - [ ] `NNN-PLAN.md` created by planner (1-3 tasks)
345
344
  - [ ] Independent plan check ran (only if workflow.planCheck is true)
346
345
  - [ ] Plan preview presented to user before execution
@@ -358,10 +357,10 @@ Report to the user what was accomplished, then present the next step:
358
357
  **Completed:** Quick task #{next_num} — {description}
359
358
 
360
359
  Created:
361
- - `.planning/quick/{next_num}-{slug}/{next_num}-PLAN.md`
362
- - `.planning/quick/{next_num}-{slug}/{next_num}-SUMMARY.md`
363
- - `.planning/quick/{next_num}-{slug}/{next_num}-VERIFICATION.md` (if verifier enabled)
364
- - Updated `.planning/quick/LOG.md`
360
+ - `.work/quick/{next_num}-{slug}/{next_num}-PLAN.md`
361
+ - `.work/quick/{next_num}-{slug}/{next_num}-SUMMARY.md`
362
+ - `.work/quick/{next_num}-{slug}/{next_num}-VERIFICATION.md` (if verifier enabled)
363
+ - Updated `.work/quick/LOG.md`
365
364
 
366
365
  **Next step:** `/gsdd-progress` — check project status and continue phase work
367
366
 
@@ -7,15 +7,15 @@ Scope boundary: unlike progress.md, you have side effects — checkpoint cleanup
7
7
  </role>
8
8
 
9
9
  <prerequisites>
10
- `.planning/` should exist. If it does not, route the user to `npx -y gsdd-cli init`.
10
+ `.work/` should exist. If it does not, route the user to `npx -y gsdd-cli init`.
11
11
  </prerequisites>
12
12
 
13
13
  <repo_root_helper_contract>
14
- All `node .planning/bin/gsdd.mjs ...` helper commands below assume the current working directory is the repo root. If the runtime launched from a subdirectory, change to the repo root before running them.
14
+ All `node .work/bin/gsdd.mjs ...` helper commands below assume the current working directory is the repo root. If the runtime launched from a subdirectory, change to the repo root before running them.
15
15
  </repo_root_helper_contract>
16
16
 
17
17
  <runtime_contract>
18
- Use the `Runtime` type from `.planning/SPEC.md`.
18
+ Use the `Runtime` type from `.work/SPEC.md`.
19
19
  Infer runtime from the launching surface when obvious: `.claude/` -> `claude-code`, `.codex/` or Codex portable skill -> `codex-cli`, `.opencode/` -> `opencode`, otherwise `other`.
20
20
  When a checkpoint's `runtime` differs from the inferred current runtime, surface it as an informational note in `<present_status>` — it is context, not a gate.
21
21
  </runtime_contract>
@@ -23,7 +23,7 @@ When a checkpoint's `runtime` differs from the inferred current runtime, surface
23
23
  <lifecycle_preflight>
24
24
  Before loading checkpoint state or cleaning up any checkpoint file, run:
25
25
 
26
- - `node .planning/bin/gsdd.mjs lifecycle-preflight resume`
26
+ - `node .work/bin/gsdd.mjs lifecycle-preflight resume`
27
27
 
28
28
  If the preflight result is `blocked`, STOP and report the blocker instead of inferring resume eligibility from workflow-local prose.
29
29
 
@@ -36,15 +36,16 @@ Treat the preflight as an authorization seam over shared repo truth only:
36
36
  <process>
37
37
 
38
38
  <control_map_reconciliation>
39
- Before routing from a checkpoint, run `node .planning/bin/gsdd.mjs control-map --json` when available. Reconcile the checkpoint narrative against computed repo/worktree/planning truth: canonical branch/HEAD, tracked/untracked/ignored dirty buckets, sibling or detached worktrees, local annotations, active brownfield anchors, and planning drift. If the checkpoint understates dirty work, points at a stale branch/worktree, or conflicts with the active planning/brownfield surface, stop and present the mismatch before recommending execution. Local annotations are useful intent hints, not authority.
39
+ Before routing from a checkpoint, run `node .work/bin/gsdd.mjs control-map --json` when available. Reconcile the checkpoint narrative against computed repo/worktree/planning truth: canonical branch/HEAD, tracked/untracked/ignored dirty buckets, sibling or detached worktrees, local annotations, active brownfield anchors, and planning drift. If the checkpoint understates dirty work, points at a stale branch/worktree, or conflicts with the active planning/brownfield surface, stop and present the mismatch before recommending execution. Local annotations are useful intent hints, not authority.
40
40
  </control_map_reconciliation>
41
41
 
42
42
  <detect_state>
43
43
  Check for project artifacts in order:
44
44
 
45
- 1. **No `.planning/` directory** — route user to run `npx -y gsdd-cli init`. Stop.
46
- 2. **If `.planning/brownfield-change/CHANGE.md` exists** — this repo has an active medium-scope brownfield change. Proceed to load brownfield continuity state even if there is no active roadmap.
47
- 3. **No `.planning/SPEC.md` or no `.planning/ROADMAP.md`** `.planning/` exists but the project is not fully initialized (partial init). Route user to run the `/gsdd-new-project` workflow. Stop.
45
+ 1. **No `.work/` directory** — route user to run `npx -y gsdd-cli init`. Stop.
46
+ 2. **If `.work/brownfield-change/CHANGE.md` exists and `Current posture` is not `closed`** — this repo has an active medium-scope brownfield change. Proceed to load brownfield continuity state even if there is no active roadmap.
47
+ - If `Current posture` is `closed`, treat the file as historical context only; it does not replace a checkpoint or active roadmap.
48
+ 3. **No `.work/SPEC.md` or no `.work/ROADMAP.md`** — `.work/` exists but the project is not fully initialized (partial init). Route user to run the `/gsdd-new-project` workflow. Stop.
48
49
  4. **Both exist** — proceed to load state.
49
50
  </detect_state>
50
51
 
@@ -52,7 +53,7 @@ Check for project artifacts in order:
52
53
  Read the following files and extract state:
53
54
 
54
55
  **ROADMAP.md:**
55
- If `.planning/ROADMAP.md` exists, read it. If it is absent because the active brownfield change is the only continuity anchor, keep phase fields empty and continue from `CHANGE.md`.
56
+ If `.work/ROADMAP.md` exists, read it. If it is absent because the active brownfield change is the only continuity anchor, keep phase fields empty and continue from `CHANGE.md`.
56
57
 
57
58
  When present, parse phase statuses:
58
59
  - `[ ]` = not started
@@ -66,14 +67,14 @@ Determine:
66
67
  - Completed phase count
67
68
 
68
69
  **SPEC.md:**
69
- If `.planning/SPEC.md` exists, read it. If it is absent because the active brownfield change is the only continuity anchor, label project identity as `unknown from SPEC.md` and derive runtime/context from the launching surface plus `CHANGE.md` / `HANDOFF.md`.
70
+ If `.work/SPEC.md` exists, read it. If it is absent because the active brownfield change is the only continuity anchor, label project identity as `unknown from SPEC.md` and derive runtime/context from the launching surface plus `CHANGE.md` / `HANDOFF.md`.
70
71
 
71
72
  When present, extract:
72
73
  - Project name or description (first heading or "What This Is" section)
73
74
  - Current state summary if present
74
75
 
75
76
  **Active brownfield change:**
76
- If `.planning/brownfield-change/CHANGE.md` exists, read it first as the canonical operational continuity anchor and extract:
77
+ If `.work/brownfield-change/CHANGE.md` exists and is not closed, read it first as the canonical operational continuity anchor and extract:
77
78
  - change title from the first heading
78
79
  - current posture from `## Current Status`
79
80
  - current branch / integration surface from `## Current Status`
@@ -81,7 +82,7 @@ If `.planning/brownfield-change/CHANGE.md` exists, read it first as the canonica
81
82
  - next action from `## Next Action`
82
83
  - declared write scope from `## PR Slice Ownership` when present
83
84
 
84
- If `.planning/brownfield-change/HANDOFF.md` exists, read it as judgment-only context:
85
+ If `.work/brownfield-change/HANDOFF.md` exists, read it as judgment-only context:
85
86
  - active constraints
86
87
  - unresolved uncertainty
87
88
  - decision posture
@@ -91,7 +92,7 @@ If `.planning/brownfield-change/HANDOFF.md` exists, read it as judgment-only con
91
92
  Do not flatten `CHANGE.md` and `HANDOFF.md` into co-equal operational sources. `CHANGE.md` stays the live status/next-action anchor; `HANDOFF.md` explains why that posture exists.
92
93
 
93
94
  **Checkpoint file:**
94
- Check if `.planning/.continue-here.md` exists. If yes, read it and extract:
95
+ Check if `.work/.continue-here.md` exists. If yes, read it and extract:
95
96
  - `workflow` frontmatter (phase/quick/generic)
96
97
  - `phase` frontmatter
97
98
  - `runtime` frontmatter (the runtime that wrote the checkpoint; use `unknown` if field absent)
@@ -99,12 +100,12 @@ Check if `.planning/.continue-here.md` exists. If yes, read it and extract:
99
100
  - `<judgment>` if present, including `<active_constraints>`, `<unresolved_uncertainty>`, `<decision_posture>`, and `<anti_regression>`
100
101
 
101
102
  **Phase directories:**
102
- Scan `.planning/phases/` for:
103
+ Scan `.work/phases/` for:
103
104
  - Directories with a PLAN file but no SUMMARY file (incomplete execution)
104
- - Directories with a SUMMARY file but no VERIFICATION file (unverified phase, if `workflow.verifier` is enabled in `.planning/config.json`; if config.json cannot be read, assume verifier is disabled)
105
+ - Directories with a SUMMARY file but no VERIFICATION file (unverified phase, if `workflow.verifier` is enabled in `.work/config.json`; if config.json cannot be read, assume verifier is disabled)
105
106
 
106
107
  **Quick task log:**
107
- If `.planning/quick/LOG.md` exists, read the last entry. Check if it has a non-terminal status (not `done`/`passed`).
108
+ If `.work/quick/LOG.md` exists, read the last entry. Check if it has a non-terminal status (not `done`/`passed`).
108
109
 
109
110
  **Git/worktree truth:**
110
111
  Collect the live integration-surface facts separately from checkpoint narrative truth:
@@ -120,7 +121,7 @@ Collect the live integration-surface facts separately from checkpoint narrative
120
121
  <provenance_reconciliation>
121
122
  Before routing, reconstruct and compare these truth buckets explicitly:
122
123
 
123
- 1. **Checkpoint narrative truth** — what `.planning/.continue-here.md` claims was happening
124
+ 1. **Checkpoint narrative truth** — what `.work/.continue-here.md` claims was happening
124
125
  2. **Planning/artifact truth** — what ROADMAP, SPEC, phase files, quick-task logs, and the active brownfield change artifacts say
125
126
  3. **Git/worktree truth** — what the live branch and working tree say now
126
127
 
@@ -152,12 +153,12 @@ If git/worktree truth materially disagrees with the active brownfield artifact:
152
153
  </provenance_reconciliation>
153
154
 
154
155
  <validate_checkpoint>
155
- Only run this step when `.planning/.continue-here.md` was found in `<load_artifacts>`. If no checkpoint exists, skip this step entirely.
156
+ Only run this step when `.work/.continue-here.md` was found in `<load_artifacts>`. If no checkpoint exists, skip this step entirely.
156
157
 
157
158
  Cross-validate checkpoint fields against current roadmap state in this order:
158
159
 
159
160
  1. Extract the checkpoint `workflow` and `phase` frontmatter fields.
160
- 2. If `phase` is non-null, look up that exact phase name in `.planning/ROADMAP.md`.
161
+ 2. If `phase` is non-null, look up that exact phase name in `.work/ROADMAP.md`.
161
162
  - If the matching roadmap entry is `[x]`, mark the checkpoint as stale.
162
163
  - Record the specific reason in this form: `checkpoint references phase "[phase]" which is already complete [x] in ROADMAP.md`.
163
164
  - Stop further staleness checks after recording this reason.
@@ -280,7 +281,7 @@ If `<validate_checkpoint>` marked the checkpoint as stale, keep the same routing
280
281
  If `<provenance_reconciliation>` marked a material checkpoint/worktree mismatch, keep the same routing logic but require explicit acknowledgement before continuing. The workflow should not silently route onward from a materially misleading checkpoint narrative.
281
282
  If an active brownfield change also exists, apply the same strict-match rule before making a `phase` or `quick` checkpoint primary. A checkpoint only stays primary when branch alignment, scope alignment, and still-active execution state all hold at once. Otherwise, keep the checkpoint visible and user-selectable, but fall through to the active brownfield change as the default resume target.
282
283
 
283
- **Active brownfield change (`.planning/brownfield-change/CHANGE.md`):**
284
+ **Active brownfield change (`.work/brownfield-change/CHANGE.md`):**
284
285
  If there is no checkpoint, or if the surviving checkpoint does not satisfy the strict-match rule against the active brownfield change:
285
286
  - present the `CHANGE.md` next action as the primary resume target
286
287
  - keep `HANDOFF.md` as supporting judgment context only
@@ -327,8 +328,8 @@ Wait for user selection.
327
328
  <cleanup_checkpoint>
328
329
  Immediately after the user confirms their action selection (before routing to the target workflow):
329
330
  - If the user chose to resume from `.continue-here.md`:
330
- 1. Run `node .planning/bin/gsdd.mjs file-op copy .planning/.continue-here.md .planning/.continue-here.bak`.
331
- 2. After the copy succeeds, run `node .planning/bin/gsdd.mjs file-op delete .planning/.continue-here.md`.
331
+ 1. Run `node .work/bin/gsdd.mjs file-op copy .work/.continue-here.md .work/.continue-here.bak`.
332
+ 2. After the copy succeeds, run `node .work/bin/gsdd.mjs file-op delete .work/.continue-here.md`.
332
333
  - If the user chose a different action (not based on the checkpoint), leave `.continue-here.md` in place for a future resume.
333
334
 
334
335
  Copying before deleting ensures the checkpoint survives a session crash between deletion and dispatch. `.continue-here.bak` is cleaned up by the downstream workflow after absorbing the judgment, or by the next `pause.md` run.