gsdd-cli 0.3.1 → 0.18.0

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,21 @@
 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)
+40. [Three-Layer Continuity Boundary](#d40---three-layer-continuity-boundary)
+41. [Compressed Judgment Persistence Surface](#d41---compressed-judgment-persistence-surface)
+42. [Session-Boundary Safety](#d42---session-boundary-safety)
+43. [Resume Provenance Truth Split](#d43---resume-provenance-truth-split)
+44. [Warning-First Transition Safety And Fail-Closed Terminal Writes](#d44---warning-first-transition-safety-and-fail-closed-terminal-writes)
+45. [Fork-Honest Launch Posture Before Identity Migration](#d45---fork-honest-launch-posture-before-identity-migration)
+46. [Archived Milestone Routing With Retained ROADMAP](#d46---archived-milestone-routing-with-retained-roadmap)
+47. [Brownfield Quick-Win Repair](#d47---brownfield-quick-win-repair)
+48. [Shared Lifecycle Evaluator And Dual-Canonical Runtime Boundary](#d48---shared-lifecycle-evaluator-and-dual-canonical-runtime-boundary)
+49. [Deterministic Lifecycle Preflight Gates](#d49---deterministic-lifecycle-preflight-gates)
+50. [Evidence-Gated Closure Matrix](#d50---evidence-gated-closure-matrix)
+51. [Deterministic Runtime Surface Freshness](#d51---deterministic-runtime-surface-freshness)
+52. [Generic Checkpoint Routing Ownership](#d52---generic-checkpoint-routing-ownership)
 
 ---
 
@@ -68,8 +86,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 +177,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 +224,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 +265,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 +289,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 +301,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 +319,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 +349,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 +379,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 +495,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 +816,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 +841,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
 
 ---
 
@@ -824,7 +854,7 @@ Implementation lives under `bin/lib/`:
 
 **GSDD (before this decision):** Codex CLI was a skills-first runtime at ~40% parity. It consumed the portable `.agents/skills/gsdd-*/SKILL.md` surface but had no native plan-checker, no orchestration loop, no model control, and no dedicated adapter module. `--tools codex` was deprecated and silently stripped. Every Codex plan ran in silent `reduced_assurance` mode.
 
-**GSDD (after this decision):** Codex CLI is promoted to `native_capable` — same tier as Claude Code and OpenCode. A dedicated `bin/adapters/codex.mjs` generates `.codex/agents/gsdd-plan-checker.toml` (read-only TOML agent with the plan-checker delegate). Codex's entry surface is the portable skill at `.agents/skills/gsdd-plan/SKILL.md` — Codex auto-discovers it via its `.agents/skills/` skill scanning ([developers.openai.com/codex/skills](https://developers.openai.com/codex/skills)). The portable skill now contains vendor-neutral checker invocation instructions (JSON schema, max-3 cycle loop, escalation), so when Codex follows it, it spawns the native `gsdd-plan-checker` agent for fresh-context review. `--tools codex` is reinstated as an active adapter flag.
+**GSDD (after this decision):** Codex CLI is promoted to `native_capable` — same tier as Claude Code and OpenCode. A dedicated `bin/adapters/codex.mjs` generates `.codex/agents/gsdd-plan-checker.toml` (read-only TOML agent with the plan-checker delegate). Codex's entry surface is the portable skill at `.agents/skills/gsdd-plan/SKILL.md` — Codex auto-discovers it via its `.agents/skills/` skill scanning ([developers.openai.com/codex/skills](https://developers.openai.com/codex/skills)). The portable skill now contains vendor-neutral checker invocation instructions (JSON schema, max-3 cycle loop, escalation) plus an explicit plan-only completion lock, so when Codex follows it, it spawns the native `gsdd-plan-checker` agent for fresh-context review and still requires a separate `$gsdd-execute` transition before implementation. `--tools codex` is reinstated as an active adapter flag.
 
 **Why:** Codex CLI v0.115.0 (2026-03-16) stabilized its multi-agent system with `.codex/agents/*.toml` definitions, `spawn_agent` fresh-context invocation, per-agent `model` and `model_reasoning_effort` fields, and `sandbox_mode` access control. This provides structural parity with Claude's `.claude/agents/` and OpenCode's `.opencode/agents/`.
 
@@ -846,6 +876,7 @@ Implementation lives under `bin/lib/`:
 - No deterministic spawn API — spawning is model-interpreted via natural language, not a programmatic `Task()` call
 - GitHub issues #14719 (re-spawn failure) and #14841 (spawn loops with weaker models) are documented risks; GSDD's simple spawn-wait-pattern minimizes exposure, and the max-3 loop has escalation
 - JSON schema duplication — the checker JSON schema is embedded in Claude, OpenCode orchestration prompts and the portable skill; tests guard drift across all surfaces
+- Execution authorization must stay explicit — Codex and other runtimes must not infer implementation permission from generic imperative handoff text after `gsdd-plan`
 - No Codex CLI in CI — future regressions still require disposable-fixture validation even though local live validation now exists
 - Entry surface is shared — Codex uses the portable `.agents/skills/gsdd-plan/SKILL.md` as its entry surface (no vendor-specific skill path exists in Codex). The portable skill's checker invocation is vendor-neutral, but routing depends on Codex's implicit skill selection matching the task description
 
@@ -901,7 +932,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 +943,21 @@ 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 | ROADMAP/SPEC requirement status drift |
+| W11 | WARN | Installed generated runtime surfaces drift from current render output |
+| W12 | WARN | Planning state drifted since last recorded session (fingerprint mismatch) |
 | 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 +979,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-W12/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 +1000,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 +1167,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 +1208,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,9 +1259,9 @@ 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.
+**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. Preserve lifecycle order, but for `plan` make the boundary explicit: completion may name `/gsdd-execute` as the next workflow, while the current `gsdd-plan` run remains plan-only and does not authorize implementation.
 
 **Changes:**
 
@@ -1239,10 +1281,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 +1292,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` → separate `/gsdd-execute` run (routing only; no same-run execution authorization)
+- `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 +1468,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 +1513,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 +1616,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 +1630,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 +1676,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 +1684,640 @@ 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 secondary 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 bounded brownfield feature work.
+- `map-codebase` completion now synthesizes an explicit brownfield routing summary from the existing 4 docs: safest next change lane, highest-risk zones, must-know traps, and the recommended workflow with rationale.
+- `quick` now reads `.planning/codebase/ARCHITECTURE.md`, `.planning/codebase/STACK.md`, `.planning/codebase/CONVENTIONS.md`, and `.planning/codebase/CONCERNS.md` when they exist and passes a summarized `$CODEBASE_CONTEXT` into the planner delegate.
+- `quick` stays structurally pure: it gains safer brownfield routing/context, not spec, roadmap, or research-lite behavior.
+
+**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, convention, and risk 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 and not a fifth persistent artifact. If the user cannot yet name the bounded change, the workflow should steer back to `new-project`.
+
+**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 secondary branch for feature-by-feature brownfield work.
+
+**GSDD implementation:** `distilled/workflows/quick.md` (Step 2 codebase context, planner context, bounded-lane hardening), `distilled/workflows/map-codebase.md` (completion routing + brownfield routing summary), `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`
+
+---
+
+## D45 - Fork-Honest Launch Posture Before Identity Migration
+
+**Decision (2026-04-15):** GSDD keeps a fork-honest launch posture until package, workspace, help, proof, and release surfaces are migrated together. `Workspine` is the active public-name target in planning truth, but do not present an independent product identity as already complete while the operative contracts remain `gsdd-cli`, `gsdd`, `gsdd-*`, and `.planning/`.
+
+**Context:**
+- The v1.1 launch jury split repo truth into two layers: the core delivery kernel is real, but the public release surface still over-relied on internal and gitignored proof.
+- The next-milestone challenge pass found that `.planning/` is not a cheap cosmetic constant. It is a deep runtime, workflow, template, and test contract across the framework repo.
+- The same pass also found that a split public-name story layered on top of `gsdd-cli` / `gsdd` / `.planning` made the product look more independent than the install, workspace, and proof surfaces could honestly support.
+
+**Decision:**
+- v1.2.0 is scoped as **fork-honest launch hardening**, not as an independent rename milestone.
+- `Workspine` is the primary public product name in planning truth for v1.2.0, but it is not yet a full package/workspace/help contract migration.
+- Keep `.planning`, `gsdd-cli`, `gsdd`, and `gsdd-*` intentionally in the active launch contract.
+- Remove or demote independent-brand assumptions from planning and public-surface truth until a dedicated migration milestone proves the full blast radius is handled.
+- Treat identity migration as real engineering work across code, docs, help text, generated surfaces, tests, and release packaging — not as copy cleanup.
+- Keep the release-floor packaging story repo-tracked and inspectable: package metadata, tarball audit, `SECURITY.md`, and repo-owned release automation must align without relying on unpublished release artifacts or broader runtime-parity claims.
+
+**Why this fits the codebase:**
+- It preserves the already-shipped repo-native kernel and avoids turning a launch-hardening milestone into a hidden workspace/package migration.
+- It keeps product truth aligned with what the repo can actually prove today.
+- It narrows the next milestone to the highest-leverage launch debt: public identity coherence, public proof export, packaging truth, and post-archive routing integrity.
+
+**Evidence:**
+- `.planning/SPEC.md` v1.2.0 active requirements and current-state posture
+- `.planning/ROADMAP.md` v1.2.0 Phase 23-27 ownership
+- `.internal-research/TODO.md` active milestone notes
+- `.internal-research/gaps.md` `I39`
+- `.internal-research/release-jury-verdict-2026-04-15.md`
+- `.internal-research/release-jury-public-truth-drift-2026-04-15.md`
+- `.internal-research/public-release-two-layer-brief-2026-04-15.md`
+- `get-shit-done/workflows/progress.md` (GSD's archived-state heuristic still assumes ROADMAP removal, which is one reason GSDD must be explicit when it diverges)
+
+**Consequences:**
+- Public launch work must make proof inspectable from tracked/public artifacts instead of citing `.planning/` or `.internal-research/`.
+- `Northline` is retired as the default launch-facing brand direction; `Workspine` is the only active public-name target in planning truth until later phases prove the tracked public surface can support it honestly.
+- If a future session wants independent identity, it should open a dedicated migration milestone rather than sneaking the blast radius into generic launch cleanup.
+- Release packaging and repo-owner surfaces must stay aligned to current repo truth. If a package/help/release workflow change would reintroduce stale owner residue or parity overstatement, treat that as fork-honest launch drift rather than as harmless metadata cleanup.
+
+**GSD comparison:** GSD keeps identity and workflow contracts coupled; its archived-state routing still assumes the active roadmap disappears. GSDD is diverging on archive-state persistence, so it must also stay explicit and conservative about identity/proof claims rather than layering a cosmetic product rename on top of unresolved contract differences.
+
+**GSDD implementation:** `.planning/SPEC.md`, `.planning/ROADMAP.md`, `.internal-research/TODO.md`, `.internal-research/gaps.md`, `.internal-research/lessons-learned.md`
+
+---
+
+## D46 - Archived Milestone Routing With Retained ROADMAP
+
+**Decision (2026-04-15):** `gsdd-progress` must treat a retained `ROADMAP.md` as historical archive state when the current roadmap milestone/version has both a shipped ledger entry in `.planning/MILESTONES.md` and the matching archived milestone audit artifact. In that state, the workflow routes to `/gsdd-new-milestone` rather than back to `/gsdd-audit-milestone`.
+
+**Context:**
+- GSDD now retains `ROADMAP.md` after milestone completion as a historical shipped-summary surface instead of deleting it at archive time.
+- The older `progress.md` logic still treated "between milestones" as equivalent to "SPEC exists while ROADMAP is absent", which matched the stricter GSD archive model but no longer matched current repo truth.
+- That created I39: the same archived milestone could satisfy "all phases complete" and get routed back into audit even though `.planning/SPEC.md` and `.internal-research/TODO.md` already treated the milestone as archived.
+
+**Decision:**
+- Keep the audit-ready branch for milestones whose phases are all complete but which do not yet have archive evidence.
+- Detect the archived-with-`ROADMAP.md` state from the current roadmap milestone/version plus:
+  - a shipped ledger entry for that same milestone in `.planning/MILESTONES.md`
+  - the matching archived milestone audit artifact for that same milestone/version
+- Only when both pieces of archive evidence exist does `progress.md` route to `/gsdd-new-milestone`.
+- Earlier archived milestones in the ledger must not satisfy the route for the current roadmap milestone/version.
+
+**Why this fits the codebase:**
+- It preserves the retained `ROADMAP.md` design without pretending that "all phases complete" always means "run audit again".
+- It keeps the routing decision grounded in durable truth surfaces that already exist, rather than inventing a new milestone-state file.
+- It narrows the change to the high-frequency handoff seam and leaves milestone audit behavior intact for not-yet-archived milestones.
+
+**Evidence:**
+- `.internal-research/gaps.md` `I39`
+- `.planning/MILESTONES.md`
+- `.planning/v1.1-MILESTONE-AUDIT.md`
+- `distilled/workflows/progress.md`
+- `tests/gsdd.guards.test.cjs`
+- `tests/gsdd.scenarios.test.cjs`
+- `tests/gsdd.health.test.cjs`
+- GSD comparison source: `get-shit-done/workflows/progress.md` (between-milestones routing still tied to ROADMAP absence)
+
+**Consequences:**
+- Post-archive progress routing now depends on explicit archive evidence, not on `ROADMAP.md` deletion.
+- Health truth can stay strict: W9/W10 clear because repo truth is aligned, not because the checker semantics were weakened.
+- Future milestone-lifecycle changes that retain or restore historical roadmap files must preserve the current-milestone archive-evidence check.
+
+**GSDD implementation:** `distilled/workflows/progress.md`, `.planning/MILESTONES.md`, `.planning/v1.1-MILESTONE-AUDIT.md`, `.internal-research/gaps.md`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.scenarios.test.cjs`, `tests/gsdd.health.test.cjs`
+
+---
+
+## D47 - Brownfield Quick-Win Repair
+
+**Decision (2026-04-16):** Keep the existing workflow set, but repair the brownfield contract end to end so the same story holds in docs, workflow routing, and progress reporting.
+
+**Context:**
+- The earlier brownfield fix (D39) made `map-codebase -> quick` explicit, but the full user journey still had three contradictions:
+  - public docs still over-taught `new-project` or implied users must always start brownfield work with `map-codebase`
+  - `quick.md` depended on codebase maps when present but had no documented just-enough fallback when maps were absent
+  - `progress.md` still treated codebase-only or quick-only repos as "no artifacts", so `map-codebase -> quick -> progress` was not a coherent lane
+- The user explicitly chose a quick win over a heavier product redesign: repair the existing lane now, and record the larger enterprise middle-lane question as follow-on work.
+
+**Decision:**
+- `gsdd-new-project` remains the full initializer for greenfield work, fuzzy brownfield scope, or milestone-shaped work. It owns brownfield codebase mapping internally when the deeper baseline is needed.
+- `gsdd-quick` is now the documented bounded brownfield lane. It reuses `.planning/codebase/*` when present and otherwise builds a just-enough inline brownfield baseline from stable repo-root surfaces before planning.
+- `gsdd-map-codebase` remains the deeper orientation pass for unfamiliar or higher-risk brownfield repos. It is optional before `quick`, not a mandatory first step for every existing repo.
+- `gsdd-progress` keeps the same six route branches, but Branch F is broadened into a general non-phase state branch that covers:
+  - between milestones
+  - codebase-only brownfield state
+  - quick-lane-only brownfield state
+- The heavier "durable enterprise middle lane" problem is explicitly deferred rather than being smuggled into `quick`.
+
+**Why this shape:** The highest-leverage failure was contract drift, not missing workflow count. Repairing the existing lane preserves the current architecture, minimizes new surface area, and removes the onboarding contradiction without prematurely inventing a durable change-management workflow.
+
+**Tradeoff:** This is intentionally not the full middle-lane redesign. `quick` is stronger and clearer now, but it still stays optimized for bounded work. Long-lived ticket/PBI continuity remains an explicit deferred product decision instead of silent scope creep inside `quick`.
+
+**Evidence:**
+- `.planning/SPEC.md` `DX-03` and `BROWNFIELD-01`
+- `distilled/workflows/quick.md`
+- `distilled/workflows/progress.md`
+- `distilled/workflows/new-project.md`
+- `distilled/workflows/map-codebase.md`
+- `README.md`
+- `docs/USER-GUIDE.md`
+- `distilled/README.md`
+- `tests/gsdd.guards.test.cjs`
+- `tests/gsdd.scenarios.test.cjs`
+- `.internal-research/gaps.md` (`I43`)
+
+**Consequences:**
+- New consumers no longer need to be told "always start with new-project, then maybe map-codebase, then maybe quick" for bounded brownfield work.
+- Brownfield onboarding, workflow routing, and status reporting now move together as one contract.
+- Any future change to brownfield entry must update the docs, workflow contracts, and status routing together instead of treating them as separate concerns.
+
+**GSD comparison:** GSD keeps brownfield posture closer to the full initialization flow after mapping. GSDD now preserves that full path, but also treats bounded-change brownfield work as a first-class documented lane without adding a new workflow surface.
+
+**GSDD implementation:** `distilled/workflows/quick.md`, `distilled/workflows/progress.md`, `distilled/workflows/new-project.md`, `distilled/workflows/map-codebase.md`, `README.md`, `docs/USER-GUIDE.md`, `distilled/README.md`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.scenarios.test.cjs`, `.planning/SPEC.md`, `.internal-research/TODO.md`, `.internal-research/gaps.md`, `.internal-research/lessons-learned.md`
+
+---
+
+## D48 - Shared Lifecycle Evaluator And Dual-Canonical Runtime Boundary
+
+**Decision (2026-04-16):** Phase and milestone posture should be derived through one shared evaluator over existing repo artifacts, while runtime-surface truth should use a dual-canonical contract that explicitly separates authored workflow source from the generated Codex-consumed surface until deterministic freshness checks exist.
+
+**Context:**
+- v1.3.0 Phase 29 audited two different claim seams that had been conflated in planning truth:
+  - lifecycle-state derivation from `SPEC.md`, `ROADMAP.md`, `MILESTONES.md`, phase artifacts, audit artifacts, and provenance
+  - Codex/runtime-surface truth across `distilled/workflows/*` and generated `.agents/skills/*`
+- `bin/lib/health.mjs` and `bin/lib/health-truth.mjs` both carried overlapping lifecycle parsing logic, which made ENGINE-02 weaker than the docs suggested.
+- At the same time, the repo could not honestly keep saying there was one tracked canonical Codex/runtime surface, because `.agents/` is still ignored and the consumed runtime boundary can drift from the authored source boundary.
+
+**Decision:**
+- Introduce one shared lifecycle evaluator seam for phase and milestone posture and make downstream health/reporting code consume it instead of maintaining competing parsers.
+- Keep lifecycle evaluation repo-truth-only: it reads existing planning artifacts plus provenance inputs and does not introduce a new project-scoped state file.
+- Narrow the runtime story to a **dual-canonical** contract:
+  - `distilled/workflows/*` is the authored source contract
+  - generated `.agents/skills/*` is the consumed Codex runtime surface
+- Treat deterministic freshness enforcement across authored and generated surfaces as later work, not as something Phase 29 can imply without proof.
+
+**Why this fits the codebase:**
+- It matches the repo's existing architecture bias toward file-backed truth and shared helper enforcement instead of workflow-local prose.
+- It separates two different hardening seams cleanly: state derivation and runtime freshness.
+- It preserves the portable-core model without pretending generated runtime surfaces are already tracked or freshness-enforced when repo truth cannot prove that yet.
+
+**Evidence:**
+- `.planning/SPEC.md` `ENGINE-01`, `ENGINE-02`, and `ENGINE-05`
+- `.planning/ROADMAP.md` Phases 29 and 32
+- `.internal-research/TODO.md`
+- `.internal-research/gaps.md` `I42`
+- `bin/lib/lifecycle-state.mjs`
+- `bin/lib/health.mjs`
+- `bin/lib/health-truth.mjs`
+- `tests/phase.test.cjs`
+- `tests/gsdd.health.test.cjs`
+- `tests/gsdd.guards.test.cjs`
+- GSD comparison source: `get-shit-done/workflows/progress.md` still assumes workflow-local routing logic rather than a shared lifecycle evaluator seam, so this is an intentional GSDD tightening.
+
+**Consequences:**
+- Phase/milestone posture is now an engine seam with one evaluator, which later lifecycle gates can reuse directly.
+- Runtime-surface claims are more conservative immediately: the repo no longer needs to pretend one tracked canonical Codex surface exists before deterministic freshness enforcement is real.
+- Phase 32 now owns authored/generated freshness enforcement explicitly instead of inheriting that work as vague follow-through from Phase 29.
+
+**GSDD implementation:** `bin/lib/lifecycle-state.mjs`, `bin/lib/health.mjs`, `bin/lib/health-truth.mjs`, `.planning/SPEC.md`, `.planning/ROADMAP.md`, `.internal-research/TODO.md`, `.internal-research/gaps.md`, `tests/phase.test.cjs`, `tests/gsdd.health.test.cjs`, `tests/gsdd.guards.test.cjs`
+
+---
+
+## D49 - Deterministic Lifecycle Preflight Gates
+
+**Decision (2026-04-16):** Transition-sensitive lifecycle surfaces must derive eligibility from one deterministic preflight seam layered over the shared lifecycle evaluator, while `gsdd phase-status` remains the only explicit ROADMAP mutator and `progress` remains read-only.
+
+**Context:**
+- Phase 29 centralized lifecycle posture into `bin/lib/lifecycle-state.mjs`, but the transition-sensitive workflows still described eligibility in workflow-local prose.
+- That left three risks open:
+  - command entrypoints could grow a second lifecycle parser
+  - transition-sensitive workflows could silently drift into inconsistent blockers or mutation rules
+  - the read-only / owned-write / explicit-lifecycle-mutation split could blur again in docs or helpers
+- Phase 30 was explicitly scoped to turn the shared evaluator seam into deterministic preflight enforcement without widening into Phase 31 evidence typing or Phase 32 freshness enforcement.
+
+**Decision:**
+- Add `bin/lib/lifecycle-preflight.mjs` as the single deterministic gate for lifecycle-sensitive workflow entry surfaces.
+- Keep the preflight seam descriptive and repo-truth-based:
+  - it consumes the shared lifecycle evaluator
+  - it reports blockers, owned writes, mutation expectations, and lifecycle posture
+  - it does not mutate ROADMAP or milestone state itself
+- Keep `gsdd phase-status` as the only explicit ROADMAP mutator for phase-state transitions.
+- Require transition-sensitive workflow contracts to call the shared preflight seam instead of narrating their own lifecycle inference.
+- Preserve `progress` as read-only and make it explicitly defer any recommended transition back to the downstream workflow's own preflight gate.
+
+**Why this fits the codebase:**
+- It extends the existing file-backed engine model rather than adding a new state artifact or hidden control plane.
+- It reuses the shared evaluator introduced in D48 instead of tolerating another lifecycle interpretation seam.
+- It keeps mutation boundaries honest: descriptive evaluation, owned artifact writes, and explicit lifecycle mutation remain separate responsibilities.
+
+**Evidence:**
+- `.planning/SPEC.md` (`ENGINE-01`, `ENGINE-02`, `ENGINE-03`)
+- `.planning/ROADMAP.md` (Phase 30 success criteria)
+- `bin/lib/lifecycle-preflight.mjs`
+- `bin/lib/lifecycle-state.mjs`
+- `bin/gsdd.mjs`
+- `distilled/workflows/execute.md`
+- `distilled/workflows/verify.md`
+- `distilled/workflows/audit-milestone.md`
+- `distilled/workflows/complete-milestone.md`
+- `distilled/workflows/new-milestone.md`
+- `distilled/workflows/resume.md`
+- `distilled/workflows/progress.md`
+- `tests/phase.test.cjs`
+- `tests/gsdd.guards.test.cjs`
+- `tests/gsdd.scenarios.test.cjs`
+- GSD comparison source: `get-shit-done/workflows/progress.md` still keeps lifecycle routing inside the workflow surface rather than through a shared helper seam, so this is an intentional GSDD tightening.
+
+**Consequences:**
+- Illegal transitions and missing prerequisite artifacts can now fail closed from one helper seam instead of from drifting prompt-local logic.
+- `progress` can continue reporting lifecycle posture without inheriting write authority or becoming a hidden transition surface.
+- Phase 31 can build evidence-gated closure on top of a stable deterministic preflight contract instead of competing lifecycle entry logic.
+
+**GSDD implementation:** `bin/lib/lifecycle-preflight.mjs`, `bin/lib/lifecycle-state.mjs`, `bin/gsdd.mjs`, `bin/lib/init.mjs`, `distilled/workflows/execute.md`, `distilled/workflows/verify.md`, `distilled/workflows/audit-milestone.md`, `distilled/workflows/complete-milestone.md`, `distilled/workflows/new-milestone.md`, `distilled/workflows/resume.md`, `distilled/workflows/progress.md`, `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.scenarios.test.cjs`
+
+---
+
+## D50 - Evidence-Gated Closure Matrix
+
+**Decision (2026-04-17):** Closure-sensitive lifecycle surfaces must share one compact evidence matrix keyed by workflow surface and delivery posture, using the fixed evidence kinds `code`, `test`, `runtime`, `delivery`, and `human`.
+
+**Context:**
+- Phase 30 hardened lifecycle eligibility, but the closure surfaces still described proof in mismatched ways:
+  - `verify.md` still used the older four-proof vocabulary
+  - `audit-milestone.md` aggregated phase outcomes but did not record a shared closure posture
+  - `complete-milestone.md` trusted a passed audit without checking whether the audit had actually proven the right kind of evidence for repo-only versus delivery-sensitive closeout
+- That created two opposite failure modes:
+  - repo-only work could feel pressured to fabricate runtime or delivery proof just to satisfy prose
+  - delivery-sensitive closure could pass on code inspection, tests, or human commentary alone even when the claim required runtime and delivery proof
+
+**Decision:**
+- Add `bin/lib/evidence-contract.mjs` as the shared internal closure-evidence seam.
+- Fix the stable evidence kinds to `code`, `test`, `runtime`, `delivery`, and `human`.
+- Key the matrix by both:
+  - closure surface (`verify`, `audit-milestone`, `complete-milestone`)
+  - delivery posture (`repo_only`, `delivery_sensitive`)
+- Make `verify` record the selected delivery posture plus required, observed, and missing evidence kinds in its report contract.
+- Make `audit-milestone` aggregate the same evidence posture and fail closed when required kinds remain missing.
+- Make `complete-milestone` consume the audit's evidence contract instead of silently trusting a passed audit that lacks the required closure evidence.
+
+**Why this fits the codebase:**
+- It follows the repo's existing pattern of small shared helpers plus file-backed workflow contracts instead of adding another freeform prompt convention.
+- It keeps repo-only work honest without pretending every closure needs runtime or delivery proof.
+- It raises the bar only where the claim itself is stronger: shipped or externally consumed outcomes now pay the stronger evidence cost explicitly.
+- It keeps the matrix internal and compact rather than inventing a second public mini-language for closure semantics.
+
+**Evidence:**
+- `.planning/SPEC.md` (`ENGINE-04`, `VERIFY-01`)
+- `.planning/ROADMAP.md` (Phase 31 success criteria)
+- `bin/lib/evidence-contract.mjs`
+- `bin/lib/lifecycle-preflight.mjs`
+- `distilled/workflows/verify.md`
+- `distilled/workflows/audit-milestone.md`
+- `distilled/workflows/complete-milestone.md`
+- `tests/phase.test.cjs`
+- `tests/gsdd.guards.test.cjs`
+- `tests/gsdd.scenarios.test.cjs`
+- GSD comparison sources: `agents/_archive/gsd-verifier.md` and `agents/_archive/gsd-integration-checker.md` preserve outcome verification and integration audit, but they do not expose one typed closure matrix shared across phase verification, milestone audit, and milestone completion.
+
+**Consequences:**
+- Closure-sensitive workflows now share one stable evidence vocabulary instead of drifting between proof synonyms.
+- Repo-only closures can stay repo-only without invented runtime theatrics.
+- Delivery-sensitive closure now has an explicit fail-closed bar: missing `runtime` or `delivery` evidence cannot be papered over by prose, code-only review, or human confirmation alone.
+- Milestone completion inherits the same evidence posture proven by audit, which reduces false-positive closure on technically incomplete release claims.
+
+**GSDD implementation:** `bin/lib/evidence-contract.mjs`, `bin/lib/lifecycle-preflight.mjs`, `distilled/workflows/verify.md`, `distilled/workflows/audit-milestone.md`, `distilled/workflows/complete-milestone.md`, `.planning/SPEC.md`, `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.scenarios.test.cjs`
+
+---
+
+## D51 - Deterministic Runtime Surface Freshness
+**Decision (2026-04-17):** Installed generated runtime-facing surfaces are trustworthy only through deterministic rendering from the authored workflow and delegate sources. When .agents/skills/, .claude/, .opencode/, or .codex/ exist locally, gsdd health must compare those generated files against current render output and route any drift back through gsdd update.
+**Context:**
+- Phase 29 narrowed the runtime story to a dual-canonical boundary: distilled/workflows/* is the authored source contract and generated runtime-facing files are the consumed local surfaces.
+- That narrowing was honest but still left I42 open because the repo could not yet prove that installed generated files stayed aligned with the current authored source without reviewer memory.
+- The framework repo also cannot fail closed on missing generated surfaces, because those directories are intentionally gitignored and may be absent even when the authored source is healthy.
+**Decision:**
+- Add one shared renderer-backed helper for runtime-surface freshness rather than per-test or per-runtime drift logic.
+- Compare only installed runtime surfaces; absent generated roots stay non-issues until the runtime surface actually exists locally.
+- Route drift through deterministic repair (gsdd update or a targeted gsdd update --tools <runtime>) instead of treating the fix as a manual review exercise.
+- Keep the public/runtime-facing wording brief: the authored source stays canonical, generated files are trusted because they are rendered and checked, and parity language remains narrow where live validation still does not exist.
+**Why this fits the codebase:**
+- It extends the existing render/update/health pattern instead of inventing a new state file or hidden synchronization layer.
+- It keeps the dual-canonical runtime contract honest: authored source and consumed generated files are distinct surfaces, but the boundary is now mechanically checked where the generated surface is actually installed.
+- It preserves framework-source honesty by warning only on installed drift, not on intentionally absent generated directories.
+**Evidence:**
+- .planning/SPEC.md (ENGINE-05)
+- .planning/ROADMAP.md (Phase 32)
+- .internal-research/gaps.md (I42 closure)
+- in/lib/runtime-freshness.mjs
+- in/lib/health.mjs
+- in/lib/health-truth.mjs
+- in/lib/rendering.mjs
+- in/adapters/claude.mjs, in/adapters/opencode.mjs, in/adapters/codex.mjs
+- README.md, docs/RUNTIME-SUPPORT.md, distilled/README.md
+- 	ests/phase.test.cjs, 	ests/gsdd.health.test.cjs, 	ests/gsdd.plan.adapters.test.cjs, 	ests/gsdd.guards.test.cjs, 	ests/gsdd.scenarios.test.cjs
+**Consequences:**
+- gsdd health can now surface installed generated-surface drift as deterministic workspace truth instead of relying on review discipline.
+- gsdd update becomes the explicit repair path for authored/generated runtime-surface drift.
+- Public support wording can stay compact without implying that generated files are trustworthy merely because they were generated once.
+- Claude Code and Codex CLI remain the mandatory live/native validation floor for the hardened runtime boundary, while other runtimes stay honest about their proof level.
+**GSD comparison:** GSD keeps runtime-facing workflow surfaces closer to the Claude-authored source and does not have to model a generated multi-runtime freshness boundary explicitly. GSDD does, because authored workflow source and consumed runtime surfaces are intentionally separated.
+**GSDD implementation:** in/lib/runtime-freshness.mjs, in/lib/health.mjs, in/lib/health-truth.mjs, in/lib/rendering.mjs, in/adapters/claude.mjs, in/adapters/opencode.mjs, in/adapters/codex.mjs, README.md, docs/RUNTIME-SUPPORT.md, distilled/README.md, .planning/SPEC.md, .internal-research/TODO.md, .internal-research/gaps.md, 	ests/phase.test.cjs, 	ests/gsdd.health.test.cjs, 	ests/gsdd.plan.adapters.test.cjs, 	ests/gsdd.guards.test.cjs, 	ests/gsdd.scenarios.test.cjs
+
+---
+
+## D52 - Generic Checkpoint Routing Ownership
+
+**Decision (2026-04-17):** Generic checkpoints remain visible continuity artifacts, but they do not block read-only `progress` routing. `resume` owns checkpoint cleanup only when the user explicitly resumes from the checkpoint, while `progress` treats a surviving generic checkpoint as informational context and continues routing toward the real next lifecycle action.
+
+**Context:**
+- Phase 19 intentionally allowed `resume` to preserve a generic checkpoint when the user chose a different path, because generic checkpoints can carry real context without pretending to be an active phase or quick-task execution surface.
+- That same flexibility exposed a later contradiction: `progress` still treated any `.continue-here.md` as a Branch A reroute back to `/gsdd-resume`, so a generic checkpoint could create a `resume -> progress -> resume` loop even after `resume` had already surfaced the checkpoint and routed the user onward.
+- Phase 33 was scoped narrowly to repair that control-plane seam without inventing a new checkpoint artifact, a broader checkpoint-consumption protocol, or a heavier brownfield/middle-lane redesign.
+
+**Decision:**
+- Add one shared checkpoint-routing classification seam in `bin/lib/provenance.mjs`:
+  - `phase` and `quick` checkpoints are routing blockers
+  - `generic` checkpoints are informational for read-only `progress` routing
+  - checkpoint cleanup remains resume-owned when the user explicitly resumes from the checkpoint
+- Keep `resume` behavior unchanged in one important respect: generic checkpoints still surface their `next_action` and let the user decide whether to resume from them.
+- Change `progress` behavior explicitly:
+  - show a generic checkpoint in the status block
+  - surface its `next_action`
+  - continue evaluating Branch B-F for the primary recommendation instead of routing back through Branch A
+- Regenerate the consumed skill surfaces from the authored workflow source so the portable contract and local runtime surface stay aligned.
+
+**Why this fits the codebase:**
+- It preserves the existing checkpoint artifact model and the three-layer continuity boundary instead of inventing another state file or destructive auto-cleanup step.
+- It keeps `progress` read-only and avoids pushing reporting semantics into lifecycle preflight, which would blur the distinction between routing/reporting and mutation authorization.
+- It moves the ownership split into one small shared seam plus tests, so the rule is no longer dependent on remembering two different workflow wordings.
+
+**Evidence:**
+- `.planning/SPEC.md` (`ENGINE-01`, `ENGINE-03`)
+- `.internal-research/gaps.md` (`I45`)
+- `bin/lib/provenance.mjs`
+- `distilled/workflows/resume.md`
+- `distilled/workflows/progress.md`
+- `.agents/skills/gsdd-resume/SKILL.md`
+- `.agents/skills/gsdd-progress/SKILL.md`
+- `tests/phase.test.cjs`
+- `tests/gsdd.guards.test.cjs`
+- `tests/gsdd.scenarios.test.cjs`
+- GSD comparison source: GSD session-routing surfaces assume the checkpoint itself is the dominant continuity signal. GSDD now keeps that behavior only for real execution checkpoints (`phase`, `quick`) and treats generic checkpoints as context once the user has already been routed onward.
+
+**Consequences:**
+- A surviving generic checkpoint can coexist with milestone-close or next-phase guidance without forcing the user back into `/gsdd-resume`.
+- `resume` still owns the destructive checkpoint-cleanup step, which keeps cleanup tied to an explicit user choice rather than to a read-only reporter.
+- Future checkpoint lifecycle edits must update the shared provenance helper, the authored workflow contracts, the regenerated skill surfaces, and the regression suites together or the repo truth will drift immediately.
+
+**GSDD implementation:** `bin/lib/provenance.mjs`, `distilled/workflows/resume.md`, `distilled/workflows/progress.md`, `.agents/skills/gsdd-resume/SKILL.md`, `.agents/skills/gsdd-progress/SKILL.md`, `.planning/SPEC.md`, `.internal-research/TODO.md`, `.internal-research/gaps.md`, `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.scenarios.test.cjs`
+
 ## Maintenance
 
 This document is updated when: