openplanr 3.4.0 → 3.6.0

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

@@ -17,10 +17,11 @@ plain Ship never launches its helper. Keep the work local; do not publish or dep
 
 For a selector, locate exactly one task and read it completely. Then follow its
 `storyId` and `specId` to the parent story, acceptance criteria, Gherkin file
-when present, and specification. Also read repository instructions, ADRs,
-planning rules, applicable stack guidance, relevant design/database context,
-implementation code, tests, and interfaces produced by declared dependencies. Read any
-`.planr/conventions/<area>.md`, indexed from AGENTS.md, for the areas this task touches.
+when present, and specification. Read the files the task names, plus `AGENTS.md` and
+`CLAUDE.md` when tracked, in one batch, and any `.planr/conventions/<area>.md` indexed
+from AGENTS.md for the areas this task touches. Expand only for a missing contract, a
+dependency's interface or a contradiction, and stop when each claim has evidence or a
+named gap.
 
 Read [the design lineage contract](references/design-lineage.md). If the selected
 planning root contains `design-lineage.json`, load only the selected task's mapped
@@ -78,29 +79,43 @@ its `changed` list with `git diff --name-only` plus untracked files; report any
 
 ## Discover and run verification
 
-Discover checks in this order:
+Inspect these sources directly, in this order:
 
 1. task Test Requirements;
 2. repository instructions;
 3. package and task-runner scripts;
-4. applicable CI and pre-commit configuration.
-
-Run `openplanr ship checks --json --task <task-path>` (omit `--task` for a direct
-request; add `--tier story` or `--tier push` before pushing) and run its `checks`
-from each `cwd`. The command never executes checks or writes files. When
+4. applicable CI configuration, the pre-commit hook (for example lint-staged) and the
+   pre-push hook, when present, whatever the change touches.
+
+List each candidate check with its `cwd` and the source that named it. Discovery
+only reads sources: never build, install or execute a check while discovering;
+running checks is a later step. Then run the candidates from each `cwd`. Let the change pick checks: when it touches a build input (a
+`tsconfig*.json`, a bundler config, or a package's `main`, `exports`, `bin` or
+`build` scripts), include the build CI runs; prefer tests related to the changed
+files. Before pushing, include every CI job whose triggers and path filters fire
+for the changed paths, and for a published package that gains non-code files, a
+dry-run pack that confirms they are packed. When a workflow selects jobs at
+runtime (a `changes` or paths-filter job whose outputs gate other jobs), list every job it
+gates and mark each conditional. Run a conditional job when a local equivalent command
+exists; otherwise report it as "conditional, not run". Never drop one silently or by
+reading the paths yourself. Read every workflow file whose triggers fire for the
+change, not only the main one: dedicated browser, end-to-end and sandbox workflows are sources too. List a git hook as
+its own command and, when it delegates to a script, also each check that script runs.
+Discovery lists what the sources define whatever the size or kind of the change, a
+documentation-only change included; the change picks only which listed checks you run.
+Missing commands are diagnostics, not a reason to invent or
+skip all verification.
+
+If `openplanr` is already on `PATH`, `openplanr ship checks --json --task <task-path>`
+(omit `--task` for a direct request; add `--tier story` or `--tier push` before
+pushing) adds `complete` and diagnostics. The command never executes checks or writes files. When
 `complete` is `false`, report its error diagnostics and treat the check set as
 incomplete: a pass is not CI-equivalent. Act on warning diagnostics too; each names
 the files or checks it affects. A diagnostic that a check could not run, such as
 `TYPESCRIPT_UNAVAILABLE`, is not a pass: name that check in `checks` and verify its
 concern yourself where you can (for a new test file, confirm some tsconfig includes
 it). For a `package-contents` check, account for every `expectFiles` entry in the
-tarball's `files`: packed or deliberately left out. Without
-the CLI, the packaged read-only [verification discovery helper](scripts/discover-verification.mjs)
-may list candidates. Resolve it relative to this `SKILL.md` and run
-`node <helper> --project <repository-root> --task <task-path>`; omit `--task` for a
-direct request. It never executes checks or writes files. If both are unavailable,
-inspect those four sources directly. Missing commands are diagnostics, not a
-reason to invent or skip all verification.
+tarball's `files`: packed or deliberately left out.
 
 Run the strongest applicable focused checks while working, then the relevant
 regression checks. Run each check on its own or under `set -o pipefail`, and judge
@@ -111,9 +126,9 @@ For an acceptance check written or changed for this task, follow
 Read [the result contract](references/result-contract.md) before reporting.
 
 Report defects you notice outside the task as [findings](references/findings.md),
-and never fix them in this change unless they block it. 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`.
+and never fix them in this change unless they block it.
+[Backlog filing](references/backlog-filing.md) lists and files backlog items with
+your own file tools.
 
 Do not write progress into an approved design package. The studio derives
 approved, planned, implementing, and verified state from canonical planning and
@@ -135,10 +150,8 @@ results instead of reproducing them in chat.
 - **Issues:** blockers with problem, impact, and next action, or `none`; then
   findings outside the task, each with its disposition.
 
-Keep the five machine fields unchanged. A human summary may omit empty or unavailable fields,
-but must make partial, blocked or unverified work clear and give the smallest
-recovery action. Preserve native transcripts; never require another execution
-or correction just to change summary wording.
+Keep the five machine fields unchanged. Follow [the shared return rules](references/return-contract.md);
+the summary must make partial, blocked or unverified work clear.
 
 Suggest `planr-land` only when a landing step remains in the requested workflow.
 Do not add a next action when the requested scope is fulfilled. This guidance

package/lib/host-packages/claude/openplanr/skills/ship/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/ship/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/ship/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/claude/openplanr/skills/spec/SKILL.md

@@ -12,10 +12,10 @@ another model process.
 
 ## Ground the specification
 
-Read the request, repository instructions, ADRs, product documentation,
-existing planning artifacts, relevant implementation code and tests, stack
-configuration, design inputs, database context, and current behavior. Infer
-facts the repository already answers.
+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. Infer facts the repository
+already answers.
 
 When a missing decision materially changes scope or observable behavior, use
 the host's structured question interface. Ask no more than three short,
@@ -45,9 +45,10 @@ out-of-scope boundaries. Record concrete repository paths and verification
 signals when they are known. Keep unresolved questions out of the saved
 contract when a repository-backed default exists.
 
-Validate the completed artifact before returning. If a helper is unavailable,
-perform the same deterministic checks directly; never fall back to a
-model-backed CLI.
+Validate the completed artifact before returning: run `openplanr spec validate <SPEC-ID>`
+when `command -v openplanr` succeeds, otherwise check the path, frontmatter,
+headings and acceptance IDs against the specification contract directly. Never
+fall back to a model-backed CLI.
 
 ## Return
 
@@ -62,5 +63,4 @@ If the specification is partial or blocked, name the missing decision and its im
   none remains.
 - **Next:** a copy-ready host-native `planr-plan` invocation for the saved spec.
 
-The summary is a human view of the specification, not another schema or a reason
-to rerun a completed operation for different wording.
+Follow [the shared return rules](references/return-contract.md).

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