gsdd-cli 0.16.1 → 0.18.1

package/distilled/DESIGN.md

@@ -50,6 +50,25 @@
 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)
+53. [Fail-Closed Milestone And Phase Contracts](#d53---fail-closed-milestone-and-phase-contracts)
+54. [Bounded Brownfield Change Folder Contract](#d54---bounded-brownfield-change-folder-contract)
+55. [Brownfield Continuity Anchor And Mismatch Split](#d55---brownfield-continuity-anchor-and-mismatch-split)
+56. [Executable Brownfield Routing And Widen-Only Escalation](#d56---executable-brownfield-routing-and-widen-only-escalation)
+57. [Bounded Brownfield Growth And Context-Preserving Milestone Handoff](#d57---bounded-brownfield-growth-and-context-preserving-milestone-handoff)
+58. [Local Workflow Helper Launcher](#d58---local-workflow-helper-launcher)
 
 ---
 
@@ -841,7 +860,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/`.
 
@@ -863,6 +882,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
 
@@ -941,7 +961,9 @@ Implementation lives under `bin/lib/`:
 | W7 | WARN | `distilled/DESIGN.md` health check table differs from implemented check IDs |
 | W8 | WARN | `distilled/README.md` workflow inventory differs from `distilled/workflows/` |
 | W9 | WARN | `.internal-research/gaps.md` references missing repo-local paths |
-| W10 | WARN | `.planning/ROADMAP.md` phase status differs from `.planning/SPEC.md` requirement checkboxes |
+| 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 |
@@ -971,7 +993,7 @@ Implementation lives under `bin/lib/`:
 
 **What was removed vs GSD:**
 - `--repair` flag and associated repair actions
-- Error codes E001-E005/W001-W007 (replaced with simpler E1-E8/W1-W10/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)
@@ -1245,7 +1267,7 @@ D12 established the session persistence design. D26 mechanically enforces the ro
 
 **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:**
 
@@ -1277,7 +1299,7 @@ Consider clearing context before starting the next workflow for best results.
 
 **Routing map (acyclic, complete):**
 - `new-project` → `/gsdd-plan`
-- `plan` → `/gsdd-execute`
+- `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)
@@ -1713,18 +1735,20 @@ Sub-gap (b) was closed by D28's `<persistence>` mandate and guarded by G30. Sub-
 
 **Problem:** The brownfield path was structurally incomplete. `map-codebase` generated useful orientation artifacts, but it routed users only toward full project initialization. `quick` remained blind to those same codebase maps, so brownfield users who wanted disciplined feature work without full roadmap ceremony had no first-class lane.
 
-**Decision:** Wire the existing brownfield lane instead of adding a new workflow.
+**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 brownfield feature work.
-- `quick` now reads `.planning/codebase/ARCHITECTURE.md` and `.planning/codebase/STACK.md` when they exist and passes a summarized `$CODEBASE_CONTEXT` into the planner delegate.
+- `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 awareness without forcing full milestone ceremony.
+**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.
+**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 branch for feature-by-feature brownfield work.
+**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), `distilled/workflows/map-codebase.md` (completion routing), `tests/gsdd.guards.test.cjs`, `tests/gsdd.scenarios.test.cjs`
+**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:**
 
@@ -1932,7 +1956,677 @@ Sub-gap (b) was closed by D28's `<persistence>` mandate and guarded by G30. Sub-
 
 ---
 
-## Maintenance
+## 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`
+
+---
+
+## D53 - Fail-Closed Milestone And Phase Contracts
+
+**Decision (2026-04-21):** Active milestone roadmaps and new phase plans must carry explicit anti-drift contract fields so agents stop and challenge ambiguity instead of inferring scope or overclaiming closure.
+
+**Context:**
+- v1.5.0 milestone-init truth correctly identified the brownfield middle-lane gap, but the active roadmap was still too weak at the phase-contract layer: one-line phase goals without assigned requirements, explicit out-of-scope, or stop/replan conditions.
+- The repo already had stronger anti-drift rules in `AGENTS.md`, `.internal-research/lessons-learned.md`, and the existing plan/execution/verification skills, but they were fragmented across governance and postmortems rather than enforced by the roadmap and `PLAN.md` schema themselves.
+- Cross-SOTA research converged on the same pattern: OpenSpec/Spec Kit/LeanSpec/Task Master all keep stronger `what / not this / done means` boundaries than the old GSDD roadmap shape, while Anthropic/OpenAI/GitHub guidance all push pause-on-ambiguity, explicit evidence, and approval gates near side effects.
+
+**Decision:**
+- Harden active roadmap phases into compact execution contracts:
+  - requirement assignments
+  - success criteria
+  - out-of-scope
+  - stop/replan conditions
+- Harden `PLAN.md` into a fail-closed anti-drift contract with explicit:
+  - `non_goals`
+  - `hard_boundaries`
+  - `escalation_triggers`
+  - `approval_gates`
+  - `anti_regression_targets`
+  - `closure_claim_limit`
+  - `parallelism_budget`
+  - `leverage` (`lost / kept / gained`)
+- Upgrade planner checking to block missing anti-drift contract fields instead of treating them as optional prose quality.
+- Thread the new contract through execution and verification so the fields constrain what execution may do and what closure may claim.
+
+**Why this fits the codebase:**
+- It keeps the existing Workspine lifecycle intact instead of inventing a new workflow family.
+- It codifies rules the repo already depends on, rather than adding another layer of planning ceremony.
+- It raises rigor where the failure mode actually lives: weak roadmap and plan contracts, not missing abstract governance prose.
+- It stays compact and checkable, following the repo's “rigor that pays rent” principle rather than adopting heavier spec-framework ceremony wholesale.
+
+**Evidence:**
+- `.planning/SPEC.md` (`PLAN-03`, v1.5.0 Current State, key decision on anti-drift planning contract)
+- `.planning/ROADMAP.md` (v1.5.0 Phases 39-43)
+- `.internal-research/TODO.md` (active v1.5.0 objective and next-step reconciliation)
+- `.internal-research/lessons-learned.md` (`LL-PLANS-MUST-CARRY-THE-ANTI-DRIFT-CONTRACT`, `LL-ACTIVE-MILESTONE-TRUTH-MUST-STAY-SYNCHRONIZED`, `LL-AMBIGUITY-ABOUT-INTENT-MUST-STOP-EXECUTION`)
+- `.agents/skills/gsdd-new-milestone/SKILL.md`
+- `.agents/skills/gsdd-plan/SKILL.md`
+- `.agents/skills/gsdd-execute/SKILL.md`
+- `.agents/skills/gsdd-verify/SKILL.md`
+- GSD comparison source: `get-shit-done/workflows/new-milestone.md` and `get-shit-done/workflows/plan.md` preserve stronger planning discipline than the weakened one-line GSDD roadmap shape had drifted into.
+- External comparison sources: OpenSpec concepts/workflows, LeanSpec guide/limits, OpenAI practical guide to building agents, Anthropic effective/trustworthy agents, GitHub Copilot task best practices.
+
+**Consequences:**
+- Active milestone phases are no longer loose roadmap themes; they are the minimum durable contract needed for safe planning.
+- `gsdd-plan` now fails closed when the roadmap phase contract is too weak or self-contradictory.
+- Execution and verification inherit explicit anti-drift boundaries instead of reconstructing them from memory or postmortems.
+- The active milestone truth now needs to stay synchronized across the planning surfaces that drive work, or the contradiction itself becomes a blocker.
+
+---
+
+## D54 - Bounded Brownfield Change Folder Contract
+
+**Decision (2026-04-21):** The medium-scope brownfield lane should use one dedicated `brownfield-change/` folder family with three files (`CHANGE.md`, `HANDOFF.md`, `VERIFICATION.md`) instead of stretching `quick` or reusing milestone phases outside `ROADMAP.md`.
+
+**Context:**
+- D47 intentionally repaired the existing quick brownfield lane without turning it into a hidden middle lane. That left `I43` open on purpose: bounded quick work was cleaner, but ticket/PBI-sized brownfield work still had no durable repo-native contract outside milestones.
+- Phase 39 then hardened the anti-drift planning contract so Phase 40 could define the lane shape under a stronger control surface instead of improvising another loose planning artifact.
+- Phase 40 research converged on the same tradeoff from both repo truth and adjacent systems: one-file brownfield state collapses scope, live status, and proof into a conflict-prone hotspot, while reusing phase artifacts outside milestones either becomes milestone-lite or demands a second planning system.
+
+**Decision:**
+- Introduce one dedicated medium-scope change-folder family under `.planning/templates/brownfield-change/`:
+  - `CHANGE.md` is the canonical active change contract
+  - `HANDOFF.md` carries rolling decision context and anti-regression judgment
+  - `VERIFICATION.md` carries the bounded closeout proof
+- Keep the lane explicitly bounded:
+  - one active medium-scope change stream at a time
+  - no phase numbering or roadmap semantics inside the change folder
+  - multiple PR slices are allowed only when write ownership is explicitly disjoint and every slice still rolls up to one shared goal and closeout path
+- Keep routing, resume continuity, and milestone handoff out of this phase. The contract lands first; Phases 41-43 own continuity, deterministic routing, and promotion behavior.
+
+**Why this fits the codebase:**
+- It preserves the existing milestone-owned lifecycle engine instead of creating a second roadmap system.
+- It keeps the new lane repo-native and file-backed, which matches the rest of Workspine's continuity model.
+- It separates active scope, rolling handoff, and closeout proof without exploding into milestone ceremony.
+- It turns the middle lane into an explicit product contract rather than quiet scope creep inside `quick`.
+
+**Evidence:**
+- `.planning/SPEC.md` (`BROWNFIELD-01` through `BROWNFIELD-05`, Current State, key decision row)
+- `.planning/ROADMAP.md` (Phase 40 success criteria and follow-on Phases 41-43)
+- `.planning/templates/brownfield-change/CHANGE.md`
+- `.planning/templates/brownfield-change/HANDOFF.md`
+- `.planning/templates/brownfield-change/VERIFICATION.md`
+- `.internal-research/TODO.md` (active v1.5.0 order after Phase 40 execution)
+- `.internal-research/gaps.md` (`I43`, `I46`)
+- `SPEC.md` (bounded brownfield lane product contract)
+- `tests/gsdd.guards.test.cjs`
+- GSD comparison source: `get-shit-done/workflows/quick.md` and `get-shit-done/workflows/new-project.md` keep brownfield work closer to the lightweight quick lane or to full project/milestone planning; they do not define a distinct medium-scope change-folder family.
+- External comparison sources: OpenSpec concepts/getting-started docs, Task Master docs, BMAD workflow map, GitHub Copilot coding-agent best practices.
+
+**Consequences:**
+- The medium-scope lane now has a concrete artifact contract instead of an open-ended "maybe deepen quick later" gap.
+- Future continuity and routing work must build on this folder family rather than inventing a different middle-lane shape.
+- `quick` remains the sub-hour lane, and milestones remain the only roadmap-owned lifecycle.
+- If future work weakens the one-active-stream or disjoint-write-ownership boundaries, the repo should treat that as contract drift, not as harmless copy edits.
+
+---
+
+## D55 - Brownfield Continuity Anchor And Mismatch Split
+
+**Decision (2026-04-21):** Active medium-scope brownfield continuity should use one operational anchor plus one judgment surface: `CHANGE.md` owns status, integration surface, and next action; `HANDOFF.md` owns the cold-start judgment layer. `progress` stays warning-only, while `resume` requires acknowledgement when live git/worktree truth materially conflicts with the active change artifact.
+
+**Context:**
+- D54 defined the bounded `brownfield-change/` 3-file family, but it deliberately left continuity, resume behavior, and drift handling for the next phase.
+- Existing repo continuity already had the right primitives in separate places: provenance split in Phase 19, shared lifecycle derivation in Phase 29, deterministic preflight in Phase 30, and generic-checkpoint ownership repair in Phase 33.
+- Without an explicit anchor split, the new lane risked recreating the same ambiguity the milestone hardening had just removed: two files that both looked like status truth, plus git/worktree drift that could remain visible only to whichever session happened to notice it.
+
+**Decision:**
+- Treat `.planning/brownfield-change/CHANGE.md` as the canonical operational continuity anchor for:
+  - current posture
+  - integration surface
+  - owner/runtime
+  - next action
+  - declared write scope when PR slices exist
+- Treat `.planning/brownfield-change/HANDOFF.md` as the judgment-only cold-start surface for:
+  - active constraints
+  - unresolved uncertainty
+  - decision posture
+  - anti-regression
+  - context behind the next action
+- Add one helper-backed continuity seam:
+  - `bin/lib/lifecycle-state.mjs` reconstructs the active brownfield state from repo artifacts
+  - `bin/lib/provenance.mjs` classifies material mismatch between the artifact and live git/worktree truth
+- Keep the mismatch split asymmetric:
+  - `progress` warns but remains read-only
+  - `resume` requires acknowledgement before continuing from materially misleading brownfield continuity state
+
+**Why this fits the codebase:**
+- It extends the existing repo-truth continuity model instead of inventing a second hidden state system or a new user-facing brownfield command.
+- It preserves the earlier checkpoint-ownership rule: read-only reporting should not silently become a gating/mutating control surface.
+- It keeps cold-start judgment available without turning the operational artifact into a second copy of the judgment layer.
+- It narrows `I46` honestly: the repo can now detect more drift deterministically, but it still does not pretend gitignored `.planning/` persistence is solved.
+
+**Evidence:**
+- `.planning/SPEC.md` (`BROWNFIELD-02`, `BROWNFIELD-05`, Current State, key decision row)
+- `.planning/phases/41-brownfield-continuity-and-resume/41-PLAN.md`
+- `.planning/templates/brownfield-change/CHANGE.md`
+- `.planning/templates/brownfield-change/HANDOFF.md`
+- `bin/lib/lifecycle-state.mjs`
+- `bin/lib/provenance.mjs`
+- `distilled/workflows/progress.md`
+- `distilled/workflows/resume.md`
+- `tests/phase.test.cjs`
+- `tests/gsdd.guards.test.cjs`
+- `tests/gsdd.scenarios.test.cjs`
+- GSD comparison sources: `get-shit-done/workflows/resume.md` and `get-shit-done/workflows/progress.md` keep continuity centered on session checkpoints and roadmap state; they do not define a separate medium-scope brownfield continuity anchor with explicit artifact-versus-worktree mismatch handling.
+
+**Consequences:**
+- The medium-scope lane now has a deterministic repo-truth continuity floor rather than only a static artifact family.
+- `CHANGE.md` and `HANDOFF.md` no longer compete implicitly for authority; future edits must preserve the one-anchor split.
+- `progress` can report the active brownfield state without widening into a mutating workflow.
+- `resume` can restore brownfield continuity honestly while still stopping short of the broader routing and promotion work reserved for Phases 42-43.
+
+## D56 - Executable Brownfield Routing And Widen-Only Escalation
+
+**Decision (2026-04-21):** Brownfield routing should treat `CHANGE.md` as the default operational anchor and allow a surviving `phase` or `quick` checkpoint to outrank it only when one strict-match rule proves the checkpoint is still the active execution surface. From concrete brownfield state, `/gsdd-new-project` remains available only as an intentional widen path into full milestone setup, not as an accidental fallback recommendation.
+
+**Context:**
+- D54 defined the bounded `brownfield-change/` contract and D55 established its continuity floor, but the routing matrix above those artifacts was still inconsistent: `progress` could still route back through stale checkpoint residue, `resume` could still make a non-matching checkpoint primary, and `quick` / `map-codebase` / `new-project` still risked implying that full lifecycle initialization was the normal fallback from already-concrete bounded work.
+- The repo already had the right raw pieces in place: checkpoint-class ownership from D52, one-anchor continuity from D55, non-phase state derivation in `lifecycle-state.mjs`, and generated-surface freshness via `gsdd update`.
+- Phase 42 was intentionally scoped to validity of next-step routing only. It did not reopen growth policy, add a new command, or weaken the one-active-stream contract.
+
+**Decision:**
+- Add one shared routing seam in `bin/lib/provenance.mjs`:
+  - `generic` checkpoints never outrank an active brownfield change
+  - `phase` and `quick` checkpoints outrank `CHANGE.md` only when branch alignment, scope alignment, and still-active execution state all hold at once
+  - otherwise the checkpoint stays visible context, but the brownfield operational anchor remains primary
+- Apply that same rule across the authored `progress` and `resume` contracts instead of letting each workflow invent its own checkpoint-versus-change exception.
+- Keep `/gsdd-new-project` available from brownfield surfaces only as an explicit widen path:
+  - `quick` uses it when the bounded change is still undefined or when the user intentionally widens scope
+  - `map-codebase` frames it as full lifecycle setup only when the user wants to widen beyond bounded brownfield work
+  - `new-project` itself recognizes existing `CHANGE.md` continuity and treats invocation from that state as deliberate promotion, not mistaken routing
+- Lock the contract with helper, guard, and generated-surface scenario coverage.
+
+**Why this fits the codebase:**
+- It extends the existing provenance helper and generated-surface workflow model instead of inventing another routing registry or hidden state store.
+- It preserves the D55 one-anchor split: checkpoints stay visible and resume-owned, but they do not silently demote the active brownfield contract unless the repo can prove the checkpoint is still current.
+- It keeps the brownfield lane bounded by removing accidental fallback escalation while still preserving an intentional route into milestone planning.
+- It matches the repo's anti-drift posture: ambiguous or weak routing proof fails closed in favor of the current operational anchor.
+
+**Evidence:**
+- `.planning/SPEC.md` (`BROWNFIELD-03`, Current State, key decision row)
+- `.planning/phases/42-executable-brownfield-routing/42-PLAN.md`
+- `bin/lib/provenance.mjs`
+- `distilled/workflows/progress.md`
+- `distilled/workflows/resume.md`
+- `distilled/workflows/quick.md`
+- `distilled/workflows/map-codebase.md`
+- `distilled/workflows/new-project.md`
+- `.internal-research/TODO.md`
+- `.internal-research/gaps.md` (`I43`, `I46`)
+- `tests/phase.test.cjs`
+- `tests/gsdd.guards.test.cjs`
+- `tests/gsdd.scenarios.test.cjs`
+- `get-shit-done/workflows/progress.md`, `get-shit-done/workflows/resume.md`, `get-shit-done/workflows/quick.md`, `get-shit-done/workflows/new-project.md`
+
+**Consequences:**
+- Brownfield next-step routing now has one deterministic precedence rule instead of five workflow-local interpretations.
+- A stale or unrelated `phase` / `quick` checkpoint can remain reviewable without automatically hijacking the current brownfield lane.
+- `/gsdd-new-project` remains part of the system, but as deliberate promotion from concrete brownfield work rather than as a generic fallback.
+- Phase 43 can now focus on bounded growth and milestone handoff instead of first repairing invalid routing recommendations.
+
+## D57 - Bounded Brownfield Growth And Context-Preserving Milestone Handoff
+
+**Decision (2026-04-22):** When bounded brownfield work widens into milestone planning, keep the lane explicit and case-by-case. Reuse `CHANGE.md`, `HANDOFF.md`, and `VERIFICATION.md` directly as the promotion input surface through `/gsdd-new-project` (first milestone) or `/gsdd-new-milestone` (subsequent milestone) instead of inventing another artifact family or silently widening the lane.
+
+**Context:**
+- D54 established the bounded brownfield artifact family, D55 gave it a continuity floor, and D56 repaired routing precedence. That still left the final growth seam open: how the bounded lane should widen without becoming milestone-lite or forcing rediscovery.
+- The risk was architectural, not cosmetic. Without an explicit handoff rule, future work could either accrete ad hoc behavior into `quick`-style lanes or create a second "promotion" artifact that duplicated state the brownfield family already carried.
+- Phase 43 was deliberately scoped to finish that seam inside the current architecture: no new workflow family, no hidden state store, and no automatic promotion.
+
+**Decision:**
+- Keep widening explicit and structural, not automatic:
+  - stay in the bounded lane by default
+  - widen only when the work no longer fits one active stream, needs milestone-owned lifecycle state, or needs broader requirement/phase tracking
+- Reuse the existing brownfield artifact family directly during widening:
+  - `CHANGE.md` remains the operational summary of goal, scope, next action, and write scope
+  - `HANDOFF.md` remains the preserved judgment surface
+  - `VERIFICATION.md` remains the carried-forward proof and gap surface, including partial validation
+- Split the milestone-init paths honestly:
+  - `/gsdd-new-project` is the widen path when no shipped milestone history exists yet
+  - `/gsdd-new-milestone` is the widen path when the repo already has shipped milestone history
+- Keep `progress` and `resume` explicit about this boundary so widening remains a deliberate user choice rather than a default fallback.
+
+**Why this fits the codebase:**
+- It completes the brownfield lane using the existing artifact family rather than adding another continuity surface.
+- It preserves the one-active-stream posture by making growth structural and case-by-case instead of opening the lane into silent multi-stream sprawl.
+- It keeps first-milestone and subsequent-milestone initiation aligned without pretending they are the same lifecycle posture.
+- It avoids rediscovery debt: milestone setup inherits current scope, judgment, and proof from repo truth rather than from chat memory.
+
+**Evidence:**
+- `.planning/SPEC.md` (`BROWNFIELD-04`, Current State, key decision row)
+- `.planning/phases/43-bounded-growth-and-milestone-handoff/43-PLAN.md`
+- `.planning/templates/brownfield-change/CHANGE.md`
+- `.planning/templates/brownfield-change/HANDOFF.md`
+- `.planning/templates/brownfield-change/VERIFICATION.md`
+- `distilled/workflows/progress.md`
+- `distilled/workflows/resume.md`
+- `distilled/workflows/new-project.md`
+- `distilled/workflows/new-milestone.md`
+- `.internal-research/TODO.md`
+- `.internal-research/gaps.md` (`I43`, `I46`)
+- `.internal-research/lessons-learned.md`
+- `tests/phase.test.cjs`
+- `tests/gsdd.guards.test.cjs`
+- `tests/gsdd.scenarios.test.cjs`
+- `get-shit-done/workflows/new-project.md`, `get-shit-done/workflows/quick.md`
+
+**Consequences:**
+- The bounded lane now has an explicit growth contract instead of a hand-wavy "promote later" escape hatch.
+- Milestone initiation can inherit real brownfield context without adding a second handoff file or restarting discovery.
+- `progress` and `resume` can present widening as a deliberate choice while keeping `CHANGE.md` primary until the user intentionally crosses the lifecycle boundary.
+- Phase 43 can now verify one concrete seam: bounded growth and context-preserving milestone handoff from repo truth.
+
+## D58 - Local Workflow Helper Launcher
+
+**Decision (2026-04-22):** Workflow-embedded CLI helper commands must run through a generated local launcher at `.planning/bin/gsdd.mjs` instead of assuming a bare `gsdd` binary is available on the consumer repo's PATH.
+
+**Context:**
+- Public onboarding already leads with `npx gsdd-cli init`, which works even when the package is not globally installed.
+- The authored workflow surfaces had drifted into a different assumption: embedded helper commands such as `lifecycle-preflight`, `file-op`, and `phase-status` were written as bare `gsdd ...` invocations.
+- That split contract caused consumer friction in the exact place the deterministic helper seam was supposed to help: a workflow could initialize successfully, then fail later because the repo did not have a global `gsdd` on PATH.
+- The launcher must stay out of `.agents/` ownership so it does not pollute unrelated `.agents` folders or leak into generated governance.
+
+**Decision:**
+- Generate `.planning/bin/gsdd.mjs` on `gsdd init` for every initialized workspace.
+- Regenerate that launcher on `gsdd update` whenever `.planning/` exists.
+- Keep the launcher machine-independent by resolving back to the published `gsdd-cli` package version used for generation rather than embedding framework checkout paths.
+- Route workflow-embedded helper commands through `node .planning/bin/gsdd.mjs ...` for the deterministic helper seam:
+  - `lifecycle-preflight`
+  - `file-op`
+  - `phase-status`
+- Keep `.agents/skills/` as the canonical portable workflow discovery surface and keep generated `AGENTS.md` governance-only. No `.agents/bin` surface is introduced.
+
+**Why this fits the codebase:**
+- It preserves the existing skills-first architecture instead of inventing a second discovery or governance path.
+- It fixes the actual consumer DX failure at the point where workflows invoke deterministic helper commands.
+- It keeps ownership aligned with `.planning/`, which already holds the other local runtime mechanics and generation-manifest state.
+
+**Evidence:**
+- `bin/lib/init-flow.mjs`
+- `bin/lib/rendering.mjs`
+- `bin/lib/runtime-freshness.mjs`
+- `bin/lib/manifest.mjs`
+- `bin/lib/health.mjs`
+- `distilled/workflows/execute.md`
+- `distilled/workflows/verify.md`
+- `distilled/workflows/resume.md`
+- `tests/gsdd.init.test.cjs`
+- `tests/gsdd.health.test.cjs`
+- `tests/gsdd.manifest.test.cjs`
+- `tests/gsdd.scenarios.test.cjs`
+
+**Consequences:**
+- Consumer repos no longer need a global `gsdd` binary for workflow-embedded helper mechanics after init.
+- Helper-command freshness is now owned under `.planning/` without widening `.agents` install detection.
+- Generated governance remains compact and routing-focused because launcher instructions stay out of `AGENTS.md`.
+
+## Maintenance
 
 This document is updated when: