gsdd-cli 0.3.1 → 0.16.1

package/distilled/templates/agents.block.md

@@ -1,92 +1,21 @@
 ## GSDD Governance (Generated)
 
-This block is managed by `gsdd`. Do not edit inside the block directly.
-Edit the source template in the GSDD framework instead.
+Managed by `gsdd`; edit the framework template, not this block.
 
-### What This Project Uses
-- Framework: GSDD (Spec-Driven Development)
-- Planning dir: `.planning/` (specs, roadmaps, plans, research, templates)
-- Lifecycle: `bootstrap (gsdd init) -> new-project -> [discuss-approach -> plan -> execute -> verify] x N -> audit-milestone` for roadmap work
-- Supporting workflows: quick (sub-hour tasks), map-codebase (codebase analysis), pause/resume (session management), progress (status query)
+Lifecycle: `new-project -> plan -> execute -> verify -> audit-milestone`.
 
-### Rules You MUST Follow
+Core skills: `gsdd-new-project`, `gsdd-plan`, `gsdd-execute`, `gsdd-verify`, `gsdd-progress`.
+Planning state: `.planning/`. Portable workflows: `.agents/skills/gsdd-*/SKILL.md`.
 
-1. Never Skip The Workflow
-- Roadmap work should follow: plan -> execute -> verify.
-- Direct user requests do NOT need to be forced into a phase or plan unless the user explicitly wants roadmap tracking.
-- Before coding roadmap work: read `.planning/SPEC.md`, `.planning/ROADMAP.md`, and the relevant phase plan if one exists.
-- After coding: verify against the relevant success criteria before claiming done.
+Invoke: `/gsdd-plan` (Claude, OpenCode, Cursor, Copilot, Gemini) · `$gsdd-plan` (Codex) · open SKILL.md directly elsewhere.
 
-2. Read Before You Write
-- If `.planning/` exists, read in order:
-  - `.planning/SPEC.md`
-  - `.planning/ROADMAP.md`
-  - `.planning/config.json`
-  - The relevant phase plan in `.planning/phases/` when the work is roadmap-scoped
-- If `.planning/` does not exist, the project has not been bootstrapped. Run `gsdd init`, then run the new-project workflow (`.agents/skills/gsdd-new-project/SKILL.md`).
+Rules:
+1. Read before writing roadmap work: `.planning/SPEC.md`, `.planning/ROADMAP.md`, `.planning/config.json`, and the relevant phase plan when one exists.
+2. Stay in scope. Implement only what the approved plan or direct user request says. Record unrelated ideas as TODOs.
+3. Verify before claiming done: artifact exists, content is substantive, and it is wired into the system.
+4. Research unfamiliar domains from real docs and code; never hallucinate paths or APIs.
+5. Do not pollute core workflows with vendor-specific syntax; adapters are generated under `bin/`.
+6. Git guidance in `.planning/config.json` -> `gitProtocol` is advisory; follow the repo's own conventions first.
 
-3. Stay In Scope (Zero Deviation)
-- Implement ONLY what the approved plan or direct user request specifies.
-- If you notice unrelated improvements, do not implement them. Record them as a TODO for a future phase.
+If `.planning/` is missing, run `gsdd init` then `gsdd-new-project`.
 
