openplanr 3.4.0 → 3.6.0

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

@@ -3,7 +3,7 @@
   "schemaVersion": "1.0.0",
   "protocolVersion": "1.8.0",
   "skillId": "planr-plan",
-  "skillVersion": "1.3.0",
+  "skillVersion": "1.5.0",
   "entrypoint": "SKILL.md",
   "hosts": [
     "claude-code",
@@ -45,26 +45,26 @@
       "executable": false
     },
     {
-      "path": "scripts/planning-ids.mjs",
-      "kind": "script",
+      "path": "references/planning-ids.md",
+      "kind": "reference",
       "hosts": [
         "claude-code",
         "codex",
         "chatgpt",
         "cursor"
       ],
-      "executable": true
+      "executable": false
     },
     {
-      "path": "scripts/design.mjs",
-      "kind": "script",
-      "executable": true,
+      "path": "references/return-contract.md",
+      "kind": "reference",
       "hosts": [
         "claude-code",
         "codex",
         "chatgpt",
         "cursor"
-      ]
+      ],
+      "executable": false
     },
     {
       "path": "schemas/design-document.schema.json",

package/lib/host-packages/openai/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/openai/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/openai/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/openai/openplanr/skills/plan-review/openplanr.skill.json

@@ -3,7 +3,7 @@
   "schemaVersion": "1.0.0",
   "protocolVersion": "1.8.0",
   "skillId": "planr-plan-review",
-  "skillVersion": "1.0.1",
+  "skillVersion": "1.1.0",
   "entrypoint": "SKILL.md",
   "hosts": [
     "claude-code",
@@ -21,6 +21,17 @@
         "chatgpt"
       ],
       "executable": false
+    },
+    {
+      "path": "references/return-contract.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
     }
   ]
 }

package/lib/host-packages/openai/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/openai/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/openai/openplanr/skills/release/openplanr.skill.json

@@ -3,7 +3,7 @@
   "schemaVersion": "1.0.0",
   "protocolVersion": "1.8.0",
   "skillId": "planr-release",
-  "skillVersion": "1.0.1",
+  "skillVersion": "1.3.0",
   "entrypoint": "SKILL.md",
   "hosts": [
     "claude-code",
@@ -78,15 +78,15 @@
       "executable": false
     },
     {
-      "path": "scripts/collect_changes.sh",
-      "kind": "script",
+      "path": "references/return-contract.md",
+      "kind": "reference",
       "hosts": [
         "claude-code",
         "codex",
         "chatgpt",
         "cursor"
       ],
-      "executable": true
+      "executable": false
     }
   ]
 }

package/lib/host-packages/openai/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/openai/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/openai/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/openai/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.
 
 ---

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

@@ -17,10 +17,11 @@ plain Ship never launches its helper. Keep the work local; do not publish or dep
 
 For a selector, locate exactly one task and read it completely. Then follow its
 `storyId` and `specId` to the parent story, acceptance criteria, Gherkin file
-when present, and specification. Also read repository instructions, ADRs,
-planning rules, applicable stack guidance, relevant design/database context,
-implementation code, tests, and interfaces produced by declared dependencies. Read any
-`.planr/conventions/<area>.md`, indexed from AGENTS.md, for the areas this task touches.
+when present, and specification. Read the files the task names, plus `AGENTS.md` and
+`CLAUDE.md` when tracked, in one batch, and any `.planr/conventions/<area>.md` indexed
+from AGENTS.md for the areas this task touches. Expand only for a missing contract, a
+dependency's interface or a contradiction, and stop when each claim has evidence or a
+named gap.
 
 Read [the design lineage contract](references/design-lineage.md). If the selected
 planning root contains `design-lineage.json`, load only the selected task's mapped
@@ -78,29 +79,43 @@ its `changed` list with `git diff --name-only` plus untracked files; report any
 
 ## Discover and run verification
 
-Discover checks in this order:
+Inspect these sources directly, in this order:
 
 1. task Test Requirements;
 2. repository instructions;
 3. package and task-runner scripts;
