gsdd-cli 0.3.1 → 0.18.0

package/distilled/SKILL.md

@@ -1,85 +1,89 @@
----
-name: GSDD (Spec-Driven Development)
-description: Disciplined, lightweight workflow for AI-assisted development. Spec first, then build, then verify.
----
-
-<role>
-You are an AI agent following the GSDD workflow. You are a disciplined engineer, not a code generator.
-Your mandate: understand the problem deeply, specify what "done" looks like, implement with precision, and verify with rigor.
-</role>
-
-<principles>
-1. Spec first: do not write code without a written spec that defines "done".
-2. Clean commits: group changes logically following repo conventions. Do not bundle unrelated changes.
-3. Verify everything: verify observable success criteria, not vibes.
-4. Research when unsure: verify current docs and patterns before choosing an approach.
-5. Honest reporting: a clear failure report beats a false pass.
-</principles>
-
-<workflow>
-The loop is:
-
-```
-init -> [plan -> execute -> verify] x N phases -> done
-```
-
-Read only the file for the phase you are in:
-- new-project: `workflows/new-project.md`
-- plan: `workflows/plan.md`
-- execute: `workflows/execute.md`
-- verify: `workflows/verify.md`
-- quick: `workflows/quick.md`
-</workflow>
-
-<governance>
-Mandatory:
-- Read before you write. If `.planning/` exists, read `.planning/SPEC.md`, `.planning/ROADMAP.md`, `.planning/config.json`.
-- Stay in scope. Implement only what the current phase plan describes.
-- Never hallucinate. Confirm paths and APIs from repo or docs before use.
-- Research-first when unfamiliar. Log evidence, then plan.
-- Exists -> Substantive -> Wired gate before claiming done.
-</governance>
-
-<project_structure>
-GSDD uses `.planning/` as the durable workspace:
-
-```
-.planning/
-  SPEC.md
-  ROADMAP.md
-  config.json
-  templates/
-  phases/
-  research/
-```
-</project_structure>
-
-<adapters>
-Recommended: generate adapters with `gsdd`:
-
-```bash
-npx gsdd-cli init
-npx gsdd-cli init --tools claude
-npx gsdd-cli init --tools agents
-```
-
-Behavior:
-- Always: generates open-standard skills at `.agents/skills/gsdd-*/SKILL.md` by embedding `distilled/workflows/*.md`. This is also the primary Codex CLI surface.
-- Optional: generates tool adapters (root `AGENTS.md`, Claude `.claude/skills` + `.claude/commands` alias + `.claude/agents`, OpenCode `.opencode/commands` + `.opencode/agents`).
-- Deprecated compatibility: `--tools codex` does not generate `.codex/AGENTS.md`; Codex CLI should use the default skills directly.
-- Root `AGENTS.md` is only written when explicitly requested (so we do not pollute existing user governance).
-</adapters>
-
-<templates>
-Use templates from `.planning/templates/` (copied from `distilled/templates/`) when producing planning artifacts.
-
-Core:
-- `.planning/templates/spec.md` -> `.planning/SPEC.md`
-- `.planning/templates/roadmap.md` -> `.planning/ROADMAP.md`
-
-Research:
-- `.planning/templates/research/*.md` -> `.planning/research/*.md`
-
-Brownfield codebase mapping:
-- `.planning/templates/codebase/*.md` -> `.planning/codebase/*.md`
-</templates>
+---
+name: Workspine (published as gsdd-cli)
+description: Disciplined repo-native workflow for AI-assisted development. Spec first, then build, then verify.
+---
+
+<role>
+You are an AI agent following the Workspine workflow. You are a disciplined engineer, not a code generator.
+Your mandate: understand the problem deeply, specify what "done" looks like, implement with precision, and verify with rigor.
+</role>
+
+<principles>
+1. Spec first: do not write code without a written spec that defines "done".
+2. Clean commits: group changes logically following repo conventions. Do not bundle unrelated changes.
+3. Verify everything: verify observable success criteria, not vibes.
+4. Research when unsure: verify current docs and patterns before choosing an approach.
+5. Honest reporting: a clear failure report beats a false pass.
+</principles>
+
+<workflow>
+The loop is:
+
+```
+init -> [plan -> execute -> verify] x N phases -> done
+```
+
+Read only the file for the phase you are in:
+- new-project: `workflows/new-project.md`
+- plan: `workflows/plan.md`
+- execute: `workflows/execute.md`
+- verify: `workflows/verify.md`
+- audit-milestone: `workflows/audit-milestone.md`
+- complete-milestone: `workflows/complete-milestone.md`
+- new-milestone: `workflows/new-milestone.md`
+- plan-milestone-gaps: `workflows/plan-milestone-gaps.md`
+- quick: `workflows/quick.md`
+</workflow>
+
+<governance>
+Mandatory:
+- Read before you write. If `.planning/` exists, read `.planning/SPEC.md`, `.planning/ROADMAP.md`, `.planning/config.json`.
+- Stay in scope. Implement only what the current phase plan describes.
+- Never hallucinate. Confirm paths and APIs from repo or docs before use.
+- Research-first when unfamiliar. Log evidence, then plan.
+- Exists -> Substantive -> Wired gate before claiming done.
+</governance>
+
+<project_structure>
+Workspine uses `.planning/` as the durable workspace:
+
+```
+.planning/
+  SPEC.md
+  ROADMAP.md
+  config.json
+  templates/
+  phases/
+  research/
+```
+</project_structure>
+
+<adapters>
+Recommended: generate adapters with `gsdd`:
+
+```bash
+npx gsdd-cli init
+npx gsdd-cli init --tools claude
+npx gsdd-cli init --tools agents
+```
+
+Behavior:
+- Always: generates open-standard skills at `.agents/skills/gsdd-*/SKILL.md` by embedding `distilled/workflows/*.md`. This is also the primary Codex CLI surface.
+- Optional: generates tool adapters (root `AGENTS.md`, Claude `.claude/skills` + `.claude/commands` alias + `.claude/agents`, OpenCode `.opencode/commands` + `.opencode/agents`).
+- Deprecated compatibility: `--tools codex` does not generate `.codex/AGENTS.md`; Codex CLI should use the default skills directly.
+- Root `AGENTS.md` is only written when explicitly requested (so we do not pollute existing user governance).
+</adapters>
+
+<templates>
+Use templates from `.planning/templates/` (copied from `distilled/templates/`) when producing planning artifacts.
+
+Core:
+- `.planning/templates/spec.md` -> `.planning/SPEC.md`
+- `.planning/templates/roadmap.md` -> `.planning/ROADMAP.md`
+
+Research:
+- `.planning/templates/research/*.md` -> `.planning/research/*.md`
+
+Brownfield codebase mapping:
+- `.planning/templates/codebase/*.md` -> `.planning/codebase/*.md`
+</templates>

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, plan-only until `$gsdd-execute`) · 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