-Priority order when instructions conflict:
-- Developer explicit instruction (highest)
-- Current approved plan or direct task scope
-- `.planning/SPEC.md`
-- General best practices (lowest)
-
-4. Version Control Protocol
-- Treat `.planning/config.json` -> `gitProtocol` as advisory guidance, not a mandatory naming template.
-- Follow the existing repo or team git conventions first.
-- Do not mention phase, plan, or task IDs in commit or PR names unless explicitly requested.
-- Tests must pass before committing.
-
-5. Verify Your Own Work (Exists -> Substantive -> Wired)
-Before reporting "done", verify each deliverable:
-- Exists: artifact is present where the plan says it should be
-- Substantive: real content/code, not placeholders or TODOs
-- Wired: connected to the system (imported, called, rendered, tested)
-
-6. Research Before Unfamiliar Domains
-If you are not confident about a domain/library/pattern:
-- Stop and research first (docs + existing code).
-- Do not assume training data is current.
-- Cite sources in `.planning/research/` (or `.internal-research/` for framework work).
-
-7. Never Hallucinate Paths Or APIs
-- Use only file paths you've confirmed exist.
-- Use only APIs verified in docs or source.
-
-8. Adapter Architecture Rule
-- Do not pollute core workflows (`distilled/workflows/*.md`) with vendor-specific syntax.
-- Tool-specific adapters are generated in `bin/` (generators, not converters).
-
-9. Anti-YOLO
-- Do not delete or rewrite code unless explicitly asked.
-- If asked for analysis, answer first; propose changes separately.
-
-### Where The Workflows Live
-- Primary lifecycle:
-  - `.agents/skills/gsdd-new-project/SKILL.md` — project initialization (spec + roadmap)
-  - `.agents/skills/gsdd-plan/SKILL.md` — phase planning with optional independent checking
-  - `.agents/skills/gsdd-execute/SKILL.md` — plan execution with quality gates
-  - `.agents/skills/gsdd-verify/SKILL.md` — phase goal-backward verification
-  - `.agents/skills/gsdd-audit-milestone/SKILL.md` — milestone integration audit
-- Supporting workflows:
-  - `.agents/skills/gsdd-quick/SKILL.md` — sub-hour tasks outside the phase cycle
-  - `.agents/skills/gsdd-map-codebase/SKILL.md` — codebase analysis and refresh
-  - `.agents/skills/gsdd-pause/SKILL.md` — session checkpoint
-  - `.agents/skills/gsdd-resume/SKILL.md` — session context restore and routing
-  - `.agents/skills/gsdd-progress/SKILL.md` — read-only status and next-action routing
-
-### How To Invoke Workflows
-
-How you run these workflows depends on your tool:
-
-- **Claude Code / OpenCode / Cursor / Copilot / Gemini:** Use slash commands — `/gsdd-new-project`, `/gsdd-plan`, `/gsdd-execute`, etc.
-- **Codex CLI:** Use skill references — `$gsdd-new-project`, `$gsdd-plan`, `$gsdd-execute`, etc.
-- **Other AI tools:** Open the SKILL.md file listed above and follow its instructions.
-
-If this root `AGENTS.md` block is present in a Cursor, Copilot, or Gemini project, treat it as behavioral governance on top of the runtime's native slash-command discovery. Do not treat this file as the mechanism that makes the workflows discoverable.
-
-Start with the new-project workflow to produce `.planning/SPEC.md` and `.planning/ROADMAP.md`.

package/distilled/templates/agents.md

@@ -1,12 +1,5 @@
 # AGENTS.md - GSDD Governance
 
-This file is generated by `gsdd` when requested for runtimes that use AGENTS.md governance surfaces.
-It provides the universal governance layer for agents that support the AGENTS.md convention.
-
-See also:
-- Skills (preferred workflow entrypoints): `.agents/skills/gsdd-*/SKILL.md`
-- Planning workspace: `.planning/`
-
 <!-- BEGIN GSDD -->
 {{GSDD_BLOCK}}
 <!-- END GSDD -->

package/distilled/templates/delegates/plan-checker.md

@@ -1,6 +1,6 @@
 **Role contract:** Read `.planning/templates/roles/planner.md` before starting. Reuse its planning vocabulary and quality standards, but this wrapper overrides your objective: you are reviewing plans, not authoring them.
 
-You are the fresh-context plan checker for `/gsdd:plan`.
+You are the fresh-context plan checker for `/gsdd-plan`.
 
 Read only the explicit inputs provided by the orchestrator:
 - target phase goal and requirement IDs
@@ -21,7 +21,10 @@ Verify these dimensions:
 - `key_link_completeness`: important wiring/integration links are planned, not just isolated artifacts
 - `scope_sanity`: plans are sized so an executor can complete them without context collapse
 - `must_have_quality`: success criteria and must-haves are specific, observable, and reflected in tasks
-- `context_compliance`: locked decisions are honored and deferred ideas stay out of scope
+- `context_compliance`: locked decisions are honored and deferred ideas stay out of scope. Additionally check scope consistency:
+  - **Must-have coverage?** Every must-have requirement mapped to this phase in SPEC.md must appear in at least one plan task. A must-have that silently disappears from the plan is a `blocker`.
+  - **Deferred exclusion?** Items marked "Nice to Have", "Deferred", or "Out of Scope" in SPEC.md must not appear as plan tasks. Present → `blocker`.
+  - **Cross-surface consistency?** If SPEC.md marks an item as must-have but APPROACH.md marks it as deferred (or vice versa), surface the contradiction → `blocker`. Include a `fix_hint` asking the planner to resolve the conflict with the user before proceeding.
 - `goal_achievement`: does the plan, if executed perfectly, actually achieve the stated phase goal? Check:
   - **Goal addressed?** Compare the phase goal statement to the plan's collective task outputs. Would successful completion of all tasks deliver the goal? If the goal says "users can authenticate" but tasks only set up database schema → `blocker`.
   - **Success criteria reachable?** Are the phase success criteria from ROADMAP.md achievable through the planned tasks? Each success criterion should be traceable to at least one task's verify output → `blocker` if unreachable.
@@ -30,7 +33,7 @@ Verify these dimensions:
   - **Chosen honored?** Does each plan task align with the approach chosen in APPROACH.md for its gray area? A task that implements an alternative the user explicitly rejected -> `blocker`.
   - **Discretion respected?** "Agent's Discretion" items allow planner flexibility — do NOT flag these as misalignment.
   - **Deferred excluded?** Deferred ideas from APPROACH.md must not appear in plan tasks -> `blocker` if found.
-  - If no APPROACH.md was provided, skip this dimension entirely.
+  - If `workflow.discuss` is `true` in the project config and no APPROACH.md was provided, emit a `blocker` on `approach_alignment` with `description: 'workflow.discuss is true but no APPROACH.md was provided'` and `fix_hint: 'Run approach exploration before planning — workflow.discuss=true requires an approved APPROACH.md before a plan can be emitted.'` If `workflow.discuss` is `false` or the key is absent and no APPROACH.md was provided, skip this dimension entirely.
 
 Return JSON only as a single object with this shape:
 

package/distilled/workflows/audit-milestone.md

@@ -160,7 +160,7 @@ Plus full markdown report body with tables for requirements, phases, integration
 - `gaps_found` - critical blockers exist (unsatisfied requirements, unprotected sensitive flows, broken flows, or missing verifications)
 - `tech_debt` - no blockers but accumulated deferred items need review
 
-**MANDATORY: The milestone audit report must exist at `.planning/v{version}-MILESTONE-AUDIT.md` on disk before presenting results. If the file was not written, STOP and report the write failure. Do NOT present audit results from conversation context alone — this is the highest-cost artifact to regenerate.**
+**MANDATORY: The milestone audit report must exist at `.planning/v{version}-MILESTONE-AUDIT.md` on disk before presenting results. If the file was not written, STOP and report the write failure. Do NOT present audit results from conversation context alone — this is the highest-cost artifact to regenerate. Do NOT downgrade a write failure into "results shown inline anyway."**
 
 ## 7. Present Results
 
@@ -205,17 +205,17 @@ Report the audit result to the user, then present the next step:
 **Completed:** Milestone audit — created `.planning/v{version}-MILESTONE-AUDIT.md`.
 
 If status is `passed`:
-**Next step:** `/gsdd:complete-milestone` — archive the milestone and prepare for the next
+**Next step:** `/gsdd-complete-milestone` — archive the milestone and prepare for the next
 
 If status is `gaps_found`:
-**Next step:** `/gsdd:plan` — plan gap-closure phases for the unsatisfied requirements
+**Next step:** `/gsdd-plan-milestone-gaps` — create gap-closure phases for the unsatisfied requirements
 
 If status is `tech_debt`:
-**Next step:** Either `/gsdd:complete-milestone` (accept debt) or `/gsdd:plan` (cleanup phase)
+**Next step:** Either `/gsdd-complete-milestone` (accept debt) or `/gsdd-plan` (cleanup phase)
 
 Also available:
