openplanr 3.5.0 → 3.6.0

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

@@ -6,9 +6,7 @@ license: MIT
 
 # 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
 
@@ -20,58 +18,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 |
 |---|---|---|
@@ -81,21 +90,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`
 
@@ -144,47 +149,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](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](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](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/openai/openplanr/skills/operate/openplanr.skill.json

@@ -3,7 +3,7 @@
   "schemaVersion": "1.0.0",
   "protocolVersion": "1.8.0",
   "skillId": "planr-operate",
-  "skillVersion": "2.1.1",
+  "skillVersion": "2.4.0",
   "entrypoint": "SKILL.md",
   "hosts": [
     "claude-code",
@@ -14,15 +14,15 @@
   "execution": "host-agent",
   "resources": [
     {
-      "path": "scripts/validate-note.mjs",
-      "kind": "script",
+      "path": "references/note-checklist.md",
+      "kind": "reference",
       "hosts": [
         "claude-code",
         "codex",
         "chatgpt",
         "cursor"
       ],
-      "executable": true
+      "executable": false
     },
     {
       "path": "agents/openai.yaml",
@@ -32,6 +32,17 @@
         "chatgpt"
       ],
       "executable": false
+    },
+    {
+      "path": "references/return-contract.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
     }
   ]
 }

package/lib/host-packages/openai/openplanr/skills/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/openai/openplanr/skills/operate/references/return-contract.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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