openplanr 3.5.0 → 3.6.0

package/lib/host-packages/claude/openplanr/skills/operate/references/note-checklist.md

@@ -0,0 +1,131 @@
+# Operate note checklist
+
+Check a written Operate note line by line before returning it. Each item names the diagnostic
+code `openplanr operate validate-note` reports for the same problem. Fix what you can; report each
+item that stays unresolved as a structural issue, with its code.
+
+This checklist is the check. Never run `npx`, install or download anything, or search the
+filesystem for a validator or the CLI. Run `openplanr operate validate-note <note> --profile
+<profile> --contract-version 2.0.0` only if `command -v openplanr` succeeds, and treat its
+diagnostics the same way.
+
+Profiles: `advisor` (CEO, CTO, CPO, CMO and COO reviews), `challenger`, `chair` and
+`board-report`. Notes written now use contract 2.0.0.
+
+## Every profile
+
+- [ ] The profile is one of the four above (`E_OPERATE_REVIEW_PROFILE_INVALID`).
+- [ ] The preamble, before the first `##` heading, holds at most one contract line, written
+      `> **Contract:** …` or `- **Contract:** …`
+      (`E_OPERATE_REVIEW_CONTRACT_DECLARATION_DUPLICATE`). A note with no contract line passes.
+      Only a contract line that is present is checked: its value must be exactly
+      `operate-review-quality-contract@2.0.0` (`E_OPERATE_REVIEW_CONTRACT_DECLARATION_INVALID`
+      for an unsupported kind or version, `E_OPERATE_REVIEW_CONTRACT_VERSION_INVALID`,
+      `E_OPERATE_REVIEW_CONTRACT_VERSION_MISMATCH`).
+- [ ] The note has exactly one level-one `#` title (`E_OPERATE_REVIEW_TITLE_MISSING`,
+      `E_OPERATE_REVIEW_TITLE_DUPLICATE`).
+- [ ] The note fits its size limit in UTF-8 bytes: advisor 16 KiB, challenger 12 KiB, chair and
+      board-report 24 KiB (`E_OPERATE_REVIEW_SIZE_LIMIT`).
+- [ ] Every required `##` section for the profile is present (`E_OPERATE_REVIEW_SECTION_MISSING`)
+      and appears once (`E_OPERATE_REVIEW_SECTION_DUPLICATE`); there is no other `##` section
+      (`E_OPERATE_REVIEW_SECTION_UNEXPECTED`); and the sections follow the order listed below
+      (`E_OPERATE_REVIEW_SECTION_ORDER`).
+- [ ] Check section items, section fields and item fields only in sections that are present. A
+      missing section is reported once, as `E_OPERATE_REVIEW_SECTION_MISSING`, and yields no
+      field or item code for what it would have held. The preamble fields are always checked.
+- [ ] Each required field is written as `- **Name:** value` or `> **Name:** value`, appears once
+      in its scope (`E_OPERATE_REVIEW_FIELD_DUPLICATE`), and holds a real value, not empty, `...`,
+      `TBD`, `TODO` or a `<placeholder>` (`E_OPERATE_REVIEW_FIELD_MISSING`).
+- [ ] A field with a fixed value list uses one of the listed values exactly
+      (`E_OPERATE_REVIEW_FIELD_VALUE_INVALID`).
+- [ ] The item section holds at least one item or its exact empty-state sentence
+      (`E_OPERATE_REVIEW_ITEM_OR_EMPTY_STATE_MISSING`), at most five items
+      (`E_OPERATE_REVIEW_ITEM_LIMIT`), headed `### <prefix><n> — <title>` and numbered 1, 2, 3
+      with no gaps or repeats (`E_OPERATE_REVIEW_ITEM_SEQUENCE`).
+- [ ] `Decision-changing gaps` is `None.` or a list within its limit (advisor and challenger 3,
+      chair and board-report 5) counted as `- ` lines (`E_OPERATE_REVIEW_SECTION_ITEM_LIMIT`).
+
+## advisor
+
+- [ ] Preamble fields: `Signal` (`action`, `watch` or `insufficient context`) and `Bottom line`.
+- [ ] Sections: `Findings`, `Recommended next move`, `Decision-changing gaps`,
+      `Sources consulted`.
+- [ ] Items `F1`…`F5` under `Findings`, or `No decision-relevant finding was established.` Each
+      has `Priority` (`P0`, `P1`, `P2` or `unranked`), `Status` (`observed` or `inferred`),
+      `Why it matters`, `Sources`, `Confidence` and `Decision impact`.
+- [ ] `Recommended next move` is exactly `No recommendation from current context.` or has
+      `Recommendation`, `Suggested owner`, `First step`, `Expected result`, `Check` and
+      `Revisit when`.
+
+## challenger
+
+- [ ] Preamble fields: `Verdict` (`holds`, `holds with exceptions` or `not decision-ready`) and
+      `Bottom line`.
+- [ ] Sections: `Material exceptions`, `Decisions that still hold`, `Risks and dissent`,
+      `Decision-changing gaps`.
+- [ ] Items `X1`…`X5` under `Material exceptions`, or `No material exception found.` Each has
+      `Target`, `Type` (`unsupported`, `contradicted`, `correlated reasoning`,
+      `missing alternative`, `unpriced downside` or `overconfident`), `Decision impact`,
+      `Challenge`, `Sources` and `Resolution`.
+- [ ] `Risks and dissent` has `Dissent` and `Resolution condition`.
+
+## chair
+
+- [ ] Preamble fields: `Overall signal` (`act now`, `decide next`, `watch` or
+      `insufficient context`) and `Executive call`.
+- [ ] Sections: `Decision queue`, `Action plan`, `Risks and dissent`, `Decision-changing gaps`,
+      `Review coverage`.
+- [ ] The decision queue and action plan items below.
+
+## board-report
+
+- [ ] No preamble fields are required.
+- [ ] Sections: `Scope`, `Executive summary`, `Decision queue`, `Action plan`,
+      `Risks and dissent`, `Decision-changing gaps`, `Review coverage`, `Issues`.
+- [ ] `Scope` has `Subject`, `Window`, `Requested decision` and `Custody`.
+- [ ] `Executive summary` is not empty (`E_OPERATE_REVIEW_SUMMARY_MISSING`); a missing
+      `Executive summary` section is reported both as `E_OPERATE_REVIEW_SECTION_MISSING` and as
+      `E_OPERATE_REVIEW_SUMMARY_MISSING`.
+- [ ] Exceptions to "a missing section yields no other code": with at least one decision, a
+      missing `Action plan` (chair or board-report) also yields
+      `E_OPERATE_REVIEW_ACTION_PLAN_INVALID`; in a contract 1.0.0 note, a missing `Executive call`
+      also yields `E_OPERATE_REVIEW_EXECUTIVE_CALL_MISSING` and a missing `Human gate` also yields
+      `E_OPERATE_REVIEW_HUMAN_GATE_INCOMPLETE`.
+- [ ] The decision queue and action plan items below.
+
+## Decision queue and action plan (chair and board-report)
+
+- [ ] Items `D1`…`D5` under `Decision queue`, or `No decision-ready proposal was established.`
+- [ ] Each heading carries a priority: `### D1 — [P0] <title>`, with `P0`, `P1`, `P2` or
+      `unranked` (`E_OPERATE_REVIEW_ITEM_HEADING_INVALID`).
+- [ ] Each decision has `Recommendation`, `Why now`, `Suggested owner`, `Confidence`,
+      `Alternative`, `First step`, `Expected result`, `Check`, `Dependencies`, `Revisit when`,
+      `Sources` and `Dissent`.
+- [ ] With at least one decision, `Action plan` has the table header
+      `| ID | Priority | Action | Suggested owner | First step | Success measure | Check | Depends on |`
+      and at least one `A<n>` row (`E_OPERATE_REVIEW_ACTION_PLAN_INVALID`).
+- [ ] The action plan has at most seven rows (`E_OPERATE_REVIEW_ACTION_LIMIT`), and every row
+      has exactly eight columns, none empty or a placeholder from the field list above (`...`,
+      `TBD`, `TODO`, `<placeholder>`); `—` is accepted, for example in `Depends on`
+      (`E_OPERATE_REVIEW_ACTION_ROW_INVALID`).
+
+## Older notes (contract 1.0.0)
+
+Only for reading a note that declares `operate-human-review-contract@1.0.0`; never write one.
+Its sections and fields differ from the lists above. A 1.0.0 board report also needs:
+
+- [ ] A non-empty `Executive call` section (`E_OPERATE_REVIEW_EXECUTIVE_CALL_MISSING`).
+- [ ] A `Human gate` with one statement per decision naming adopt, reject, defer, the decision's
+      owner and a reason; with no decision, it offers close, supply evidence, and re-run for any
+      absent review seat (`E_OPERATE_REVIEW_HUMAN_GATE_INCOMPLETE`), and never offers adopt,
+      reject or defer (`E_OPERATE_REVIEW_HUMAN_GATE_CONTRADICTORY`).
+
+A caller that requires a conforming note fails it as a whole when any item above is unresolved
+(`E_OPERATE_REVIEW_NOTE_INVALID`); that whole-note code is never listed on the `CODES:` line.
+
+## Report format
+
+End the reply with exactly one line: `CODES: ` followed by every distinct code from the items
+above, each written in full, sorted alphabetically and comma-separated; write
+`CODES: none` when every item passes. Each code appears once however many times the problem
+occurs.

