openplanr 3.2.0 → 3.4.0

package/docs/CLI.md

@@ -243,6 +243,30 @@ openplanr spec shape SPEC-001
 
 ---
 
+#### `openplanr spec validate`
+
+Check one spec file against the specification contract. It reads the file and writes nothing.
+
+```bash
+openplanr spec validate SPEC-001
+openplanr spec validate SPEC-001 --json
+```
+
+| Option     | Description                                                     | Required |
+| ---------- | --------------------------------------------------------------- | -------- |
+| `<specId>` | Spec ID to check                                                | Yes      |
+| `--json`   | Print `{ ok, specId, file, violations[] }` instead of text      | No       |
+
+**Rules:**
+1. **`path`** — the file is `SPEC-NNN-{slug}/SPEC-NNN-{slug}.md`, and its frontmatter `id` and `slug` match that path.
+2. **`frontmatter`** — the frontmatter is valid against the Protocol spec schema for the `schemaVersion` it declares (`1.0.0` or `1.7.0`): every required key (including `id`), allowed values, no unknown keys. A missing or unsupported `schemaVersion` is an error that lists the supported versions.
+3. **`headings`** — the 13 contract headings, from `## Context & Goal` to `## Notes for Decomposition`, appear in order, and `## Scope Boundaries` has `### In Scope` and `### Out of Scope`. Other headings may sit between them.
+4. **`acceptance-ids`** — every top-level item under `## Acceptance Criteria` starts with a unique `AC-NNN` id (a checkbox and bold markers before it are fine).
+
+Each violation is printed with the file, the rule, and what was found. The command exits 1 when there is any violation or the spec is not found, and 0 otherwise.
+
+---
+
 #### `openplanr spec sync`
 
 Validate spec integrity and auto-fix safe inconsistencies. Use after manual edits, interrupted work, or when in doubt.
@@ -322,12 +346,20 @@ openplanr spec attach-design SPEC-001 --files login.png signup.png
 
 #### `openplanr spec promote`
 
-Validate that a spec is ready for handoff to `planr-pipeline` (has stories, tasks, non-trivial body) and print the next-step pipeline command. Updates SPEC frontmatter `status: ready-for-pipeline`.
+Validate that a spec is ready for handoff (has stories, tasks, and a non-trivial body), mark the spec ready-for-pipeline by writing `status: "ready-for-pipeline"` into its frontmatter, and print the next-step pipeline command.
 
 ```bash
 openplanr spec promote SPEC-001
+openplanr spec promote SPEC-001 --dry-run   # validate and print the handoff; write nothing
 ```
 
+| Option      | Description                                                                     | Required |
+| ----------- | ------------------------------------------------------------------------------- | -------- |
+| `<specId>`  | Spec ID to promote                                                              | Yes      |
+| `--dry-run` | Validate and print the handoff command without marking the spec ready-for-pipeline | No    |
+
+To check a spec's structure without changing its status, use `openplanr spec validate`.
+
 After promotion, run from any configured runtime:
 
 ```text
@@ -612,6 +644,12 @@ openplanr artifact open <file> [--title <title>] [--root <asset-root>] [--theme
 openplanr artifact share <file> [--title <title>] [--root <asset-root>] [--presentation auto|document|canvas] [--snapshot] [--short] [--ttl 1d|7d|30d] [--secret-output <private-file>] [--no-open] [--json] [--yes]
 openplanr artifact publish <diagram-manifest|diagram-bundle|design-document> [--yes] [--json]
 openplanr artifact sync <diagram-manifest|diagram-bundle|design-document> [--json]
+openplanr artifact status <design-document> [--json]
+openplanr artifact manage <design-document> --action rotate|pause|resume|revoke|delete|access|recovery|restore [--output <new-path>] [--input <recovery-file>] [--yes] [--json]
+openplanr artifact feedback <design-document> [--action inspect|export|import|select|resolve] [--format json|markdown] [--scope current|all] [--output <new-path>] [--input <file>] [--json]
+openplanr artifact handoff <design-document> [--action draft|inspect|update|approve|category|disposition] [--input <file|->] [--json]
+openplanr artifact share-runtime [--json]
+openplanr artifact review-metadata <design-document> --revision <hosted-revision> --input <file|-> [--json]
 openplanr artifact import --secret-input <private-file|-> [--output <path>] [--allow-stale] [--json] [--yes]
 openplanr artifact export <session-id> [--format json|markdown] [--output <path>]
 ```
@@ -624,6 +662,22 @@ explicitly; `sync` imports revision-bound feedback without changing the diagram.
 Native diagram sharing does not accept `--snapshot`, `--short`, or `--ttl`;
 export HTML first to choose the generic snapshot transport.
 
