gsdd-cli 0.3.1 → 0.18.0

package/distilled/EVIDENCE-INDEX.md

@@ -0,0 +1,402 @@
+# GSDD Evidence Index
+
+> One-line-per-source mapping of every design decision to its primary evidence.
+> Extracted from inline **Evidence** sections in `distilled/DESIGN.md`.
+> Updated when a decision is added or revised.
+> Guarded by G31 in `tests/gsdd.guards.test.cjs`.
+
+---
+
+## D1 — 4-File Codebase Standard
+- `agents/_archive/gsd-codebase-mapper.md` lines 72-79 (GSD 7-file model)
+- `agents/mapper.md` (GSDD 4-file standard)
+- `.planning/SPEC.md` "Lean Context Decision" section
+- Liu et al. "Lost in the Middle: How Language Models Use Long Contexts" (NeurIPS 2023) — position-dependent recall supports minimal stable context footprint
+- 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
+
+## D2 — Agent Consolidation: 11 to 10
+- `agents/_archive/` (11 original GSD files, git history via `git mv`)
+- `agents/` + `agents/README.md` (10 canonicals, lifecycle table)
+- `agents/README.md` lifecycle table (canonical-to-GSD source mapping)
+- CrewAI role-based team patterns, Microsoft AutoGen hierarchical agents, LangGraph multi-agent subgraphs (validate role specialization; specific count of 10 is engineering judgment)
+
+## D3 — Two-Layer Architecture: Roles and Delegates
+- `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` (role file existence and delegate-role reference validation)
+- All 10 delegate files in `distilled/templates/delegates/`
+- Jensen & Meckling "Theory of the Firm" (Journal of Financial Economics 1976) — principal-agent delegation contracts
+- Gamma et al. GoF Strategy Pattern ("Design Patterns" 1994) — separating algorithm definition from usage context
+- LangGraph multi-agent subgraphs + Microsoft AutoGen hierarchical agents (production validation of two-layer separation)
+
+## D4 — Zero-Hop Security Propagation
+- `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)
+- OWASP Top 10 for LLM Applications v2.0 (2025) — LLM01 (Prompt Injection) + LLM07 (System Prompt Leakage) support embedding security rules at the role-contract level
+- Greshake et al. "Not What You've Signed Up For" (IEEE S&P 2023) — indirect prompt injection validates defense-in-depth at the agent-contract layer
+- Saltzer & Schroeder "Protection of Information in Computer Systems" (1975) — complete mediation principle
+
+## D5 — Conditional Synthesizer
+- `get-shit-done/workflows/new-project.md` lines 708-729 (GSD always-spawn synthesizer)
+- `distilled/templates/delegates/researcher-synthesizer.md`
+- `agents/synthesizer.md` (cross-reference algorithm)
+- `.planning/config.json` `researchDepth` field contract
+- LangGraph conditional edges — adaptive agent invocation based on workflow state
+- Asai et al. "Self-RAG: Learning to Retrieve, Generate, and Critique through Self-Reflection" (ICLR 2024) — conditional retrieval/synthesis based on need
+- Anthropic "Building effective agents" (Dec 2024) — routing workflows match task complexity to agent selection
+
+## D6 — Mapper Staleness: Standalone Workflow
+- `get-shit-done/workflows/map-codebase.md` lines 35-62 (GSD staleness check with 3 options)
+- `get-shit-done/workflows/new-project.md` lines 61-80 (brownfield offer delegates to map-codebase)
+- `distilled/workflows/map-codebase.md` (standalone, re-runnable)
+- `distilled/workflows/new-project.md` (auto-invoke for brownfield via skill reference)
+- Aider (aider.chat) — dynamic tree-sitter-based repo maps generated on-demand (validates freshness-over-cache approach)
+- Cursor — continuous background indexing (cached approach; shows both are production-valid tradeoffs)
+
+## D7 — Milestone Hierarchy and Phase Continuation
+- `get-shit-done/workflows/new-milestone.md` lines 101-173 (milestone-aware researchers)
+- `get-shit-done/workflows/new-milestone.md` line 269 (phase numbering continuation)
+- `distilled/README.md` lifecycle diagram
+- `.planning/SPEC.md` "Long-Term Lifecycle" section
+- Erol, Hendler & Nau / Nau et al. Hierarchical Task Networks (JAIR 2003) — foundational milestone→phase→task decomposition in AI planning
+- PMI PMBOK Work Breakdown Structure (WBS) standard — industry-standard phase/task hierarchy
+- Khot et al. "Decomposed Prompting" (ICLR 2023) — task decomposition improves LLM performance on multi-step work
+
+## D8 — Advisory Git Protocol
+- `agents/_archive/gsd-executor.md` (mandatory commit in algorithm, TDD flow)
+- `agents/executor.md` lines 57-64 (Git Guidance — repo-native, advisory)
+- Industry consensus: Aider, GitHub Copilot, Cursor, Codex CLI, OpenCode — all treat git as advisory/user-configured; no major AI coding tool enforces a specific commit or branch convention
+
+## D9 — Adapter Generation Over Conversion
+- `get-shit-done/install.js` (GSD converter with per-runtime conversion logic)
+- `get-shit-done/workflows/new-project.md` (851 lines, 10+ AskUserQuestion calls, 7 Task() calls)
+- `bin/gsdd.mjs` (thin CLI entrypoint and adapter dispatcher)
+- `bin/adapters/` (vendor-specific adapter generation)
+- `distilled/templates/delegates/plan-checker.md` (single payload source for native checker generation)
+- `.planning/SPEC.md` "Agent Integration Strategy" section
+- AGENTS.md Linux Foundation standard: agents.md
+
+## D10 — Context Isolation: Summaries Up, Documents to Disk
+- `get-shit-done/workflows/new-project.md` lines 544-706 (4 researchers write to files, return summaries)
+- All 9 delegate files (return format instructions)
+- `agents/synthesizer.md` (reads full research files from disk)
+- Anthropic Agent Teams (Feb 2026): "Shared State, Not Shared Context"
+- AI21 Modular Intelligence (Feb 2026): orchestrator-based designs prevent context drift
+
+## D11 — Quick-Work Lane
+- `get-shit-done/workflows/quick.md` (454 lines, two modes, STATE.md tracking)
+- `distilled/workflows/quick.md` (~120 lines, single mode, LOG.md tracking)
+- Crystal Clear (Cockburn 2004) — ceremony scales with team size and criticality; lightweight methods prescribed for small/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 task complexity
+
+## D12 — Session Persistence Without State File
+- `get-shit-done/workflows/pause-work.md` (123 lines, phase-scoped checkpoint)
+- `get-shit-done/workflows/resume-project.md` (307 lines, STATE.md-dependent)
+- `get-shit-done/workflows/progress.md` (382 lines, gsd-tools.cjs-dependent)
+- `distilled/workflows/pause.md`, `distilled/workflows/resume.md`, `distilled/workflows/progress.md`
+- `.internal-research/gsd-distilled-audit-13th-march-2026.md` — Highest-ROI recommendation #3
+
+## D13 — Mechanical Invariant Enforcement
+- `tests/gsdd.invariants.test.cjs` lines 1015+ (6 suites, ~106 assertions)
+- OpenAI Harness Engineering blog (Feb 2026): "error messages as enforcement mechanism"
+- External audit (2026-03-13): recommendation #4 "Mechanize the framework's invariants"
+- PRs #20-23: orphan `</output>` tags survived 4 manual review cycles before G4 caught them
+
+## D14 — Headless Mode
+- `get-shit-done/workflows/new-project.md` lines 9-40 (GSD headless predecessor)
+- Claude Code: `-p` flag for headless execution (docs.anthropic.com)
+- Codex CLI: `--quiet` and `--auto-edit` flags (developers.openai.com/codex/cli/reference)
+- Cline CLI 2.0: explicit headless CI/CD mode (devops.com, 2025)
+
+## D15 — Model Profile Propagation
+- `get-shit-done/references/model-profiles.md` + `model-profile-resolution.md` (GSD reference)
+- OpenSpec: portable spec core is tool-agnostic (openspec.dev)
+- Claude Code: `model:` field with aliases (docs.anthropic.com/en/docs/claude-code/sub-agents)
+- OpenCode: `model:` in agent frontmatter (opencode.ai/docs/agents)
+- Agent Skills standard: no `model:` field in spec (agentskills.io/specification)
+
+## D16 — Template Versioning via Generation Manifest
+- `get-shit-done/install.js` lines 1227-1327 (SHA-256 manifest + backup directory)
+- OpenSpec: managed blocks with bounded upsert (openspec.dev)
+- Angular/Turborepo/Next.js: ordered migrations with dry-run preview
+- Langfuse: generation/prompt versioning with hash-based change detection (langfuse.com/docs/prompts)
+
+## D17 — CLI Composition Root Boundary
+- `get-shit-done/install.js` (GSD monolithic install/conversion surface)
+- `bin/gsdd.mjs`, `bin/lib/init.mjs`, `bin/lib/templates.mjs`, `bin/lib/models.mjs`
+- `tests/gsdd.init.test.cjs`, `tests/gsdd.models.test.cjs`, `tests/gsdd.manifest.test.cjs`
+- Seemann "Dependency Injection in .NET" (Manning 2011) — named "Composition Root" pattern
+- Martin "Clean Architecture" (2017) — main component as the outermost wiring layer
+- Standard pattern in oclif, Commander.js, yargs, Cobra CLIs
+
+## D18 — Codex CLI Native Adapter
+- OpenAI Codex CLI docs: developers.openai.com/codex/subagents
+- Codex CLI v0.115.0 release notes: github.com/openai/codex/releases/tag/rust-v0.115.0
+- Agent Skills standard: developers.openai.com/codex/skills
+- `bin/adapters/codex.mjs` (implementation)
+- Live validation fixtures (2026-03-17): 3 Codex test runs confirming happy path, revision, max-3 escalation
+
+## D19 — Scenario-Based Eval Coverage
+- 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)
+- `tests/gsdd.scenarios.test.cjs` (S1–S5, ~37 assertions)
+
+## D20 — Workspace Health Diagnostics
+- `get-shit-done/workflows/health.md` (157 lines, GSD predecessor)
+- OpenAI Harness Engineering (Feb 2026): error messages as enforcement mechanism
+- External audit (2026-03-13): recommendation #3 "Add just enough: status/resume/progress/health"
+- `bin/lib/health.mjs`, `tests/gsdd.health.test.cjs`, `tests/gsdd.guards.test.cjs` (G14)
+
+## D21 — OWASP Authorization Matrix
+- OWASP Authorization Testing Automation Cheat Sheet: pivot-format matrix standard
+- OWASP Top 10 for Agentic Applications 2026: A1 Agent Overreach, A4 Insufficient Authorization
+- External audits (2026-03-13, 2026-03-17): independently flagged auth verification gap
+- `distilled/templates/auth-matrix.md`, `agents/integration-checker.md` (Step 4a)
+
+## D22 — Delegate Layer Architecture
+- Anthropic multi-agent guidance: orchestration patterns with isolated sub-agents
+- OpenAI Harness Engineering (2026): delegate pattern for reusable sub-agent behavior
+- OpenDev "Terminal Agents" (arXiv 2603.05344): multi-agent coordination with explicit role contracts
+- `distilled/templates/delegates/` (11 delegate files)
+- `distilled/workflows/*.md` (`<delegate>` blocks)
+
+## D23 — Mapper Output Quantification
+- `ideas.md` (internal, Feb 2026): direct per-tool comparison — "84% declining > uses constructor injection"
+- ArXiv 2602.20478 (Codified Context): structured quantifiable facts enable JIT context loading
+- GetDX measurement framework (2026): adoption % as primary signal for convention strength
+- Anthropic 2026 Agentic Coding Trends: context quality as primary competitive advantage
+- `distilled/templates/codebase/conventions.md`, `distilled/templates/delegates/mapper-quality.md`
+
+## D24 — Consumer Governance Completeness
+- Anthropic "Effective harnesses for long-running agents" (2026): incomplete maps cause agent failure
+- Agent Skills specification (agentskills.io): progressive disclosure requires complete top-level map
+- HumanLayer "Skill Issue" (2026): AGENTS.md should be a complete capability map
+- External audits (2026-03-13, 2026-03-17): documentation accuracy as top adoption blocker
+- `distilled/templates/agents.block.md`, `tests/gsdd.guards.test.cjs` (G18)
+
+## D25 — Consumer First-Run Experience
+- Anthropic harness engineering (2025-2026): "honest constraints over vague prompting"
+- OpenAI Codex skills documentation: clear per-platform invocation patterns
+- Both GSDD external audits (2026-03-13, 2026-03-17): "architecture solid, presentation lags"
+- `README.md`, `distilled/templates/agents.block.md`, `bin/lib/init.mjs`, `tests/gsdd.guards.test.cjs` (G19)
+
+## D26 — Session Continuity Contract Hardening
+- Anthropic "Effective harnesses for long-running agents" (2026): artifact-based session handoff
+- GitHub "How to build reliable AI workflows with agentic primitives" (2026): session splitting
+- OpenAI harness engineering (2026): incremental progress tracking is the key multi-session mechanism
+- OpenDev terminal agents (arXiv 2603.05344): runtime state must be derivable from artifacts
+- `distilled/workflows/pause.md`, `distilled/workflows/resume.md`, `distilled/workflows/progress.md`
+- `tests/gsdd.guards.test.cjs` (G20)
+
+## D27 — Consumer-Ready Surface Completion
+- External audit (2026-03-13): "architecture solid, presentation lags implementation"
+- External audit (2026-03-17): "consumer surface identified as #1 bottleneck"
+- External audit (2026-03-18): "docs should close the consumer journey"
+- `README.md` (6 new subsections), `tests/gsdd.guards.test.cjs` (G21)
+
+## D28 — Workflow Completion Routing
+- Consumer audit (2026-03-21): "agent never proactively suggested the next GSDD command"
+- `get-shit-done/workflows/progress.md` (GSD "Next Up" block pattern)
+- Anthropic "Building effective agents" (2025): explicit handoff points with clear next actions
+- `distilled/workflows/*.md` (9 `<completion>` sections), `tests/gsdd.guards.test.cjs` (G22)
+
+## D29 — Approach Exploration
+- Anthropic "Building effective agents" (2025): sub-agents return condensed summaries
+- LangChain "Context Engineering for Agents" (2025): Write/Select/Compress/Isolate patterns
+- `get-shit-done/workflows/discuss-phase.md` (gray area identification, GSD source)
+- `get-shit-done/workflows/list-phase-assumptions.md` (5-dimension assumption surfacing)
+- `get-shit-done/workflows/discovery-phase.md` (3-level research workflow)
+- `agents/approach-explorer.md`, `distilled/templates/delegates/approach-explorer.md`
+
+## D30 — Hardening Propagation
+- D28 consumer audit (2026-03-21): persistence failures at every workflow boundary
+- Huang et al. "LLMs Cannot Self-Correct Reasoning Yet" (ICLR 2024): LLMs need external feedback
+- Kamoi et al. "When Can LLMs Actually Correct Their Own Mistakes?" (TACL 2024): self-correction requires reliable external feedback
+- Anthropic long-context research (2024): instructions at decision points followed more reliably
+- `distilled/workflows/quick.md`, `distilled/workflows/map-codebase.md`, `tests/gsdd.guards.test.cjs` (G24)
+
+## D31 — Outcome Dimension for Plan-Checker
+- Yu et al. "Outcome-Refining Process Supervision for Code Generation" (ICML 2025): +26.9% correctness with hybrid process+outcome supervision
+- Rajan "Multi-Agent Code Verification via Information Theory" (2025): diminishing returns plateau at 4-7 dimensions
+- Lightman et al. "Let's Verify Step by Step" (ICLR 2024): process supervision significantly outperforms outcome-only
+- `distilled/templates/delegates/plan-checker.md` (`goal_achievement` dimension)
+
+## D32 — Quick Workflow Alignment Hardening
+- Risk-adaptive autonomy pattern (AWS, Azure, Anthropic 2025-2026): confirmation gates scale with consequence
+- Anthropic agent autonomy research (2026): human-on-the-loop > human-in-the-loop
+- Madaan et al. "Self-Refine" (NeurIPS 2023): 1 revision cycle captures most improvement
+- `distilled/workflows/quick.md` (Steps 3.5-3.7), `tests/gsdd.guards.test.cjs` (G24)
+
+## D33 — Quick Approach Clarification
+- Anthropic "Measuring AI agent autonomy in practice" (2025): Claude asks 2x+ on complex tasks
+- Knight First Amendment Institute "Levels of Autonomy for AI Agents" (2025): 5-level autonomy spectrum
+- Anthropic "Framework for safe and trustworthy agents" (2025): recommendation-first framing
+- Martin Fowler "Humans and Agents in SE Loops" (2025): HOTL > HITL
+- `distilled/workflows/quick.md` (Step 2.5), `tests/gsdd.guards.test.cjs` (G24)
+
+## D34 — Context Engineering Applied to Quick Workflow
+- Anthropic Claude Prompting Best Practices: XML tags for semantic structure and attention
+- Selective Prompt Anchoring (arXiv 2408.09121, 2024): up to 12.9% Pass@1 improvement from strategic anchoring
+- `agentskit-architect SKILL.md` (prompty): identical hybrid XML-outer/markdown-inner structure
+- `distilled/DESIGN.md` (DISTILLATION.md authority language resolution)
+- `distilled/workflows/quick.md` (`<anti_patterns>` section, STOP normalization)
+
+## D35 — Skills-Native Runtimes vs Governance Adapters
+- Live consumer testing (2026-03-20): Cursor and Copilot auto-discover `.agents/skills/`
+- User-performed live validation (2026-03-25): Gemini confirms same behavior
+- `bin/lib/init.mjs` (adapter registry and root-governance generator)
+- `README.md`, `distilled/templates/agents.block.md`, `tests/gsdd.guards.test.cjs`
+
+## D36 — Interactive Init Wizard
+- `bin/lib/init.mjs` existing adapter-selection seam
+- Local research on adjacent `prompty` repo: portable skills as primary install surface
+- Repo lesson LL-INSTALL-DX-BEFORE-ALIAS-CLEANUP (lessons-learned.md)
+- `bin/lib/init.mjs`, `bin/gsdd.mjs`, `tests/gsdd.init.test.cjs`
+- npm init, Vite `create-vite`, Next.js `create-next-app`, Angular CLI `ng new`, Astro `create astro` — all use TTY-interactive wizard with headless flags (industry standard for project scaffolding)
+
+## D37 — Mutability-Driven Workflow Classification
+- `distilled/workflows/verify.md`, `new-project.md`, `audit-milestone.md`, `pause.md`, `resume.md` (all require artifact writes)
+- `distilled/workflows/progress.md` (only read-only workflow)
+- Consumer audit: verification reports lost when persistence skipped
+- `bin/gsdd.mjs`, `bin/lib/rendering.mjs`, `tests/gsdd.guards.test.cjs` (G27)
+- Meyer's Command-Query Separation (CQS, "Object-Oriented Software Construction" 1988) — classify operations by mutation behavior, not semantic category
+- Greg Young's CQRS (2010) — CQS applied at the architectural level
+- Unix rwx model + AWS IAM / Kubernetes RBAC — classify by mutation semantics as industry norm
+
+## D38 — Retroactive Artifact Enforcement
+- `.internal-research/gaps.md` I27 entry (two occurrences, root-cause analysis, close conditions)
+- `distilled/workflows/execute.md` (D28 SUMMARY.md persistence gate)
+- `distilled/workflows/verify.md` (D28 VERIFICATION.md persistence gate + D28/G30 ROADMAP closure)
+- `distilled/workflows/audit-milestone.md` (retroactive artifact completeness check)
+- `.internal-research/strategy.md` (kernel simplicity vs policy depth trade-off)
+- `tests/gsdd.guards.test.cjs` (G30 guard for ROADMAP closure on pass)
+- NIST SP 800-53 Rev. 5 (2020) — detective vs preventive controls as equally valid risk-management strategies
+- ISO 27001 risk treatment — choice of detective vs preventive depends on cost/complexity tradeoff
+- Reason's Swiss Cheese model (1990) — layered defense where retroactive audit catches what preventive layers miss
+
+## D39 — Brownfield Entry Wiring
+- User brownfield audit finding (2026-03-20): map-codebase was useful but not presented as the start of a lightweight feature-work lane
+- Existing quick-workflow hardening decisions D32-D34: quick already had alignment and scope controls, so the open gap was routing/context, not quick quality
+- `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
+- Phase 7 continuity review across all 14 workflow files: durable artifacts and live-state artifacts were present, but compressed judgment was not explicitly modeled
+- D12 and D26: artifact/state continuity existed already, but without a named three-layer boundary
+- `.planning/SPEC.md` (Continuity Layers constraint, Key Decisions row)
+- `distilled/workflows/resume.md` (first workflow adopting the boundary directly)
+
+## D41 — Compressed Judgment Persistence Surface
+- Phase 8 review of `plan.md`, `execute.md`, `verify.md`, and `resume.md` as the four judgment-recovery entry points
+- `distilled/workflows/pause.md` (checkpoint `<judgment>` write)
+- `distilled/workflows/execute.md` (`SUMMARY.md` `<judgment>` write and prior-summary read)
+- `distilled/workflows/plan.md`, `distilled/workflows/verify.md`, `distilled/workflows/resume.md` (judgment reads)
+- `.planning/SPEC.md` (Key Decisions row)
+
+## D42 — Session-Boundary Safety
+- `distilled/workflows/resume.md` (`.continue-here.bak` retained across dispatch)
+- `distilled/workflows/plan.md`, `distilled/workflows/execute.md`, `distilled/workflows/verify.md`, `distilled/workflows/quick.md` (fallback `.bak` judgment reads)
+- `distilled/workflows/pause.md` (stale `.bak` crash-cleanup path)
+- `tests/gsdd.guards.test.cjs`, `tests/gsdd.invariants.test.cjs`
+
+## D43 — Resume Provenance Truth Split
+- `.internal-research/gaps.md` (`I29`, `I30`)
+- `.internal-research/TODO.md` (stale checkpoint/worktree drift notes)
+- `.internal-research/consumer-audits/worktree-provenance-and-checkpoint-drift-2026-04-12.md`
+- `distilled/workflows/pause.md`, `distilled/workflows/resume.md`
+- `bin/lib/provenance.mjs`
+- `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.invariants.test.cjs`
+
+## D44 — Warning-First Transition Safety And Fail-Closed Terminal Writes
+- `.planning/SPEC.md` (`LAUNCH-12`, `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`
+
+## D45 — Fork-Honest Launch Posture Before Identity Migration
+- `.planning/SPEC.md` (v1.2.0 active requirements and posture)
+- `.planning/ROADMAP.md` (Phase 23-27 ownership)
+- `.internal-research/TODO.md`, `.internal-research/gaps.md` (`I39`), `.internal-research/lessons-learned.md`
+- `.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`
+
+## D46 — Archived Milestone Routing With Retained ROADMAP
+- `.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`
+- `get-shit-done/workflows/progress.md`
+
+## D47 — Brownfield Quick-Win Repair
+- `.planning/SPEC.md` (`DX-03`, `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`, `tests/gsdd.invariants.test.cjs`
+
+## D48 — Shared Lifecycle Evaluator And Dual-Canonical Runtime Boundary
+- `.planning/SPEC.md` (`ENGINE-01`, `ENGINE-02`, `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`
+- `get-shit-done/workflows/progress.md`
+
+## D49 — Deterministic Lifecycle Preflight Gates
+- `.planning/SPEC.md` (`ENGINE-01`, `ENGINE-02`, `ENGINE-03`)
+- `.planning/ROADMAP.md` (Phase 30)
+- `bin/lib/lifecycle-preflight.mjs`, `bin/lib/lifecycle-state.mjs`
+- `bin/gsdd.mjs`, `bin/lib/init.mjs`
+- `distilled/workflows/execute.md`, `distilled/workflows/verify.md`
+- `distilled/workflows/audit-milestone.md`, `distilled/workflows/complete-milestone.md`
+- `distilled/workflows/new-milestone.md`, `distilled/workflows/resume.md`, `distilled/workflows/progress.md`
+- `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.scenarios.test.cjs`
+- `get-shit-done/workflows/progress.md`
+
+## D50 — Evidence-Gated Closure Matrix
+- `.planning/SPEC.md` (`ENGINE-04`, `VERIFY-01`)
+- `.planning/ROADMAP.md` (Phase 31)
+- `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`
+- `agents/_archive/gsd-verifier.md`, `agents/_archive/gsd-integration-checker.md`
+
+## D51 — Deterministic Runtime Surface Freshness
+- `.planning/SPEC.md` (`ENGINE-05`)
+- `.planning/ROADMAP.md` (Phase 32)
+- `.internal-research/gaps.md` (`I42`)
+- `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`
+- `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`
+- `get-shit-done/workflows/progress.md`
+
+## D52 — Generic Checkpoint Routing Ownership
+- `.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`
+- `get-shit-done/workflows/progress.md`
+
+---
+
+## Maintenance
+
+Update this file when:
+- A new design decision is added to `distilled/DESIGN.md` (add entry here before or alongside the DESIGN.md commit)
+- An existing decision's evidence changes (update the relevant entry)
+
+Guard: G31 in `tests/gsdd.guards.test.cjs` asserts every decision in DESIGN.md ToC has an entry here with at least one source.

package/distilled/README.md

@@ -1,16 +1,28 @@
-# GSDD (Get Shit Done Distilled)
+# Workspine
 
-Lightweight Spec-Driven Development (SDD) for AI-assisted engineering.
+A repo-native delivery spine for planning, checking, execution, verification, and handoff of long-horizon AI-assisted work.
 
-Distilled from GSD (Get Shit Done): keep rigor and leverage, drop ceremony.
+Workspine keeps planning, execution, verification, handoff, and progress state in the repo so work survives cold starts, runtime switches, and session loss. The retained package and CLI contracts remain `gsdd-cli` / `gsdd`.
 
 ## What This Is
 
-GSDD is a small set of workflow sources plus a CLI (`gsdd`) that:
+Workspine is a small set of workflow sources plus a CLI (`gsdd`) that:
 - scaffolds a project planning workspace (`.planning/`)
 - generates portable workflow entrypoints as skills (`.agents/skills/gsdd-*/SKILL.md`)
 - optionally generates tool-specific adapters for runtimes that need extra native surfaces (root `AGENTS.md`, Claude skills + plan-command alias + native agents, OpenCode commands + native agents)
 
+It gives serious AI-assisted work one durable repo workflow spine for planning, checking, execution, verification, and handoff without pretending to be a hosted orchestration layer.
+
+Workspine is the product name. The package, CLI commands, workflow prefixes, and workspace directory remain `gsdd-cli`, `gsdd`, `gsdd-*`, and `.planning/` — these are retained technical contracts, not rename residue.
+
+Workspine began as a fork of Get Shit Done, whose long-horizon delivery spine proved the problem was real. Since the fork, upstream GSD has continued evolving into a broad multi-runtime framework. Workspine took a different path: a smaller repo-native delivery spine with fewer public workflow surfaces, generated runtime surfaces from a portable core, evidence-gated closure, and provenance-aware continuity.
+
+Launch proof posture:
+- Directly validated in repo truth: Claude Code, Codex CLI, OpenCode
+- Qualified support only: Cursor, Copilot, Gemini CLI support the same core workflow via the shared `.agents/skills/` surface plus optional governance; proof and ergonomics differ from the directly validated runtimes
+- Installed generated runtime surfaces are renderer-checked locally through `gsdd health`, with deterministic repair through `gsdd update`
+- Public proof entrypoints: `docs/BROWNFIELD-PROOF.md`, `docs/proof/consumer-node-cli/README.md`, `docs/RUNTIME-SUPPORT.md`, `docs/VERIFICATION-DISCIPLINE.md`
+
 ## Quick Start
 
 Run in your project root:
@@ -41,39 +53,57 @@ Notes:
 ## The Workflow
 
 ```
