openplanr 1.25.3 → 2.0.0

package/lib/host-packages/openai/openplanr/skills/plan/scripts/runtime/packages/protocol/schemas/v1.9.0/design-workspace-event.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/v1.9.0/design-workspace-event.schema.json",
+  "x-openplanr-contract": {
+    "id": "design-workspace-event",
+    "version": "1.9.0"
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{22,64}$"
+    },
+    "revisionId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{22,64}$"
+    },
+    "reviewOf": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "epoch": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 2147483647
+    },
+    "iv": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "minLength": 16,
+      "maxLength": 16
+    },
+    "ciphertext": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "minLength": 22,
+      "maxLength": 6990507
+    },
+    "publicKey": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kty",
+        "crv",
+        "x",
+        "y"
+      ],
+      "properties": {
+        "kty": {
+          "const": "EC"
+        },
+        "crv": {
+          "const": "P-256"
+        },
+        "x": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_-]+$",
+          "minLength": 43,
+          "maxLength": 43
+        },
+        "y": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_-]+$",
+          "minLength": 43,
+          "maxLength": 43
+        },
+        "ext": {
+          "type": "boolean"
+        },
+        "key_ops": {
+          "type": "array",
+          "items": {
+            "const": "verify"
+          },
+          "maxItems": 1
+        }
+      }
+    },
+    "signature": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "minLength": 86,
+      "maxLength": 86
+    }
+  },
+  "required": [
+    "id",
+    "revisionId",
+    "reviewOf",
+    "epoch",
+    "iv",
+    "ciphertext",
+    "publicKey",
+    "signature"
+  ]
+}

package/lib/host-packages/openai/openplanr/skills/plan/scripts/runtime/packages/protocol/schemas/v1.9.0/design-workspace-revision.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/v1.9.0/design-workspace-revision.schema.json",
+  "x-openplanr-contract": {
+    "id": "design-workspace-revision",
+    "version": "1.9.0"
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{22,64}$"
+    },
+    "epoch": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 2147483647
+    },
+    "reviewOf": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "iv": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "minLength": 16,
+      "maxLength": 16
+    },
+    "ciphertext": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "minLength": 22,
+      "maxLength": 6990507
+    },
+    "signature": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "minLength": 86,
+      "maxLength": 86
+    }
+  },
+  "required": [
+    "id",
+    "epoch",
+    "reviewOf",
+    "createdAt",
+    "iv",
+    "ciphertext",
+    "signature"
+  ]
+}

package/lib/host-packages/openai/openplanr/skills/plan-review/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: plan-review
+description: Review an OpenPlanr plan for product, engineering, design, and developer-experience problems. Use after planning and before implementation to improve the plan.
+license: MIT
+---
+
+# Planr Plan Review
+
+Give the plan a senior, practical review. Read the plan, its repository context,
+and the decisions it depends on. Use only the review lenses relevant to the
+work; do not manufacture a fixed committee.
+
+## Review
+
+- Check that the outcome and user value are clear and measurable.
+- Check scope, sequencing, ownership, architecture, migration, security,
+  operability, testing, and rollback in proportion to the change.
+- Check the first-run and everyday developer experience, including setup,
+  diagnostics, defaults, and recovery.
+- Prefer concrete corrections over abstract criticism. Name the affected plan
+  section and the change that would resolve each material issue.
+- Use subagents or tools when they improve the review, but return one coherent
+  result rather than their raw transcripts.
+
+Ask through the host's native structured question UI only when a missing answer
+would materially change the review. Otherwise state the assumption and continue.
+
+## Output
+
+Lead with one verdict: `ready`, `ready with improvements`, or `needs revision`.
+Then report:
+
+1. Must fix — only issues that would make the implementation wrong or unsafe.
+2. Improvements — worthwhile changes that are not blockers.
+3. Decisions and assumptions — unresolved choices with a recommended default.
+4. Next action — the smallest useful next step.
+
+Return the useful findings directly. Revisit the review when the user asks or
+the plan materially changes.

package/lib/host-packages/openai/openplanr/skills/plan-review/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Planr Plan Review"
+  short_description: "Review an OpenPlanr plan for product, engineering, design, and…"
+  default_prompt: "Use $planr:plan-review to review an OpenPlanr plan for product, engineering, design, and developer-experience problems. Use after planning and before implementation to improve the plan."
+policy:
+  allow_implicit_invocation: true

package/lib/host-packages/openai/openplanr/skills/plan-review/openplanr.skill.json

