openplanr 3.5.0 → 3.6.0

package/lib/host-packages/openai/openplanr/skills/coo-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/openai/openplanr/skills/cpo-review/openplanr.skill.json

@@ -3,7 +3,7 @@
   "schemaVersion": "1.0.0",
   "protocolVersion": "1.8.0",
   "skillId": "planr-cpo-review",
-  "skillVersion": "2.0.1",
+  "skillVersion": "2.1.0",
   "entrypoint": "SKILL.md",
   "hosts": [
     "claude-code",
@@ -25,15 +25,15 @@
       "executable": false
     },
     {
-      "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",

package/lib/host-packages/openai/openplanr/skills/cpo-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/openai/openplanr/skills/cpo-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/openai/openplanr/skills/cto-review/openplanr.skill.json

@@ -3,7 +3,7 @@
   "schemaVersion": "1.0.0",
   "protocolVersion": "1.8.0",
   "skillId": "planr-cto-review",
-  "skillVersion": "2.0.1",
+  "skillVersion": "2.1.0",
   "entrypoint": "SKILL.md",
   "hosts": [
     "claude-code",
@@ -25,15 +25,15 @@
       "executable": false
     },
     {
-      "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",

package/lib/host-packages/openai/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/openai/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/openai/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/openai/openplanr/skills/investigate/openplanr.skill.json

@@ -3,7 +3,7 @@
   "schemaVersion": "1.0.0",
   "protocolVersion": "1.8.0",
   "skillId": "planr-investigate",
-  "skillVersion": "2.3.0",
+  "skillVersion": "2.4.0",
   "entrypoint": "SKILL.md",
   "hosts": [
     "claude-code",
@@ -45,15 +45,15 @@
       "executable": false
     },
     {
-      "path": "scripts/backlog-item.mjs",
-      "kind": "script",
+      "path": "references/backlog-filing.md",
+      "kind": "reference",
       "hosts": [
         "claude-code",
         "codex",
         "chatgpt",
         "cursor"
       ],
-      "executable": true
+      "executable": false
     }
   ]
 }

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