openplanr 3.5.0 → 3.6.0

package/lib/host-packages/cursor/openplanr/rules/planr-operate/references/note-checklist.md

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

package/lib/host-packages/cursor/openplanr/rules/planr-operate/references/return-contract.md

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

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

@@ -5,9 +5,7 @@ alwaysApply: false
 
 # OpenPlanr Operate
 
-Run one useful operating review, not a ceremony. Build shared context once, fan out the five
-executive advisors, use the Challenger to test material claims, and let the Chair synthesize the
-result. Return a clean board report with decisions, actions, risks, gaps, and any real issues.
+Run one useful operating review, not a ceremony. By default one agent applies all seven lenses in one pass and writes one report with decisions, actions, risks, gaps, and any real issues.
 
 ## Scope the review
 
@@ -19,58 +17,69 @@ Infer these values from the request and repository when they are clear:
 - **Roster** — all seven lenses unless the user selects fewer.
 
 Use the current repository, current snapshot, periodic review, and all seven lenses as sensible
-defaults. When ownership is useful, a recommendation may suggest a person, a role, or
-`unassigned`.
+defaults. A recommendation may suggest a person, a role, or `unassigned`.
 
 Ask only when an unresolved choice would materially change the sources inspected or the decision
 being answered. Use the host's native structured-question UI when available, offering a
 recommended choice and short alternatives. Otherwise ask one concise chat question at a time.
 Never present the scope fields as a prose questionnaire.
 
-Preserve the user's wording in `cycle.md`, followed by the effective scope used by the lenses.
-Do not claim a trend from a current snapshot; describe current state and name any missing baseline.
+Record the user's wording and the effective scope in the report's Scope section. Do not claim a
+trend from a current snapshot; describe current state and name any missing baseline.
 
-## Create the cycle workspace
+## Choose the mode
 
-Use a short subject slug and today's ISO date. Choose the first unused path;
-when the base path exists, append `-02`, `-03`, and so on. Reuse an existing
-cycle only when the user explicitly asks to resume it and its recorded scope
-matches. Never overwrite a prior cycle implicitly.
+Default: this agent applies the lenses itself. Use subagents only when the user names a roster or
+asks for independent reviewers; then follow Fan out.
 
-```text
-.planr/operate/<date>-<slug>/
-  cycle.md
-  brief.md
-  <selected-lens-notes>.md
-  board-report.md
-```
+Where the report goes: with no `.planr/` in the repository, answer in chat, or write one file where
+the repository already keeps such documents. With `.planr/`, write `board-report.md` in a cycle
+directory (below). `cycle.md`, `brief.md` and per-lens notes only when subagents run or the user asks to persist the cycle; a persisted cycle without fan-out writes `cycle.md` and `brief.md` with the contents defined under Fan out.
+
+## Read the sources
+
+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. Keep observations separate from interpretation.
+
+## Apply the lenses
+
+Work through each selected lens in one pass:
 
-`cycle.md` records the effective scope, roster, repository revision when relevant, and the outcome
-of each lens. An advisor lens run on its own creates the same layout with a one-lens roster and an
-unsynthesized `board-report.md`, so every review the dashboard lists has one shape.
-If the directory is ignored by Git, continue locally and mention that in the report; do not ask the
-user to change ignore rules. Report an exact filesystem error only when the cycle workspace cannot be
-created or written.
+| Lens | Focus |
+|---|---|
+| CEO | strategy and finance: direction, runway, margin, cost of delay |
+| CTO | technology and delivery risk: architecture, reliability, security, execution risk |
+| CPO | product and activation: customer value, activation, prioritization, adoption |
+| CMO | growth and market: acquisition, positioning, demand, retention, measurement |
+| COO | operations and customer health: process, support, incidents, capacity |
+| Challenger | for each material claim: the strongest alternative, the downside, and the confidence |
+| Chair | the decision queue and action plan, from the findings above |
 
