openplanr 3.5.0 → 3.6.0

package/lib/host-packages/claude/openplanr/skills/cto-review/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/claude/openplanr/skills/cto-review/references/operate-advisor-contract.md

@@ -122,13 +122,8 @@ findings, use `No recommendation from current context.`, and list only decision-
 
 ## Optional quality check and return
 
-When available, the following command can report structural issues:
-
-```sh
-node "<skill-root>/scripts/validate-note.mjs" "<absolute-output-path>" --profile advisor --contract-version 2.0.0
-```
-
-Treat its diagnostics as editing guidance and report any unresolved structural issue.
+Check the note against the advisor profile in [the note checklist](note-checklist.md). Treat
+unchecked items as editing guidance and report any unresolved structural issue.
 
 Lead the chat return with the grounded signal and principal recommendation. Link
 the output note, summarize the finding count, and state the evidence reviewed and

package/lib/host-packages/claude/openplanr/skills/investigate/SKILL.md

@@ -28,9 +28,8 @@ Prove the regression test with [fail-first](references/fail-first.md).
 
 Report other defects you notice as [findings](references/findings.md), and never
 fix them in this change unless they block the requested fix. The established cause
-is never a finding. The packaged [backlog helper](scripts/backlog-item.mjs) lists
-and files backlog items when no CLI is installed; resolve it relative to this
-`SKILL.md`.
+is never a finding. [Backlog filing](references/backlog-filing.md) lists and files
+backlog items with your own file tools.
 
 ## Return
 

package/lib/host-packages/claude/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/claude/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/claude/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.