+A shared design is managed from the same command. `status` shows the review link
+and whether the current revision is published, without printing secrets. `manage`
+rotates the reviewer access token, pauses or resumes comments, revokes or deletes
+the review, prints the reviewer token with `--action access --json`, and writes or
+restores a private recovery file. Without `--output`, the recovery file is a new
+file in `PLANR_HOME/design-recovery` (folder 0700, file 0600). Rotate, revoke, delete and restore ask first;
+`--yes` confirms them non-interactively. `feedback` syncs a shared design before it
+inspects or exports feedback. `handoff` drafts the review handoff by default, and
+its other actions update it from a JSON object; on a shared design, category and
+disposition changes also publish to the review. `share-runtime` reports the CLI,
+workflow package and design sharing format versions, and `review-metadata` publishes
+one owner category or disposition; the bundled design helpers use both to hand sharing
+to the CLI. Design sharing needs the
+optional `planr-pipeline` package; without it these commands fail with
+`E_DESIGN_SHARE_PIPELINE_MISSING`.
+
 When `--root` is omitted, the artifact file's directory is the asset root. This
 makes `openplanr artifact share /absolute/path/to/artifact.html` work without
 changing directories or supplying a redundant root. Supported public HTTPS
@@ -710,7 +764,7 @@ openplanr ship checks --tier push --json
 | `--task <path>` | Task file whose Test Requirements to include                   | none                                      |
 | `--tier <tier>` | `task`, `story`, `push` or `planning`                          | `planning` for a `.planr`-only change, else `task` |
 | `--base <ref>`  | Compare against the merge base with this ref                   | `origin/HEAD`, then `main`                |
-| `--json`        | Print the `openplanr-ship-checks` result (schema `1.0.0`)      | `false`                                   |
+| `--json`        | Print the `openplanr-ship-checks` result (schema `1.2.0`)      | `false`                                   |
 
 **Tiers:**
 
@@ -723,6 +777,21 @@ openplanr ship checks --tier push --json
 - `story`: `task` plus every `run` step of the pull-request and merge-queue
   workflows whose path filters match the change.
 - `push`: `story` without path filters, plus push workflows and pre-push hooks.
+  When the change adds non-code files (for example JSON data or templates) to a
+  package that is not `private`, it also lists
+  `npm pack --dry-run --json --ignore-scripts` from that package's directory,
+  tagged `package-contents`. Its `expectFiles` names the new files relative to
+  the package. Run it after the build and account for each one: it, or the copy
+  the build writes for it, appears in the tarball's `files`, or the package
+  deliberately leaves it out. The command lists what npm would pack; it exits 0
+  either way, and a package that publishes another directory (for example with
+  pnpm `publishConfig.directory`) needs its own check. Files in any
+  dot-directory, dotfiles and files under `test`, `tests`, `__tests__`,
+  `fixture`, `fixtures` or `node_modules` folders are not listed, unless the
+  package's `files` names that folder. New code files are out of scope: a
+  package that ships unbuilt `.js` or `.mjs` scripts needs another check that
+  they are packed.
+  `--ignore-scripts` keeps `prepack`, `prepare` and `postpack` from running.
 
 Each CI step is kept verbatim with its `cwd` (step, then job, then workflow
 `working-directory`). Install steps and `uses` steps are skipped. A static matrix
@@ -732,6 +801,21 @@ runs directly mentions `lint-staged`, `ls-files`, `--cached` or `--staged`;
 deeper calls are not followed. `relatedTests` lists test files that mention a
 name the change exports, a `.command()` name, or a route path.
 
+`coverage` names changed files that a passing run may not have checked.
+`trackedOnly.unseen` lists untracked files when any check is `tracked-only`
+(warning `UNTRACKED_NOT_SEEN`); `git add -N` makes them visible.
+`typescript.uncovered` lists new `.ts`, `.tsx`, `.mts` and `.cts` files outside
+`.planr/` that no `tsconfig*.json` root file set includes (`files`, `include`,
+`exclude`, `extends`, and `references` one level deep; warning `TS_NOT_COVERED`).
+A file reached only through an import is still reported, and the command does
+not check which tsconfig CI runs. A tsconfig that TypeScript reports errors for
+raises `TSCONFIG_ERROR` with its first message, and a config whose `extends`
+cannot be read adds no coverage. To read tsconfigs, the command loads the
+`typescript` package that Node resolves from the project root, which can be a
+copy in a parent directory, and that runs the package's code; it never executes
+checks. When Node cannot resolve `typescript` there, `typescript` is `null` with
+the info diagnostic `TYPESCRIPT_UNAVAILABLE`.
+
 `complete` is `false` when any diagnostic is an `error`, for example a workflow
 that fails to parse: the listed checks are then not the full CI set. The command
 exits 1 for an unknown tier, a missing `--task` file or a directory outside git.