-gsdd init           -> bootstrap (create .planning/, copy templates, generate skills/adapters)
-/gsdd:new-project   -> .planning/SPEC.md + .planning/ROADMAP.md  (questioning + codebase audit + research)
-/gsdd:plan N        -> phases/N/PLAN.md      (task breakdown + research)
-/gsdd:execute N     -> code changes          (plan execution with quality gates)
-/gsdd:verify N      -> VERIFICATION.md       (goal-backward validation)
+gsdd init                  -> bootstrap (create .planning/, copy templates, generate skills/adapters)
+/gsdd-new-project          -> .planning/SPEC.md + .planning/ROADMAP.md  (questioning + codebase audit + research)
+/gsdd-plan N               -> phases/N/PLAN.md      (task breakdown + research)
+/gsdd-execute N            -> code changes           (plan execution with quality gates)
+/gsdd-verify N             -> VERIFICATION.md        (goal-backward validation)
   ... repeat plan/execute/verify per phase ...
-/gsdd:quick         -> .planning/quick/NNN/  (sub-hour task outside phases)
-/gsdd:pause         -> .planning/.continue-here.md  (session checkpoint)
-/gsdd:resume        -> restore context, route to next action
-/gsdd:progress      -> show status, route to next action
+/gsdd-audit-milestone      -> MILESTONE-AUDIT.md     (cross-phase integration + requirements coverage)
+/gsdd-complete-milestone   -> milestones/vX.Y-*      (archive, evolve spec, collapse roadmap)
+/gsdd-new-milestone        -> updated SPEC.md + ROADMAP.md  (next milestone goals + phases)
+/gsdd-plan-milestone-gaps  -> gap closure phases in ROADMAP.md  (from audit results)
+/gsdd-quick                -> .planning/quick/NNN/   (sub-hour task outside phases)
+/gsdd-pause                -> .planning/.continue-here.md  (session checkpoint)
+/gsdd-resume               -> restore context, route to next action
+/gsdd-progress             -> show status, route to next action
 ```
 
-## Current Status (updated 2026-03-20)
-
-| Workflow | Status | Notes |
-|----------|--------|-------|
-| `new-project.md` | [OK] Defined, source-audited | Covers greenfield + brownfield + milestone context |
-| `plan.md` | [OK] Defined, source-audited | Portable workflow defines the planner contract and supports independent plan checking through generated native adapters |
-| `execute.md` | [OK] Source-audited | Mandatory read enforcement, auth-gate routing, deviation-rule examples, and substantive summary quality gate |
-| `verify.md` | [OK] Source-audited | 5 gap closures against hardened verifier role contract: grouped-gap guidance, orphan detection, frontmatter enforcement, verification basis emphasis, requirements coverage chain |
-| `audit-milestone.md` | [OK] Defined, source-audited | Aggregates phase verification, cross-phase integration audit, auth protection checks, requirement reconciliation, and orphan detection into `MILESTONE-AUDIT.md` |
-| `quick.md` | [OK] | Quick-work lane for sub-hour tasks outside the phase cycle (D11) |
-| `pause.md` | [OK] Source-audited | Session checkpoint writer with conversational handoff (D12) |
-| `resume.md` | [OK] Source-audited | Session context restorer with priority-ordered routing (D12) |
-| `progress.md` | [OK] Source-audited | Read-only status reporter with 6 named route branches, recent work, between-milestones detection (D12) |
-| `map-codebase.md` | [OK] Defined, source-audited | Standalone codebase mapping/refresh |
+## Brownfield Entry Contract
+
+Use the same three-way routing everywhere:
+
+- `gsdd-new-project` is the full initializer for greenfield work, fuzzy brownfield scope, or milestone-shaped work. Users do not need to pre-run `map-codebase`; `new-project` does that internally when needed.
+- `gsdd-quick` is the bounded brownfield lane when the change is already concrete. It uses existing codebase maps when present and otherwise builds a just-enough inline baseline.
+- `gsdd-map-codebase` is the deeper orientation pass for unfamiliar or higher-risk repos before choosing between `quick` and `new-project`.
+
+## Workflow Surface (updated 2026-04-19)
+
+| Workflow | What ships |
+|----------|------------|
+| `new-project.md` | Greenfield + brownfield + milestone initialization |
+| `plan.md` | Portable planner contract with independent plan checking through generated native adapters |
+| `execute.md` | Mandatory reads, auth-gate routing, deviation rules, and substantive summary quality gate |
+| `verify.md` | Phase verification with orphan detection, frontmatter enforcement, and requirements coverage chain |
+| `audit-milestone.md` | Cross-phase integration audit, auth protection checks, requirement reconciliation, and orphan detection into `MILESTONE-AUDIT.md` |
+| `complete-milestone.md` | Milestone archive, spec evolution, and roadmap collapse |
+| `new-milestone.md` | Brownfield milestone continuation: goals, requirements, and roadmap phases |
+| `plan-milestone-gaps.md` | Gap-closure phases from `MILESTONE-AUDIT.md` results |
+| `quick.md` | Quick-work lane for sub-hour tasks outside the phase cycle |
+| `pause.md` | Session checkpoint writer with conversational handoff |
+| `resume.md` | Session context restorer with priority-ordered routing |
+| `progress.md` | Read-only status reporter with recent work, archived-milestone detection, and non-phase brownfield routing |
+| `map-codebase.md` | Standalone codebase mapping/refresh and deeper brownfield orientation |
+| `verify-work.md` | Conversational UAT validation with structured gap tracking |
 
 Architecture notes:
 - `bin/gsdd.mjs` remains the thin generator entrypoint, while vendor-specific rendering lives in adapter modules.
 - Codex CLI uses the always-generated `.agents/skills/gsdd-*` surface as its entry path and can add a native `.codex/agents/gsdd-plan-checker.toml` checker agent.
+- `gsdd health` now compares any installed generated runtime surfaces against current render output and routes repairs back through `gsdd update`.
 - Portable lifecycle contracts now align to the roadmap template status grammar: `[ ]`, `[-]`, `[x]`.
 - Phase verification and milestone integration audit are treated as separate concerns.
 - Canonical role contracts use bounded sections, typed output examples, and checklist-driven completion where those structures materially improve downstream reliability.
+- Public launch wording is conservative by design: direct proof is claimed only for runtimes with recorded lifecycle evidence in the repo.
 
 ## Init Workflow Agent Count (by config)
 
@@ -100,10 +130,14 @@ Note: `parallelization: false` keeps the same mapper/researcher set but runs the
   research/            # optional research outputs
 .agents/skills/
   gsdd-new-project/SKILL.md
+  gsdd-new-milestone/SKILL.md
   gsdd-plan/SKILL.md
+  gsdd-plan-milestone-gaps/SKILL.md
   gsdd-execute/SKILL.md
   gsdd-verify/SKILL.md
+  gsdd-verify-work/SKILL.md
   gsdd-audit-milestone/SKILL.md
+  gsdd-complete-milestone/SKILL.md
   gsdd-quick/SKILL.md
   gsdd-pause/SKILL.md
   gsdd-resume/SKILL.md
@@ -130,19 +164,24 @@ Note: `parallelization: false` keeps the same mapper/researcher set but runs the
 
 ```
 distilled/
-  DESIGN.md                # design decisions and rationale (36 decisions, evidence-backed)
+  DESIGN.md                # design decisions and rationale (52 decisions, evidence-backed)
+  EVIDENCE-INDEX.md        # source-to-decision index for durable research-backed claims
   SKILL.md                 # primary entry point (plain markdown)
   workflows/
-    new-project.md
+    audit-milestone.md
+    complete-milestone.md
+    execute.md
     map-codebase.md
+    new-project.md
+    new-milestone.md
+    pause.md
     plan.md
+    plan-milestone-gaps.md
     progress.md
-    execute.md
-    verify.md
-    audit-milestone.md
     quick.md
-    pause.md
     resume.md
+    verify-work.md
+    verify.md
   templates/
     spec.md
     roadmap.md
@@ -154,6 +193,7 @@ distilled/
       mapper-quality.md
       mapper-concerns.md
       plan-checker.md
+      approach-explorer.md
       researcher-stack.md
       researcher-features.md
       researcher-architecture.md