-## Build shared context once
+Name each Review coverage row `CEO`, `CTO`, `CPO`, `CMO`, `COO`, `Challenger` or `Chair`; the dashboard matches on those names.
 
-Write `brief.md` as a compact orientation aid, not a conclusion. Include:
+Every recommendation cites a source: a project path, command output, or a named gap. Do not
+fabricate a lens with no evidence; record it as `no material finding` or `unavailable` in review
+coverage with the smallest next action. Then assemble the report below.
 
-- effective subject, window, requested decision, and roster;
-- current revision and working-tree state when relevant;
-- the requested range and a short change summary when the review is historical;
-- paths to relevant planning, product, customer, financial, operational, delivery, architecture,
-  incident, and metric sources;
-- important context that was searched for but not found.
+## Cycle directory
 
-Open enough of the repository to make these pointers useful. Keep observations separate from
-interpretation so every lens can reach its own conclusion. The brief is a starting point; lenses
-may inspect other relevant project sources.
+Use a short subject slug and today's ISO date: `.planr/operate/<date>-<slug>/`. Choose the first
+unused path; when the base path exists, append `-02`, `-03`, and so on. Reuse an existing cycle
+only when the user explicitly asks to resume it and its recorded scope matches. Never overwrite a
+prior cycle implicitly. If the directory is ignored by Git, continue locally and mention that in the
+report; do not ask the user to change ignore rules. Report an exact filesystem error only when the
+directory cannot be created or written.
 
-## Run the selected lenses (seven by default)
+## Fan out
+
+When the user names a roster or asks for independent reviewers, create the cycle directory with
+`cycle.md` (effective scope, roster, revision when relevant, outcome of each lens) and `brief.md`
+(scope, revision, source paths, context searched for but not found), then one note per selected lens. An advisor lens run on its own creates the same layout with a one-lens
+roster and an unsynthesized `board-report.md`.
 
 Dispatch only the selected independent advisors, in parallel when subagents are
-available:
+available, giving each the brief path, its output path and the effective scope:
 
 | Lens | Skill | Output |
 |---|---|---|
@@ -80,21 +89,17 @@ available:
 | Growth and market | `planr-cmo-review` | `cmo.md` |
 | Operations and customer health | `planr-coo-review` | `coo.md` |
 
-Give each selected advisor the brief path, its output path, and the effective
-scope. Do not invoke or create note files for advisor lenses omitted by the
-roster. After the selected advisor work finishes:
+Do not create note files for omitted lenses. After the advisor work finishes:
 
-1. If Challenger is selected, run `planr-challenger-review` over the available
-   advisor notes to surface only material exceptions, alternatives, and downside.
-2. If Chair is selected, run `planr-chair-review` over the available selected
-   notes to produce the decision queue and action plan.
-3. If Challenger or Chair is omitted, record `omitted by scope` in review
-   coverage. Assemble the board report from the available selected notes without
-   inventing the omitted lens; when Chair is absent, clearly label the result as
-   an unsynthesized lens summary rather than a Chair recommendation.
+1. If Challenger is selected, run `planr-challenger-review` over the available advisor notes to
+   surface only material exceptions, alternatives, and downside.
+2. If Chair is selected, run `planr-chair-review` over the available notes to produce the decision
+   queue and action plan.
+3. If Challenger or Chair is omitted, record `omitted by scope` in review coverage and label the
+   result an unsynthesized lens summary, not a Chair recommendation.
 
-Missing or malformed lens output is an issue, not a reason to fabricate that lens or discard all
-other useful work. Record the problem, its effect on confidence, and the smallest next action.
+Missing or malformed lens output is an issue, not a reason to fabricate that lens or discard the
+other work. Record the problem, its effect on confidence, and the smallest next action.
 
 ## Assemble `board-report.md`
 
@@ -143,47 +148,31 @@ Use these sections in this order:
 ## Review coverage
 | Lens | Outcome | Note | Informed |
 |---|---|---|---|
-| ... | reported / no material finding / unavailable / omitted by scope | `file.md` or `—` | D1 / watch / none |
+| CEO | reported / no material finding / unavailable / omitted by scope | `file.md` or `—` | D1 / watch / none |
 
 ## Issues
 - **I1 — <problem>:** <impact and practical next action>
 <or `None.`>
 ```
 
-When Chair is selected, copy decisions and actions from `chair.md`; do not create a new executive
-opinion during assembly. When Chair is omitted, summarize only the available selected notes,
-label the report as an unsynthesized lens summary, and use `No decision-ready proposal was
-established.` plus `No proposed actions.` unless those notes already state a directly supported
-proposal. Never present that result as Chair synthesis. Keep at most five decisions, seven actions,
-and five decision-changing gaps. When no decision is ready, say so plainly and retain the strongest
-watch items and the context needed to improve the next review.
-
-## Optional quality check
+In fan out with Chair, copy decisions and actions from `chair.md` without adding a new executive
+opinion. Without Chair, summarize only the available notes, label the report an unsynthesized lens
+summary, and use `No decision-ready proposal was established.` plus `No proposed actions.` unless
+those notes already state a supported proposal. Keep at most five decisions, seven actions, and five
+decision-changing gaps. When no decision is ready, say so and keep the strongest watch items.
 
-The packaged [note validator](planr-operate/scripts/validate-note.mjs) can identify missing sections, fields, or limits:
+## Quality check
 
-```sh
-node "<skill-root>/scripts/validate-note.mjs" "<absolute-advisor-output>" --profile advisor --contract-version 2.0.0
-node "<skill-root>/scripts/validate-note.mjs" "<absolute-challenger-output>" --profile challenger --contract-version 2.0.0
-node "<skill-root>/scripts/validate-note.mjs" "<absolute-chair-output>" --profile chair --contract-version 2.0.0
-node "<skill-root>/scripts/validate-note.mjs" "<absolute-board-report-path>" --profile board-report --contract-version 2.0.0
-```
-
-Use their diagnostics as editing help. Include unresolved structural problems under `Issues` with
-their impact and next action while preserving the useful parts of the report.
+Before returning, check the report (and any lens note) against [the note checklist](planr-operate/references/note-checklist.md), which runs the CLI's `validate-note` when `command -v openplanr` succeeds and is the check otherwise. Put unresolved structural problems under `Issues` with their impact and next action.
 
 ## Return
 
-Lead with the grounded overall signal and most consequential decision or missing
-evidence. Link `board-report.md`, summarize decision/action counts and the review
-coverage actually completed, and name any unavailable or unsynthesized lens.
-Keep the full decision queue, source inventories and diagnostic output in their
-existing artifacts. Include unresolved issues with their impact and next action,
-omitting empty chat sections. Preserve the durable report contract; different
-summary wording never requires another review or corrective run.
-
-When the OpenPlanr dashboard is running, the operating cycle is browsable at
-`#/operate/cycles/<id>`, the completed review index at `#/operate/cycles`, and the latest
-completed review at `#/operate/today`. The standalone dashboard presents these local reports
-read-only and refreshes them automatically. Inbox, actions, evidence, outcomes, recovery, and
-all mutations require an actor-bound governed Operate session.
+Lead with the grounded overall signal and most consequential decision or missing evidence.
+Link `board-report.md` when one was written, summarize decision and action counts and the review
+coverage completed, and name any unavailable or unsynthesized lens. Follow
+[the shared return rules](planr-operate/references/return-contract.md).
+
+When the OpenPlanr dashboard is running, the cycle is browsable at `#/operate/cycles/<id>`, the
+review index at `#/operate/cycles`, and the latest review at `#/operate/today`, read-only.
+Inbox, actions, evidence, outcomes, recovery, and all mutations require an actor-bound governed
+Operate session.

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

@@ -5,9 +5,11 @@ alwaysApply: false
 
 # 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
 
@@ -41,6 +43,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](planr-plan-review/references/return-contract.md).

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

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

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