chore: drop upstream gsd issue and pr governance
Some checks failed
Tests / lint-tests (push) Has been cancelled
Tests / plugin-validate (push) Has been cancelled
Tests / test (ubuntu-latest, 24, shard 1/3) (push) Has been cancelled
Tests / test (ubuntu-latest, 24, shard 2/3) (push) Has been cancelled
Tests / test (ubuntu-latest, 24, shard 3/3) (push) Has been cancelled
Tests / test (ubuntu-latest, 24) (push) Has been cancelled
Tests / test (inert CI) (push) Has been cancelled
Tests / conformance test (macos-latest, 24) (push) Has been cancelled
Tests / conformance test (windows-latest, 24, shard 1/3) (push) Has been cancelled
Tests / conformance test (windows-latest, 24, shard 2/3) (push) Has been cancelled
Tests / conformance test (windows-latest, 24, shard 3/3) (push) Has been cancelled
Tests / Coverage gate (merged shards) (push) Has been cancelled
Tests / QA loop walk (smell ratchet) (push) Has been cancelled
Tests / Required tests (push) Has been cancelled
Tests / Publish emitted-baseline artifact (push) Has been cancelled
Tests / PR mergeability (push) Has been cancelled
Tests / Base branch health (push) Has been cancelled
Tests / Detect test scope (push) Has been cancelled

MSD does not use an issue tracker, and the inherited GSD community gates
auto-closed PR #1 for lacking an issue-numbered title. Remove them:

- workflows: require-issue-link, pr-title-validator,
  auto-close-unsolicited-prs, pr-template-format, close-draft-prs(-sweep),
  auto-label-issues, auto-branch, duplicate-check, duplicate-sweep,
  remove-duplicate-label
- GSD PR and issue templates, plus the scripts only they used
  (require-issue-link-policy, pr-template-policy, pr-changed-files) and
  their tests
- workflow lists in ci-test-scope, ci-pr-mergeability,
  workflow-maintainer-skip, lint-pr-check-project-dir, the docs-guard
  baseline and the conformance tiers
- CONTRIBUTING: PR-against-next flow with no issue or template; PR titles
  are conventional without an issue ref; ADR/PRD files use the PR number
- CONTEXT.md: drop the PR-template predicates (k328, templates-mandatory)
This commit is contained in:
Jakub Zych
2026-10-09 10:53:54 +02:00
parent b7e36d5d38
commit bb581803ad
40 changed files with 44 additions and 4294 deletions

View File

