dsh-gsd-bundle

dsh-gsd-bundle

A plugin bundle for DeepSeek Harness (dsh) that reimplements opengsd-core — Git Ship Done (GSD) — as a set of host-plane Cordis plugins. It replaces the default agent-loop behaviour with the GSD phase loop, so every session becomes a disciplined, artefact-driven engineering loop.

Spec → Discuss → (UI design, optional) → Plan → Execute → Verify → Ship

Every unit of work is a phase that moves through these steps in order, wrapped by advisory soft gates (gap-analysis after Plan, code-review and UI-review after Execute, validate before Ship). State survives across sessions and context resets on disk under .planning/, with STATE.md as the navigation spine. Heavy work (research, planning, execution, verification, review) runs in fresh-context subagents spawned by the orchestrator, so the main session stays lean.

Release status

Milestone core-loop-helpers v3.1 is complete and released as v3.1.0 — this final 8-phase delta (phases 52–59) completes the bundle's parity with upstream opengsd-core's command surface: phase management, smart entry, freeform routing, quick batching, fast mode, MVP scoping, bounded node repair, and the rebuilt code-review fix companion. It follows the v3.0 upstream-parity milestone, which brought the full upstream step surface (spec, gap-analysis, code-review, UI-review, validate, undo, health, milestone-audit, learnings, graphify, mempalace, assumption-delta, pause/resume-work, autonomous, add-tests, and the direct phase-branch clean-PR model). The earlier v2.2 public-launch, v2.1 public-release-readiness, v2.0 graceful-removal, and v1.7 job-intel-multiwindow milestones remain prior releases. The surface today: 28 Cordis plugin rows (1 override + 27 inserts), 37 gsd_* tools, and 34 /gsd-* commands — all proven by the mount and per-plugin removal suites.

v3.1 release note — core-loop-helpers

The v3.1 milestone adds eight core-loop helper commands, completing the phase-loop tooling surface. It delivered:

• Phase-management — gsd_phase (/gsd-phase-manage): add, insert, remove, reorder, and edit phases directly in ROADMAP.md with validation and integrity checks; ROADMAP.md, its ## Progress table, and STATE.md progress stay consistent and commit atomically.
• Smart-entry — gsd_next (/gsd-next): detect the current project state and route to the best next action, with an auto-advance option.
• Freeform-routing — gsd_route (/gsd-route): parse a plain-English intent and dispatch it to the most appropriate GSD command — recommend-only; never auto-runs.
• Quick-batch — gsd_quick_batch (/gsd-quick-batch): run multiple quick tasks in a single batch with per-task results and failure isolation.
• Fast-mode — gsd_fast_mode (/gsd-fast-mode): a lightweight single-pass fast path (auto-derive CONTEXT → execute → summary → verify → ship) for simple phases.
• MVP-phase — gsd_mvp_phase (/gsd-mvp-phase): an interactive propose-then-confirm scoping flow that produces a real PLAN.md and delegates to the normal loop; refuses completed phases and never auto-retries on failure.
• Node-repair — gsd_repair (/gsd-repair): bounded automatic recovery for a phase whose verification returned gaps — up to 2 rounds of gsd_plan --gaps → gsd_execute --gaps-only → gsd_verify --gaps, stopping with clear causes; writes <NN>-REPAIR.md.
• Review-fix-companion — the gsd_code_review --fix companion rebuilt on a bounded anchor-edit contract: per-fix atomic commits with real commit hashes, skip-and-continue fault isolation, a node --check parse gate before write, and REVIEW-FIX.md reporting that works in live sessions.

v3.0 release note — upstream-parity

The v3.0 milestone brings the bundle to full parity with upstream opengsd-core's phase loop and step surface. It delivered:

