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
|
@@ -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 .
|
|
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
|
-
`.
|
|
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 `.
|
|
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 .
|
|
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 .
|
|
28
|
-
- If you recommend a next step that crosses a lifecycle boundary, the downstream mutating workflow must rerun its own `node .
|
|
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 `.
|
|
37
|
-
2. **If `.
|
|
38
|
-
|
|
39
|
-
|
|
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 `.
|
|
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 `.
|
|
50
|
-
- If `.
|
|
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 `.
|
|
54
|
-
- `active_brownfield_change` — `.
|
|
55
|
-
- `between_milestones` — `.
|
|
56
|
-
- `codebase_only` — `.
|
|
57
|
-
- `quick_lane` — `.
|
|
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 `.
|
|
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 `.
|
|
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 `.
|
|
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 `.
|
|
93
|
-
- check for the matching archived milestone audit artifact for that same milestone/version (for example `.
|
|
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 `.
|
|
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 `.
|
|
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 `.
|
|
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 `.
|
|
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 `.
|
|
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 `.
|
|
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 `.
|
|
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
|
-
- `.
|
|
270
|
-
- `.
|
|
271
|
-
- `.
|
|
272
|
-
- `.
|
|
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 `.
|
|
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 `.
|
|
281
|
-
Also available: inspect `.
|
|
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 .
|
|
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 `.
|
|
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
|
-
`.
|
|
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 `.
|
|
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 .
|
|
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 `.
|
|
41
|
-
2. Scan `.
|
|
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 `.
|
|
44
|
-
5. If `.
|
|
45
|
-
6. If `.
|
|
46
|
-
7. If `.
|
|
47
|
-
8. **Session-boundary fallback:** If `.
|
|
48
|
-
9. Inspect the live branch/worktree surface separately from checkpoint or planning artifacts. Run `node .
|
|
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 `.
|
|
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 `.
|
|
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 `.
|
|
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: `.
|
|
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 `
|
|
122
|
-
-
|
|
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
|
|
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:** `.
|
|
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 `.
|
|
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 `.
|
|
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 `.
|
|
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: `.
|
|
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
|
|
166
|
-
- Skip: `key_link_completeness`, `context_compliance`,
|
|
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 `.
|
|
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 `.
|
|
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 `.
|
|
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: `.
|
|
263
|
-
- Project conventions: `.
|
|
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: `.
|
|
272
|
-
- If the quick plan
|
|
273
|
-
- For live
|
|
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:** `.
|
|
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 `.
|
|
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 `.
|
|
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 `.
|
|
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: `.
|
|
299
|
-
- Summary: `.
|
|
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: `.
|
|
303
|
+
- Write report to: `.work/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-VERIFICATION.md`
|
|
305
304
|
|
|
306
|
-
**Output:** `.
|
|
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 `.
|
|
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 `.
|
|
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
|
-
- [ ] `.
|
|
343
|
-
- [ ] Task directory created at `.
|
|
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
|
-
- `.
|
|
362
|
-
- `.
|
|
363
|
-
- `.
|
|
364
|
-
- Updated `.
|
|
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
|
-
`.
|
|
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 .
|
|
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 `.
|
|
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 .
|
|
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 .
|
|
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 `.
|
|
46
|
-
2. **If `.
|
|
47
|
-
|
|
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 `.
|
|
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 `.
|
|
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 `.
|
|
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 `.
|
|
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 `.
|
|
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 `.
|
|
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 `.
|
|
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 `.
|
|
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 `.
|
|
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 `.
|
|
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 `.
|
|
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 (`.
|
|
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 .
|
|
331
|
-
2. After the copy succeeds, run `node .
|
|
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.
|