golem15/msd-core
4
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: hard-fork GSD -> MSD (Make Software Done)

Browse Source 
Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD
across contents and paths, upstream package/repo coordinates -> @golem15/msd-core
and golem15com/msd-core. Deep links into upstream history, sibling upstream
packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is.

Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line,
package/plugin identity, regenerated lockfile, install-tree fixtures, derived
registries and benchmark baseline; migration checksum baseline re-locked
(MSD keeps its own install state, so no install had applied the old sums);
sort-order and regex-escaped expectations in tests adjusted.
This commit is contained in:
Jakub Zych
2026-10-06 01:47:40 +02:00
parent fe069b2a56
commit a9a7a328e6
2763 changed files with 78465 additions and 78434 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
docs/reference/planning-artifacts.md
View File

@@ -1,6 +1,6 @@
# Planning artifacts reference
The `.planning/` directory is GSD Core's shared memory for a project. Every workflow reads from it, writes to it, and leaves an auditable trail of decisions. This page maps every file, its purpose, and which command produces or consumes it. See [docs index](../README.md).
The `.planning/` directory is MSD Core's shared memory for a project. Every workflow reads from it, writes to it, and leaves an auditable trail of decisions. This page maps every file, its purpose, and which command produces or consumes it. See [docs index](../README.md).
---
@@ -50,34 +50,34 @@ The `.planning/` directory is GSD Core's shared memory for a project. Every work
| | |
|---|---|
| **Purpose** | Canonical project identity: what it is, who it is for, core value, requirements, constraints, and key decisions. Updated throughout the project lifecycle as the product evolves. |
| **Produced by** | `/gsd-new-project` (initial creation, including `/gsd-onboard` handoff); updated by `/gsd-complete-milestone` as decisions are validated. |
| **Consumed by** | All planning workflows; `gsd-phase-researcher`, `gsd-planner` (context); `discuss-phase` (prior decisions); `gsd-plan-checker` (project constraints). |
| **Produced by** | `/msd-new-project` (initial creation, including `/msd-onboard` handoff); updated by `/msd-complete-milestone` as decisions are validated. |
| **Consumed by** | All planning workflows; `msd-phase-researcher`, `msd-planner` (context); `discuss-phase` (prior decisions); `msd-plan-checker` (project constraints). |
Includes an optional `## Business Context` section (Customer, Revenue model, Success metric, Strategy notes) for monetized or customer-facing projects — four one-line fields that connect business outcomes to requirement prioritization. It is deleted for internal tools, experiments, or meta workspaces, and reviewed at each milestone by `/gsd-complete-milestone` when present.
Includes an optional `## Business Context` section (Customer, Revenue model, Success metric, Strategy notes) for monetized or customer-facing projects — four one-line fields that connect business outcomes to requirement prioritization. It is deleted for internal tools, experiments, or meta workspaces, and reviewed at each milestone by `/msd-complete-milestone` when present.
### `ROADMAP.md`
| | |
|---|---|
| **Purpose** | Milestone and phase listing with goals, requirement IDs, success criteria, and canonical references per phase. The single source of truth for what the project is building and in what order. |
| **Produced by** | `/gsd-new-project` (initial creation, including `/gsd-onboard` handoff); updated by `/gsd-phase --insert` and `/gsd-complete-milestone`. |
| **Consumed by** | `/gsd-discuss-phase`, `/gsd-plan-phase`, `/gsd-execute-phase`; all orchestration commands that need phase information; `gsd-planner`, `gsd-plan-checker`, `gsd-phase-researcher`. |
| **Produced by** | `/msd-new-project` (initial creation, including `/msd-onboard` handoff); updated by `/msd-phase --insert` and `/msd-complete-milestone`. |
| **Consumed by** | `/msd-discuss-phase`, `/msd-plan-phase`, `/msd-execute-phase`; all orchestration commands that need phase information; `msd-planner`, `msd-plan-checker`, `msd-phase-researcher`. |
### `REQUIREMENTS.md`
| | |
|---|---|
| **Purpose** | Numbered, checkable acceptance criteria for the project. Each requirement carries an ID (e.g., `AUTH-01`) that maps to roadmap phases. Marks requirements complete as phases are executed. |
| **Produced by** | `/gsd-new-project` (initial creation, including `/gsd-onboard` handoff); requirements marked complete by `execute-phase`. |
| **Consumed by** | `gsd-planner` (plans must address all phase requirement IDs); `gsd-plan-checker` Dimension 1 (requirement coverage); `discuss-phase` (prior requirements). |
| **Produced by** | `/msd-new-project` (initial creation, including `/msd-onboard` handoff); requirements marked complete by `execute-phase`. |
| **Consumed by** | `msd-planner` (plans must address all phase requirement IDs); `msd-plan-checker` Dimension 1 (requirement coverage); `discuss-phase` (prior requirements). |
### `STATE.md`
| | |
|---|---|
| **Purpose** | Living position tracker — current phase and plan, progress metrics, accumulated decisions, session continuity notes. Read at the start of every workflow run. Updated after every significant action. |
| **Produced by** | `/gsd-new-project` (initial creation, including `/gsd-onboard` handoff); updated continuously by all phase workflows, `/gsd-pause-work`, `/gsd-resume-work`. |
| **Consumed by** | All orchestration workflows; `/gsd-progress`; ad-hoc task execution via `/gsd-quick`; `gsd-planner` and `gsd-phase-researcher` (project decisions). |
| **Produced by** | `/msd-new-project` (initial creation, including `/msd-onboard` handoff); updated continuously by all phase workflows, `/msd-pause-work`, `/msd-resume-work`. |
| **Consumed by** | All orchestration workflows; `/msd-progress`; ad-hoc task execution via `/msd-quick`; `msd-planner` and `msd-phase-researcher` (project decisions). |
See [STATE.md schema](state-md.md) for the full field reference.
@@ -86,8 +86,8 @@ See [STATE.md schema](state-md.md) for the full field reference.
| | |
|---|---|
| **Purpose** | Workflow configuration: model profiles, research and plan-checker toggles, git branching strategy, Nyquist validation, parallelisation settings, and per-agent model overrides. |
| **Produced by** | `/gsd-new-project` (initial creation); `/gsd-settings` (interactive editing). |
| **Consumed by** | Every workflow and subagent — read at init time via `gsd-tools query config-get`. |
| **Produced by** | `/msd-new-project` (initial creation); `/msd-settings` (interactive editing). |
| **Consumed by** | Every workflow and subagent — read at init time via `msd-tools query config-get`. |
See [CONFIGURATION](../CONFIGURATION.md) for the complete schema.
@@ -95,17 +95,17 @@ See [CONFIGURATION](../CONFIGURATION.md) for the complete schema.
| | |
|---|---|
| **Purpose** | Brownfield onboarding index that records artifact status, whether codebase mapping is complete, and the next recommended GSD command after first-time setup. |
| **Produced by** | `/gsd-onboard` after `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, and `STATE.md` all exist. |
| **Consumed by** | Humans reviewing first-time setup; future `/gsd-onboard` runs when confirming existing onboarding state. |
| **Purpose** | Brownfield onboarding index that records artifact status, whether codebase mapping is complete, and the next recommended MSD command after first-time setup. |
| **Produced by** | `/msd-onboard` after `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, and `STATE.md` all exist. |
| **Consumed by** | Humans reviewing first-time setup; future `/msd-onboard` runs when confirming existing onboarding state. |
### `MILESTONES.md` (optional)
| | |
|---|---|
| **Purpose** | Historical record of completed milestones. Populated as each milestone is closed; provides an archival snapshot of what shipped and when. |
| **Produced by** | `/gsd-complete-milestone`. |
| **Consumed by** | `/gsd-audit-milestone`; human review. |
| **Produced by** | `/msd-complete-milestone`. |
| **Consumed by** | `/msd-audit-milestone`; human review. |
### `DECISIONS-INDEX.md` (optional)
@@ -120,8 +120,8 @@ See [CONFIGURATION](../CONFIGURATION.md) for the complete schema.
| | |
|---|---|
| **Purpose** | Machine-readable pause state written when work is interrupted. Contains the resume point, in-progress context, and continuation instructions. Consumed exactly once — on resume. |
| **Produced by** | `/gsd-pause-work`. |
| **Consumed by** | `/gsd-resume-work`. |
| **Produced by** | `/msd-pause-work`. |
| **Consumed by** | `/msd-resume-work`. |
---
@@ -134,8 +134,8 @@ All per-phase files live under `.planning/phases/<NN>-<slug>/` where `NN` is the
| | |
|---|---|
| **Purpose** | Implementation decisions captured before planning begins. Contains the phase boundary (`<domain>`), locked decisions with `D-NN` identifiers (`<decisions>`), canonical document references (`<canonical_refs>`), existing code insights (`<code_context>`), specific inspirations (`<specifics>`), and deferred ideas (`<deferred>`). |
| **Produced by** | `/gsd-discuss-phase` (interactive discussion or PRD/ADR express paths). |
| **Consumed by** | `gsd-phase-researcher` (what to investigate); `gsd-planner` (locked decisions); `gsd-plan-checker` Dimension 7 (context compliance). |
| **Produced by** | `/msd-discuss-phase` (interactive discussion or PRD/ADR express paths). |
| **Consumed by** | `msd-phase-researcher` (what to investigate); `msd-planner` (locked decisions); `msd-plan-checker` Dimension 7 (context compliance). |
See [CONTEXT.md schema](context-md.md) for the full field reference.
@@ -144,7 +144,7 @@ See [CONTEXT.md schema](context-md.md) for the full field reference.
| | |
|---|---|
| **Purpose** | Human-readable audit trail of the discuss-phase session: areas discussed, options presented, selections made, deferred ideas, and items left to Claude's discretion. Not consumed by automated workflows. |
| **Produced by** | `/gsd-discuss-phase` (`git_commit` step). |
| **Produced by** | `/msd-discuss-phase` (`git_commit` step). |
| **Consumed by** | Human review; retrospectives. |
### `<NN>-RESEARCH.md`
@@ -152,32 +152,32 @@ See [CONTEXT.md schema](context-md.md) for the full field reference.
| | |
|---|---|
| **Purpose** | Technical research findings produced before planning. Answers "What do I need to know to plan this phase well?" — covers domain analysis, patterns, risks, an Architectural Responsibility Map, and a Validation Architecture section (used by the Nyquist gate). |
| **Produced by** | `/gsd-plan-phase` via `gsd-phase-researcher` agent. |
| **Consumed by** | `gsd-planner` (planning inputs); `gsd-plan-checker` Dimension 7c (tier compliance), Dimension 8 (Nyquist), Dimension 11 (research resolution); `gsd-pattern-mapper` (file list source). |
| **Produced by** | `/msd-plan-phase` via `msd-phase-researcher` agent. |
| **Consumed by** | `msd-planner` (planning inputs); `msd-plan-checker` Dimension 7c (tier compliance), Dimension 8 (Nyquist), Dimension 11 (research resolution); `msd-pattern-mapper` (file list source). |
### `<NN>-VALIDATION.md`
| | |
|---|---|
| **Purpose** | Nyquist-inspired validation strategy derived from the `## Validation Architecture` section of RESEARCH.md. Specifies automated test coverage requirements that plans must honour. |
| **Produced by** | `/gsd-plan-phase` (Step 5.5, when `workflow.nyquist_validation` is enabled and RESEARCH.md contains a Validation Architecture section). |
| **Consumed by** | `gsd-plan-checker` Dimension 8 (Check 8e gate — must exist before Nyquist checks proceed); `gsd-verifier`. |
| **Produced by** | `/msd-plan-phase` (Step 5.5, when `workflow.nyquist_validation` is enabled and RESEARCH.md contains a Validation Architecture section). |
| **Consumed by** | `msd-plan-checker` Dimension 8 (Check 8e gate — must exist before Nyquist checks proceed); `msd-verifier`. |
### `<NN>-PATTERNS.md`
| | |
|---|---|
| **Purpose** | Codebase analog map produced by `gsd-pattern-mapper`. For each file to be created or modified this phase, identifies the closest existing analog, classifies the file's role and data flow, and extracts concrete code excerpts. Guides the planner towards consistent patterns. |
| **Produced by** | `/gsd-plan-phase` via `gsd-pattern-mapper` agent (optional; skipped if `workflow.pattern_mapper: false`). |
| **Consumed by** | `gsd-planner` (pattern guidance); `gsd-plan-checker` Dimension 12 (pattern compliance). |
| **Purpose** | Codebase analog map produced by `msd-pattern-mapper`. For each file to be created or modified this phase, identifies the closest existing analog, classifies the file's role and data flow, and extracts concrete code excerpts. Guides the planner towards consistent patterns. |
| **Produced by** | `/msd-plan-phase` via `msd-pattern-mapper` agent (optional; skipped if `workflow.pattern_mapper: false`). |
| **Consumed by** | `msd-planner` (pattern guidance); `msd-plan-checker` Dimension 12 (pattern compliance). |
### `<NN>-<PP>-PLAN.md`
| | |
|---|---|
| **Purpose** | Executable plan for a single unit of work within the phase. Contains YAML frontmatter (wave, dependencies, files, requirements, `must_haves`), an objective, context references, XML-structured tasks with `<read_first>`, `<action>`, `<verify>`, and `<acceptance_criteria>` fields, and verification criteria. |
| **Produced by** | `/gsd-plan-phase` via `gsd-planner` agent. One file per plan — e.g., `03-02-PLAN.md` is Phase 3, Plan 2. |
| **Consumed by** | `/gsd-execute-phase` (executor agent reads plan and runs tasks); `gsd-plan-checker` (pre-execution quality review); `gsd-verifier` (reads `must_haves` for post-execution verification). |
| **Produced by** | `/msd-plan-phase` via `msd-planner` agent. One file per plan — e.g., `03-02-PLAN.md` is Phase 3, Plan 2. |
| **Consumed by** | `/msd-execute-phase` (executor agent reads plan and runs tasks); `msd-plan-checker` (pre-execution quality review); `msd-verifier` (reads `must_haves` for post-execution verification). |
See [PLAN.md schema](plan-md.md) for the full field reference.
@@ -187,7 +187,7 @@ See [PLAN.md schema](plan-md.md) for the full field reference.
|---|---|
| **Purpose** | Execution record written after a plan completes. Documents what was built, deviations from the plan, a self-check against acceptance criteria, and the dependency graph for the phase. |
| **Produced by** | `execute-phase` executor agent (written at the end of each plan's execution). |
| **Consumed by** | `/gsd-progress` (phase status); `gsd-planner` (when a subsequent plan has a genuine dependency on prior plan output); `milestone-summary`. |
| **Consumed by** | `/msd-progress` (phase status); `msd-planner` (when a subsequent plan has a genuine dependency on prior plan output); `milestone-summary`. |
**`actuals` frontmatter (#2632, [ADR-2629](../adr/2629-phase-effort-estimation-calibration.md)).** When the phase's PLAN carried an `estimate`, the executor records what it actually cost:
@@ -198,30 +198,30 @@ actuals:
commits: 7
```
`tokens` uses the **same scale as the estimate**, not a harness-reported token count — an executor subagent cannot read its own consumption, and a ratio between two different measurement methods would measure the methods rather than the miss. `/gsd-extract-learnings` pairs each phase's estimate with its actuals via `gsd_run query estimate-calibrate`, writes `.planning/estimation-calibration.json`, and the planner applies the resulting factor to subsequent estimates. Additive and optional: a summary without `actuals` simply contributes no calibration sample.
`tokens` uses the **same scale as the estimate**, not a harness-reported token count — an executor subagent cannot read its own consumption, and a ratio between two different measurement methods would measure the methods rather than the miss. `/msd-extract-learnings` pairs each phase's estimate with its actuals via `msd_run query estimate-calibrate`, writes `.planning/estimation-calibration.json`, and the planner applies the resulting factor to subsequent estimates. Additive and optional: a summary without `actuals` simply contributes no calibration sample.
### `<NN>-VERIFICATION.md`
| | |
|---|---|
| **Purpose** | Phase goal verification report. Checks `must_haves.truths`, `must_haves.artifacts`, and `must_haves.key_links` from all plans against the actual codebase after execution. Records `status: passed \| gaps_found \| human_needed`. A truth whose correctness depends on runtime behaviour — a state transition or a cancellation/cleanup/ordering invariant — is marked `⚠️ PRESENT_BEHAVIOR_UNVERIFIED` (not `VERIFIED`) when no test exercises it: it is excluded from `score`, counted in the `behavior_unverified` frontmatter field, and routed to `human_needed`, so a behaviour-dependent gap can no longer count toward a clean N/N. A truth that *does* reach `✓ VERIFIED` but holds for an incidental reason (`undeclared-precondition`, `incidental-ordering`, `fixture-only`) is qualified `✓ VERIFIED (coincidental-reliance)` and listed in `coincidental_reliance_items` — **advisory only**: it still counts toward `score`, does not change `status`, and emits no human-verification item (#1955). During re-verification (after a `/gsd-plan-phase --gaps` cycle), an anti-pattern blocker that is neither a carried-forward gap nor found in a file modified since the prior pass, and carries no deterministic evidence (a test run red, or another concrete reproducible artifact), is downgraded to the `advisory:` frontmatter list instead of reopening `status: gaps_found` — it does not revert a completed must-have (#3304). |
| **Produced by** | `/gsd-verify-work` (or the verify step within `/gsd-execute-phase`). |
| **Consumed by** | `plan-phase` closed-phase gate (a `status: passed` VERIFICATION.md marks the phase `Complete` and blocks replanning without `--force`); `/gsd-progress`; human review. |
| **Purpose** | Phase goal verification report. Checks `must_haves.truths`, `must_haves.artifacts`, and `must_haves.key_links` from all plans against the actual codebase after execution. Records `status: passed \| gaps_found \| human_needed`. A truth whose correctness depends on runtime behaviour — a state transition or a cancellation/cleanup/ordering invariant — is marked `⚠️ PRESENT_BEHAVIOR_UNVERIFIED` (not `VERIFIED`) when no test exercises it: it is excluded from `score`, counted in the `behavior_unverified` frontmatter field, and routed to `human_needed`, so a behaviour-dependent gap can no longer count toward a clean N/N. A truth that *does* reach `✓ VERIFIED` but holds for an incidental reason (`undeclared-precondition`, `incidental-ordering`, `fixture-only`) is qualified `✓ VERIFIED (coincidental-reliance)` and listed in `coincidental_reliance_items` — **advisory only**: it still counts toward `score`, does not change `status`, and emits no human-verification item (#1955). During re-verification (after a `/msd-plan-phase --gaps` cycle), an anti-pattern blocker that is neither a carried-forward gap nor found in a file modified since the prior pass, and carries no deterministic evidence (a test run red, or another concrete reproducible artifact), is downgraded to the `advisory:` frontmatter list instead of reopening `status: gaps_found` — it does not revert a completed must-have (#3304). |
| **Produced by** | `/msd-verify-work` (or the verify step within `/msd-execute-phase`). |
| **Consumed by** | `plan-phase` closed-phase gate (a `status: passed` VERIFICATION.md marks the phase `Complete` and blocks replanning without `--force`); `/msd-progress`; human review. |
### `<NN>-UAT.md`
| | |
|---|---|
| **Purpose** | Persistent UAT session tracking. Records each test case, expected observable behaviour, result, and developer response across a live UAT session. Carries YAML frontmatter (`status`, `phase`, `source`, timestamps). |
| **Produced by** | `/gsd-audit-uat` (interactive UAT session). |
| **Consumed by** | `/gsd-audit-uat` (resume a previous UAT session). |
| **Produced by** | `/msd-audit-uat` (interactive UAT session). |
| **Consumed by** | `/msd-audit-uat` (resume a previous UAT session). |
### `.continue-here.md`
| | |
|---|---|
| **Purpose** | Human-readable resume instructions written when work on a phase is paused. Contains context for resuming agents: critical anti-patterns, blocking issues, required reading, and the exact command to resume. |
| **Produced by** | `/gsd-pause-work`. |
| **Produced by** | `/msd-pause-work`. |
| **Consumed by** | Any workflow that starts on a phase — `discuss-phase` and `plan-phase` both check for this file at entry and require the agent to demonstrate understanding of any `blocking` anti-patterns before proceeding. |
### `.planning/async-jobs/<job>.json`
@@ -245,7 +245,7 @@ actuals:
| `status` | enum | Scheduler-agnostic lifecycle state (see below). |
| `expected_artifacts` | string[] | Paths the job is expected to produce; verified before the plan is closed. |
| `verification_command` | string | Command that verifies the job's output before close-out. |
| `resume_command` | string | Exact command to resume GSD reconciliation (re-enter the loop to re-check the job), e.g. `/gsd-execute-phase <phase>`. This is a GSD reconciliation entry point, not a scheduler resubmit. |
| `resume_command` | string | Exact command to resume MSD reconciliation (re-enter the loop to re-check the job), e.g. `/msd-execute-phase <phase>`. This is a MSD reconciliation entry point, not a scheduler resubmit. |
| `submitted_at` | string | ISO 8601 submission timestamp. |
| `terminal_details` | object \| null | Failure/terminal-state detail; `null` while non-terminal. |