@unbrained/pm-cli 2026.3.9 → 2026.3.12

package/AGENTS.md

@@ -19,6 +19,11 @@ This document defines how coding agents must use `pm` for planning, execution, a
 - Refresh the global CLI from this repository for maintainer runs:
   - Run `npm install -g .` from repository root.
   - Verify availability with `pm --version` before mutation commands.
+- Run baseline runtime/build sanity checks before mutation commands:
+  - `PM_CMD --version`
+  - `node -v`
+  - `pnpm -v`
+  - `pnpm build` (if configured)
 - For real repository tracking, do not override `PM_PATH`.
 - For tests only, always use sandboxed `PM_PATH` and `PM_GLOBAL_PATH` (or `node scripts/run-tests.mjs ...`).
 
@@ -26,6 +31,15 @@ This document defines how coding agents must use `pm` for planning, execution, a
 
 ### Step A - Pick next work
 
+Before creating any new `pm` item, always check for an existing relevant item first.
+
+- Search and list existing items before `pm create`:
+  - `pm search "<keywords>" --limit 10`
+  - `pm list-open --limit 20`
+  - `pm list-in-progress --limit 20`
+- If a relevant item already exists, reuse it, update it, or claim it instead of creating a new one.
+- Never create duplicate `pm` items for the same work.
+
 Use one of:
 
 - `pm list-in-progress --limit 20`
@@ -279,7 +293,7 @@ For `create` and `update`, use camelCase wrapper parameters for the canonical CL
   "component": "none",
   "regression": "none",
   "customerImpact": "none",
-  "definitionOfReady": "Extension loading contract is clarified in docs.",
+  "definitionOfReady": "Extension loading behavior is clarified in docs.",
   "order": 1,
   "goal": "Release-hardening",
   "objective": "Ship deterministic extension loading",
@@ -293,7 +307,7 @@ For `create` and `update`, use camelCase wrapper parameters for the canonical CL
   "learning": ["none"],
   "linkedFile": ["path=src/core/extensions/loader.ts,scope=project,note=planned implementation file"],
   "linkedTest": ["command=node scripts/run-tests.mjs test,scope=project,timeout_seconds=240,note=sandbox-safe regression"],
-  "doc": ["path=PRD.md,scope=project,note=authoritative contract"]
+  "doc": ["path=docs/ARCHITECTURE.md,scope=project,note=implementation reference"]
 }
 ```
 

package/PRD.md

@@ -1,6 +1,6 @@
 # pm-cli Product Requirements Document (PRD)
 
-Status: Draft v1 (authoritative for implementation)  
+Status: Draft v1 (planning reference; pm data and runtime behavior are authoritative)
 Project: `pm` / `pm-cli`  
 Last Updated: 2026-02-19
 
@@ -39,9 +39,9 @@ Existing trackers either rely on hosted backends, store state in non-diff-friend
 - No required database for core tracker (file-backed core is mandatory).
 - Export to Beads is not required in v1 (import only).
 
-## 4) Authoritative Inputs and Design Findings
+## 4) Reference Inputs and Design Findings
 
-### 4.1 Local authoritative references analyzed
+### 4.1 Local reference inputs analyzed
 
 1. `todos.ts` (local Pi extension implementation)
 2. `.beads/issues.jsonl` (local Beads-style JSONL data)
@@ -396,7 +396,7 @@ Unset optional fields are omitted.
   ],
   "tests": [
     {
-      "command": "pnpm test history",
+      "command": "node scripts/run-tests.mjs test -- tests/unit/history-command.spec.ts",
       "scope": "project",
       "timeout_seconds": 90
     }
@@ -739,7 +739,7 @@ All commands return deterministic top-level objects (TOON by default, JSON with
 | `pm get <ID>` | normalized id | `{ item, body, linked: { files, tests, docs } }` |
 | `pm search <keywords>` | keyword query + optional mode/include-linked/limit filters | `{ query, mode, items, count, filters, now }` |
 | `pm reindex` | optional `--mode` (`keyword|semantic|hybrid` baseline) | `{ ok, mode, total_items, artifacts, warnings, generated_at }` |
-| `pm beads import --file <path?>` | optional Beads JSONL source path (defaults to `.beads/issues.jsonl`) | `{ ok, source, imported, skipped, ids, warnings }` |
+| `pm beads import [--file <path\|->] [--preserve-source-ids]` | optional Beads JSONL source path (`.beads/issues.jsonl` auto-discovered first, then `issues.jsonl`; implicit `sync_base.jsonl` fallback is refused as unsafe) | `{ ok, source, imported, skipped, ids, warnings }` |
 | `pm todos import --folder <path?>` | optional todos markdown source folder (defaults to `.pi/todos`); preserves canonical optional `ItemFrontMatter` metadata when present and applies deterministic defaults for missing PM fields | `{ ok, folder, imported, skipped, ids, warnings }` |
 | `pm todos export --folder <path?>` | optional todos markdown destination folder (defaults to `.pi/todos`) | `{ ok, folder, exported, ids, warnings }` |
 | `pm create ...` | required title + schema flags | `{ item, changed_fields, warnings }` |
@@ -1013,7 +1013,7 @@ export interface ExtensionApi {
 
 Command:
 
-- `pm beads import [--file <path>]`
+- `pm beads import [--file <path>|-] [--preserve-source-ids]`
 
 Current baseline status (release-hardening):
 
@@ -1023,9 +1023,10 @@ Behavior:
 
 - Parse Beads JSONL records.
 - Map Beads fields to PM schema.
-- Preserve IDs and timestamps where possible.
+- Preserve IDs and timestamps where possible, including Beads-only compatibility metadata such as `source_type`, `source_owner`, `source_kind`, `design`, `external_ref`, and `closed_at`.
 - Append history with `op: "import"`.
-- Default input path is `.beads/issues.jsonl` when `--file` is not provided.
+- When `--file` is not provided, auto-discover `.beads/issues.jsonl` first and then `issues.jsonl`; implicit fallback to `sync_base.jsonl` is refused because it may be partial.
+- `--preserve-source-ids` preserves explicit Beads item IDs verbatim instead of rewriting them to the tracker prefix.
 - Invalid JSONL lines or duplicate IDs are skipped with deterministic warnings.
 
 ### B) todos.ts import/export
@@ -1363,7 +1364,7 @@ Checklist:
 
 - [x] CI matrix finalized (ubuntu/macos/windows Node 20, ubuntu Node 22, ubuntu Node 24)
 - [x] fixture corpus for restore/import/search
-- [x] command help and README examples validated in tests
+- [x] command help and pm-data-driven runtime checks validated in tests
 - [x] repository layout refactor (`src/cli`, `src/core`, `src/types`)
 - [x] sandboxed integration harness (`withTempPmPath`)
 - [x] sandboxed pm-runner (`scripts/run-tests.mjs`) for `pm test` and `pm test-all` safety
@@ -1376,7 +1377,7 @@ Checklist:
 Definition of Done:
 
 - All required commands and tests passing
-- docs and behavior aligned with this PRD
+- pm data, runtime behavior, and user-facing docs kept coherent
 
 ## 22) Open Assumptions and Clarifications Captured