gsdd-cli 0.1.0 → 0.3.1

package/distilled/templates/delegates/plan-checker.md

@@ -5,6 +5,7 @@ You are the fresh-context plan checker for `/gsdd:plan`.
 Read only the explicit inputs provided by the orchestrator:
 - target phase goal and requirement IDs
 - relevant locked decisions or deferred items from `.planning/SPEC.md`
+- approach decisions from `.planning/phases/*-APPROACH.md` (if provided)
 - any relevant phase research file
 - the produced `.planning/phases/*-PLAN.md` file(s)
 
@@ -21,6 +22,15 @@ Verify these dimensions:
 - `scope_sanity`: plans are sized so an executor can complete them without context collapse
 - `must_have_quality`: success criteria and must-haves are specific, observable, and reflected in tasks
 - `context_compliance`: locked decisions are honored and deferred ideas stay out of scope
+- `goal_achievement`: does the plan, if executed perfectly, actually achieve the stated phase goal? Check:
+  - **Goal addressed?** Compare the phase goal statement to the plan's collective task outputs. Would successful completion of all tasks deliver the goal? If the goal says "users can authenticate" but tasks only set up database schema → `blocker`.
+  - **Success criteria reachable?** Are the phase success criteria from ROADMAP.md achievable through the planned tasks? Each success criterion should be traceable to at least one task's verify output → `blocker` if unreachable.
+  - **Outcome observable?** After execution, could a human or automated check confirm the goal was met? Plans that produce only internal artifacts with no user-visible or testable outcome → `warning`.
+- `approach_alignment`: when APPROACH.md is provided, verify that plan tasks implement the chosen approaches from the user's decisions. Check:
+  - **Chosen honored?** Does each plan task align with the approach chosen in APPROACH.md for its gray area? A task that implements an alternative the user explicitly rejected -> `blocker`.
+  - **Discretion respected?** "Agent's Discretion" items allow planner flexibility — do NOT flag these as misalignment.
+  - **Deferred excluded?** Deferred ideas from APPROACH.md must not appear in plan tasks -> `blocker` if found.
+  - If no APPROACH.md was provided, skip this dimension entirely.
 
 Return JSON only as a single object with this shape:
 