• Spec-phase — gsd_spec_phase: a spec step that produces a SPEC.md with falsifiable Current/Target/Acceptance requirements, gated by an ambiguity-scoring score (≤ 0.20 across four weighted clarity dimensions).
• Gap-analysis — gsd_gap_analysis: a post-planning coverage tool emitting a deterministic REQ-ID/D-ID vs plan-body coverage table (<NN>-COVERAGE.md).
• Code-review — gsd_code_review: a post-execute review pass producing REVIEW.md with severity-classified findings (BLOCKER/WARNING/INFO).
• UI-review — gsd_ui_review: a retroactive 6-pillar UI audit producing UI-REVIEW.md (overall /24).
• Validate-phase — gsd_validate_phase: a retro audit mapping each phase requirement to the test infra, classifying COVERED/PARTIAL/MISSING/Manual-Only (<NN>-VALIDATION.md).
• Undo — gsd_undo: a safe rollback path via git revert with dependency checks and a dry-run-by-default confirmation gate.
• Health — gsd_health: a .planning/ integrity diagnostic (phase/plan numbering, orphan SUMMARYs, STATE/ROADMAP disagreement) with non-destructive config-only repair.
• Milestone-audit — gsd_milestone_audit: the milestone close-gate aggregating per-phase verifications, plus a cross-phase UAT outstanding-items list.
• Learnings — gsd_extract_learnings: cross-phase learnings extraction into a carrying-forward .planning/LEARNINGS.md.
• Graphify — gsd_graphify: a project knowledge graph in .planning/graphs/ with build/query/status modes.
• Mempalace — cross-session memory capture/recall (see Mempalace).
• Assumption-delta — an advisory architecture checkpoint wired into gsd_plan (plan:pre): when a phase makes something plural/optional/chosen that used to be singular/required/derived, it surfaces one identity-model question (promote vs add-alongside). Gated by workflow.assumption_delta; a pure deterministic scan, never an LLM judgment.
• Pause-resume-work — gsd_pause_work / gsd_resume_work: a structured mid-phase context handoff (HANDOFF.json + a .continue-here.md pointer, committed as a WIP commit) and its resume counterpart.
• Autonomous — gsd_autonomous: drives every remaining incomplete phase of the active milestone end-to-end (discuss → plan → execute → verify per phase) without per-phase manual prompting; stops on a hard failure, never ships.
• Add-tests — gsd_add_tests: a test generator creating Unit/Integration tests for a completed phase from its SUMMARY/CONTEXT/VERIFICATION and implementation, committed atomically (<NN>-ATEST.md).
• Drop-clean-branch — gsd_ship now pushes and PRs the phase-<NN> branch directly (one branch per phase); no separate clean review branch is built.

v2.2 release note — public-launch

The v2.2 milestone makes the GSD bundle publish-ready for npm and surfaces its health at a glance. It delivered:

• Provenance/health badge row — the README now carries a single-line row of three clickable badges directly under the H1: the whole CI workflow status, the MIT license, and an npm-version badge statically pinned to the released version.
• Repo discoverability — repository topics and the homepage are configured so the package is findable on GitHub and the npm registry.
• README-linked documentation shipped — the npm files whitelist was expanded to ship DISTRIBUTION.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, and CHANGELOG.md in the package.
• Security + contribution surface — a SECURITY.md and GitHub issue/PR templates were added so the repo is ready for external contributors.
• Released as v2.2.0 — the @dsh-gsd/bundle package is published with full npm metadata (repository, homepage, bugs, keywords, engines, author).

v2.1 release note — public-release-readiness

The v2.1 milestone hardens the GSD bundle for public release — licensing and attribution, repository hygiene, CI and security, distribution research, and a deterministic pre-ship verification gate. It delivered:

• License-and-attribution — added an MIT LICENSE, verified opengsd-core attribution and license compliance in NOTICE, and fixed the broken opengsd-core reference in the README.
• Repo-hygiene — added CHANGELOG.md, CONTRIBUTING.md, and CODE_OF_CONDUCT.md, and applied the .planning/ keep-vs-gitignore-vs-curate decision.
• Ci-and-security — added a GitHub Actions test workflow (.github/workflows/ci.yml) running the suite on pull requests and push to main, committed a package-lock.json for reproducible npm ci installs, and added a gitleaks secret-scan guard that fails a PR if a new secret is introduced.
• Publish-research — a research-backed distribution decision for the bundle, recorded in DISTRIBUTION.md.
• Pre-ship-verify — a new deterministic pre-ship verification gate in gsd_ship that runs npm ci + npm test in a temp copy of the repo before pushing, skippable via a flag.

v2.0 release note — graceful-removal

The v2.0 milestone proves the whole GSD plugin bundle is swappable and customizable — every step plugin can be retired and the loop keeps working. It delivered:

• Capability-services — each step plugin publishes a capability service declaring the loop step it provides; the persona and slash-command layer declare coeffects on the capabilities they need.
• Reactive-loop-rendering — the persona, runtime-context snapshot, and gsd_status re-render from the available step capabilities, so absent steps are skipped and no missing tool is ever instructed.
• Removal-verification — an automated per-plugin removal test proving every single step plugin can be retired with its effects reverted and the remaining loop still functional end-to-end.
• Composability-hardening — the background-job live registry is effect-scoped to its owning fiber so unload/HMR cancels running jobs, and the subagents coeffect is declared in every consuming plugin so temporal and spatial composability hold for the job runtime and subagent paths.

Features

The phase loop, as model-facing tools:

• Spec → Discuss → (UI) → Plan → Execute → Verify → Ship — every step is a tool: gsd_spec_phase (optional falsifiable SPEC.md), gsd_discuss (CONTEXT.md), gsd_ui_phase (UI-SPEC.md), gsd_plan (researcher → planner → plan-checker, dependency waves), gsd_execute (fresh-context executors, atomic commits, checkpoint-resume), gsd_verify (VERIFICATION.md + status routing), gsd_ship (preflight, capability gates, pre-ship-verify, PR).
• Advisory soft gates around the loop — gsd_gap_analysis (post-plan coverage table), gsd_code_review (REVIEW.md, with an optional --fix companion that applies findings as per-fix atomic commits into REVIEW-FIX.md), gsd_ui_review (6-pillar UI audit), gsd_validate_phase (requirement→test coverage audit). Each is gated by its own workflow.* config flag and never blocks the next loop step.
• Bounded auto-recovery — gsd_repair runs up to 2 rounds of plan(gaps) → execute(gaps-only) → verify(gaps) for a phase whose verification found gaps, stopping with clear causes on anything it cannot recover from.
• Autonomous path — gsd_autonomous drives all remaining incomplete phases of the active milestone end-to-end (auto-deriving CONTEXT when absent) and reports a per-phase STATUS; it stops on a hard failure, never ships, and never runs milestone lifecycle.
• Orientation helpers — gsd_init, gsd_status, gsd_progress, gsd_next (state detection + next-action routing, with auto-advance), gsd_route (recommend-only plain-English intent dispatch), gsd_progress, and gsd_new_milestone.
• Sub-threshold quick path — gsd_quick for single-turn tasks, plus gsd_quick_batch for many with failure isolation, gsd_fast_mode for simple phases, and gsd_mvp_phase for propose-then-confirm minimal-viable scoping.
• Phase management + out-of-band tools — gsd_phase (add/insert/remove/reorder/edit phases with ROADMAP/STATE integrity checks), gsd_undo (git-revert rollback with dependency checks), gsd_health (.planning/ integrity diagnostic), gsd_pause_work / gsd_resume_work (mid-phase handoff + resume), and gsd_intel_updater (targeted codebase-map re-map of drifted paths).

Milestone close-out and memory:

• Milestone-audit, learnings, graphify — gsd_milestone_audit (close-gate audit report), gsd_extract_learnings (carrying-forward LEARNINGS.md), and gsd_graphify (a project knowledge graph in .planning/graphs/ with build/query/status).
• Mempalace — opt-in cross-session memory: deliberate recall before discuss/plan (MEMORY-RECALL.md) and verbatim artifact capture at phase boundaries, through an injectable CLI seam.
• Add-tests — gsd_add_tests generates unit/integration tests for a completed phase from its artifacts and commits them atomically.
• Assumption-delta checkpoint — a rarely-firing advisory identity-model question surfaced by gsd_plan when a phase generalizes a previously singular/required/derived concept.

Platform properties (carried from earlier milestones):

