gsdd-cli 0.3.1 → 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.
 
 ---
 
@@ -45,6 +48,8 @@
 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)
 
 ---
 
@@ -68,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
 
 ---
 
@@ -159,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
 
 ---
 
@@ -205,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
 
 ---
 
@@ -245,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
 
 ---
 
@@ -268,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
 
 ---
 
@@ -279,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.
 
@@ -297,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
 
 ---
 
@@ -326,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
 
 ---
 
@@ -355,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
 
 ---
 
@@ -470,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
 
 ---
 
@@ -790,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
@@ -812,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
 
 ---
 
@@ -901,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:**
 
@@ -912,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 |
@@ -939,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)
@@ -956,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)
 
 ---
 
@@ -1123,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
@@ -1166,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`
 
 ---
 
@@ -1217,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.
 
@@ -1239,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.
 ---
@@ -1250,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:**
 
@@ -1426,7 +1452,7 @@ GSD's approach was a `--full` flag that added plan-checking + verification to qu
 
 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.
+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.
 
@@ -1471,7 +1497,7 @@ The step has a **dual gate** — even with `workflow.discuss: true`, it evaluate
 | 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`.
+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.
 
@@ -1574,11 +1600,11 @@ That conflation was survivable while Cursor and Copilot were incorrectly treated
 
 **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.
+**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 existing planning defaults in the same guided flow instead of dropping back to free-form line prompts.
+- 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.
 
@@ -1588,18 +1614,25 @@ That conflation was survivable while Cursor and Copilot were incorrectly treated
 - 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. 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.
+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/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`
+**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`
 
 ---
 
@@ -1627,6 +1660,7 @@ That conflation was survivable while Cursor and Copilot were incorrectly treated
 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.
 
@@ -1634,6 +1668,270 @@ That conflation was survivable while Cursor and Copilot were incorrectly treated
 
 ---
 
+## 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: