openplanr 1.25.3 → 2.0.1

package/lib/host-packages/cursor/openplanr/rules/planr-release/references/schemes.md

@@ -0,0 +1,103 @@
+# Choosing and running a versioning scheme
+
+Contents:
+1. The question the version number answers
+2. SemVer
+3. CalVer
+4. Two version lines
+5. Monorepos
+6. Pre-1.0 and pre-release tags
+7. Worked selections
+
+---
+
+## 1. The question the version number answers
+
+A version number is a compression of "what am I dealing with". Different audiences ask different questions, and the scheme should answer the one that actually gets asked.
+
+- A developer who installed your package asks **"can I upgrade without breaking?"** That is a compatibility question, and SemVer answers it.
+- A user of a hosted app asks **"is this current, and what changed?"** That is a recency question, and CalVer answers it.
+- Support asks **"which build is this person on?"** Either works, as long as it is visible in the product.
+
+Pick the scheme that answers the question your actual audience asks. Applying SemVer to a SaaS dashboard where nobody can pin a version produces a number that looks meaningful and is not.
+
+---
+
+## 2. SemVer
+
+`MAJOR.MINOR.PATCH`, incremented on compatibility impact against a declared public API.
+
+Use when consumers pin, install or integrate: npm and PyPI packages, SDKs, CLIs, public HTTP APIs, anything with a dependency range pointed at it.
+
+**The prerequisite is a declared public surface.** Without it the scheme is unusable, because "breaking" is defined relative to something. Write the surface down in the profile. For a TypeScript package that means exported types and functions from the entrypoint, not everything importable via deep paths. For an HTTP API it means documented endpoints, request and response shapes, status codes, auth flow and webhook payloads.
+
+Anything outside the declared surface can change in a patch. This is what makes SemVer survivable: without a boundary, every internal rename is theoretically breaking and you never ship a minor again.
+
+**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.
+- PATCH: fix behavior to match documentation, performance, internal changes, dependency updates with no surface impact.
+
+**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.
+
+---
+
+## 3. CalVer
+
+`YYYY.MM.PATCH` (recommended default), `YYYY.MM.DD`, or `YY.MINOR.PATCH`.
+
+Use for hosted apps, internal tools, and anything where the user is always on the latest version because you put them there.
+
+**What it does well:** answers "how stale is this" instantly, no argument about whether something is a minor or a major, and it maps naturally onto a release rhythm.
+
+**What it cannot do:** carry a compatibility signal. `2026.09.1` to `2026.10.0` tells the reader nothing about whether anything broke. That obligation moves entirely onto the release notes, so a CalVer product must lead its notes with breaking changes and must announce them in-product, not just in a changelog nobody reads.
+
+Recommended format is `YYYY.MM.PATCH`: `2026.09.0` for the first September release, `2026.09.1` for the next. The month gives recency, the counter distinguishes multiple releases within it, and it sorts correctly as a string. Avoid `YYYY.M.D` with unpadded numbers, since it sorts wrong and reads ambiguously.
+
+---
+
+## 4. Two version lines
+
+The most common structural mistake is a single number covering both an app and the API it exposes. They change for unrelated reasons and have different audiences, so one number cannot serve both. A UI redesign is a big deal to users and a non-event to integrators. An API field rename is the reverse.
+
+When a product has both, run:
+
+- **App version:** CalVer, shown in the UI footer or settings, referenced in support and release notes.
+- **API version:** SemVer, or a dated URL version (`/v1/`, `2026-09-08`), governed by its own compatibility policy and deprecation timeline.
+
+Record both in the profile, with a note on which one the release notes are written against. Usually the app version leads and API changes appear as a clearly marked section.
+
+---
+
+## 5. Monorepos
+
+Two viable models. Pick one and record it.
+
+**Fixed (single version across all packages).** Every package ships the same number. Simple to reason about, simple to support, at the cost of publishing no-change versions for untouched packages. Good when the packages are only ever consumed together.
+
+**Independent (per-package versions).** Each package versions on its own changes. Correct for consumers, more machinery. Use Changesets in a JS/TS monorepo: contributors add a changeset describing the change and its bump level as part of the PR, and the tool aggregates them into version bumps and changelog entries at release time.
+
+Independent versioning plus Changesets is the better default when packages have separate consumers, because it captures the bump decision at the moment the author still remembers the intent, rather than reconstructing it from commit messages weeks later.
+
+---
+
+## 6. Pre-1.0 and pre-release tags
+
+**0.x** signals "the surface is not stable yet, expect breaks". Under SemVer convention, `0.MINOR.PATCH` treats minor as the breaking position. This is a legitimate state for something genuinely still forming.
+
+It stops being legitimate once real users depend on it. A product with paying customers on `0.x` is either lying about its stability or has forgotten to cut 1.0. Cutting 1.0 is a promise about the public surface, not a claim of feature completeness, and delaying it past the point of real usage costs credibility.
+
+**Pre-release identifiers:** `1.4.0-beta.1`, `2026.09.0-rc.2`. Use for builds going to a subset of users before general release. They sort before the final version, and package managers exclude them from normal ranges. Do not use them as a permanent staging label; something that lives on `-beta` for a year is just the product.
+
+---
+
+## 7. Worked selections
+
+**A booking site for a single business.** One audience, always on latest, no integrators. CalVer `YYYY.MM.PATCH`. The public surface is the booking flow itself, and the only breaking-class events are things like changing how existing appointment links resolve.
+
+**A mentorship platform with a Stripe-backed API and webhooks.** Two lines. CalVer for the app, SemVer for the API and webhook payloads, because integrators parse those payloads and a field rename genuinely breaks them. Webhook payload shape belongs in the declared public surface even though it is easy to forget.
+
+**A published npm package used by other teams.** SemVer, strict, with the declared surface listed as the entrypoint exports. Consumers automate upgrades against the number, so accuracy matters more than convenience.
+
+**An internal admin tool.** CalVer, minimal ceremony. Nobody pins it, and the useful question is "is this the build from before or after the fix".