@@ -30,7 +40,7 @@ Return JSON only as a single object with this shape:
   "summary": "One sentence overall assessment",
   "issues": [
     {
-      "dimension": "requirement_coverage",
+      "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance | goal_achievement | approach_alignment",
       "severity": "blocker",
       "description": "What is wrong",
       "plan": "01-PLAN",

package/distilled/workflows/audit-milestone.md

@@ -160,6 +160,8 @@ Plus full markdown report body with tables for requirements, phases, integration
 - `gaps_found` - critical blockers exist (unsatisfied requirements, unprotected sensitive flows, broken flows, or missing verifications)
 - `tech_debt` - no blockers but accumulated deferred items need review
 
+**MANDATORY: The milestone audit report must exist at `.planning/v{version}-MILESTONE-AUDIT.md` on disk before presenting results. If the file was not written, STOP and report the write failure. Do NOT present audit results from conversation context alone — this is the highest-cost artifact to regenerate.**
+
 ## 7. Present Results
 
 Route by audit status:

package/distilled/workflows/map-codebase.md

@@ -160,13 +160,18 @@ These 4 documents are consumed by downstream GSDD workflows:
 
 After all mappers complete, verify:
 
-- [ ] All 4 documents exist in `.planning/codebase/`
-- [ ] No document is empty or trivially short (each should have substantive content)
-- [ ] Each document contains actual file path references (backtick-formatted)
-
-If any mapper failed, note the failure and inform the user which documents need manual completion.
+- [ ] All 4 documents exist in `.planning/codebase/` (L1: exists)
+- [ ] No document is empty or trivially short — each must exceed 20 non-empty lines (L2: substantive)
+- [ ] Each document contains actual file path references in backtick format — not generic advice (L2: specificity)
+- [ ] STACK.md names at least 2 concrete technologies with version information (L2: specificity)
+- [ ] ARCHITECTURE.md references at least 1 specific directory or module path (L2: specificity)
+- [ ] No document is a carbon copy of another — each covers a distinct dimension (L2: non-duplicate)
+
+If any check fails, note the specific failure and inform the user which documents need re-mapping or manual completion.
 </validation>
 
+**MANDATORY: All 4 codebase documents must exist on disk before proceeding to security scan or commit. If any document is missing, STOP and report which mapper(s) failed. Do NOT proceed to `<secrets_scan>` with incomplete output.**
+
 <secrets_scan>
 ### 5. Security Scan (Mandatory Before Commit)
 

package/distilled/workflows/new-project.md

@@ -282,26 +282,9 @@ Display key findings before moving to spec creation.
 **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.**
 
 <data_schema_definition>
-**(SOTA Insight: Derived from GitHub Blog - "Multi-agent workflows often fail")**
-Multi-agent systems require Typed Schemas to pass reliable state. Natural language instructions fail across agent handoffs.
-Before writing the final SPEC.md, explicitly define the core Data Models/Typed Schemas the project will use (e.g., `type UserProfile = { id: number; plan: 'free' | 'pro' }`).
-These strict schemas MUST be included in the `SPEC.md` to prevent agent hallucination during the implementation phases.
-6. **Typed Data Schemas**: Add the strict data models defined earlier.
-7. **Done-When Verification Chain (SOTA Insight from Cyanluna)**: For EVERY single requirement in the "Must Have (v1)" section, you MUST define a clear, verifiable `[Done-When: ...]` criteria. Vague requirements like "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.
-
-*DO NOT include implementation tasks here. SPEC.md defines WHAT, not HOW.*
+Before writing SPEC.md, define core Data Models/Typed Schemas *(SOTA: GitHub Blog — "Multi-agent workflows often fail")*. Multi-agent systems 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.*
 </data_schema_definition>
 
-<capability_gates>
-**(SOTA Insight: Derived from OpenFang - "16 Security Systems & Capability Gates")**
-Before finishing SPEC.md, explicitly define what the agents are NOT allowed to do automatically without human approval.
-If `autoAdvance: true`, skip this question. Add a deferred placeholder to SPEC.md:
-"## Capability & Security Gates\n_Deferred — auto mode cannot elicit gate preferences; requires explicit review before production deployment._"
-Otherwise:
-Ask the user: "Are there any destructive actions, purchases, or external API calls that should require mandatory human approval (Capability Gates)?"
-Add these into the new `## Capability & Security Gates` section of the SPEC.md.
-</capability_gates>
-
 <spec_creation>
 After the subagent research completes, synthesize EVERYTHING into `SPEC.md`:
 
@@ -311,9 +294,21 @@ After the subagent research completes, synthesize EVERYTHING into `SPEC.md`:
 4. **Requirements are ordered** by priority within each category
 5. **Out of Scope is populated** — includes things the developer explicitly said "not now" AND anti-features found in Research.
 6. **Key Decisions are logged** — any choices made during questioning or dictated by the SOTA research.
-7. **Capability & Security Gates are handled explicitly** — define concrete human-in-the-loop triggers in interactive mode, or add the deferred review placeholder in auto mode so the security decision is visible rather than silently omitted.
-8. **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.
-9. **Current State is set** to Phase 1, Status: Not started.
+7. **Typed Data Schemas** *(SOTA: GitHub Blog — "Multi-agent workflows often fail")*: explicitly define the core Data Models/Typed Schemas the project will use (e.g., `type UserProfile = { id: number; plan: 'free' | 'pro' }`). Multi-agent systems 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.*
+8. **Done-When Verification Chain** *(SOTA: Cyanluna)*: 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.
+9. **Capability & Security Gates**: Handle per the `<capability_gates>` section below.
+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.
+11. **Current State is set** to Phase 1, Status: Not started.
+
+<capability_gates>
+**(SOTA Insight: Derived from OpenFang - "16 Security Systems & Capability Gates")**
+Before finishing SPEC.md, explicitly define what the agents are NOT allowed to do automatically without human approval.
+If `autoAdvance: true`, skip this question. Add a deferred placeholder to SPEC.md:
+"## Capability & Security Gates\n_Deferred — auto mode cannot elicit gate preferences; requires explicit review before production deployment._"
+Otherwise:
+Ask the user: "Are there any destructive actions, purchases, or external API calls that should require mandatory human approval (Capability Gates)?"
+Add these into the `## Capability & Security Gates` section of the SPEC.md.
+</capability_gates>
 
 ### Quality Check Before Presenting
 - [ ] Can I explain the core value in one sentence?
@@ -331,6 +326,8 @@ Do NOT proceed to roadmap creation until the developer explicitly approves.
 **Commit**: `docs: initialize project spec`
 </spec_creation>
 
+**STOP. Spec creation is complete. Verify that `.planning/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.**
+
 <roadmap_creation>
 After `SPEC.md` is approved, you must create `ROADMAP.md`.
 Since you are an Orchestrator with fresh context, you DO NOT need to spawn a subagent for this—write it yourself directly, retaining full thoroughness.
@@ -382,6 +379,14 @@ Do NOT proceed to planning until the developer explicitly approves.
 **Commit**: `docs: create project roadmap`
 </roadmap_creation>
 
+<persistence>
+MANDATORY: Both `.planning/SPEC.md` and `.planning/ROADMAP.md` must exist on disk before reporting completion.
+
+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.
+
+These files are consumed by every downstream workflow. Artifacts that exist only in chat context will be lost on context compression, leaving the project in an unrecoverable state.
+</persistence>
+
 <success_criteria>
 Init is DONE when ALL of these are true:
 

package/distilled/workflows/pause.md

@@ -80,6 +80,8 @@ timestamp: $ISO_8601_TIMESTAMP
 The checkpoint is project-scoped (lives at `.planning/.continue-here.md`, not inside a phase directory) so resume always knows where to look.
 </write_checkpoint>
 
+**MANDATORY: `.planning/.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.**
+
 <advisory_git>
 Read `.planning/config.json` for the `gitProtocol` section. If config.json cannot be read, skip git advice.
 

package/distilled/workflows/plan.md

@@ -10,8 +10,9 @@ Before starting, read these files:
 1. `.planning/SPEC.md` - requirements, constraints, key decisions, current state
 2. `.planning/ROADMAP.md` - find the target phase, its goal, requirements, and success criteria
 3. `.planning/research/*.md` - if research exists and is relevant to this phase
-4. `.planning/phases/*-PLAN.md` - any previous plans that affect this phase
-5. Relevant source code - if this phase builds on existing code, read the key files
+4. `.planning/phases/*-APPROACH.md` - approach decisions from user discussion (if exists)
+5. `.planning/phases/*-PLAN.md` - any previous plans that affect this phase
+6. Relevant source code - if this phase builds on existing code, read the key files
 
 Identify the target phase: the first phase with status `[ ]` or `[-]` in `ROADMAP.md`.
 </load_context>
@@ -20,8 +21,9 @@ Identify the target phase: the first phase with status `[ ]` or `[-]` in `ROADMA
 Before planning, acknowledge what is locked:
 
 - Decisions in `.planning/SPEC.md` "Key Decisions" - do not revisit them.
+- Decisions in APPROACH.md "Implementation Decisions" - these are user-validated choices. Implement the chosen approaches, not alternatives. "Agent's Discretion" items give you flexibility.
 - Patterns from previous phases - match existing conventions. Do not introduce new patterns without cause.
-- Deferred items - items marked v2, nice-to-have, or out of scope. Do not plan for them.
+- Deferred items - items marked v2, nice-to-have, or out of scope in SPEC.md or APPROACH.md. Do not plan for them.
 
 If you need to challenge a locked decision: stop, ask the developer, and document the new decision explicitly.
 </context_fidelity>
@@ -250,15 +252,79 @@ must_haves:
 ```
 </plan_structure>
 
-<clarify_approach>
-If there is ambiguity in how to implement:
+<approach_exploration>
+### When This Runs
 
-1. Ask the developer about preferences when the choice materially changes the design.
-2. Surface your assumptions explicitly.
-3. Present trade-offs when multiple approaches are valid.
+Check `.planning/config.json` for `workflow.discuss`:
+- If `workflow.discuss: false` (or key missing): skip this section, go to `<goal_backward_planning>`. Note `reduced_alignment` in the orchestration summary.
+- If `workflow.discuss: true`: mandatory before planning.
 
-If the approach is obvious or fully defined by `.planning/SPEC.md`, skip questions and proceed.
-</clarify_approach>
+### Check for Existing APPROACH.md
+
+Check if `{phase_dir}/{padded_phase}-APPROACH.md` exists.
+
+**If exists:**
+Offer the user a choice:
+- "Use existing" — load decisions from APPROACH.md, skip to `<goal_backward_planning>`
+- "Update it" — run the approach explorer to revise decisions
+- "View it" — display APPROACH.md contents, then offer "Use existing" / "Update"
+
+**If does not exist (or user chose "Update"):**
+Run the approach explorer.
+
+### Running the Approach Explorer
+
+**Primary path — inline conversation with research subagents:**
+
+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.
+
+1. Load context: read ONLY locked decisions from `.planning/SPEC.md` and the target phase goal/requirements from `.planning/ROADMAP.md`.
+
+2. Identify 3-4 domain-specific gray areas. Classify each as **taste** (preference, no research needed), **technical** (trade-offs, research first), or **hybrid** (both).
+
+3. For each **technical or hybrid** gray area, spawn a read-only research subagent.
+   Use the prompt template from `.planning/templates/roles/approach-explorer.md` (`<research_subagent_prompt>` section), substituting the gray area name, classification, phase context, and relevant codebase files. Each subagent returns a structured summary under 1000 tokens.
+
+4. Present each gray area to the user individually:
+   - For taste areas: ask directly
+   - For technical/hybrid: present the research summary, lead with recommendation
+   - Ask: "Discuss this, or should I use my judgment?"
+
+5. For each area the user chose to discuss, ask adaptive questions until the decision converges. Persist each confirmed decision to disk incrementally.
+
+6. Surface assumptions across 5 dimensions with confidence levels. Wait for corrections.
+
+7. Self-check: verify every decision is concrete enough for the planner before writing.
+
+8. Write `{padded_phase}-APPROACH.md` to the phase directory.
+
+**Native agent optimization:**
+
+If your runtime provides an interactive `gsdd-approach-explorer` agent:
+- Invoke it with: target phase goal, requirement IDs, locked decisions, phase research (if exists), relevant codebase files
+- The native agent runs the full exploration in its own context window
+- This is an optimization — the output (APPROACH.md) is identical to the primary path
+
+**Inline fallback (reduced alignment):**
+
+If neither the primary path nor native agent is available (e.g., the runtime cannot spawn research subagents):
+- Read the phase goal and identify 2-3 obvious gray areas
+- Present them to the user with your best assessment
+- Capture any decisions the user provides
+- Explicitly report `reduced_alignment` — the user did not get full research-backed exploration
+
+### Using APPROACH.md Decisions
+
+After approach exploration completes (or existing APPROACH.md is loaded):
+- Treat decisions from APPROACH.md as locked constraints, same priority as `.planning/SPEC.md` decisions
+- "Agent's Discretion" items from APPROACH.md give the planner flexibility — do not treat them as locked
+- Thread the APPROACH.md file path to both the planner prompt and the plan-checker prompt
+- Deferred ideas from APPROACH.md must not appear in the plan
+
+### Role Contract
+
+The approach explorer's full role contract is at `.planning/templates/roles/approach-explorer.md`. The portable workflow describes the orchestration; the role contract describes the agent's behavior.
+</approach_exploration>
 
 <plan_check_orchestration>
 ### How Plan Checking Works
@@ -274,6 +340,8 @@ After the planner produces a draft plan, an independent checker reviews it in fr
 5. `scope_sanity` - plans are sized so an executor can complete them without context collapse
 6. `must_have_quality` - success criteria are specific, observable, and reflected in tasks
 7. `context_compliance` - locked decisions are honored and deferred ideas stay out of scope
+8. `goal_achievement` - the plan, if executed perfectly, actually achieves the stated phase goal: goal addressed (tasks deliver the goal), success criteria reachable (each criterion traceable to a task verify output), and outcome observable (a human or automated check can confirm the goal was met)
+9. `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. Skipped when no APPROACH.md is provided.
 
 ### Invoking the Checker
 
@@ -282,6 +350,7 @@ After the planner produces a draft plan, an independent checker reviews it in fr
 3. If a native checker agent is available, invoke it in a fresh context with only these explicit inputs:
    - target phase goal and requirement IDs
    - relevant locked decisions / deferred items from `.planning/SPEC.md`
+   - approach decisions from `.planning/phases/*-APPROACH.md` (if exists)
    - relevant phase research file(s)
    - produced `.planning/phases/*-PLAN.md` file(s)
 4. Require the checker to return a single JSON object:
@@ -291,7 +360,7 @@ After the planner produces a draft plan, an independent checker reviews it in fr
      "summary": "One sentence overall assessment",
      "issues": [
        {
-         "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance",
+         "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance | goal_achievement | approach_alignment",
          "severity": "blocker | warning",
          "description": "What is wrong",
          "plan": "01-PLAN",
@@ -354,6 +423,8 @@ For each task:
 Planning is done when all of these are true:
 
 - [ ] Target phase identified from `ROADMAP.md`
+- [ ] Approach exploration completed or explicitly skipped with `reduced_alignment` reported
+- [ ] When `workflow.discuss: true`: user alignment confirmed via APPROACH.md before planning
 - [ ] Research check completed where needed
 - [ ] Plan self-check passed
 - [ ] Success criteria from `ROADMAP.md` are represented as must-haves
@@ -362,7 +433,7 @@ Planning is done when all of these are true:
 - [ ] Every task has XML structure with `id`, `type`, `files`, `action`, `verify`, and `done`
 - [ ] Every task has at least one runnable verify command
 - [ ] Plan sizing stays within 2-5 tasks, preferring 2-3
-- [ ] Locked decisions from `.planning/SPEC.md` are honored
+- [ ] Locked decisions from `.planning/SPEC.md` and APPROACH.md are honored
 - [ ] Any git guidance stays repo-native and follows `.planning/config.json`
 </success_criteria>
 

package/distilled/workflows/quick.md

@@ -5,6 +5,16 @@ Quick tasks are for sub-hour work: bug fixes, small features, config changes, on
 They reuse the same planner, executor, and verifier roles but skip research and synthesizer.
 </role>
 
+<anti_patterns>
+- Do not execute before the user sees the plan preview (Step 3.7 must complete before Step 4)
+- Do not proceed past file verification gates if the expected file does not exist on disk — a plan that exists only in conversation context will be lost on compaction
+- Do not ask more than 2 approach clarification questions — if 3+ grey areas exist, recommend /gsdd:plan instead
+- Do not create APPROACH.md for quick tasks — use inline $APPROACH_CONTEXT only
+- Do not update ROADMAP.md or SPEC.md from quick tasks — these are phase-level artifacts
+- Do not skip config.json reads — workflow toggles (discuss, planCheck, verifier) control flow
+- Do not expand scope mid-execution — if the plan reveals architectural work, surface the scope signal (Step 3.6) and let the user decide
+</anti_patterns>
+
 <prerequisites>
 `.planning/` must exist (from `gsdd init`). ROADMAP.md is NOT required -- quick tasks work during any project phase.
 
@@ -39,6 +49,44 @@ If `.planning/quick/` does not exist, create it along with an empty `LOG.md`:
 
 ---
 
+## Step 2.5: Approach clarification (conditional)
+
+Read `.planning/config.json`.
+- If `workflow.discuss` is `false` (or key missing): set `$APPROACH_CONTEXT` to empty, skip to Step 3.
+- If `workflow.discuss` is `true`: evaluate `$DESCRIPTION` for ambiguity signals.
+
+### Ambiguity signals
+
+| Signal | Detection | Example |
+|--------|-----------|---------|
+| Multiple valid approaches | Description could be solved via distinct patterns | "add caching" (Redis? in-memory? HTTP headers?) |
+| Destructive operations | Contains: `delete`, `remove`, `migrate`, `rename`, `replace`, `rewrite`, `drop` | "remove the old auth middleware" |
+| Vague scope | Contains: `improve`, `fix`, `update`, `refactor`, `clean up`, `optimize` without specifying target | "improve error handling" |
+| Trade-off present | Description implies competing goals (performance vs simplicity, DRY vs explicit) | "make it faster" |
+
+If **no signals fire**: set `$APPROACH_CONTEXT` to empty, skip to Step 3 silently.
+
+If **any signal fires**: identify 1-2 grey areas and ask targeted questions.
+
+### Question format
+
+For each grey area, present 2-3 concrete options with a recommended default:
+
+"I'd approach this with **{recommendation}** because {reason}. Want me to proceed, or do you prefer {alternative}?"
+
+- If user says "go ahead" / "your call" / presses Enter → use the recommendation.
+- If user specifies a preference → record it.
+- Maximum 2 questions. If the task has 3+ grey areas, it's not a quick task.
+
+### Output
+
+Store confirmed decisions as `$APPROACH_CONTEXT` — a short string of user-validated choices.
+Example: "User confirmed: use in-memory LRU cache, not Redis. Keep existing error format."
+
+No APPROACH.md file is created. This is inline context only.
+
+---
+
 ## Step 3: Plan
 
 Delegate to the planner role in quick mode.
@@ -49,10 +97,12 @@ Delegate to the planner role in quick mode.
 
 **Context to provide:**
 - Task description: `$DESCRIPTION`
+- Approach context: `$APPROACH_CONTEXT` (user-confirmed decisions from Step 2.5 — treat as locked constraints, do not revisit)
 - Mode: quick (single plan, 1-3 tasks, no research phase)
 - Output path: `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md`
 
 **Constraints:**
+- If `$APPROACH_CONTEXT` is non-empty, implement the user's confirmed choices — do not substitute alternatives
 - Create a SINGLE plan with 1-3 focused tasks
 - Quick tasks are atomic and self-contained
 - No research phase, no ROADMAP requirements
@@ -66,13 +116,116 @@ Delegate to the planner role in quick mode.
 </delegate>
 
 After the planner returns:
-1. Verify the plan file exists.
-2. If not found, report the error and stop.
+
+**STOP. Verify that `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md` exists on disk before proceeding to execution. If the file does not exist, report the error to the user and do NOT proceed. A plan that exists only in conversation context will be lost.**
+
+### Quick Plan Self-Check
+
+Before proceeding to execution, verify the plan meets minimum quality:
+- [ ] Plan has at least 1 task with `<action>` and `<verify>` sections
+- [ ] Each task's `<verify>` has at least one runnable command
+- [ ] Plan tasks do not exceed 3 (quick scope constraint)
+
+This is a self-check, not an independent plan-check. Failures are noted but do NOT block execution — report `reduced_assurance` in the completion summary.
+
+---
+
+## Step 3.5: Independent plan check (conditional)
+
+Read `.planning/config.json`.
+- If `workflow.planCheck` is `false` (or key missing): skip to Step 3.6.
+- If `workflow.planCheck` is `true`: delegate to the plan-checker with quick-scoped dimensions.
+
+<delegate>
+**Identity:** Plan Checker (quick mode)
+**Instruction:** Read `.planning/templates/delegates/plan-checker.md` for your role contract, then check this quick task plan.
+
+**Context to provide:**
+- Task description: `$DESCRIPTION` (treat as the phase goal equivalent)
+- Plan: `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md`
+- Mode: quick
+
+**Constraints:**
+- Check 5 dimensions only: `requirement_coverage`, `task_completeness`, `dependency_correctness`, `scope_sanity`, `must_have_quality`
+- Skip: `key_link_completeness`, `context_compliance`, `goal_achievement`, `approach_alignment`
+- Maximum 1 revision cycle (if blockers found, send back to planner once, then accept result)
+- Blocker threshold: only block on `task_completeness` or `scope_sanity` violations
+- Warnings for other dimensions are noted but do not block
+
+**Output:** Checker response (passed | issues_found) with issue details.
+**Return:** Status and issue summary.
+</delegate>
+
+If the checker returns `issues_found` with blockers and this is the first cycle:
+1. Send the issue list back to the planner for targeted revision of the plan file.
+2. Re-run the checker once more.
+3. If blockers remain after 1 revision cycle, store `$CHECKER_ISSUES` for display in the plan preview. Do NOT block — the user decides in Step 3.7.
+
+If the checker returns `passed`, or `workflow.planCheck` is false, `$CHECKER_ISSUES` is empty.
+
+---
+
+## Step 3.6: Scope signal evaluation
+
+Evaluate the plan against quick-scope boundaries. Read the plan file and check:
+
+| Signal | Threshold | `$SCOPE_WARNING` text |
+|--------|-----------|----------------------|
+| Files modified | >8 distinct files in plan | "This task touches {N} files — consider `/gsdd:plan` for full ceremony." |
+| Architecture keywords in `$DESCRIPTION` | contains: `refactor`, `migration`, `security`, `auth`, `API design`, `schema`, `database` | "This looks like architectural work — consider `/gsdd:plan` for approach exploration." |
+| 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." |
+
+If any signal fires, set `$SCOPE_WARNING` to the first matching advisory text. Multiple signals concatenate.
+If no signals fire, `$SCOPE_WARNING` is empty.
+
+This is advisory only — it does NOT block execution.
+
+---
+
+## Step 3.7: Plan preview
+
+Present the plan summary to the user before execution begins.
+
+Read the plan file and extract:
+- Task count and task names
+- List of files to be modified/created (from plan task `<files>` sections)
+- A 1-sentence approach summary (first sentence of the plan's objective or goal)
+
+Display:
+
+```
+Quick Task Plan Preview:
+- Tasks: {count} ({task_names})
+- Files: {file_list}
+- Approach: {1-sentence summary}
+```
+
+If `$SCOPE_WARNING` is non-empty, append:
+```
+Scope signal: {$SCOPE_WARNING}
+```
+
+If `$CHECKER_ISSUES` is non-empty, append:
+```
+Plan check issues: {$CHECKER_ISSUES}
+```
+
+Present options (default-yes — pressing Enter proceeds):
+- If `$SCOPE_WARNING` is empty: `[Enter to proceed / edit description / abort]`
+- If `$SCOPE_WARNING` is non-empty: `[Enter to proceed / switch to /gsdd:plan / edit description / abort]`
+
+Handle response:
+- **Enter (or "yes"):** proceed to Step 4.
+- **"edit description":** clean up the task directory, then return to Step 1 with `$DESCRIPTION` pre-filled as the starting point.
+- **"switch to /gsdd:plan":** clean up the task directory, then stop quick workflow and report: "Use `/gsdd:plan` for full ceremony with approach exploration. Task description: {$DESCRIPTION}"
+- **"abort":** clean up the task directory, report cancellation, stop.
 
 ---
 
 ## Step 4: Execute
 
+**Only reached after the user has seen the plan preview in Step 3.7.**
+
 Delegate to the executor role.
 
 <delegate>
@@ -96,8 +249,8 @@ Delegate to the executor role.
 </delegate>
 
 After the executor returns:
-1. Verify the summary file exists.
-2. If not found, report the error and stop.
+
+**STOP. Verify the SUMMARY file exists at `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-SUMMARY.md` on disk. If it does not exist, report the write failure. Do NOT proceed to verification or LOG.md update without a persisted summary.**
 
 ---
 
@@ -125,6 +278,8 @@ Read `.planning/config.json`.
 **Return:** Verification status (passed | gaps_found | human_needed).
 </delegate>
 
+**STOP. Verify the VERIFICATION file exists at `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-VERIFICATION.md` on disk (when verifier ran). If it does not exist, report the write failure. Do NOT proceed to LOG.md update without a persisted verification report.**
+
 ---
 
 ## Step 6: Update LOG.md
@@ -154,9 +309,13 @@ Report to the user:
 
 <success_criteria>
 - [ ] User provided a task description
+- [ ] Approach clarification ran (only if workflow.discuss is true AND ambiguity detected)
 - [ ] `.planning/quick/` directory exists (created if needed)
 - [ ] Task directory created at `.planning/quick/NNN-slug/`
 - [ ] `NNN-PLAN.md` created by planner (1-3 tasks)
+- [ ] Independent plan check ran (only if workflow.planCheck is true)
+- [ ] Plan preview presented to user before execution
+- [ ] User confirmed (or pressed Enter) before execution proceeded
 - [ ] `NNN-SUMMARY.md` created by executor
 - [ ] `NNN-VERIFICATION.md` created by verifier (only if workflow.verifier is true)
 - [ ] `LOG.md` updated with task row

package/package.json

@@ -1,14 +1,22 @@
 {
   "name": "gsdd-cli",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "description": "GSDD — a portable, spec-driven development kernel for AI coding agents. Works with Claude Code, Codex CLI, OpenCode, Cursor, Copilot, and Gemini CLI.",
   "type": "module",
   "bin": {
-    "gsdd": "./bin/gsdd.mjs"
+    "gsdd": "bin/gsdd.mjs"
   },
   "scripts": {
     "test:gsdd": "node tests/gsdd.init.test.cjs && node tests/gsdd.models.test.cjs && node tests/gsdd.manifest.test.cjs && node tests/gsdd.plan.adapters.test.cjs && node tests/gsdd.audit-milestone.test.cjs && node tests/gsdd.invariants.test.cjs && node tests/gsdd.guards.test.cjs && node tests/gsdd.health.test.cjs && node tests/gsdd.scenarios.test.cjs"
   },
+  "devDependencies": {
+    "semantic-release": "^24.2.3",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
   "files": [
     "bin/adapters/",
     "bin/lib/",
@@ -40,6 +48,6 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/PatrickSys/get-shit-done-distilled"
+    "url": "git+https://github.com/PatrickSys/get-shit-done-distilled.git"
   }
 }