gsdd-cli 0.19.0 → 0.19.2
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 +4 -3
- package/agents/approach-explorer.md +9 -0
- package/agents/executor.md +118 -39
- package/agents/planner.md +32 -3
- package/bin/adapters/claude.mjs +9 -7
- package/bin/adapters/opencode.mjs +9 -7
- package/bin/gsdd.mjs +4 -4
- package/bin/lib/evidence-contract.mjs +216 -3
- package/bin/lib/health-truth.mjs +26 -11
- package/bin/lib/health.mjs +88 -23
- package/bin/lib/init-runtime.mjs +2 -0
- package/bin/lib/lifecycle-preflight.mjs +418 -6
- package/bin/lib/lifecycle-state.mjs +9 -4
- package/bin/lib/phase.mjs +7 -2
- package/bin/lib/plan-constants.mjs +5 -0
- package/bin/lib/rendering.mjs +4 -0
- package/bin/lib/session-fingerprint.mjs +91 -14
- package/distilled/DESIGN.md +148 -18
- package/distilled/EVIDENCE-INDEX.md +29 -5
- package/distilled/templates/approach.md +40 -0
- package/distilled/templates/delegates/approach-explorer.md +3 -0
- package/distilled/templates/delegates/plan-checker.md +14 -4
- package/distilled/workflows/audit-milestone.md +29 -1
- package/distilled/workflows/complete-milestone.md +36 -23
- package/distilled/workflows/execute.md +35 -33
- package/distilled/workflows/new-project.md +28 -31
- package/distilled/workflows/plan.md +18 -16
- package/distilled/workflows/quick.md +10 -6
- package/distilled/workflows/verify.md +8 -8
- package/package.json +1 -1
|
@@ -20,7 +20,7 @@ When `autoAdvance: true`, this workflow runs non-interactively:
|
|
|
20
20
|
|
|
21
21
|
5. **Keep quality gates:** All quality checks in `<spec_creation>` and `<roadmap_creation>` still apply. Thoroughness is preserved; only user wait-points are removed.
|
|
22
22
|
|
|
23
|
-
6. **After completion:** Report what was created and any assumptions inferred from the brief. Do NOT auto-
|
|
23
|
+
6. **After completion:** Report what was created and any assumptions inferred from the brief. Do NOT auto-progress into plan, execute, verify, release, or delivery. The user or CI system must start any later lifecycle workflow explicitly.
|
|
24
24
|
|
|
25
25
|
All other sections (`<detect_mode>`, `<codebase_context>`, `<research>`, `<spec_creation>`, `<roadmap_creation>`, `<success_criteria>`) execute normally. Auto mode bypasses: the `<questioning>` section, both `<approval_gate>` blocks, the user question in `<project_principles>`, and the user question in `<capability_gates>`. All other workflow logic executes normally.
|
|
26
26
|
</auto_mode>
|
|
@@ -33,8 +33,8 @@ Before starting, read these files (if they exist):
|
|
|
33
33
|
4. Project root files: `package.json`, `README.md`, main entry point, `.gitignore`
|
|
34
34
|
5. `.planning/config.json` — The deterministic project settings. Key fields:
|
|
35
35
|
- `researchDepth`: balanced | fast | deep — controls research thoroughness
|
|
36
|
-
- `parallelization`: true | false
|
|
37
|
-
- `workflow.research`: true | false
|
|
36
|
+
- `parallelization`: true | false - whether to run delegate work in parallel when the platform supports it; when false, run the same delegates sequentially
|
|
37
|
+
- `workflow.research`: true | false - whether to do domain research before spec
|
|
38
38
|
- `workflow.planCheck`: true | false — whether plan-check agent runs later
|
|
39
39
|
- `workflow.verifier`: true | false — whether verifier runs after execution
|
|
40
40
|
- `modelProfile`: balanced | quality | budget — model selection hint
|
|
@@ -44,7 +44,6 @@ Before starting, read these files (if they exist):
|
|
|
44
44
|
</load_context>
|
|
45
45
|
|
|
46
46
|
<project_principles>
|
|
47
|
-
**(SOTA Insight: Derived from Spec-Kit)**
|
|
48
47
|
Before diving into technical specifications, establish the core governing principles of the project.
|
|
49
48
|
If `autoAdvance: true` in `.planning/config.json`, skip this question. Infer core principles
|
|
50
49
|
from the project brief (code quality signals, constraint language, scope decisions) and note
|
|
@@ -161,7 +160,7 @@ Before creating a spec, you MUST have clear answers to:
|
|
|
161
160
|
- **3-5 rounds minimum** for non-trivial projects
|
|
162
161
|
|
|
163
162
|
### Categorizing Requirements (Crucial)
|
|
164
|
-
As the user provides answers, you must mentally categorize the features they request
|
|
163
|
+
As the user provides answers, you must mentally categorize the features they request:
|
|
165
164
|
1. **Table Stakes**: Features users absolutely expect. Without them, your product feels broken (e.g., password reset).
|
|
166
165
|
2. **Differentiators**: Features that set this project apart from competitors.
|
|
167
166
|
3. **Out of Scope**: Explicit anti-requirements for v1 to prevent scope creep.
|
|
@@ -202,28 +201,27 @@ MANDATORY STEP. After the goal is clarified but BEFORE writing any specs.
|
|
|
202
201
|
|
|
203
202
|
**Check config first:** Read `.planning/config.json`.
|
|
204
203
|
- If `workflow.research: false` → skip this section entirely, go to `<spec_creation>`.
|
|
205
|
-
- If `researchDepth: "fast"`
|
|
206
|
-
- If `researchDepth: "balanced"` or `"deep"`
|
|
204
|
+
- If `researchDepth: "fast"` - use the same 4 specialists below, then synthesize `SUMMARY.md` inline. Faster and cheaper; acceptable for well-known domains.
|
|
205
|
+
- If `researchDepth: "balanced"` or `"deep"` - use the same 4 specialists below plus the synthesizer (default).
|
|
207
206
|
|
|
208
|
-
### Why
|
|
209
|
-
**(SOTA: Anthropic Agent Teams, OpenAI Multi-Agents — 90.2% performance improvement for complex research tasks)**
|
|
207
|
+
### Why Specialists, Not One Generalist
|
|
210
208
|
|
|
211
209
|
DO NOT research in this main thread — noisy intermediate output pollutes the context window.
|
|
212
210
|
DO NOT use a single generalist to write all research files — domain switching degrades quality.
|
|
213
211
|
|
|
214
212
|
Use the same 4 specialized researchers every time. The difference is execution order and synthesis mode.
|
|
215
|
-
- If `parallelization: true` and your platform supports parallel execution (`run_in_background=true`, async tasks, etc.)
|
|
216
|
-
- If `parallelization: false` or your platform lacks parallel execution
|
|
217
|
-
- If `researchDepth: "fast"`
|
|
218
|
-
- If `researchDepth: "balanced"` or `"deep"`
|
|
213
|
+
- If `parallelization: true` and your platform supports parallel execution (`run_in_background=true`, async tasks, etc.) - run all 4 simultaneously.
|
|
214
|
+
- If `parallelization: false` or your platform lacks parallel execution - run the same 4 researchers sequentially.
|
|
215
|
+
- If `researchDepth: "fast"` - synthesize inline after the 4 researcher outputs return.
|
|
216
|
+
- If `researchDepth: "balanced"` or `"deep"` - use the synthesizer delegate after the 4 researcher outputs are written.
|
|
219
217
|
|
|
220
218
|
|
|
221
219
|
```
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
220
|
+
Spawning 4 researchers...
|
|
221
|
+
-> Stack research -> .planning/research/STACK.md
|
|
222
|
+
-> Features research -> .planning/research/FEATURES.md
|
|
223
|
+
-> Architecture research -> .planning/research/ARCHITECTURE.md
|
|
224
|
+
-> Pitfalls research -> .planning/research/PITFALLS.md
|
|
227
225
|
```
|
|
228
226
|
|
|
229
227
|
Ensure `.planning/research/` directory exists before spawning.
|
|
@@ -234,7 +232,7 @@ Parallel: (use parallelization value from .planning/config.json)
|
|
|
234
232
|
Context: Project goal: [user's stated goal]. Milestone context: [greenfield|subsequent]. DO NOT share conversation history.
|
|
235
233
|
Instruction: Read `.planning/templates/delegates/researcher-stack.md` for full task instructions. Apply the project goal and milestone context provided above.
|
|
236
234
|
Output: `.planning/research/STACK.md`
|
|
237
|
-
Return: 3-5 sentence summary to Orchestrator.
|
|
235
|
+
Return: 3-5 sentence summary to Orchestrator; full findings stay in the output artifact.
|
|
238
236
|
Guardrails: Max Agent Hops = 3.
|
|
239
237
|
</delegate>
|
|
240
238
|
|
|
@@ -244,7 +242,7 @@ Parallel: (use parallelization value from .planning/config.json)
|
|
|
244
242
|
Context: Project goal: [user's stated goal]. Milestone context: [greenfield|subsequent]. DO NOT share conversation history.
|
|
245
243
|
Instruction: Read `.planning/templates/delegates/researcher-features.md` for full task instructions. Apply the project goal and milestone context provided above.
|
|
246
244
|
Output: `.planning/research/FEATURES.md`
|
|
247
|
-
Return: 3-5 sentence summary to Orchestrator.
|
|
245
|
+
Return: 3-5 sentence summary to Orchestrator; full findings stay in the output artifact.
|
|
248
246
|
Guardrails: Max Agent Hops = 3.
|
|
249
247
|
</delegate>
|
|
250
248
|
|
|
@@ -254,7 +252,7 @@ Parallel: (use parallelization value from .planning/config.json)
|
|
|
254
252
|
Context: Project goal: [user's stated goal]. Milestone context: [greenfield|subsequent]. DO NOT share conversation history.
|
|
255
253
|
Instruction: Read `.planning/templates/delegates/researcher-architecture.md` for full task instructions. Apply the project goal and milestone context provided above.
|
|
256
254
|
Output: `.planning/research/ARCHITECTURE.md`
|
|
257
|
-
Return: 3-5 sentence summary to Orchestrator.
|
|
255
|
+
Return: 3-5 sentence summary to Orchestrator; full findings stay in the output artifact.
|
|
258
256
|
Guardrails: Max Agent Hops = 3.
|
|
259
257
|
</delegate>
|
|
260
258
|
|
|
@@ -264,14 +262,14 @@ Parallel: (use parallelization value from .planning/config.json)
|
|
|
264
262
|
Context: Project goal: [user's stated goal]. Milestone context: [greenfield|subsequent]. DO NOT share conversation history.
|
|
265
263
|
Instruction: Read `.planning/templates/delegates/researcher-pitfalls.md` for full task instructions. Apply the project goal and milestone context provided above.
|
|
266
264
|
Output: `.planning/research/PITFALLS.md`
|
|
267
|
-
Return: 3-5 sentence summary to Orchestrator.
|
|
265
|
+
Return: 3-5 sentence summary to Orchestrator; full findings stay in the output artifact.
|
|
268
266
|
Guardrails: Max Agent Hops = 3.
|
|
269
267
|
</delegate>
|
|
270
268
|
|
|
271
269
|
**After all 4 researchers complete**, synthesize based on `researchDepth`:
|
|
272
270
|
|
|
273
271
|
**If `researchDepth: "fast"`:** Synthesize inline.
|
|
274
|
-
You hold 4
|
|
272
|
+
You hold 4 x 3-5 sentence summaries. Write `.planning/research/SUMMARY.md` directly using `.planning/templates/research/summary.md`. Cross-reference the summaries. Do NOT spawn another agent.
|
|
275
273
|
|
|
276
274
|
**If `researchDepth: "balanced"` or `"deep"`:** Spawn synthesizer to read the full research files.
|
|
277
275
|
|
|
@@ -281,7 +279,7 @@ Parallel: false
|
|
|
281
279
|
Context: Researcher summaries returned above. DO NOT share conversation history.
|
|
282
280
|
Instruction: Read `.planning/templates/delegates/researcher-synthesizer.md` for full task instructions.
|
|
283
281
|
Output: `.planning/research/SUMMARY.md`
|
|
284
|
-
Return: 5-7 bullet key findings to Orchestrator.
|
|
282
|
+
Return: 5-7 bullet key findings to Orchestrator; full synthesis stays in the output artifact.
|
|
285
283
|
Guardrails: Max Agent Hops = 2. Do not do new research — synthesize only.
|
|
286
284
|
</delegate>
|
|
287
285
|
|
|
@@ -293,7 +291,7 @@ Display key findings before moving to spec creation.
|
|
|
293
291
|
- [ ] All 4 specialist files written to `.planning/research/`
|
|
294
292
|
- [ ] SUMMARY.md written with "Implications for Roadmap" section populated
|
|
295
293
|
- [ ] Negative claims verified with current web docs (not training data)
|
|
296
|
-
- [ ] Confidence levels assigned:
|
|
294
|
+
- [ ] Confidence levels assigned: verified | likely | uncertain
|
|
297
295
|
|
|
298
296
|
**Commit**: `docs: add domain research`
|
|
299
297
|
</research>
|
|
@@ -301,7 +299,7 @@ Display key findings before moving to spec creation.
|
|
|
301
299
|
**STOP. Research is complete. Do NOT write any application code. Proceed to spec creation below. Your job now is to produce SPEC.md and ROADMAP.md — not to build the project.**
|
|
302
300
|
|
|
303
301
|
<data_schema_definition>
|
|
304
|
-
Before writing SPEC.md, define core Data Models/Typed Schemas
|
|
302
|
+
Before writing SPEC.md, define core Data Models/Typed Schemas. Multi-agent handoffs require typed schemas to pass reliable state. These schemas MUST be included in SPEC.md (see item 7 in `<spec_creation>` below). Also define Done-When verification criteria for every requirement (see item 8). *SPEC.md defines WHAT, not HOW - do not include implementation tasks.*
|
|
305
303
|
</data_schema_definition>
|
|
306
304
|
|
|
307
305
|
<spec_creation>
|
|
@@ -312,15 +310,14 @@ After the subagent research completes, synthesize EVERYTHING into `SPEC.md`:
|
|
|
312
310
|
3. **Requirements have IDs**: `AUTH-01`, `DATA-02`, `UI-03`
|
|
313
311
|
4. **Requirements are ordered** by priority within each category
|
|
314
312
|
5. **Out of Scope is populated** — includes things the developer explicitly said "not now" AND anti-features found in Research.
|
|
315
|
-
6. **Key Decisions are logged** — any choices made during questioning or dictated by the
|
|
316
|
-
7. **Typed Data Schemas
|
|
317
|
-
8. **Done-When Verification Chain
|
|
313
|
+
6. **Key Decisions are logged** — any choices made during questioning or dictated by the research.
|
|
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
|
+
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.
|
|
318
316
|
9. **Capability & Security Gates**: Handle per the `<capability_gates>` section at the end of this `<spec_creation>` block.
|
|
319
317
|
10. **Authorization Matrix (optional)**: For projects with multiple user roles or protected resources, create `.planning/AUTH_MATRIX.md` using the template at `.planning/templates/auth-matrix.md`. The integration checker will use this matrix for systematic auth verification during milestone audits.
|
|
320
318
|
11. **ROADMAP phase status is initialized** with Phase 1 marked `[ ]` / not started using the roadmap template's phase-status language.
|
|
321
319
|
|
|
322
320
|
<capability_gates>
|
|
323
|
-
**(SOTA Insight: Derived from OpenFang - "16 Security Systems & Capability Gates")**
|
|
324
321
|
Before finishing SPEC.md, explicitly define what the agents are NOT allowed to do automatically without human approval.
|
|
325
322
|
If `autoAdvance: true`, skip this question. Add a deferred placeholder to SPEC.md:
|
|
326
323
|
"## Capability & Security Gates\n_Deferred — auto mode cannot elicit gate preferences; requires explicit review before production deployment._"
|
|
@@ -410,7 +407,7 @@ Init is DONE when ALL of these are true:
|
|
|
410
407
|
|
|
411
408
|
- [ ] Codebase audit completed (brownfield) OR greenfield confirmed
|
|
412
409
|
- [ ] Developer was questioned in depth (3+ rounds for non-trivial projects) — [interactive only; skip when autoAdvance: true]
|
|
413
|
-
- [ ] Research subagent spawned and
|
|
410
|
+
- [ ] Research subagent spawned and domain patterns retrieved
|
|
414
411
|
- [ ] `SPEC.md` exists with testable requirements, out-of-scope, and current state
|
|
415
412
|
- [ ] SPEC.md was reviewed and approved by the developer — [interactive only; skip when autoAdvance: true]
|
|
416
413
|
- [ ] ROADMAP.md exists with phases, success criteria, and requirement mapping
|
|
@@ -22,6 +22,14 @@ Identify the target phase: the first phase with status `[ ]` or `[-]` in `ROADMA
|
|
|
22
22
|
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.
|
|
23
23
|
</repo_root_helper_contract>
|
|
24
24
|
|
|
25
|
+
<lifecycle_preflight>
|
|
26
|
+
Before writing or rewriting phase planning artifacts, run:
|
|
27
|
+
|
|
28
|
+
- `node .planning/bin/gsdd.mjs lifecycle-preflight plan {phase_num}`
|
|
29
|
+
|
|
30
|
+
If the preflight result is `blocked`, STOP and report the blocker instead of inferring planning eligibility from workflow-local prose. Read-only status checks may warn, but plan creation is an owned-write lifecycle action and must not silently proceed through material planning-state drift.
|
|
31
|
+
</lifecycle_preflight>
|
|
32
|
+
|
|
25
33
|
<integration_surface_check>
|
|
26
34
|
Before planning roadmap work, inspect the live integration surface separately from checkpoint or planning artifacts:
|
|
27
35
|
- current branch name
|
|
@@ -411,18 +419,15 @@ notes: [What the checker actually validated or why it was skipped]
|
|
|
411
419
|
|
|
412
420
|
<approach_exploration>
|
|
413
421
|
### When This Runs
|
|
414
|
-
|
|
415
422
|
Check `.planning/config.json` for `workflow.discuss`:
|
|
416
423
|
- If `workflow.discuss: false` (or key missing): skip this section, go to `<goal_backward_planning>`. Note `reduced_alignment` in the orchestration summary.
|
|
417
424
|
- If `workflow.discuss: true`: mandatory before planning.
|
|
418
425
|
|
|
419
426
|
### Check for Existing APPROACH.md
|
|
420
|
-
|
|
421
427
|
Check if `{phase_dir}/{padded_phase}-APPROACH.md` exists.
|
|
422
|
-
|
|
423
428
|
**If exists:**
|
|
424
429
|
Offer the user a choice:
|
|
425
|
-
- "Use existing" — load decisions from APPROACH.md,
|
|
430
|
+
- "Use existing" — load decisions from APPROACH.md, validate the alignment proof below, then continue to `<goal_backward_planning>` only if the proof is valid
|
|
426
431
|
- "Update it" — run the approach explorer to revise decisions
|
|
427
432
|
- "View it" — display APPROACH.md contents, then offer "Use existing" / "Update"
|
|
428
433
|
|
|
@@ -430,9 +435,7 @@ Offer the user a choice:
|
|
|
430
435
|
Run the approach explorer.
|
|
431
436
|
|
|
432
437
|
### Running the Approach Explorer
|
|
433
|
-
|
|
434
438
|
**Primary path — inline conversation with research subagents:**
|
|
435
|
-
|
|
436
439
|
The conversation with the user runs inline in the main context. For each technical gray area, a read-only research subagent is spawned to isolate heavy codebase and documentation reads, returning only compressed summaries.
|
|
437
440
|
|
|
438
441
|
1. Load context: read ONLY locked decisions from `.planning/SPEC.md` and the target phase goal/requirements from `.planning/ROADMAP.md`.
|
|
@@ -458,7 +461,7 @@ The conversation with the user runs inline in the main context. For each technic
|
|
|
458
461
|
**Native agent optimization:**
|
|
459
462
|
|
|
460
463
|
If your runtime provides an interactive `gsdd-approach-explorer` agent:
|
|
461
|
-
- Invoke it with: target phase goal, requirement IDs, locked decisions, phase research (if exists), relevant codebase files
|
|
464
|
+
- Invoke it with: target phase goal, requirement IDs, project config from `.planning/config.json` (especially `workflow.discuss`), locked decisions, phase research (if exists), relevant codebase files
|
|
462
465
|
- The native agent runs the full exploration in its own context window
|
|
463
466
|
- This is an optimization — the output (APPROACH.md) is identical to the primary path
|
|
464
467
|
|
|
@@ -471,8 +474,8 @@ If neither the primary path nor native agent is available (e.g., the runtime can
|
|
|
471
474
|
- Explicitly report `reduced_alignment` — the user did not get full research-backed exploration
|
|
472
475
|
|
|
473
476
|
### Using APPROACH.md Decisions
|
|
474
|
-
|
|
475
477
|
After approach exploration completes (or existing APPROACH.md is loaded):
|
|
478
|
+
- If `workflow.discuss: true`, validate that APPROACH.md records `alignment_status: user_confirmed` or `alignment_status: approved_skip` with the canonical fields `alignment_method`, `user_confirmed_at`, `explicit_skip_approved`, `skip_scope`, `skip_rationale`, and `confirmed_decisions` before goal-backward planning begins. Stop and update the APPROACH artifact if proof is missing, unknown, agent-discretion-only, or based only on agent "No questions needed" judgment.
|
|
476
479
|
- Treat decisions from APPROACH.md as locked constraints, same priority as `.planning/SPEC.md` decisions
|
|
477
480
|
- "Agent's Discretion" items from APPROACH.md give the planner flexibility — do not treat them as locked
|
|
478
481
|
- Thread the APPROACH.md file path to both the planner prompt and the plan-checker prompt
|
|
@@ -485,11 +488,9 @@ The approach explorer's full role contract is at `.planning/templates/roles/appr
|
|
|
485
488
|
|
|
486
489
|
<plan_check_orchestration>
|
|
487
490
|
### How Plan Checking Works
|
|
488
|
-
|
|
489
491
|
After the planner produces a draft plan, an independent checker reviews it in fresh context. The checker does not inherit the planner's hidden reasoning; it treats the plan as an untrusted draft.
|
|
490
492
|
|
|
491
493
|
### What The Checker Verifies
|
|
492
|
-
|
|
493
494
|
1. `requirement_coverage` - every phase requirement is covered by at least one concrete task
|
|
494
495
|
2. `task_completeness` - every task has files, action, verify, and done fields; verify quality sub-checks ensure at least one runnable command per task, flag slow or watch-mode verification, and check test file ordering
|
|
495
496
|
3. `dependency_correctness` - ordering, dependencies, and plan structure are coherent
|
|
@@ -503,20 +504,21 @@ After the planner produces a draft plan, an independent checker reviews it in fr
|
|
|
503
504
|
11. `escalation_integrity` - stop-and-challenge triggers and approval gates are present where side effects or ambiguity warrant them
|
|
504
505
|
12. `closure_honesty` - closure claim limit prevents the plan from overclaiming what verification can prove
|
|
505
506
|
13. `high_leverage_review` - high-leverage surfaces and second-pass obligations are recorded honestly
|
|
506
|
-
14. `approach_alignment` - when APPROACH.md exists, plans implement the chosen approaches, not alternatives. Blocker if plan contradicts an explicit user choice. Warning if plan drifts from recommendation without justification.
|
|
507
|
+
14. `approach_alignment` - when APPROACH.md exists, plans implement the chosen approaches, not alternatives. Blocker if plan contradicts an explicit user choice. Warning if plan drifts from recommendation without justification. When `workflow.discuss: true`, missing, proofless, agent-discretion-only, or invalid APPROACH.md is a blocker before a plan can be accepted.
|
|
507
508
|
### Invoking the Checker
|
|
508
|
-
1. If `.planning/config.json` has `workflow.planCheck: false`, skip the independent checker. Perform the planner self-check below and report `reduced_assurance`.
|
|
509
|
+
1. If `.planning/config.json` has `workflow.planCheck: false`, skip the independent checker. Perform the planner self-check below and report `reduced_assurance`. This does not skip the earlier alignment-proof gate when `workflow.discuss: true`.
|
|
509
510
|
2. If plan checking is enabled, check if your runtime provides a `gsdd-plan-checker` agent.
|
|
510
511
|
3. If a native checker agent is available, invoke it in a fresh context with only these explicit inputs:
|
|
511
512
|
- target phase goal and requirement IDs
|
|
512
513
|
- relevant locked decisions / deferred items from `.planning/SPEC.md`
|
|
514
|
+
- project config from `.planning/config.json`, especially `workflow.discuss` and `workflow.planCheck`
|
|
513
515
|
- approach decisions from `.planning/phases/*-APPROACH.md` (if exists)
|
|
514
516
|
- relevant phase research file(s)
|
|
515
517
|
- produced `.planning/phases/*-PLAN.md` file(s)
|
|
516
518
|
4. Require the checker to return a single JSON object:
|
|
517
519
|
```json
|
|
518
520
|
{
|
|
519
|
-
"status": "
|
|
521
|
+
"status": "issues_found",
|
|
520
522
|
"summary": "One sentence overall assessment",
|
|
521
523
|
"issues": [
|
|
522
524
|
{
|
|
@@ -530,10 +532,10 @@ After the planner produces a draft plan, an independent checker reviews it in fr
|
|
|
530
532
|
]
|
|
531
533
|
}
|
|
532
534
|
```
|
|
533
|
-
Status must be either "passed" or "issues_found".
|
|
535
|
+
Status must be either "passed" or "issues_found". Use "passed" only when "issues": []; any blocker or warning must use "issues_found".
|
|
534
536
|
5. If the checker returns `passed`, finish and summarize.
|
|
535
537
|
6. If the checker returns `issues_found`, revise the existing plan files only where needed, then invoke the checker again.
|
|
536
|
-
7. Maximum 3 checker cycles total. If blockers remain after cycle 3, stop and escalate to the user instead of pretending the plan is ready.
|
|
538
|
+
7. Maximum 3 checker cycles total. If any blockers or warnings remain after cycle 3, stop and escalate to the user instead of pretending the plan is ready.
|
|
537
539
|
8. If no native checker agent is available in your runtime, perform the planner self-check below and explicitly report `reduced_assurance` rather than claiming an independent checker ran.
|
|
538
540
|
When the checker outcome is finalized, write the result into the plan artifact:
|
|
539
541
|
- checker ran in same runtime or planner self-check only -> set frontmatter `assurance: self_checked`
|
|
@@ -553,7 +555,7 @@ The checker returns structured JSON feedback with specific issues, severities, a
|
|
|
553
555
|
|
|
554
556
|
### When To Escalate
|
|
555
557
|
|
|
556
|
-
If blockers remain after 3 checker cycles, the orchestrator stops and escalates to the user. It does not pretend the plan is ready.
|
|
558
|
+
If any blockers or warnings remain after 3 checker cycles, the orchestrator stops and escalates to the user. It does not pretend the plan is ready.
|
|
557
559
|
</plan_check_orchestration>
|
|
558
560
|
|
|
559
561
|
<plan_self_check>
|
|
@@ -169,9 +169,9 @@ Read `.planning/config.json`.
|
|
|
169
169
|
If the checker returns `issues_found` with blockers and this is the first cycle:
|
|
170
170
|
1. Send the issue list back to the planner for targeted revision of the plan file.
|
|
171
171
|
2. Re-run the checker once more.
|
|
172
|
-
3. If blockers remain after 1 revision cycle, store `$CHECKER_ISSUES` for display in the plan preview
|
|
172
|
+
3. If blockers remain after 1 revision cycle, store `$CHECKER_ISSUES` for display in the plan preview and set `$RISK_ACCEPTANCE_REQUIRED=true`. Do not execute from default Enter; the user must explicitly accept the known risk in Step 3.7.
|
|
173
173
|
|
|
174
|
-
If the checker returns `passed`, or `workflow.planCheck` is false, `$CHECKER_ISSUES` is empty
|
|
174
|
+
If the checker returns `passed`, or `workflow.planCheck` is false, `$CHECKER_ISSUES` is empty and `$RISK_ACCEPTANCE_REQUIRED=false`.
|
|
175
175
|
|
|
176
176
|
---
|
|
177
177
|
|
|
@@ -222,14 +222,18 @@ If `$CHECKER_ISSUES` is non-empty, append:
|
|
|
222
222
|
Plan check issues: {$CHECKER_ISSUES}
|
|
223
223
|
```
|
|
224
224
|
|
|
225
|
-
Present options
|
|
226
|
-
- If `$
|
|
227
|
-
-
|
|
225
|
+
Present options:
|
|
226
|
+
- If `$CHECKER_ISSUES` is non-empty: `[type "proceed despite issues" to execute / edit description / abort]`
|
|
227
|
+
- Otherwise if `$SCOPE_WARNING` is empty: `[Enter to proceed / edit description / abort]`
|
|
228
|
+
- Otherwise if `$SCOPE_WARNING` contains `/gsdd-new-project`: `[Enter to proceed / switch to /gsdd-new-project / edit description / abort]`
|
|
228
229
|
- Otherwise if `$SCOPE_WARNING` contains `/gsdd-map-codebase`: `[Enter to proceed / switch to /gsdd-map-codebase / edit description / abort]`
|
|
229
230
|
- Otherwise if `$SCOPE_WARNING` is non-empty: `[Enter to proceed / switch to /gsdd-plan / edit description / abort]`
|
|
230
231
|
|
|
232
|
+
Default-yes applies only when `$CHECKER_ISSUES` is empty. When unresolved checker blockers remain, pressing Enter must not execute; repeat the issues and ask for `proceed despite issues`, `edit description`, or `abort`.
|
|
233
|
+
|
|
231
234
|
Handle response:
|
|
232
|
-
- **Enter (or "yes"):** proceed to Step 4.
|
|
235
|
+
- **Enter (or "yes") when `$CHECKER_ISSUES` is empty:** proceed to Step 4.
|
|
236
|
+
- **"proceed despite issues" when `$CHECKER_ISSUES` is non-empty:** proceed to Step 4 and record the explicit risk acceptance in the quick summary.
|
|
233
237
|
- **"edit description":** clean up the task directory, then return to Step 1 with `$DESCRIPTION` pre-filled as the starting point.
|
|
234
238
|
- **"switch to /gsdd-new-project":** clean up the task directory, then stop quick workflow and report: "Use `/gsdd-new-project` to define or intentionally widen the work into full lifecycle planning. Task description: {$DESCRIPTION}"
|
|
235
239
|
- **"switch to /gsdd-map-codebase":** clean up the task directory, then stop quick workflow and report: "Use `/gsdd-map-codebase` for a deeper brownfield baseline before quick work. Task description: {$DESCRIPTION}"
|
|
@@ -117,12 +117,12 @@ Apply the shared `verify` matrix:
|
|
|
117
117
|
| delivery_posture | required evidence | recommended evidence | cannot carry closure alone |
|
|
118
118
|
| -------------------- | ----------------- | -------------------------- | -------------------------- |
|
|
119
119
|
| `repo_only` | `code` | `test` | `human`, `delivery` |
|
|
120
|
-
| `delivery_sensitive` | `code`, `runtime` | `test`, `
|
|
120
|
+
| `delivery_sensitive` | `code`, `runtime`, `delivery` | `test`, `human` | `code`, `human` |
|
|
121
121
|
|
|
122
122
|
Rules:
|
|
123
123
|
- repo-only work must not invent `runtime` or `delivery` proof just to satisfy a template
|
|
124
|
-
- delivery-sensitive closure must not pass on prose, `code`-only inspection, or `human` confirmation without the required `runtime` evidence
|
|
125
|
-
- `human` evidence supports ambiguous or visual outcomes; it does not replace required `code` or `
|
|
124
|
+
- delivery-sensitive closure must not pass on prose, `code`-only inspection, or `human` confirmation without the required `runtime` and `delivery` evidence
|
|
125
|
+
- `human` evidence supports ambiguous or visual outcomes; it does not replace required `code`, `runtime`, or `delivery` evidence
|
|
126
126
|
- if a required evidence kind cannot be collected, record it in `missing_evidence`; route purely human-observable follow-up to `human_verification` only when the blocking runtime/delivery requirement is already satisfied
|
|
127
127
|
|
|
128
128
|
Note: this step does NOT replace levels 1–3. An artifact can satisfy the evidence-kind requirement and still fail Level 2 (substantive) or Level 3 (wired). Both checks must run.
|
|
@@ -247,10 +247,10 @@ status: gaps_found
|
|
|
247
247
|
score: 2/3 must-haves verified
|
|
248
248
|
delivery_posture: delivery_sensitive
|
|
249
249
|
evidence_contract:
|
|
250
|
-
required_kinds: [code, runtime]
|
|
251
|
-
recommended_kinds: [test,
|
|
250
|
+
required_kinds: [code, runtime, delivery]
|
|
251
|
+
recommended_kinds: [test, human]
|
|
252
252
|
observed_kinds: [code]
|
|
253
|
-
missing_kinds: [runtime]
|
|
253
|
+
missing_kinds: [runtime, delivery]
|
|
254
254
|
re_verification:
|
|
255
255
|
previous_status: gaps_found
|
|
256
256
|
previous_score: 1/3
|
|
@@ -262,9 +262,9 @@ re_verification:
|
|
|
262
262
|
gaps:
|
|
263
263
|
- truth: "Users can create a user from the page"
|
|
264
264
|
status: failed
|
|
265
|
-
required_evidence: [code, runtime]
|
|
265
|
+
required_evidence: [code, runtime, delivery]
|
|
266
266
|
observed_evidence: [code]
|
|
267
|
-
missing_evidence: [runtime]
|
|
267
|
+
missing_evidence: [runtime, delivery]
|
|
268
268
|
severity: blocker # blocker = required proof absent; warning = artifact missing but proof exists via other means
|
|
269
269
|
reason: "Form submits, but route returns placeholder data"
|
|
270
270
|
artifacts:
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "gsdd-cli",
|
|
3
|
-
"version": "0.19.
|
|
3
|
+
"version": "0.19.2",
|
|
4
4
|
"description": "Workspine — a repo-native delivery spine for long-horizon AI-assisted work, with directly validated support for Claude Code, Codex CLI, and OpenCode, published as gsdd-cli.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|