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.
- package/README.md +53 -22
- package/agents/DISTILLATION.md +2 -2
- package/agents/README.md +4 -4
- package/agents/approach-explorer.md +4 -4
- package/agents/executor.md +20 -20
- package/agents/integration-checker.md +2 -2
- package/agents/planner.md +10 -26
- package/agents/researcher.md +2 -2
- package/agents/roadmapper.md +6 -6
- package/agents/synthesizer.md +18 -18
- package/agents/verifier.md +3 -3
- package/bin/adapters/agents.mjs +3 -3
- package/bin/adapters/claude.mjs +16 -14
- package/bin/adapters/opencode.mjs +15 -12
- package/bin/gsdd.mjs +16 -13
- package/bin/lib/{models.mjs → config.mjs} +23 -16
- package/bin/lib/control-map.mjs +17 -488
- package/bin/lib/health-truth.mjs +8 -13
- package/bin/lib/health.mjs +25 -39
- package/bin/lib/init-flow.mjs +44 -38
- package/bin/lib/init-prompts.mjs +3 -3
- package/bin/lib/init-runtime.mjs +11 -30
- package/bin/lib/lifecycle-preflight.mjs +97 -410
- package/bin/lib/lifecycle-state.mjs +2 -1
- package/bin/lib/next.mjs +243 -20
- package/bin/lib/phase.mjs +706 -280
- package/bin/lib/plan-constants.mjs +0 -5
- package/bin/lib/rendering.mjs +64 -44
- package/bin/lib/runtime-freshness.mjs +18 -15
- package/bin/lib/state-dir.mjs +45 -0
- package/bin/lib/templates.mjs +59 -22
- package/bin/lib/work-context.mjs +12 -1
- package/bin/lib/workflows.mjs +0 -1
- package/bin/lib/workspace-root.mjs +11 -6
- package/distilled/DESIGN.md +89 -31
- package/distilled/EVIDENCE-INDEX.md +18 -5
- package/distilled/README.md +23 -33
- package/distilled/SKILL.md +9 -10
- package/distilled/templates/agents.block.md +5 -5
- package/distilled/templates/approach.md +3 -3
- package/distilled/templates/auth-matrix.md +2 -2
- package/distilled/templates/brownfield-change/CHANGE.md +1 -1
- package/distilled/templates/delegates/approach-explorer.md +5 -5
- package/distilled/templates/delegates/mapper-arch.md +3 -3
- package/distilled/templates/delegates/mapper-concerns.md +4 -4
- package/distilled/templates/delegates/mapper-quality.md +3 -3
- package/distilled/templates/delegates/mapper-tech.md +3 -3
- package/distilled/templates/delegates/plan-checker.md +18 -19
- package/distilled/templates/delegates/researcher-architecture.md +3 -3
- package/distilled/templates/delegates/researcher-features.md +3 -3
- package/distilled/templates/delegates/researcher-pitfalls.md +3 -3
- package/distilled/templates/delegates/researcher-stack.md +3 -3
- package/distilled/templates/delegates/researcher-synthesizer.md +7 -7
- package/distilled/templates/research/architecture.md +1 -1
- package/distilled/templates/research/pitfalls.md +1 -1
- package/distilled/templates/research/stack.md +1 -1
- package/distilled/templates/roadmap.md +4 -4
- package/distilled/templates/spec.md +2 -2
- package/distilled/templates/ui-proof.md +81 -181
- package/distilled/workflows/audit-milestone.md +23 -23
- package/distilled/workflows/complete-milestone.md +35 -35
- package/distilled/workflows/execute.md +34 -35
- package/distilled/workflows/map-codebase.md +30 -30
- package/distilled/workflows/new-milestone.md +18 -18
- package/distilled/workflows/new-project.md +45 -45
- package/distilled/workflows/pause.md +15 -15
- package/distilled/workflows/plan.md +106 -114
- package/distilled/workflows/progress.md +40 -39
- package/distilled/workflows/quick.md +49 -50
- package/distilled/workflows/resume.md +23 -22
- package/distilled/workflows/verify-work.md +7 -7
- package/distilled/workflows/verify.md +26 -26
- package/docs/BROWNFIELD-PROOF.md +1 -1
- package/docs/RUNTIME-SUPPORT.md +13 -13
- package/docs/USER-GUIDE.md +26 -21
- package/docs/claude/context-monitor.md +1 -1
- package/docs/proof/consumer-node-cli/README.md +1 -1
- package/package.json +3 -3
- package/bin/lib/closeout-report.mjs +0 -318
- package/bin/lib/evidence-contract.mjs +0 -325
- package/bin/lib/provenance.mjs +0 -390
- package/bin/lib/session-fingerprint.mjs +0 -223
- package/bin/lib/ui-proof.mjs +0 -1007
- package/distilled/workflows/plan-milestone-gaps.md +0 -204
|
@@ -6,11 +6,11 @@ Your output: SPEC.md (the single source of truth) and ROADMAP.md (the execution
|
|
|
6
6
|
</role>
|
|
7
7
|
|
|
8
8
|
<auto_mode>
|
|
9
|
-
Check `.
|
|
9
|
+
Check `.work/config.json` for `autoAdvance: true`. If NOT set, skip this section entirely.
|
|
10
10
|
|
|
11
11
|
When `autoAdvance: true`, this workflow runs non-interactively:
|
|
12
12
|
|
|
13
|
-
1. **Input:** Read `.
|
|
13
|
+
1. **Input:** Read `.work/PROJECT_BRIEF.md`. If it does not exist, stop with a clear error: "Auto mode requires a project brief. Provide one via `npx -y gsdd-cli init --auto --tools <runtime> --brief <path>` or place it at `.work/PROJECT_BRIEF.md`."
|
|
14
14
|
|
|
15
15
|
2. **Extract context from brief:** Parse the brief document to understand the project goal, target users, constraints, requirements, and out-of-scope items. Apply the same requirement categorization as `<questioning>` (Table Stakes / Differentiators / Out of Scope). Do NOT ask interactive questions.
|
|
16
16
|
|
|
@@ -28,10 +28,10 @@ All other sections (`<detect_mode>`, `<codebase_context>`, `<research>`, `<spec_
|
|
|
28
28
|
<load_context>
|
|
29
29
|
Before starting, read these files (if they exist):
|
|
30
30
|
1. `AGENTS.md` (root) — understand the full SDD workflow and governance rules.
|
|
31
|
-
2. `.
|
|
32
|
-
3. `.
|
|
31
|
+
2. `.work/templates/spec.md` — template for creating SPEC.md
|
|
32
|
+
3. `.work/templates/roadmap.md` — template for creating ROADMAP.md
|
|
33
33
|
4. Project root files: `package.json`, `README.md`, main entry point, `.gitignore`
|
|
34
|
-
5. `.
|
|
34
|
+
5. `.work/config.json` — The deterministic project settings. Key fields:
|
|
35
35
|
- `researchDepth`: balanced | fast | deep — controls research thoroughness
|
|
36
36
|
- `parallelization`: true | false - whether to run delegate work in parallel when the platform supports it; when false, run the same delegates sequentially
|
|
37
37
|
- `workflow.research`: true | false - whether to do domain research before spec
|
|
@@ -39,13 +39,13 @@ Before starting, read these files (if they exist):
|
|
|
39
39
|
- `workflow.verifier`: true | false — whether verifier runs after execution
|
|
40
40
|
- `modelProfile`: balanced | quality | budget — model selection hint
|
|
41
41
|
- `gitProtocol`: advisory git guidance only — follow repo/user conventions first and never invent phase/plan/task git naming by default
|
|
42
|
-
6. Any existing `.
|
|
43
|
-
7. `.
|
|
42
|
+
6. Any existing `.work/SPEC.md` or `.work/ROADMAP.md` (if resuming)
|
|
43
|
+
7. `.work/brownfield-change/CHANGE.md`, `HANDOFF.md`, and `VERIFICATION.md` (when present as the widening input from an active bounded change)
|
|
44
44
|
</load_context>
|
|
45
45
|
|
|
46
46
|
<project_principles>
|
|
47
47
|
Before diving into technical specifications, establish the core governing principles of the project.
|
|
48
|
-
If `autoAdvance: true` in `.
|
|
48
|
+
If `autoAdvance: true` in `.work/config.json`, skip this question. Infer core principles
|
|
49
49
|
from the project brief (code quality signals, constraint language, scope decisions) and note
|
|
50
50
|
the inferred principles in the completion report. Otherwise:
|
|
51
51
|
Ask the user: "What are the core principles for this project regarding code quality, UI consistency, or performance?"
|
|
@@ -57,23 +57,23 @@ Determine the situation:
|
|
|
57
57
|
|
|
58
58
|
- **Greenfield**: No existing code. Empty or minimal project. Skip codebase audit, go to questioning.
|
|
59
59
|
- **Brownfield**: Existing codebase. You MUST audit before questioning.
|
|
60
|
-
- **Resuming**: `.
|
|
61
|
-
- **Concrete brownfield continuity already exists**: if `.
|
|
60
|
+
- **Resuming**: `.work/SPEC.md` already exists. Read it, confirm current state with developer, continue from where things left off.
|
|
61
|
+
- **Concrete brownfield continuity already exists**: if `.work/brownfield-change/CHANGE.md` exists, treat `/gsdd-new-project` as an explicit widen path into full milestone setup, not as the default resume route for that bounded change. Preserve the current bounded context unless the user clearly wants to widen scope.
|
|
62
62
|
</detect_mode>
|
|
63
63
|
|
|
64
64
|
<brownfield_widening_context>
|
|
65
|
-
If `.
|
|
65
|
+
If `.work/brownfield-change/CHANGE.md` exists, treat it as an explicit widening input rather than as noise to rediscover:
|
|
66
66
|
|
|
67
67
|
1. Read `CHANGE.md` for the active goal, in-scope/out-of-scope, done-when, next action, and declared write scope.
|
|
68
68
|
2. Read `HANDOFF.md` for preserved constraints, unresolved uncertainty, decision posture, and anti-regression rules.
|
|
69
69
|
3. Read `VERIFICATION.md` for existing proof, open gaps, and any partial validation that the first milestone should inherit honestly.
|
|
70
70
|
|
|
71
71
|
Do not create a new promotion artifact. Reuse the existing brownfield folder directly when widening into milestone setup.
|
|
72
|
-
If `.
|
|
72
|
+
If `.work/MILESTONES.md` already contains shipped milestone history, stop and route this widen request to `/gsdd-new-milestone` instead of reopening first-milestone initialization here.
|
|
73
73
|
</brownfield_widening_context>
|
|
74
74
|
|
|
75
75
|
<milestone_context>
|
|
76
|
-
Determine research context before spawning researchers. Check if `.
|
|
76
|
+
Determine research context before spawning researchers. Check if `.work/SPEC.md` has existing Validated requirements:
|
|
77
77
|
|
|
78
78
|
- **Greenfield**: No SPEC.md, or SPEC.md has no "Validated" items → Research from scratch for this domain.
|
|
79
79
|
- **Subsequent milestone**: SPEC.md exists with Validated items → Research what's needed to ADD the new feature set — do NOT re-research the existing system.
|
|
@@ -87,7 +87,7 @@ Before asking ANY questions, you must understand what exists.
|
|
|
87
87
|
|
|
88
88
|
### Check for Existing Codebase Maps
|
|
89
89
|
|
|
90
|
-
Check whether `.
|
|
90
|
+
Check whether `.work/codebase/STACK.md`, `.work/codebase/ARCHITECTURE.md`, `.work/codebase/CONVENTIONS.md`, or `.work/codebase/CONCERNS.md` already exist and contain substantive content.
|
|
91
91
|
|
|
92
92
|
**If codebase maps exist:** Use them directly. Skip to Brownfield Validated Requirements Inference below.
|
|
93
93
|
|
|
@@ -97,7 +97,7 @@ Inform the user: "No codebase maps found. Running codebase mapping before contin
|
|
|
97
97
|
|
|
98
98
|
This is an internal prerequisite of `new-project`, not a user-facing routing requirement. If the user started with `/gsdd-new-project` on a brownfield repo, do not bounce them out and tell them to restart with `/gsdd-map-codebase`. Run the mapping dependency, then continue this workflow.
|
|
99
99
|
|
|
100
|
-
If `.
|
|
100
|
+
If `.work/brownfield-change/CHANGE.md` exists, keep it as the current bounded continuity anchor while you do this work. Do not treat its presence as evidence that the user should have used another command instead. The only question is whether they intentionally want to widen that bounded brownfield change into full milestone planning.
|
|
101
101
|
|
|
102
102
|
Read and follow the `gsdd-map-codebase` skill now. Prefer the repo-local `.agents/skills/gsdd-map-codebase/SKILL.md` when it exists; otherwise use the globally installed `gsdd-map-codebase` skill available in the current runtime. Execute its full flow (check existing, spawn mappers, validate, secrets scan). When map-codebase completes, return here and continue from Brownfield Validated Requirements Inference below.
|
|
103
103
|
|
|
@@ -105,8 +105,8 @@ Read and follow the `gsdd-map-codebase` skill now. Prefer the repo-local `.agent
|
|
|
105
105
|
|
|
106
106
|
Read the completed codebase map and infer what the project already does. These become **Validated** requirements in SPEC.md -- existing capabilities the new work must not break.
|
|
107
107
|
|
|
108
|
-
1. Read `.
|
|
109
|
-
2. Read `.
|
|
108
|
+
1. Read `.work/codebase/ARCHITECTURE.md` -- identify existing components and their responsibilities
|
|
109
|
+
2. Read `.work/codebase/STACK.md` -- identify what's already integrated
|
|
110
110
|
3. For each existing capability: add as a Validated requirement in SPEC.md later
|
|
111
111
|
|
|
112
112
|
Example format (for SPEC.md requirements section):
|
|
@@ -199,7 +199,7 @@ YOU: "So two views: today and someday. What happens to completed tasks — archi
|
|
|
199
199
|
<research>
|
|
200
200
|
MANDATORY STEP. After the goal is clarified but BEFORE writing any specs.
|
|
201
201
|
|
|
202
|
-
**Check config first:** Read `.
|
|
202
|
+
**Check config first:** Read `.work/config.json`.
|
|
203
203
|
- If `workflow.research: false` → skip this section entirely, go to `<spec_creation>`.
|
|
204
204
|
- If `researchDepth: "fast"` - use the same 4 specialists below, then synthesize `SUMMARY.md` inline. Faster and cheaper; acceptable for well-known domains.
|
|
205
205
|
- If `researchDepth: "balanced"` or `"deep"` - use the same 4 specialists below plus the synthesizer (default).
|
|
@@ -218,50 +218,50 @@ Use the same 4 specialized researchers every time. The difference is execution o
|
|
|
218
218
|
|
|
219
219
|
```
|
|
220
220
|
Spawning 4 researchers...
|
|
221
|
-
-> Stack research -> .
|
|
222
|
-
-> Features research -> .
|
|
223
|
-
-> Architecture research -> .
|
|
224
|
-
-> Pitfalls research -> .
|
|
221
|
+
-> Stack research -> .work/research/STACK.md
|
|
222
|
+
-> Features research -> .work/research/FEATURES.md
|
|
223
|
+
-> Architecture research -> .work/research/ARCHITECTURE.md
|
|
224
|
+
-> Pitfalls research -> .work/research/PITFALLS.md
|
|
225
225
|
```
|
|
226
226
|
|
|
227
|
-
Ensure `.
|
|
227
|
+
Ensure `.work/research/` directory exists before spawning.
|
|
228
228
|
|
|
229
229
|
<delegate>
|
|
230
230
|
Agent: StackResearcher
|
|
231
|
-
Parallel: (use parallelization value from .
|
|
231
|
+
Parallel: (use parallelization value from .work/config.json)
|
|
232
232
|
Context: Project goal: [user's stated goal]. Milestone context: [greenfield|subsequent]. DO NOT share conversation history.
|
|
233
|
-
Instruction: Read `.
|
|
234
|
-
Output: `.
|
|
233
|
+
Instruction: Read `.work/templates/delegates/researcher-stack.md` for full task instructions. Apply the project goal and milestone context provided above.
|
|
234
|
+
Output: `.work/research/STACK.md`
|
|
235
235
|
Return: Human-read structured summary to Orchestrator (300-500 tokens); full findings stay in the output artifact.
|
|
236
236
|
Guardrails: Max Agent Hops = 3.
|
|
237
237
|
</delegate>
|
|
238
238
|
|
|
239
239
|
<delegate>
|
|
240
240
|
Agent: FeaturesResearcher
|
|
241
|
-
Parallel: (use parallelization value from .
|
|
241
|
+
Parallel: (use parallelization value from .work/config.json)
|
|
242
242
|
Context: Project goal: [user's stated goal]. Milestone context: [greenfield|subsequent]. DO NOT share conversation history.
|
|
243
|
-
Instruction: Read `.
|
|
244
|
-
Output: `.
|
|
243
|
+
Instruction: Read `.work/templates/delegates/researcher-features.md` for full task instructions. Apply the project goal and milestone context provided above.
|
|
244
|
+
Output: `.work/research/FEATURES.md`
|
|
245
245
|
Return: Human-read structured summary to Orchestrator (300-500 tokens); full findings stay in the output artifact.
|
|
246
246
|
Guardrails: Max Agent Hops = 3.
|
|
247
247
|
</delegate>
|
|
248
248
|
|
|
249
249
|
<delegate>
|
|
250
250
|
Agent: ArchitectureResearcher
|
|
251
|
-
Parallel: (use parallelization value from .
|
|
251
|
+
Parallel: (use parallelization value from .work/config.json)
|
|
252
252
|
Context: Project goal: [user's stated goal]. Milestone context: [greenfield|subsequent]. DO NOT share conversation history.
|
|
253
|
-
Instruction: Read `.
|
|
254
|
-
Output: `.
|
|
253
|
+
Instruction: Read `.work/templates/delegates/researcher-architecture.md` for full task instructions. Apply the project goal and milestone context provided above.
|
|
254
|
+
Output: `.work/research/ARCHITECTURE.md`
|
|
255
255
|
Return: Human-read structured summary to Orchestrator (300-500 tokens); full findings stay in the output artifact.
|
|
256
256
|
Guardrails: Max Agent Hops = 3.
|
|
257
257
|
</delegate>
|
|
258
258
|
|
|
259
259
|
<delegate>
|
|
260
260
|
Agent: PitfallsResearcher
|
|
261
|
-
Parallel: (use parallelization value from .
|
|
261
|
+
Parallel: (use parallelization value from .work/config.json)
|
|
262
262
|
Context: Project goal: [user's stated goal]. Milestone context: [greenfield|subsequent]. DO NOT share conversation history.
|
|
263
|
-
Instruction: Read `.
|
|
264
|
-
Output: `.
|
|
263
|
+
Instruction: Read `.work/templates/delegates/researcher-pitfalls.md` for full task instructions. Apply the project goal and milestone context provided above.
|
|
264
|
+
Output: `.work/research/PITFALLS.md`
|
|
265
265
|
Return: Human-read structured summary to Orchestrator (300-500 tokens); full findings stay in the output artifact.
|
|
266
266
|
Guardrails: Max Agent Hops = 3.
|
|
267
267
|
</delegate>
|
|
@@ -269,7 +269,7 @@ Guardrails: Max Agent Hops = 3.
|
|
|
269
269
|
**After all 4 researchers complete**, synthesize based on `researchDepth`:
|
|
270
270
|
|
|
271
271
|
**If `researchDepth: "fast"`:** Synthesize inline.
|
|
272
|
-
You hold 4 human-read structured summaries. Write `.
|
|
272
|
+
You hold 4 human-read structured summaries. Write `.work/research/SUMMARY.md` directly using `.work/templates/research/summary.md`. Cross-reference the summaries. Do NOT spawn another agent.
|
|
273
273
|
|
|
274
274
|
**If `researchDepth: "balanced"` or `"deep"`:** Spawn synthesizer to read the full research files.
|
|
275
275
|
|
|
@@ -277,8 +277,8 @@ You hold 4 human-read structured summaries. Write `.planning/research/SUMMARY.md
|
|
|
277
277
|
Agent: ResearchSynthesizer
|
|
278
278
|
Parallel: false
|
|
279
279
|
Context: Researcher summaries returned above. DO NOT share conversation history.
|
|
280
|
-
Instruction: Read `.
|
|
281
|
-
Output: `.
|
|
280
|
+
Instruction: Read `.work/templates/delegates/researcher-synthesizer.md` for full task instructions.
|
|
281
|
+
Output: `.work/research/SUMMARY.md`
|
|
282
282
|
Return: Agent-mediated structured summary to Orchestrator (500-800 tokens); full synthesis stays in the output artifact.
|
|
283
283
|
Guardrails: Max Agent Hops = 2. Do not do new research — synthesize only.
|
|
284
284
|
</delegate>
|
|
@@ -288,7 +288,7 @@ Guardrails: Max Agent Hops = 2. Do not do new research — synthesize only.
|
|
|
288
288
|
Display key findings before moving to spec creation.
|
|
289
289
|
|
|
290
290
|
### Research Quality Gate — All of These Must Be True:
|
|
291
|
-
- [ ] All 4 specialist files written to `.
|
|
291
|
+
- [ ] All 4 specialist files written to `.work/research/`
|
|
292
292
|
- [ ] SUMMARY.md written with "Implications for Roadmap" section populated
|
|
293
293
|
- [ ] Negative claims verified with current web docs (not training data)
|
|
294
294
|
- [ ] Confidence levels assigned: verified | likely | uncertain
|
|
@@ -305,7 +305,7 @@ Before writing SPEC.md, define core Data Models/Typed Schemas. Multi-agent hando
|
|
|
305
305
|
<spec_creation>
|
|
306
306
|
After the subagent research completes, synthesize EVERYTHING into `SPEC.md`:
|
|
307
307
|
|
|
308
|
-
1. **Use the template** from `.
|
|
308
|
+
1. **Use the template** from `.work/templates/spec.md`.
|
|
309
309
|
2. **Requirements are testable**: "User can X" not "System does Y"
|
|
310
310
|
3. **Requirements have IDs**: `AUTH-01`, `DATA-02`, `UI-03`
|
|
311
311
|
4. **Requirements are ordered** by priority within each category
|
|
@@ -314,7 +314,7 @@ After the subagent research completes, synthesize EVERYTHING into `SPEC.md`:
|
|
|
314
314
|
7. **Typed Data Schemas**: explicitly define the core Data Models/Typed Schemas the project will use (e.g., `type UserProfile = { id: number; plan: 'free' | 'pro' }`). Multi-agent handoffs require typed schemas to pass reliable state; natural language instructions fail across agent handoffs. *SPEC.md defines WHAT, not HOW - do not include implementation tasks.*
|
|
315
315
|
8. **Done-When Verification Chain**: For EVERY requirement in the "Must Have (v1)" section, define a clear, verifiable `[Done-When: ...]` criterion. "User can log in" must become "User can log in [Done-When: Login form submits, JWT is received, and User is redirected to Dashboard]". No exceptions.
|
|
316
316
|
9. **Capability & Security Gates**: Handle per the `<capability_gates>` section at the end of this `<spec_creation>` block.
|
|
317
|
-
10. **Authorization Matrix (optional)**: For projects with multiple user roles or protected resources, create `.
|
|
317
|
+
10. **Authorization Matrix (optional)**: For projects with multiple user roles or protected resources, create `.work/AUTH_MATRIX.md` using the template at `.work/templates/auth-matrix.md`. The integration checker will use this matrix for systematic auth verification during milestone audits.
|
|
318
318
|
11. **ROADMAP phase status is initialized** with Phase 1 marked `[ ]` / not started using the roadmap template's phase-status language.
|
|
319
319
|
|
|
320
320
|
<capability_gates>
|
|
@@ -341,7 +341,7 @@ Do NOT proceed to roadmap creation until the developer explicitly approves.
|
|
|
341
341
|
**Commit**: `docs: initialize project spec`
|
|
342
342
|
</spec_creation>
|
|
343
343
|
|
|
344
|
-
**STOP. Spec creation is complete. Verify that `.
|
|
344
|
+
**STOP. Spec creation is complete. Verify that `.work/SPEC.md` exists on disk with the approved content before creating the roadmap. Do NOT create ROADMAP.md from memory — read the persisted SPEC.md as input.**
|
|
345
345
|
|
|
346
346
|
<roadmap_creation>
|
|
347
347
|
After `SPEC.md` is approved, you must create `ROADMAP.md`.
|
|
@@ -395,7 +395,7 @@ Do NOT proceed to planning until the developer explicitly approves.
|
|
|
395
395
|
</roadmap_creation>
|
|
396
396
|
|
|
397
397
|
<persistence>
|
|
398
|
-
MANDATORY: Both `.
|
|
398
|
+
MANDATORY: Both `.work/SPEC.md` and `.work/ROADMAP.md` must exist on disk before reporting completion.
|
|
399
399
|
|
|
400
400
|
If either file was not written (permissions issue, path problem), STOP and report the blocker to the user. Do NOT report success without persisted artifacts.
|
|
401
401
|
|
|
@@ -424,8 +424,8 @@ Report to the user what was accomplished, then present the next step:
|
|
|
424
424
|
|
|
425
425
|
---
|
|
426
426
|
**Completed:** Project initialization — created:
|
|
427
|
-
- `.
|
|
428
|
-
- `.
|
|
427
|
+
- `.work/SPEC.md` — living specification (requirements, constraints, decisions)
|
|
428
|
+
- `.work/ROADMAP.md` — phased execution plan with success criteria
|
|
429
429
|
|
|
430
430
|
**Next step:** `/gsdd-plan` — create a detailed plan for Phase 1
|
|
431
431
|
|
|
@@ -7,17 +7,17 @@ Scope boundary: you write a checkpoint file. You do not route, present status, o
|
|
|
7
7
|
</role>
|
|
8
8
|
|
|
9
9
|
<prerequisites>
|
|
10
|
-
`.
|
|
10
|
+
`.work/` must exist (from `npx -y gsdd-cli init`, or `gsdd init` when globally installed).
|
|
11
11
|
|
|
12
|
-
If `.
|
|
12
|
+
If `.work/` does not exist, stop and tell the user to run `npx -y gsdd-cli init` first.
|
|
13
13
|
</prerequisites>
|
|
14
14
|
|
|
15
15
|
<repo_root_helper_contract>
|
|
16
|
-
All `node .
|
|
16
|
+
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.
|
|
17
17
|
</repo_root_helper_contract>
|
|
18
18
|
|
|
19
19
|
<runtime_contract>
|
|
20
|
-
Use the `Runtime` type from `.
|
|
20
|
+
Use the `Runtime` type from `.work/SPEC.md`.
|
|
21
21
|
Infer runtime from the launching surface when obvious: `.claude/` -> `claude-code`, `.codex/` or Codex portable skill -> `codex-cli`, `.opencode/` -> `opencode`, otherwise `other`.
|
|
22
22
|
Checkpoints record `runtime` only — assurance does not apply to state snapshots.
|
|
23
23
|
</runtime_contract>
|
|
@@ -27,8 +27,8 @@ Checkpoints record `runtime` only — assurance does not apply to state snapshot
|
|
|
27
27
|
<detect_work>
|
|
28
28
|
Scan for active work in priority order:
|
|
29
29
|
|
|
30
|
-
1. **Active phase work** — look in `.
|
|
31
|
-
2. **Active quick task** — read `.
|
|
30
|
+
1. **Active phase work** — look in `.work/phases/` for directories containing a PLAN file but no SUMMARY file (execution started but not completed).
|
|
31
|
+
2. **Active quick task** — read `.work/quick/LOG.md` if it exists. Check the last entry: if its status is not `done`/`passed`, there is an incomplete quick task.
|
|
32
32
|
3. **Generic work** — if neither of the above, ask the user what they were working on.
|
|
33
33
|
|
|
34
34
|
If no active work is detected and the user confirms nothing is in progress, inform them there is nothing to pause and exit.
|
|
@@ -39,7 +39,7 @@ Store the detected work type as `$WORK_TYPE` (one of: `phase`, `quick`, `generic
|
|
|
39
39
|
<gather_state>
|
|
40
40
|
Build a draft checkpoint from artifact truth before asking the user to restate work. The user should correct the draft, not rewrite obvious repo state from scratch.
|
|
41
41
|
|
|
42
|
-
When available, run `node .
|
|
42
|
+
When available, run `node .work/bin/gsdd.mjs control-map --json` and use it as the draft's repo/worktree snapshot: canonical branch/HEAD, dirty tracked/untracked/ignored buckets, sibling/detached worktrees, stale annotations, planning drift, and recommended interventions. Include only a compact summary or pointer in `.work/.continue-here.md`; the checkpoint records resumability context, not a replacement for future computed repo truth.
|
|
43
43
|
|
|
44
44
|
Ask the user conversationally to fill in the gaps the artifacts cannot answer:
|
|
45
45
|
|
|
@@ -63,11 +63,11 @@ Question budget:
|
|
|
63
63
|
</gather_state>
|
|
64
64
|
|
|
65
65
|
<write_checkpoint>
|
|
66
|
-
Before writing the new checkpoint, run `node .
|
|
66
|
+
Before writing the new checkpoint, run `node .work/bin/gsdd.mjs file-op delete .work/.continue-here.bak --missing ok` to clear the prior session backup. This is cleanup-only and should no-op safely if the backup is absent.
|
|
67
67
|
|
|
68
68
|
When the current branch/worktree is known to be evidence-only, stale/spent, or otherwise not the next intended execution surface, say that explicitly in `<current_state>`, `<remaining_work>`, and `<anti_regression>`. Do not flatten evidence-only local state into the same continuity story as the next execution surface.
|
|
69
69
|
|
|
70
|
-
Write `.
|
|
70
|
+
Write `.work/.continue-here.md` with the following structure:
|
|
71
71
|
|
|
72
72
|
```markdown
|
|
73
73
|
---
|
|
@@ -117,13 +117,13 @@ runtime: $INFERRED_RUNTIME
|
|
|
117
117
|
</judgment>
|
|
118
118
|
```
|
|
119
119
|
|
|
120
|
-
The checkpoint is project-scoped (lives at `.
|
|
120
|
+
The checkpoint is project-scoped (lives at `.work/.continue-here.md`, not inside a phase directory) so resume always knows where to look.
|
|
121
121
|
</write_checkpoint>
|
|
122
122
|
|
|
123
|
-
**MANDATORY: `.
|
|
123
|
+
**MANDATORY: `.work/.continue-here.md` must exist on disk after writing. If the file was not created, STOP and report the failure. The entire purpose of this workflow is to persist context — a failed write means the pause did nothing.**
|
|
124
124
|
|
|
125
125
|
<advisory_git>
|
|
126
|
-
Read `.
|
|
126
|
+
Read `.work/config.json` for the `gitProtocol` section. If config.json cannot be read, skip git advice.
|
|
127
127
|
|
|
128
128
|
Suggest a WIP commit following the project's git conventions. Do not mandate it — the user decides whether and how to commit.
|
|
129
129
|
|
|
@@ -132,7 +132,7 @@ Example suggestion: "You may want to commit your current changes as a WIP before
|
|
|
132
132
|
|
|
133
133
|
<confirm>
|
|
134
134
|
Report to the user:
|
|
135
|
-
- Checkpoint location: `.
|
|
135
|
+
- Checkpoint location: `.work/.continue-here.md`
|
|
136
136
|
- Work type captured (phase/quick/generic)
|
|
137
137
|
- How to resume: run the `/gsdd-resume` workflow in the next session
|
|
138
138
|
</confirm>
|
|
@@ -142,7 +142,7 @@ Report to the user:
|
|
|
142
142
|
<success_criteria>
|
|
143
143
|
- [ ] Active work context detected (phase, quick, or generic)
|
|
144
144
|
- [ ] User provided missing context via conversation
|
|
145
|
-
- [ ] `.
|
|
145
|
+
- [ ] `.work/.continue-here.md` created with frontmatter, all 6 sections, and <judgment> block
|
|
146
146
|
- [ ] Advisory git suggestion presented (not mandated)
|
|
147
147
|
- [ ] User informed of checkpoint location and resume instructions
|
|
148
148
|
</success_criteria>
|
|
@@ -151,7 +151,7 @@ Report to the user:
|
|
|
151
151
|
Report to the user what was accomplished, then present the next step:
|
|
152
152
|
|
|
153
153
|
---
|
|
154
|
-
**Completed:** Session paused — created `.
|
|
154
|
+
**Completed:** Session paused — created `.work/.continue-here.md` (checkpoint file).
|
|
155
155
|
|
|
156
156
|
**Next step (next session):** `/gsdd-resume` — restore context and continue where you left off
|
|
157
157
|
|