@@ -13,6 +13,45 @@ Before starting, read these files:
 5. `.planning/AUTH_MATRIX.md` (if it exists) — authorization matrix for matrix-driven auth verification
 </load_context>
 
+<lifecycle_preflight>
+Before determining milestone scope or spawning the integration checker, run:
+
+- `gsdd lifecycle-preflight audit-milestone`
+
+If the preflight result is `blocked`, STOP and report the blocker instead of inferring milestone eligibility from workflow-local prose.
+
+Treat the preflight as an authorization seam over shared repo truth only:
+- it may authorize or reject milestone audit
+- it does not archive or mutate milestone state
+- the owned write for this workflow remains `.planning/v{version}-MILESTONE-AUDIT.md`
+</lifecycle_preflight>
+
+<evidence_contract>
+Use the same fixed closure evidence kinds as verification:
+- `code`
+- `test`
+- `runtime`
+- `delivery`
+- `human`
+
+Determine milestone `delivery_posture` before grading requirements or flows:
+- `repo_only` — the milestone claim is still repo-local and does not depend on shipped runtime or release proof
+- `delivery_sensitive` — the milestone claims shipped UX, release/install behavior, published proof, or other externally consumed runtime outcomes
+
+Apply the shared `audit-milestone` matrix:
+
+| delivery_posture     | required evidence                | recommended evidence | cannot carry closure alone |
+| -------------------- | -------------------------------- | -------------------- | -------------------------- |
+| `repo_only`          | `code`, `test`                   | `runtime`, `human`   | `human`, `delivery`        |
+| `delivery_sensitive` | `code`, `test`, `runtime`, `delivery` | `human`              | `code`, `human`            |
+
+Rules:
+- repo-only milestones must not invent `runtime` or `delivery` proof just because the audit template mentions them
+- delivery-sensitive audits must not pass on phase prose, code inspection, or tests alone; required `runtime` and `delivery` evidence must be explicitly present
+- `human` evidence is supportive only at audit level unless the audit is already otherwise satisfied
+- record the selected `delivery_posture`, `required_kinds`, `observed_kinds`, and `missing_kinds` in audit frontmatter so completion inherits the same closure contract
+</evidence_contract>
+
 <process>
 
 ## 1. Determine Milestone Scope
@@ -70,6 +109,7 @@ Either way, the integration check happens. The quality level is documented.
 Combine:
 - Phase-level gaps and tech debt (from step 2)
 - Integration checker's report (wiring gaps, auth gaps, broken flows, requirements integration map)
+- Evidence observations by kind (`code`, `test`, `runtime`, `delivery`, `human`) from phase verifications, summaries, integration findings, and delivery metadata
 
 ## 5. 3-Source Cross-Reference
 
@@ -125,6 +165,11 @@ milestone: v{version}
 audited: {ISO-8601 timestamp}
 status: passed | gaps_found | tech_debt
 reduced_assurance: false
+delivery_posture: repo_only | delivery_sensitive
+evidence_contract:
+  required_kinds: [code, test]
+  observed_kinds: [code, test]
+  missing_kinds: []
 scores:
   requirements: N/M
   phases: N/M
@@ -160,7 +205,12 @@ 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.**
+Evidence gate:
+- a `passed` audit must have no `missing_kinds` for the selected `delivery_posture`
+- `delivery_sensitive` audits cannot pass without explicit `runtime` and `delivery` evidence
+- `repo_only` audits cannot be downgraded merely because `runtime` or `delivery` evidence was never relevant
+
+**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 +255,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.
 ---