@@ -29,95 +29,39 @@ environment validator, daily commands, and troubleshooting.
---
## Types of Contributions
## How Changes Land
MSD accepts three types of contributions. Each type has a different process and a different bar for acceptance. **Read this section before opening anything.**
MSD is maintained by a small team and does not use an issue tracker. Work happens on a feature branch and lands through a pull request against `next` on [git.golem15.com](https://git.golem15.com/golem15/msd-core):
### 🐛 Fix (Bug Report)
1. Branch from `next` (`feat/<slug>`, `fix/<slug>`, `chore/<slug>`, …).
2. Make the change, with tests. Add a `.changeset/` fragment if it is user-facing (see below).
3. Open a PR against `next`. Describe what changed and why, and how you tested it. No issue link or PR template is required.
4. Merge once CI is green and the change is reviewed.
A fix corrects something that is broken, crashes, produces wrong output, or behaves contrary to documented behavior.
**Process:**
1. Open a [Bug Report issue](https://github.com/open-gsd/gsd-core/issues/new?template=bug_report.yml) — fill it out completely.
2. Wait for a maintainer to confirm it is a bug (label: `confirmed-bug`). For obvious, reproducible bugs this is typically fast.
3. Fix it. Write a test that would have caught the bug.
4. Open a PR using the [Fix PR template](.github/PULL_REQUEST_TEMPLATE/fix.md) — link the confirmed issue.
**Rejection reasons:** Not reproducible, works-as-designed, duplicate of an existing issue.
---
### ⚡ Enhancement
An enhancement improves an existing feature — better output, faster execution, cleaner UX, expanded edge-case handling. It does **not** add new commands, new workflows, or new concepts.
**The bar:** Enhancements must have a scoped written proposal approved by a maintainer before any code is written. A PR for an enhancement will be closed without review if the linked issue does not carry the `approved-enhancement` label.
**Process:**
1. Open an [Enhancement issue](https://github.com/open-gsd/gsd-core/issues/new?template=enhancement.yml) with the full proposal. The issue template requires: the problem being solved, the concrete benefit, the scope of changes, and alternatives considered.
2. **Wait for maintainer approval.** A maintainer must label the issue `approved-enhancement` before you write a single line of code. Do not open a PR against an unapproved enhancement issue — it will be closed.
3. Write the code. Keep the scope exactly as approved. If scope creep occurs, comment on the issue and get re-approval before continuing.
4. Open a PR using the [Enhancement PR template](.github/PULL_REQUEST_TEMPLATE/enhancement.md) — link the approved issue.
**Rejection reasons:** Issue not labeled `approved-enhancement`, scope exceeds what was approved, no written proposal, duplicate of existing behavior.
---
### ✨ Feature
A feature adds something new — a new command, a new workflow, a new concept, a new integration. Features have the highest bar because they add permanent maintenance burden to a solo-developer tool maintained by a small team.
**The bar:** Features require a complete written specification approved by a maintainer before any code is written. A PR for a feature will be closed without review if the linked issue does not carry the `approved-feature` label. Incomplete specs are closed, not revised by maintainers.
**Process:**
1. **Discuss first** — check [Discussions](https://github.com/open-gsd/gsd-core/discussions) to see if the idea has been raised. If it has and was declined, don't open a new issue.
2. Open a [Feature Request issue](https://github.com/open-gsd/gsd-core/issues/new?template=feature_request.yml) with the complete spec. The template requires: the solo-developer problem being solved, what is being added, full scope of affected files and systems, user stories, acceptance criteria, and assessment of maintenance burden.
3. **Wait for maintainer approval.** A maintainer must label the issue `approved-feature` before you write a single line of code. Approval is not guaranteed — MSD is intentionally lean and many valid ideas are declined because they conflict with the project's design philosophy.
4. Write the code. Implement exactly the approved spec. Changes to scope require re-approval.
5. Open a PR using the [Feature PR template](.github/PULL_REQUEST_TEMPLATE/feature.md) — link the approved issue.
**Rejection reasons:** Issue not labeled `approved-feature`, spec is incomplete, scope exceeds what was approved, feature conflicts with MSD's solo-developer focus, maintenance burden too high.
Releases are cut from `next` as `vX.Y.Z` tags; the `stable` branch follows the latest release (see `CLAUDE.md`, "Distribution and releases").
---
### 📐 Proposing an ADR or PRD
An ADR (Architecture Decision Record) documents a significant architectural decision. A PRD (Product Requirements Document) captures the what and why of a feature before implementation. Both are governed by the same issue-first rule as everything else.
An ADR (Architecture Decision Record) documents a significant architectural decision. A PRD (Product Requirements Document) captures the what and why of a feature before implementation.
**Process:**
1. Open an issue of the appropriate type (enhancement for an ADR revisiting an existing area, feature for a new architectural surface, chore for policy/docs decisions). Fill it out completely.
2. **Wait for maintainer approval.** A maintainer must label the issue `approved-enhancement`, `approved-feature`, or confirm the chore before any file is created.
3. The GitHub-assigned issue number becomes your filename prefix. Create the file on a branch named after the issue:
- `docs/adr/<issue#>-<slug>.md` for ADRs
- `docs/prd/<issue#>-<slug>.md` for PRDs
- Branch: `docs/<issue#>-<slug>`
4. Open a PR using the appropriate template and close the issue with `Closes #<issue#>` in the PR body.
1. Open the PR that adds the file (it can start as just the document) so it gets a number.
2. Use that PR number as the filename prefix:
- `docs/adr/<pr#>-<slug>.md` for ADRs
- `docs/prd/<pr#>-<slug>.md` for PRDs
3. Agree on the decision in the PR before building on it.
**One issue = one ADR-or-PRD = one PR.** Do not batch multiple decisions into one file or one PR.
**One ADR-or-PRD per PR.** Do not batch multiple decisions into one file or one PR.
**Do not compute a "next number" locally.** Any PR that uses the legacy `NNNN-*` sequential pattern for a *new* ADR or PRD will be asked to rename the file to the `<issue#>-<slug>.md` format before merge.
**Example:** Issue #2264 was opened, approved, and its number became the prefix: `docs/adr/2264-golden-parity-redesign.md`.
**Rejection reasons:** Issue not approved before file was created, filename uses local-compute sequential number instead of issue#, multiple decisions bundled in one PR, file placed in wrong directory (`docs/adr/` vs `docs/prd/`).
**Do not compute a "next number" locally** — the PR number is unique, a locally guessed sequence is not. Existing files keep the upstream issue numbers they were created with.
**This process is for a *new* ADR file.** An accepted ADR is never rewritten from scratch — check `docs/adr/` first for a broader ADR that already owns the area. Amending one is a separate, lighter-weight path: see **[`docs/contributor-standards.md` — "Amending an accepted ADR"](docs/contributor-standards.md#amending-an-accepted-adr)** for the two established patterns (an in-place dated section, or a new ADR that declares `Amends`/gets the reciprocal `Amended by` back-link).
---
## The Issue-First Rule — No Exceptions
> **No code before approval.**
For **fixes**: open the issue, confirm it's a bug, then fix it.
For **enhancements**: open the issue, get `approved-enhancement`, then code.
For **features**: open the issue, get `approved-feature`, then code.
PRs that arrive without a properly-labeled linked issue are closed automatically. This is not a bureaucratic hurdle — it protects you from spending time on work that will be rejected, and it protects maintainers from reviewing code for changes that were never agreed to.
---
## Where Do I Open My PR? (Branching Model)
MSD uses two long-lived branches: `main` (production, what's on npm `@latest`)
@@ -182,23 +126,15 @@ Contributor requirements (summary):
- Read `CONTEXT.md` before naming or refactoring modules/interfaces/seams.
- Use `CONTEXT.md` vocabulary consistently in code comments, tests, issue/PR text, and docs for the touched area.
- Check relevant ADRs in `docs/adr/` before proposing or implementing architectural changes.
- If a change intentionally revisits an ADR decision, call it out explicitly in the linked issue and PR rationale.
- If a change intentionally revisits an ADR decision, call it out explicitly in the PR rationale.
- Do not rewrite maintainer intent in `CONTEXT.md`/ADRs as part of drive-by cleanup; propose focused updates tied to approved scope.
- If using an AI assistant, prompt it to read `CONTEXT.md` and the relevant ADRs before writing any code or docs, and verify it used the correct vocabulary before opening the PR.
**Every PR must link to an approved issue.** PRs without a linked issue are closed without review, no exceptions.
- **No draft PRs** — draft PRs are automatically closed. Only open a PR when it is complete, tested, and ready for review. If your work is not finished, keep it on your local branch until it is.
- **Use the correct PR template** — there are separate templates for [Fix](.github/PULL_REQUEST_TEMPLATE/fix.md), [Enhancement](.github/PULL_REQUEST_TEMPLATE/enhancement.md), and [Feature](.github/PULL_REQUEST_TEMPLATE/feature.md). Using the wrong template or using the default template for a feature is a rejection reason.
- **Link with a closing keyword** — use `Closes #123`, `Fixes #123`, or `Resolves #123` in the PR body. The CI check will fail and the PR will be auto-closed if no valid issue reference is found.
- **Test-only and docs-only follow-up PRs may reference without closing.** If your PR is documentation or regression coverage only — say, a repo-wide guard for a fix that already shipped — and there is no open issue for it to close, use a non-closing reference instead: `Refs #123`. `Ref`, `Refs`, `References`, `Relates to`, `Related to`, and `Follow-up to` are all accepted in that position. Do **not** write a closing keyword against an already-closed issue to satisfy the check; on merge it closes nothing, and it trains readers to treat closing keywords as decorative.
- **Qualifying diff shape:** every changed file must be under `tests/`, under `docs/`, or a root-level `*.md` (`README.md`, `CONTRIBUTING.md`, …). This mirrors the doc-only classification the push gate already uses, and it is deliberately root-only — markdown under a subdirectory (`msd-core/workflows/*.md`, `agents/*.md`, `commands/**/*.md`) is runtime-loaded text, not documentation, so it still requires a closing keyword. `CHANGELOG.md` is excluded too: edit it through a `.changeset/` fragment, never directly.
- This weaker form is accepted **only** for that diff shape. A PR touching anything else still needs a closing keyword, and a PR with no issue reference at all still fails. On a very large PR (more than 100 changed files) the check cannot confirm the diff shape and falls back to requiring a closing keyword.
- **One concern per PR** — bug fixes, enhancements, and features must be separate PRs
- **No drive-by formatting** — don't reformat code unrelated to your change
- **Don't bundle test-fixture updates into `docs:` or unrelated commits** — when a production change makes an existing test assertion stale, the test correction MUST land as its own `test:` (or `fix:`) commit, not bundled into a `docs:` commit that also updates the explanation. The release-sdk hotfix cherry-pick filter routes by commit-subject prefix (`fix:`, `chore:`, `test:`); a test-fixture correction packed under a `docs:` prefix is invisible to the picker and ships a half-state to the hotfix branch — production code changed, test assertion stale. v1.42.3 hit this exact mode (#3621). The fix is upstream: keep the test-fixture commit separate.
- **CI must pass** — all configured matrix jobs must be green. Node 24 is the compatibility floor and primary target; Node 26 compatibility must be preserved for code and tests even when a Node 26 CI lane is not yet available.
- **Scope matches the approved issue** — if your PR does more than what the issue describes, the extra changes will be asked to be removed or moved to a new issue
- **Scope matches the PR description** — unrelated changes go in their own PR
## CHANGELOG Entries — Drop a Fragment
@@ -244,32 +180,18 @@ node scripts/release-notes/format-github-release-notes.cjs \
Omit `--apply` to print the reformatted body to stdout for review without
publishing.
### PR title convention (enforced at open time)
### PR title convention
Because the changelog is built from PR titles, your **PR title** must follow:
Because the GitHub-style release notes are grouped by PR title, start the title with a conventional type:
```
type(#<issue>): short summary
type: short summary
```
- **Start with the type** — `feat`, `fix`, or any other conventional type
(`chore`, `docs`, `refactor`, …). No leading tags or prefixes: a title like
`[security] fix(config): …` defeats the `^fix` bucket anchor and silently
files the entry under the wrong changelog section.
- **Put the linked issue ref in the scope** — `(#<digits>)`. This is what
renders as a link to the issue in the changelog line. `fix(core): …` buckets
correctly but produces a changelog entry with **no issue link**.
- A breaking-change marker is fine: `feat(#42)!: …`.
- **Start with the type** — `feat`, `fix`, or any other conventional type (`chore`, `docs`, `refactor`, …). No leading tags: a title like `[security] fix: …` defeats the `^fix` anchor and files the entry under the wrong section.
- A scope and a breaking-change marker are fine: `fix(installer): …`, `feat!: …`.
Examples: `fix(#1542): roadmap rollback`, `feat(#39): milestone-prefixed phase IDs`,
`enhance(#1549): add PR-title validator`.
**CI enforcement:** `pr-title-validator.yml` checks the title on open/edit and
fails with the required format if it doesn't conform. It reuses the same matcher
the changelog classifier uses (`scripts/release-notes/conventional-title.cjs`), so a title
that passes the check is guaranteed to bucket and link correctly. Fix a flagged
title by editing it in place — the check re-runs on edit, no need to recreate
the PR.
Nothing enforces this in CI; `scripts/release-notes/conventional-title.cjs` is the matcher the release notes use.
## Documentation Updates — Update the Relevant Docs
@@ -347,7 +269,7 @@ shared file, so there is nothing to collide on.
1. **Any unique `id` is legal.** It does not have to be contiguous or maximal —
58, 113 and 131 are already absent, and `6.5`, `27a` and `27b` are live
non-integer ids. **Use your issue number** and you never have to revisit the
non-integer ids. **Use your PR number** and you never have to revisit the
choice after a rebase. `--check` rejects a duplicate with an `id_duplicate`
violation naming both fragments, so a collision is a loud one-line fix in
your own file, not a merge conflict.
@@ -373,7 +295,7 @@ shared file, so there is nothing to collide on.
rejects it (`body_heading_too_shallow`).
**Fork contributors:** there is nothing to coordinate and nothing to chase. Pick
your issue number, add your file, regenerate. If `docs/FEATURES.md` conflicts on
your PR number, add your file, regenerate. If `docs/FEATURES.md` conflicts on
a rebase, discard your side and re-run `--write` — it is a derived artifact.
**Agents:** no Fleet allocation lease is needed for a feature number any more.
@@ -1361,7 +1283,7 @@ Reviewers do not rely solely on CI to verify correctness. Before approving a PR,
- Build locally (`npm run build` if applicable)
- Run the full test suite locally (`npm test`)
- Confirm regression tests exist for bug fixes and that they would fail without the fix
- Validate that the implementation matches what the linked issue described — green CI on the wrong implementation is not an approval signal
- Validate that the implementation matches what the PR description says — green CI on the wrong implementation is not an approval signal
**"Tests pass in CI" is not sufficient for merge.** The implementation must correctly solve the problem described in the linked issue.