gsdd-cli 0.2.0 → 0.16.1

package/distilled/DESIGN.md

@@ -3,6 +3,9 @@
 > Rationale for every structural choice GSDD makes relative to GSD.
 > Each decision cites GSD source files, GSDD implementation, and external research.
 > Updated as decisions are revised or new ones land.
+>
+> **Evidence index:** `distilled/EVIDENCE-INDEX.md` — one-line-per-source mapping for all decisions.
+> **Open gaps:** `.internal-research/gaps.md` — live blockers, contradictions, and deferred decisions.
 
 ---
 
@@ -37,6 +40,16 @@
 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)
+38. [Retroactive Artifact Enforcement](#38-retroactive-artifact-enforcement)
+39. [Brownfield Entry Wiring](#39-brownfield-entry-wiring)
 
 ---
 
@@ -60,8 +73,8 @@
 
 - GSD source: `agents/_archive/gsd-codebase-mapper.md` lines 72-79 (original 7-file model)
 - GSDD implementation: `agents/mapper.md` input/output contracts (4 files only)
-- External: LeanSpec "Context Economy" principle; Aider tree-sitter dynamic repomaps (2026 SOTA)
 - `.planning/SPEC.md` "Lean Context Decision" section
+- External: Liu et al. "Lost in the Middle: How Language Models Use Long Contexts" (NeurIPS 2023) — position in context significantly affects recall; middle content is underweighted, supporting minimal stable file sets; Levy et al. "Same Task, More Tokens: Impact of Input Length on the Reasoning Performance of LLMs" (EMNLP 2024) — longer inputs degrade reasoning performance; Aider tree-sitter dynamic repo maps (aider.chat) — on-demand structural mapping as an alternative to static context files
 
 ---
 
@@ -151,6 +164,7 @@ This hardening pass also clarified a reusable architectural rule: strict portabl
 - GSD originals preserved in `agents/_archive/` (11 files, git history intact via `git mv`)
 - GSDD canonicals in `agents/` (9 files + README.md)
 - `agents/README.md` lifecycle table maps each canonical role to its GSD sources
+- External: CrewAI role-based team patterns, Microsoft AutoGen hierarchical agents, LangGraph multi-agent subgraphs — all validate role specialization over monolithic agents; specific count of 10 is engineering judgment shaped by GSD source lineage, not an externally prescribed number
 
 ---
 
@@ -197,6 +211,7 @@ This hardening pass also clarified a reusable architectural rule: strict portabl
 - `bin/gsdd.mjs` lines 84-102 (role copy step with existsSync guard)
 - `tests/gsdd.init.test.cjs` (validates role file existence and delegate-role references)
 - All 10 delegate files (each starts with a role contract reference on line 1)
+- External: Principal-agent theory (Jensen & Meckling, Journal of Financial Economics 1976) — the foundational model of delegation contracts where principals define behavioral constraints and agents execute within them; GoF Strategy Pattern (Gamma et al. "Design Patterns" 1994) — separating algorithm definition (role) from its usage context (delegate); LangGraph multi-agent subgraphs and Microsoft AutoGen hierarchical agent patterns validate role/orchestration separation in production AI systems
 
 ---
 
@@ -237,6 +252,7 @@ This hardening pass also clarified a reusable architectural rule: strict portabl
 - PR 2 intermediate state (one-hop via SKILL.md cross-reference)
 - PR 4 final state (zero-hop, role contains all rules)
 - `package.json` `files` array includes `agents/` (npm distribution fix)
+- External: OWASP Top 10 for LLM Applications v2.0 (2025) — LLM01 (Prompt Injection) and LLM07 (System Prompt Leakage) directly support embedding security rules at the role contract level; Greshake et al. "Not What You've Signed Up For: Compromising Real-World LLM-Integrated Applications with Indirect Prompt Injection" (IEEE S&P 2023) — validates defense-in-depth at the agent-contract layer; Saltzer & Schroeder "The Protection of Information in Computer Systems" (1975) — complete mediation principle: every access must be checked against the access control policy
 
 ---
 
@@ -260,6 +276,7 @@ This hardening pass also clarified a reusable architectural rule: strict portabl
 - GSDD: `distilled/templates/delegates/researcher-synthesizer.md` (active delegate, references `synthesizer.md`)
 - `agents/synthesizer.md` canonical contract (cross-reference algorithm)
 - Config contract: `.planning/config.json` `researchDepth` field
+- External: LangGraph conditional edges — adaptive agent invocation based on workflow state is a core LangGraph pattern; Asai et al. "Self-RAG: Learning to Retrieve, Generate, and Critique through Self-Reflection" (ICLR 2024) — validates conditional retrieval/synthesis based on whether additional context is needed; Anthropic "Building effective agents" (Dec 2024) — routing workflows match task complexity to agent selection
 
 ---
 
@@ -271,7 +288,7 @@ This hardening pass also clarified a reusable architectural rule: strict portabl
 
 1. **On first brownfield init:** `new-project.md` detects source files, offers codebase mapping. If accepted, invokes `map-codebase` via the portable skill surface (`.agents/skills/gsdd-map-codebase/SKILL.md`).
 
-2. **On subsequent runs:** If `.planning/codebase/` already exists, mappers are skipped during init. User runs `/gsdd:map-codebase` directly to trigger the Refresh/Update/Skip flow.
+2. **On subsequent runs:** If `.planning/codebase/` already exists, mappers are skipped during init. User runs `/gsdd-map-codebase` directly to trigger the Refresh/Update/Skip flow.
 
 **Why standalone:** Codebase maps become stale after major refactors. Users need to refresh maps independently of project initialization. Embedding mapping inside init would force a full re-init to refresh maps.
 
@@ -289,6 +306,7 @@ This hardening pass also clarified a reusable architectural rule: strict portabl
 - GSD source: `get-shit-done/workflows/new-project.md` lines 61-80 (brownfield offer delegates to map-codebase)
 - GSDD: `distilled/workflows/map-codebase.md` (standalone, re-runnable)
 - GSDD: `distilled/workflows/new-project.md` (auto-invoke for brownfield via skill reference)
+- External: Aider (aider.chat) uses dynamic tree-sitter-based repo maps generated on-demand rather than persistent cached indices — validates the freshness-over-cache approach; Cursor uses continuous background indexing (cached approach) showing both on-demand and cached are production-valid; on-demand is one defensible point on the freshness-vs-staleness-cost spectrum
 
 ---
 
@@ -318,6 +336,7 @@ This hardening pass also clarified a reusable architectural rule: strict portabl
 - GSD source: `get-shit-done/workflows/new-milestone.md` lines 101-173 (milestone-aware researchers), line 269 (phase numbering continuation)
 - GSDD: `distilled/README.md` lifecycle diagram
 - `.planning/SPEC.md` "Long-Term Lifecycle" section
+- External: Hierarchical Task Network (HTN) planning (Erol, Hendler & Nau 1994; Nau et al. JAIR 2003) — foundational AI planning literature establishing milestone→phase→task decomposition as the standard approach for complex goal hierarchies; PMI PMBOK Work Breakdown Structure (WBS) standard — industry-standard phase/task hierarchy for project planning; Khot et al. "Decomposed Prompting: A Modular Approach for Solving Complex Tasks" (ICLR 2023) — task decomposition improves LLM performance on multi-step work by reducing scope per subproblem
 
 ---
 
@@ -347,6 +366,7 @@ This hardening pass also clarified a reusable architectural rule: strict portabl
 - GSD source: `agents/_archive/gsd-executor.md` (mandatory commit in algorithm, TDD flow)
 - GSDD: `agents/executor.md` lines 57-64 (Git Guidance -- repo-native, advisory)
 - PR 5 (merged as PR #7): removed rigid git naming from workflows, adapters, generated governance
+- External: Industry consensus — Aider, GitHub Copilot, Cursor, Codex CLI, and OpenCode all treat git operations as user-controlled or advisory, not as enforced framework requirements; no major AI coding tool mandates a specific commit-per-task or branch-naming convention
 
 ---
 
@@ -462,6 +482,7 @@ Codex is skills-first because the Codex CLI already supports repository skills d
 - D7 (milestone hierarchy): STATE.md replaced by ROADMAP.md inline status
 - D8 (advisory git): repo conventions over framework defaults
 - D10 (context isolation): summaries up, documents to disk
+- External: Crystal Clear (Cockburn 2004) — ceremony scales with team size and criticality; lightweight methods are prescribed for small, co-located, low-criticality work; Kanban class-of-service (Anderson 2010) — routing tasks by size/urgency to appropriate workflow lanes; Anthropic "Building effective agents" (Dec 2024) — match workflow complexity to actual task complexity rather than applying uniform ceremony
 
 ---
 
@@ -782,13 +803,16 @@ dispatch in a single file.
 
 Implementation lives under `bin/lib/`:
 - `cli-utils.mjs` owns flag parsing and JSON output helpers
+- `file-ops.mjs` owns workspace-confined deterministic file copy, delete, and regex-sub mechanics
 - `models.mjs` owns config/model schema and `cmdModels`
-- `phase.mjs` owns phase discovery, verify, and scaffold commands
+- `phase.mjs` owns phase discovery, verify, scaffold, and the status-aware ROADMAP phase helper
 - `templates.mjs` owns template/role install and refresh flows
 - `init.mjs` owns `createCmdInit(ctx)`, `createCmdUpdate(ctx)`, help text, and bootstrap/update helper logic
 
 **Boundary rules:**
 - keep `bin/gsdd.mjs` as composition root, not a second implementation module
+- route deterministic copy/delete/text-mutation mechanics through CLI helpers instead of leaving manual file edits in workflow prose
+- keep ROADMAP phase checkbox transitions in a status-aware helper; broader roadmap rewrites stay outside this helper boundary
 - keep config-schema ownership in `models.mjs`; do not duplicate or relocate `buildDefaultConfig` into `init.mjs`
   just to satisfy an old task list
 - let `init` use the same template-sync module that `update --templates` uses, instead of maintaining separate
@@ -804,9 +828,10 @@ Implementation lives under `bin/lib/`:
 
 **Evidence:**
 - GSD source: `get-shit-done/install.js` (monolithic install/conversion surface)
-- GSDD implementation: `bin/gsdd.mjs`, `bin/lib/init.mjs`, `bin/lib/templates.mjs`, `bin/lib/models.mjs`
+- GSDD implementation: `bin/gsdd.mjs`, `bin/lib/init.mjs`, `bin/lib/templates.mjs`, `bin/lib/models.mjs`, `bin/lib/file-ops.mjs`, `bin/lib/phase.mjs`
 - GSDD tests: `tests/gsdd.init.test.cjs`, `tests/gsdd.models.test.cjs`, `tests/gsdd.manifest.test.cjs`,
-  `tests/gsdd.guards.test.cjs`
+  `tests/gsdd.guards.test.cjs`, `tests/phase.test.cjs`, `tests/gsdd.invariants.test.cjs`, `tests/gsdd.scenarios.test.cjs`
+- External: Seemann "Dependency Injection in .NET" (Manning 2011) — coined "Composition Root" as the named pattern for the single location where the entire application is assembled; Martin "Clean Architecture" (2017) — the main component as the outermost, dirtiest layer that owns all wiring; standard practice in oclif, Commander.js, yargs, and Cobra CLI frameworks
 
 ---
 
@@ -893,7 +918,7 @@ Implementation lives under `bin/lib/`:
 
 **GSD:** `health.md` (157 lines) — calls `gsd-tools.cjs validate health [--repair]`, parses JSON with error codes E001-E005/W001-W007, supports `--repair` flag for createConfig/resetConfig/regenerateState repair actions.
 
-**GSDD:** `gsdd health` CLI command (~150 lines in `bin/lib/health.mjs`). Factory function `createCmdHealth(ctx)` returning an async command. No `--repair` flag — fixes are documented as actionable instructions, not automated mutations. GSDD already has `gsdd init` and `gsdd update --templates` as the repair paths; a separate repair mode would duplicate those commands.
+**GSDD:** `gsdd health` CLI command (`bin/lib/health.mjs` + `bin/lib/health-truth.mjs`). Factory function `createCmdHealth(ctx)` returning an async command. No `--repair` flag — fixes are documented as actionable instructions, not automated mutations. GSDD already has `gsdd init` and `gsdd update --templates` as the repair paths; a separate repair mode would duplicate those commands.
 
 **Check categories:**
 
@@ -904,12 +929,19 @@ Implementation lives under `bin/lib/`:
 | E3 | ERROR | `.planning/templates/` missing |
 | E4 | ERROR | `.planning/templates/roles/` missing or empty |
 | E5 | ERROR | `.planning/templates/delegates/` missing or empty |
+| E6 | ERROR | `.planning/templates/research/` missing or empty |
+| E7 | ERROR | `.planning/templates/codebase/` missing or empty |
+| E8 | ERROR | `.planning/templates/` missing critical root files (`spec.md`, `roadmap.md`, `auth-matrix.md`) |
 | W1 | WARN | `generation-manifest.json` missing |
 | W2 | WARN | Template files modified locally (hash mismatch vs manifest) |
 | W3 | WARN | Template/role files missing from disk but listed in manifest |
-| W4 | WARN | ROADMAP.md references phases not found in `.planning/phases/` |
+| W4 | WARN | Active non-archived phases marked in progress/done are missing from `.planning/phases/` |
 | W5 | WARN | Phase artifact set has PLAN but no matching SUMMARY (stale in-progress) |
 | W6 | WARN | No adapter surfaces detected |
+| W7 | WARN | `distilled/DESIGN.md` health check table differs from implemented check IDs |
+| W8 | WARN | `distilled/README.md` workflow inventory differs from `distilled/workflows/` |
+| W9 | WARN | `.internal-research/gaps.md` references missing repo-local paths |
+| W10 | WARN | `.planning/ROADMAP.md` phase status differs from `.planning/SPEC.md` requirement checkboxes |
 | I1 | INFO | Generation manifest `frameworkVersion` differs from current `FRAMEWORK_VERSION` |
 | I2 | INFO | Phase completion count from ROADMAP |
 | I3 | INFO | Which adapters are installed |
@@ -931,11 +963,15 @@ Implementation lives under `bin/lib/`:
 
 3. **Pre-init guard.** If `.planning/config.json` doesn't exist, output a one-line message and exit 1. No partial checks — the workspace is simply not initialized.
 
-4. **Reuses existing modules.** `readManifest()` and `detectModifications()` from `manifest.mjs` handle W1-W3. `isProjectInitialized()` pattern from `models.mjs` handles the pre-init guard. No new utility functions.
+4. **Split structural vs truth checks.** `bin/lib/health.mjs` keeps the structural workspace checks. `bin/lib/health-truth.mjs` holds the always-on cross-file truth checks (W7-W10) so the health surface can grow without turning the main command into one monolith.
+
+5. **Reuses existing modules.** `readManifest()` and `detectModifications()` from `manifest.mjs` handle W1-W3. `isProjectInitialized()` pattern from `models.mjs` handles the pre-init guard. Truth checks stay read-only and operate on repo-local artifacts only when those framework files exist.
+
+6. **Framework-source mode skips installed-project template checks.** Inside the GSDD framework repo itself, `distilled/templates/` is the source of truth and `.planning/templates/` is intentionally absent. `gsdd health` therefore skips the installed-project template/manifest checks (E3-E8, W1-W3) in framework-source mode instead of producing false positives during self-health runs.
 
 **What was removed vs GSD:**
 - `--repair` flag and associated repair actions
-- Error codes E001-E005/W001-W007 (replaced with simpler E1-E5/W1-W6/I1-I3)
+- Error codes E001-E005/W001-W007 (replaced with simpler E1-E8/W1-W10/I1-I3)
 - STATE.md checks (GSDD has no STATE.md per D7)
 - PROJECT.md checks (GSDD uses SPEC.md, not checked by health — it's workflow-authored)
 - Phase directory naming format checks (GSDD uses flat numbered files, not NN-name directories)
@@ -948,7 +984,7 @@ Implementation lives under `bin/lib/`:
 - External audit (2026-03-13): recommendation #3 "Add just enough: status/resume/progress/health"
 - External audit (2026-03-17): "You probably do need a minimal health surface, but not GSD's full style"
 - PR #32: pre-init guard bug proved workspace integrity issues are real, not theoretical
-- GSDD implementation: `bin/lib/health.mjs`, `bin/gsdd.mjs`, `tests/gsdd.health.test.cjs`, `tests/gsdd.guards.test.cjs` (G14)
+- GSDD implementation: `bin/lib/health.mjs`, `bin/lib/health-truth.mjs`, `bin/gsdd.mjs`, `tests/gsdd.health.test.cjs`, `tests/gsdd.guards.test.cjs` (G14)
 
 ---
 
@@ -1115,41 +1151,39 @@ This is acceptable because:
 
 ## 24. Consumer Governance Completeness
 
-**Problem:** Consumer governance surfaces (`agents.block.md`) listed only 4 of 10 delivered workflows. When a consumer ran `gsdd init --tools agents`, the generated AGENTS.md told the agent about new-project, plan, execute, and verify -- but audit-milestone, quick, pause, resume, progress, and map-codebase were invisible. AI agents working in consumer projects could not discover 60% of the available workflows.
+**Problem:** Consumer governance surfaces were oscillating between two failure modes. The earlier block was too thin and hid core lifecycle entry points. The later block over-corrected into a long wall that tried to enumerate every delivered workflow, which made first-run `AGENTS.md` too heavy for a stranger to scan quickly.
 
-**GSDD decision:** Consumer governance surfaces must enumerate all delivered capabilities. Governance maps that omit delivered workflows are functionally broken -- agents cannot use what they cannot discover.
+**GSDD decision:** Consumer-generated `AGENTS.md` must be complete for the primary lifecycle, not exhaustive for the whole framework. The generated governance surface is a routing map for the core path (`new-project -> plan -> execute -> verify -> progress`) plus the durable location of the portable skills. Secondary workflows remain discoverable through `.agents/skills/gsdd-*/SKILL.md`, but they do not all need to be listed inline in the short generated file.
 
 **What changed:**
 
-- `agents.block.md` now lists all 10 workflow skills, organized by function (primary lifecycle + supporting workflows)
-- Lifecycle description updated to mention audit-milestone and supporting surfaces
-- 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)
+- `agents.block.md` now names the five core lifecycle skills explicitly instead of trying to inline all workflow inventory
+- The lifecycle line still anchors the full flow through `audit-milestone`, but the generated block stays routing-first and compact
+- The block tells agents where the full portable workflow set lives: `.agents/skills/gsdd-*/SKILL.md`
+- Guard coverage now enforces the compact contract instead of exhaustive inventory in the generated file
 
-**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.
+**Why this is high-leverage:** Consumer `AGENTS.md` is read at the exact moment a stranger is deciding whether the framework is legible. The file has to preserve load-bearing routing while staying short enough to scan. Exhaustive workflow inventory belongs in the durable skills directory and public docs, not in the first-run governance block.
 
 **Evidence:**
 
-- Anthropic, "Effective harnesses for long-running agents" (2026): harnesses must provide comprehensive, discoverable context; incomplete maps cause agent failure
-- Agent Skills specification (agentskills.io): progressive disclosure requires a complete top-level map
-- HumanLayer, "Skill Issue" (2026): AGENTS.md should be a short map (~100 lines) that points to all available capabilities
-- OpenAI, "Harness Engineering" (2026): the harness determines whether agents succeed or fail
-- External audits (2026-03-13, 2026-03-17): both independently flagged documentation accuracy as the top remaining blocker for consumer adoption
-- GSDD implementation: `distilled/templates/agents.block.md`, `CHANGELOG.md`, `README.md`, `tests/gsdd.guards.test.cjs` (G18)
+- HumanLayer, "Skill Issue" (2026): AGENTS.md works best as a short routing map, not a full product manual
+- OpenAI, "Harness Engineering" (2026): the harness should surface the critical path clearly at the moment of action
+- Phase 17 repo proof: `tests/gsdd.consumer-ceremony.test.cjs` now asserts the generated consumer file stays within 15-25 lines while preserving core routing hints and portable-skill discovery
+- GSDD implementation: `distilled/templates/agents.block.md`, `distilled/templates/agents.md`, `tests/gsdd.consumer-ceremony.test.cjs`, `tests/gsdd.guards.test.cjs`
 
 ---
 
 ## 25. Consumer First-Run Experience
 
-**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.
+**Problem:** GSDD's internal architecture was stronger than its first-run UX. The framework had the right runtime surfaces and workflow depth, but consumer onboarding still felt like an internal tool: too many init questions, too much generated governance text, and not enough immediate clarity about the next step.
 
-**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.
+**Decision:** Keep launch-proof posture in public docs and install/help surfaces, while making the actual first-run experience intentionally lightweight: a guided init wizard with only load-bearing choices, explicit post-init summary output, and a compact generated governance block focused on the core path.
 
 **Key changes:**
-- Platform adapter table uses honest capability tiers (native vs governance) instead of aspirational labels (skill_aware, custom_command_aware)
-- Post-init CLI output shows platform-specific next-step commands
-- AGENTS.md governance block includes per-platform invocation guide
-- Quickstart section provides a guided first-use flow
+- Interactive init now asks only five visible questions: runtimes, AGENTS governance, rigor, cost, and whether to track `.planning/` in git
+- Init prints a short summary showing the selected rigor/cost defaults and the core workflow route
+- AGENTS.md governance stays focused on invocation guidance, the governance-vs-discovery boundary, and the core lifecycle rather than launch-proof copy or exhaustive inventory
+- Quickstart and public docs still carry the broader platform and proof story
 
 **Evidence:**
 1. **Anthropic harness engineering** (2025-2026): "honest constraints over vague prompting" — harnesses should clearly communicate what they can and cannot enforce
@@ -1158,7 +1192,7 @@ This is acceptable because:
 4. **Martin Fowler on context engineering**: Emphasizes that "the right information at the right time" applies to human consumers as much as to AI agents
 5. **Both GSDD external audits** (March 13 + 17, 2026): Independently concluded the same gap — "architecture is solid, presentation lags implementation"
 
-**GSDD implementation:** `README.md` (quickstart, honest platform tiers), `distilled/templates/agents.block.md` (per-platform invocation guide), `bin/lib/init.mjs` (platform-aware post-init routing), `tests/gsdd.guards.test.cjs` (G19)
+**GSDD implementation:** `README.md` (quickstart, honest platform tiers), `distilled/templates/agents.block.md` (compact governance plus governance/discovery boundary), `bin/lib/init-flow.mjs` (post-init summary), `bin/lib/init-prompts.mjs` (5-prompt guided flow), `tests/gsdd.consumer-ceremony.test.cjs`, `tests/gsdd.guards.test.cjs`
 
 ---
 
@@ -1209,7 +1243,7 @@ D12 established the session persistence design. D26 mechanically enforces the ro
 
 ## 28. Workflow Completion Routing
 
-**Problem:** Consumer testing (2026-03-21) revealed that AI agents completing a GSDD workflow go silent — the user must manually figure out which `/gsdd:*` command to run next. The lifecycle contract (`new-project → plan → execute → verify → [next phase]`) was correct in design but invisible in practice at each step boundary. GSD original solved this with explicit "Next Up" sections at the end of every workflow; GSDD lost this pattern during distillation.
+**Problem:** Consumer testing (2026-03-21) revealed that AI agents completing a GSDD workflow go silent — the user must manually figure out which `/gsdd-*` command to run next. The lifecycle contract (`new-project → plan → execute → verify → [next phase]`) was correct in design but invisible in practice at each step boundary. GSD original solved this with explicit "Next Up" sections at the end of every workflow; GSDD lost this pattern during distillation.
 
 **Decision:** Add `<completion>` sections after `<success_criteria>` in all 9 terminal workflows. Add positional discipline gates (STOP instructions at exact deviation points) and mandatory persistence enforcement for critical artifacts.
 
@@ -1231,10 +1265,10 @@ Report to the user what was accomplished, then present the next step:
 ---
 **Completed:** [what finished]
 
-**Next step:** `/gsdd:[command]` — [description]
+**Next step:** `/gsdd-[command]` — [description]
 
 Also available:
-- `/gsdd:[alt]` — [description]
+- `/gsdd-[alt]` — [description]
 
 Consider clearing context before starting the next workflow for best results.
 ---
@@ -1242,15 +1276,15 @@ Consider clearing context before starting the next workflow for best results.
 ```
 
 **Routing map (acyclic, complete):**
-- `new-project` → `/gsdd:plan`
-- `plan` → `/gsdd:execute`
-- `execute` → `/gsdd:verify` (if verifier enabled) or `/gsdd:progress`
-- `verify` → `/gsdd:progress` (passed), `/gsdd:plan` (gaps), `/gsdd:verify` (human_needed)
-- `audit-milestone` → `/gsdd:complete-milestone` (passed), `/gsdd:plan` (gaps/debt)
-- `quick` → `/gsdd:progress`
-- `pause` → `/gsdd:resume` (next session)
+- `new-project` → `/gsdd-plan`
+- `plan` → `/gsdd-execute`
+- `execute` → `/gsdd-verify` (if verifier enabled) or `/gsdd-progress`
+- `verify` → `/gsdd-progress` (passed), `/gsdd-plan` (gaps), `/gsdd-verify` (human_needed)
+- `audit-milestone` → `/gsdd-complete-milestone` (passed), `/gsdd-plan` (gaps/debt)
+- `quick` → `/gsdd-progress`
+- `pause` → `/gsdd-resume` (next session)
 - `resume` → dispatches to selected workflow
-- `map-codebase` → `/gsdd:new-project`
+- `map-codebase` → `/gsdd-new-project`
 
 **GSD comparison:**
 
@@ -1348,6 +1382,556 @@ 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. The guided path must stay intentionally compact: runtime choice, governance opt-in, and a small set of bundled planning defaults rather than a long per-setting questionnaire.
+
+- 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 planning defaults through two orthogonal bundled choices (`Rigor` and `Cost`) plus the separate `.planning` tracking choice, instead of a long per-setting questionnaire.
+- 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.
+
+**Phase 17 refinement:**
+
+- The guided config path was reduced from 13 visible prompts to 5.
+- `Rigor` controls `researchDepth` and workflow strictness (`research`, `discuss`, `planCheck`) while keeping `workflow.verifier` always on.
+- `Cost` controls `modelProfile` and `parallelization` independently, so combinations such as `thorough + budget` remain reachable.
+- `gitProtocol` remains in `config.json` with defaults but is intentionally out of the wizard until a dedicated UX pass decides the right shape.
+
+**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. External: npm init (Node.js), Vite `create-vite`, Next.js `create-next-app`, Angular CLI `ng new`, and Astro `create astro` all implement the same pattern — TTY-interactive wizard by default, `--yes`/`--defaults` for headless; this is the de facto standard for modern project scaffolding tools.
+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/lib/init-flow.mjs`, `bin/lib/init-prompts.mjs`, `bin/lib/models.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.consumer-ceremony.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.
+4. External: Meyer's Command-Query Separation (CQS, "Object-Oriented Software Construction" 1988) — the foundational principle that operations should be classified by whether they modify state, not by what they conceptually represent; Greg Young's CQRS (2010) — CQS applied at the architectural level; Unix rwx permission model and AWS IAM/Kubernetes RBAC all classify operations by mutation semantics rather than by semantic category name
+
+**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`
+
+---
+
+## 38. Retroactive Artifact Enforcement
+
+**Problem:** ROADMAP.md phase `[x]` can be marked complete without the required artifacts (PLAN.md, SUMMARY.md, VERIFICATION.md) existing on disk. No mechanical gate prevents phase advancement without artifacts. This gap (I27) recurred twice in the v1 milestone:
+
+- Sub-gap (a): early session termination drops final bookkeeping — ROADMAP marked `[x]` with no VERIFICATION.md.
+- Sub-gap (b): `verify.md` structural omission — even on full lifecycle success, ROADMAP stayed stale because only `execute.md` updated it.
+
+Sub-gap (b) was closed by D28's `<persistence>` mandate and guarded by G30. Sub-gap (a) requires either a preventive CLI gate or an explicit accept-by-design decision.
+
+**Decision:** Accept milestone-audit as the retroactive enforcement layer for sub-gap (a). Do not add a preventive CLI gate.
+
+**Rationale:**
+
+1. **Artifact mandates already exist.** D28 added `<persistence>` sections with MANDATORY language to `execute.md` and `verify.md`. D30 propagated them to `quick.md`, `map-codebase.md`, `audit-milestone.md`, and `pause.md`. The specification-level enforcement is in place across all artifact-producing workflows.
+
+2. **Kernel simplicity.** Adding a preventive gate (e.g., `gsdd verify` checking artifact existence before allowing ROADMAP updates) would require every workflow to call a CLI guard before its state update. This creates a new coupling between the CLI layer and the workflow layer — complexity the kernel explicitly avoids. See `.internal-research/strategy.md` section on policy depth vs kernel purity.
+
+3. **Retroactive audit is sufficient.** The milestone audit (`audit-milestone.md`, `agents/integration-checker.md`) checks artifact completeness across all phases as its first step. Violations surface as structured gaps, not silent passes. The audit cost is bounded and predictable.
+
+4. **Gap already has guard coverage.** G30 mechanically enforces that `verify.md` closes ROADMAP on passed status. The sub-gap (b) failure mode is now guarded. Sub-gap (a) (session interruption) is a behavioral failure by the agent, not a structural gap in the spec — no guard can prevent a session from crashing mid-workflow.
+
+5. **GSD comparison.** GSD has no preventive artifact gate either. GSD's enforcement relies on its mandatory commit steps and `gsd-tools.cjs` CLI calls. GSDD's design choice strips mandatory commits (D8) and CLI-gated workflow steps (D9), trading off some enforcement depth for portability. Milestone audit is the equivalent retroactive layer.
+
+**What this decision closes:** I27 sub-gap (a) is accepted by design. The full I27 gap is now CLOSED: sub-gap (b) by D28/G30, sub-gap (a) by this decision.
+
+**Evidence:**
+
+- `.internal-research/gaps.md` I27 entry (two occurrences, root-cause analysis, close conditions)
+- D28 mandate language in `distilled/workflows/execute.md` and `distilled/workflows/verify.md`
+- D30 propagation to all artifact-producing workflows
+- G30 guard in `tests/gsdd.guards.test.cjs` (verify.md ROADMAP closure)
+- `.internal-research/strategy.md` (kernel simplicity vs policy depth trade-off)
+- `distilled/workflows/audit-milestone.md` (retroactive artifact completeness check)
+- External: NIST SP 800-53 Rev. 5 (2020) — distinguishes detective controls (post-event detection) from preventive controls (pre-event blocking) as equally valid risk-management strategies; ISO 27001 risk treatment options — the choice of detective vs preventive control depends on cost/complexity tradeoff, not on which is inherently superior; Reason's Swiss Cheese model (1990) — layered defense-in-depth where retroactive audit layers catch what preventive layers miss; session interruption is a distributed systems failure mode (analogous to the Two Generals problem) that cannot be fully eliminated by local gates
+
+**GSD comparison:** GSD's `gsd-tools.cjs` CLI enforces workflow progression gates directly. GSDD replaces those with specification-level MANDATORY language (D9). This is a deliberate portability trade-off, not an oversight.
+
+**GSDD implementation:** `distilled/workflows/execute.md` (SUMMARY.md persistence gate), `distilled/workflows/verify.md` (VERIFICATION.md persistence gate + ROADMAP closure), `distilled/workflows/audit-milestone.md` (retroactive artifact check), `tests/gsdd.guards.test.cjs` (G30), `distilled/EVIDENCE-INDEX.md` (D38 entry)
+
+---
+
+## 39. Brownfield Entry Wiring
+
+**Problem:** The brownfield path was structurally incomplete. `map-codebase` generated useful orientation artifacts, but it routed users only toward full project initialization. `quick` remained blind to those same codebase maps, so brownfield users who wanted disciplined feature work without full roadmap ceremony had no first-class lane.
+
+**Decision:** Wire the existing brownfield lane instead of adding a new workflow.
+
+- `map-codebase` completion now offers two explicit next steps: `/gsdd-new-project` for full lifecycle setup and `/gsdd-quick` for brownfield feature work.
+- `quick` now reads `.planning/codebase/ARCHITECTURE.md` and `.planning/codebase/STACK.md` when they exist and passes a summarized `$CODEBASE_CONTEXT` into the planner delegate.
+
+**Why this shape:** The missing leverage was routing and context reuse, not another onboarding surface. Reusing the existing codebase map artifacts preserves the current workflow set, keeps quick mode lightweight, and gives brownfield users immediate architecture awareness without forcing full milestone ceremony.
+
+**Tradeoff:** This gives `quick` orientation, not full brownfield inference. It deliberately avoids turning quick mode into a lite `new-project`; the planner receives only a bounded summary from the codebase maps, not a new research phase.
+
+**GSD comparison:** GSD's brownfield posture is centered on the full project-initialization flow after mapping. GSDD keeps the full path available, but adds an explicit lighter-weight branch for feature-by-feature brownfield work.
+
+**GSDD implementation:** `distilled/workflows/quick.md` (Step 2 codebase context, planner context), `distilled/workflows/map-codebase.md` (completion routing), `tests/gsdd.guards.test.cjs`, `tests/gsdd.scenarios.test.cjs`
+
+**Evidence:**
+
+- User brownfield audit finding (2026-03-20): mapping was useful, but the lighter-weight feature-work lane was not explicit
+- D32-D34 quick-workflow hardening: alignment and scope controls already existed, so the remaining gap was routing plus codebase-context reuse
+- `distilled/workflows/quick.md` (Step 2 codebase-context read, planner delegate context)
+- `distilled/workflows/map-codebase.md` (completion offers `/gsdd-quick` as the brownfield lane)
+- `tests/gsdd.guards.test.cjs`, `tests/gsdd.scenarios.test.cjs`
+
+---
+
+## D40 - Three-Layer Continuity Boundary
+
+**Decision (2026-03-30):** GSDD adopts an explicit three-layer continuity boundary so cold-start recovery, resume behavior, and future continuity work do not blur durable truth, live workflow state, and the still-missing compressed judgment layer.
+
+**Context:**
+- Gap S6 showed that cold-start continuity was stronger on artifact and state recovery than on decision-quality recovery. The repo could reconstruct what was built, but not always the smallest why/why-not layer needed for equally strong planning after a restart.
+- Phase 7 requirement JUDGE-01 required the continuity model to be named and adopted explicitly instead of being inferred from scattered docs.
+- Lesson `LL-ARTIFACT-PERSISTENCE-IS-NOT-ENOUGH` already established the core failure mode: artifacts preserve what was built, but not the minimum judgment layer needed to continue with the same decision posture.
+
+**Decision text:**
+- **Durable Truth**: files that survive across milestones and cold starts and define product or framework truth. This layer includes `SPEC.md`, `distilled/DESIGN.md`, `MILESTONES.md`, milestone archives, `config.json`, codebase maps, research artifacts, role contracts, and workflow definitions.
+- **Live Workflow State**: files that describe current progress, active execution position, or resumable session state. This layer includes `ROADMAP.md`, phase `PLAN`/`APPROACH`/`SUMMARY`/`VERIFICATION` artifacts, `.continue-here.md`, quick task logs, and `generation-manifest.json`.
+- **Compressed Judgment**: the smallest persistence surface for active constraints, unresolved uncertainty, decision posture, and anti-regression rules. This layer is recognized as necessary but not yet fully designed; its persistence surface is deferred to Phase 8.
+- Workflow changes must classify artifacts against this boundary. Readers must not infer durable truth from live-state artifacts alone, and writers must not collapse multiple layers into a new catch-all state file.
+
+**Evidence:**
+- Phase 7 exploration reviewed all 14 current workflow files and mapped which artifacts they read, write, or treat as primary truth. The review found durable artifacts and live-state artifacts in use, but no explicit three-layer model naming compressed judgment as its own continuity concern.
+- D12 established the "artifact-derived state, no `STATE.md`" direction, which kept GSDD repo-native and file-backed, but did not define a distinct compressed judgment layer.
+- D26 hardened routing and session continuity contracts, but likewise operated on artifacts and checkpoints without naming the broader continuity boundary.
+- The three-layer boundary therefore emerged from Phase 7 as a missing architectural definition rather than a reversal of prior decisions.
+
+**Consequences:**
+- Phase 8 must define the compressed-judgment persistence surface and workflow-consumption rules needed to satisfy JUDGE-02 and JUDGE-03.
+- Future workflow and artifact changes should explicitly classify any touched file as durable truth, live workflow state, or compressed judgment before changing its contract.
+- `distilled/workflows/resume.md` is the first workflow to adopt this boundary directly by validating live checkpoint state against durable roadmap truth without inventing a new project-scoped state file.
+
+**GSDD implementation:** `.planning/SPEC.md` (Continuity Layers constraint, Key Decisions row), `distilled/DESIGN.md` (this decision), `distilled/workflows/resume.md` (first workflow adoption)
+
+---
+
+## D41 - Compressed Judgment Persistence Surface
+
+**Decision (2026-03-30):** GSDD persists compressed judgment as a bounded `<judgment>` XML block with four sections in two existing surfaces: the checkpoint for mid-phase cold restarts and the phase SUMMARY for phase-to-phase handoffs.
+
+**Context:**
+- Phase 7 defined the three-layer continuity boundary in D40, but explicitly left the compressed judgment persistence surface undefined as a Phase 8 target.
+- JUDGE-02 requires the judgment layer to use existing primary or checkpoint artifacts rather than inventing a new project-scoped state file.
+- JUDGE-03 requires planning, execution, verification, and resume to recover judgment at entry without relying on chat memory.
+- Gap S6 showed that artifact persistence alone preserves what was built, not the smallest why/why-not layer needed to continue with the same decision posture.
+- Lesson `LL-ARTIFACT-PERSISTENCE-IS-NOT-ENOUGH` established that the continuity problem is not solved by durable artifacts alone.
+
+**Decision text:**
+- Persist compressed judgment as a bounded `<judgment>` XML block with four sections: `<active_constraints>`, `<unresolved_uncertainty>`, `<decision_posture>`, and `<anti_regression>`.
+- Embed the exact same shape in two existing surfaces:
+  - the checkpoint (`.continue-here.md`), written by `pause.md` at session pause and read by `resume.md` for mid-phase cold restarts
+  - the phase `SUMMARY.md`, written by `execute.md` at phase completion and read by `plan.md`, `execute.md`, and `verify.md` for phase-to-phase handoffs
+- The shape must remain identical in both locations so the judgment layer is consistent across lifecycle entry points.
+- No new project-scoped state file is introduced.
+
+**Evidence:**
+- Phase 8 reviewed the four workflow entry points that need judgment recovery: `plan.md`, `execute.md`, `verify.md`, and `resume.md`.
+- The review mapped each workflow's current `<load_context>` or artifact read path and confirmed that checkpoint and SUMMARY are already in the natural read/write flow of these workflows.
+- `SUMMARY.md` already carries "Notes for Next Work", but that section is unstructured prose and is not consumed by any workflow's `<load_context>`.
+- The checkpoint already stores session-local state and decisions, but it does not capture a cumulative, bounded judgment layer with the four facets needed for continuity.
+- The dual-surface approach covers both required handoff scenarios without inventing a new persistence path: checkpoint for mid-phase restart, SUMMARY for phase-to-phase continuation.
+
+**Consequences:**
+- Future workflow changes must maintain judgment read/write integration at these designated points rather than creating ad hoc persistence surfaces.
+- The judgment shape is intentionally bounded to four sections and must not expand into an unbounded session log.
+- Phase 9 remains responsible for runtime metadata and portability concerns (ADAPT-02); judgment portability across runtimes is not broadened here.
+
+**GSDD implementation:** `.planning/SPEC.md` (Key Decisions row), `distilled/workflows/pause.md` (checkpoint write), `distilled/workflows/execute.md` (SUMMARY write and prior-summary read), `distilled/workflows/plan.md` (prior-summary read), `distilled/workflows/verify.md` (summary judgment verification input), `distilled/workflows/resume.md` (checkpoint read and surfacing)
+
+---
+
+## D42 - Session-Boundary Safety
+
+**Decision (2026-04-04):** `.continue-here.bak` survives `resume.md` dispatch so downstream workflows can read it as a fallback judgment source when no prior SUMMARY.md `<judgment>` section is available. The downstream workflow auto-cleans `.bak` after absorbing the judgment.
+
+**Context:**
+- D41 established two judgment persistence surfaces: checkpoint (`.continue-here.md`) and phase SUMMARY.md.
+- `resume.md` copies `.continue-here.md` to `.continue-here.bak` during `<cleanup_checkpoint>` (crash safety), then previously deleted `.bak` in `<completion>` before dispatching.
+- When a user clears context between resume and the dispatched workflow, session-specific judgment is permanently lost: `.continue-here.md` already deleted, `.bak` already deleted, and the prior SUMMARY.md only carries the *prior completed phase's* judgment — not the interrupted session's `<active_constraints>`, `<decision_posture>`, or `<anti_regression>` rules.
+- `pause.md` line 53 already deletes stale `.bak` files from prior crashed resumes — this crash-cleanup path remains unchanged.
+
+**Decision:**
+- `resume.md` `<completion>` no longer deletes `.planning/.continue-here.bak`.
+- `plan.md`, `execute.md`, `verify.md`, and `quick.md` read `.planning/.continue-here.bak` as a fallback judgment source if no prior SUMMARY.md `<judgment>` section is available, then auto-clean it.
+- `pause.md` `.bak` cleanup (crash-recovery path, line 53) remains unchanged.
+
+**Transition safety table:**
+
+| Transition | Judgment source | `.bak` state after | Risk |
+|---|---|---|---|
+| pause → resume (same session) | `.continue-here.md` live in context | `.bak` created by `<cleanup_checkpoint>` | None: judgment in context |
+| resume → workflow (same session, no context clear) | Judgment in context from resume | `.bak` on disk, ignored | None: judgment in context |
+| resume → [context clear] → workflow | `.bak` fallback read | Deleted by workflow after read (auto-clean) | **Solved by this change** |
+| resume → [context clear] → workflow (SUMMARY.md judgment exists) | Prior SUMMARY.md `<judgment>` | `.bak` on disk, not read | `.bak` orphaned; cleaned by next `pause.md` run (line 53) |
+| Crash during resume (before dispatch) | `.continue-here.md` still exists | `.bak` may exist | Next resume reads `.md`; stale `.bak` cleaned by next `pause.md` |
+
+**Evidence:**
+- Gap identified by tracing judgment lifecycle through pause → resume → [context clear] → downstream workflow.
+- `pause.md` line 53 already handles crash-orphaned `.bak` files — no new general cleanup path needed.
+- The conditional read (only when no SUMMARY.md judgment exists) prevents double-sourcing judgment from both `.bak` and SUMMARY.md.
+
+**Consequences:**
+- `.bak` now has a defined lifecycle: created by `resume.md` `<cleanup_checkpoint>`, consumed-and-deleted by the next downstream workflow, or cleaned by the next `pause.md` run.
+- Future workflows added as resume dispatch targets must include the `.bak` fallback read pattern if they consume judgment.
+- The judgment shape remains bounded to four sections (D41 constraint). `.bak` is a fallback read path, not a new persistence surface.
+- `quick.md` reads `.bak` unconditionally (no SUMMARY.md check) because quick tasks have no phase lifecycle and no prior SUMMARY.md to consult. The other three workflows (`plan.md`, `execute.md`, `verify.md`) read `.bak` conditionally — only when no prior SUMMARY.md `<judgment>` section exists.
+
+**GSDD implementation:** `distilled/workflows/resume.md` (`.bak` deletion removed from `<completion>`), `distilled/workflows/plan.md` (fallback read item 8), `distilled/workflows/execute.md` (fallback read item 7), `distilled/workflows/verify.md` (fallback read item 7), `distilled/workflows/quick.md` (fallback read in Step 2), `distilled/DESIGN.md` (this decision), `tests/gsdd.guards.test.cjs` (negative and positive invariant tests)
+
+---
+
+## D43 - Resume Provenance Truth Split
+
+**Decision (2026-04-13):** `resume.md` must reconcile three truth surfaces explicitly instead of treating a structurally valid checkpoint as sufficient truth on its own.
+
+**Context:**
+- The 2026-04-12 failure chain showed that a generic checkpoint can be structurally valid while materially understating the live branch/worktree scope.
+- The continuity boundary from D40/D41/D42 solved judgment persistence, but it did not yet distinguish checkpoint narrative truth from live git/worktree truth when the checked-out branch is stale, mixed-scope, or otherwise not the intended execution surface.
+- Phase 19 required resume UX hardening for `LAUNCH-09` and provenance/trust separation for `LAUNCH-10`.
+
+**Decision:**
+- `resume.md` must surface and reconcile three truth buckets:
+  - **checkpoint narrative truth**
+  - **planning/artifact truth**
+  - **git/worktree truth**
+- `pause.md` must build a checkpoint draft from artifact truth first, then ask only bounded correction questions rather than asking the user to reconstruct obvious repo state from scratch.
+- Material mismatch between checkpoint narrative truth and git/worktree truth must become a first-class warning with explicit acknowledgement before continuing.
+- Ordinary git risk remains warning-level by default. The stronger acknowledgement gate is reserved for material mismatch, not generic dirtiness.
+
+**Why this fits the codebase:**
+- GSDD already treats repo truth as authoritative when docs and repo disagree. This decision extends that hierarchy to session continuity by preventing `.continue-here.md` from silently outranking the live integration surface.
+- The change keeps the product file-based and workflow-driven. It does not add a new public command or a new project-scoped state file.
+- The shared helper stays internal because the user-facing behavior belongs in workflows, while the classification logic belongs in reusable library code.
+
+**Evidence:**
+- `.internal-research/gaps.md` items `I29` and `I30`
+- `.internal-research/TODO.md` notes on stale checkpoints, worktree drift, and parallel worktree rules
+- `.internal-research/consumer-audits/worktree-provenance-and-checkpoint-drift-2026-04-12.md`
+- `distilled/workflows/pause.md` (draft-first checkpointing, 3-question cap, evidence-only language)
+- `distilled/workflows/resume.md` (`<provenance_reconciliation>`, explicit mismatch acknowledgement)
+- `bin/lib/provenance.mjs`
+- `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.invariants.test.cjs`
+- External: GitHub Docs on checking branch divergence and working tree state; OpenAI/Anthropic guidance on grounding agent actions in current tool-observed state rather than conversational assumptions
+
+**Consequences:**
+- Resume is now conservative by design when a checkpoint narrative is stale relative to the live branch/worktree.
+- Future workflows that route from checkpoint state must preserve the same truth separation instead of flattening narrative, planning, and git state into one status line.
+- Phase 22 must replay the 2026-04-12 incident and prove this separation holds end-to-end.
+
+**GSD comparison:** GSD's flow relies more heavily on the operator and commit discipline to keep resume context aligned with branch truth. GSDD keeps the lighter-weight continuity surface, but compensates by making the truth split explicit inside the resume workflow.
+
+**GSDD implementation:** `distilled/workflows/pause.md`, `distilled/workflows/resume.md`, `bin/lib/provenance.mjs`, `.planning/SPEC.md`, `.planning/ROADMAP.md`, `.internal-research/TODO.md`, `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.invariants.test.cjs`
+
+---
+
+## D44 - Warning-First Transition Safety And Fail-Closed Terminal Writes
+
+**Decision (2026-04-13):** GSDD uses one warning-first provenance pattern across transition-sensitive workflows, while terminal artifact gates fail closed when the required durable output does not exist on disk.
+
+**Context:**
+- Phase 20 needed a single transition-safety posture for `pause`, `resume`, `plan`, `execute`, `new-milestone`, `quick`, and `complete-milestone` instead of each workflow inventing its own git-risk language.
+- The same failure chain also exposed a different class of problem: terminal workflows could present closure-like outcomes even when the required durable artifact was missing.
+- D38 previously accepted retroactive artifact enforcement for an older closure gap. The new failure mode is narrower and higher leverage: terminal verification and milestone audit must not present durable completion outcomes without their mandatory artifacts.
+
+**Decision:**
+- Transition-sensitive workflows share one warning pattern for:
+  - staged, unstaged, and untracked work
+  - unpushed commits
+  - PR-less integration surfaces
+  - stale/spent branches relative to `main`
+  - mixed-scope working trees
+- These conditions are warning-first by default. They should inform routing and user acknowledgement, not become blanket hard blockers.
+- Two terminal write gates fail closed under `LAUNCH-13`:
+  - `verify.md` must not advance ROADMAP closure on a passed result unless the required `SUMMARY.md` still exists on disk
+  - `audit-milestone.md` must not present a durable audit result unless `MILESTONE-AUDIT.md` was written successfully
+- This slice does not introduce managed worktree orchestration or a new public provenance command.
+
+**Why this fits the codebase:**
+- Warning-first delivery preserves GSDD's portable, advisory git stance instead of turning the kernel into an intrusive branch manager.
+- Fail-closed write gates are justified here because verification and milestone audit are terminal state transitions. If their durable artifact is missing, the claimed state transition is not trustworthy.
+- Keeping the gate narrow avoids reopening D38 into a broad CLI policy layer.
+
+**Evidence:**
+- `.planning/SPEC.md` `LAUNCH-12` and `LAUNCH-13`
+- `.planning/ROADMAP.md` Phase 20 and Phase 22 scope notes
+- `distilled/workflows/plan.md`, `execute.md`, `quick.md`, `new-milestone.md`, `complete-milestone.md`
+- `distilled/workflows/verify.md`, `distilled/workflows/audit-milestone.md`
+- `bin/lib/provenance.mjs`
+- `tests/gsdd.guards.test.cjs`, `tests/gsdd.invariants.test.cjs`, `tests/gsdd.scenarios.test.cjs`
+- External: NIST detective vs preventive control framing; GitHub guidance on protected branches and review signals as advisory integration metadata rather than direct truth
+
+**Consequences:**
+- Workflow routing can warn consistently about risky integration surfaces without forcing managed branch behavior before launch.
+- Terminal audit/verification claims now depend on durable write success, not just conversational success.
+- Phase 22 proof scope expands to cover both provenance warnings and fail-closed terminal writes.
+
+**GSD comparison:** GSD relies more on explicit commit and CLI discipline for transition safety. GSDD continues to strip that rigidity from the portable core, but adds explicit warning reuse and narrow fail-closed gates where launch trust depends on artifact presence.
+
+**GSDD implementation:** `distilled/workflows/plan.md`, `distilled/workflows/execute.md`, `distilled/workflows/quick.md`, `distilled/workflows/new-milestone.md`, `distilled/workflows/complete-milestone.md`, `distilled/workflows/verify.md`, `distilled/workflows/audit-milestone.md`, `bin/lib/provenance.mjs`, `.planning/SPEC.md`, `.planning/ROADMAP.md`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.invariants.test.cjs`, `tests/gsdd.scenarios.test.cjs`
+
+---
+
 ## Maintenance
 
 This document is updated when: