openplanr 3.4.0 → 3.6.0

package/lib/host-packages/openai/openplanr/skills/investigate/references/backlog-filing.md

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

package/lib/host-packages/openai/openplanr/skills/investigate/references/findings.md

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

package/lib/host-packages/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
@@ -45,10 +42,14 @@ unresolved feedback; carry relevant gaps into explicit task checks. Preserve
 existing design or re-extract an authored specification from preview images.
 
 When `review-handoff.json` is present beside `design-spec.md`, read its current
-approval and freshness with the bundled
-`node scripts/design.mjs handoff <design-document.json> --action inspect --json`. Use approved, current
+approval and freshness with
+`openplanr design handoff <design-document.json> --action inspect --json`. Use approved, current
 handoff items as additional planning context, retaining revision/comment links and
-unresolved questions. An outdated or unapproved draft is evidence, not agreed scope;
+unresolved questions. When `openplanr` is not found, does not know `design`, or
+reports `E_DESIGN_RUNTIME_MISSING`, treat the handoff as unverified evidence rather
+than agreed scope, continue when the specification is decision-complete, and name
+the fix: `npm install -g openplanr`, `npm install -g openplanr@latest`, or
+`npm install -g openplanr` without `--omit=optional`, respectively. An outdated or unapproved draft is evidence, not agreed scope;
 report the changed inputs and obtain the missing decision only when it affects the
 requested plan. Never silently substitute a newer draft for an approved snapshot.
 A missing review handoff does not block ordinary planning from a clear specification.
@@ -89,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
@@ -112,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
@@ -138,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-###>`.