docs(skill): add versioning policy

[diberry]

Documents versioning rules to prevent prerelease version incidents.

Supersedes #689 with a clean branch from upstream/dev.
Fork PR: diberry#117.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[Copilot]

Pull request overview

Adds internal Squad documentation to codify a versioning policy intended to prevent prerelease-version incidents in the npm workspace monorepo.

Changes:

• Introduces a new team skill documenting semver and prerelease rules for the SDK/CLI.
• Adds an inbox decision capturing the proposed policy and rationale (incident references + CI gate mention).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
.squad/skills/versioning-policy/SKILL.md	New SKILL.md documenting version format, prerelease handling, workspace semver footgun, and CI enforcement.
.squad/decisions/inbox/flight-versioning-policy.md	New decision entry summarizing the policy and referencing the skill.

[Copilot]

Section 3 states SDK/CLI/root versions MUST always be identical and that divergence breaks workspace resolution. This contradicts the repo’s existing “independent versioning via changesets” guidance (e.g., docs/blog/017-version-alignment.md and docs/src/content/docs/guide/contributing.md) and the fact that the CLI depends on the SDK via a range (>=0.9.0), so simple divergence doesn’t inherently break workspace linking. Suggest clarifying that the real footgun is prerelease versions (e.g., -build.N) not satisfying the dependency range, and either remove the “must be identical” rule or explicitly document it as a new policy (and update the rest of the repo to match).

Suggested change

	Both `@bradygaster/squad-sdk` and `@bradygaster/squad-cli` **MUST have the same version** at all times. The root `package.json` version must also match.
	`bump-build.mjs` enforces this by updating all three `package.json` files in lockstep (root + `packages/squad-sdk` + `packages/squad-cli`).
	If versions diverge, workspace resolution silently breaks (see §4).
	As a **project convention**, `@bradygaster/squad-sdk`, `@bradygaster/squad-cli`, and the root `package.json` version **SHOULD normally be kept aligned** for release tags on `dev` and `main`. This avoids confusion when correlating bugs, logs, and published artifacts.
	`bump-build.mjs` helps enforce this convention by updating all three `package.json` files in lockstep (root + `packages/squad-sdk` + `packages/squad-cli`) during local version bumps.
	Workspace resolution only breaks when the SDK version does **not** satisfy the CLI’s semver range (typically because the SDK is on a prerelease like `0.9.1-build.4` while the CLI depends on `>=0.9.0`), as explained in §4.

[Copilot]

In §1, 0.9.1-build.4 is shown under ❌ even though §2 explains these -build.N versions are intentionally produced locally by bump-build.mjs. Consider rewording the ✅/❌ examples to make it explicit that -build.N is valid semver but disallowed on dev/main / in committed diffs (rather than implying the format itself is invalid).

Suggested change

	All packages use **strict semver**: `MAJOR.MINOR.PATCH`
	- ✅ `0.9.1`, `1.0.0`, `0.10.0`
	- ❌ `0.9.1-build.4`, `0.9.1-preview.1`, `0.8.6.1-preview`
	No prerelease suffixes on `dev` or `main` branches — ever.
	All packages use **strict semver** in committed `package.json` files on `dev` and `main`: `MAJOR.MINOR.PATCH`
	- ✅ Allowed in committed `package.json` on `dev`/`main`: `0.9.1`, `1.0.0`, `0.10.0`
	- ⚠️ Valid semver used **only for local testing** (never committed): `0.9.1-build.4` (see §2)
	- ❌ Disallowed in committed `package.json` on `dev`/`main`: `0.9.1-preview.1`, `0.8.6.1-preview`
	No prerelease suffixes in committed `package.json` files on `dev` or `main` branches — `-build.N` is for local-only testing (see §2).

[Copilot]

The decision asserts “SDK and CLI versions must stay in sync” and that divergence breaks npm workspace resolution. Current repo docs and changeset configuration describe independent versioning (e.g., docs/blog/017-version-alignment.md and docs/src/content/docs/guide/contributing.md), and the documented workspace incident is about prerelease versions not matching the SDK dependency range, not about version divergence itself. Recommend rewording this bullet to focus on the prerelease-range mismatch (and only claim lockstep versioning if the repo is actually moving to a fixed/linked versioning model).

Suggested change

	3. **SDK and CLI versions must stay in sync.** Divergence silently breaks npm workspace resolution.
	3. **SDK and CLI dependency ranges must remain compatible.** Prerelease versions (e.g., `0.9.1-build.N`) that fall outside declared semver ranges can silently break npm workspace resolution and fall back to registry packages.