openplanr 3.5.0 → 3.6.0

package/lib/host-packages/cursor/openplanr/rules/planr-release.mdc

@@ -5,49 +5,39 @@ alwaysApply: false
 
 # 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](planr-release/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](planr-release/references/schemes.md), get the user's agreement, then write it with the [release profile template](planr-release/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](planr-release/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 |
 |---|---|---|
@@ -59,129 +49,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](planr-release/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](planr-release/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](planr-release/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](planr-release/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](planr-release/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](planr-release/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](planr-release/references/schemes.md): full scheme selection guide, multi-line versioning, monorepo handling
-- [Release notes](planr-release/references/release-notes.md): voice rules, worked rewrites, per-channel formats
-- [Release cadence](planr-release/references/cadence.md): release rhythms, hotfixes, freezes, bad releases
-- [Release profile template](planr-release/assets/profile-template.md): the `.release/profile.md` written during setup
-- [Changelog template](planr-release/assets/changelog-template.md): starting `CHANGELOG.md`
-- [Change collector](planr-release/scripts/collect_changes.sh): gathers commits, optional merged PRs, and tag information for a window
+- [Versioning schemes](planr-release/references/schemes.md): read on first setup or when asked to choose a scheme.
+- [Release cadence and health](planr-release/references/cadence.md): read for cadence, hotfixes, freezes, a bad release or a versioning health check.
+- [Release notes](planr-release/references/release-notes.md): voice rules and worked rewrites, read before writing notes.
+- [Release profile template](planr-release/assets/profile-template.md) and [changelog template](planr-release/assets/changelog-template.md): read when writing either file.

package/lib/host-packages/cursor/openplanr/rules/planr-ship/references/backlog-filing.md