@@ -0,0 +1,26 @@
+{
+  "kind": "openplanr-skill-package",
+  "schemaVersion": "1.0.0",
+  "protocolVersion": "1.8.0",
+  "skillId": "planr-plan-review",
+  "skillVersion": "1.0.0",
+  "entrypoint": "SKILL.md",
+  "hosts": [
+    "claude-code",
+    "codex",
+    "chatgpt",
+    "cursor"
+  ],
+  "execution": "host-agent",
+  "resources": [
+    {
+      "path": "agents/openai.yaml",
+      "kind": "agent-metadata",
+      "hosts": [
+        "codex",
+        "chatgpt"
+      ],
+      "executable": false
+    }
+  ]
+}

package/lib/host-packages/openai/openplanr/skills/release/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: release
+description: Choose and maintain a product's versioning scheme, classify shipped changes, and write user-facing changelogs or release notes. Use for SemVer or CalVer decisions, version bumps, release cadence, and preparing a versioned release after landing.
+license: MIT
+---
+
+# Planr Release
+
+Two jobs: pick the right version number, and tell users what changed in language they care about. Both fall out of correctly classifying what shipped, so classification comes first and everything else follows from it.
+
+The failure mode this skill exists to prevent: version numbers chosen by gut feeling or diff size, and changelogs that read like a git log. Both make releases untrustworthy to the people downstream of them.
+
+This skill owns versioning and release communication after implementation. Use
+`planr-land` for merge readiness and landing order, and `planr-ship` for code
+implementation. Do not turn a release request into a new implementation pass.
+
+## Step 0: Load the release profile
+
+Look for `.release/profile.md` at the repo root. It records the scheme, cadence, public surface and voice already chosen for this product.
+
+If it exists, read it and follow it. Do not re-argue the scheme on every release. Re-deciding is how version histories become incoherent, and the whole value of a version number is that it means the same thing this month as it did last month.
+
+If it does not exist, this is first-time setup. Work through Step 3, propose a profile, get the user's agreement, then write it using the [release profile template](assets/profile-template.md). Every later release starts from that file instead of from scratch.
+
+## Step 1: Gather what shipped
+
+Establish the window first. Default is "since the last release":
+
+```bash
+git describe --tags --abbrev=0          # last tag
+git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges
+```
+
+If the user names a period instead ("this week", "since the 1st"), use the
+matching date window. The [change collector](scripts/collect_changes.sh) gathers local Git evidence in
+one pass. Pass `--include-prs` only when remote pull-request context is useful
+and available.
+
+Pull from all three sources, since each catches things the others miss:
+
+1. **Commits and tags.** The complete record of code change, and the noisiest.
+2. **Merged PRs and branch names.** Better titles than commits, and they group related commits into one user-visible unit. `gh pr list --state merged --search "merged:>=YYYY-MM-DD"` when the `gh` CLI is available.
+3. **The user's own summary.** Authoritative for anything git cannot see: infra changes, config and feature flags, third-party integrations, work shipped from another repo, and which of the twelve commits behind a feature actually matter to users.
+
+Use any product summary already present in the request or repository. If material
+non-Git changes could alter the release notes, ask one concise question about
+what Git missed before finalizing.
+
+## Step 2: Classify each change
+
+For every unit of work, ask one question: **does a user have to do, know, or expect something different now?** Not "how much code moved". A 2000 line refactor with identical behavior is invisible. A one line default change can be breaking.
+
+| Class | Test | Notes |
+|---|---|---|
+| Breaking | Someone must change something they configured, integrated or learned | Drives the largest bump, always announced |
+| Feature | New capability a user can reach | |
+| Improvement | Existing capability now better, faster or clearer | |
+| Fix | A symptom users could hit is gone | |
+| Security | Vulnerability closed | Ship alone and fast, describe impact not exploit |
+| Deprecation | Still works, will be removed | Must state the removal target |
+| Internal | Refactor, tests, CI, dep bumps, formatting | Affects the bump only if behavior moved |
+
+Internal work is real work and still does not belong in user-facing notes. Keep it out. Empty sections beat padded ones.
+
+## Step 3: Choose the scheme (first time only)
+
+Pick per product and state the reasoning in one or two sentences. Read the [versioning schemes guide](references/schemes.md) for the full decision guide, edge cases and the multi-line setup. The short version:
+
+- **Library, SDK, CLI or anything others install and pin** to SemVer, strictly. The declared public API is the contract, and consumers automate against the number.
+- **Hosted app with no external integrators** to CalVer. Nobody pins a version they cannot choose, so the number's real job is answering "how old is this", which a date does better than a counter.
+- **Hosted app that also exposes an API, webhooks or an SDK** to two version lines: SemVer on the API surface, CalVer or SemVer on the app itself. Conflating them forces an app redesign to look like an API break.
+- **Internal tool** to CalVer. Low ceremony, and the deploy date is the thing people actually ask about.
+
+Record the choice, the reasoning and the declared public surface in the profile. "Public surface" is the most important field: it is the list of things a break can happen to, and without it "breaking" has no meaning.
+
+## Step 4: Decide the bump
+
+Work the classification against the scheme.
+
+**SemVer**, where MAJOR/MINOR/PATCH map to compatibility:
+
+- MAJOR: anything in the Breaking row above. Removal of a documented feature, changed response shape, changed default that alters outcomes, tightened validation that rejects previously accepted input, renamed config, new required field.
+- MINOR: new capability, backward compatible. Also the release that first ships a deprecation warning.
+- PATCH: fixes, performance, copy, visual polish, dependency updates with no behavior change.
+
+For hosted products, SemVer's definition of breaking needs translating, because there is no compilation step to fail. Treat it as breaking if a user's saved workflow, integration, bookmark, muscle memory or stored data stops working the way it did. Moving a primary action to a different screen is a change users must relearn, and pretending otherwise is how "we never make breaking changes" becomes false.
+
+**CalVer** (`YYYY.MM.PATCH` or `YYYY.MM.DD`), where the number encodes time, not compatibility. The counter carries no compatibility signal, so breaking changes must be carried by the notes instead. Lead with them and never bury them.
+
+Two rules that hold under any scheme:
+
+- One release, one version. At daily or weekly cadence, do not bump per commit or per deploy. A version number that increments forty times a week communicates nothing.
+- Never bundle a breaking change with unrelated work. It ships alone so the notes and the rollback are both about one thing.
+
+## Step 5: Cadence
+
+The mechanism that makes frequent shipping compatible with meaningful versions is separating **deploys** from **releases**. Deploy whenever the work is ready. Cut versions on a rhythm.
+
+Keep a rolling `## [Unreleased]` section at the top of `CHANGELOG.md` and append to it as work merges, while the context is fresh. Cutting a release then means renaming that section to the version and date, and opening a fresh empty one. This is what makes weekly releases take five minutes instead of an hour of git archaeology.
+
+Default rhythm for a daily-to-weekly product:
+
+- Fixes that unblock users: cut immediately as a patch. Do not make people wait for Friday.
+- Features and improvements: accumulate into the regular cut, weekly or twice weekly.
+- Breaking changes: announced ahead, shipped alone, on a date users were told about.
+
+See the [release cadence guide](references/cadence.md) for the hotfix path, release freezes, and what to do when a release goes out wrong.
+
+## Step 6: Write the release notes
+
+Read the [release notes guide](references/release-notes.md) before writing. It carries the voice rules and worked rewrites; a summary here would produce notes that read like a commit log, which is the exact thing being avoided.
+
+The shape, following Keep a Changelog:
+
+```markdown
+## [1.4.0] - 2026-09-08
+
+### Removed
+- Entry, with the migration step inline.
+
+### Added
+- Entry.
+
+### Changed
+- Entry.
+
+### Fixed
+- Entry.
+```
+
+Order sections by what costs the reader most if missed: Removed and any breaking Changed first, then Added, then the rest. Omit empty sections entirely.
+
+Core rules, expanded in the reference:
+
+- Lead with what the user can now do, not with what was built.
+- Name features exactly as they appear in the product UI.
+- Describe fixes by the symptom users saw, not the cause in code.
+- One line per entry. If it needs a paragraph, it needs a linked doc.
+- No em dashes, no filler openers, no "we're excited to announce".
+
+## Step 7: Prepare the local release
+
+1. Prepend the new section to `CHANGELOG.md` and open a fresh `## [Unreleased]`.
+2. Bump version numbers with the repository's existing release tool, never by
+   hand-editing duplicated numbers. Keep the operation local and untagged unless
+   the user requested a tag. For npm, use `npm version --no-git-tag-version`;
+   for independent JavaScript packages, prefer the repository's Changesets flow.
+3. Inspect recent tags and preserve the established tag format. A repository
+   tagged `v1.2.0` must not suddenly get `1.3.0`.
+4. Run the repository's release checks. Confirm every release-note entry maps to
+   shipped behavior and every user-visible change in the selected window is
+   represented.
+5. Push tags, publish packages, create hosted releases, post announcements, or
+   deploy only when the user explicitly requests that external effect.
+
+## Return
+
+- **Version:** current and proposed versions, scheme, and bump rationale.
+- **Included:** user-visible changes in the release window.
+- **Notes:** the release-note text or changed changelog path.
+- **Checks:** release verification performed and results.
+- **Next:** the one remaining local or external release action, or `none`.
+
+## Long-term health
+
+Every few months, or when the user asks whether versioning is working:
+
+- **Drift check.** Do the tag, the manifest and what is deployed agree.
+- **Deprecation hygiene.** Every deprecation announced needs a stated removal target and eventual follow-through. Deprecations that never get removed teach users to ignore them.
+- **Stuck at 0.x.** A product with real paying users on `0.x` is signalling instability it does not have. Cutting 1.0 is a decision about the public surface being stable enough to promise, not about feature completeness.
+- **Scheme fit.** A product that grew an API since the profile was written probably needs a second version line now.
+
+## Reference files
+
+- [Versioning schemes](references/schemes.md): full scheme selection guide, multi-line versioning, monorepo handling
+- [Release notes](references/release-notes.md): voice rules, worked rewrites, per-channel formats
+- [Release cadence](references/cadence.md): release rhythms, hotfixes, freezes, bad releases
+- [Release profile template](assets/profile-template.md): the `.release/profile.md` written during setup
+- [Changelog template](assets/changelog-template.md): starting `CHANGELOG.md`
+- [Change collector](scripts/collect_changes.sh): gathers commits, optional merged PRs, and tag information for a window

