gsdd-cli 0.1.0

package/agents/DISTILLATION.md

@@ -0,0 +1,306 @@
+# GSDD Role Distillation Ledger
+
+Evidence map from each of the 9 canonical GSDD roles to their GSD sources, with keep/strip/why rationale. This ledger documents why each role exists in its current form and what GSD content was distilled or merged.
+
+---
+
+## 1. Mapper
+
+**Canonical role:** `agents/mapper.md`
+
+**GSD source:** `agents/_archive/gsd-codebase-mapper.md`
+
+**Merger type:** Kept-as-is (function scope preserved, output contract simplified)
+
+**Kept from GSD:**
+- Mandatory initial-read discipline for context files
+- 4 focus areas (tech, arch, quality, concerns)
+- Output contract with artifact names and downstream consumers
+- Core algorithm: parse → explore → fill template → write → confirm
+
+**Stripped from GSD:**
+- Multi-file codebase output reduced to 4-file standard (see D1)
+- Validator-pass patterns (GSDD trusts agent reads, not file validation)
+
+**Gained in GSDD:**
+- Explicit "Downstream Consumers" section (shows who uses mapper output)
+- Clear guidance on prescriptive vs. descriptive output (helps agents write better code)
+
+**Rationale:** Mapper is the lowest-level, most stable role. Its core job (explore + document) hasn't changed, but the output set shrank from 7 files to 4 files per D1 (lean context decision). The agent role contract itself needed no substantive changes.
+
+---
+
+## 2. Researcher
+
+**Canonical role:** `agents/researcher.md`
+
+**GSD sources:** `agents/_archive/gsd-project-researcher.md` + `agents/_archive/gsd-phase-researcher.md` (merged)
+
+**Merger type:** Merged (same algorithm, different scope parameter)
+
+**Kept from GSD:**
+- Mandatory initial-read discipline
+- Research scope (project vs. phase)
+- Research mode (ecosystem, feasibility, comparison)
+- Core algorithm: receive scope → identify domains → execute tool hierarchy → verify → write → return structured result
+- Quality guarantees (training data = hypothesis, honest reporting, investigation not confirmation, confidence levels on every finding)
+- Research pitfalls and prevention strategies
+
+**Stripped from GSD:**
+- Separate role contracts for project-researcher and phase-researcher (merged into one with scope parameter)
+- Tool-specific shell commands (kept portable tool contracts instead)
+
+**Gained in GSDD:**
+- Explicit "Scope" table showing scope × trigger × focus × output location
+- Clear statement: "Same algorithm, different scope. The scope is a context input, not a different role."
+
+**Rationale:** The GSD original had two roles (project and phase researcher) that followed the identical algorithm but with a scope parameter. GSDD merged them into one canonical role taking scope as input, reducing the role count from 11 to 9 while preserving all leverage. This is the clean merger mentioned in D2.
+
+---
+
+## 3. Synthesizer
+
+**Canonical role:** `agents/synthesizer.md`
+
+**GSD source:** `agents/_archive/gsd-research-synthesizer.md` (with recovery hardening from PR #15)
+
+**Merger type:** Kept-as-is (hardened in 2026-03-13)
+
+**Kept from GSD:**
+- Mandatory initial-read discipline
+- Input contract: all 4 research files (STACK, FEATURES, ARCHITECTURE, PITFALLS)
+- Output contract: SUMMARY.md with executive summary, key findings, roadmap implications, confidence/gaps
+- Downstream consumer (roadmapper) and what it needs
+- 6-step execution flow: read → synthesize → extract → derive → assess → write
+
+**Stripped from GSD:**
+- Conditional skip logic (kept mandatory synthesizer per D5 original decision)
+- Vendor-specific output formatting
+
+**Gained in GSDD (PR #15 hardening):**
+- Explicit required files list with blocked-return pattern (do not guess from partial context, return blocked status naming missing file)
+- "Be opinionated" guidance to roadmapper
+- Stronger structured-return contract
+
+**Rationale:** Synthesizer is a thin single-step role with no merge or extraction needed. It was hardened in PR #15 to restore explicit structure and completion discipline, but the core function and leverage remained unchanged from GSD.
+
+---
+
+## 4. Planner
+
+**Canonical role:** `agents/planner.md`
+
+**GSD sources:** `agents/_archive/gsd-planner.md` + `agents/_archive/gsd-plan-checker.md` (merged)
+
+**Merger type:** Merged (orchestration ownership transferred to native adapters)
+
+**Kept from GSD:**
+- Mandatory initial-read discipline
+- Phase goal decomposition and dependency graphs
+- Goal-backward verification (must-haves, artifacts, key links)
+- Planner responsibility and scope
+- Input contract (SPEC, ROADMAP, codebase context, prior phase artifacts)
+- Output contract (PLAN.md with frontmatter, objective, context references, typed tasks)
+
+**Stripped from GSD:**
+- Separate plan-checker role (now a delegate at `distilled/templates/delegates/plan-checker.md`)
+- GSD's native 3-cycle verification loop (embedded in planner) → moved to native adapter surfaces (Claude skill, OpenCode command, Codex agent)
+- Vendor-specific fresh-context orchestration logic
+
+**Gained in GSDD:**
+- Explicit scope boundary: "plan-scoped, does not own verification or milestone audit"
+- Goal-backward section with 4 clear questions
+- Planning process section with concrete steps
+- Reference to plan-checker delegate for fresh-context review
+- Reduced-assurance fallback mode description (when no independent checker runs)
+
+**Rationale:** GSD's plan-checker was a separate role running a 3-cycle revision loop. GSDD merged planner and plan-checker into a single portable contract, but preserved the adversarial review concept through native adapter surfaces. The portable workflow describes the reduced-assurance fallback. This is the high-impact merger from D2 with full tradeoff documentation.
+
+---
+
+## 5. Roadmapper
+
+**Canonical role:** `agents/roadmapper.md`
+
+**GSD source:** `agents/_archive/gsd-roadmapper.md` (with recovery hardening from PR #15)
+
+**Merger type:** Kept-as-is (hardened in 2026-03-13)
+
+**Kept from GSD:**
+- Mandatory initial-read discipline
+- Bounded section structure (phases, requirements, success criteria, coverage validation)
+- Explicit coverage validation
+- Parse-critical artifact contract
+- Structured return modes
+- Checklist-driven completion
+
+**Stripped from GSD:**
+- Template-path references (output lives in `.planning/ROADMAP.md`)
+- Commit steps (GSDD handles git separately)
+- Vendor-specific file conventions
+
+**Gained in GSDD (PR #15 hardening):**
+- Explicit `.planning/ROADMAP.md` ownership contract
+- Explicit `[ ]` / `[-]` / `[x]` status grammar
+- Concrete `ROADMAP CREATED` artifact example
+- Hard boundary: "this role does not settle the separate ROADMAP/STATE lifecycle seam"
+
+**Rationale:** Roadmapper was over-distilled in the initial extraction; PR #15 recovered visible structure and completion discipline. The core role and leverage were intact; hardening just restored the guardrails that improve compliance.
+
+---
+
+## 6. Executor
+
+**Canonical role:** `agents/executor.md`
+
+**GSD source:** `agents/_archive/gsd-executor.md` (with substantial hardening from PR #16)
+
+**Merger type:** Kept-as-is (hardened significantly in 2026-03-13)
+
+**Kept from GSD:**
+- Plan-scoped execution discipline
+- Task implementation and deviation handling
+- Git action recording without repo-specific naming assumptions
+- Checkpoint protocol
+- Completion summary
+- State update responsibility
+
+**Stripped from GSD:**
+- Bash recipe patterns and shell-specific guidance
+- Tool-specific directory naming conventions
+
+**Gained in GSDD (PR #16 hardening):**
+- Explicit scope boundary with 6 things executor does NOT own
+- Clearer deviation rules with priority order (auto-fix bugs first)
+- Success criteria confirmation requirement
+- Verify quality checks now live inside task_completeness (runnable, fast, ordered)
+- Stronger commitment to documented deviations
+
+**Rationale:** Executor is the most complex role, with the broadest deviation surface. PR #16 audit recovered substantive guardrails: explicit scope boundaries, rule priority, and verification discipline. The ~150-line executor contract expanded to ~400 lines because the detail prevents misalignment, not because the job changed.
+
+---
+
+## 7. Verifier
+
+**Canonical role:** `agents/verifier.md`
+
+**GSD source:** `agents/_archive/gsd-verifier.md` (with selective hardening from D2)
+
+**Merger type:** Kept-as-is (scope preserved; cross-phase audit extracted separately)
+
+**Kept from GSD:**
+- Phase-level goal-backward verification
+- Exists/Substantive/Wired gate
+- Anti-pattern scan
+- Output contract with compact base fields (phase, verified, status, score)
+- Verification-report structure
+
+**Stripped from GSD:**
+- Cross-phase integration audit scope (extracted as separate role + workflow)
+- GSD's narrative all-encompassing verification
+
+**Gained in GSDD:**
+- Richer structured verifier findings (re_verification, gaps, human_verification) when material
+- Explicit boundaries: "phase-scoped only, cross-phase integration is a separate concern"
+- D2 cross-reference: why integration-checker exists as a separate role
+
+**Rationale:** Verifier's phase-level job is unchanged. The extraction of integration-checker as a separate milestone surface (D2, PR #12) made verifier smaller and clearer. Phase verification and milestone integration audit are now distinct concerns with explicit handoff points.
+
+---
+
+## 8. Integration-Checker
+
+**Canonical role:** `agents/integration-checker.md`
+
+**GSD source:** `agents/_archive/gsd-integration-checker.md` (with structural recovery in PR #12 and systemic hardening in PR #15)
+
+**Merger type:** Extracted as standalone role (cross-phase scope differs structurally from phase verification)
+
+**Kept from GSD:**
+- Mandatory initial-read discipline
+- Cross-phase wiring verification (exports → imports, APIs → consumers, forms → handlers, data → display)
+- E2E flow tracing
+- Typed structured return
+- Checklist-driven completion
+
+**Stripped from GSD (intentional):**
+- Framework-specific Bash recipes
+- Hardcoded path assumptions
+- File-extension-specific grep flags
+- Tool-specific details that don't survive vendor-agnostic distillation
+
+**Gained in GSDD:**
+- PR #12: explicit section boundaries, stronger structured output, cleaner split between role contract and milestone workflow
+- PR #15: recovered compliance guardrails, restored mandatory read enforcement, explicit auth-protection verification
+- D2 reference: structural difference from phase verifier
+- New in D21 (PR #35): Step 4a matrix-driven auth verification (if AUTH_MATRIX.md exists)
+
+**Rationale:** GSD's integration-checker was a separate surface but lived in the shadows of the main role contracts. PR #12 extracted it fully; PR #15 recovered its substantive guardrails. The role is different from verifier because it owns milestone scope (all-phase wiring) vs. phase scope (phase goal). This is the cleanest separation in D2.
+
+---
+
+## 9. Debugger
+
+**Canonical role:** `agents/debugger.md`
+
+**GSD source:** `agents/_archive/gsd-debugger.md` (no changes)
+
+**Merger type:** Kept-as-is (unchanged)
+
+**Kept from GSD:**
+- Systematic debugging methodology
+- Hypothesis formulation and testing
+- State persistence across context resets
+- Structured checkpoint protocol
+- Deviation handling
+
+**Stripped from GSD:** (nothing significant)
+- Minor tool path references
+
+**Gained in GSDD:** (nothing)
+- The role is kept as-is for compatibility
+
+**Rationale:** Debugger is a standalone utility role with no dependencies on other roles. It was preserved exactly as-is from GSD because it works and has no vendor lock-in. It's used ad-hoc when agents encounter failures, not as part of the main workflow pipeline.
+
+---
+
+## Summary: Merger Table (from D2)
+
+| Canonical role | Absorbs from GSD | Merger criteria |
+|---|---|---|
+| `mapper.md` | `gsd-codebase-mapper.md` | Kept-as-is; output set changed per D1 (7 → 4 files) |
+| `researcher.md` | `gsd-project-researcher.md` + `gsd-phase-researcher.md` | Scope parameter instead of separate role |
+| `synthesizer.md` | `gsd-research-synthesizer.md` | Kept-as-is; hardened in PR #15 |
+| `planner.md` | `gsd-planner.md` + `gsd-plan-checker.md` | Orchestration ownership moved to native adapters; portable checker-delegate created |
+| `roadmapper.md` | `gsd-roadmapper.md` | Kept-as-is; hardened in PR #15 |
+| `executor.md` | `gsd-executor.md` | Kept-as-is; heavily hardened in PR #16 |
+| `verifier.md` | `gsd-verifier.md` | Kept-as-is; cross-phase audit extracted to integration-checker |
+| `integration-checker.md` | `gsd-integration-checker.md` | Extracted as standalone; recovered in PR #12, hardened in PR #15 |
+| `debugger.md` | `gsd-debugger.md` | Kept-as-is; no changes |
+
+**Result:** 11 GSD roles → 9 GSDD canonical roles (2 mergers: researcher, planner). 1 extraction: integration-checker moved from embedded to standalone. Total leverage preserved, role count reduced.
+
+---
+
+## Evidence and Context
+
+- GSD sources: `agents/_archive/gsd-*.md`
+- GSDD canonical roles: `agents/*.md` (all except `_archive/`)
+- Design decisions: `distilled/DESIGN.md` (D1, D2)
+- PR history:
+  - PR #9: Delegate extraction
+  - PR #12: Integration-checker extraction and lifecycle contract seam
+  - PR #14-17: Systemic role-contract hardening and leverage recovery
+  - PR #35: OWASP authorization matrix integration into integration-checker
+
+---
+
+## Maintenance
+
+This ledger is updated when:
+
+1. A canonical role contract changes significantly (update the "Kept"/"Stripped"/"Gained" sections)
+2. A GSD role is merged into or extracted from a canonical role (update the merger table)
+3. New evidence surfaces that changes the distillation rationale (update with citation)
+
+Do not add speculative content. Every entry must reference actual source files and PRs that contain evidence.

package/agents/README.md

@@ -0,0 +1,53 @@
+# Canonical Role Library
+
+Vendor-agnostic role contracts for GSDD's agent architecture.
+
+## Two-Layer Architecture
+
+| Layer | Location | Purpose |
+|-------|----------|---------|
+| **Roles** (this directory) | `agents/*.md` | Durable contracts: identity, inputs, outputs, algorithm, guarantees |
+| **Delegates** | `distilled/templates/delegates/*.md` | Task-specific wrappers: scoped instructions that reference a role |
+
+Roles define what an agent is. Delegates define what an agent does in a specific workflow context.
+
+## Lifecycle Roles
+
+| Role | File | Absorbs From (GSD) |
+|------|------|---------------------|
+| Mapper | `mapper.md` | `gsd-codebase-mapper.md` |
+| Researcher | `researcher.md` | `gsd-project-researcher.md` + `gsd-phase-researcher.md` |
+| Synthesizer | `synthesizer.md` | `gsd-research-synthesizer.md` |
+| Planner | `planner.md` | `gsd-planner.md` + `gsd-plan-checker.md` |
+| Executor | `executor.md` | `gsd-executor.md` |
+| Verifier | `verifier.md` | `gsd-verifier.md` |
+| Roadmapper | `roadmapper.md` | `gsd-roadmapper.md` |
+
+## Audit Roles
+
+| Role | File | Absorbs From (GSD) |
+|------|------|--------------------|
+| Integration Checker | `integration-checker.md` | `gsd-integration-checker.md` |
+
+## Utility Roles
+
+| Role | File | Note |
+|------|------|------|
+| Debugger | `debugger.md` | Not part of core lifecycle. Standalone diagnostic utility. |
+
+## Runtime Distribution
+
+`gsdd init` copies all role contracts (excluding this README) from `agents/` into `.planning/templates/roles/` in the consumer project. This gives consumer projects a portable, self-contained copy of the role library with no hard dependency on the GSDD framework repo at runtime.
+
+- **Single source of truth:** `agents/*.md` in this repo. Consumer copies are generated, not edited.
+- **Delegates reference the local copy:** `distilled/templates/delegates/*.md` point to `.planning/templates/roles/<role>.md`, not back to this repo.
+- **Idempotent:** `gsdd init` skips the copy if `.planning/templates/roles/` already exists.
+- **Updates:** `gsdd update --templates` re-copies from latest framework sources with hash-based modification detection.
+
+Verifier note:
+- `verifier.md` is phase-scoped.
+- The milestone integration-audit surface exists as `distilled/workflows/audit-milestone.md` with its own `integration-checker.md` role contract. It is not absorbed into the verifier.
+
+## Archive
+
+`_archive/` contains the original 11 GSD agent files (preserved via `git mv` for history). These are the verbose, GSD-specific sources from which canonical roles were distilled. Do not reference them in workflows; use the canonical roles above.

package/agents/debugger.md

@@ -0,0 +1,82 @@
+# Debugger
+
+> Investigates bugs using systematic scientific method with persistent debug log.
+
+**This is a utility role, not part of the core lifecycle (init -> plan -> execute -> verify).**
+
+## Responsibility
+
+Accountable for finding root causes through hypothesis testing, maintaining a persistent debug log (so investigation can resume after interruption), and optionally applying and verifying fixes. The user reports symptoms; the debugger investigates causes.
+
+## Input Contract
+
+- **Required:** Bug symptoms (expected behavior, actual behavior, error messages)
+- **Optional:** Reproduction steps
+- **Optional:** Mode flag: `find_root_cause_only` (diagnose but don't fix) or `find_and_fix` (default, full cycle)
+- **Optional:** Pre-filled symptoms from automated diagnosis (skip symptom gathering)
+
+## Output Contract
+
+- **Artifacts:** Debug log file written to the output directory, tracking: symptoms, hypotheses, eliminated paths, evidence, and resolution
+- **Return:** One of:
+  - `ROOT CAUSE FOUND` -- with cause, evidence, files involved, and suggested fix direction
+  - `DEBUG COMPLETE` -- with root cause, fix applied, verification result, files changed
+  - `INVESTIGATION INCONCLUSIVE` -- with what was checked, eliminated hypotheses, remaining possibilities
+  - `ESCALATE` -- when user input is unavoidable (credentials, environment access, architectural decision)
+
+## Core Algorithm
+
+1. **Check for existing debug log.** Resume from last recorded state if exists, create new if not.
+2. **Gather symptoms** (unless pre-filled). Expected vs actual behavior, error messages, reproduction steps, when it started.
+3. **Investigation loop:**
+   a. **Gather initial evidence.** Search codebase for error text, read relevant files completely, run tests to observe behavior.
+   b. **Form hypothesis.** Must be specific and falsifiable. "User state resets because component remounts on route change" not "Something is wrong with the state."
+   c. **Test hypothesis.** Execute ONE test at a time. Record result as evidence.
+   d. **Evaluate.** Confirmed -> proceed to fix (or return diagnosis). Eliminated -> record in eliminated list, form new hypothesis.
+4. **Fix and verify** (if mode is `find_and_fix`):
+   a. Implement minimal fix addressing confirmed root cause.
+   b. Verify against original symptoms.
+   c. If verification fails, return to investigation loop.
+5. **Close debug log** on resolution. Mark as resolved with final outcome.
+
+## Cognitive Bias Table
+
+| Bias | Trap | Antidote |
+|------|------|----------|
+| Confirmation | Only seeking evidence supporting your hypothesis | Actively seek disconfirming evidence. "What would prove me wrong?" |
+| Anchoring | First explanation becomes your anchor | Generate 3+ hypotheses before investigating any |
+| Availability | Recent bugs -> assume similar cause | Treat each bug as novel until evidence suggests otherwise |
+| Sunk Cost | 2 hours on one path, keep going despite evidence | Every 30 min: "If I started fresh, is this still the path I'd take?" |
+
+## Investigation Techniques
+
+- **Binary search:** Cut problem space in half repeatedly (data correct at DB? Yes. At API? Yes. At frontend? No. -> serialization layer).
+- **Minimal reproduction:** Strip away everything until smallest code reproduces the bug.
+- **Working backwards:** Start from desired output, trace backwards to find divergence point.
+- **Differential debugging:** What changed since it worked? Compare environments, configs, data.
+- **Observability first:** Add logging BEFORE making any fix. Observe, then change.
+
+## When to Restart
+
+Consider starting over when: 2+ hours with no progress, 3+ "fixes" that didn't work, you can't explain the current behavior, or a fix works but you don't know why.
+
+## Quality Guarantees
+
+- **Persistent state.** Debug log is updated BEFORE each action. If the agent is interrupted, investigation can resume from exactly where it left off.
+- **No re-investigation.** The eliminated list prevents revisiting disproven hypotheses.
+- **Fix verified against original symptoms.** Not "it seems to work" but "reproduction steps now produce correct behavior."
+- **Change one variable at a time.** Multiple simultaneous changes invalidate conclusions.
+
+## Anti-Patterns
+
+- Asking the user what's causing the bug (user reports symptoms, debugger investigates causes).
+- Acting on weak evidence ("I think it might be X").
+- Testing multiple hypotheses simultaneously.
+- Skipping verification after applying a fix.
+- Making large fixes without understanding root cause.
+
+## Vendor Hints
+
+- **Tools required:** File read, file write, file edit, shell execution, content search, glob, web search
+- **Parallelizable:** No -- debugging is inherently sequential and interactive
+- **Context budget:** High -- investigation requires reading many files and running many tests. Debug file persistence mitigates context limits.