@@ -0,0 +1,102 @@
+# Backlog filing
+
+List and file backlog items with your own file tools. If `openplanr` is already on
+`PATH`, you may instead send each item as one JSON object on stdin to
+`openplanr --project-dir <repository-root> backlog add --data - --json`.
+
+## Where items live
+
+1. Read `.planr/config.json` at the repository root. If it is missing or is not
+   valid JSON, stop and report that the project has no OpenPlanr configuration.
+2. The backlog folder is `<outputPaths.agile>/backlog`, with `outputPaths.agile`
+   defaulting to `.planr`. The ID prefix is `idPrefix.backlog`, default `BL`.
+3. Issued IDs are empty marker files in `<backlog folder>/.issued-ids/`.
+
+## List open items
+
+List the files named `<PREFIX>-NNN-<slug>.md` in the backlog folder and read each
+frontmatter's `id`, `title` and `status`. An item is open unless its `status` is
+`closed` or `done`; a missing `status` counts as open.
+
+## Take an ID
+
+Do this immediately before writing each item, never earlier in the run:
+
+1. List the backlog folder and `.issued-ids/` again; create `.issued-ids/` if it is
+   missing.
+2. Find the highest `<PREFIX>-NNN` number among the file names in both. The new
+   number is that plus 1, or 1 when there is none, padded to at least 3 digits
+   (`BL-007`, `BL-1000`).
+3. Claim it by creating the empty file `.issued-ids/<ID>`. In a POSIX shell use a
+   no-clobber create, `(set -C; : > '<backlog folder>/.issued-ids/<ID>')`, or
+   elsewhere any create that fails when the file already exists, and treat a
+   failure as the ID being taken.
+4. If the marker already existed or any `<ID>-*.md` file exists, take the next
+   number and repeat step 3.
+
+Never overwrite or edit an existing backlog file or marker. A marker outlives its
+item, so the ID of a deleted item is never issued again.
+
+## Write the item
+
+Name the file `<ID>-<slug>.md` in the backlog folder. The slug is the title in
+lowercase with every character other than ASCII letters, digits, `_`, `-` and
+whitespace removed, runs of whitespace, `_` and `-` turned into one `-`, and
+leading or trailing `-` removed. When it is longer than 80 characters, cut it at 80, then back to the last
+`-`.
+
+The frontmatter needs every field below. Scalar values are double-quoted JSON strings;
+arrays use the flow form shown in the example:
+
+- `id`: the claimed ID.
+- `title`: one line.
+- `priority`: `critical`, `high`, `medium` or `low`.
+- `tags`: a list of quoted strings, `[]` when there are none.
+- `status`: `"open"`.
+- `created` and `updated`: today's date as `YYYY-MM-DD`.
+- `when`: `next-unit:<ref>`, `sprint:<SPRINT-NNN or next>`, `trigger:<event>`, or
+  `declined:<reason>`. Use a PR number, task ID, backlog ID, or branch for `<ref>`.
+  Never store `now`; it is a triage outcome. Trigger forms include
+  `date:YYYY-MM-DD`, `closed:<BL-NNN>`, `merged:#<PR>`, `merged:<branch>`, and
+  `release:<pkg>@<semver>`; other non-empty event text is allowed.
+- `files`: a list of quoted repo-relative paths, such as `["src/routes/import.ts"]`.
+  Omit line numbers, absolute paths and `..` segments. Use distinct paths from
+  the evidence, or `[]` when there are none.
+
+Older items may omit `when` and `files`. When listing them, derive files from
+body evidence such as `src/routes/import.ts:41` only if `files` is absent.
+
+The body is `# <ID>: <title>`, then `## Tags` with one `- <tag>` line per tag
+(omitted when there are none), then the description. A description that starts
+with its own `##` sections stands as written; otherwise it goes under
+`## Description`. End with a `---` line and the close line.
+
+```markdown
+---
+id: "BL-007"
+title: "Import endpoint has no rate limit"
+priority: "medium"
+tags: ["security", "api"]
+status: "open"
+created: "2026-11-08"
+updated: "2026-11-08"
+when: "next-unit:#612"
+files: ["src/routes/import.ts"]
+---
+
+# BL-007: Import endpoint has no rate limit
+
+## Tags
+
+- security
+- api
+
+## Problem
+
+`/import` accepts unlimited requests (`src/routes/import.ts:41`).
+
+---
+_Close when done: `openplanr backlog update BL-007 --status closed`_
+```
+
+Report the ID and the repo-relative path of each filed item.

package/lib/host-packages/cursor/openplanr/rules/planr-ship/references/findings.md

@@ -31,9 +31,8 @@ Merge duplicates within the run. Sort by severity, highest first, and number fro
 
 ## Check what is already tracked
 
-Before showing findings, list open backlog items with the backlog helper
-linked from SKILL.md, resolved relative to that file: `node <helper> list
---project <repository-root> --open`. A finding about the same problem as an open item,
+Before showing findings, list open backlog items as
+[backlog filing](backlog-filing.md) describes. A finding about the same problem as an open item,
 normally the same evidence file and an equivalent title, is `tracked`. Never file
 it again and never edit the existing item.
 
@@ -52,26 +51,19 @@ rule that applies. File only what it allows.
    example a print or exec mode), another skill or a delegate runner started this
    run, or the user said not to ask. Read `findings.unattended` in
    `.planr/config.json`. Only `file` files every untracked finding. With
-   `report`, or no setting, do not run `add` at all: mark the findings `reported`.
+   `report`, or no setting, do not file at all: mark the findings `reported`.
 
 Never ask per finding, never ask mid-run, and never file or drop a finding
 silently.
 
 ## File
 
-Send each item as one JSON object (`title`, `priority`, `tags`, `description`)
-on stdin. Never pass `acceptanceCriteria`.
+File each item from its `title`, `priority`, `tags` and `description` as
+[backlog filing](backlog-filing.md) describes. Never add acceptance criteria.
+When the `openplanr` command files it and the result says
+`templateOverrideIgnored`, say the default format was used.
 