package/lib/host-packages/cursor/openplanr/rules/planr-release/scripts/collect_changes.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Collect everything that shipped in a window, as raw material for release notes.
+#
+# Usage:
+#   ./collect_changes.sh                         # since the last tag
+#   ./collect_changes.sh "2026-09-01"            # since a date
+#   ./collect_changes.sh --include-prs            # include remote PR metadata
+#   ./collect_changes.sh "2026-09-01" --include-prs
+#
+# Output is raw material, not release notes. Classify it before writing.
+
+set -uo pipefail
+
+SINCE_ARG=""
+INCLUDE_PRS=0
+
+for ARG in "$@"; do
+  case "$ARG" in
+    --include-prs)
+      INCLUDE_PRS=1
+      ;;
+    -*)
+      printf 'Unknown option: %s\n' "$ARG" >&2
+      exit 2
+      ;;
+    *)
+      if [ -n "$SINCE_ARG" ]; then
+        printf 'Only one date window may be supplied.\n' >&2
+        exit 2
+      fi
+      SINCE_ARG="$ARG"
+      ;;
+  esac
+done
+
+if [ -n "$SINCE_ARG" ]; then
+  RANGE_DESC="since $SINCE_ARG"
+  LOG_ARGS=(--since="$SINCE_ARG")
+  PR_SEARCH="merged:>=$SINCE_ARG"
+else
+  LAST_TAG="$(git describe --tags --abbrev=0 2>/dev/null || true)"
+  if [ -z "$LAST_TAG" ]; then
+    RANGE_DESC="all history (no previous tag found)"
+    LOG_ARGS=()
+    PR_SEARCH=""
+  else
+    TAG_DATE="$(git log -1 --format=%cs "$LAST_TAG")"
+    RANGE_DESC="since $LAST_TAG ($TAG_DATE)"
+    LOG_ARGS=("$LAST_TAG..HEAD")
+    PR_SEARCH="merged:>=$TAG_DATE"
+  fi
+fi
+
+echo "=============================================="
+echo "Changes $RANGE_DESC"
+echo "=============================================="
+echo
+echo "--- Recent tags (match this format when tagging) ---"
+git tag --list --sort=-creatordate | head -5 || echo "none"
+echo
+echo "--- Commits (merges excluded) ---"
+git log "${LOG_ARGS[@]}" --no-merges --pretty=format:'%h %s' || true
+echo
+echo
+echo "--- Files touched, by area ---"
+git log "${LOG_ARGS[@]}" --name-only --pretty=format: 2>/dev/null \
+  | awk 'NF' \
+  | awk -F/ '{ if (NF>1) print $1"/"$2; else print $1 }' \
+  | sort | uniq -c | sort -rn | head -20
+echo
+echo "--- Merged PRs ---"
+if [ "$INCLUDE_PRS" -eq 1 ] && command -v gh >/dev/null 2>&1 && [ -n "$PR_SEARCH" ]; then
+  gh pr list --state merged --search "$PR_SEARCH" --limit 100 \
+    --json number,title \
+    --template '{{range .}}#{{.number}} {{.title}}{{"\n"}}{{end}}' 2>/dev/null \
+    || echo "gh is installed but the query failed. Check: gh auth status"
+else
+  echo "PR collection not requested, unavailable, or missing a date window."
+fi
+echo
+echo "=============================================="
+echo "Check whether this misses config or feature flag"
+echo "changes, infrastructure, work from other repos,"
+echo "or other user-visible behavior before finalizing."
+echo "=============================================="

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

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

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

@@ -0,0 +1,14 @@
+# Ship result contract
+
+Return one concise human rendering backed by these five machine fields:
+
+1. `outcome`: `completed`, `partial`, or `blocked`, plus the achieved result.
+2. `task`: exact task identity and path, or `direct-request`.
+3. `changed`: material files grouped by purpose.
+4. `checks`: each executed or applicable check with `passed`, `failed`, or
+   `not-run` and a concise result.
+5. `issues`: unresolved problem, impact, and next action; use `none` when empty.
+
+Do not add receipts, digests, proof ledgers, fixed review loops, or approval
+narration. Mention evidence only when it is the natural result of a command or
+test the user needs to understand.

package/lib/host-packages/cursor/openplanr/rules/planr-ship/scripts/discover-verification.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const COMMAND = /^(?:npm|npx|pnpm|yarn|bun|node|deno|cargo|go|make|just|pytest|python(?:3)?\s+-m|dotnet|mvn|gradle|\.\/gradlew)\b/u;
+const PRIORITY = Object.freeze(['test', 'test:unit', 'test:integration', 'typecheck', 'check', 'lint', 'build']);
+const read = (path) => readFileSync(path, 'utf8').replace(/\r\n/gu, '\n');
+
+function commands(markdown) {
+  const rows = [];
+  for (const match of markdown.matchAll(/```(?:bash|sh|shell|zsh)?\s*\n([\s\S]*?)```/gu)) {
+    for (const line of match[1].split('\n').map((value) => value.trim())) {
+      if (COMMAND.test(line)) rows.push(line);
+    }
+  }
+  for (const match of markdown.matchAll(/`([^`\n]+)`/gu)) {
+    const value = match[1].trim();
+    if (COMMAND.test(value)) rows.push(value);
+  }
+  return rows;
+}
+
+function section(markdown, heading) {
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+  return new RegExp(`^## ${escaped}\\s*$([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, 'mu').exec(markdown)?.[1] ?? '';
+}
+
+function files(directory, predicate) {
+  if (!existsSync(directory) || !statSync(directory).isDirectory()) return [];
+  return readdirSync(directory, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && predicate(entry.name))
+    .map((entry) => resolve(directory, entry.name))
+    .sort();
+}
+
+function packageChecks(root) {
+  const packagePath = resolve(root, 'package.json');
+  if (!existsSync(packagePath)) return [];
+  const scripts = JSON.parse(read(packagePath)).scripts ?? {};
+  const manager = existsSync(resolve(root, 'pnpm-lock.yaml')) ? 'pnpm'
+    : existsSync(resolve(root, 'yarn.lock')) ? 'yarn'
+      : existsSync(resolve(root, 'bun.lock')) || existsSync(resolve(root, 'bun.lockb')) ? 'bun'
+        : 'npm';
+  return Object.keys(scripts)
+    .filter((name) => PRIORITY.includes(name) || /^(?:test|check|lint|build|typecheck)(?::|$)/u.test(name))
+    .sort((left, right) => {
+      const a = PRIORITY.indexOf(left);
+      const b = PRIORITY.indexOf(right);
+      return (a < 0 ? 99 : a) - (b < 0 ? 99 : b) || left.localeCompare(right);
+    })
+    .map((name) => `${manager} run ${name}`);
+}
+
+function parseArgs(argv) {
+  const options = { project: '.', task: null };
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] === '--project') options.project = argv[++index];
+    else if (argv[index] === '--task') options.task = argv[++index];
+    else throw new Error(`Unknown argument: ${argv[index]}`);
+  }
+  return options;
+}
+
+function discover({ project, task }) {
+  const root = resolve(project);
+  const taskPath = task ? resolve(root, task) : null;
+  const groups = [
+    ['task-requirements', taskPath && existsSync(taskPath) ? commands(section(read(taskPath), 'Test Requirements')) : []],
+    ['repository-instructions', ['AGENTS.md', 'CLAUDE.md', '.planr/rules.md'].flatMap((name) => {
+      const path = resolve(root, name);
+      return existsSync(path) ? commands(read(path)) : [];
+    })],
+    ['package-task-runner', packageChecks(root)],
+    ['ci-pre-commit', [
+      ...files(resolve(root, '.github/workflows'), (name) => /\.ya?ml$/u.test(name)),
+      ...files(resolve(root, '.husky'), (name) => !name.startsWith('.')),
+      ...['.gitlab-ci.yml', '.pre-commit-config.yaml', 'Makefile', 'justfile']
+        .map((name) => resolve(root, name))
+        .filter(existsSync),
+    ].flatMap((path) => commands(read(path)))],
+  ];
+  const seen = new Set();
+  const checks = groups.flatMap(([source, values]) => values.flatMap((command) => {
+    if (seen.has(command)) return [];
+    seen.add(command);
+    return [{ command, source }];
+  }));
+  return {
+    kind: 'verification-discovery',
+    schemaVersion: '1.0.0',
+    projectRoot: root,
+    taskPath,
+    checks,
+    diagnostics: [
+      ...(taskPath && !existsSync(taskPath) ? [`Task file not found: ${taskPath}`] : []),
+      ...(checks.length === 0 ? ['No verification commands were discovered; inspect the repository directly.'] : []),
+    ],
+  };
+}
+
+try {
+  process.stdout.write(`${JSON.stringify(discover(parseArgs(process.argv.slice(2))), null, 2)}\n`);
+} catch (error) {
+  process.stderr.write(`E_VERIFICATION_DISCOVERY: ${error.message}\n`);
+  process.exitCode = 1;
+}

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

@@ -0,0 +1,79 @@
+---
+description: "Implement an OpenPlanr plan, specification, task, or clearly stated request end to end in the current repository. Use when the user asks to build, implement, fix, finish, or ship local work."
+alwaysApply: false
+---
+
+# Planr Ship
+
+Produce an implementation-complete local repository in this active coding
+session. Landing and release preparation belong to `planr-land`. Do not
+delegate implementation to a command-line or model subprocess.
+Keep the work local; do not publish or deploy it.
+
+## Resolve the task and context
+
+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.
+
+Only `dependsOn` defines semantic ordering. When a dependency has not produced
+the interface this task consumes, report that concrete gap. Never infer a
+dependency from order or overlapping paths. Isolate independent executions when
+the host supports it; otherwise serialize only overlapping writes.
+
+Create and Modify describe the expected surface, not an artificial file fence.
+Include companion files needed for correctness, leave Preserve entries
+unchanged, and retain unrelated working-tree changes. If a selector resolves to
+zero or multiple tasks, report the searched locations and candidates instead of
+guessing. For a direct implementation request, the request plus repository
+context is sufficient; missing planning files do not create a gate.
+
+## Implement with native roles
+
+Use the host's read, edit, shell, browser, and test capabilities. When native
+agents are available, dispatch only the applicable frontend, backend, database,
+QA, DevOps, and documentation roles inside this session. Give each role its
+owned outcome, relevant context paths, and explicit file coordination boundary.
+Run independent work in parallel. When native agents are unavailable, perform
+the same lenses sequentially in the active agent.
+
+Integrate the complete change, then verify behavior. `reviewRisks` and
+`browserSurfaces` select useful checks; empty arrays are normal and neither field
+is a workflow gate.
+
+## Discover and run verification
+
+Discover checks in this order:
+
+1. task Test Requirements;
+2. repository instructions;
+3. package and task-runner scripts;
+4. applicable CI and pre-commit configuration.
+
+The packaged read-only [verification discovery helper](scripts/discover-verification.mjs)
+may list candidates. Resolve it relative to this `SKILL.md`; pass the repository
+root and task path. It never executes checks or writes files. If it is unavailable,
+inspect those four sources directly. Missing commands are diagnostics, not a
+reason to invent or skip all verification.
+
+Run the strongest applicable focused checks while working, then the relevant
+regression checks. Fix failures caused by the change and rerun affected checks.
+Read [the result contract](references/result-contract.md) before reporting.
+
+## Return
+
+Return the existing five fields:
+
+- **Outcome:** `completed`, `partial`, or `blocked`, followed by what now works.
+- **Task:** task ID and path, or `direct-request`.
+- **Changed:** material paths grouped by purpose.
+- **Checks:** command, `passed`, `failed`, or `not-run`, plus a concise result.
+- **Issues:** problem, impact, and next action, or `none`.
+
+For a completed outcome, append `Next: planr-land` to the human summary. It is
+presentation guidance, not a sixth machine field.
+
+When the OpenPlanr dashboard is running, the shipped work is browsable at
+`#/detail/<T-###>` and the board at `#/board`. This is navigation only.