• A durable .planning/ artefact model — PROJECT.md, ROADMAP.md, REQUIREMENTS.md, STATE.md, config.json, per-phase artefacts, milestone audit reports, the codebase map, and the knowledge graph (see the full tree below).
• Checkpoint-resume & conversational UAT — an interrupted gsd_execute resumes from its last checkpoint; a checkpoint:decision / checkpoint:human-action task surfaces a human-facing question and the plan resumes with the answer applied.
• Capability gates & pre-ship-verify — gsd_ship runs the security / broken-windows / TDD-audit gates (with a skip_gates escape hatch) and a deterministic npm ci + npm test verification in a temp copy of the repo before pushing.
• Real background-job runtime — gsd_job launches shell/subagent jobs with timeouts, cancellation, and retry; lifecycle is tracked in the async-jobs.json manifest and reflected through gsd_status.
• Window ledger — a root-level WINDOWS.md multi-window ledger, surfaced through gsd_status.
• Brownfield codebase mapping — gsd_map_codebase analyses an existing codebase with parallel fresh-context mappers (7 documents), answers --query questions against the map, detects drift, and re-maps targeted paths via gsd_intel_updater.
• Capability-services & reactive rendering — every step plugin publishes a capability service; the persona, runtime-context snapshot, and gsd_status re-render from the available capabilities, so a retired or replaced step is simply skipped.
• Swappable & customizable — an automated per-plugin removal suite proves every step plugin can be retired with its effects reverted and the loop still functional end-to-end.
• Two driving UXes — natural language (the persona makes the agent a GSD driver) and the /gsd-* slash-command layer.

Prerequisites

• DeepSeek Harness (dsh) with the dsh CLI available on PATH.
• Node.js ≥ 20 (declared via the package's engines field).
• A git repository for the project you want to drive with GSD (the loop commits atomically and ships PRs via the gh CLI).
• The GitHub CLI (gh) installed and authenticated if you want gsd_ship to create pull requests.

Install

See DISTRIBUTION.md for the research-backed distribution decision.

Add the bundle to a dsh profile (it layers after dsh-base). The primary install path is the npm registry:

dsh plugin --profile <name> add @dsh-gsd/bundle
dsh --profile <name> web   # or tui / headless

Alternative — install from source

If you prefer a local/git checkout over the registry package, clone this repo and point dsh plugin add at the checkout path (pnpm resolves the local spec the same way it resolves the registry name):

git clone https://github.com/jaaty/dsh-gsd-bundle.git
dsh plugin --profile <name> add <path-to-this-bundle>
dsh --profile <name> web   # or tui / headless

The bundle's cordis.patch.yml overrides the host agent-loop row to configure a gsd agent and inserts the 27 GSD plugin rows. CLI profiles get the gsd startup agent; web sessions are created on demand and inherit the GSD persona + tools.

About the peer dependencies: @deepseek-ai/dsh-tools and @deepseek-ai/dsh-llm are imported directly by the bundle's modules. @deepseek-ai/schemastery and @deepseek-ai/cordis are host-contract peers — no module imports them; they are declared so npm installs a compatible host runtime, and the host supplies them via the injected ctx (tools/provide/get) at runtime. Both declarations are intentional.

Quickstart

In a session on a profile with the bundle mounted:

1. Bootstrap — gsd_init to create the .planning/ project (name, milestone, requirements, ordered phases).
2. Orient — gsd_status (or gsd_next / /gsd-next) to see where the loop stands and what to do next.
3. Run the loop — gsd_spec_phase (optional) → gsd_discuss → (optional gsd_ui_phase) → gsd_plan → gsd_execute → gsd_verify → gsd_ship, with the advisory soft gates (gsd_gap_analysis, gsd_code_review, gsd_ui_review, gsd_validate_phase) between steps when you want them.

Or just say "let's build X with GSD" — the persona already makes the agent a GSD phase-loop driver, pausing at decision points. You can also drive individual steps directly: "plan phase 1", "execute phase 1", "verify phase 1" — or let gsd_route recommend the right command for a plain-English intent.

The gsd_* tools

All tools are registered by the bundle's plugins and available to the model in any session on a mounted profile (37 tools across 27 plugins, proven by the mount test).

Orientation & entry (gsd-core-tools)

Loop steps

Advisory soft gates

Repair & orchestration

Out-of-band & close-out

Onboarding, quick work & memory

Slash-commands

The gsd-commands plugin registers the /gsd-* commands as thin routers — each injects a user message telling the agent to run the matching tool, then returns a short ack: