gsdd-cli 0.1.0 → 0.3.1

package/bin/lib/models.mjs

@@ -16,7 +16,7 @@ export const DEFAULT_GIT_PROTOCOL = {
 };
 
 export const VALID_MODEL_PROFILES = ['quality', 'balanced', 'budget'];
-export const PORTABLE_AGENT_IDS = ['plan-checker'];
+export const PORTABLE_AGENT_IDS = ['plan-checker', 'approach-explorer'];
 export const MODEL_RUNTIME_IDS = ['claude', 'opencode', 'codex'];
 export const MODEL_ID_PATTERN = /^[a-zA-Z0-9._\/:@-]+$/;
 
@@ -30,7 +30,7 @@ export function buildDefaultConfig({ autoAdvance = false } = {}) {
     parallelization: true,
     commitDocs: true,
     modelProfile: 'balanced',
-    workflow: { research: true, planCheck: true, verifier: true },
+    workflow: { research: true, discuss: false, planCheck: true, verifier: true },
     gitProtocol: { ...DEFAULT_GIT_PROTOCOL },
     initVersion: 'v1.1',
   };
@@ -157,9 +157,11 @@ export function cmdModels(...modelArgs) {
 function cmdModelsShow() {
   const cwd = process.cwd();
   const config = loadProjectModelConfig(cwd);
-  const ocOverride = getRuntimeModelOverride(config, 'opencode', 'plan-checker');
+  const ocCheckerOverride = getRuntimeModelOverride(config, 'opencode', 'plan-checker');
+  const ocExplorerOverride = getRuntimeModelOverride(config, 'opencode', 'approach-explorer');
   const ocDetected = detectOpenCodeConfiguredModel(cwd);
-  const codexOverride = getRuntimeModelOverride(config, 'codex', 'plan-checker');
+  const codexCheckerOverride = getRuntimeModelOverride(config, 'codex', 'plan-checker');
+  const codexExplorerOverride = getRuntimeModelOverride(config, 'codex', 'approach-explorer');
   output({
     modelProfile: normalizeModelProfile(config.modelProfile),
     agentModelProfiles: config.agentModelProfiles || {},
@@ -172,26 +174,41 @@ function cmdModelsShow() {
           agentId: 'plan-checker',
           profileMap: CLAUDE_MODEL_PROFILES,
         }),
+        'approach-explorer': getRuntimeAgentModelState({
+          config,
+          runtime: 'claude',
+          agentId: 'approach-explorer',
+          profileMap: CLAUDE_MODEL_PROFILES,
+        }),
       },
       opencode: {
         'plan-checker': {
-          mode: ocOverride ? 'override' : 'inherit',
-          model: ocOverride,
+          mode: ocCheckerOverride ? 'override' : 'inherit',
+          model: ocCheckerOverride,
+          runtimeDetectedModel: ocDetected,
+        },
+        'approach-explorer': {
+          mode: ocExplorerOverride ? 'override' : 'inherit',
+          model: ocExplorerOverride,
           runtimeDetectedModel: ocDetected,
         },
       },
       codex: {
         'plan-checker': {
-          mode: codexOverride ? 'override' : 'inherit',
-          model: codexOverride,
+          mode: codexCheckerOverride ? 'override' : 'inherit',
+          model: codexCheckerOverride,
+        },
+        'approach-explorer': {
+          mode: codexExplorerOverride ? 'override' : 'inherit',
+          model: codexExplorerOverride,
         },
       },
     },
     detectedRuntimeModels: {
       opencode: ocDetected,
     },
-    hints: !ocOverride ? {
-      opencode: 'OpenCode currently inherits its runtime model unless you set an explicit override. Use gsdd models set --runtime opencode --agent plan-checker --model <provider/model-id> to inject an explicit checker model.',
+    hints: (!ocCheckerOverride || !ocExplorerOverride) ? {
+      opencode: 'OpenCode currently inherits its runtime model unless you set an explicit override. Use gsdd models set --runtime opencode --agent <agent-id> --model <provider/model-id> to inject an explicit agent model.',
     } : undefined,
   });
 }

package/distilled/DESIGN.md