-4. applicable CI and pre-commit configuration.
-
-Run `openplanr ship checks --json --task <task-path>` (omit `--task` for a direct
-request; add `--tier story` or `--tier push` before pushing) and run its `checks`
-from each `cwd`. The command never executes checks or writes files. When
+4. applicable CI configuration, the pre-commit hook (for example lint-staged) and the
+   pre-push hook, when present, whatever the change touches.
+
+List each candidate check with its `cwd` and the source that named it. Discovery
+only reads sources: never build, install or execute a check while discovering;
+running checks is a later step. Then run the candidates from each `cwd`. Let the change pick checks: when it touches a build input (a
+`tsconfig*.json`, a bundler config, or a package's `main`, `exports`, `bin` or
+`build` scripts), include the build CI runs; prefer tests related to the changed
+files. Before pushing, include every CI job whose triggers and path filters fire
+for the changed paths, and for a published package that gains non-code files, a
+dry-run pack that confirms they are packed. When a workflow selects jobs at
+runtime (a `changes` or paths-filter job whose outputs gate other jobs), list every job it
+gates and mark each conditional. Run a conditional job when a local equivalent command
+exists; otherwise report it as "conditional, not run". Never drop one silently or by
+reading the paths yourself. Read every workflow file whose triggers fire for the
+change, not only the main one: dedicated browser, end-to-end and sandbox workflows are sources too. List a git hook as
+its own command and, when it delegates to a script, also each check that script runs.
+Discovery lists what the sources define whatever the size or kind of the change, a
+documentation-only change included; the change picks only which listed checks you run.
+Missing commands are diagnostics, not a reason to invent or
+skip all verification.
+
+If `openplanr` is already on `PATH`, `openplanr ship checks --json --task <task-path>`
+(omit `--task` for a direct request; add `--tier story` or `--tier push` before
+pushing) adds `complete` and diagnostics. The command never executes checks or writes files. When
 `complete` is `false`, report its error diagnostics and treat the check set as
 incomplete: a pass is not CI-equivalent. Act on warning diagnostics too; each names
 the files or checks it affects. A diagnostic that a check could not run, such as
 `TYPESCRIPT_UNAVAILABLE`, is not a pass: name that check in `checks` and verify its
 concern yourself where you can (for a new test file, confirm some tsconfig includes
 it). For a `package-contents` check, account for every `expectFiles` entry in the
-tarball's `files`: packed or deliberately left out. Without
-the CLI, the packaged read-only [verification discovery helper](scripts/discover-verification.mjs)
-may list candidates. Resolve it relative to this `SKILL.md` and run
-`node <helper> --project <repository-root> --task <task-path>`; omit `--task` for a
-direct request. It never executes checks or writes files. If both are unavailable,
-inspect those four sources directly. Missing commands are diagnostics, not a
-reason to invent or skip all verification.
+tarball's `files`: packed or deliberately left out.
 
 Run the strongest applicable focused checks while working, then the relevant
 regression checks. Run each check on its own or under `set -o pipefail`, and judge
@@ -111,9 +126,9 @@ For an acceptance check written or changed for this task, follow
 Read [the result contract](references/result-contract.md) before reporting.
 
 Report defects you notice outside the task as [findings](references/findings.md),
-and never fix them in this change unless they block it. The packaged
-[backlog helper](scripts/backlog-item.mjs) lists and files backlog items when no
-CLI is installed; resolve it relative to this `SKILL.md`.
+and never fix them in this change unless they block it.
+[Backlog filing](references/backlog-filing.md) lists and files backlog items with
+your own file tools.
 
 Do not write progress into an approved design package. The studio derives
 approved, planned, implementing, and verified state from canonical planning and
@@ -135,10 +150,8 @@ results instead of reproducing them in chat.
 - **Issues:** blockers with problem, impact, and next action, or `none`; then
   findings outside the task, each with its disposition.
 
-Keep the five machine fields unchanged. A human summary may omit empty or unavailable fields,
-but must make partial, blocked or unverified work clear and give the smallest
-recovery action. Preserve native transcripts; never require another execution
-or correction just to change summary wording.
+Keep the five machine fields unchanged. Follow [the shared return rules](references/return-contract.md);
+the summary must make partial, blocked or unverified work clear.
 
 Suggest `planr-land` only when a landing step remains in the requested workflow.
 Do not add a next action when the requested scope is fulfilled. This guidance