package/lib/host-packages/claude/openplanr/skills/operate/references/return-contract.md

@@ -0,0 +1,10 @@
+# Return rules
+
+Shared by Spec, Plan, Plan Review, Ship, Operate and Release. Each skill lists its own fields.
+
+- Lead with the outcome: what is ready, prepared or released, then what is partial or blocked.
+- Link durable artifacts by purpose. Keep inventories, command output and transcripts in their files.
+- Report only checks you ran, with their result. Name each check you could not run and what stays unverified.
+- Omit empty fields. Give each open issue its impact and the smallest recovery action.
+- The summary is a human view, not a schema. Different wording never calls for a rerun or a correction pass.
+- Keep any machine-readable field a skill defines unchanged.

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

@@ -14,14 +14,11 @@ automatically.
 
 ## Resolve context directly
 
-Read the strongest available inputs:
-
-1. the request and selected specification;
-2. repository instructions (`AGENTS.md`, `CLAUDE.md`, or equivalents), ADRs,
-   planning rules, and active stack files named by the repository;
-3. relevant implementation code, tests, package scripts, and CI configuration;
-4. design inputs and design specifications when a browser surface is involved;
-5. the database schema or persistence code when data behavior is involved.
+Read the request, the selected specification and the files either names, plus
+`AGENTS.md` and `CLAUDE.md` when tracked, in one batch. Expand only for a missing
+contract, a dependency or a contradiction, and stop when each claim has evidence
+or a named gap. Read design inputs when a browser surface is involved and the
+schema or persistence code when data behavior is involved.
 
 Use repository-local conventions first. Missing legacy `input/` or `.planr/`
 paths do not block a clear request. State what was unavailable and continue when
@@ -93,11 +90,10 @@ Read [the artifact contract](references/artifact-contract.md) before writing.
 Write stories and tasks directly in the repository's active planning mode.
 
 - Allocate project-global monotonic `US-NNN` and `T-NNN` IDs. Never reuse a
-  deleted ID. The packaged [planning ID helper](scripts/planning-ids.mjs) may
-  inspect or reserve IDs; it never generates content. Pass `--root` with the
-  `specs` folder under the project's configured planning path (`.planr/specs`
-  by default). It exits non-zero when that folder is missing or is not the one
-  `.planr/config.json` configures; never fall back to `US-001` or `T-001`.
+  deleted ID. Follow [the planning ID procedure](references/planning-ids.md)
+  immediately before writing: it reads the stored sequence and the existing
+  files, never overwrites an artifact, and never falls back to `US-001` or
+  `T-001`.
 - Give each story stable acceptance IDs starting at `AC-001`.
 - Split each story into tasks that are coherent and independently verifiable.
   Separate by ownership first: UI work is a `UI` task for the frontend role and
@@ -116,9 +112,12 @@ Write stories and tasks directly in the repository's active planning mode.
 - Name concrete files and repository-grounded checks. Preserve established
   repository headings when they carry additional information.
 
-Validate all frontmatter and acceptance coverage before finishing. If a helper
-is unavailable, inspect existing IDs and validate the same invariants directly;
-do not route semantic work to a CLI fallback.
+Before finishing, check directly that every story and task frontmatter is
+valid, every acceptance ID is mapped through `acceptanceRefs` and named under
+`## Test Requirements`, and no ID repeats an existing one. When
+`command -v openplanr` succeeds and a `SPEC-NNN` exists,
+`openplanr spec sync <SPEC-ID> --dry-run` adds an orphan and schema-drift check
+and writes nothing. Do not route semantic work to a CLI fallback.
 
 For approved design input, author the complete story and task bytes before
 touching target paths, then commit those bytes and the sibling
@@ -142,7 +141,7 @@ instead of repeating every path in chat.
   (Codex/ChatGPT) or the `planr-ship` rule (Cursor).
 
 Mention the planning layout or consulted lenses only when they explain a material
-choice. Different summary wording never requires another planning run.
+choice. Follow [the shared return rules](references/return-contract.md).
 
 When the OpenPlanr dashboard is running, the planned graph is browsable at
 `#/board`; open one story at `#/detail/<US-###>`.

package/lib/host-packages/claude/openplanr/skills/plan/references/planning-ids.md

@@ -0,0 +1,53 @@
+# Allocate planning IDs
+
+`SPEC-NNN`, `US-NNN` and `T-NNN` are project-global and monotonic. Allocate them
+with your own file tools; never reuse a deleted ID and never fall back to
+`US-001` or `T-001` because the sequence looked empty.
+
+1. **Find the specs root.** Read `.planr/config.json` and take
+   `outputPaths.agile` (default `.planr`). The specs root is
+   `<agile>/specs`. Stop and report when the config is missing or not valid
+   JSON, or when the specs root does not exist or is not a directory; do not
+   create it.
+2. **Respect the CLI's lock.** If `<specs root>/.id-sequence.lock` exists, an
+   `openplanr` command is reserving IDs. Wait about five seconds and check
+   again. If it is still there, stop and tell the user that
+   `.id-sequence.lock` is held and to retry when the `openplanr` command
+   finishes; delete the lock only if they confirm no `openplanr` command is
+   running. Never write while the lock exists.
+3. **Read the stored sequence.** If `<specs root>/.id-sequence.json` exists, it
+   must have `kind: "planning-id-sequence"`, `protocolVersion: "1.7.0"` and a
+   positive integer `next.SPEC`, `next.US` and `next.T`. Stop and report when it
+   does not; never repair or replace it silently. A missing file means every
+   stored `next` is 1.
+4. **Scan existing IDs.** List the specs root recursively, skipping directories
+   whose names start with `.`. For each file or directory name that starts with
+   `SPEC-`, `US-` or `T-` followed by three or more digits, keep the highest
+   number per kind.
+5. **Choose the first ID.** For each kind, `next = max(stored next, highest + 1)`.
+   Number the new artifacts upward from `next`, padded to at least three digits
+   (`US-015`, `T-120`).
+6. **Never overwrite.** Immediately before writing each artifact, confirm no file
+   or directory with that ID exists anywhere under the specs root. If one does,
+   take the next number and check again.
+7. **Advance the sequence.** After writing, check the lock again (step 2),
+   then write `.id-sequence.json` in the specs root with two-space
+   indentation and a final newline. Each `next` is one past the highest ID you
+   wrote, or the value from step 5 for a kind you did not use. Never lower a
+   value. After writing `US-015` and `T-041`, for example:
+
+   ```json
+   {
+     "kind": "planning-id-sequence",
+     "schemaVersion": "1.0.0",
+     "protocolVersion": "1.7.0",
+     "next": {
+       "SPEC": 4,
+       "US": 16,
+       "T": 42
+     }
+   }
+   ```
+
+Re-run steps 2–5 right before writing rather than reusing numbers from earlier in
+the session: another writer may have added artifacts since.

package/lib/host-packages/claude/openplanr/skills/plan/references/return-contract.md

@@ -0,0 +1,10 @@
+# Return rules
+
+Shared by Spec, Plan, Plan Review, Ship, Operate and Release. Each skill lists its own fields.
+
+- Lead with the outcome: what is ready, prepared or released, then what is partial or blocked.
+- Link durable artifacts by purpose. Keep inventories, command output and transcripts in their files.
+- Report only checks you ran, with their result. Name each check you could not run and what stays unverified.
+- Omit empty fields. Give each open issue its impact and the smallest recovery action.
+- The summary is a human view, not a schema. Different wording never calls for a rerun or a correction pass.
+- Keep any machine-readable field a skill defines unchanged.

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

@@ -6,9 +6,11 @@ license: MIT
 
 # OpenPlanr 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.
+Give the plan a senior, practical review. Read the plan and the files it names,
+plus `AGENTS.md` and `CLAUDE.md` when tracked, in one batch. Expand only for a
+missing contract, a dependency or a contradiction, and stop when each claim has
+evidence or a named gap. Use only the review lenses relevant to the work; do not
+manufacture a fixed committee.
 
 ## Review
 
@@ -42,6 +44,4 @@ the plan materially changes.
 
 Link the reviewed plan and locate each actionable finding. State what was
 inspected and any material evidence gap; a source review is not a passing test
-run. Omit empty categories and raw agent transcripts. Expand findings when their
-impact needs explanation, without requiring a fixed chat layout or a corrective
-review just for wording.
+run. Follow [the shared return rules](references/return-contract.md).

package/lib/host-packages/claude/openplanr/skills/plan-review/references/return-contract.md

@@ -0,0 +1,10 @@
+# Return rules
+
+Shared by Spec, Plan, Plan Review, Ship, Operate and Release. Each skill lists its own fields.
+
+- Lead with the outcome: what is ready, prepared or released, then what is partial or blocked.
+- Link durable artifacts by purpose. Keep inventories, command output and transcripts in their files.
+- Report only checks you ran, with their result. Name each check you could not run and what stays unverified.
+- Omit empty fields. Give each open issue its impact and the smallest recovery action.
+- The summary is a human view, not a schema. Different wording never calls for a rerun or a correction pass.
+- Keep any machine-readable field a skill defines unchanged.

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

@@ -6,49 +6,39 @@ license: MIT
 
 # OpenPlanr 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.
+Classify what shipped by what users must do or expect differently, then say so in their language. This skill owns versioning and release communication after implementation; use `planr-land` for merge readiness and `planr-ship` for code.
 
-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.
+## Do only the verb
 
-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.
+| The user asks for | Do | Never, unless also asked |
+|---|---|---|
+| Release notes, a summary of what changed, or a proposed version | Steps 0 to 4 (Step 0 only reads). Return the notes and the proposed version in chat. | Write `CHANGELOG.md` or `.release/profile.md`, bump a version, run tests, tag |
+| Prepare or cut a release | Steps 0 to 5 | Push, tag, publish, deploy |
+| A tag, a publication or an announcement | That one external effect, after Step 5 is done | Anything else external |
 
-## Step 0: Load the release profile
+A request for release notes or a proposed version changes no file, bumps no version and runs no tests, and never writes the profile.
 
-Look for `.release/profile.md` at the repo root. It records the scheme, cadence, public surface and voice already chosen for this product.
+## Step 0: Load the release profile
 
-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.
+Read `.release/profile.md`, plus `AGENTS.md` and `CLAUDE.md` when tracked, in one batch. Expand only for a missing contract, a dependency or a contradiction, and stop when each claim has evidence or a named gap.
 
-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.
+When the profile exists, follow it; do not re-argue the scheme. When it does not, propose a scheme and the bump in your answer from the recent tags and the public surface, and say the profile is missing; do not write it for a notes-only request. Choose a scheme and write a profile only on first-time setup, when the user asks to set one up, or when preparing the first release: read [the versioning schemes guide](references/schemes.md), get the user's agreement, then write it with the [release profile template](assets/profile-template.md).
 
 ## 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.
+These steps only read. Treat the output as evidence to classify, not as release notes. Run each git command on its own and check its exit status. A failure other than "no tag found" stops collection: report the command and its error text, and never read it as an empty window.
 
-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.
+1. **Base.** If the user names a period ("this week", "since the 1st"), turn it into a date `YYYY-MM-DD` and use `--since=<date>` as the log range. Otherwise find the last tag with `git describe --tags --abbrev=0`, read its date with `git log -1 --format=%cs <tag>`, and use `<tag>..HEAD` as the range. With no tag at all, the window is all history: drop the range from the commands below. Record the base (`git rev-parse <tag>`, or the date) and the head (`git rev-parse HEAD`) in your return.
+2. **Recent tags.** Run `git tag --list --sort=-creatordate` and keep the first five. Match their format when you tag.
+3. **Commits.** Run `git log <range> --no-merges --pretty=format:'%h %s'`.
+4. **Bodies and footers.** Run `git log <range> --no-merges --pretty=format:'--- %h%n%b'` and read every body. A `BREAKING CHANGE:` footer, or `!` after the type, makes the change Breaking whatever its subject says; a `Revert` subject and the change it reverts cancel out.
+5. **Files touched, by area.** Run `git log <range> --name-only --pretty=format:`, drop blank lines, and reduce each path to its first two segments (`src/cli` for `src/cli/run.ts`; a top-level file stays as it is). Count the paths per area, sort by count, highest first, and keep the top 20.
+6. **Merged PRs.** Only when pull-request context is useful, `gh` is installed and the window has a date (the user's date or the last tag's), run `gh pr list --state merged --search "merged:>=<date>" --limit 100 --json number,title`. If it fails, say so and suggest `gh auth status`; do not drop the section silently.
+7. **Gaps.** Before finalizing, check whether this misses config or feature-flag changes, infrastructure, work from other repositories, or other user-visible behavior. Git cannot see these, so use any product summary in the request or repository; if material non-Git changes could alter the notes, ask one concise question.
 
 ## 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.
+For every unit of work ask: **does a user have to do, know, or expect something different now?** Code size does not matter; a one line default change can be breaking.
 
 | Class | Test | Notes |
 |---|---|---|
@@ -60,129 +50,40 @@ For every unit of work, ask one question: **does a user have to do, know, or exp
 | 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.
+Keep Internal work out of user-facing notes.
 
-Two rules that hold under any scheme:
+## Step 3: Decide the bump
 
-- 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.
+Work the classification against the profile's scheme. SemVer: any Breaking change is MAJOR, a new compatible capability is MINOR, everything else PATCH. For hosted products, treat a change as breaking if a user's saved workflow, integration, bookmark or stored data stops working the way it did. CalVer: the number encodes time, so the notes lead with breaking changes. The [schemes guide](references/schemes.md) has the edge cases.
 
-## Step 5: Cadence
+Under any scheme: one release, one version, never one per commit or deploy; a breaking change ships alone; and keep the existing tag format (a repository tagged `v1.2.0` must not get `1.3.0`).
 
-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.
+## Step 4: Write the release notes
 
-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.
+Read [the release notes guide](references/release-notes.md) before writing; it carries the voice rules and worked rewrites. Follow Keep a Changelog: a `## [version] - date` heading, then `### Removed`, `### Added`, `### Changed` and `### Fixed`, in the order that costs the reader most if missed (Removed and any breaking Changed first). Omit empty sections. One line per entry, led by what the user can now do, with fixes described by the symptom users saw.
 
-Default rhythm for a daily-to-weekly product:
+## Step 5: Prepare the local release
 
-- 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
+Only when the user asks to prepare or cut a 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.
+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. Run the repository's release checks. Confirm every release-note entry maps to shipped behavior and every user-visible change in the window is represented.
+4. Push tags, publish packages, create hosted releases, post announcements, or deploy only when the user explicitly requests that external effect.
 
 ## Return
 
-Lead with what was prepared locally or actually released. Preparing notes or
-versions is not publication. Link the durable notes, summarize checks actually
-performed, and name any incomplete step with its impact and recovery action.
+Lead with what was prepared locally or actually released; preparing notes or versions is not publication. Follow [the shared return rules](references/return-contract.md).
 