@@ -9,7 +9,7 @@
 ## Table of Contents
 
 1. [4-File Codebase Standard](#1-4-file-codebase-standard)
-2. [Agent Consolidation: 11 to 9](#2-agent-consolidation-11-to-9)
+2. [Agent Consolidation: 11 to 10](#2-agent-consolidation-11-to-10)
 3. [Two-Layer Architecture: Roles and Delegates](#3-two-layer-architecture-roles-and-delegates)
 4. [Zero-Hop Security Propagation](#4-zero-hop-security-propagation)
 5. [Conditional Synthesizer](#5-conditional-synthesizer)
@@ -36,6 +36,15 @@
 26. [Session Continuity Contract Hardening](#26-session-continuity-contract-hardening)
 27. [Consumer-Ready Surface Completion](#27-consumer-ready-surface-completion)
 28. [Workflow Completion Routing](#28-workflow-completion-routing)
+29. [Approach Exploration](#29-approach-exploration)
+30. [Hardening Propagation](#30-hardening-propagation)
+31. [Outcome Dimension for Plan-Checker](#31-outcome-dimension-for-plan-checker)
+32. [Quick Workflow Alignment Hardening](#32-quick-workflow-alignment-hardening)
+33. [Quick Approach Clarification](#33-quick-approach-clarification)
+34. [Context Engineering Applied to Quick Workflow](#34-context-engineering-applied-to-quick-workflow)
+35. [Skills-Native Runtimes vs Governance Adapters](#35-skills-native-runtimes-vs-governance-adapters)
+36. [Interactive Init Wizard](#36-interactive-init-wizard)
+37. [Mutability-Driven Workflow Classification](#37-mutability-driven-workflow-classification)
 
 ---
 
@@ -64,11 +73,11 @@
 
 ---
 
-## 2. Agent Consolidation: 11 to 9
+## 2. Agent Consolidation: 11 to 10
 
 **GSD:** 11 specialized agent files, each scoped to a single concern.
 
-**GSDD:** 9 canonical roles. 3 mergers and 1 extraction.
+**GSDD:** 10 canonical roles. 2 mergers, 1 extraction, 1 addition (approach-explorer, D29).
 
 **Merger table:**
 
@@ -1001,7 +1010,7 @@ Permission values: ALLOW (role can access), DENY (explicit rejection required),
 
 **GSD:** Orchestrator subagent prompts were embedded inline in workflow files or referenced indirectly through agent role contracts. No explicit thin-wrapper layer. Scope and context were implicit in the orchestrator's prompt shaping.
 
-**GSDD:** Extracted 10 delegates as explicit thin-wrapper files in `distilled/templates/delegates/`. A delegate is a sub-agent instruction wrapper scoped to a specific orchestrator task, carrying a bounded input/output contract. Ten delegates cover 3 canonical roles: mapper × 4 focus-scoped variants, researcher × 4 dimension-scoped variants, synthesizer × 1 (via `researcher-synthesizer.md`), plus one fresh-context adversarial reviewer (`plan-checker.md`, new in D9, no GSD equivalent). Executor, verifier, integration-checker, planner, and roadmapper are invoked directly from orchestrator workflows without thin-wrapper delegates.
+**GSDD:** Extracted 11 delegates as explicit thin-wrapper files in `distilled/templates/delegates/`. A delegate is a sub-agent instruction wrapper scoped to a specific orchestrator task, carrying a bounded input/output contract. Eleven delegates cover 4 canonical roles: mapper × 4 focus-scoped variants, researcher × 4 dimension-scoped variants, synthesizer × 1 (via `researcher-synthesizer.md`), one fresh-context adversarial reviewer (`plan-checker.md`, new in D9, no GSD equivalent), and one interactive approach explorer (`approach-explorer.md`, recovers GSD discuss-phase leverage with research enhancement). Executor, verifier, integration-checker, planner, and roadmapper are invoked directly from orchestrator workflows without thin-wrapper delegates.
 
 **Why "delegates":** In multi-agent orchestration literature (Anthropic multi-agent guidance, OpenAI harness engineering, OpenDev terminal-agents paper arXiv 2603.05344), a delegate is a sub-agent invoked by an orchestrator with:
 1. A single, bounded responsibility (not a general-purpose role)
@@ -1041,7 +1050,7 @@ This is acceptable because:
 2. The clarity gain outweighs the reading cost
 3. Delegate independence enables better testing and quality gates
 
-**10 delegates:**
+**11 delegates:**
 
 | Delegate | Purpose | Wrapped Role |
 |----------|---------|--------------|
@@ -1055,6 +1064,7 @@ This is acceptable because:
 | `researcher-pitfalls.md` | Research domain pitfalls and risks | researcher (dimension: pitfalls) |
 | `researcher-synthesizer.md` | Synthesize research into roadmap implications | synthesizer |
 | `plan-checker.md` | Fresh-context adversarial plan review | planner (adversarial, new in D9) |
+| `approach-explorer.md` | Interactive approach exploration and user alignment | approach-explorer (interactive, recovers GSD discuss-phase) |
 
 **Evidence:**
 
@@ -1124,7 +1134,7 @@ This is acceptable because:
 - G18 guard suite mechanically prevents recurrence: asserts every WORKFLOWS entry appears in `agents.block.md`
 - CHANGELOG and README synced to actual counts (assertions, design decisions, PRs, test suites)
 
-**Why this is high-leverage:** The framework machinery is mechanically sound (800+ assertions, 10 workflows, 9 roles, 3 native adapters, 23 design decisions). But an incomplete AGENTS.md map is functionally broken governance -- agents succeed or fail based on the harness, not the LLM.
+**Why this is high-leverage:** The framework machinery is mechanically sound (800+ assertions, 10 workflows, 10 roles, 3 native adapters, 23 design decisions). But an incomplete AGENTS.md map is functionally broken governance -- agents succeed or fail based on the harness, not the LLM.
 
 **Evidence:**
 
@@ -1139,7 +1149,7 @@ This is acceptable because:
 
 ## 25. Consumer First-Run Experience
 
-**Problem:** GSDD's internal architecture is complete (24 design decisions, 800+ tests, 10 workflows, 9 roles), but consumer-facing surfaces don't honestly guide first-time users. Two independent audits identified this as the single largest barrier to adoption.
+**Problem:** GSDD's internal architecture is complete (24 design decisions, 800+ tests, 10 workflows, 10 roles), but consumer-facing surfaces don't honestly guide first-time users. Two independent audits identified this as the single largest barrier to adoption.
 
 **Decision:** Make all consumer-facing surfaces (README, agents.block.md, post-init CLI output) honestly distinguish between native-capable and governance-only platforms, and provide platform-specific invocation guidance at every consumer touchpoint.
 
@@ -1275,6 +1285,355 @@ GSDD's `<completion>` pattern is vendor-agnostic (GSD's `/clear` is Claude-speci
 
 ---
 
+## 29. Approach Exploration
+
+**GSD baseline:** Three separate workflows handle pre-planning user alignment:
+
+| GSD workflow | Purpose | Output |
+|---|---|---|
+| `discuss-phase.md` (541 lines) | Gray area identification, 4-question batched loops per area, deferred ideas capture | `CONTEXT.md` |
+| `list-phase-assumptions.md` (179 lines) | 5-dimension assumption surfacing (technical approach, implementation order, scope boundaries, risks, dependencies) | Conversational only (no file output) |
+| `discovery-phase.md` | 3-level research (Quick/Standard/Deep) with domain exploration | `DISCOVERY.md` |
+
+Combined, these three workflows provided genuine leverage: the planner could not silently converge on a single approach without user input. GSD's initial GSDD distillation dropped all three, removing this alignment step entirely. The planner was left to infer approaches without user validation.
+
+**Problem:** Without approach exploration, the planner explores no alternatives, surfaces no assumptions, and captures no user decisions. The user's first chance to disagree with approach choices is after implementation — too late for efficient correction.
+
+**GSDD decision:** Recover the discuss-phase leverage as a single role (`agents/approach-explorer.md`) embedded in the plan workflow, with a hybrid interaction architecture:
+
+1. **Primary path (inline + research subagents):** Conversation runs in the plan workflow's main context (required for user interactivity). For each technical gray area, a read-only research subagent spawns, reads codebase/docs, and returns a compressed ~1000-token structured summary. Only summaries enter the conversation context, not raw file reads.
+
+2. **Native agent optimization:** Runtimes with interactive subagent support (Claude Code with `AskUserQuestion`, Codex interactive agents, OpenCode `mode: agent`) can run the full exploration as a native agent. Falls back to the inline primary path if unavailable.
+
+Both paths produce identical output: `{padded_phase}-APPROACH.md` in the phase directory.
+
+**Key enhancements over GSD:**
+
+| Enhancement | GSD pattern | GSDD pattern | Why |
+|---|---|---|---|
+| Gray area classification | All areas treated identically | Taste / technical / hybrid classification | Taste decisions need no research; technical ones do. Asking "what color?" the same way as "JWT vs sessions?" wastes context and user time |
+| Questioning style | Rigid 4-question batched loop | Adaptive convergence (2-6 questions depending on complexity) | Fixed batch sizes don't match decision complexity. Some areas resolve in 2 questions, others need 6 |
+| Pre-question research | No research before asking | Research subagent per technical area returns structured summary before asking | Users make better decisions when presented with researched options and trade-offs |
+| Quality gate | None | Self-check before writing APPROACH.md (concrete decisions, no vague language, source backing, scope compliance) | Prevents weak outputs that force re-asking during planning |
+| Intermediate persistence | No persistence until final output | Confirmed decisions written to disk incrementally | Protects against context limits in long conversations |
+| Context loading | "Read everything" | JIT extraction guidance (e.g., "From SPEC.md read ONLY locked decisions") | Prevents context pollution with irrelevant content |
+| Plan-checker integration | None | New `approach_alignment` dimension in plan-checker | Verifies plans honor approach decisions, not just requirements |
+| Delegation option | Not available | "Agent's Discretion" — user can explicitly delegate choices to the agent | Reduces user fatigue on areas where they have no strong preference |
+
+**Role contract design:** Ground-up rewrite applying prompt engineering best practices:
+
+- XML semantic structure (`<role>`, `<algorithm>`, `<examples>`, `<anti_patterns>`, `<quality_guarantees>`) matching the planner role pattern
+- 3 few-shot conversation examples (taste decision, technical decision with research, hybrid with delegation)
+- Vendor-neutral throughout — no tool-specific references in the role contract
+- Anti-patterns placed early for high attention weight
+
+**Architecture rationale — why hybrid:**
+
+The approach explorer needs two capabilities with opposite context requirements:
+- **Conversation** needs the main context (for user interaction)
+- **Research** generates thousands of tokens of raw content the conversation doesn't need
+
+Isolating research in subagents and returning compressed summaries follows the Compress and Isolate patterns from context engineering literature. The research subagent prompt template lives in the role contract (`<research_subagent_prompt>` section of `agents/approach-explorer.md`) — co-located with the algorithm it serves, and referenced by the portable workflow rather than inlined. The main context budget stays manageable: ~1000 tokens orchestration + ~4000 tokens research summaries (4 areas × ~1000) + ~4000 tokens conversation + ~500 tokens APPROACH.md = ~9500 tokens. The 1000-token budget (matching Anthropic CE's recommended floor) gives research subagents room for the structured format (Name/Pro/Con/Source) plus recommendation reasoning, source verification, and enough project-specific context that the main agent can handle follow-up questions without re-querying the subagent.
+
+**Evidence:**
+
+1. Anthropic "Building effective agents" (2025): sub-agents perform deep technical work, returning condensed summaries to the orchestrator — "find the smallest set of high-signal tokens"
+2. Anthropic prompting best practices (2025): XML tags for semantic structure, role preamble, few-shot examples, adaptive thinking
+3. LangChain "Context Engineering for Agents" (2025): Write/Select/Compress/Isolate patterns — "isolate: split context across separate processes", "compress: summarize at agent-agent boundaries"
+4. Agent Skills specification (agentskills.io): progressive disclosure, SKILL.md format with metadata-first structure
+5. OpenAI meta-prompting (2025): LLM-as-judge evaluation, specification-based output quality verification
+6. GSD source: `get-shit-done/workflows/discuss-phase.md` (gray area identification, AskUserQuestion interaction, deferred ideas)
+7. GSD source: `get-shit-done/workflows/list-phase-assumptions.md` (5-dimension assumption surfacing with confidence levels)
+8. GSD source: `get-shit-done/workflows/discovery-phase.md` (3-level research workflow)
+
+**Trade-offs:**
+
+- Benefit: planner receives locked user decisions instead of guessing approaches; plan-checker can verify approach alignment; context stays lean via research isolation
+- Cost: adds one interactive step before planning (~5-15 minutes of user time per phase); hybrid architecture is more complex than a single monolithic workflow
+- Mitigation: `workflow.discuss: true|false` toggle in `.planning/config.json` allows skipping with explicit `reduced_alignment` reporting; taste areas skip research entirely. Default is `false` (opt-in) to stay consistent with GSDD's stripped-down identity; users enable it explicitly
+
+**GSDD implementation:** `agents/approach-explorer.md` (role contract), `distilled/templates/delegates/approach-explorer.md` (thin delegate), `distilled/templates/approach.md` (output template), `distilled/workflows/plan.md` (`<approach_exploration>` section), `agents/planner.md` (`<approach_decisions>` section), `distilled/templates/delegates/plan-checker.md` (`approach_alignment` dimension), `bin/adapters/claude.mjs` + `bin/adapters/opencode.mjs` + `bin/adapters/codex.mjs` (native agent rendering)
+
+---
+
+## 30. Hardening Propagation
+
+**Problem:** D28 introduced three hardening patterns (positional STOP gates, mandatory persistence with STOP-on-failure, guard-backed regression prevention) but applied them selectively: STOP gates only in `new-project.md`, persistence gates only in `execute.md` and `verify.md`. Three medium-tier workflows (`quick.md`, `map-codebase.md`, `new-project.md`) and two consistency targets (`audit-milestone.md`, `pause.md`) produce equally critical artifacts but lacked these protections.
+
+**Decision:** Propagate D28 patterns to all workflows that produce durable artifacts, organized into three tiers. Intentionally exclude read-only workflows (`progress.md`) and workflows with adequate existing coverage (`resume.md`).
+
+| Tier | ID | Workflow | Hardening | Pattern Source |
+|------|-----|----------|-----------|----------------|
+| 1 | H1 | `quick.md` | MANDATORY persistence gates for SUMMARY.md and VERIFICATION.md | `execute.md` SUMMARY gate |
+| 1 | H2 | `quick.md` | Positional STOP gate between plan and execute | `new-project.md` STOP gates |
+| 1 | H3 | `map-codebase.md` | Semantic quality check on mapper outputs (L2 substantiveness) | `verify.md` L1/L2/L3 checking |
+| 1 | H4 | `map-codebase.md` | MANDATORY persistence gate for 4 codebase documents | `execute.md` SUMMARY gate |
+| 1 | H5 | `new-project.md` | `<persistence>` section for SPEC.md and ROADMAP.md | `verify.md` `<persistence>` |
+| 1 | H6 | `quick.md` | Reduced-assurance plan self-check with `reduced_assurance` label | `plan.md` self-check fallback |
+| 2 | H7 | `audit-milestone.md` | MANDATORY persistence gate for MILESTONE-AUDIT.md | `execute.md` SUMMARY gate |
+| 2 | H8 | `pause.md` | MANDATORY persistence gate for `.continue-here.md` | `execute.md` SUMMARY gate |
+| 2 | H9 | `new-project.md` | Positional STOP gate between spec approval and roadmap creation | `new-project.md` STOP gates |
+
+**Intentional non-propagation:**
+- `progress.md`: read-only by contract — writes zero files, modifies zero state. Nothing to gate.
+- `resume.md`: state detection already validates artifact existence before routing. No gap.
+
+**Evidence:**
+
+1. D28 consumer audit (2026-03-21): persistence failures and routing dead ends at every workflow boundary — patterns proven effective, scope was incomplete
+2. Huang et al. "Large Language Models Cannot Self-Correct Reasoning Yet" (ICLR 2024): LLMs cannot reliably self-correct without external feedback — validates fresh-context checking and explicit STOP gates over implicit behavioral expectations
+3. Kamoi et al. "When Can LLMs Actually Correct Their Own Mistakes?" (TACL 2024): self-correction works ONLY with reliable external feedback — validates MANDATORY gates as the external enforcement mechanism
+4. Anthropic long-context research (2024): instructions at decision points are followed more reliably than instructions at document start — validates positional STOP placement at exact deviation points
+5. D13 consistency argument: mechanical invariant enforcement prevents regression. The same structural pattern should be enforced everywhere it applies, not selectively.
+
+**Tradeoff:** 18 new guard assertions (G24) to maintain, but prevents artifact loss across 5 additional workflows. Each persistence gate adds 1-2 lines to its workflow. Positional STOP gates add 1 line each. The cost is minimal relative to the failure modes prevented (lost SPEC.md, lost checkpoint, empty codebase maps poisoning downstream planning).
+
+**GSDD implementation:** `distilled/workflows/quick.md`, `distilled/workflows/map-codebase.md`, `distilled/workflows/new-project.md`, `distilled/workflows/audit-milestone.md`, `distilled/workflows/pause.md`, `tests/gsdd.guards.test.cjs` (G24)
+
+---
+
+## 31. Outcome Dimension for Plan-Checker
+
+**Problem:** GSDD's plan-checker verifies 7 structural dimensions (requirement coverage, task completeness, dependency correctness, key link completeness, scope sanity, must-have quality, context compliance). All 7 are process supervision — they check whether the plan is well-formed, not whether it achieves the phase goal. A plan can pass all 7 dimensions while producing only scaffolding artifacts that don't deliver the stated outcome.
+
+**Decision:** Add an 8th dimension `goal_achievement` that performs outcome-level verification:
+
+- **Goal addressed?** Do the plan's collective task outputs deliver the phase goal? Tasks that only set up infrastructure without delivering the stated user-facing outcome → `blocker`.
+- **Success criteria reachable?** Are ROADMAP.md success criteria traceable to task verify outputs? Each criterion should map to at least one task → `blocker` if unreachable.
+- **Outcome observable?** Could a human or automated check confirm the goal was met after execution? Plans producing only internal artifacts with no testable outcome → `warning`.
+
+This creates a hybrid process+outcome verification architecture: 7 structural dimensions (process) + 1 outcome dimension.
+
+**Evidence:**
+
+1. Yu et al. "Outcome-Refining Process Supervision for Code Generation" (ICML 2025): hybrid process+outcome supervision achieves +26.9% correctness over either alone — the strongest evidence for adding outcome-level checks alongside process checks
+2. Rajan "Multi-Agent Code Verification via Information Theory" (2025): diminishing returns plateau around 4-7 specialized dimensions. 8 dimensions is within the efficient range; each additional dimension beyond 4 adds +11-15pp detection improvement
+3. Lightman et al. "Let's Verify Step by Step" (ICLR 2024): process supervision (per-step feedback) significantly outperforms outcome-only supervision — validates keeping the existing 7 process dimensions while adding outcome as complement, not replacement
+
+**Tradeoff:** One additional dimension for the checker to evaluate per plan. Minimal cost: the goal and success criteria are already available as checker inputs (phase goal from ROADMAP.md, success criteria from ROADMAP.md phase section). No new inputs required.
+
+**GSDD implementation:** `distilled/templates/delegates/plan-checker.md` (`goal_achievement` dimension), `tests/gsdd.guards.test.cjs` (G24 assertions)
+
+---
+
+## 32. Quick Workflow Alignment Hardening
+
+**Problem:** GSDD's quick workflow has exactly one user alignment touchpoint — the task description at Step 1. After "what do you want to do?", the agent has unchecked autonomy over approach selection, scope interpretation, and execution. The full ceremony (`plan.md`) has 3-4 alignment touchpoints (approach exploration, plan review, checker escalation, mandatory verification). This gap is too large: quick mode trades ALL alignment for speed, creating a cliff between "zero agent oversight" and "full multi-round ceremony."
+
+GSD's approach was a `--full` flag that added plan-checking + verification to quick tasks. But a flag you must remember to use doesn't solve alignment — the default mode still had zero user visibility into the plan before execution.
+
+**Decision:** Three targeted interventions that close the alignment gap from 1 to 2-3 touchpoints without killing quick mode's speed advantage:
+
+1. **Plan Preview Gate (mandatory, default-yes):** After the planner returns and the STOP gate verifies the plan exists, present a structured summary (task count, files to touch, 1-sentence approach) and wait for the user. Default-yes: pressing Enter proceeds. Options include edit, abort, and (when scope signal fires) switch to full ceremony. This is the core fix — the user sees agent intent before code changes happen.
+
+2. **Scope Signal with Escalation (advisory, always-on):** Inline orchestrator evaluation checks the plan against quick-scope boundaries: >8 files modified, architecture keywords in description (`refactor`, `migration`, `security`, `auth`, `API design`, `schema`, `database`), new public APIs. If any signal fires, the advisory appears in the plan preview with a recommendation to use `/gsdd:plan` for approach exploration. Advisory only — the user decides. Keyword heuristics have false positives; blocking would train users to ignore the signal.
+
+3. **Config-Gated Independent Plan Check (optional):** When `workflow.planCheck: true` in config.json, the existing plan-checker delegate runs against the quick task plan with 5 of 9 dimensions: `requirement_coverage`, `task_completeness`, `dependency_correctness`, `scope_sanity`, `must_have_quality`. Maximum 1 revision cycle (not 3 — diminishing returns for 1-3 task plans). If blockers remain, they surface in the plan preview for user decision. No new delegate or config key — reuses existing infrastructure.
+
+**GSD comparison:**
+
+| Aspect | GSD `--full` | GSDD D32 |
+|--------|-------------|----------|
+| Plan visibility | None in default, plan-checker in --full | Always-on preview (default-yes) |
+| Activation | Flag per invocation (easy to forget) | Config-driven (project-wide, consistent) |
+| Scope awareness | None | Advisory scope signal with escalation |
+| Checker scope | Full 5-dimension check (--full only) | 5-dimension quick-scoped check (config-gated) |
+| Revision cycles | Max 2 (--full only) | Max 1 (quick tasks don't warrant extended loops) |
+| User decision | Force proceed or abort after checker | Preview + scope signal + checker issues → informed decision |
+
+**Evidence:**
+
+1. Risk-adaptive autonomy pattern (AWS, Azure, Anthropic 2025-2026): confirmation gates should scale with consequence level — routine auto-proceeds, uncertain pauses, high-impact requires sign-off. The plan preview is the "pause for uncertain" gate.
+2. Human-on-the-loop > human-in-the-loop (Anthropic agent autonomy research 2026): HOTL gives visibility without requiring active management of each step. Default-yes implements HOTL — the user monitors, intervenes only when needed.
+3. Osmani / Fowler on spec-driven development (2025): "iterate in small loops, course-correct quickly." The plan preview IS the small-loop checkpoint for quick tasks.
+4. Madaan et al. "Self-Refine" (NeurIPS 2023): 1 revision cycle captures most improvement; diminishing returns argue against 3 cycles for 1-3 task plans. Validates max-1 checker cycle for quick scope.
+5. Huang et al. "LLMs Cannot Self-Correct Reasoning Yet" (ICLR 2024): self-check without external feedback is unreliable. The plan preview provides external feedback (user eyes on the plan) even when the independent checker is disabled.
+6. SkillsBench (Feb 2026): focused skills outperform comprehensive docs. Quick mode should stay focused and escalate to full ceremony when scope exceeds boundaries, not expand to absorb more ceremony.
+
+**Tradeoff:** ~5 seconds overhead for plan preview (default-yes), ~60-90 seconds if independent checker runs. Sub-hour work stays sub-hour. Adds ~60 lines to quick.md (198→~260). No new files, no new delegates, no new config keys.
+
+**GSDD implementation:** `distilled/workflows/quick.md` (Steps 3.5-3.7), `distilled/DESIGN.md` (this section), `tests/gsdd.guards.test.cjs` (G24 assertions for plan preview, scope signal, conditional plan-checker)
+
+---
+
+## 33. Quick Approach Clarification
+
+**Problem:** D32 added post-plan alignment to quick tasks (plan preview, scope signal, optional plan check), but all three interventions are **reactive** — the agent selects the approach unilaterally, writes the plan, then shows it to the user. The user can abort or edit the description, but cannot shape the approach before the planner commits. The full ceremony's `<approach_exploration>` (plan.md) solves this at scale with 3-4 grey areas, research subagents, and persisted APPROACH.md — but that's wrong for sub-hour work.
+
+**Decision:** Add Step 2.5 (Approach Clarification) between Initialize and Plan. Config-gated via the existing `workflow.discuss` toggle — same toggle that gates full ceremony's approach exploration, same intent ("align on approach before planning"), lighter mechanism for quick scope.
+
+The step has a **dual gate** — even with `workflow.discuss: true`, it evaluates the task description for ambiguity signals before asking anything:
+
+| Signal | Detection | Example |
+|--------|-----------|---------|
+| Multiple valid approaches | Description solvable 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 | Implies competing goals | "make it faster" (algorithmic? caching? denormalization?) |
+
+If no signals fire, the step skips silently — no questions asked, even with toggle on. When signals fire, the orchestrator identifies 1-2 grey areas and asks targeted questions in **recommendation-first format**: "I'd approach this with X because Y. Want me to proceed, or do you prefer Z?" Maximum 2 questions — if a task has 3+ grey areas, the scope signal (D32) should already be recommending `/gsdd:plan`.
+
+Output is inline `$APPROACH_CONTEXT` (e.g., "User confirmed: use in-memory LRU cache, not Redis") passed to the planner as locked constraints. No APPROACH.md file — file artifacts add overhead with no return for sub-hour work.
+
+**GSD comparison:** GSD has no pre-plan questioning in quick mode. The `--full` flag adds plan-checking and verification but not approach alignment — the agent still decides the approach unilaterally in all modes.
+
+| Aspect | GSD Quick | GSDD Quick (D32) | GSDD Quick (D32+D33) | GSDD Full Ceremony |
+|--------|----------|------------------|---------------------|-------------------|
+| Pre-plan alignment | None | None | 1-2 questions (conditional) | 3-4 grey areas + research subagents |
+| Post-plan alignment | None (--full adds checker) | Preview + scope signal | Preview + scope signal | Checker blocks (max-3 cycles) |
+| Approach persistence | None | None | Inline context only | APPROACH.md file |
+| User alignment rounds | 1 | 2-3 | 2-4 | 3-4 |
+
+**Evidence:**
+
+1. Anthropic "Measuring AI agent autonomy in practice" (2025): Claude asks 2x+ more on complex tasks; uncertainty awareness is treated as a safety property. D33's ambiguity detection formalizes what Claude naturally does — ask when uncertain, proceed when confident.
+2. Knight First Amendment Institute "Levels of Autonomy for AI Agents" (2025): 5-level autonomy spectrum. Quick tasks map to Level 3 ("Consultant"): agent decides, asks when uncertain. D33 implements this — agent leads with recommendation, asks only on ambiguity.
+3. Anthropic "Framework for safe and trustworthy agents" (2025): recommendation-first framing validated. "I'd do X because Y. Approve?" outperforms open-ended "What should I do?" — preserves agent leadership while giving user override.
+4. Martin Fowler "Humans and Agents in SE Loops" (2025): HOTL > HITL — agents handle 95% autonomously, pause for 5% edge cases. D33 asks only when ambiguity detected, not on every task.
+5. Huang et al. "LLMs Cannot Self-Correct Reasoning Yet" (ICLR 2024): LLMs cannot reliably self-correct without external feedback. Pre-plan user input catches approach errors that self-check cannot detect.
+6. Anthropic trust calibration data (2025): users auto-approve 20% initially → 40% by session 750+. Config-gated design respects this — experienced users who trust the agent disable `workflow.discuss`.
+
+**Counter-evidence addressed:** Asking too much creates HITL bottleneck (iMerit 2025, McKinsey 2025) → mitigated by dual gate (config + ambiguity detection). Open-ended questions reduce user confidence (Anthropic best practices) → mitigated by recommendation-first format. Routine tasks shouldn't be interrupted (SkillsBench Feb 2026) → mitigated by silent skip when no ambiguity detected.
+
+**Competitor landscape:** Cursor uses explicit mode selection (Ask vs Agent) without automatic ambiguity detection. GitHub Copilot uses post-hoc PR review only. GSD uses per-invocation `--full` flag. None do automatic ambiguity-sensitive pre-plan questioning.
+
+**Tradeoff:** ~15-30 seconds overhead when triggered (1-2 questions). Skipped entirely when no ambiguity detected, even with toggle on. Adds ~40 lines to quick.md. No new files, no new delegates, no new config keys — reuses existing `workflow.discuss` toggle.
+
+**GSDD implementation:** `distilled/workflows/quick.md` (Step 2.5), `distilled/DESIGN.md` (this section), `tests/gsdd.guards.test.cjs` (G24 assertions for approach clarification, ambiguity signals, recommendation-first format)
+
+---
+
+## 34. Context Engineering Applied to Quick Workflow
+
+**GSD:** GSD quick.md has `<purpose>`, `<required_reading>`, `<process>` (XML outer sections) with `**Step N:**` bold markdown inside `<process>`. No `<anti_patterns>` section. No authority language conventions for process gates.
+
+**GSDD (before D34):** Same XML outer sections with markdown step headers inside `<process>`. All 9 role contracts have `<anti_patterns>` after `<role>` (documented in DISTILLATION.md as mandatory placement), but quick.md — an orchestrator consumed by AI agents — had none. Authority language mixed between `**STOP.**` and `**MANDATORY:**` across 3 file-verification gates.
+
+**GSDD (D34):** Two targeted changes applying context engineering principles from the prompty/agentskit reference implementation (28 primary sources) and Anthropic prompting guidance:
+
+**Change 1: `<anti_patterns>` section.** Added 7 anti-patterns after `<role>`, matching the 5-8 item range used by role contracts. Each maps to a real workflow gate (plan preview, file verification, max 2 questions, no APPROACH.md, no ROADMAP/SPEC updates, config.json reads, no scope expansion). This is the single highest-value context engineering improvement — it gives agents explicit "don't do this" guardrails for the workflow's most critical gates.
+
+**Change 2: Authority language normalization.** `**MANDATORY:**` → `**STOP.**` on 2 of 3 file-verification gates. DISTILLATION.md resolves authority language vocabulary: CRITICAL for initial-read gates, normal imperative language for process gates. STOP is the correct word for "halt and check" gates; MANDATORY is not in the resolved vocabulary.
+
+**What was investigated but NOT changed:**
+
+| Finding | Decision | Why |
+|---------|----------|-----|
+| Steps use markdown headers, not XML `<step>` tags | Keep markdown headers | All 10 GSDD workflows use the same pattern. prompty's agentskit-architect SKILL.md uses the identical pattern (single `<algorithm>` container with text step labels). Changing quick.md alone creates cross-workflow inconsistency. Candidate for a future cross-workflow PR. |
+| No `<output_contract>` section | Not needed | `<completion>` section already specifies what the workflow produces — paths, status, next steps |
+| No `<input_contract>` section | Not needed | `<prerequisites>` section already covers required preconditions |
+| No progressive disclosure restructuring | Not needed | ~350 lines is within the agentskills.io 500-line recommended limit |
+| Caching-friendly ordering | Already correct | Static content (role, anti_patterns, prerequisites) at top, variable content (process steps) below |
+
+**Evidence:**
+
+| Source | Contribution |
+|--------|-------------|
+| Anthropic Claude Prompting Best Practices [S1] | "Claude has been specifically tuned to pay special attention to your structure when using XML tags." Validates XML for section boundaries. Anti-patterns placed early for attention weight. |
+| DISTILLATION.md (GSDD internal) | "Anti-patterns early — Place 'don't do this' instructions near the top, after role definition." Cross-source validated pattern across all 9 role contracts. Authority language resolution: CRITICAL for initial-read, normal language elsewhere. |
+| Selective Prompt Anchoring, arxiv 2408.09121 (2024) | Up to 12.9% Pass@1 improvement from strategic attention anchoring. XML tags create hard attention boundaries; markdown headers may be treated as content formatting. |
+| agentskit-architect SKILL.md (prompty) | Uses single `<algorithm>` container with text step labels inside — same structural pattern as GSDD's `<process>` with markdown headers. Validates the hybrid XML-outer/markdown-inner approach. |
+| Manus AI Context Engineering [S5] | "Filesystem as extended context" — structural quality of prompt files directly impacts agent behavior. Validates treating workflow files as engineered artifacts, not documentation. |
+| agentskit-evaluator SKILL.md (prompty) | Authority language audit: "CRITICAL only for gates?" is a scored compliance check. Validates normalizing gate vocabulary. |
+
+**Scope:** quick.md only. If `<anti_patterns>` proves valuable for orchestrators, extend to plan.md and other workflows in a follow-up PR.
+
+**GSDD implementation:** `distilled/workflows/quick.md` (`<anti_patterns>` section, STOP normalization), `distilled/DESIGN.md` (this section), `tests/gsdd.guards.test.cjs` (G26 assertions for anti_patterns placement, content, gate language consistency, XML structural sections)
+
+---
+
+## 35. Skills-Native Runtimes vs Governance Adapters
+
+**Problem:** Repo surfaces had started conflating two different questions:
+1. Does the runtime discover `.agents/skills/` natively?
+2. What extra generated adapter artifact does `gsdd init --tools <runtime>` add?
+
+That conflation was survivable while Cursor and Copilot were incorrectly treated as governance-first tools, but it became actively misleading once live testing proved they were skills-native. Gemini then moved into the same bucket via user-performed live validation on 2026-03-25. The old grouped README / AGENTS wording wrongly implied the root `AGENTS.md` block was required for workflow discovery on those runtimes.
+
+**Decision:** Separate runtime capability from generated adapter artifact kind.
+
+- Cursor, Copilot, and Gemini are documented as **skills-native runtimes**: they discover `.agents/skills/gsdd-*` and surface the workflows directly as slash commands.
+- `--tools cursor`, `--tools copilot`, `--tools gemini`, and `--tools agents` still generate the same root `AGENTS.md` bounded block, but that artifact is **governance only**.
+- The root `AGENTS.md` block remains valuable behavioral discipline, but it must not be described as the workflow-discovery mechanism for a skills-native runtime.
+- No new runtime-specific adapter files are introduced just to make the docs read cleaner. The generated artifact model stays simple unless a stronger runtime-specific UX is actually needed.
+
+**Why this fits the architecture:** The adapter code already had the right implementation shape: one shared root-governance generator (`createRootAgentsAdapter`) with different runtime labels. The bug was the capability story wrapped around it. Fixing the narrative without inventing redundant adapter files preserves leverage and keeps the portable `.agents/skills/` surface as the canonical entry layer.
+
+**Evidence:**
+
+1. Live consumer testing (2026-03-20) proved Cursor and Copilot auto-discover `.agents/skills/` and expose slash commands without AGENTS.md.
+2. User-performed live validation (2026-03-25) confirmed the same behavior for Gemini.
+3. GSDD implementation already always generates `.agents/skills/` and uses the root `AGENTS.md` block as a bounded governance upsert, not as a workflow source.
+4. This resolution matches the repo rule that skills, adapters, and governance surfaces must not be conflated.
+
+**GSDD implementation:** `README.md`, `distilled/templates/agents.block.md`, `bin/lib/init.mjs`, `SPEC.md`, `.internal-research/TODO.md`, `.internal-research/gaps.md`, `.internal-research/lessons-learned.md`, `tests/gsdd.guards.test.cjs`
+
+---
+
+## 36. Interactive Init Wizard
+
+**Problem:** `gsdd init` had two mismatched onboarding models at once. The public story was moving toward skills-native runtimes and optional governance, but the actual CLI still made users memorize `--tools ...` values as the primary install experience. The only interactive part was the config questionnaire, which started after filesystem writes and did not help the user decide which runtime surfaces or governance overlays to install.
+
+**Decision:** Make `gsdd init` a guided install wizard in TTY environments, while preserving `--tools` and `--auto` as the manual/headless contract.
+
+- Step 1: choose runtimes/vendors with a simple checkbox-style selector (space toggles, enter confirms).
+- Step 2: ask separately whether to install repo-wide `AGENTS.md` governance, with explicit explanation of why it helps and why it may feel invasive.
+- Step 3: collect the existing planning defaults in the same guided flow instead of dropping back to free-form line prompts.
+- Portable `.agents/skills/gsdd-*` skills remain the always-generated baseline.
+- Legacy values such as `--tools cursor`, `--tools copilot`, and `--tools gemini` remain valid for backward compatibility.
+
+**Key architectural rule:** runtime selection and adapter generation are separate concerns.
+
+- In the wizard, choosing Cursor/Copilot/Gemini affects post-init routing and user-facing install intent, but does **not** silently write root `AGENTS.md`.
+- Root `AGENTS.md` is generated only when the user explicitly opts into governance (wizard) or explicitly requests a governance-writing flag path (`--tools agents`, `--tools all`, or legacy runtime aliases).
+- This keeps D35's capability split honest instead of re-conflating skills-native runtime choice with governance-file generation.
+
+**Why this fits the codebase:** The adapter registry and `init.mjs` already own the right boundary. The high-leverage change was to add a decision layer in front of writes, not to invent a new adapter model or a new config schema. This keeps the CLI lightweight, preserves backward compatibility, and makes the default install path match the product story.
+
+**Evidence:**
+
+1. Existing repo truth: `gsdd init` always generates `.agents/skills/` and already has a central adapter-selection seam in `bin/lib/init.mjs`.
+2. Local research on the adjacent `prompty` repo: portable skills are the primary install surface, while native command surfaces are optional additions.
+3. Common CLI onboarding pattern: modern project bootstrap tools use interactive setup by default and flags for headless/manual flows; GSDD now matches that expectation without dropping its automation path.
+4. Repo lesson LL-INSTALL-DX-BEFORE-ALIAS-CLEANUP already recorded that install ergonomics should be fixed before alias-policy cleanup.
+
+**GSD comparison:** GSD's install surface is more operator-heavy and framework-specific. GSDD keeps the deterministic bootstrap principle but shifts the user-facing choice surface into a lightweight guided CLI instead of requiring users to know adapter values in advance.
+
+**GSDD implementation:** `bin/lib/init.mjs`, `bin/gsdd.mjs`, `README.md`, `distilled/README.md`, `SPEC.md`, `.internal-research/TODO.md`, `.internal-research/gaps.md`, `.internal-research/lessons-learned.md`, `tests/gsdd.init.test.cjs`, `tests/gsdd.guards.test.cjs`
+
+---
+
+## 37. Mutability-Driven Workflow Classification
+
+**Problem:** GSDD had started treating several artifact-writing workflows as planning-class surfaces in the workflow registry. That looked semantically neat (`new-project`, `plan`, `verify`, `audit-milestone`, `pause`, `resume` all sound like "thinking" work), but it created a runtime contradiction: the workflow contract required disk persistence while the generated surface could be interpreted as a read-only planning lane.
+
+**Decision:** Classify workflow surfaces by mutability, not by whether the workflow feels like planning.
+
+- Any workflow that writes or deletes durable artifacts emits `agent: Code` and `opencodeType: edit`.
+- Only truly read-only workflows emit `agent: Plan` and `opencodeType: plan`.
+- `progress` remains the only read-only workflow in the current lifecycle.
+- The registry now records this explicitly via `mutatesArtifacts` so future changes have an inspectable invariant instead of relying on naming intuition.
+
+**Why this fits the codebase:** GSDD's real leverage depends on docs-to-disk persistence. `new-project`, `plan`, `verify`, `audit-milestone`, `pause`, and `resume` are orchestration-heavy, but they are still state-changing workflows. Treating them as read-only breaks the artifact chain that downstream workflows consume.
+
+**Kept / stripped / gained relative to the previous state:**
+
+- **Kept:** the existing portable workflow content, native plan-checker surfaces, and the distinction between read-only reporting (`progress`) and artifact-producing lifecycle work.
+- **Stripped:** the informal assumption that "planning-like" workflows should all share the `Plan` lane.
+- **Gained:** an explicit mutability invariant, generated-surface tests, and safer behavior in runtimes that enforce planning/read-only execution semantics.
+
+**Evidence:**
+
+1. `distilled/workflows/verify.md`, `new-project.md`, `audit-milestone.md`, `pause.md`, and `resume.md` all require artifact writes or deletions as part of completion.
+2. `distilled/workflows/progress.md` is the only workflow that explicitly declares itself read-only.
+3. Consumer audit evidence already showed verification reports being lost when persistence was skipped; this decision closes the registry seam that could recreate the same class of failure.
+
+**GSD comparison:** GSD's leverage also depends on persisted workflow artifacts. GSDD's portable/runtime split adds a new failure mode GSD did not have in the same form: a generated adapter can misclassify a mutating workflow even when the markdown contract is correct. This decision makes the adapter/runtime layer honor the artifact contract instead of undermining it.
+
+**GSDD implementation:** `bin/gsdd.mjs`, `bin/lib/rendering.mjs`, `tests/gsdd.init.test.cjs`, `tests/gsdd.plan.adapters.test.cjs`, `tests/gsdd.guards.test.cjs`, `SPEC.md`, `.internal-research/TODO.md`, `.internal-research/gaps.md`, `.internal-research/lessons-learned.md`
+
+---
+
 ## Maintenance
 
 This document is updated when: