# GSDD Design Decisions > 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. --- ## Table of Contents 1. [4-File Codebase Standard](#1-4-file-codebase-standard) 2. [Agent Consolidation: 11 to 10](#2-agent-consolidation-11-to-10) 3. [Two-Layer Architecture: Roles and Delegates](#3-two-layer-architecture-roles-and-delegates) 4. [Zero-Hop Security Propagation](#4-zero-hop-security-propagation) 5. [Conditional Synthesizer](#5-conditional-synthesizer) 6. [Mapper Staleness: Standalone Workflow](#6-mapper-staleness-standalone-workflow) 7. [Milestone Hierarchy and Phase Continuation](#7-milestone-hierarchy-and-phase-continuation) 8. [Advisory Git Protocol](#8-advisory-git-protocol) 9. [Adapter Generation Over Conversion](#9-adapter-generation-over-conversion) 10. [Context Isolation: Summaries Up, Documents to Disk](#10-context-isolation-summaries-up-documents-to-disk) 11. [Quick-Work Lane](#11-quick-work-lane) 12. [Session Persistence Without State File](#12-session-persistence-without-state-file) 13. [Mechanical Invariant Enforcement](#13-mechanical-invariant-enforcement) 14. [Headless Mode](#14-headless-mode) 15. [Model Profile Propagation](#15-model-profile-propagation) 16. [Template Versioning via Generation Manifest](#16-template-versioning-via-generation-manifest) 17. [CLI Composition Root Boundary](#17-cli-composition-root-boundary) 18. [Codex CLI Native Adapter](#18-codex-cli-native-adapter) 19. [Scenario-Based Eval Coverage](#19-scenario-based-eval-coverage) 20. [Workspace Health Diagnostics](#20-workspace-health-diagnostics) 21. [OWASP Authorization Matrix](#21-owasp-authorization-matrix) 22. [Delegate Layer Architecture](#22-delegate-layer-architecture) 23. [Mapper Output Quantification](#23-mapper-output-quantification) 24. [Consumer Governance Completeness](#24-consumer-governance-completeness) 25. [Consumer First-Run Experience](#25-consumer-first-run-experience) 26. [Session Continuity Contract Hardening](#26-session-continuity-contract-hardening) 27. [Consumer-Ready Surface Completion](#27-consumer-ready-surface-completion) 28. [Workflow Completion Routing](#28-workflow-completion-routing) 29. [Approach Exploration](#29-approach-exploration) 30. [Hardening Propagation](#30-hardening-propagation) 31. [Outcome Dimension for Plan-Checker](#31-outcome-dimension-for-plan-checker) 32. [Quick Workflow Alignment Hardening](#32-quick-workflow-alignment-hardening) 33. [Quick Approach Clarification](#33-quick-approach-clarification) 34. [Context Engineering Applied to Quick Workflow](#34-context-engineering-applied-to-quick-workflow) 35. [Skills-Native Runtimes vs Governance Adapters](#35-skills-native-runtimes-vs-governance-adapters) 36. [Interactive Init Wizard](#36-interactive-init-wizard) 37. [Mutability-Driven Workflow Classification](#37-mutability-driven-workflow-classification) 38. [Retroactive Artifact Enforcement](#38-retroactive-artifact-enforcement) 39. [Brownfield Entry Wiring](#39-brownfield-entry-wiring) 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) 59. [Continuity Authority And Planning-State Drift](#d59---continuity-authority-and-planning-state-drift) 60. [Release Closeout Contract](#d60---release-closeout-contract) 61. [Deliberate Subagent Contract](#d61---deliberate-subagent-contract) 62. [Repo-Native Browser Proof Contract](#d62---repo-native-browser-proof-contract) 63. [Computed-First Control Map](#d63---computed-first-control-map) 64. [Work-Native Continuity Authority](#d64---work-native-continuity-authority) --- ## 1. 4-File Codebase Standard **GSD:** 7 static files during codebase mapping -- STACK.md, ARCHITECTURE.md, CONVENTIONS.md, CONCERNS.md, STRUCTURE.md, INTEGRATIONS.md, TESTING.md. **GSDD:** 4 files -- STACK.md, ARCHITECTURE.md, CONVENTIONS.md, CONCERNS.md. **What was dropped and where the rules went:** | Dropped file | Absorbed into | Rationale | | --------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | STRUCTURE.md | CONVENTIONS.md ("Where to put new code") | Physical directory maps break the moment a folder is added. Stale structure causes agent hallucination. Modern agents use dynamic tools (tree-sitter, codebase indexing) to view current structure. | | INTEGRATIONS.md | STACK.md + CONVENTIONS.md | Database schemas and endpoint maps change daily. Agents should read definitive `schema.prisma` or `init.sql` dynamically, not trust a stale markdown summary. | | TESTING.md | CONVENTIONS.md ("How to mock the database", testing patterns) | Testing conventions are stable rules; test inventories are not. Rules belong in CONVENTIONS.md. | **Core principle:** Drop the _state_ (which rots), keep the _rules_ (which don't). Maximum architectural discipline without feeding stale topologies into limited context windows. **Evidence:** - 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) - `.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 --- ## 2. Agent Consolidation: 11 to 10 **GSD:** 11 specialized agent files, each scoped to a single concern. **GSDD:** 10 canonical roles. 2 mergers, 1 extraction, 1 addition (approach-explorer, D29). **Merger table:** | Canonical role | Absorbs from GSD | Merger criteria | | ------------------------ | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `integration-checker.md` | `gsd-integration-checker.md` | Cross-phase integration checking is structurally different from single-phase verification: different inputs (all phase SUMMARYs/VERIFICATIONs vs single phase), different scope (milestone-wide wiring vs phase goal), different algorithm (connectivity checks vs goal-backward). Extracted as standalone role rather than absorbed into verifier. | | `researcher.md` | `gsd-project-researcher.md` + `gsd-phase-researcher.md` | Same algorithm, different scope. Scope is an input parameter, not a role distinction. Clean merger. | | `planner.md` | `gsd-planner.md` + `gsd-plan-checker.md` | Reduces coordination overhead. **Tradeoff:** GSD's plan-checker was a fresh-context adversarial pass with a 3-cycle revision loop (planner -> checker -> revise x 3 max). GSDD keeps an explicit `plan-checker` contract, generates native planner/checker entry surfaces where runtimes can support the loop directly, and describes reduced-assurance fallback in the portable workflow when no independent checker runs. | | `verifier.md` | `gsd-verifier.md` | Phase-level goal-backward verification remains the verifier's scope. Cross-phase integration audit remains a separate milestone surface rather than being silently absorbed. GSDD keeps the compact verification-report base fields and also preserves richer structured verifier findings where they materially improve re-verification and gap closure. | **Known tradeoffs in mergers:** The researcher merger is clean - scope is genuinely a parameter. The planner and verifier mergers each carry a real cost: - **Planner:** External verification by a fresh-context agent catches blind spots the author cannot catch in self-review. GSDD restores that concept with a canonical `plan-checker` delegate, native planner/checker entry surfaces for Claude/OpenCode, and a portable workflow that describes reduced-assurance fallback when no independent checker runs. Verify quality checks now live inside `task_completeness`, so the planner/checker contract enforces runnable, fast, and ordered verification. - **Adapter boundary:** `bin/gsdd.mjs` now stays the thin generator entrypoint and adapter dispatcher, while vendor-specific rendering lives under `bin/adapters/`. This is an architecture cleanup, not proof of runtime parity by itself. - **Verifier:** The integration-checker's cross-phase wiring scope (orphaned exports, unconsumed API routes, broken E2E flows) is structurally different from single-phase goal-backward verification. GSDD keeps `verifier.md` phase-scoped and implements milestone integration audit as a separate surface: `distilled/workflows/audit-milestone.md` with `integration-checker.md`. - **Verifier output contract:** Upstream GSD exposes two relevant shapes: the slim `verification-report.md` template with base fields (`phase`, `verified`, `status`, `score`) and the richer `gsd-verifier.md` output example with structured `re_verification`, `gaps`, and `human_verification`. GSDD keeps the richer phase-verifier structure intentionally, but labels it as normalized verifier behavior rather than pretending every field came from the slimmer template alone. **Integration-checker second-pass recovery (2026-03-12):** The first extraction of `integration-checker.md` preserved the milestone scope and core algorithm, but over-stripped execution leverage. The recovery pass keeps the portable role framework-neutral while restoring the upstream scaffolding that materially improves compliance: - **Kept from GSD:** mandatory initial-read discipline, explicit section boundaries, auth-protection verification, end-to-end flow tracing, typed structured return, and checklist-driven completion. - **Intentionally stripped:** framework-specific Bash recipes, hardcoded path assumptions, file-extension-specific grep flags, and other tool/runtime details that do not survive vendor-agnostic distillation well. - **Gained in GSDD:** a cleaner split between role contract and milestone workflow, a stronger explicit phase-vs-milestone boundary, and a portable typed report shape aligned to the milestone auditor's current schema. **Systemic role-contract hardening follow-up (2026-03-12):** The same over-distillation pattern had also flattened `roadmapper.md`, `synthesizer.md`, `verifier.md`, and `planner.md`. The first recovery pass restored visible structure, but the follow-up audit found that structure alone was not enough. The current hardening pass restores the stricter mechanics that materially improve compliance while continuing to strip vendor/tool specifics. - **Roadmapper kept from GSD:** mandatory initial-read discipline, bounded section structure, explicit coverage validation, parse-critical artifact contract, structured return modes, and checklist-driven completion. - **Roadmapper intentionally stripped:** template-path references, commit steps, and vendor-specific file conventions. - **Roadmapper gained in GSDD:** an explicit `.planning/ROADMAP.md` ownership contract, explicit `[ ]` / `[-]` / `[x]` status grammar, a concrete `ROADMAP CREATED` artifact example, and a hard boundary that this role does not settle the separate ROADMAP/STATE lifecycle seam. - **Synthesizer kept from GSD:** mandatory initial-read discipline, deterministic research-input contract, execution-flow structure, output-format block, structured returns, blocked return shape, provenance via `Sources`, and completion checklist. - **Synthesizer intentionally stripped:** commit behavior, template paths, and literal shell snippets. - **Synthesizer gained in GSDD:** cleaner alignment with conditional invocation by `researchDepth` rather than implying it always runs, plus an explicit scope boundary that keeps research, roadmap authoring, and git ownership separate. - **Verifier kept from GSD:** mandatory initial-read discipline, explicit must-have derivation steps, named L1/L2/L3 checks, truth-level status taxonomy, explicit key-link categories, typed report example, machine-usable structured gaps, structured return, and completion checklist. - **Verifier intentionally stripped:** GSD tool invocations, literal grep/bash procedures, and commit steps. - **Verifier gained in GSDD:** a portable verification-basis discovery protocol, grouped-gap guidance, a dedicated `` contract for orchestrator handoff, and a stricter frontmatter-only machine-readable findings contract that now lines up directly with the current normalized `VERIFICATION.md` schema and the separate milestone-audit boundary. - **Planner kept from GSD:** mandatory initial-read discipline, bounded section structure, context-fidelity rules, TDD detection heuristic, automated-verify discipline, test-scaffold-first rule when verification is missing, explicit output block, structured planning return, and completion checklist. - **Planner intentionally stripped:** `user_setup`, vendor runtime/tool instructions, commit steps, and GSD-specific validation commands. - **Planner gained in GSDD:** recovered strictness without regressing the current GSDD schema (`files-modified`, `checkpoint:user`, `checkpoint:review`, `2-5` tasks max, reduced-assurance checker fallback), plus portable gap-closure semantics and a concrete dependency-graph / wave example. Full `type: tdd` lifecycle support remains later research, not part of this recovery. **Executor leverage audit (2026-03-13):** The executor was the last un-audited core lifecycle role. At 89 lines it was the most under-structured role contract in the system — no XML section boundaries, no explicit context-intake tiers, no scope boundary, no typed output example, no auth-gate protocol, no completion checklist. The audit applied the same S12 hardening pattern. - **Executor kept from GSD:** mandatory context-intake discipline, explicit deviation-rule examples (null pointers, missing auth, missing dependency, new DB tables), auth-gate protocol (401/403 recognition, checkpoint return with exact auth steps), substantive summary quality gate, TDD RED/GREEN/REFACTOR steps with infrastructure detection, self-check discipline, and completion checklist. - **Executor intentionally stripped:** wave-based parallelization, agent tracking journal, segment execution patterns A/B/C, auto-mode checkpoint routing (`auto_advance` config), per-task commit format `{type}({phase}-{plan}):`, `gsd-tools.cjs` CLI commands, template path references (`~/.claude/`), `user_setup` generation, `executor_model` selection, and codebase-map sync with dropped files (`STRUCTURE.md`, `INTEGRATIONS.md`). - **Executor gained in GSDD:** XML-bounded section structure, explicit scope boundary (plan-scoped, does not own planning/verification/milestone audit), typed SUMMARY.md output example with YAML frontmatter, portable auth-gate protocol (checkpoint:user with exact steps, not vendor-specific checkpoint return format), and execution-loop alignment with the current GSDD plan schema (`checkpoint:user`, `checkpoint:review`, change-impact discipline). The accompanying workflow alignment pass on `distilled/workflows/execute.md` added four targeted changes: tiered context-intake enforcement, auth-gate routing in the checkpoint protocol, concrete deviation-rule examples matching the role contract, and a substantive summary quality gate. This hardening pass also clarified a reusable architectural rule: strict portable workflows are not enough if the canonical role contracts underneath them are flattened into prose. Role strictness and workflow strictness both matter. **Research-claim narrowing from `agentic-prd-sota.md`:** - **Keep:** density over brevity, no arbitrary line caps, bounded role contracts, deterministic inputs, and typed/machine-usable handoffs when another agent consumes the result. - **Narrow:** the nested-data benchmark is relevant to output schema choices, not to whether XML-style prompt sections should exist. Prompt delimiters and machine-readable output formats are different problems. - **Reject as universal claim:** "YAML is better than markdown" is too broad. The defensible rule is narrower: use constrained machine-readable structure when downstream agents must parse and aggregate findings. - **Keep scoped:** OWASP auth guidance remains decisive for the milestone integration/audit surface, not for these four role contracts. **Direct distillations (1:1 source lineage):** | Canonical role | GSD source | Audit status | | ---------------- | ------------------------------------------------------------------ | ------------------------------- | | `mapper.md` | `gsd-codebase-mapper.md` | source-audited | | `synthesizer.md` | `gsd-research-synthesizer.md` | source-audited (S12) | | `executor.md` | `gsd-executor.md` | source-audited (executor audit) | | `roadmapper.md` | `gsd-roadmapper.md` | source-audited (S12) | | `debugger.md` | `gsd-debugger.md` (standalone utility, not part of core lifecycle) | — | **Evidence:** - 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 --- ## 3. Two-Layer Architecture: Roles and Delegates **GSD:** Workflows embed role instructions inline. No separation between what an agent _is_ and what it _does_ in a given workflow. A single GSD workflow file (e.g., `new-project.md` at 851 lines) contains both orchestration logic and agent behavioral contracts. **GSDD:** Two explicit layers. | Layer | Location | Purpose | Example | | --------- | ------------------------------------ | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | Roles | `agents/*.md` | Durable contracts: identity, algorithm, quality guarantees, anti-patterns | `agents/mapper.md` -- defines the mapper's forbidden-files rule, output format, verification protocol | | Delegates | `distilled/templates/delegates/*.md` | Thin task-specific wrappers: scoped instructions referencing a role | `mapper-tech.md` -- tells the mapper to focus on tech stack, write to STACK.md | **Why two layers:** - Roles can be audited and improved independently of workflow wiring. - Delegates can be rewired (point to different output paths, change scope) without touching role semantics. - New workflows compose existing roles via new delegates without duplicating behavioral definitions. - Security rules, quality gates, and algorithms are defined once in the role -- not scattered across delegates. **Delegate thinness principle:** Delegates carry ONLY task-specific content (output path, focus area, return format, quality checklist). They do NOT contain algorithms, verification protocols, security rules, or anti-patterns -- those live in the role contract. **Delegate catalog:** | Delegate | Role | Output | Workflow | | ---------------------------- | ----------- | ------------------------------------ | ---------------------- | | `mapper-tech.md` | mapper | `.planning/codebase/STACK.md` | map-codebase | | `mapper-arch.md` | mapper | `.planning/codebase/ARCHITECTURE.md` | map-codebase | | `mapper-quality.md` | mapper | `.planning/codebase/CONVENTIONS.md` | map-codebase | | `mapper-concerns.md` | mapper | `.planning/codebase/CONCERNS.md` | map-codebase | | `researcher-stack.md` | researcher | `.planning/research/STACK.md` | new-project | | `researcher-features.md` | researcher | `.planning/research/FEATURES.md` | new-project | | `researcher-architecture.md` | researcher | `.planning/research/ARCHITECTURE.md` | new-project | | `researcher-pitfalls.md` | researcher | `.planning/research/PITFALLS.md` | new-project | | `researcher-synthesizer.md` | synthesizer | `.planning/research/SUMMARY.md` | new-project | | `plan-checker.md` | planner | JSON checker report | plan (native adapters) | **Distribution model:** `npx -y gsdd-cli init` copies role contracts from `agents/` to `.planning/templates/roles/` in consumer projects. Delegates in `.planning/templates/delegates/` reference the local role copy (`Read .planning/templates/roles/.md`). Consumer projects are self-contained at runtime -- no dependency on the framework repo. **Evidence:** - `agents/README.md` (Two-Layer Architecture and Runtime Distribution sections) - `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) - Delegate files under `distilled/templates/delegates/` (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 --- ## 4. Zero-Hop Security Propagation **GSD:** Security rules for mapper agents lived in `gsd-codebase-mapper.md` (the agent file). Workflows like `map-codebase.md` contained a `` block. Agents needed to read both the workflow and their own role definition to get the full security picture -- a one-hop dependency. **GSDD evolution (two phases):** | Phase | PR | What changed | | ------------ | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | A (one-hop) | PR 2 | Mapper delegates cross-referenced `` from the map-codebase skill. Security rules reachable but required reading a second file. | | B (zero-hop) | PR 4 | Full 12-category forbidden-files list absorbed into `agents/mapper.md`. Delegates reference the role contract directly. No second file needed. | **The zero-hop rule:** Any rule that a delegate MUST follow belongs in the role contract it references, not in a cross-referenced workflow file that consumer projects may or may not have. When a delegate reads its role contract, it gets the complete behavioral and security contract in one read. **Forbidden-files categories in `agents/mapper.md`:** 1. `.env`, `.env.*`, `*.env` 2. `credentials.*`, `secrets.*`, `*secret*`, `*credential*` 3. `*.pem`, `*.key`, `*.p12`, `*.pfx`, `*.jks` 4. `id_rsa*`, `id_ed25519*`, `id_dsa*` 5. `.npmrc`, `.pypirc`, `.netrc` 6. `config/secrets/*`, `.secrets/*`, `secrets/` 7. `*.keystore`, `*.truststore` 8. `serviceAccountKey.json`, `*-credentials.json` 9. `docker-compose*.yml` -- read for architecture; flag inline secrets under Hard stop 10. Gitignored files that appear to contain secrets 11. `node_modules/`, `vendor/`, `.git/` 12. Binary files, database files, media files **Hard stop:** Before writing CONCERNS.md, grep for `API_KEY`, `SECRET`, `PASSWORD`, `PRIVATE_KEY`, `-----BEGIN`, `Authorization:`. If hardcoded secrets found: STOP immediately, report to orchestrator. Mapper output gets committed to git -- leaked secrets are a security incident. **Evidence:** - `agents/mapper.md` lines 66-90 (Forbidden Files section + Hard stop) - `agents/_archive/gsd-codebase-mapper.md` lines 66-97 (original narrower rules) - 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 --- ## 5. Conditional Synthesizer **GSD:** Always spawns `gsd-research-synthesizer` after 4 researchers complete. Synthesizer reads all 4 research files, writes SUMMARY.md. No option to skip. **GSDD:** Conditional on `researchDepth` config: | researchDepth | Synthesizer behavior | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fast` | Orchestrator writes SUMMARY.md inline from the 4 human-read structured summaries it holds in context. No delegate spawned. | | `balanced` | ResearchSynthesizer delegate spawned. Reads 4 full research files. Cross-references build order constraints, pitfall-to-phase mappings, feature-architecture conflicts that short summaries omit. | | `deep` | Same as balanced but researchers produce longer output (more material for synthesizer to cross-reference). | **Why conditional:** The synthesizer's value is in cross-referencing specific data across research dimensions. When `researchDepth=fast`, researchers return compact summaries and the full research files remain available on disk; spawning a synthesizer to reformat shallow inputs wastes a context window and an agent hop. **Evidence:** - GSD source: `get-shit-done/workflows/new-project.md` lines 708-729 (always-spawn synthesizer) - 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 --- ## 6. Mapper Staleness: Standalone Workflow **GSD:** `map-codebase.md` was ALWAYS a standalone workflow, separate from `new-project.md`. It had built-in staleness detection with three user options: Refresh (delete + remap), Update (selective document refresh), Skip (use existing maps). **GSDD:** Preserved exactly. Two integration points: 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. **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. **Agent count implications:** | Scenario | Mappers spawned | | ---------------------- | ------------------------------------------------- | | Brownfield, first run | 4 (one per focus area) | | Brownfield, maps exist | 0 (skipped, user directed to standalone workflow) | | Greenfield | 0 (no codebase to map) | **Evidence:** - GSD source: `get-shit-done/workflows/map-codebase.md` lines 35-62 (staleness check with 3 options) - 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 --- ## 7. Milestone Hierarchy and Phase Continuation **GSD:** Three project-state files -- PROJECT.md (project definition), REQUIREMENTS.md (scoped features), STATE.md (current phase/status). Milestones archived in MILESTONES.md. Phase numbering continues across milestones (v1.0 phases 1-5, v1.1 starts at phase 6). **GSDD:** Merged to two files -- `.planning/SPEC.md` (combines PROJECT.md + REQUIREMENTS.md), `.planning/ROADMAP.md` (combines roadmap + inline status, replacing STATE.md). Same milestone semantics. | GSD file | GSDD equivalent | What changed | | --------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------- | | PROJECT.md | `.planning/SPEC.md` (project definition section) | Merged -- no separate project definition file | | REQUIREMENTS.md | `.planning/SPEC.md` (requirements section) | Merged -- requirements live alongside project context | | STATE.md | `.planning/ROADMAP.md` (inline status per phase) | Dropped as separate file -- checkbox status in `.planning/ROADMAP.md` is sufficient | | ROADMAP.md | `.planning/ROADMAP.md` | Simplified format -- checkboxes, no REQ-ID traceability tables | | MILESTONES.md | `.planning/milestones/` directory | Archive of completed milestone roadmaps | **Preserved semantics:** - `.planning/SPEC.md` = project lifetime (grows with validated requirements) - `.planning/ROADMAP.md` = current milestone only (archived when milestone completes) - Phase numbering continues across milestones - Researchers receive `milestone_context: [subsequent]` on new milestones -- they focus on new features, not existing system **Evidence:** - 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 --- ## 8. Advisory Git Protocol **GSD:** Embedded git naming conventions in workflows and executor agents. Phase/plan/task IDs appeared in commit messages. Executor's core algorithm ended each task with a commit step. TDD flow required commits at RED/GREEN steps. **GSDD:** Git guidance is advisory. Repository and team conventions take precedence over framework defaults. **What was removed:** - Phase/plan/task ID formatting in commit messages - Mandatory one-commit-per-task rule in executor algorithm - Mandatory commits at TDD RED/GREEN steps in executor contract - Phase-scoped branch naming in generated governance **What was kept:** - `gitProtocol` config key in `.planning/config.json` (stable, not renamed) - Advisory guidance fields: `branch`, `commit`, `pr` (user fills in or accepts defaults) - Defaults state: "Follow the existing repo or team convention" **Why advisory:** GSDD targets diverse teams and repos. Imposing one-commit-per-task or phase-scoped branch names on a repo that uses squash-and-merge or trunk-based development creates friction without value. The framework provides structure for planning -- it should not dictate git workflow. **Evidence:** - 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 --- ## 9. Adapter Generation Over Conversion **GSD:** Writes workflows for Claude Code first. `install.js` converts Claude-specific frontmatter (AskUserQuestion, Task(), SlashCommand(), `~/.claude/` paths) to OpenCode and Gemini formats. Conversion is lossy -- some Claude features have no equivalent. **GSDD:** Core workflows are plain markdown. No vendor-specific APIs. Adapter files are generated from agent-agnostic source, not converted from a Claude-first original. **GSD's vendor lock-in surface:** | API | Call sites in GSD | GSDD replacement | | ------------------- | -------------------------------- | ---------------------------------------------- | | `AskUserQuestion` | 38+ (15 workflows + 14 commands) | Plain text: "Ask the user: ..." | | `Task()` subagent | 35+ across 15 workflows | `` blocks with markdown instructions | | `SlashCommand()` | 4 call sites | Skill references or inline workflow steps | | `~/.claude/` paths | 39+ files | Install-time paths via CLI | | `gsd-tools.cjs` CLI | 28 workflow files | `bin/gsdd.mjs` (simplified) | **Adapter output per tool:** | Tool | Generated surface | Trigger | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | Any (portable) | `.agents/skills/gsdd-*/SKILL.md` | Always generated on `npx -y gsdd-cli init` | | Claude Code | `.claude/skills/gsdd-*/SKILL.md` + `.claude/commands/gsdd-plan.md` (compatibility alias for `plan`) + `.claude/agents/gsdd-plan-checker.md` | `--tools claude` | | Codex CLI | `.agents/skills/gsdd-*/SKILL.md` + optional `.codex/agents/gsdd-plan-checker.toml` | Skills are always generated; checker agent via `--tools codex` | | Codex VS Code/app | `.agents/skills/gsdd-*/SKILL.md` opened or pasted manually unless discovery exists | Fallback surface only; not covered by Codex CLI proof | | OpenCode | `.opencode/commands/gsdd-*.md` + `.opencode/agents/gsdd-plan-checker.md` | `--tools opencode` | | Cursor/Copilot | `.agents/skills/gsdd-*/SKILL.md` | Slash-invoked skills once the runtime is configured with that skills location | | Gemini CLI | `.agents/skills/gsdd-*/SKILL.md` | Skills-native path when discovered; `AGENTS.md` governance is optional | Codex CLI is skills-first because the terminal CLI supports repository skills directly. GSDD should not generate a `.codex/AGENTS.md` file just to simulate a native path that the runtime does not need. Codex VS Code and the Codex app are separate product surfaces; unless they expose compatible skill discovery, the honest fallback is opening or pasting `.agents/skills/gsdd-*/SKILL.md`. Runtime validation status belongs in the runtime support docs and evidence docs, not in broad parity claims. **Why generation over conversion:** Converting from a vendor-specific source is lossy and brittle -- every new agent needs a new converter. Generating tool-specific files from vendor-agnostic markdown is lossless and scales linearly. Pattern validated by OpenSpec (24 AI tools, 48 contributors). **Evidence:** - GSD source: `bin/install.js` (converter with per-runtime conversion logic) - GSD source: `get-shit-done/workflows/new-project.md` (851 lines, 10+ AskUserQuestion calls, 7 Task() calls) - GSDD: `bin/gsdd.mjs` (thin CLI entrypoint and adapter dispatcher after the boundary cleanup) - GSDD: `bin/adapters/*` (vendor-specific adapter generation and native prompt rendering after the boundary cleanup) - GSDD: `distilled/templates/delegates/plan-checker.md` as the single payload source for native-capable checker-agent generation - `.planning/SPEC.md` "Agent Integration Strategy" section - AGENTS.md Linux Foundation standard: [agents.md](https://agents.md) - OpenAI Codex CLI: natively reads repository Agent Skills from `.agents/skills/` (open Agent Skills surface); no `.codex/AGENTS.md` required for the CLI --- ## 10. Context Isolation: Summaries Up, Documents to Disk **GSD:** Subagents (researchers, mappers) write documents to `.planning/` directories. Orchestrator spawns agents via `Task()`, receives their return value. The pattern implicitly keeps large documents out of the orchestrator's context. **GSDD:** Makes this explicit as a design rule. **The rule:** Delegates write full documents to disk. They return bounded summaries to the orchestrator: routing summaries use 100-200 tokens, human-read summaries use 300-500 tokens, and agent-mediated discussion summaries use 500-800 tokens. The orchestrator never receives document contents in its conversation context. **Why this matters:** - LLM context windows are finite. An orchestrator that receives 4 full research files (each 200+ lines) before writing `.planning/SPEC.md` will be context-starved for the spec-writing step. - Disk is unlimited. Downstream agents (synthesizer, planner) read files directly when they need the full content. - Summaries give the orchestrator enough signal to make routing decisions (skip synthesis? flag a blocker?) without consuming the context budget. **Implementation:** - Each delegate's instructions identify the correct summary tier and keep full document contents on disk instead of echoing them into orchestrator context. - Output templates in `.planning/templates/research/` and `.planning/templates/codebase/` define the on-disk format. - The synthesizer reads all 4 research files from disk -- it is the only agent that sees full research content. **Evidence:** - GSD source: `get-shit-done/workflows/new-project.md` lines 544-706 (4 researchers write to files, return summaries) - GSDD: delegate files under `distilled/templates/delegates/` (return format instructions) - GSDD: `agents/synthesizer.md` (reads full research files from disk) - External: Anthropic Agent Teams (Feb 2026) -- "Shared State, Not Shared Context" using filesystem over context window - External: AI21 Modular Intelligence (Feb 2026) -- orchestrator-based designs prevent context drift --- ## 11. Quick-Work Lane **GSD:** `get-shit-done/workflows/quick.md` (454 lines). Two modes: default (plan + execute) and `--full` (adds plan-checking and verification). Tracks tasks in STATE.md. Uses `gsd-tools.cjs` CLI, `Task()` subagent API, `AskUserQuestion` API, and mandatory atomic commits per task. **GSDD:** Single mode, ~120 lines. Conditional verifier via `config.json`, LOG.md tracking, advisory git, direct role references. **What was kept:** - `.planning/quick/NNN-slug/` directory structure with sequential numbering - 1-3 task maximum for quick plans - Separate tracking from phase work (quick tasks don't touch ROADMAP.md) - Reuse of planner, executor, and verifier roles (no new roles or delegates) **What was stripped:** - `--full` flag duality (use the full phase cycle when you need plan-checking depth) - `STATE.md` tracking (eliminated in D7; replaced with append-only LOG.md) - `gsd-tools.cjs` CLI calls for init, commit, and slug generation - `Task()` vendor API and `AskUserQuestion` API (replaced with portable `` blocks) - Mandatory atomic commits (replaced with advisory git per D8) - Plan-checker loop for quick tasks (the full phase workflow handles this when needed) **What was added:** - Advisory git protocol (D8) — follows repo conventions, no framework-imposed commit format - Context isolation (D10) — delegates write to disk, return summaries - Conditional verifier toggle via `config.json` `workflow.verifier` setting - `.planning/quick/LOG.md` — append-only table tracking all quick tasks with status **No new delegates.** Quick workflow uses `` blocks referencing existing role contracts directly (same pattern as `audit-milestone.md`). Delegate count stays at 10. **Evidence:** - GSD source: `get-shit-done/workflows/quick.md` (454 lines, two modes, STATE.md tracking) - GSDD: `distilled/workflows/quick.md` (~120 lines, single mode, LOG.md tracking) - 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 --- ## 12. Session Persistence Without State File **GSD:** 4 control-plane workflows — `pause-work.md` (123L), `resume-project.md` (307L), `progress.md` (382L), `health.md` (157L) = 969 lines. All depend on `STATE.md` for current position, `gsd-tools.cjs` for timestamps and init, and Claude-specific APIs (`Task()`, `AskUserQuestion`). Resume includes ASCII box UI, progress bars, interrupted-agent detection, and STATE.md reconstruction. **GSDD:** 3 workflows — `pause.md` (~107L) + `resume.md` (~139L) + `progress.md` (~200L) = ~446 lines. All three now use named XML sections inside `` (aligned with core workflow conventions) and explicit scope boundaries in ``. **What was kept from GSD:** - Disk-based state detection (phase directories, checkpoint files, plan/summary presence) - Conversational pause gathering (ask the user to fill gaps artifacts can't answer) - `.continue-here.md` checkpoint file with structured sections - Contextual resume routing (5 priority-ordered branches) - Quick-resume shortcut ("continue"/"go" = skip options, execute primary action) **What was stripped at D12 design time:** - `progress.md` (382L) — initially assessed as subsumed by resume; re-added as separate workflow after audit (see amendment below) - `health.md` (157L) — GSDD's simpler `.planning/` structure does not warrant a dedicated error taxonomy and repair workflow - `STATE.md` loading and reconstruction — GSDD has no STATE.md (D7) - `gsd-tools.cjs` CLI calls for timestamps, init resume, and commit - Interrupted-agent detection (vendor-specific `Task()` API, `agent-history.json`) - ASCII box UI and progress bars - `CONTEXT.md` awareness (no discuss-phase workflow in GSDD) - Todo tracking integration - Session continuity STATE.md updates - Mandatory WIP commit format **What was added:** - Project-scoped checkpoint (single known location `.planning/.continue-here.md` vs GSD's phase-scoped glob) - Quick-task awareness (LOG.md incomplete entries detected by both pause and resume) - Workflow-type frontmatter in checkpoint (`workflow`, `phase`, `timestamp`) for resume routing - Checkpoint cleanup after successful resume routing - Explicit routing to GSDD workflow names (`gsdd-execute`, `gsdd-plan`, etc.) **Design principle:** Derive state from primary artifacts (ROADMAP.md checkboxes, phase directories, checkpoint file), not from secondary summary files that can drift. This extends D7's elimination of STATE.md. **No new roles or delegates.** Pause, resume, and progress are orchestrator-level workflows (read files, present status, route). Same pattern as `audit-milestone.md`. Delegate count stays at 10. **Progress amendment (2026-03-14):** The initial D12 assessment — that resume subsumes progress — turned out to be incomplete. An external audit (2026-03-13) explicitly listed `progress` as a required control-plane element in its top-3 highest-ROI recommendations. After delivering pause+resume, the gap became clear: the two workflows serve different contracts. | Workflow | Contract | Side effects | | ------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------ | | `resume.md` | Restore session context, load checkpoint, execute the primary next action | Checkpoint cleanup, state restoration, conversational resume | | `progress.md` | Read-only status query: where am I, what's next? | None — no files written, no state changed | A user who wants a quick status snapshot before deciding what to do next should not have to trigger a full session restore. Progress answers "where am I?" without side effects. Resume answers "restore me and get me moving." GSDD's `progress.md` (~200 lines) is a deep distillation of GSD's 382-line version: - **Kept from GSD:** project-existence check, ROADMAP.md phase-status parsing (`[ ]`/`[-]`/`[x]`), phase completion count, checkpoint-file detection, incomplete-work scanning (PLAN without SUMMARY, SUMMARY without VERIFICATION), quick-task log check, priority-ordered routing with 6 named branches (A-F) and output blocks, recent work from 2-3 most recent SUMMARY.md files, between-milestones detection (SPEC exists, ROADMAP absent), edge case handling for compound states, typed filled-in example - **Stripped:** `gsd-tools.cjs` CLI calls, `STATE.md` loading, progress-bar rendering, Key Decisions section, Blockers section, Pending Todos, Active Debug Sessions, Profile display, UAT gap routing Design principle unchanged: derive state from primary artifacts (ROADMAP.md, SPEC.md, phase directories, checkpoint file). No new roles, no new delegates. **Evidence:** - GSD source: `get-shit-done/workflows/pause-work.md` (123 lines, phase-scoped checkpoint) - GSD source: `get-shit-done/workflows/resume-project.md` (307 lines, STATE.md-dependent) - GSD source: `get-shit-done/workflows/progress.md` (382 lines, gsd-tools.cjs-dependent, STATE.md-dependent, progress bars, rich session dashboard) - GSDD: `distilled/workflows/pause.md` (project-scoped checkpoint, advisory git) - GSDD: `distilled/workflows/resume.md` (artifact-derived state, priority-ordered routing) - GSDD: `distilled/workflows/progress.md` (~200 lines, read-only, no side effects, artifact-derived state) - External audit: `.internal-research/gsd-distilled-audit-13th-march-2026.md` — Highest-ROI recommendation #3: "Add just enough: status/resume/progress/health" - D7 (milestone hierarchy): STATE.md replaced by ROADMAP.md inline status - D8 (advisory git): WIP commit is suggested, not mandated --- ## 13. Mechanical Invariant Enforcement **GSD:** No structural invariant tests. Framework correctness relies on manual review and ad-hoc checking. **GSDD:** The guard and invariant suites enforce structural properties across framework markdown files. Every assertion message includes a `FIX:` instruction so CI agents can self-remediate. **Suite inventory:** | Suite | Name | Assertions | What it guards | |-------|------|------------|----------------| | G1 | Cross-Document Schema Consistency | ~20 | Same field documented in all surfaces that reference it | | G3 | File Size Guards | ~29 | Prevent bloat regression (roles ≤500L, workflows ≤400L, delegates ≤100L) | | G4 | XML Section Well-Formedness | ~29 | Every `` has matching `` across all framework files | | G5 | Artifact Lifecycle Chain | ~11 | Each role references its input and output artifacts | | G6 | DESIGN.md Decision Registry | ~5 | ≥13 numbered decisions, each with Evidence subsection | | G7 | Delegate Thinness | ~9 | Non-empty lines ≤50 (plan-checker exempt) | **Why remediation messages matter:** OpenAI's Harness Engineering (Feb 2026) confirmed what GSDD's audit surfaced independently: for agent-driven development, **error messages ARE the enforcement mechanism**. When an agent reads `"pause.md: opened 2x but closed 1x. FIX: Add missing ."`, it can act on the fix instruction directly. Test failures without actionable messages require the agent to reason about intent from stack traces — slower and less reliable. **The G4 suite caught 3 real bugs on first run:** 3 session workflows (pause.md, progress.md, resume.md) had orphan `` closing tags with no corresponding opener. These were invisible to manual review across PRs #20-23 but immediately flagged by the well-formedness check. **Evidence:** - `tests/gsdd.invariants.test.cjs` and `tests/gsdd.guards.test.cjs` enforce structural drift checks with actionable `FIX:` messages - OpenAI Harness Engineering blog (Feb 2026): "error messages as enforcement mechanism" - External audit (2026-03-13): recommendation #4 "Mechanize the framework's invariants" - GSD source: no equivalent test infrastructure - PRs #20-23: orphan `` tags survived 4 manual review cycles before G4 caught them --- ## 14. Headless Mode **GSD:** `--auto` flag in `new-project.md` — skips interactive questioning, requires idea document, auto-approves requirements and roadmap, auto-advances to plan phase. Implemented across 5 workflow files with `AskUserQuestion` API gates. **GSDD:** `npx -y gsdd-cli init --auto --tools ` — non-interactive CLI bootstrap. Workflow-level auto mode via `autoAdvance: true` in `.planning/config.json` + `` section in `new-project.md`. **Key design choices:** 1. **Brief-file over argument-passing.** GSD passes the idea document as a workflow argument or pasted text. GSDD uses a well-known file path (`.planning/PROJECT_BRIEF.md`) because: - File reads work on every agent platform (portable) - Brief can be inspected and edited before the workflow runs - Matches GSDD's "documents to disk" principle (D10) - CI pipelines can prepare the brief as a build artifact 2. **Config-driven, not flag-driven at the workflow level.** The CLI sets `autoAdvance: true` in config. The workflow reads config, not CLI arguments. This means any agent on any platform can detect auto mode by reading config.json — no vendor-specific argument parsing required. 3. **No auto-advance to plan phase.** GSD auto-chains: new-project → discuss → plan → execute. GSDD stops after SPEC.md + ROADMAP.md are created. Reason: GSDD doesn't have a discuss-phase workflow, and chaining the full lifecycle requires auto-mode support in plan.md/execute.md/verify.md (future work). Stopping after init gives CI systems a review checkpoint. 4. **Unified with existing non-TTY fallback.** `bin/gsdd.mjs` already had a non-interactive path for piped stdin. `--auto` and the TTY fallback now share `buildDefaultConfig()`, reducing code duplication and ensuring identical default config shape. **Evidence:** - GSD source: `get-shit-done/workflows/new-project.md` lines 9-40 — direct predecessor and only comparable headless workflow found in reviewed spec-framework sources - OpenFang comparison: capability-gate emphasis supports keeping security review explicit even in automated flows, which is why auto mode inserts a deferred gate-review placeholder instead of silently omitting the section - Claude Code: `-p` flag for headless execution with `--allowedTools` for access control (docs.anthropic.com) - Codex CLI: `--quiet` and `--auto-edit` flags for non-interactive modes (developers.openai.com/codex/cli/reference) - Cline CLI 2.0: explicit headless CI/CD mode (devops.com, 2025) --- ## 15. Model Profile Propagation **GSD:** `modelProfile` stored in `.planning/config.json` with profile-to-model mapping. GSD generates `opencode.json` with agent-to-model mappings for the OpenCode runtime; does not inject `model:` into individual sub-agent frontmatter files. **GSDD:** Static injection at generation time, with explicit runtime ownership. `modelProfile` remains the portable semantic default. `agentModelProfiles` adds per-agent semantic overrides. Claude generation translates those semantic tiers into stable aliases for the native checker agent. OpenCode generation no longer infers exact `provider/model-id` strings from detected runtime config; it only injects an OpenCode `model:` when the user explicitly sets `runtimeModelOverrides.opencode.`. **Decision: static injection at generation time, not dynamic runtime config reading.** Dynamic reading (having agent files instruct the LLM to read config.json and select a model) is incompatible with how Claude Code and OpenCode frontmatter works: it is parsed at agent spawn time, not by the agent itself. Static injection remains the right mechanic, but the old OpenCode approach overreached by guessing runtime-specific ids from detected provider config. Current GSDD keeps the portable semantic layer and makes exact runtime ids explicit user-owned configuration instead of framework inference. **Scope: agent files only.** The current supported agent id is `plan-checker`. The `model:` field is injected into: - `.claude/agents/gsdd-plan-checker.md` using Claude Code aliases (`opus`, `sonnet`, `haiku`) - `.opencode/agents/gsdd-plan-checker.md` using an exact runtime-native string only when the user explicitly configured `runtimeModelOverrides.opencode.plan-checker` Current repo truth: - portable semantic settings: - `modelProfile` - optional `agentModelProfiles.` (currently consumed by `plan-checker`) - exact runtime-native settings: - optional `runtimeModelOverrides..` (currently consumed by checker agents) - Claude checker generation uses the resolved semantic tier unless an exact Claude runtime override exists - OpenCode checker generation omits `model:` by default and inherits the active OpenCode runtime model - OpenCode checker generation injects `model:` only when `runtimeModelOverrides.opencode.plan-checker` is explicitly set - `models show` returns typed effective-state data and keeps human guidance in `hints` rather than mixing prose into machine-readable model fields NOT injected into: - `.claude/commands/*.md` / `.opencode/commands/*.md` run in main orchestrator context; model is orchestrator-determined - `.agents/skills/*/SKILL.md` because the Agent Skills open standard has no `model:` field **Resolution order:** 1. `runtimeModelOverrides..` 2. `agentModelProfiles.` 3. global `modelProfile` 4. runtime default / omitted `model:` **CLI surface:** - `npx -y gsdd-cli models show` - `npx -y gsdd-cli models profile ` - `npx -y gsdd-cli models agent-profile --agent plan-checker --profile ` - `npx -y gsdd-cli models clear-agent-profile --agent plan-checker` - `npx -y gsdd-cli models set --runtime --agent plan-checker --model ` - `npx -y gsdd-cli models clear --runtime --agent plan-checker` **Trade-off: static files become stale after a profile change.** If the user changes `modelProfile` or runtime override config directly, generated checker files are not updated until `npx -y gsdd-cli update` (or global `gsdd update`) is run. This is consistent with D9 (adapter generation over conversion): adapter files are generated on demand. **Scope: checker-only is the final design boundary.** GSDD delegates are inline orchestrator instructions (`` blocks), not standalone agent files. Only the plan-checker produces standalone agent files (`.claude/agents/`, `.opencode/agents/`, `.codex/agents/`) where static `model:` injection is both possible and meaningful. GSD's per-agent model profiles relied on `Task(model=...)`; GSDD replaced `Task()` with agent-agnostic delegate blocks, making per-delegate model injection architecturally not viable without reverting to vendor-specific APIs. This closes Gap I4 by design. **Evidence:** - GSD reference: `modelProfile` in `.planning/config.json` plus per-agent model resolution, including per-agent overrides, in `get-shit-done/references/model-profiles.md` and `get-shit-done/references/model-profile-resolution.md` - OpenSpec: portable spec/workflow core is tool-agnostic and leaves runtime-specific execution concerns to integrations rather than encoding them into the portable spec surface (openspec.dev) - MetaGPT: role-specialized orchestration is a legitimate place to express role-level model intent, but that does not imply exact vendor model ids belong in a portable workflow contract (github.com/FoundationAgents/MetaGPT) - Claude Code: `model:` field with aliases `sonnet`, `opus`, `haiku` documented for sub-agents (docs.anthropic.com/en/docs/claude-code/sub-agents) - OpenCode: `model:` in agent frontmatter uses `provider/model-id`, and when omitted the agent inherits the current model (opencode.ai/docs/agents) - OpenCode config docs: OpenCode already owns project/global model configuration through runtime-native config, including `model` and `small_model`, so GSDD does not need to guess exact ids to regain DX (opencode.ai/docs/config) - OpenCode troubleshooting: `ProviderModelNotFoundError` usually means a bad `provider/model-id` reference, which argues for explicit user-owned runtime ids instead of inferred framework guesses (opencode.ai/docs/troubleshooting) - OpenAI API models: `gpt-5.4` exists and is positioned as a top-tier model for coding and agentic work, but vendor API availability alone does not prove an OpenCode-safe `provider/model-id`, which is why GSDD no longer infers OpenCode ids from vendor releases (developers.openai.com/api/docs/models/gpt-5.4) - Agent Skills open standard: no `model:` field in spec (agentskills.io/specification) - no change --- ## 16. Template Versioning via Generation Manifest **GSD:** `install.js` uses SHA-256 manifest (`installedFileHashes`) plus `gsd-local-patches/` backup directory (lines 1227-1327). On update, GSD backs up user-modified files before overwriting, enabling rollback. **GSDD:** Generation manifest in `.planning/generation-manifest.json`, opt-in `--templates` flag on `npx -y gsdd-cli update`, warn-but-overwrite semantics (no backup directory), `--dry` preview mode. **Key differences from GSD:** - **No backup directory.** Git handles recovery — users can `git checkout` to restore any overwritten template. Adding a `gsd-local-patches/` equivalent would introduce stale-state complexity that Git already solves. - **Opt-in flag.** `npx -y gsdd-cli update` without `--templates` preserves current behavior (adapter/skill refresh only). Template refresh is explicitly requested, so users are not surprised by file overwrites. - **Project-scoped manifest.** `generation-manifest.json` lives in `.planning/` alongside other project artifacts, making it portable and inspectable. The manifest records SHA-256 hashes of all installed templates and role contracts at init/update time. - **Modification detection.** When `--templates` runs, GSDD compares installed file hashes against the manifest to detect user modifications. Modified files trigger a `WARN` before overwrite. Files matching the manifest (unchanged) are silently refreshed. Files matching source (already current) are skipped. **Manifest shape:** ```json { "frameworkVersion": "v1.2", "generatedAt": "ISO-8601", "templates": { "delegates": { "file.md": "sha256..." }, "research": { ... }, "codebase": { ... }, "root": { "agents.block.md": "sha256..." } }, "roles": { "mapper.md": "sha256..." } } ``` **`FRAMEWORK_VERSION` vs `initVersion`:** `initVersion` (currently `v1.1`) tracks config schema version. `FRAMEWORK_VERSION` (currently `v1.2`) tracks template/generation versions in the manifest. They are independent concerns — config shape can change without template changes and vice versa. **Evidence:** - GSD `install.js`: SHA-256 manifest + backup directory pattern (`get-shit-done/install.js` lines 1227-1327) - OpenSpec: managed blocks with bounded upsert for vendor-specific surfaces (openspec.dev) - Angular/Turborepo/Next.js: ordered migrations with dry-run preview (angular.dev/cli/update, turbo.build/repo/docs/guides/migrate) - Langfuse: generation/prompt versioning with hash-based change detection (langfuse.com/docs/prompts/get-started) --- ## 17. CLI Composition Root Boundary **GSD:** `install.js` and adjacent install/generation logic mix orchestration, runtime-specific conversion, template syncing, prompts, and filesystem writes in one large entry surface. **GSDD before D17 Session 2:** `bin/gsdd.mjs` had already pushed vendor rendering into `bin/adapters/`, but it still mixed CLI composition with bootstrap command bodies, template refresh logic, prompt flows, and update dispatch in a single file. **GSDD after D17 Session 2:** `bin/gsdd.mjs` is a thin composition root. It owns: - top-level constants (`WORKFLOWS`, `FRAMEWORK_VERSION`, path roots) - adapter registry construction - command registry wiring - `runCli` - stable exported command handles for tests 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, 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 copy logic - enforce the boundary with code-structure guard tests, not by re-auditing the file manually each session **Why this split:** - it reduces the regression surface when bootstrap or template-refresh logic changes - it keeps command logic close to the helpers it depends on - it preserves a stable import surface for tests while making the main CLI file small enough to inspect quickly - it aligns with the existing D9/D15/D16 direction: adapters own runtime-specific behavior; `bin/lib/` owns framework logic; `bin/gsdd.mjs` wires them together **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`, `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/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 --- ## 18. Codex CLI Native Adapter **GSD:** No dedicated Codex CLI adapter. GSD was Claude-first. **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) 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/`. **Why now:** Phase A research confirmed all three prerequisites for native-capable promotion: 1. A native agent surface exists (`.codex/agents/*.toml` with TOML format) 2. Fresh-context subagent invocation is confirmed (`spawn_agent` tool, new `ThreadId` per subagent) 3. Per-agent model control exists (`model` field in agent TOML) **Key design choices:** 1. **TOML agent format** — Codex uses `.codex/agents/.toml` (not markdown). The plan-checker delegate content goes inside `developer_instructions = """..."""`. A TOML escape guard replaces `"""` with `"" "` in delegate content to prevent string termination. Model IDs are validated at the CLI setter (`MODEL_ID_PATTERN`) and escaped in the TOML renderer as defense-in-depth. 2. **Portable skill as entry surface** — Unlike Claude (which has a vendor-specific `.claude/skills/gsdd-plan/SKILL.md`) and OpenCode (which has `.opencode/commands/gsdd-plan.md`), Codex reads skills from `.agents/skills/` — the shared portable path. The portable skill is enhanced with vendor-neutral checker invocation instructions (JSON schema, max-3 cycle loop, escalation, orchestration summary), making it self-sufficient as the Codex entry surface. When Codex auto-selects the `gsdd-plan` skill, the instructions tell it to invoke the `gsdd-plan-checker` agent if available. No separate planner TOML is needed — the portable skill handles orchestration directly. 3. **Inherit-by-default model** — Following OpenCode's pattern, no `model` field is set by default (inherits from parent session). An explicit `model = ""` is only written when the user sets `runtimeModelOverrides.codex.plan-checker`. 4. **Always-high reasoning effort** — `model_reasoning_effort = "high"` is always set for the plan-checker (analysis agent should think carefully). 5. **Read-only sandbox** — `sandbox_mode = "read-only"` prevents the checker from editing plans, functionally equivalent to OpenCode's `write: false, edit: false, bash: false`. **Known gaps:** - No `hidden: true` equivalent — unlike OpenCode, the checker agent is visible to users (ergonomic gap, not functional; no Codex equivalent exists) - 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 - Codex VS Code/app are not implied by Codex CLI validation — when those products do not expose compatible repository skill discovery, the supported posture is manual open/paste of `.agents/skills/gsdd-*/SKILL.md`, not a native-capable claim **Live validation (2026-03-17):** - Local runtime: `codex-cli 0.113.0` with `features.multi_agent = true` - Happy path fixture: `%TEMP%\\gsdd-codex-pr29-happy-20260317-214241` wrote `.planning/phases/01-foundation/01-PLAN.md` through the portable `gsdd-plan` entry surface while the native checker double returned `CHECKER_HAPPY` - Forced revision fixture: `%TEMP%\\gsdd-codex-pr29-revision-20260317-214942` required the checker-driven sentinel `SENTINEL-REVISION-OK` in the plan `Notes` section; the plan was revised and the second checker pass passed - Max-3 escalation fixture: `%TEMP%\\gsdd-codex-pr29-max3-noresearch-20260317-220608` set `workflow.research = false` to isolate the checker seam; Codex spawned 3 fresh-context checker agents, each returned `CHECKER_STILL_BLOCKED`, and the final result was `escalated` **Evidence:** - OpenAI Codex CLI docs: [developers.openai.com/codex/subagents](https://developers.openai.com/codex/subagents) - Codex CLI config reference: [developers.openai.com/codex/config-reference](https://developers.openai.com/codex/config-reference) - Codex CLI v0.115.0 release notes: [github.com/openai/codex/releases/tag/rust-v0.115.0](https://github.com/openai/codex/releases/tag/rust-v0.115.0) - Agent Skills standard: [developers.openai.com/codex/skills](https://developers.openai.com/codex/skills) - GitHub issues: [#14719](https://github.com/openai/codex/issues/14719), [#14841](https://github.com/openai/codex/issues/14841) - GSDD adapter patterns: `bin/adapters/claude.mjs`, `bin/adapters/opencode.mjs` - GSDD implementation: `bin/adapters/codex.mjs`, `bin/adapters/index.mjs`, `bin/lib/init.mjs`, `bin/lib/models.mjs` - GSDD tests: `tests/gsdd.init.test.cjs`, `tests/gsdd.models.test.cjs`, `tests/gsdd.plan.adapters.test.cjs` --- ## 19. Scenario-Based Eval Coverage **GSD:** No structural eval tests. Correctness relied on manual review and live agent runs. **GSDD:** Deterministic scenario tests (`tests/gsdd.scenarios.test.cjs`) verify artifact-chain contracts across 3 golden paths and 2 native-capable runtime chains. No LLM calls required. **What scenarios test (S1–S5):** | Suite | Coverage | |-------|----------| | S1 — Greenfield Golden Path | init → new-project → plan → execute → verify → audit-milestone artifact chain | | S2 — Brownfield Path | map-codebase delegates, codebase map references, mapper role installation | | S3 — Quick-Task Path | Isolation from ROADMAP/research, role references, researcher exclusion | | S4 — Native Runtime Chain | Claude skill/command/checker + Codex TOML checker completeness, 7 dimensions | | S5 — Config-to-Content Propagation | Default config values reflected in generated artifacts | **What scenarios do NOT test:** Runtime LLM behavior, aggregate success rates, LLM-judge quality. Those belong in a future eval layer above this one. **Design rationale:** The testing pyramid for AI agents (Block, Jan 2026) puts deterministic no-LLM tests at the base. OpenAI's eval guidance recommends skill-level testing with deterministic graders. Anthropic's guidance says "grade outcomes, not paths" — these tests verify what was produced, not how. This layer complements the G1–G13 invariant suites (D13) which test structural properties of source files; scenario tests verify that the *generated* artifact chain between workflows is complete. **Evidence:** - OpenAI: "Testing Agent Skills Systematically with Evals" (developers.openai.com/blog/eval-skills) - Anthropic: "Demystifying Evals for AI Agents" (anthropic.com/engineering/demystifying-evals-for-ai-agents) - Block: "Testing Pyramid for AI Agents" (engineering.block.xyz/blog/testing-pyramid-for-ai-agents) - GSDD implementation: `tests/gsdd.scenarios.test.cjs` (S1–S5, ~37 assertions) - Invariant complement: D13, `tests/gsdd.invariants.test.cjs`, `tests/gsdd.guards.test.cjs` --- ## 20. Workspace Health Diagnostics **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:** `npx -y gsdd-cli health` CLI command (`bin/lib/health.mjs` + `bin/lib/health-truth.mjs`; global `gsdd health` is equivalent). Factory function `createCmdHealth(ctx)` returning an async command. No `--repair` flag — fixes are documented as actionable instructions, not automated mutations. GSDD already has `npx -y gsdd-cli init` and `npx -y gsdd-cli update --templates` as the repair paths; a separate repair mode would duplicate those commands. **Check categories:** | ID | Severity | What it checks | |----|----------|----------------| | E1 | ERROR | `.planning/config.json` missing or unparseable | | E2 | ERROR | config.json missing required fields (`researchDepth`, `modelProfile`, `initVersion`) | | 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`, `ui-proof.md`) | | E9 | ERROR | `.planning/templates/brownfield-change/` missing or missing critical files (`CHANGE.md`, `HANDOFF.md`, `VERIFICATION.md`) | | E10 | RETIRED | Retired UI proof bundle metadata validator; current browser proof uses plan declarations and markdown observation records | | W1 | WARN | `generation-manifest.json` missing | | W2 | WARN | Manifest-tracked installed templates/helpers modified locally (hash mismatch vs manifest) | | W3 | WARN | Manifest-tracked installed templates/helpers missing from disk but listed in manifest | | 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 generated workflow 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 lifecycle status drift, including requirement checkbox and overview/detail phase status mismatches | | W11 | WARN | Renderer-backed generated runtime/helper 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 runtime/governance surfaces are installed | **Verdict logic:** - Any ERROR → `broken` (exit code 1) - Any WARN, no ERROR → `degraded` (exit code 0) - No ERROR, no WARN → `healthy` (exit code 0) **Output modes:** - Default: human-readable with severity markers and verdict line - `--json`: machine-readable `{ status, errors[], warnings[], info[] }` **Key design choices:** 1. **No `--repair` flag.** GSD's health workflow supported `--repair` with three actions (createConfig, resetConfig, regenerateState). GSDD does not need this because `npx -y gsdd-cli init` and `npx -y gsdd-cli update --templates` already serve as repair paths. Documenting the fix command in each diagnostic is sufficient — agents can read and execute the instruction directly. 2. **`brew doctor` pattern.** Diagnose, report, suggest — never auto-fix. This matches the D13 principle: error messages ARE the enforcement mechanism. When an agent reads `"E3: .planning/templates/ missing. Fix: Run npx -y gsdd-cli update --templates"`, it can act on the instruction. 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. **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-W12) 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 only for the actual source repo.** Inside the GSDD framework repo itself, `distilled/templates/` is the source of truth and `.planning/templates/` can be intentionally absent. `npx -y gsdd-cli health` therefore skips installed-project template/manifest checks (E3-E9, W1-W3) only when source-repo identity signals also match (`package.json` name plus CLI source), avoiding false suppression in copied or unusual initialized repos that happen to contain `distilled/templates` and `distilled/workflows`. 7. **Generated adapters and governance are reported separately.** W6 checks generated workflow entry surfaces (`.agents/skills`, Claude skills/commands, OpenCode commands) and does not treat root `AGENTS.md`, native checker agents, or Codex native checker TOML as workflow adapters. Codex CLI uses `.agents/skills` as its workflow entry path. I3 may still report native agents and root `AGENTS.md` as installed runtime/governance surfaces so users understand what exists without confusing those files with executable workflow discovery. **What was removed vs GSD:** - `--repair` flag and associated repair actions - Error codes E001-E005/W001-W007 (replaced with simpler E1-E9/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) **Evidence:** - GSD source: `get-shit-done/workflows/health.md` (157 lines, predecessor) - `brew doctor` pattern: diagnose, report, suggest — never auto-fix - OpenAI Harness Engineering (Feb 2026): error messages as enforcement mechanism (same principle as D13) - 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/lib/health-truth.mjs`, `bin/gsdd.mjs`, `tests/gsdd.health.test.cjs`, `tests/gsdd.guards.test.cjs` (G14) --- ## 21. OWASP Authorization Matrix **GSD:** No formal authorization matrix. Auth verification during milestone audits relies on the integration checker's narrative inference — it identifies sensitive surfaces and checks for auth protection, but has no systematic cell-by-cell verification against declared permissions. **GSDD:** Adds an optional OWASP-style authorization matrix as a project artifact (`.planning/AUTH_MATRIX.md`). When present, the integration checker performs cell-by-cell verification in addition to its existing narrative auth check. **The matrix uses the OWASP pivot format:** | Resource | Action | Role A | Role B | Role C | |----------|--------|--------|--------|--------| | /resource| verb | ALLOW | DENY | OWN | Permission values: ALLOW (role can access), DENY (explicit rejection required), OWN (ownership-scoped access), N/A (not applicable). **Design choices:** 1. **Project artifact, not framework source.** The matrix lives in `.planning/AUTH_MATRIX.md` — a project-specific file created during `new-project` when the project has multiple roles. The template at `distilled/templates/auth-matrix.md` teaches the format but is not consumed at runtime. This follows the same pattern as `SPEC.md` and `ROADMAP.md`: the template instructs, the project artifact governs. 2. **Backwards compatible.** The integration checker's new Step 4a is fully gated by an existence check: `If .planning/AUTH_MATRIX.md does not exist, skip this sub-step.` The narrative auth check (Step 4) always runs regardless. Projects without a matrix see zero behavioral change. 3. **OWASP pivot format.** The resource x role x permission table is the standard format from the OWASP Authorization Testing Automation Cheat Sheet. Using a recognized standard means the matrix is portable — it can be consumed by other tools, reviewed by security auditors, or extended with automated test generation outside GSDD. 4. **No automated test generation.** The matrix is consumed for verification, not for generating test code. Test generation would require framework-specific knowledge (HTTP client, test runner, auth setup) that varies per project. The integration checker reports VERIFIED / MISMATCH / UNTESTED per cell — turning mismatches into tests is the developer's job. 5. **No auto-creation.** The `new-project` workflow mentions the matrix as optional item 8 in ``. It is not automatically generated because auth requirements vary widely and a wrong matrix is worse than no matrix. 6. **Template portability.** The template is auto-distributed by `installProjectTemplates()` (same `cpSync` path as all templates) and auto-tracked by `buildManifest()`. No code changes to `templates.mjs` or `manifest.mjs` were needed. **What GSDD does NOT do:** - Does not generate test code from the matrix - Does not auto-create the matrix during project init - Does not require the matrix for milestone audits to pass - Does not replace the narrative auth check (Step 4 always runs) **Evidence:** - OWASP Authorization Testing Automation Cheat Sheet: pivot-format matrix standard - OWASP Top 10 for Agentic Applications 2026: A1 Agent Overreach, A4 Insufficient Authorization - External audit (2026-03-13): "Upgrade milestone auth from intent to matrix" - External audit (2026-03-17): confirmed auth verification gap independently - GSD source: `agents/integration-checker.md` (narrative auth check, no matrix support) - GSDD implementation: `distilled/templates/auth-matrix.md`, `agents/integration-checker.md` (Step 4a), `distilled/workflows/audit-milestone.md`, `distilled/workflows/new-project.md`, `tests/gsdd.guards.test.cjs` (G15) --- ## 22. Delegate Layer Architecture **GSD:** Orchestrator subagent prompts were embedded inline in workflow files or referenced indirectly through agent role contracts. No explicit thin-wrapper layer. Scope and context were implicit in the orchestrator's prompt shaping. **GSDD:** Extracted 11 delegates as explicit thin-wrapper files in `distilled/templates/delegates/`. A delegate is a sub-agent instruction wrapper scoped to a specific orchestrator task, carrying a bounded input/output contract. Eleven delegates cover 4 canonical roles: mapper × 4 focus-scoped variants, researcher × 4 dimension-scoped variants, synthesizer × 1 (via `researcher-synthesizer.md`), one fresh-context adversarial reviewer (`plan-checker.md`, new in D9, no GSD equivalent), and one interactive approach explorer (`approach-explorer.md`, recovers GSD discuss-phase leverage with research enhancement). Executor, verifier, integration-checker, planner, and roadmapper are invoked directly from orchestrator workflows without thin-wrapper delegates. **Why "delegates":** In multi-agent orchestration literature (Anthropic multi-agent guidance, OpenAI harness engineering, OpenDev terminal-agents paper arXiv 2603.05344), a delegate is a sub-agent invoked by an orchestrator with: 1. A single, bounded responsibility (not a general-purpose role) 2. A typed input/output contract 3. Explicit scope boundaries (what the sub-agent owns vs. doesn't own) 4. A specific invocation pattern (fresh context, checkpoint, isolation) GSDD's delegates are exactly this: thin instruction wrappers that route to a canonical role contract, carry a specific scope parameter, enforce context isolation, and return typed structured output. The name is intentional and accurate to multi-agent literature. **Why extract delegates:** Orchestrator workflows need to invoke sub-agents with consistent, predictable behavior. The orchestrator's prompt is large and carries session context; the sub-agent should be small, focused, and isolated. GSD embedded sub-agent instructions inline, making workflows hard to read and sub-agent contracts hard to reuse. GSDD extracts delegates into portable files at `distilled/templates/delegates/`, installed to `.planning/templates/delegates/` per project, and referenced by `` blocks in orchestrator workflows: ``` Instruction: Read .planning/templates/delegates/researcher-stack.md Scope: domain tech stack research Input: Project domain, tech constraints, research mode Output: STACK.md with structured findings and confidence levels ``` Benefits: 1. **Reusable:** The same delegate can be invoked from multiple orchestrator workflows (new-project, plan, milestone audit) 2. **Testable:** Delegate contracts are explicit and can be verified independently 3. **Portable:** Delegates are plain markdown; any agent can read them 4. **Versioned:** The generation manifest tracks delegate content; `npx -y gsdd-cli update --templates` refreshes them **Tradeoffs and close condition:** The delegate layer is a semantic extraction, not a functional one. It does not change what happens at runtime; it only changes how we describe what happens. The tradeoff is: - **Benefit:** Orchestrators are smaller, clearer, and sub-agent contracts are reusable - **Cost:** One more layer of indirection; agents must read both the workflow and the delegate to understand the full contract This is acceptable because: 1. Agents are fast at reading multiple files 2. The clarity gain outweighs the reading cost 3. Delegate independence enables better testing and quality gates **Delegate catalog:** | Delegate | Purpose | Wrapped Role | |----------|---------|--------------| | `mapper-tech.md` | Map codebase tech stack | mapper (focus: tech) | | `mapper-arch.md` | Map codebase architecture | mapper (focus: arch) | | `mapper-quality.md` | Map code quality conventions | mapper (focus: quality) | | `mapper-concerns.md` | Identify code concerns and debt | mapper (focus: concerns) | | `researcher-stack.md` | Research domain tech stack | researcher (dimension: stack) | | `researcher-features.md` | Research domain feature landscape | researcher (dimension: features) | | `researcher-architecture.md` | Research domain architecture patterns | researcher (dimension: architecture) | | `researcher-pitfalls.md` | Research domain pitfalls and risks | researcher (dimension: pitfalls) | | `researcher-synthesizer.md` | Synthesize research into roadmap implications | synthesizer | | `plan-checker.md` | Fresh-context adversarial plan review | planner (adversarial, new in D9) | | `approach-explorer.md` | Interactive approach exploration and user alignment | approach-explorer (interactive, recovers GSD discuss-phase) | **Evidence:** - Anthropic multi-agent guidance: orchestration patterns with isolated sub-agents - OpenAI Harness Engineering (2026): delegate pattern for consistent, reusable sub-agent behavior - OpenDev "Terminal Agents" (arXiv 2603.05344): multi-agent coordination with explicit role contracts - GSDD implementation: `distilled/templates/delegates/`, `distilled/workflows/*.md` (with `` blocks), `bin/lib/rendering.mjs` (delegate text injection) - Tests: `tests/gsdd.scenarios.test.cjs` (S1–S5 verify delegate invocation chains) --- ## 23. Mapper Output Quantification **GSD baseline:** Mapper agents produce qualitative descriptions ("uses constructor injection") without adoption rates, trend signals, or exemplar file identification. No systematic mechanism for ranking concerns by downstream impact. **GSDD decision:** Five quantification primitives added across codebase map templates and delegates: | Primitive | Where | Format | |-----------|-------|--------| | Convention adoption rates | CONVENTIONS.md + mapper-quality delegate | `~N% (stable\|rising\|declining)` via grep-counting | | Golden files (conventions) | CONVENTIONS.md + mapper-quality delegate | 2–3 files with highest convention density in production code | | Golden files per layer (arch) | ARCHITECTURE.md + mapper-arch delegate | Most-imported file per layer (inbound import frequency) | | Must-know packages | STACK.md + mapper-tech delegate | 3–5 packages with risk index low/medium/high + common mistake | | Downstream impact ranking | CONCERNS.md + mapper-concerns delegate | Top 3 concerns ranked by ARCHITECTURE.md change-routing rows blocked | **Why algorithmic, not subjective:** Each primitive has a deterministic algorithm so different agents produce comparable output: - Adoption rate: grep-count ÷ total instances, expressed as ~N% - Golden file (conventions): highest density of documented conventions per production file - Golden file (arch): highest inbound import count per layer - Must-know packages: misuse causes hardest-to-debug problems (data corruption or silent failure = risk: high) - Impact ranking: number of ARCHITECTURE.md change-routing rows blocked per concern **Why `~N%` format:** The tilde prefix signals estimation, not measurement. This prevents false precision while still providing a useful signal. "~84% (declining)" conveys the same planning information as an exact count while being honest about the estimation method. **Why separate sections, not inline annotations:** Inline annotations ("constructor injection — 84%") would require reformatting existing rules. Dedicated sections (Convention Adoption Rates, Golden Files) keep quantification additive — the existing prescriptive rules remain unchanged and the new sections are skippable by agents that don't need them. **Problem this solves:** Internal research (ideas.md, Feb 2026) directly compared GSDD's mapper against codebase-context MCP on the same codebase and found: GSDD returned "uses constructor injection" while CC returned "84% (declining)". The qualitative output gives downstream planners and executors weaker signal for prioritization decisions on brownfield projects. **Evidence:** 1. `ideas.md` (internal, Feb 2026): direct per-tool comparison — "Quantification matters — '84% declining' > 'uses constructor injection'" 2. ArXiv 2602.20478 (Codified Context): structured quantifiable facts enable agents to load context JIT without reading full files 3. GetDX measurement framework (2026): adoption % is the primary signal for convention strength in engineering teams 4. Anthropic 2026 Agentic Coding Trends: context quality is the primary competitive advantage; bottleneck is "does agent have context it needs?" 5. Codebase-Context MCP (PatrickSys): already returns quantified patterns — GSDD without this produces weaker artifacts on the same codebase **Trade-offs:** - Benefit: downstream planners and executors get quantified signals for prioritization; "~84% declining" tells the planner to budget for migration, "~100% stable" tells it not to - Cost: mapper must grep-count each major convention, adding analysis time; the tilde prefix is honest about estimation but agents may treat it as less authoritative than exact counts - Scope: quantification is additive — existing qualitative rules remain; agents can skip the new sections if not needed **GSDD implementation:** `distilled/templates/codebase/conventions.md`, `distilled/templates/codebase/architecture.md`, `distilled/templates/codebase/stack.md`, `distilled/templates/codebase/concerns.md`, `distilled/templates/delegates/mapper-quality.md`, `distilled/templates/delegates/mapper-arch.md`, `distilled/templates/delegates/mapper-tech.md`, `distilled/templates/delegates/mapper-concerns.md`, `agents/mapper.md` --- ## 24. Consumer Governance Completeness **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-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 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:** 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:** - 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 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:** 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:** - 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 2. **OpenAI Codex skills documentation**: Shows clear per-platform invocation patterns with explicit examples, not generic "use the skill" instructions 3. **GitHub spec-driven development toolkit**: Provides explicit getting-started flows that match the user's specific tool, not one-size-fits-all docs 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` (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` --- ## 26. Session Continuity Contract Hardening **GSD:** No explicit session management contract. State lived in a separate STATE.md file. No pause/resume/progress workflows. Session continuity depended on the user remembering where they left off. **GSDD:** Three specialized session workflows with artifact-based state derivation: - **pause.md:** Writes `.continue-here.md` checkpoint with frontmatter (`workflow`, `phase`, `timestamp`) and 6 XML sections (`current_state`, `completed_work`, `remaining_work`, `decisions`, `blockers`, `next_action`). Detects 3 work types (phase/quick/generic), gathers missing context conversationally, and advises on git commit. - **resume.md:** Reads artifacts (ROADMAP.md, SPEC.md, .continue-here.md, phase directories, quick LOG.md), routes to the correct next action with 5-branch priority logic (checkpoint-based routing, incomplete execution, needs planning, needs verification, all phases complete), and cleans up the checkpoint before dispatching. - **progress.md:** Read-only reporter with 4-way existence detection, 6 named routing branches (A through F), edge case handling for compound states, and recent-work scanning from SUMMARY.md files. Creates, modifies, or deletes no files. D12 established the session persistence design. D26 mechanically enforces the routing contracts that D12 introduced with a G20 guard suite. **Evidence:** 1. Anthropic "Effective harnesses for long-running agents" (2026): artifact-based session handoff (`claude-progress.txt`) is the winning pattern; context compaction alone is "not sufficient" -- explicit progress files bridge sessions 2. GitHub "How to build reliable AI workflows with agentic primitives" (2026): session splitting as a first-class agentic primitive; distinct sessions for different phases improve accuracy 3. OpenAI harness engineering (2026): incremental progress tracking (JSON feature lists, progress files) is the key mechanism for multi-session work; "finding a way for agents to quickly understand the state of work when starting with a fresh context window" 4. OpenDev terminal agents (arXiv 2603.05344): scaffolding-harness separation; runtime state must be derivable from artifacts, not from context window memory 5. GSDD internal: I5 invariant suite covers basic structure (16 assertions) but not routing completeness; S1-S5 scenarios don't exercise session workflows in isolation; 18+ routing branches untested before D26 **Tradeoff:** More assertions to maintain (~35 new), but prevents routing drift that would break the consumer's primary multi-session interaction pattern. GSDD's 3-workflow session design already aligns with Anthropic's recommendation -- D26 mechanically locks it down. **GSDD implementation:** `distilled/workflows/pause.md`, `distilled/workflows/resume.md`, `distilled/workflows/progress.md`, `tests/gsdd.guards.test.cjs` (G20) --- ## 27. Consumer-Ready Surface Completion **Problem:** Three independent external audits (March 13, 17, 18 2026) converged: GSDD's architecture is complete but consumer-facing documentation has gaps blocking self-service adoption. Specifically: auto-mode not in README, no troubleshooting section, no git tracking guidance, model strategy unexplained, health not positioned as diagnostic entry point, team onboarding absent, and docs/USER-GUIDE.md not linked from README. **Decision:** Close consumer journey gaps with compact README sections cross-referencing the existing User Guide. Do not bloat the README. **Changes:** 6 new README subsections (Headless Mode, Team Use, User Guide link, Model Strategy, What to Track, Troubleshooting). G21 guard suite enforces section presence. **Evidence:** 1. External audit (2026-03-13): "architecture is solid, presentation lags implementation" 2. External audit (2026-03-17): "close scope around the kernel" — consumer surface identified as #1 bottleneck 3. External audit (2026-03-18): "docs should close the consumer journey" 4. OpenAI harness engineering (2026): documentation is part of the harness environment 5. Anthropic context engineering (2026): progressive disclosure for onboarding 6. Agent Skills standard (agentskills.io, 30+ tools): skills need clear discovery documentation **GSDD implementation:** `README.md`, `docs/USER-GUIDE.md` (already exists, now cross-referenced), `tests/gsdd.guards.test.cjs` (G21) --- ## 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. **Decision:** Add `` sections after `` 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:** | Fix | Scope | Files | |-----|-------|-------| | `` sections | 9 workflows (all except `progress.md` which already has routing) | `new-project.md`, `plan.md`, `execute.md`, `verify.md`, `audit-milestone.md`, `quick.md`, `pause.md`, `resume.md`, `map-codebase.md` | | Positional STOP gates | 2 transition points in `new-project.md` (questioning→research, research→spec) | `new-project.md` | | SUMMARY.md persistence gate | MANDATORY write enforcement in `` | `execute.md` | | VERIFICATION.md persistence | Dedicated `` section with STOP-on-failure | `verify.md` | | G22 guard suite | ~30 assertions preventing regression | `tests/gsdd.guards.test.cjs` | **Completion section pattern (consistent across all 9 workflows):** ```markdown Report to the user what was accomplished, then present the next step: --- **Completed:** [what finished] **Next step:** `/gsdd-[command]` — [description] Also available: - `/gsdd-[alt]` — [description] Consider clearing context before starting the next workflow for best results. --- ``` **Routing map (acyclic, complete):** - `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` **GSD comparison:** | Aspect | GSD | GSDD | |--------|-----|------| | End-of-workflow routing | `## ▶ Next Up` with emoji, separators, backticked commands | `` section with bold routing, consistent format | | Context clearing | Explicit: `/clear first → fresh context window` | Vendor-agnostic: "Consider clearing context before starting the next workflow" | | Persistence enforcement | No explicit gates | MANDATORY gates on SUMMARY.md and VERIFICATION.md | | Positional discipline | Rules at top of file only | STOP gates at exact deviation transition points | GSDD's `` pattern is vendor-agnostic (GSD's `/clear` is Claude-specific) and adds persistence enforcement that GSD lacked. **Evidence:** 1. Consumer audit (2026-03-21): "Agent never proactively suggested the next GSDD command... the user becomes the workflow engine" 2. GSD source: `get-shit-done/workflows/progress.md` — every routing branch ends with formatted "Next Up" block showing exact command and alternatives 3. Anthropic "Building effective agents" (2025): workflows should make handoff points explicit with clear next actions 4. Consumer audit issue #6: "verification not persisted to disk" — VERIFICATION.md existed only in chat context, lost on context compression 5. Positional discipline research (Anthropic long-context, 2024): instructions at decision points are followed more reliably than instructions at document start **Tradeoff:** ~30 new guard assertions to maintain, but prevents the highest-impact consumer UX failure (routing dead ends at every workflow boundary). Persistence gates add 2-3 lines per workflow but prevent artifact loss that breaks downstream audit. **GSDD implementation:** `distilled/workflows/*.md` (9 files), `tests/gsdd.guards.test.cjs` (G22) --- ## 29. Approach Exploration **GSD baseline:** Three separate workflows handle pre-planning user alignment: | GSD workflow | Purpose | Output | |---|---|---| | `discuss-phase.md` (541 lines) | Gray area identification, 4-question batched loops per area, deferred ideas capture | `CONTEXT.md` | | `list-phase-assumptions.md` (179 lines) | 5-dimension assumption surfacing (technical approach, implementation order, scope boundaries, risks, dependencies) | Conversational only (no file output) | | `discovery-phase.md` | 3-level research (Quick/Standard/Deep) with domain exploration | `DISCOVERY.md` | Combined, these three workflows provided genuine leverage: the planner could not silently converge on a single approach without user input. GSD's initial GSDD distillation dropped all three, removing this alignment step entirely. The planner was left to infer approaches without user validation. **Problem:** Without approach exploration, the planner explores no alternatives, surfaces no assumptions, and captures no user decisions. The user's first chance to disagree with approach choices is after implementation — too late for efficient correction. **GSDD decision:** Recover the discuss-phase leverage as a single role (`agents/approach-explorer.md`) embedded in the plan workflow, with a hybrid interaction architecture: 1. **Primary path (inline + research subagents):** Conversation runs in the plan workflow's main context (required for user interactivity). For each technical gray area, a read-only research subagent spawns, reads codebase/docs, and returns a compressed 500-800 token structured summary. Only summaries enter the conversation context, not raw file reads. 2. **Native agent optimization:** Runtimes with interactive subagent support (Claude Code with `AskUserQuestion`, Codex interactive agents, OpenCode `mode: agent`) can run the full exploration as a native agent. Falls back to the inline primary path if unavailable. Both paths produce identical output: `{padded_phase}-APPROACH.md` in the phase directory. **Key enhancements over GSD:** | Enhancement | GSD pattern | GSDD pattern | Why | |---|---|---|---| | Gray area classification | All areas treated identically | Taste / technical / hybrid classification | Taste decisions need no research; technical ones do. Asking "what color?" the same way as "JWT vs sessions?" wastes context and user time | | Questioning style | Rigid 4-question batched loop | Adaptive convergence (2-6 questions depending on complexity) | Fixed batch sizes don't match decision complexity. Some areas resolve in 2 questions, others need 6 | | Pre-question research | No research before asking | Research subagent per technical area returns structured summary before asking | Users make better decisions when presented with researched options and trade-offs | | Quality gate | None | Self-check before writing APPROACH.md (concrete decisions, no vague language, source backing, scope compliance) | Prevents weak outputs that force re-asking during planning | | Alignment proof gate | None | `APPROACH.md` records `alignment_status: user_confirmed` or explicit `approved_skip`, and planning validates this before goal-backward planning when `workflow.discuss: true` | Prevents native or existing-artifact paths from turning mandatory discussion into artifact theater | | Intermediate persistence | No persistence until final output | Confirmed decisions written to disk incrementally | Protects against context limits in long conversations | | Context loading | "Read everything" | JIT extraction guidance (e.g., "From SPEC.md read ONLY locked decisions") | Prevents context pollution with irrelevant content | | Plan-checker integration | None | New `approach_alignment` dimension in plan-checker | Verifies plans honor approach decisions, not just requirements | | Delegation option | Not available | "Agent's Discretion" — user can explicitly delegate choices to the agent | Reduces user fatigue on areas where they have no strong preference | **Role contract design:** Ground-up rewrite applying prompt engineering best practices: - XML semantic structure (``, ``, ``, ``, ``) matching the planner role pattern - 3 few-shot conversation examples (taste decision, technical decision with research, hybrid with delegation) - Vendor-neutral throughout — no tool-specific references in the role contract - Anti-patterns placed early for high attention weight **Architecture rationale — why hybrid:** The approach explorer needs two capabilities with opposite context requirements: - **Conversation** needs the main context (for user interaction) - **Research** generates thousands of tokens of raw content the conversation doesn't need Isolating research in subagents and returning compressed summaries follows the Compress and Isolate patterns from context engineering literature. The research subagent prompt template lives in the role contract (`` section of `agents/approach-explorer.md`) — co-located with the algorithm it serves, and referenced by the portable workflow rather than inlined. The main context budget stays manageable: about 1000 tokens orchestration, up to 3200 tokens research summaries (4 areas x 800), about 4000 tokens conversation, and about 500 tokens APPROACH.md. The 500-800 token agent-mediated discussion tier gives research subagents room for the structured format (Name/Pro/Con/Source) plus recommendation reasoning, source verification, and enough project-specific context that the main agent can handle follow-up questions without re-querying the subagent. **Evidence:** 1. Anthropic "Building effective agents" (2025): sub-agents perform deep technical work, returning condensed summaries to the orchestrator — "find the smallest set of high-signal tokens" 2. Anthropic prompting best practices (2025): XML tags for semantic structure, role preamble, few-shot examples, adaptive thinking 3. LangChain "Context Engineering for Agents" (2025): Write/Select/Compress/Isolate patterns — "isolate: split context across separate processes", "compress: summarize at agent-agent boundaries" 4. Agent Skills specification (agentskills.io): progressive disclosure, SKILL.md format with metadata-first structure 5. OpenAI meta-prompting (2025): LLM-as-judge evaluation, specification-based output quality verification 6. GSD source: `get-shit-done/workflows/discuss-phase.md` (gray area identification, AskUserQuestion interaction, deferred ideas) 7. GSD source: `get-shit-done/workflows/list-phase-assumptions.md` (5-dimension assumption surfacing with confidence levels) 8. GSD source: `get-shit-done/workflows/discovery-phase.md` (3-level research workflow) **Trade-offs:** - Benefit: planner receives locked user decisions instead of guessing approaches; plan-checker can verify approach alignment; existing APPROACH artifacts are not trusted unless their alignment proof is valid; context stays lean via research isolation - Cost: adds one interactive step before planning (~5-15 minutes of user time per phase); hybrid architecture is more complex than a single monolithic workflow - Mitigation: `workflow.discuss: true|false` toggle in `.planning/config.json` allows skipping with explicit `reduced_alignment` reporting; taste areas skip research entirely. Default is `false` (opt-in) to stay consistent with GSDD's stripped-down identity; users enable it explicitly **GSDD implementation:** `agents/approach-explorer.md` (role contract), `distilled/templates/delegates/approach-explorer.md` (thin delegate), `distilled/templates/approach.md` (output template), `distilled/workflows/plan.md` (`` section), `agents/planner.md` (`` section), `distilled/templates/delegates/plan-checker.md` (`approach_alignment` dimension), `bin/adapters/claude.mjs` + `bin/adapters/opencode.mjs` + `bin/adapters/codex.mjs` (native agent rendering), `tests/gsdd.guards.test.cjs`, `tests/gsdd.plan.adapters.test.cjs`, and `tests/gsdd.scenarios.test.cjs` (alignment-proof propagation coverage) --- ## 30. Hardening Propagation **Problem:** D28 introduced three hardening patterns (positional STOP gates, mandatory persistence with STOP-on-failure, guard-backed regression prevention) but applied them selectively: STOP gates only in `new-project.md`, persistence gates only in `execute.md` and `verify.md`. Three medium-tier workflows (`quick.md`, `map-codebase.md`, `new-project.md`) and two consistency targets (`audit-milestone.md`, `pause.md`) produce equally critical artifacts but lacked these protections. **Decision:** Propagate D28 patterns to all workflows that produce durable artifacts, organized into three tiers. Intentionally exclude read-only workflows (`progress.md`) and workflows with adequate existing coverage (`resume.md`). | Tier | ID | Workflow | Hardening | Pattern Source | |------|-----|----------|-----------|----------------| | 1 | H1 | `quick.md` | MANDATORY persistence gates for SUMMARY.md and VERIFICATION.md | `execute.md` SUMMARY gate | | 1 | H2 | `quick.md` | Positional STOP gate between plan and execute | `new-project.md` STOP gates | | 1 | H3 | `map-codebase.md` | Semantic quality check on mapper outputs (L2 substantiveness) | `verify.md` L1/L2/L3 checking | | 1 | H4 | `map-codebase.md` | MANDATORY persistence gate for 4 codebase documents | `execute.md` SUMMARY gate | | 1 | H5 | `new-project.md` | `` section for SPEC.md and ROADMAP.md | `verify.md` `` | | 1 | H6 | `quick.md` | Reduced-assurance plan self-check with `reduced_assurance` label | `plan.md` self-check fallback | | 2 | H7 | `audit-milestone.md` | MANDATORY persistence gate for MILESTONE-AUDIT.md | `execute.md` SUMMARY gate | | 2 | H8 | `pause.md` | MANDATORY persistence gate for `.continue-here.md` | `execute.md` SUMMARY gate | | 2 | H9 | `new-project.md` | Positional STOP gate between spec approval and roadmap creation | `new-project.md` STOP gates | **Intentional non-propagation:** - `progress.md`: read-only by contract — writes zero files, modifies zero state. Nothing to gate. - `resume.md`: state detection already validates artifact existence before routing. No gap. **Evidence:** 1. D28 consumer audit (2026-03-21): persistence failures and routing dead ends at every workflow boundary — patterns proven effective, scope was incomplete 2. Huang et al. "Large Language Models Cannot Self-Correct Reasoning Yet" (ICLR 2024): LLMs cannot reliably self-correct without external feedback — validates fresh-context checking and explicit STOP gates over implicit behavioral expectations 3. Kamoi et al. "When Can LLMs Actually Correct Their Own Mistakes?" (TACL 2024): self-correction works ONLY with reliable external feedback — validates MANDATORY gates as the external enforcement mechanism 4. Anthropic long-context research (2024): instructions at decision points are followed more reliably than instructions at document start — validates positional STOP placement at exact deviation points 5. D13 consistency argument: mechanical invariant enforcement prevents regression. The same structural pattern should be enforced everywhere it applies, not selectively. **Tradeoff:** 18 new guard assertions (G24) to maintain, but prevents artifact loss across 5 additional workflows. Each persistence gate adds 1-2 lines to its workflow. Positional STOP gates add 1 line each. The cost is minimal relative to the failure modes prevented (lost SPEC.md, lost checkpoint, empty codebase maps poisoning downstream planning). **GSDD implementation:** `distilled/workflows/quick.md`, `distilled/workflows/map-codebase.md`, `distilled/workflows/new-project.md`, `distilled/workflows/audit-milestone.md`, `distilled/workflows/pause.md`, `tests/gsdd.guards.test.cjs` (G24) --- ## 31. Outcome Dimension for Plan-Checker **Problem:** GSDD's plan-checker verifies 7 structural dimensions (requirement coverage, task completeness, dependency correctness, key link completeness, scope sanity, must-have quality, context compliance). All 7 are process supervision — they check whether the plan is well-formed, not whether it achieves the phase goal. A plan can pass all 7 dimensions while producing only scaffolding artifacts that don't deliver the stated outcome. **Decision:** Add an 8th dimension `goal_achievement` that performs outcome-level verification: - **Goal addressed?** Do the plan's collective task outputs deliver the phase goal? Tasks that only set up infrastructure without delivering the stated user-facing outcome → `blocker`. - **Success criteria reachable?** Are ROADMAP.md success criteria traceable to task verify outputs? Each criterion should map to at least one task → `blocker` if unreachable. - **Outcome observable?** Could a human or automated check confirm the goal was met after execution? Plans producing only internal artifacts with no testable outcome → `warning`. This creates a hybrid process+outcome verification architecture: 7 structural dimensions (process) + 1 outcome dimension. **Evidence:** 1. Yu et al. "Outcome-Refining Process Supervision for Code Generation" (ICML 2025): hybrid process+outcome supervision achieves +26.9% correctness over either alone — the strongest evidence for adding outcome-level checks alongside process checks 2. Rajan "Multi-Agent Code Verification via Information Theory" (2025): diminishing returns plateau around 4-7 specialized dimensions. 8 dimensions is within the efficient range; each additional dimension beyond 4 adds +11-15pp detection improvement 3. Lightman et al. "Let's Verify Step by Step" (ICLR 2024): process supervision (per-step feedback) significantly outperforms outcome-only supervision — validates keeping the existing 7 process dimensions while adding outcome as complement, not replacement **Tradeoff:** One additional dimension for the checker to evaluate per plan. Minimal cost: the goal and success criteria are already available as checker inputs (phase goal from ROADMAP.md, success criteria from ROADMAP.md phase section). No new inputs required. **GSDD implementation:** `distilled/templates/delegates/plan-checker.md` (`goal_achievement` dimension), `tests/gsdd.guards.test.cjs` (G24 assertions) --- ## 32. Quick Workflow Alignment Hardening **Problem:** GSDD's quick workflow has exactly one user alignment touchpoint — the task description at Step 1. After "what do you want to do?", the agent has unchecked autonomy over approach selection, scope interpretation, and execution. The full ceremony (`plan.md`) has 3-4 alignment touchpoints (approach exploration, plan review, checker escalation, mandatory verification). This gap is too large: quick mode trades ALL alignment for speed, creating a cliff between "zero agent oversight" and "full multi-round ceremony." GSD's approach was a `--full` flag that added plan-checking + verification to quick tasks. But a flag you must remember to use doesn't solve alignment — the default mode still had zero user visibility into the plan before execution. **Decision:** Three targeted interventions that close the alignment gap from 1 to 2-3 touchpoints without killing quick mode's speed advantage: 1. **Plan Preview Gate (mandatory, default-yes):** After the planner returns and the STOP gate verifies the plan exists, present a structured summary (task count, files to touch, 1-sentence approach) and wait for the user. Default-yes: pressing Enter proceeds. Options include edit, abort, and (when scope signal fires) switch to full ceremony. This is the core fix — the user sees agent intent before code changes happen. 2. **Scope Signal with Escalation (advisory, always-on):** Inline orchestrator evaluation checks the plan against quick-scope boundaries: >8 files modified, architecture keywords in description (`refactor`, `migration`, `security`, `auth`, `API design`, `schema`, `database`), new public APIs. If any signal fires, the advisory appears in the plan preview with a recommendation to use `/gsdd-plan` for approach exploration. Advisory only — the user decides. Keyword heuristics have false positives; blocking would train users to ignore the signal. 3. **Config-Gated Independent Plan Check (optional):** When `workflow.planCheck: true` in config.json, the existing plan-checker delegate runs against the quick task plan with 5 of 9 dimensions: `requirement_coverage`, `task_completeness`, `dependency_correctness`, `scope_sanity`, `must_have_quality`. Maximum 1 revision cycle (not 3 — diminishing returns for 1-3 task plans). If blockers remain, they surface in the plan preview for user decision. No new delegate or config key — reuses existing infrastructure. **GSD comparison:** | Aspect | GSD `--full` | GSDD D32 | |--------|-------------|----------| | Plan visibility | None in default, plan-checker in --full | Always-on preview (default-yes) | | Activation | Flag per invocation (easy to forget) | Config-driven (project-wide, consistent) | | Scope awareness | None | Advisory scope signal with escalation | | Checker scope | Full 5-dimension check (--full only) | 5-dimension quick-scoped check (config-gated) | | Revision cycles | Max 2 (--full only) | Max 1 (quick tasks don't warrant extended loops) | | User decision | Force proceed or abort after checker | Preview + scope signal + checker issues → informed decision | **Evidence:** 1. Risk-adaptive autonomy pattern (AWS, Azure, Anthropic 2025-2026): confirmation gates should scale with consequence level — routine auto-proceeds, uncertain pauses, high-impact requires sign-off. The plan preview is the "pause for uncertain" gate. 2. Human-on-the-loop > human-in-the-loop (Anthropic agent autonomy research 2026): HOTL gives visibility without requiring active management of each step. Default-yes implements HOTL — the user monitors, intervenes only when needed. 3. Osmani / Fowler on spec-driven development (2025): "iterate in small loops, course-correct quickly." The plan preview IS the small-loop checkpoint for quick tasks. 4. Madaan et al. "Self-Refine" (NeurIPS 2023): 1 revision cycle captures most improvement; diminishing returns argue against 3 cycles for 1-3 task plans. Validates max-1 checker cycle for quick scope. 5. Huang et al. "LLMs Cannot Self-Correct Reasoning Yet" (ICLR 2024): self-check without external feedback is unreliable. The plan preview provides external feedback (user eyes on the plan) even when the independent checker is disabled. 6. SkillsBench (Feb 2026): focused skills outperform comprehensive docs. Quick mode should stay focused and escalate to full ceremony when scope exceeds boundaries, not expand to absorb more ceremony. **Tradeoff:** ~5 seconds overhead for plan preview (default-yes), ~60-90 seconds if independent checker runs. Sub-hour work stays sub-hour. Adds ~60 lines to quick.md (198→~260). No new files, no new delegates, no new config keys. **GSDD implementation:** `distilled/workflows/quick.md` (Steps 3.5-3.7), `distilled/DESIGN.md` (this section), `tests/gsdd.guards.test.cjs` (G24 assertions for plan preview, scope signal, conditional plan-checker) --- ## 33. Quick Approach Clarification **Problem:** D32 added post-plan alignment to quick tasks (plan preview, scope signal, optional plan check), but all three interventions are **reactive** — the agent selects the approach unilaterally, writes the plan, then shows it to the user. The user can abort or edit the description, but cannot shape the approach before the planner commits. The full ceremony's `` (plan.md) solves this at scale with 3-4 grey areas, research subagents, and persisted APPROACH.md — but that's wrong for sub-hour work. **Decision:** Add Step 2.5 (Approach Clarification) between Initialize and Plan. Config-gated via the existing `workflow.discuss` toggle — same toggle that gates full ceremony's approach exploration, same intent ("align on approach before planning"), lighter mechanism for quick scope. The step has a **dual gate** — even with `workflow.discuss: true`, it evaluates the task description for ambiguity signals before asking anything: | Signal | Detection | Example | |--------|-----------|---------| | Multiple valid approaches | Description solvable via distinct patterns | "add caching" (Redis? in-memory? HTTP headers?) | | Destructive operations | Contains: `delete`, `remove`, `migrate`, `rename`, `replace`, `rewrite`, `drop` | "remove the old auth middleware" | | Vague scope | Contains: `improve`, `fix`, `update`, `refactor`, `clean up`, `optimize` without specifying target | "improve error handling" | | Trade-off present | Implies competing goals | "make it faster" (algorithmic? caching? denormalization?) | If no signals fire, the step skips silently — no questions asked, even with toggle on. When signals fire, the orchestrator identifies 1-2 grey areas and asks targeted questions in **recommendation-first format**: "I'd approach this with X because Y. Want me to proceed, or do you prefer Z?" Maximum 2 questions — if a task has 3+ grey areas, the scope signal (D32) should already be recommending `/gsdd-plan`. Output is inline `$APPROACH_CONTEXT` (e.g., "User confirmed: use in-memory LRU cache, not Redis") passed to the planner as locked constraints. No APPROACH.md file — file artifacts add overhead with no return for sub-hour work. **GSD comparison:** GSD has no pre-plan questioning in quick mode. The `--full` flag adds plan-checking and verification but not approach alignment — the agent still decides the approach unilaterally in all modes. | Aspect | GSD Quick | GSDD Quick (D32) | GSDD Quick (D32+D33) | GSDD Full Ceremony | |--------|----------|------------------|---------------------|-------------------| | Pre-plan alignment | None | None | 1-2 questions (conditional) | 3-4 grey areas + research subagents | | Post-plan alignment | None (--full adds checker) | Preview + scope signal | Preview + scope signal | Checker blocks (max-3 cycles) | | Approach persistence | None | None | Inline context only | APPROACH.md file | | User alignment rounds | 1 | 2-3 | 2-4 | 3-4 | **Evidence:** 1. Anthropic "Measuring AI agent autonomy in practice" (2025): Claude asks 2x+ more on complex tasks; uncertainty awareness is treated as a safety property. D33's ambiguity detection formalizes what Claude naturally does — ask when uncertain, proceed when confident. 2. Knight First Amendment Institute "Levels of Autonomy for AI Agents" (2025): 5-level autonomy spectrum. Quick tasks map to Level 3 ("Consultant"): agent decides, asks when uncertain. D33 implements this — agent leads with recommendation, asks only on ambiguity. 3. Anthropic "Framework for safe and trustworthy agents" (2025): recommendation-first framing validated. "I'd do X because Y. Approve?" outperforms open-ended "What should I do?" — preserves agent leadership while giving user override. 4. Martin Fowler "Humans and Agents in SE Loops" (2025): HOTL > HITL — agents handle 95% autonomously, pause for 5% edge cases. D33 asks only when ambiguity detected, not on every task. 5. Huang et al. "LLMs Cannot Self-Correct Reasoning Yet" (ICLR 2024): LLMs cannot reliably self-correct without external feedback. Pre-plan user input catches approach errors that self-check cannot detect. 6. Anthropic trust calibration data (2025): users auto-approve 20% initially → 40% by session 750+. Config-gated design respects this — experienced users who trust the agent disable `workflow.discuss`. **Counter-evidence addressed:** Asking too much creates HITL bottleneck (iMerit 2025, McKinsey 2025) → mitigated by dual gate (config + ambiguity detection). Open-ended questions reduce user confidence (Anthropic best practices) → mitigated by recommendation-first format. Routine tasks shouldn't be interrupted (SkillsBench Feb 2026) → mitigated by silent skip when no ambiguity detected. **Competitor landscape:** Cursor uses explicit mode selection (Ask vs Agent) without automatic ambiguity detection. GitHub Copilot uses post-hoc PR review only. GSD uses per-invocation `--full` flag. None do automatic ambiguity-sensitive pre-plan questioning. **Tradeoff:** ~15-30 seconds overhead when triggered (1-2 questions). Skipped entirely when no ambiguity detected, even with toggle on. Adds ~40 lines to quick.md. No new files, no new delegates, no new config keys — reuses existing `workflow.discuss` toggle. **GSDD implementation:** `distilled/workflows/quick.md` (Step 2.5), `distilled/DESIGN.md` (this section), `tests/gsdd.guards.test.cjs` (G24 assertions for approach clarification, ambiguity signals, recommendation-first format) --- ## 34. Context Engineering Applied to Quick Workflow **GSD:** GSD quick.md has ``, ``, `` (XML outer sections) with `**Step N:**` bold markdown inside ``. No `` section. No authority language conventions for process gates. **GSDD (before D34):** Same XML outer sections with markdown step headers inside ``. All 9 role contracts have `` after `` (documented in DISTILLATION.md as mandatory placement), but quick.md — an orchestrator consumed by AI agents — had none. Authority language mixed between `**STOP.**` and `**MANDATORY:**` across 3 file-verification gates. **GSDD (D34):** Two targeted changes applying context engineering principles from the prompty/agentskit reference implementation (28 primary sources) and Anthropic prompting guidance: **Change 1: `` section.** Added 7 anti-patterns after ``, matching the 5-8 item range used by role contracts. Each maps to a real workflow gate (plan preview, file verification, max 2 questions, no APPROACH.md, no ROADMAP/SPEC updates, config.json reads, no scope expansion). This is the single highest-value context engineering improvement — it gives agents explicit "don't do this" guardrails for the workflow's most critical gates. **Change 2: Authority language normalization.** `**MANDATORY:**` → `**STOP.**` on 2 of 3 file-verification gates. DISTILLATION.md resolves authority language vocabulary: CRITICAL for initial-read gates, normal imperative language for process gates. STOP is the correct word for "halt and check" gates; MANDATORY is not in the resolved vocabulary. **What was investigated but NOT changed:** | Finding | Decision | Why | |---------|----------|-----| | Steps use markdown headers, not XML `` tags | Keep markdown headers | All 10 GSDD workflows use the same pattern. prompty's agentskit-architect SKILL.md uses the identical pattern (single `` container with text step labels). Changing quick.md alone creates cross-workflow inconsistency. Candidate for a future cross-workflow PR. | | No `` section | Not needed | `` section already specifies what the workflow produces — paths, status, next steps | | No `` section | Not needed | `` section already covers required preconditions | | No progressive disclosure restructuring | Not needed | ~350 lines is within the agentskills.io 500-line recommended limit | | Caching-friendly ordering | Already correct | Static content (role, anti_patterns, prerequisites) at top, variable content (process steps) below | **Evidence:** | Source | Contribution | |--------|-------------| | Anthropic Claude Prompting Best Practices [S1] | "Claude has been specifically tuned to pay special attention to your structure when using XML tags." Validates XML for section boundaries. Anti-patterns placed early for attention weight. | | DISTILLATION.md (GSDD internal) | "Anti-patterns early — Place 'don't do this' instructions near the top, after role definition." Cross-source validated pattern across all 9 role contracts. Authority language resolution: CRITICAL for initial-read, normal language elsewhere. | | Selective Prompt Anchoring, arxiv 2408.09121 (2024) | Up to 12.9% Pass@1 improvement from strategic attention anchoring. XML tags create hard attention boundaries; markdown headers may be treated as content formatting. | | agentskit-architect SKILL.md (prompty) | Uses single `` container with text step labels inside — same structural pattern as GSDD's `` with markdown headers. Validates the hybrid XML-outer/markdown-inner approach. | | Manus AI Context Engineering [S5] | "Filesystem as extended context" — structural quality of prompt files directly impacts agent behavior. Validates treating workflow files as engineered artifacts, not documentation. | | agentskit-evaluator SKILL.md (prompty) | Authority language audit: "CRITICAL only for gates?" is a scored compliance check. Validates normalizing gate vocabulary. | **Scope:** quick.md only. If `` proves valuable for orchestrators, extend to plan.md and other workflows in a follow-up PR. **GSDD implementation:** `distilled/workflows/quick.md` (`` section, STOP normalization), `distilled/DESIGN.md` (this section), `tests/gsdd.guards.test.cjs` (G26 assertions for anti_patterns placement, content, gate language consistency, XML structural sections) --- ## 35. Skills-Native Runtimes vs Governance Adapters **Problem:** Repo surfaces had started conflating two different questions: 1. Does the runtime expose `.agents/skills/` through skill or slash discovery? 2. What extra generated adapter artifact does `npx -y gsdd-cli init --tools ` add? That conflation was survivable while Cursor and Copilot were incorrectly treated as governance-first tools, but it became actively misleading once skill discovery was validated outside the root `AGENTS.md` governance path. The old grouped README / AGENTS wording wrongly implied the root `AGENTS.md` block was required for workflow discovery on those runtimes. **Decision:** Separate runtime capability from generated adapter artifact kind. - Cursor, Copilot, and Gemini are documented as **qualified-support runtimes**: they can use `.agents/skills/gsdd-*` when skill or slash discovery is available, with `SKILL.md` fallback when it is not. - `--tools cursor`, `--tools copilot`, `--tools gemini`, and `--tools agents` still generate the same root `AGENTS.md` bounded block, but that artifact is **governance only**. - The root `AGENTS.md` block remains valuable behavioral discipline, but it must not be described as the workflow-discovery mechanism for a skills-native runtime. - No new runtime-specific adapter files are introduced just to make the docs read cleaner. The generated artifact model stays simple unless a stronger runtime-specific UX is actually needed. **Why this fits the architecture:** The adapter code already had the right implementation shape: one shared root-governance generator (`createRootAgentsAdapter`) with different runtime labels. The bug was the capability story wrapped around it. Fixing the narrative without inventing redundant adapter files preserves leverage and keeps the portable `.agents/skills/` surface as the canonical entry layer. **Evidence:** 1. Consumer testing showed Cursor and Copilot can use `.agents/skills/` without treating AGENTS.md as the workflow source. 2. User-performed validation showed Gemini can follow the same generated-skill path, while public docs still avoid parity claims. 3. GSDD implementation already always generates `.agents/skills/` and uses the root `AGENTS.md` block as a bounded governance upsert, not as a workflow source. 4. This resolution matches the repo rule that skills, adapters, and governance surfaces must not be conflated. **GSDD implementation:** `README.md`, `distilled/templates/agents.block.md`, `bin/lib/init.mjs`, `SPEC.md`, `.internal-research/TODO.md`, `.internal-research/gaps.md`, `.internal-research/lessons-learned.md`, `tests/gsdd.guards.test.cjs` --- ## 36. Interactive Init Wizard **Problem:** `gsdd init` (now usually invoked by humans as `npx -y gsdd-cli 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 `npx -y gsdd-cli init` a guided install wizard in TTY environments, while preserving `--tools` and `--auto` as the manual/headless contract. The guided path must stay intentionally compact: runtime choice, governance opt-in, and a small set of bundled planning defaults rather than a long per-setting questionnaire. - Step 1: choose runtimes/vendors with a simple checkbox-style selector (space toggles, enter confirms). - Step 2: ask separately whether to install repo-wide `AGENTS.md` governance, with explicit explanation of why it helps and why it may feel invasive. - Step 3: collect the planning defaults through two orthogonal bundled choices (`Rigor` and `Cost`) plus the separate `.planning` tracking choice, instead of a long per-setting questionnaire. - Portable `.agents/skills/gsdd-*` skills remain the always-generated baseline. - Legacy values such as `--tools cursor`, `--tools copilot`, and `--tools gemini` remain valid for backward compatibility. **Key architectural rule:** runtime selection and adapter generation are separate concerns. - In the wizard, choosing Cursor/Copilot/Gemini affects post-init routing and user-facing install intent, but does **not** silently write root `AGENTS.md`. - Root `AGENTS.md` is generated only when the user explicitly opts into governance (wizard) or explicitly requests a governance-writing flag path (`--tools agents`, `--tools all`, or legacy runtime aliases). - This keeps D35's capability split honest instead of re-conflating skills-native runtime choice with governance-file generation. **Phase 17 refinement:** - The guided config path was reduced from 13 visible prompts to 5. - `Rigor` controls `researchDepth` and workflow strictness (`research`, `discuss`, `planCheck`) while keeping `workflow.verifier` always on. - `Cost` controls `modelProfile` and `parallelization` independently, so combinations such as `thorough + budget` remain reachable. - `gitProtocol` remains in `config.json` with defaults but is intentionally out of the wizard until a dedicated UX pass decides the right shape. **Why this fits the codebase:** The adapter registry and `init.mjs` already own the right boundary. The high-leverage change was to add a decision layer in front of writes, not to invent a new adapter model or a new config schema. This keeps the CLI lightweight, preserves backward compatibility, and makes the default install path match the product story. **Evidence:** 1. Existing repo truth: `npx -y gsdd-cli init` always generates `.agents/skills/` and already has a central adapter-selection seam in `bin/lib/init.mjs`. 2. Local research on the adjacent `prompty` repo: portable skills are the primary install surface, while native command surfaces are optional additions. 3. External: npm init (Node.js), Vite `create-vite`, Next.js `create-next-app`, Angular CLI `ng new`, and Astro `create astro` all implement the same pattern — TTY-interactive wizard by default, `--yes`/`--defaults` for headless; this is the de facto standard for modern project scaffolding tools. 4. Repo lesson LL-INSTALL-DX-BEFORE-ALIAS-CLEANUP already recorded that install ergonomics should be fixed before alias-policy cleanup. **GSD comparison:** GSD's install surface is more operator-heavy and framework-specific. GSDD keeps the deterministic bootstrap principle but shifts the user-facing choice surface into a lightweight guided CLI instead of requiring users to know adapter values in advance. **GSDD implementation:** `bin/lib/init.mjs`, `bin/lib/init-flow.mjs`, `bin/lib/init-prompts.mjs`, `bin/lib/models.mjs`, `bin/gsdd.mjs`, `README.md`, `distilled/README.md`, `SPEC.md`, `.internal-research/TODO.md`, `.internal-research/gaps.md`, `.internal-research/lessons-learned.md`, `tests/gsdd.init.test.cjs`, `tests/gsdd.consumer-ceremony.test.cjs`, `tests/gsdd.guards.test.cjs` --- ## 37. Mutability-Driven Workflow Classification **Problem:** GSDD had started treating several artifact-writing workflows as planning-class surfaces in the workflow registry. That looked semantically neat (`new-project`, `plan`, `verify`, `audit-milestone`, `pause`, `resume` all sound like "thinking" work), but it created a runtime contradiction: the workflow contract required disk persistence while the generated surface could be interpreted as a read-only planning lane. **Decision:** Classify workflow surfaces by mutability, not by whether the workflow feels like planning. - Any workflow that writes or deletes durable artifacts emits `agent: Code` and `opencodeType: edit`. - Only truly read-only workflows emit `agent: Plan` and `opencodeType: plan`. - `progress` remains the only read-only workflow in the current lifecycle. - The registry now records this explicitly via `mutatesArtifacts` so future changes have an inspectable invariant instead of relying on naming intuition. **Why this fits the codebase:** GSDD's real leverage depends on docs-to-disk persistence. `new-project`, `plan`, `verify`, `audit-milestone`, `pause`, and `resume` are orchestration-heavy, but they are still state-changing workflows. Treating them as read-only breaks the artifact chain that downstream workflows consume. **Kept / stripped / gained relative to the previous state:** - **Kept:** the existing portable workflow content, native plan-checker surfaces, and the distinction between read-only reporting (`progress`) and artifact-producing lifecycle work. - **Stripped:** the informal assumption that "planning-like" workflows should all share the `Plan` lane. - **Gained:** an explicit mutability invariant, generated-surface tests, and safer behavior in runtimes that enforce planning/read-only execution semantics. **Evidence:** 1. `distilled/workflows/verify.md`, `new-project.md`, `audit-milestone.md`, `pause.md`, and `resume.md` all require artifact writes or deletions as part of completion. 2. `distilled/workflows/progress.md` is the only workflow that explicitly declares itself read-only. 3. Consumer audit evidence already showed verification reports being lost when persistence was skipped; this decision closes the registry seam that could recreate the same class of failure. 4. External: Meyer's Command-Query Separation (CQS, "Object-Oriented Software Construction" 1988) — the foundational principle that operations should be classified by whether they modify state, not by what they conceptually represent; Greg Young's CQRS (2010) — CQS applied at the architectural level; Unix rwx permission model and AWS IAM/Kubernetes RBAC all classify operations by mutation semantics rather than by semantic category name **GSD comparison:** GSD's leverage also depends on persisted workflow artifacts. GSDD's portable/runtime split adds a new failure mode GSD did not have in the same form: a generated adapter can misclassify a mutating workflow even when the markdown contract is correct. This decision makes the adapter/runtime layer honor the artifact contract instead of undermining it. **GSDD implementation:** `bin/gsdd.mjs`, `bin/lib/rendering.mjs`, `tests/gsdd.init.test.cjs`, `tests/gsdd.plan.adapters.test.cjs`, `tests/gsdd.guards.test.cjs`, `SPEC.md`, `.internal-research/TODO.md`, `.internal-research/gaps.md`, `.internal-research/lessons-learned.md` --- ## 38. Retroactive Artifact Enforcement **Problem:** ROADMAP.md phase `[x]` can be marked complete without the required artifacts (PLAN.md, SUMMARY.md, VERIFICATION.md) existing on disk. No mechanical gate prevents phase advancement without artifacts. This gap (I27) recurred twice in the v1 milestone: - Sub-gap (a): early session termination drops final bookkeeping — ROADMAP marked `[x]` with no VERIFICATION.md. - Sub-gap (b): `verify.md` structural omission — even on full lifecycle success, ROADMAP stayed stale because only `execute.md` updated it. Sub-gap (b) was closed by D28's `` 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 `` 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 `` 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 `` XML block with four sections: ``, ``, ``, and ``. - 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 `` 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 ``. - 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 `` 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 `` (crash safety), then previously deleted `.bak` in `` 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 ``, ``, or `` rules. - `pause.md` line 53 already deletes stale `.bak` files from prior crashed resumes — this crash-cleanup path remains unchanged. **Decision:** - `resume.md` `` 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 `` 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 `` | 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 `` | `.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` ``, 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 `` section exists. **GSDD implementation:** `distilled/workflows/resume.md` (`.bak` deletion removed from ``), `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` (``, 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. - Runtime-freshness work now owns authored/generated freshness enforcement explicitly instead of inheriting that work as vague follow-through from the earlier dual-canonical runtime split. **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 - The lifecycle-preflight work was explicitly scoped to turn the shared evaluator seam into deterministic preflight enforcement without widening into evidence typing or runtime-surface 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, including plan creation, to call the shared preflight seam instead of narrating their own lifecycle inference. - Treat planning-state drift as warning-only for read-only surfaces and blocking for owned-write surfaces, with file-level drift details from the session fingerprint helper. - 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/lib/session-fingerprint.mjs` - `bin/gsdd.mjs` - `distilled/workflows/plan.md` - `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/session-fingerprint.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/lib/session-fingerprint.mjs`, `bin/gsdd.mjs`, `bin/lib/init.mjs`, `distilled/workflows/plan.md`, `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/session-fingerprint.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, revised 2026-04-22, revised 2026-04-24):** Installed generated runtime-facing surfaces are trustworthy only through deterministic rendering from the authored workflow and delegate sources. When `.agents/`, `.claude/`, `.opencode/`, or `.codex/` exist locally, `npx -y gsdd-cli health` must compare those generated files against current render output and route any drift back through `npx -y gsdd-cli update`. Bare `gsdd health/update` remains valid only for global installs. **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. - Fresh consumer repos exposed a second contract gap: workflow-internal helper calls still assumed bare `gsdd ...` resolution even though `init` only guaranteed generated files on disk, not an ambient PATH install. **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 (`npx -y gsdd-cli update` or targeted `npx -y gsdd-cli update --tools `) instead of treating the fix as a manual review exercise. - Treat the portable runtime surface as more than skill markdown: keep workflow discovery under `.agents/skills/`, generate the repo-local helper runtime at `.planning/bin/gsdd.mjs`, route workflow-internal deterministic helper calls through `node .planning/bin/gsdd.mjs ...` instead of bare `gsdd ...`, and keep human install/update/health guidance on `npx -y gsdd-cli ...` unless a global install is explicitly present. - 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 moves helper-command resolution from ambient machine state into generated repo state under `.planning/bin`, which is the seam `init` and `update` already own deterministically. - 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 runtime-freshness milestone entry - .internal-research/gaps.md (I42 closure) - bin/lib/runtime-freshness.mjs - bin/lib/health.mjs - bin/lib/health-truth.mjs - bin/lib/rendering.mjs - bin/lib/init-flow.mjs - bin/lib/init-runtime.mjs - bin/adapters/claude.mjs, bin/adapters/opencode.mjs, bin/adapters/codex.mjs - README.md, docs/RUNTIME-SUPPORT.md, distilled/README.md - docs/USER-GUIDE.md - tests/phase.test.cjs, tests/gsdd.health.test.cjs, tests/gsdd.init.test.cjs, tests/gsdd.plan.adapters.test.cjs, tests/gsdd.guards.test.cjs, tests/gsdd.scenarios.test.cjs **Consequences:** - `npx -y gsdd-cli health` can now surface installed generated-surface drift as deterministic workspace truth instead of relying on review discipline. - `npx -y gsdd-cli update` becomes the explicit repair path for authored/generated runtime-surface drift. - Fresh consumer repos now carry their own deterministic helper-command seam under `.planning/bin`, so lifecycle/file-op/status calls no longer depend on whichever `gsdd` binary happens to be present on PATH. - 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. - Native adapters and root governance remain optional prompt/convenience surfaces; the token-saving story comes from compact skill entrypoints and repo-local artifacts, not from installing every adapter everywhere. **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:** bin/lib/runtime-freshness.mjs, bin/lib/health.mjs, bin/lib/health-truth.mjs, bin/lib/rendering.mjs, bin/adapters/claude.mjs, bin/adapters/opencode.mjs, bin/adapters/codex.mjs, README.md, docs/RUNTIME-SUPPORT.md, distilled/README.md, .planning/SPEC.md, .internal-research/TODO.md, .internal-research/gaps.md, tests/phase.test.cjs, tests/gsdd.health.test.cjs, tests/gsdd.plan.adapters.test.cjs, tests/gsdd.guards.test.cjs, tests/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` - `known_unknowns` - `browser_proof_required` - `browser_proof_rationale` - `must_haves` - Keep high-risk review pressure in the plan body through Evidence Contract, Stop-And-Challenge, Approval Gates, and Second-Pass Review sections instead of expanding the frontmatter into a control-plane schema. - 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; revised 2026-06-30):** 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. Active bounded brownfield planning uses the existing `gsdd-plan` workflow with explicit `brownfield-change` authority instead of being forced through unrelated ROADMAP phase membership. **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 - Keep `gsdd-plan` as the bounded brownfield planning entrypoint when an active `.planning/brownfield-change/CHANGE.md` exists: - `gsdd next --json` reports `authority: brownfield_change` and routes to `gsdd-plan` - `gsdd-plan` classifies the target before phase preflight - `lifecycle-preflight plan brownfield-change` authorizes the change-folder lane without requiring the active ROADMAP phase to match a PBI or consumer ticket - 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 fixes the consumer failure mode where PBI/ticket-sized brownfield work was blocked by an unrelated active ROADMAP phase while still avoiding a new workflow or auto-runner surface. - 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, and active bounded brownfield planning has one explicit preflight authority. - 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, revised 2026-04-23):** Workflow-embedded CLI helper commands must run through a generated local helper runtime under `.planning/bin/`, with `.planning/bin/gsdd.mjs` as the canonical launcher and copied support modules under `.planning/bin/lib/`, instead of assuming a bare `gsdd` binary is available on the consumer repo's PATH or proxying helper execution back through `npm exec` at workflow runtime. **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 helper surface must stay out of `.agents/` ownership so it does not pollute unrelated `.agents` folders or leak into generated governance. - The first `.planning/bin/gsdd.mjs` repair still left the wrong runtime dependency in place: the generated file was a trampoline back through `npm exec --package=gsdd-cli@... -- gsdd ...`, so helper execution still depended on npm/package resolution and shell quirks at the exact moment deterministic local mechanics were supposed to be the reliable fallback. **Decision:** - Generate `.planning/bin/gsdd.mjs` as a self-contained local helper runtime plus repo-local shell shims (`.planning/bin/gsdd`, `.planning/bin/gsdd.cmd`, `.planning/bin/gsdd.ps1`) on `gsdd init` for every initialized workspace. - Regenerate that helper surface on `gsdd update` whenever `.planning/` exists. - Copy the minimal helper support modules into `.planning/bin/lib/` so workflow-time helper execution needs only Node, not npm/package-manager resolution. - Bootstrap the workspace root from the generated helper location and shared root-resolution logic so helper commands operate on repo truth instead of raw `process.cwd()`. - 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. - It removes npm/package fetches from the helper hot path, which is the stronger cross-platform ownership model for Linux, WSL, and Windows consumers. - It lets both the generated helper runtime and the main CLI share one root-resolution seam instead of relying on repo-root `cwd` as an unstated precondition. **Evidence:** - `bin/lib/init-flow.mjs` - `bin/lib/rendering.mjs` - `bin/lib/workspace-root.mjs` - `bin/lib/file-ops.mjs` - `bin/lib/phase.mjs` - `bin/lib/lifecycle-preflight.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/phase.test.cjs` - `tests/gsdd.scenarios.test.cjs` **Consequences:** - Consumer repos no longer need a global `gsdd` binary or workflow-time `npm exec` trampoline for 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 helper-surface instructions stay out of `AGENTS.md`. - Cross-platform proof is stronger for the local-helper seam itself, but direct live validation still needs to stay conservative by environment: the repo now has focused tests plus Windows fixture proof; Linux/WSL live consumer validation remains a separate evidence question. ## D59 - Continuity Authority And Planning-State Drift **Decision (2026-04-27):** Workspine continuity authority is split by surface. Git/worktree truth owns integration visibility and overwrite risk, `.planning/` owns local workflow contracts, phase artifacts own phase-local scope and proof, generated runtime surfaces own consumed helper/adapter freshness, and compressed judgment remains advisory context. Planning-state drift must stay warning-only for read-only/reporting surfaces, but mutating lifecycle surfaces must not silently proceed through material drift. **Context:** - `.planning/` remains local-only by default in this framework repo. That preserves privacy and avoids noisy framework-internal planning commits, but it also means planning state can drift across sessions without git history protecting it. - Gap `I46` showed the concrete failure: one session wrote milestone state under ignored `.planning/`, another session read stale planning state and nearly routed execution as if the milestone did not exist. - Gap `S6` showed the related judgment failure: fresh sessions can recover artifact structure while losing the active constraints, unresolved uncertainty, decision posture, and anti-regression rules that explain how to continue safely. - Existing helper seams already detect part of the risk: `session-fingerprint.mjs` fingerprints `.planning/ROADMAP.md`, `.planning/SPEC.md`, and `.planning/config.json`; `lifecycle-preflight.mjs` exposes drift as `planning_state_drift`; `health` reports the same condition as `W12`. **Authority matrix:** | Surface | Owns | Does not own | Provenance check | Drift signal | Stop condition | Proof needed | | --- | --- | --- | --- | --- | --- | --- | | Git branch/HEAD | Integration surface identity, commit baseline, branch-local work context | Planning truth, phase status, judgment | `git rev-parse --abbrev-ref HEAD`; `git rev-parse --short HEAD` | Unexpected branch or HEAD relative to the active plan/change | Mutating workflow targets a different branch or HEAD than the active plan/change declares | Captured branch/HEAD before mutation; explicit acknowledgement if mismatched | | Staged changes | Pending commit contents and delivery visibility risk | Final repo truth until committed; planning authority | `git diff --name-only --cached` | Staged paths outside declared write set | Staged work overlaps unrelated scope or would be accidentally included | Staged path list reviewed against plan write set | | Unstaged changes | Local uncommitted edits and overwrite/conflict risk | Approved implementation state; phase closure | `git diff --name-only` | Dirty tracked files outside declared write set | Mutating workflow would overwrite or reinterpret unrelated edits | Dirty path list reviewed; user decision if conflict or overlap exists | | Untracked files | Local-only artifacts and possible proof gaps | Durable repo truth; public/delivery evidence | `git status --porcelain=v1` | Untracked required artifacts, generated dirs, or scope-expanding files | Required proof/output exists only untracked when closure claims tracked truth | Required artifacts are tracked intentionally or explicitly classified local-only | | `.planning/SPEC.md` | Local product/workflow requirements and active milestone requirement truth | Git-tracked public truth in the framework repo; branch delivery state | Read active requirements/current state; compare to roadmap and trackers | `W12`; mismatch with ROADMAP/TODO/gaps; stale active milestone | Mutating lifecycle action depends on stale or contradictory requirements | Fresh read plus drift acknowledgement/blocking behavior before mutation | | `.planning/ROADMAP.md` | Active milestone/phase ordering, status, success criteria, stop/replan contract | Artifact existence proof; implementation completion by itself | Read active phase section; lifecycle evaluator/preflight | `W12`; overview/detail mismatch; phase artifact mismatch | Execute/verify/audit/complete would act on stale or contradictory roadmap state | Preflight passes or blocks; phase status agrees with artifacts | | Phase PLAN/SUMMARY/VERIFICATION | Phase-local scope, execution result, verification result, compressed judgment handoff | Milestone-wide truth alone; git integration truth; generated runtime freshness | Check phase directory and required artifact sequence | PLAN without SUMMARY; SUMMARY missing for verify; VERIFICATION missing for completed phase | Execute without valid pending plan; verify without summary; close phase without verification | Required artifact exists, is substantive, and matches roadmap status | | Checkpoint files | Session-local resume context and mid-session compressed judgment | Durable status; routing authority over fresh roadmap/git truth | `.planning/.continue-here.md` and `.planning/.continue-here.bak` presence/classification | Checkpoint narrative conflicts with branch/worktree/planning truth; stale generic checkpoint | Resume would route from materially misleading checkpoint without acknowledgement | Resume surfaces checkpoint/planning/git split; material mismatch requires acknowledgement | | Brownfield CHANGE/HANDOFF/VERIFICATION | Medium-scope brownfield operational anchor, judgment handoff, closeout proof | Milestone phase state; roadmap-owned lifecycle; generic scratchpad | `.planning/brownfield-change/*` presence and lifecycle-state classification | Artifact branch/write-scope mismatch; missing sibling file; stale next action | Resume/progress would treat stale brownfield artifact as current without warning/acknowledgement | CHANGE primary, HANDOFF judgment-only, VERIFICATION proof; mismatch handled by progress/resume split | | Milestone audit | Milestone closure evidence and pass/fail posture | Phase execution; public release/delivery unless evidence says so | `.planning/-MILESTONE-AUDIT.md`, `status: passed`, evidence contract | Missing audit for completion; audit not passed; evidence gaps | `complete-milestone` without passed audit or required evidence | Audit artifact exists, passed, and required evidence kinds are present | | Generated runtime surfaces | Consumed local runtime/helper surfaces generated from authored source | Authored workflow truth; planning status; branch truth | `gsdd health --json` runtime freshness and manifest comparison | `W11` drift from current render output | Phase behavior depends on generated-surface parity, or closure claims runtime freshness | Run the normal update path only when needed; health/checks prove freshness | **Decision rules:** - Read-only/reporting surfaces may warn on planning-state drift and continue. They must not refresh or mutate the planning fingerprint as a side effect. - Owned-write lifecycle surfaces must treat material planning-state drift as a stop or explicit acknowledgement boundary before writing summary, verification, milestone, roadmap, or checkpoint-cleanup artifacts. - No-baseline fingerprint state is not itself proof of drift. It should be classified explicitly, but it must not strand first-session users unless another contradiction exists. - Compressed judgment remains the four-section `` shape (`active_constraints`, `unresolved_uncertainty`, `decision_posture`, `anti_regression`) and remains subordinate to operational state. - A tracked coordination artifact is not justified by Phase 44 evidence alone. It becomes necessary only if deterministic local checks cannot prevent stale-read/overwrite behavior or if a future release claim requires fresh-clone/public evidence. **Evidence:** - `.planning/phases/44-continuity-authority-and-persistence/44-APPROACH.md` - `.planning/phases/44-continuity-authority-and-persistence/44-PLAN.md` - `.planning/SPEC.md` (`REL-01`) - `.planning/ROADMAP.md` (Phase 44) - `.internal-research/gaps.md` (`I46`, `S6`) - `bin/lib/session-fingerprint.mjs` - `bin/lib/lifecycle-preflight.mjs` - `bin/lib/runtime-freshness.mjs` - `distilled/workflows/progress.md` - `distilled/workflows/resume.md` - `distilled/workflows/execute.md` - `distilled/workflows/verify.md` - `distilled/workflows/audit-milestone.md` - `distilled/workflows/complete-milestone.md` - `distilled/workflows/new-milestone.md` - `distilled/templates/brownfield-change/CHANGE.md` - `distilled/templates/brownfield-change/HANDOFF.md` - `distilled/templates/brownfield-change/VERIFICATION.md` - `tests/session-fingerprint.test.cjs` - `tests/phase.test.cjs` **Consequences:** - Phase execution can remain local-first without pretending ignored `.planning/` files are unconditional authority. - Planning drift becomes a concrete lifecycle safety signal rather than a generic health warning that agents can ignore. - The design avoids adding a scratchpad or second state system while preserving enough compressed judgment to guide cold-start continuation. - The remaining implementation question is narrow: make helper output and targeted tests reflect this authority split without widening Phase 44 into generated-surface or release-closeout work. --- ## D60 - Release Closeout Contract **Decision (2026-04-27, enforced 2026-04-27):** Release-quality milestone closeout uses a release claim posture layered over the existing evidence posture matrix. The allowed postures are `repo_closeout`, `runtime_validated_closeout`, and `delivery_supported_closeout`; each posture must stay within the fixed evidence kinds `code`, `test`, `runtime`, `delivery`, and `human`. **Context:** - D50 already defined the closure evidence matrix for `verify`, `audit-milestone`, and `complete-milestone`, but `repo_only` and `delivery_sensitive` are evidence bars rather than wording boundaries. - D59 clarified that `.planning/` remains local-only by default, generated runtime surfaces own their own freshness, and public/delivery claims need git/worktree or tracked repo-visible proof. - Phase 45 needed a way to close repo-local milestone work honestly without implying GitHub Releases, package publishes, runtime parity, generated-surface freshness, or external availability. - GitHub Releases remain explicitly deferred under `LSC-05`, so release closeout cannot depend on public release objects unless a later milestone approves them. **Decision:** - Add release claim posture semantics to `bin/lib/evidence-contract.mjs` without adding evidence kinds or replacing delivery postures. - Define the three postures as claim boundaries: - `repo_closeout`: default; permits repo-local closeout only and must not imply public support, runtime validation, delivery, publication, or generated-surface freshness. - `runtime_validated_closeout`: permits claims about a named runtime behavior or runtime surface only when `runtime` evidence exists for that exact runtime or surface. - `delivery_supported_closeout`: permits externally consumed release, install, support, or delivery claims only when the `delivery_sensitive` evidence bar is satisfied. - Thread the posture through `audit-milestone` as audit-owned release closeout metadata: unsupported claims, waivers, deferrals, and contradiction checks are recorded with the audit evidence contract. - Make `complete-milestone` inherit the audit posture and stop when unsupported claims, invalid waivers, missing evidence, incompatible posture metadata, or failed claim-scoped contradiction checks remain. - Keep `verify` out of the main release-claim decision path; phase verification still records evidence, while milestone audit and completion own release closeout. - Enforce the inherited contract in `lifecycle-preflight complete-milestone` so milestone completion cannot proceed from a passed audit that lacks release-claim metadata or still contains unsupported stronger claims, invalid waivers, missing required evidence, incompatible posture metadata, or failed claim-scoped contradiction checks. **Why this fits the codebase:** - It preserves the compact D50 evidence matrix and avoids a new `release` evidence kind. - It avoids a new workflow lane or `gsdd-release` command by using the existing closeout surfaces. - It lets repo-local milestones close without fabricated delivery proof while preventing stronger public/runtime/delivery language from outrunning evidence. - It respects D59: local-only planning artifacts can support internal closeout, but public release/support claims need tracked public or repo-visible evidence. **Waiver and deferral rule:** Waivers may narrow a claim posture or defer an unsupported claim, but they never satisfy missing required evidence for the stronger claim. Deferrals must name the unsupported claim, missing evidence kind(s), and later workflow or milestone candidate when known. **Contradiction checks:** Closeout must check evidence, public-surface, runtime, delivery, planning-drift, and generated-surface contradictions. Generated-surface drift blocks only claims that depend on generated runtime/helper freshness; it does not fail unrelated `repo_closeout` claims. Posture compatibility is part of that closeout contract: `repo_closeout` and `runtime_validated_closeout` are repo-local wording boundaries over `repo_only`, while `delivery_supported_closeout` requires the `delivery_sensitive` evidence bar. **Evidence:** - `.planning/phases/45-release-closeout-contract/45-APPROACH.md` - `.planning/phases/45-release-closeout-contract/45-PLAN.md` - `.planning/phases/48-generated-helper-and-closeout-contract-parity/48-PLAN.md` - `.planning/research/45-RESEARCH.md` - `.planning/SPEC.md` (`REL-02`, deferred `LSC-05`) - `.planning/ROADMAP.md` (Phase 45) - `bin/lib/evidence-contract.mjs` - `bin/lib/lifecycle-preflight.mjs` - `distilled/workflows/audit-milestone.md` - `distilled/workflows/complete-milestone.md` - `distilled/DESIGN.md` D50 and D59 - `tests/phase.test.cjs` - `tests/gsdd.guards.test.cjs` - `tests/gsdd.scenarios.test.cjs` **Consequences:** - A milestone audit can now distinguish internal repo closeout, runtime-validated closeout, and delivery-supported closeout without changing evidence kinds. - Missing delivery or runtime evidence must produce a downgrade or deferral; it cannot be hidden behind human waiver prose. - `complete-milestone` now fails closed before archive writes when the passed audit omits or contradicts the release claim contract. - Public claims are scoped to tracked public or repo-visible proof, while GitHub Releases, tags, package publication, and release automation remain deferred until explicitly planned. ## D61 - Deliberate Subagent Contract **Decision (2026-04-28):** Subagents are deliberate isolation tools, not hidden implementation orchestration. Workspine should use them for research, review, mapping, synthesis, and integration checking when the work is read-only or artifact-backed, while implementation remains sequential unless an approved plan explicitly owns disjoint write sets. **Context:** - Phase 50 found that existing subagent wording was over-strong in some planning and role surfaces while summary-size guidance had drifted across 3-5 sentence, 300-500 token, and 1000-token variants. - Phase 46 research supported parallel agents for breadth-first research, but warned that coding writes need stronger coordination before parallel PR or multi-worktree orchestration is safe. - Phase 53 approach alignment confirmed the conservative boundary: allow read-heavy and artifact-backed delegation, forbid hidden implementation orchestration, keep roadmapper role-only/direct invocation, and do not claim broad S3/S5 closure or native runtime parity. **Decision:** - Allowed subagent use: research, review, mapping, synthesis, and integration checks when they are read-only or when the subagent writes/updates its own bounded durable artifact. - Return discipline: routing summaries use 100-200 tokens, human-read summaries use 300-500 tokens, agent-mediated discussion summaries use 500-800 tokens, and full details live in durable documents on disk. - Forbidden by default: hidden implementation orchestration, agent teams, parallel PR flows, multi-worktree coding, and overlapping implementation writes without explicit write-set ownership in the approved plan. - Roadmapper remains role-only/direct invocation in Phase 53. Roadmap creation is sequential and coverage-sensitive, writes `.planning/ROADMAP.md`, and does not yet have a proven thin-wrapper delegate use case. - S3 and S5 remain deferred. This decision narrows the practical Workspine subagent contract but does not close broad subagent orchestration parity or adapter research gaps. **Leverage:** - Lost: less flexibility for future agents to add delegates by symmetry or treat missing delegates as accidental gaps. - Kept: the two-layer role/delegate architecture, summaries-up/documents-to-disk, repo-native workflow state, lifecycle preflight, and write-set constraints. - Gained: a durable conservative rule that tells agents when subagents earn their keep and when they create hidden orchestration risk. **Evidence:** - `agents/README.md` - `agents/DISTILLATION.md` - `distilled/templates/delegates/` - `distilled/workflows/map-codebase.md` - `distilled/workflows/new-project.md` - GSD comparison source: `get-shit-done/workflows/new-project.md` and mapper/research workflows use `Task()` subagents heavily, but GSDD keeps the portable core single-agent-safe and only preserves subagent use where isolation, artifact persistence, or fresh-context review pays for the complexity. **Consequences:** - Future role, delegate, and workflow wording must distinguish read-only/artifact-backed delegation from implementation write ownership. - A roadmapper delegate must not appear by symmetry; it needs a future explicit design decision and regression updates. - Generated runtime freshness may propagate this wording, but generated freshness is not runtime parity proof. --- ## D62 - Repo-Native Browser Proof Contract **Decision (2026-04-28; revised 2026-05-09; revised 2026-07-08):** UI-sensitive work should carry a compact browser-proof declaration in plan frontmatter and, when executed, a plain markdown observation record that references artifacts by path or link while preserving the existing closure evidence kinds: `code`, `test`, `runtime`, `delivery`, and `human`. For live rendered UI proof, `agent-browser` is the default runtime evidence path for consumers, while existing Playwright tests remain the canonical repeatable browser-regression path when present. Direct phase verification treats `browser_proof_required` and `browser_proof_rationale` as the declaration authority and fails closed on missing phase prerequisites, invalid browser-proof frontmatter, a missing `## Browser Proof Plan` when proof is required, or a required browser-proof plan that omits route/state, viewport, runtime path, evidence kind, evidence command or no-command rationale, observations, artifacts with privacy/safety posture, and claim limit. **Context:** - Browser proof targets the recurring failure mode where agents claim a UI works or looks good without rendered proof, matched observations, or explicit human judgment. - The contract defines plan declarations, Browser Proof Plan sections, observation records, fail-closed agent guardrails, privacy/safety notes, and claim limits without adding a browser-provider framework or a separate JSON validator. - GSD's archived planner, executor, and verifier roles preserve strong lifecycle discipline, but they do not provide this UI-specific browser observation model. GSDD keeps the lifecycle leverage and adds a repo-native browser proof substrate without adding a browser-provider framework. - OneShot's QC guidance and Vercel's `agent-browser` skill converge on an interactive browser loop for snapshots, ref-based interaction, screenshots, and network/console-adjacent inspection. GSDD adapts that as a default workflow instruction, not as a hard validator dependency. **Decision:** - Planning must classify UI-sensitive work with `browser_proof_required: true|false` and a nonblank `browser_proof_rationale`. - Direct phase verification must read browser-proof declaration authority from plan frontmatter only. Body prose and stale sidecars are not declaration authority. - Direct phase verification must fail nonzero with structured blockers when no matching plan or summary exists, when browser-proof frontmatter is invalid, or when a required Browser Proof Plan is missing or incomplete. - When browser proof is not required and the rationale is explicit, stale browser-proof observations are warning-level cleanup signals, not proof and not blockers. Legacy `ui_proof_slots: []` with a meaningful `no_ui_proof_rationale` is treated as a compatibility warning rather than a blocker; legacy non-empty `ui_proof_slots` still require migration because required rendered proof cannot be inferred losslessly. - Browser Proof Plan sections record route/state, viewport coverage, runtime path, evidence kind, evidence command or narrowed no-command rationale, observations, artifacts, privacy/safety note, and claim limit. - Observation records record the exact plan artifact, actual route/state, viewport, runtime path, evidence kind, command/manual step, rendered observations, artifacts, result, privacy/safety note, stale-after trigger, and claim limit. - Browser Proof Plan sections must be tight enough for the plan checker to reject vague proof: specific route/state, viewport coverage or narrowed claim, runtime path, supported evidence kind, rendered observations, artifacts/privacy notes, evidence command or no-command rationale, and claim limit. - The planner chooses viewport coverage, but responsive or layout-sensitive claims require desktop/mobile or equivalent state coverage unless the claim is explicitly narrowed. - Execution defaults to `agent-browser` for live UI runtime proof: open the route/state, capture interactive snapshots/refs where relevant, exercise the changed flow, capture screenshots for planned viewport(s), and record relevant console/network observations. - Existing Playwright tests or package scripts remain the canonical repeatable browser-regression evidence when present. Playwright scripting is reserved for checks `agent-browser` cannot cover cleanly, such as JS-disabled behavior, structured console listeners, or multi-context testing. - Direct verification fails closed unless each required browser-proof plan has a repo-local, parser-compatible, explicitly passing observation that names the exact plan artifact and carries supported evidence semantics, privacy/safety posture, and bounded claim scope. The workflow verifier still owns substantive judgment about whether the recorded observation actually supports the route/state, viewport, artifact, and claim. - Human acceptance may close a narrowed claim and record proof debt, but it must not convert missing or mismatched non-human evidence into satisfied proof. - Screenshots, traces, videos, reports, accessibility scans, Gherkin, and visual diffs are artifact types or activities mapped onto the five existing evidence kinds, not new evidence kinds. - Source annotations, AST/cAST findings, semantic search hits, comments, and Semble-like retrieval may discover proof obligations, but they are discovery hints only and do not satisfy browser proof. - Visual taste, accessibility judgment, baseline acceptance, subjective polish/layout quality, and privacy publication require human evidence or explicit waiver, and human approval does not replace required `code`, `test`, `runtime`, or `delivery` evidence. - The current contract is validator-light by design: direct phase verification checks declaration shape, required Browser Proof Plan fields, observation record shape, safe linked-record boundaries, exact plan references, explicit pass/fail posture, supported evidence-kind labels, and bounded claim wording. It does not inspect raw screenshot pixels, report contents, or visual quality; substantive rendered proof remains a workflow/role obligation captured in summaries or observation records. - Failed browser proof is reported through the failure-cause names in `distilled/references/proof-rules.md`: product behavior defects, missing or blocked infrastructure, flaky harnesses, and ambiguous specs explain causes, but they do not add new evidence kinds. **Leverage:** - Lost: UI-sensitive work still carries a small proof-contract burden, and direct verification checks only shape rather than raw screenshot/report contents. - Kept: repo-native markdown artifacts, optional project tooling, fixed closure evidence kinds, generated-surface freshness, the plan/execute/verify separation, and a concrete live browser evidence path. - Gained: a much simpler consumer contract, exact claim-to-observation traceability, privacy/safety notes, claim limits, and fail-closed overclaim guardrails without a non-existent validator command. **Evidence:** - `distilled/templates/ui-proof.md` - `distilled/workflows/plan.md`, `distilled/workflows/execute.md`, `distilled/workflows/quick.md`, `distilled/workflows/verify.md` - `agents/planner.md`, `agents/executor.md`, `agents/verifier.md`, `distilled/templates/delegates/plan-checker.md` - `bin/lib/templates.mjs`, `bin/lib/health.mjs`, `bin/lib/phase.mjs`, `bin/lib/rendering.mjs` - `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.health.test.cjs`, `tests/gsdd.init.test.cjs` - GSD comparison: the upstream planner, executor, and verifier role patterns preserve lifecycle rigor, but they do not define browser-proof plan declarations or observation records. - OneShot QC source: `https://github.com/oneshot-repo/OneShot/tree/main/skills` - Vercel `agent-browser` docs: `https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/SKILL.md` and `https://agent-browser.dev/snapshots` - Playwright docs: `https://playwright.dev/docs/trace-viewer`, `https://playwright.dev/docs/next/screenshots`, and `https://playwright.dev/mcp/tools/tracing` - Chrome DevTools for agents/MCP docs: `https://developer.chrome.com/docs/devtools/agents` and `https://developer.chrome.com/blog/chrome-devtools-mcp?hl=en` - Harness and UI-agent pitfall sources: `https://www.anthropic.com/engineering/harness-design-long-running-apps`, `https://www.huuhka.net/browser-verification-for-coding-agents-chrome-devtools-mcp-vs-agent-browser/`, `https://www.developersdigest.tech/blog/long-running-agents-need-harnesses`, `https://codemyspec.com/blog/agentic-qa-verification`, `https://dev.to/ratikkoka/your-ui-is-invisible-to-ai-agents-heres-how-to-fix-it-1ib3`, `https://dev.to/louaiboumediene/the-ai-harness-why-your-ai-coding-agent-is-only-as-smart-as-the-repo-you-put-it-in-cml`, and `https://tessl.io/blog/webmcp-making-web-apps-faster-and-cheaper-for-ai-agents/` - OpenSpec docs: `https://openspec.dev/` - LeanSpec docs: `https://www.lean-spec.dev/docs/guide/first-principles` - OpenAI Codex docs: `https://help.openai.com/en/articles/11369540-codex-in-chatgpt` - Anthropic Agent Skills docs: `https://docs.claude.com/en/docs/agents-and-tools/agent-skills` - GitHub Copilot customization docs: `https://docs.github.com/en/copilot/concepts/prompting/response-customization` **Consequences:** - Future UI-related phases must not add new evidence kinds by treating artifact types as proof categories. - Future dogfood or runtime validation must not upgrade artifact counts or human waivers into proof. - Generated runtime surfaces and local templates must stay freshness-checkable through `gsdd update --templates` and health diagnostics. - Future provider/tooling work must not make `agent-browser` a required validator field without a separate product decision; the current contract makes it the default workflow path, not a schema lock. ## D63 - Computed-First Control Map **Decision (2026-05-08; revised 2026-05-09):** Long-running multi-agent and multi-worktree control uses a computed-first `gsdd control-map` helper rather than a new lifecycle workflow or a vendor session parser. The helper computes repo/worktree/planning truth live and overlays optional local annotations only for intent that git cannot know. **Context:** - Gap I52 showed that ordinary `git status` can be clean while sibling worktrees, detached runtime worktrees, ignored/generated surfaces, snapshots, dirty local WIP, and cleanup obligations remain unexplained. - Gap I54 showed that repeated subagent swarms can become a substitute for shared state when there is no one-screen control map for active branches, ownership, proof state, and cleanup debt. - Current runtime research shows the only portable cross-vendor coordination layer is repo artifacts plus generated workflow entrypoints. Claude, OpenCode, Codex, Cursor, Copilot, and Gemini do not expose one uniform authoritative session/worktree store. - Current harness guidance favors structured handoff artifacts, worktree isolation, evaluator loops, approval gates around side effects, and browser/runtime evidence. Those ideas fit Workspine only if repo truth remains primary and vendor adapters stay thin. **Decision:** - Add `gsdd control-map [--json] [--with-ignored] [--annotations ]` to the main CLI and generated `.planning/bin/gsdd.mjs` helper runtime. - Add `gsdd control-map annotate set|clear` as the minimal mutation surface for local annotation intent. `set` creates or updates workspace-local annotation files with live branch/head snapshots, normalized write sets, cleanup state, owner/scope/next-step metadata, and stale-update refusal unless `--refresh` is explicit. `clear` removes an annotation by id or path, including stale or missing-worktree entries, without deleting branches, pruning worktrees, or cleaning files. - Add `gsdd closeout-report [--json] [--phase ]` as a read-only replay helper over the same local-state authority. It defaults to the latest completed phase and reports blockers, warnings, next safe action, control-map status, health/preflight status, direct phase verification, and UI-proof status without mutating ROADMAP status, fingerprints, annotations, branches, worktrees, generated surfaces, release state, or report files. - Compute authority from live git/worktree state first: canonical checkout, branch, HEAD, upstream divergence when comparable, tracked/untracked dirty buckets, optional ignored-path scans through `--with-ignored`, sibling git worktrees, detached/bare state, invalid git access, planning drift, checkpoint existence, lifecycle state, and repo-local runtime worktree directories. - Read optional annotations from `.planning/.local/control-map.annotations.json`. Annotations may record `runtime_owner`, intended scope, write set, cleanup state, next step, branch, last known head, and update timestamp. - Treat annotations as stale-checkable intent only. They never outrank repo truth, planning artifacts, or checkpoint reconciliation. - Emit explicit transition-risk semantics from computed truth: concrete annotation write-set overlap, live dirty-path/write-set overlap, upstream divergence, detached candidate worktrees, stale annotation mismatches, and tracked dirty canonical work behind upstream. Only concrete block-level risks should stop owned-write lifecycle transitions; ordinary dirty or detached local state remains warning-level guidance. - Keep transcript/session stores out of the helper. Vendor session evidence may support postmortems, but it is not live product truth. - Wire the control map into portable workflow behavior by having `progress`, `resume`, `pause`, `quick`, `plan`, and `execute` consult it when available. This is guidance plus deterministic helper output, not a new workflow lane. **Leverage:** - Lost: a pure zero-file model cannot preserve non-computable intent such as owner/runtime, intended scope, and cleanup obligation. - Kept: Workspine remains a lightweight repo-native spine; no new lifecycle workflow, no dashboard/control plane, no vendor session authority, and no change to the five evidence kinds. - Gained: agents can explain "clean" precisely across tracked, untracked, sibling, detached, stale, and annotated state by default, and across ignored/generated local surfaces when the caller requests the explicit `--with-ignored` scan before planning, execution, resume, cleanup, or milestone continuation. Owned-write preflight can also consume the same computed risk output, operators can update stale-aware local intent without hand-editing JSON, and closeout replay can join existing verification signals into one typed report without inventing a branch lease, control plane, or cleanup workflow. **Evidence:** - `bin/lib/control-map.mjs`, `bin/lib/closeout-report.mjs`, `bin/lib/health.mjs`, `bin/lib/phase.mjs`, `bin/lib/init-runtime.mjs`, `bin/lib/lifecycle-preflight.mjs`, `bin/gsdd.mjs`, `bin/lib/rendering.mjs` - `distilled/workflows/progress.md`, `resume.md`, `pause.md`, `quick.md`, `plan.md`, `execute.md` - `tests/gsdd.control-map.test.cjs`, `tests/gsdd.closeout-report.test.cjs`, `tests/gsdd.health.test.cjs`, `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs` - `.internal-research/gaps.md` Gap I52 and Gap I54 - `.internal-research/lessons-learned.md` entries on multi-worktree registry, clean-vs-editor-visible noise, checkpoint/worktree truth split, and subagent stop conditions - GSD comparison: upstream GSD preserves lifecycle rigor but does not define a vendor-agnostic computed worktree/control-map helper. - OpenSpec comparison: OpenSpec optimizes change-level speed and archive flow, but does not own long-running multi-worktree local-state reconciliation as a portable harness surface. - Harness sources: `https://www.anthropic.com/engineering/harness-design-long-running-apps`, `https://code.claude.com/docs/en/worktrees`, `https://developers.openai.com/codex/cloud`, `https://developers.openai.com/api/docs/guides/agents/orchestration`, `https://developers.openai.com/api/docs/guides/agents/guardrails-approvals`, `https://developers.openai.com/api/docs/guides/agent-evals`, `https://docs.github.com/en/copilot/concepts/agents/cloud-agent/about-cloud-agent`, `https://agent-browser.dev/sessions`, and `https://developer.chrome.com/docs/devtools/agents`. **Consequences:** - Future cleanup, resume, and parallel-worktree work should start from `gsdd control-map --json` rather than repeated ad hoc repo audits; use `--with-ignored` before making a clean-workspace claim that includes ignored or generated surfaces. - Annotation mutation is intentionally confined to `control-map annotate`; ordinary `control-map` reads remain computed-first and safe to call from status surfaces. - Lifecycle preflight may consume block-level control-map risks for owned-write transitions, but read-only status surfaces must not turn warning-level local state into blockers. - `closeout-report` is a compact replay/report helper, not `progress`, `verify`, milestone audit, release automation, cleanup, or a dashboard. The source CLI path includes full health diagnostics; the generated helper reports health availability as a typed warning if the full health builder is not present in that helper runtime. - Future health hardening can consume the same helper output for stricter reporting, but must avoid turning local annotations into product truth. ## D64 - Work-Native Continuity Authority **Decision (2026-06-29; revised 2026-06-30):** `.work` becomes the canonical continuity surface for `gsdd next` and future work-native state, while `.planning` remains readable legacy lifecycle input during migration and for existing workflows that still own their write paths. The authority used by routing, preflight, verification, and auto-gate packets must be explicit in machine-readable output. Repo policy, not Workspine itself, decides whether `.work` is committed or local-only; in the Workspine framework repo, `.work` is local dogfood/runtime state and should not be tracked. During migration, `gsdd next` may also route existing `.planning` brownfield-change authority into `gsdd-plan` without treating `.planning` ROADMAP phases as the only valid plan target. **Context:** - PR #116 merged the first `gsdd next` / `.work` continuity slice, but the framework repo still had split truth: `.work/milestone` described a locally implemented continuity milestone while `.planning` still described v2.0.0 parallel orchestration and P65/P66. - Old v2.0.0 parallel orchestration is too distant to migrate wholesale. Its useful ideas are partial extraction candidates: write ownership and closeout truth gates move into work-native auto-gate safety now; the PR #113 registry material remains parked for later extraction or rescue. - OpenSpec's change/archive model and LeanSpec's compact spec guidance both reinforce that long-lived state needs clear ownership and small, reviewable truth surfaces rather than scattered status prose. - The cited OpenAI and Anthropic agent-orchestration guidance favors manager-owned orchestration, explicit handoffs, guardrails, evaluator loops, and bounded tool authority rather than an unbounded agent loop. - MCP and agent-tooling security guidance reinforce that tool/resource outputs and local memory surfaces are untrusted inputs unless their provenance, privacy posture, and authority boundary are explicit. **Decision:** - Treat `.work` as the source of truth for `gsdd next` continuity routing, focus packets, work-native milestone state, decisions, questions, evidence pointers, dogfood findings, and bounded auto-gate state. - Keep `.planning` readable as legacy lifecycle input. Existing `gsdd-plan`, `gsdd-execute`, `gsdd-verify`, audit, complete-milestone, phase-status, and helper write paths continue to work against `.planning` until each surface is deliberately bridged or migrated. - Require routing and preflight output to report authority explicitly, using scoped values such as `work_milestone`, `planning`, or `blocked/conflict`; `.work` authority must not silently mask repo truth, PR truth, or unrelated `.planning` blockers. - Include `brownfield_change` as an explicit scoped authority for existing bounded-change artifacts. This is a compatibility bridge, not a new lifecycle root: it reuses the current `gsdd-plan` workflow and the brownfield-change folder contract. - Preserve repo/control-map truth as the highest authority for branch, PR, worktree, dirty-state, and delivery claims. `.work` can carry intent and continuity; it cannot convert local prose into integrated repo truth. - Define execute-until-gate as task-bounded automation, not session-bounded autonomy. Auto mode may run typed, reviewed, `type=auto` tasks and bounded verification/repair cycles only until a human gate, verification gap, repeated blocker, authority conflict, trust boundary, or scope expansion stops it. - Keep milestone completion user-owned. `gsdd next` may route to completion approval, but it must not mark a milestone complete autonomously. - Treat `.work` tracking as repo policy. Consumer projects may commit `.work` if that fits their privacy and collaboration model. The Workspine framework repo keeps `.work` local-only because it is dogfooding its own runtime state while developing the framework. - Reframe the old v2.0.0 parallel-orchestration milestone as legacy input rather than the active next milestone. Preserve write-set ownership and closeout truth gates in the new work-native authority milestone; park PR #113/P65 registry material as extract-later. **Leverage:** - Lost: the old clean "v2.0.0 parallel PR orchestration next" story and the convenience of treating `.planning` as the only lifecycle state root. - Kept: repo-native files, plain markdown workflow contracts, existing `.planning` compatibility, computed-first control-map authority, plan/execute/verify separation, and human-owned completion. - Gained: a clear continuity authority for `gsdd next`, explicit migration semantics, safer execute-until-gate foundations, repo-policy-driven tracking, a brownfield compatibility bridge for bounded consumer changes, and a typed authority boundary that prevents future auto mode from running on stale or contradictory state. **Evidence:** - `bin/lib/next.mjs`, `bin/lib/work-context.mjs`, `bin/lib/lifecycle-preflight.mjs` - `tests/gsdd.next.test.cjs` and `tests/phase.test.cjs` - `README.md` for the public `.work` tracking policy - PR #116, merged 2026-06-29 with merge commit `b91a138c42f2ab3ff7376317031208c7a716decd`: `https://github.com/PatrickSys/workspine/pull/116` - PR #113, still open as the parked registry extraction candidate: `https://github.com/PatrickSys/workspine/pull/113` - GSD comparison sources: `agents/_archive/gsd-roadmapper.md`, `agents/_archive/gsd-planner.md`, `agents/_archive/gsd-executor.md`, and `agents/_archive/gsd-verifier.md`. These preserve lifecycle rigor around requirements, plans, state, execution, and verification, but they do not define a separate work-native `next` authority root; GSDD preserves the rigor while moving agent-facing continuity into `.work`. - OpenSpec docs: `https://openspec.dev/` - LeanSpec docs: `https://www.lean-spec.dev/docs/guide/first-principles` - OpenAI Agents SDK orchestration docs: `https://developers.openai.com/api/docs/guides/agents/orchestration` - OpenAI guardrails and approvals docs: `https://developers.openai.com/api/docs/guides/agents/guardrails-approvals` - OpenAI agent evals docs: `https://developers.openai.com/api/docs/guides/agent-evals` - Anthropic agent engineering guidance: `https://www.anthropic.com/engineering/building-effective-agents` - Anthropic long-running harness guidance: `https://www.anthropic.com/engineering/harness-design-long-running-apps` - Model Context Protocol security guidance: `https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices` - GitHub Copilot repository instructions docs: `https://docs.github.com/en/copilot/concepts/prompting/response-customization` **Consequences:** - Future `gsdd next` and auto-gate work should start by reconciling `.work`, `.planning`, repo/control-map, PR truth, and active brownfield-change authority into one conservative next action or one explicit blocker. - Future milestones must not say "P65 shipped, start P66" unless repo, PR, `.work`, and legacy `.planning` truth agree. - Future auto mode must expose typed gates, loop guards, evidence requirements, stop reasons, and authority source in JSON. It must never rely on prose such as "continue autonomously" as execution permission. - Future framework work should not add tracked `.work` runtime state by default. Durable product changes belong in source/design/workflow/test files; `.work` dogfood state remains local unless explicitly promoted. --- ## Maintenance This document is updated when: - A design decision is revised or reversed (update the relevant section, note the change) - A new structural decision lands that affects how GSDD diverges from GSD (add a new section) - Evidence is found that contradicts a stated rationale (update or remove the claim) Do not add speculative decisions. Every section must cite implementation artifacts (files, PRs, tests) and at least one GSD source file for comparison.