gsdd-cli 0.2.0 → 0.3.1

package/distilled/DESIGN.md

@@ -37,6 +37,14 @@
 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)
 
 ---
 
@@ -1348,6 +1356,284 @@ Isolating research in subagents and returning compressed summaries follows the C
 
 ---
 
+## 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:

package/distilled/README.md

@@ -18,21 +18,25 @@ Run in your project root:
 npx gsdd-cli init
 ```
 
+In a TTY, `gsdd init` now opens a guided install wizard: choose runtimes first, then decide separately whether repo-wide `AGENTS.md` governance is worth installing.
+
 Optional adapters:
 ```bash
 npx gsdd-cli init --tools claude
 npx gsdd-cli init --tools opencode
 npx gsdd-cli init --tools codex
 npx gsdd-cli init --tools agents
+npx gsdd-cli init --tools cursor
 npx gsdd-cli init --tools all
 ```
 
 Notes:
 - `gsdd init` always generates open-standard skills at `.agents/skills/gsdd-*`. This is also the primary Codex CLI surface.
+- `--tools ...` remains the manual/headless path; legacy runtime aliases such as `cursor`, `copilot`, and `gemini` are still supported for backward compatibility.
 - `--tools claude` also generates native agents at `.claude/agents/gsdd-*.md` and a compatibility plan command alias at `.claude/commands/gsdd-plan.md`.
 - `--tools opencode` also generates native agents at `.opencode/agents/gsdd-*.md`.
 - `--tools codex` generates `.codex/agents/gsdd-plan-checker.toml`; the portable `.agents/skills/gsdd-plan/` surface remains the Codex entry path.
-- Root `AGENTS.md` is only written when explicitly requested (`--tools agents` or `--tools all`).
+- Root `AGENTS.md` is only written when explicitly requested (`--tools agents`, `--tools all`, legacy runtime aliases, or the wizard governance opt-in).
 
 ## The Workflow
 
@@ -126,7 +130,7 @@ Note: `parallelization: false` keeps the same mapper/researcher set but runs the
 
 ```
 distilled/
-  DESIGN.md                # design decisions and rationale (29 decisions, evidence-backed)
+  DESIGN.md                # design decisions and rationale (36 decisions, evidence-backed)
   SKILL.md                 # primary entry point (plain markdown)
   workflows/
     new-project.md

package/distilled/templates/agents.block.md

@@ -83,8 +83,10 @@ If you are not confident about a domain/library/pattern:
 
 How you run these workflows depends on your tool:
 
-- **Claude Code / OpenCode:** Use slash commands — `/gsdd-new-project`, `/gsdd-plan`, `/gsdd-execute`, etc.
+- **Claude Code / OpenCode / Cursor / Copilot / Gemini:** Use slash commands — `/gsdd-new-project`, `/gsdd-plan`, `/gsdd-execute`, etc.
 - **Codex CLI:** Use skill references — `$gsdd-new-project`, `$gsdd-plan`, `$gsdd-execute`, etc.
-- **All other tools (Cursor, Copilot, Gemini, any AI agent):** Open the SKILL.md file listed above and follow its instructions. This AGENTS.md governance block keeps the agent aligned with GSDD discipline.
+- **Other AI tools:** Open the SKILL.md file listed above and follow its instructions.
+
+If this root `AGENTS.md` block is present in a Cursor, Copilot, or Gemini project, treat it as behavioral governance on top of the runtime's native slash-command discovery. Do not treat this file as the mechanism that makes the workflows discoverable.
 
 Start with the new-project workflow to produce `.planning/SPEC.md` and `.planning/ROADMAP.md`.

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

@@ -22,6 +22,10 @@ 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.
@@ -36,7 +40,7 @@ Return JSON only as a single object with this shape:
   "summary": "One sentence overall assessment",
   "issues": [
     {
-      "dimension": "requirement_coverage | approach_alignment",
+      "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

@@ -340,7 +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. `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.
+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
 
@@ -359,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 | approach_alignment",
+         "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",