package/lib/host-packages/openai/openplanr/skills/release/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Planr Release"
+  short_description: "Choose and maintain a product's versioning scheme, classify…"
+  default_prompt: "Use $planr:release to choose and maintain a product's versioning scheme, classify shipped changes, and write user-facing changelogs or release notes. Use for SemVer or CalVer decisions, version bumps, release cadence, and preparing a versioned release after landing."
+policy:
+  allow_implicit_invocation: true

package/lib/host-packages/openai/openplanr/skills/release/assets/changelog-template.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable user-facing changes to this project are recorded here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning: <scheme, per .release/profile.md>.
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed
+
+## [1.0.0] - <DATE>
+
+Initial release.

package/lib/host-packages/openai/openplanr/skills/release/assets/profile-template.md

@@ -0,0 +1,45 @@
+# Release profile: <PRODUCT NAME>
+
+Written on <DATE>. Update when the product's audience or surface changes,
+not on every release.
+
+## Scheme
+
+**Scheme:** <SemVer | CalVer YYYY.MM.PATCH | other>
+**Why:** <one or two sentences tying the choice to who reads the number and
+what question they are asking>
+
+## Public surface
+
+The list of things a breaking change can happen to. Anything not listed here
+can change in a patch.
+
+- <e.g. documented HTTP endpoints under /api/v1>
+- <e.g. webhook payload shapes>
+- <e.g. the booking flow URLs users bookmark>
+- <e.g. exported types from the package entrypoint>
+
+## Second version line
+
+**Applies:** <yes | no>
+**If yes:** <what it covers, which scheme, where it is declared>
+
+## Cadence
+
+**Regular cut:** <e.g. weekly, Wednesday>
+**Fixes:** <e.g. shipped immediately as patches>
+**Breaking changes:** <e.g. announced 14 days ahead, shipped alone>
+**Freezes:** <e.g. none | client demo weeks | December>
+
+## Tooling
+
+**Version bump:** <e.g. pnpm changeset version | npm version>
+**Tag format:** <e.g. v1.4.0 | 2026.09.1>
+**Changelog:** <path, e.g. CHANGELOG.md, Keep a Changelog format>
+
+## Voice
+
+**Audience:** <who reads the notes>
+**Product vocabulary:** <UI terms that must be used verbatim, and the internal
+names that must never appear>
+**Channels:** <CHANGELOG.md | in-product what's new | email | GitHub releases>