-- `/gsdd:verify` — re-verify a specific phase before re-auditing
-- `/gsdd:progress` — check overall project status
+- `/gsdd-verify` — re-verify a specific phase before re-auditing
+- `/gsdd-progress` — check overall project status
 
 Consider clearing context before starting the next workflow for best results.
 ---

package/distilled/workflows/complete-milestone.md

@@ -0,0 +1,297 @@
+<role>
+You are the MILESTONE CLOSER. Your job is to formally archive a shipped milestone — gather stats, archive planning artifacts, evolve SPEC.md, collapse the roadmap, and prepare for the next cycle.
+
+Core mindset: archive facts, not intentions. Every claim in the archived record must be derivable from phase SUMMARY.md files or git history.
+
+Scope boundary: you archive the current milestone. You do not start the next one — that is `/gsdd-new-milestone` territory.
+</role>
+
+<prerequisites>
+`.planning/ROADMAP.md` must exist with phases.
+`.planning/SPEC.md` must exist.
+If `.planning/MILESTONES.md` does not exist, create it now (this is the first milestone completion — Step 8 will write the first entry).
+
+If `.planning/milestones/` does not exist, create it before writing archive files.
+</prerequisites>
+
+<load_context>
+Before starting, read these files:
+
+1. `.planning/ROADMAP.md` — phase statuses, milestone name, phase range
+2. `.planning/SPEC.md` — requirements, validated capabilities, current state section
+3. `.planning/MILESTONES.md` — previous milestone entries (for format reference); if this is the first milestone, skip — no previous entries exist yet
+4. `.planning/config.json` — `gitProtocol`, `mode` (for STOP gate behavior)
+5. All phase SUMMARY.md files in `.planning/phases/` — accomplishments, task counts
+6. Most recent `.planning/v*-MILESTONE-AUDIT.md` — audit status (passed / gaps_found)
+</load_context>
+
+<process>
+
+## 1. Verify Readiness
+
+Check:
+- **Phase completion**: Are all ROADMAP.md phases for this milestone marked `[x]`? List any that are not.
+- **Audit status**: Does a MILESTONE-AUDIT.md exist and have status `passed`? If it has status `gaps_found`, the milestone has open gaps.
+- **Spent-branch guard**: Run `git branch --merged origin/main` (substitute `master` or the configured default branch from `config.json → gitProtocol.branch` if different) and verify HEAD is not a spent/already-merged branch. If the current branch already backs a merged PR, STOP - do not instruct any commit or tag operations. Prompt the user to check out a fresh active branch before continuing.
+- **Integration-surface warning pass**: Inspect staged, unstaged, untracked, unpushed, and PR-less local truth separately from the milestone artifacts. Warn if the archive is being attempted from a mixed-scope or stale branch even when the milestone documents themselves look complete.
+
+**If phases incomplete or audit not passed:**
+
+Present options:
+1. **Proceed anyway** — archive with known gaps noted in MILESTONES.md
+2. **Run audit first** — `/gsdd-audit-milestone` (if audit is missing or stale)
+3. **Close gaps first** — `/gsdd-plan-milestone-gaps` (if audit found gaps)
+4. **Abort** — stop without archiving
+
+**STOP. Wait for user selection.**
+
+Exception: if `config.json -> mode` is `yolo`, skip the stop gate and proceed with a note about any gaps.
+
+**If all phases complete and audit passed:** Proceed.
+
+## 2. Determine Version
+
+Parse the in-progress milestone version from ROADMAP.md (e.g., the `🚧` or active entry in the Milestones list). Confirm with user if unclear.
+
+## 3. Gather Stats
+
+Extract from phase SUMMARY.md files and git:
+
+- Phase count, plan count, task count (aggregate from SUMMARY files)
+- Test count if discernible from SUMMARY files
+- Start date (first phase completion date) and end date (today)
+- Brief git stats: `git log --oneline --since="[start date]" | wc -l` for commit count
+
+Present a concise stats block for review.
+
+## 4. Extract Accomplishments
+
+Read each phase SUMMARY.md in the milestone's phase range. Extract a one-liner from each phase describing the key delivery.
+
+Present 4-8 accomplishments for review. Trim or adjust with user before writing to archive.
+
+## 5. Archive Roadmap
+
+Create `.planning/milestones/v[X.Y]-ROADMAP.md` with full milestone details:
+
+```markdown
+# Milestone v[X.Y]: [Name]
+
+**Status:** ✅ SHIPPED [date]
+**Phases:** [N]–[M]
+**Total Plans:** [count]
+**Tag:** v[X.Y]
+
+## Overview
+
+[One paragraph describing what this milestone delivered and why it mattered.]
+
+## Phases
+
+### Phase [N]: [Name]
+
+**Goal**: [goal from ROADMAP.md]
+**Requirements**: [REQ-IDs]
+
+Plans:
+- [x] [plan summary from SUMMARY.md]
+
+**Details:**
+[Key implementation decisions and what was built]
+
+**Success Criteria verified:**
+1. [criterion]
+2. [criterion]
+
+---
+
+[Repeat for each phase]
+
+## Milestone Summary
+
+**Key Decisions:**
+- [Decision and rationale from phase summaries]
+
+**Issues Resolved:**
+- [What gaps/issues were closed this milestone]
+
+**Issues Deferred (LATER):**
+- [Any LATER-tagged items not addressed]
+
+**Technical Debt Incurred:**
+- [Any known shortcuts or deferred quality work]
+
+---
+
+*For current project status, see `.planning/ROADMAP.md`*
+```
+
+## 6. Archive Requirements
+
+Create `.planning/milestones/v[X.Y]-REQUIREMENTS.md`:
+
+```markdown
+# Requirements Archive: v[X.Y] Milestone
+
+**Archived:** [date]
+**Milestone:** [name]
+**Source:** `.planning/SPEC.md` requirements section at milestone completion
+
+---
+
+## v1 Must-Have Requirements (all satisfied)
+
+| ID | Title | Status | Phase | Outcome |
+|----|-------|--------|-------|---------|
+| [ID] | [title] | ✅ verified | Phase [N] | [brief outcome] |
+
+**Result: [N]/[N] requirements satisfied**
+
+---
+
+## Validated (pre-existing capabilities confirmed at milestone)
+
+[Copy from SPEC.md Validated section]
+
+---
+
+## Nice to Have (v2 — deferred)
+
+[Copy from SPEC.md Nice to Have section]
+
+---
+
+*Source: `.planning/SPEC.md` as of [date]*
+*Next milestone requirements: defined via `/gsdd-new-milestone`*
+```
+
+## 7. Move Audit File
+
+If `.planning/v[X.Y]-MILESTONE-AUDIT.md` exists, note its location in the MILESTONES.md entry. (Leave the file in `.planning/` — it is already in the gitignored planning directory. No move required unless you prefer to co-locate it with the other archives.)
+
+## 8. Update MILESTONES.md
+
+Append an entry to `.planning/MILESTONES.md`:
+
+```markdown
+## ✅ v[X.Y] — [Name] ([date])
+
+**Phases:** [N]–[M] | **Plans:** [count] | **Tasks:** [count] | **Tests:** [N] assertions, 0 failures
+
+**Delivered:** [One sentence summary of what shipped.]
+
+**Key accomplishments:**
+1. [Accomplishment 1]
+2. [Accomplishment 2]
+3. [Accomplishment 3]
+4. [Accomplishment 4]
+
+**Archive:** `.planning/milestones/v[X.Y]-ROADMAP.md`
+**Requirements:** `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
+**Tag:** `v[X.Y]`
+```
+
+## 9. Evolve SPEC.md
+
+Update SPEC.md to reflect the completed milestone:
+
+**Move shipped requirements:**
+- Move all Must Have requirements that were satisfied this milestone to the `### Validated (existing capabilities)` section
+- Format: `- [x] **[ID]**: [title] — [brief outcome note]`
+
+**Update Current State section:**
+
+```markdown
+## Current State
+
+- **Milestone:** v[X.Y] [Name] — SHIPPED [date]
+- **Phases:** [N]–[M] complete, all requirements verified ([N]/[N]), [test count] tests passing
+- **Archive:** `.planning/milestones/v[X.Y]-ROADMAP.md`
+- **Decisions:** [D1–DN] evidence-backed, all in [reference if applicable]
+- **Blockers:** None — [list any LATER-priority gaps if applicable]
+- **Next:** `/gsdd-new-milestone` to plan v[X.next] work
+
+---
+*Last updated: [date] after v[X.Y] milestone completion*
+```
+
+## 10. Collapse ROADMAP.md
+
+Replace the active milestone phases in ROADMAP.md with a collapsed `<details>` block and add the milestone to the Milestones list:
+
+```markdown
+# Roadmap: [Project Name]
+
+## Milestones
+
+- ✅ **v[X.Y] [Name]** — Phases [N]–[M] (shipped [date])
+
+## Phases
+
+<details>
+<summary>✅ v[X.Y] [Name] (Phases [N]–[M]) — SHIPPED [date]</summary>
+
+- [x] **Phase [N]: [Name]** — completed [date]
+- [x] **Phase [N+1]: [Name]** — completed [date]
+[...]
+
+Full details: [`.planning/milestones/v[X.Y]-ROADMAP.md`](milestones/v[X.Y]-ROADMAP.md)
+
+</details>
+
+---
+*Created: [original creation date] | v[X.Y] archived: [today]*
+```
+
+## 11. Advisory: Git Tag
+
+Suggest a git tag for the milestone. Do not mandate it — follow `config.json -> gitProtocol`.
+
+```
+Advisory: Tag this milestone in git:
+  git tag -a v[X.Y] -m "v[X.Y] [Name] — [one sentence summary]"
+  git push origin v[X.Y]  # if pushing to remote
+```
+
+- Use only user-facing version identifiers and plain descriptions in tag messages, commit summaries, and PR text. Do not include internal phase IDs, requirement IDs, or local milestone tracking labels.
+
+</process>
+
+<success_criteria>
+- [ ] Readiness verified (phases complete + audit passed, or user chose to proceed with gaps)
+- [ ] Version confirmed
+- [ ] Stats gathered from SUMMARY.md files and git
+- [ ] Accomplishments extracted and reviewed
+- [ ] `.planning/milestones/v[X.Y]-ROADMAP.md` created with full phase details
+- [ ] `.planning/milestones/v[X.Y]-REQUIREMENTS.md` created with all requirement statuses
+- [ ] `.planning/MILESTONES.md` updated with new entry
+- [ ] SPEC.md Must Have requirements moved to Validated section
+- [ ] SPEC.md Current State updated to reflect shipped status
+- [ ] ROADMAP.md collapsed with `<details>` block pointing to archive
+- [ ] Advisory git tag suggestion presented
+</success_criteria>
+
+**MANDATORY: All archive files (v[X.Y]-ROADMAP.md, v[X.Y]-REQUIREMENTS.md), MILESTONES.md, SPEC.md, and ROADMAP.md must be written to disk before this workflow is complete. If any write fails, STOP and report the failure. These artifacts are the durable record — without them, the milestone history is lost.**
+
+<completion>
+Report to the user what was archived, then present the next step:
+
+---
+**Completed:** Milestone v[X.Y] [Name] archived.
+
+Archived:
+- `.planning/milestones/v[X.Y]-ROADMAP.md` — full phase details
+- `.planning/milestones/v[X.Y]-REQUIREMENTS.md` — requirements at milestone completion
+- `.planning/MILESTONES.md` — updated milestone history
+- `.planning/SPEC.md` — requirements evolved, current state updated
+- `.planning/ROADMAP.md` — active phases collapsed to `<details>`
+
+**Next step:** `/gsdd-new-milestone` — start the next milestone cycle
+
+Also available:
+- `/gsdd-progress` — check overall project status
+- `/gsdd-audit-milestone` — re-audit before archiving (if you skipped the audit)
+
+Consider clearing context before starting the next workflow for best results.
+---
+</completion>