-- When an `openplanr` CLI resolves (the project's `node_modules/.bin`, then
-  `PATH`; never `npx`): `openplanr --project-dir <repository-root> backlog add
-  --data - --json`.
-- Otherwise: `node <helper> add --project <repository-root> --data -`. Its
-  result can carry `cliHint`; end the result with that line, word for word,
-  once. Install only if the user says yes then, by running exactly the command in
-  the line. If the result says `templateOverrideIgnored`, say the default format
-  was used.
-
-If filing fails, report the command and its error, and leave the finding
+If filing fails, report the step and its error, and leave the finding
 `reported`.
 
 ## Report

package/lib/host-packages/cursor/openplanr/rules/planr-ship/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/cursor/openplanr/rules/planr-ship.mdc

@@ -16,10 +16,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](planr-ship/references/design-lineage.md). If the selected
 planning root contains `design-lineage.json`, load only the selected task's mapped
@@ -77,29 +78,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](planr-ship/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
@@ -110,9 +125,9 @@ For an acceptance check written or changed for this task, follow
 Read [the result contract](planr-ship/references/result-contract.md) before reporting.
 
 Report defects you notice outside the task as [findings](planr-ship/references/findings.md),
-and never fix them in this change unless they block it. The packaged
-[backlog helper](planr-ship/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](planr-ship/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
@@ -134,10 +149,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](planr-ship/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

package/lib/host-packages/cursor/openplanr/rules/planr-spec/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/cursor/openplanr/rules/planr-spec.mdc

@@ -11,10 +11,10 @@ another model process.
 
 ## Ground the specification
 
-Read the request, repository instructions, ADRs, product documentation,
-existing planning artifacts, relevant implementation code and tests, stack
-configuration, design inputs, database context, and current behavior. Infer
-facts the repository already answers.
+Read the files the request 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. Infer facts the repository
+already answers.
 
 When a missing decision materially changes scope or observable behavior, use
 the host's structured question interface. Ask no more than three short,
@@ -44,9 +44,10 @@ out-of-scope boundaries. Record concrete repository paths and verification
 signals when they are known. Keep unresolved questions out of the saved
 contract when a repository-backed default exists.
 
-Validate the completed artifact before returning. If a helper is unavailable,
-perform the same deterministic checks directly; never fall back to a
-model-backed CLI.
+Validate the completed artifact before returning: run `openplanr spec validate <SPEC-ID>`
+when `command -v openplanr` succeeds, otherwise check the path, frontmatter,
+headings and acceptance IDs against the specification contract directly. Never
+fall back to a model-backed CLI.
 
 ## Return
 
@@ -61,5 +62,4 @@ If the specification is partial or blocked, name the missing decision and its im
   none remains.
 - **Next:** a copy-ready host-native `planr-plan` invocation for the saved spec.
 
-The summary is a human view of the specification, not another schema or a reason
-to rerun a completed operation for different wording.
+Follow [the shared return rules](planr-spec/references/return-contract.md).

package/lib/host-packages/openai/.claude-plugin/marketplace.json

@@ -4,14 +4,14 @@
     "name": "OpenPlanr"
   },
   "metadata": {
-    "version": "3.5.0",
+    "version": "3.6.0",
     "description": "Generated local OpenPlanr package."
   },
   "plugins": [
     {
       "name": "planr",
       "source": "./openplanr",
-      "version": "3.5.0",
+      "version": "3.6.0",
       "description": "Close the loop from intent to delivery. Plans as files in your repo, checks before you merge, and a record of what shipped, in Claude Code, Codex and Cursor.",
       "strict": true
     }

package/lib/host-packages/openai/openplanr/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Close the loop from intent to delivery. Plans as files in your repo, checks before you merge, and a record of what shipped, in Claude Code, Codex and Cursor.",
   "author": {
     "name": "OpenPlanr",