package/lib/host-packages/adapter-registry.json

@@ -2,12 +2,12 @@
   "kind": "host-native-adapter-registry",
   "schemaVersion": "1.0.0",
   "protocolVersion": "1.8.0",
-  "pipelineVersion": "0.60.0",
-  "pluginVersion": "3.2.0",
+  "pipelineVersion": "0.62.0",
+  "pluginVersion": "3.4.0",
   "adapters": [
     {
       "id": "claude-code",
-      "version": "3.2.0",
+      "version": "3.4.0",
       "capabilityLevel": "product",
       "installScopes": [
         "user",
@@ -19,7 +19,7 @@
     },
     {
       "id": "codex",
-      "version": "3.2.0",
+      "version": "3.4.0",
       "capabilityLevel": "product",
       "installScopes": [
         "user",
@@ -31,7 +31,7 @@
     },
     {
       "id": "cursor",
-      "version": "3.2.0",
+      "version": "3.4.0",
       "capabilityLevel": "workflow",
       "installScopes": [
         "project"

package/lib/host-packages/capability-map.json

@@ -1,7 +1,7 @@
 {
   "kind": "openplanr-capability-map",
   "schemaVersion": "1.0.0",
-  "pluginVersion": "3.2.0",
+  "pluginVersion": "3.4.0",
   "families": [
     {
       "id": "planning",
@@ -339,7 +339,7 @@
       "id": "planr-investigate",
       "name": "investigate",
       "family": "diagnostics",
-      "description": "Diagnose a bug, regression, error, or unexplained behavior and optionally implement a bounded fix. Use for root-cause investigation, not planned feature delivery.",
+      "description": "Diagnose a bug, regression, error, or unexplained behavior and optionally implement a bounded fix. Use for root-cause investigation, including before any fix, not planned feature delivery.",
       "useWhen": [
         "Investigate a bug, regression, error, or unexplained behavior",
         "Reproduce a defect, establish its root cause, or apply a bounded fix",
@@ -471,7 +471,7 @@
       "id": "planr-ship",
       "name": "ship",
       "family": "implementation",
-      "description": "Implement an OpenPlanr plan, specification, task, or clearly stated request end to end in the current repository. Use when the user asks to build, implement, fix, finish, or ship local work.",
+      "description": "Implement an OpenPlanr plan, specification, task, or clearly stated request end to end in the current repository. Use when the user asks to build, implement, fix, finish, or ship local work, or to plan and implement an accepted change. Invoke before editing files for the requested change. Not for planning only, landing, release, or work handed to another coding agent.",
       "useWhen": [
         "Implement a plan, specification, task, fix, or clearly stated local request",
         "Build and verify the requested repository change",

package/lib/host-packages/claude/.claude-plugin/marketplace.json

@@ -5,15 +5,15 @@
     "name": "OpenPlanr"
   },
   "metadata": {
-    "version": "3.2.0",
+    "version": "3.4.0",
     "description": "Generated local OpenPlanr package."
   },
   "plugins": [
     {
       "name": "planr",
       "source": "./openplanr",
-      "version": "3.2.0",
-      "description": "Close the loop from intent to delivery. Plan, design, build, review, and operate from durable context in your repository.",
+      "version": "3.4.0",
+      "description": "Close the loop from intent to delivery. Plans as files in your repo, checks before you merge, and a record of what shipped, in Claude Code, Codex and Cursor.",
       "strict": true
     }
   ]

package/lib/host-packages/claude/openplanr/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "planr",
   "displayName": "OpenPlanr",
-  "version": "3.2.0",
-  "description": "Close the loop from intent to delivery. Plan, design, build, review, and operate from durable context in your repository.",
+  "version": "3.4.0",
+  "description": "Close the loop from intent to delivery. Plans as files in your repo, checks before you merge, and a record of what shipped, in Claude Code, Codex and Cursor.",
   "author": {
     "name": "OpenPlanr",
     "url": "https://openplanr.dev"
@@ -11,11 +11,11 @@
   "repository": "https://github.com/openplanr/OpenPlanr",
   "license": "MIT",
   "keywords": [
-    "planning",
-    "specification",
-    "delivery",
+    "coding-agents",
+    "agent-harness",
     "code-review",
-    "design"
+    "planning",
+    "verification"
   ],
   "privacyPolicyUrl": "https://openplanr.dev/privacy",
   "termsOfServiceUrl": "https://openplanr.dev/terms",