package/lib/host-packages/openai/openplanr/skills/release/openplanr.skill.json

@@ -0,0 +1,92 @@
+{
+  "kind": "openplanr-skill-package",
+  "schemaVersion": "1.0.0",
+  "protocolVersion": "1.8.0",
+  "skillId": "planr-release",
+  "skillVersion": "1.0.0",
+  "entrypoint": "SKILL.md",
+  "hosts": [
+    "claude-code",
+    "codex",
+    "chatgpt",
+    "cursor"
+  ],
+  "execution": "host-agent",
+  "resources": [
+    {
+      "path": "agents/openai.yaml",
+      "kind": "agent-metadata",
+      "hosts": [
+        "codex",
+        "chatgpt"
+      ],
+      "executable": false
+    },
+    {
+      "path": "references/schemes.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
+    {
+      "path": "references/release-notes.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
+    {
+      "path": "references/cadence.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
+    {
+      "path": "assets/profile-template.md",
+      "kind": "asset",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
+    {
+      "path": "assets/changelog-template.md",
+      "kind": "asset",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
+    {
+      "path": "scripts/collect_changes.sh",
+      "kind": "script",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": true
+    }
+  ]
+}

package/lib/host-packages/openai/openplanr/skills/release/references/cadence.md

@@ -0,0 +1,92 @@
+# Cadence, hotfixes, and recovery
+
+Contents:
+1. Deploys are not releases
+2. The Unreleased section
+3. Picking a rhythm
+4. Hotfixes
+5. When a release goes out wrong
+6. Freezes and quiet periods
+
+---
+
+## 1. Deploys are not releases
+
+A deploy puts code in production. A release is a named, dated, described unit that users and support can refer to. Conflating them is what makes high-frequency shipping incompatible with meaningful versions.
+
+Deploy continuously. Release on a rhythm. The version number then marks a point people can talk about ("this started in 2026.09.2") rather than incrementing invisibly forty times a week.
+
+The one exception is a product whose users genuinely track every deploy, which in practice means developer tooling with a public build feed. Almost nothing else qualifies.
+
+---
+
+## 2. The Unreleased section
+
+This is the mechanism that makes weekly releases cheap.
+
+Keep this at the top of `CHANGELOG.md` at all times:
+
+```markdown
+## [Unreleased]
+
+### Added
+- Entry written when the work merged, while it was still fresh.
+```
+
+Append to it as work merges, in user-facing language, not commit language. Cutting a release then becomes: rename the heading to the version and date, open a fresh empty `## [Unreleased]`, tag.
+
+The reason this is worth the discipline: reconstructing user intent from commit messages a week later is slow and lossy. The person who wrote the feature knows what it does for users on the day they merged it, and nobody knows it as well again.
+
+If the section was not maintained, fall back to collecting from git plus the user's summary. Expect gaps and ask about them explicitly.
+
+---
+
+## 3. Picking a rhythm
+
+**Daily releases.** Suits internal tools and early products with a small user base and fast feedback. CalVer `YYYY.MM.DD` fits naturally. Cost: notes get thin, and users tune out. Mitigate by skipping in-product announcements for most days and batching the announcement weekly even when the versions are daily.
+
+**Weekly.** The default for most products. Cut on a fixed day, ideally Tuesday or Wednesday. Not Friday: nobody wants to discover a bad release on a Saturday, and the person who can fix it is unreachable. Not Monday: it forces weekend work to prepare.
+
+**Twice weekly.** Works when feature flow is steady and fixes are frequent. Practical split: features on the fixed day, fixes whenever ready.
+
+**Monthly or slower.** Only where consumers bear real upgrade cost, typically libraries and on-prem software. For a hosted product, monthly releases usually mean the notes go unread because too much accumulated.
+
+Whatever the rhythm, keep the day fixed. Predictability is most of the value: support knows when to expect change, and users learn when to look.
+
+---
+
+## 4. Hotfixes
+
+A hotfix is a fix that cannot wait for the next scheduled release because users are currently blocked or losing data.
+
+Process:
+
+1. Cut it as a patch off the current release, not off main, if main has unreleased work in it. Shipping unrelated half-finished changes alongside an urgent fix is how a small incident becomes a large one.
+2. One line in the notes, describing the symptom.
+3. Tag it. A hotfix that never gets a version number is invisible to support later, when someone asks whether a given user had the fix.
+
+Do not batch hotfixes. The batching instinct is what turns a fifteen minute fix into a two hour release.
+
+---
+
+## 5. When a release goes out wrong
+
+**Never delete or move a published tag.** Anything that consumed it will silently disagree with anything that consumes it later, and that class of bug is miserable to diagnose.
+
+Instead:
+
+- Roll forward with a new patch version wherever possible. It preserves the history and is faster than a rollback in most deployment setups.
+- If the release must be pulled (a published package, a broken migration), publish a new version and mark the bad one deprecated through the registry's own mechanism. Add a changelog entry saying it was withdrawn and why. Users who already installed it need to know.
+- Correct the changelog by adding a note, not by rewriting history. A changelog that gets quietly edited stops being evidence.
+
+---
+
+## 6. Freezes and quiet periods
+
+Worth declaring in the profile if they apply:
+
+- Around a launch, a demo, or a client-facing event, hold non-urgent releases. Fixes still ship.
+- Around holidays, avoid shipping anything breaking when the people who would field the fallout are away.
+- If the product serves businesses with their own peak periods, avoid their peak. A booking product should not ship a breaking change into a salon's Saturday.
+
+A freeze is a schedule decision, not a code freeze. Work continues and accumulates in `Unreleased`.