-- **Version:** current and proposed versions, scheme, and bump rationale.
+- **Version:** current and proposed versions, scheme, bump rationale, and the base and head revisions.
 - **Included:** user-visible changes in the release window.
-- **Notes:** the release-note text or changed changelog path.
-- **Checks:** release verification performed and results.
+- **Notes:** the release-note text, or the changed changelog path when one was written.
+- **Checks:** release verification performed and results, or `not run` for a notes-only request.
 - **Next:** the one remaining local or external release action, or `none`.
 
-Keep the complete release window in the notes rather than repeating its commit
-inventory. Omit empty sections in the human summary; different wording does not
-require a second version bump or release action.
-
-## 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
+## References
 
-- [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
+- [Versioning schemes](references/schemes.md): read on first setup or when asked to choose a scheme.
+- [Release cadence and health](references/cadence.md): read for cadence, hotfixes, freezes, a bad release or a versioning health check.
+- [Release notes](references/release-notes.md): voice rules and worked rewrites, read before writing notes.
+- [Release profile template](assets/profile-template.md) and [changelog template](assets/changelog-template.md): read when writing either file.

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

@@ -7,6 +7,7 @@ Contents:
 4. Hotfixes
 5. When a release goes out wrong
 6. Freezes and quiet periods
+7. Long-term health
 
 ---
 
@@ -90,3 +91,12 @@ Worth declaring in the profile if they apply:
 - 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`.
+
+## 7. 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.

package/lib/host-packages/claude/openplanr/skills/release/references/release-notes.md

@@ -83,7 +83,7 @@ A breaking change entry needs four things in one or two lines: what changed, wha
 
 Rules:
 
-- Put it first, before Added. The reader who stops after three lines must have seen it.
+- Put it first, before Added. A Removed entry always carries its migration step inline, in the entry itself, and names features exactly as the product UI does. The reader who stops after three lines must have seen it.
 - Never bundle it into a list of unrelated improvements. It gets its own section and, where possible, its own release.
 - A changelog entry is not sufficient notice on its own. Anything with an integration cost also needs an in-product notice or a direct message to affected users, because most people do not read changelogs.
 - State the date, not "soon".

package/lib/host-packages/claude/openplanr/skills/release/references/return-contract.md

@@ -0,0 +1,10 @@
+# Return rules
+
+Shared by Spec, Plan, Plan Review, Ship, Operate and Release. Each skill lists its own fields.
+
+- Lead with the outcome: what is ready, prepared or released, then what is partial or blocked.
+- Link durable artifacts by purpose. Keep inventories, command output and transcripts in their files.
+- Report only checks you ran, with their result. Name each check you could not run and what stays unverified.
+- Omit empty fields. Give each open issue its impact and the smallest recovery action.
+- The summary is a human view, not a schema. Different wording never calls for a rerun or a correction pass.
+- Keep any machine-readable field a skill defines unchanged.

package/lib/host-packages/claude/openplanr/skills/release/references/schemes.md

@@ -35,10 +35,12 @@ Anything outside the declared surface can change in a patch. This is what makes
 
 **Bump rules:**
 
-- MAJOR: remove or rename anything in the surface, change a response or return shape, change a default that alters outcomes, tighten validation to reject formerly valid input, add a required parameter, change error semantics that callers branch on.
-- MINOR: add to the surface, add an optional parameter, add a new endpoint or export, ship a deprecation warning.
+- MAJOR: remove or rename anything in the surface, change a response or return shape, change a default that alters outcomes, tighten validation to reject formerly valid input, rename config, add a required field or parameter, change error semantics that callers branch on.
+- MINOR: add to the surface, add an optional parameter, add a new endpoint or export. The release that first ships a deprecation warning is a MINOR; the removal it announces is the MAJOR.
 - PATCH: fix behavior to match documentation, performance, internal changes, dependency updates with no surface impact.
 
+**Hosted products.** SemVer's "breaking" needs translating, because there is no compilation step to fail. Treat a change 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.
+
 **The judgement call that comes up most:** a bug fix that changes behavior people depend on. Strictly it is a fix, but if the buggy behavior is load-bearing for existing users, treat it as breaking. The test is whether shipping it silently would generate support tickets.
 
 ---