package/lib/host-packages/cursor/openplanr/rules/planr-spec/references/specification-contract.md

@@ -0,0 +1,32 @@
+# Specification contract
+
+For spec-driven repositories, write
+`.planr/specs/SPEC-NNN-{slug}/SPEC-NNN-{slug}.md` with Protocol `1.7.0`
+frontmatter: `id`, `title`, `slug`, `schemaVersion`, `status`, `priority`,
+`created`, `updated`, `ui_files`, and `tech_dependencies`. Preserve supported
+optional fields used by the repository.
+
+Use these body sections, in this order, when the repository has no stronger
+template:
+
+1. `## Context & Goal`
+2. `## Audience`
+3. `## Outcome & Measurement`
+4. `## Functional Requirements`
+5. `## Business Rules`
+6. `## Constraints`
+7. `## Evidence Expectations`
+8. `## Failure Modes`
+9. `## Rollback`
+10. `## Scope Boundaries`, with `### In Scope` and `### Out of Scope`
+11. `## Acceptance Criteria`, with stable `AC-NNN` identifiers
+12. `## Declared Risk Specialists`
+13. `## Notes for Decomposition`
+
+Keep evidence and rollback as useful planning context, not approval gates or
+receipt requirements. A risk-specialist section may be empty when no specialist
+lens applies.
+
+For a repository intentionally using default mode, write
+`input/specs/spec-{slug}.md` and preserve its active schema. Do not create a
+parallel `.planr` spec solely to normalize the project.

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

@@ -0,0 +1,52 @@
+---
+description: "Shape vague product or engineering intent into a clear, measurable Protocol-compatible specification grounded in the current repository. Use when requirements need clarification before planning or implementation."
+alwaysApply: false
+---
+
+# Planr Spec
+
+Shape vague product or engineering intent into a decision-complete
+specification inside this active coding session. Do not invoke a planning CLI or
+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.
+
+When a missing decision materially changes scope or observable behavior, use
+the host's structured question interface. Ask no more than three short,
+mutually exclusive questions at once and put the recommended option first. If
+the host lacks that interface, ask one concise chat question. Do not present a
+long prose questionnaire.
+
+When native agents are available, use the specification role to consolidate the
+contract and dispatch database or designer roles only when their lens affects
+the decision. Otherwise perform those lenses sequentially in the active agent.
+
+## Author directly
+
+Read [the specification contract](references/specification-contract.md). Write
+the specification to the repository's active planning layout, using a
+project-global monotonic `SPEC-NNN` ID. Inspect the repository's existing
+sequence and planning files before choosing it; never reuse a deleted ID.
+
+Requirements and acceptance criteria must be observable. Put non-goals under
+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.
+
+## Return
+
+- **Outcome:** what the specification now defines.
+- **Artifact:** the saved path, or `not saved` for an explicitly inline result.
+- **Decisions:** locked decisions and grounded defaults.
+- **Open question:** only a decision that still changes the product; omit when
+  none remains.
+- **Next:** a copy-ready host-native `planr-plan` invocation for the saved spec.