@unbrained/pm-cli 2026.5.12 → 2026.5.18

package/docs/COMMANDS.md

@@ -6,6 +6,7 @@ This is a task-oriented command guide. For exact flags, use runtime help because
 pm <command> --help
 pm <command> --help --json
 pm contracts --command <command> --flags-only --json
+pm install guide-shell --project
 pm guide commands --depth standard
 ```
 
@@ -13,7 +14,7 @@ pm guide commands --depth standard
 
 - Prefer `pm context`, `pm search`, and narrow list commands before mutation.
 - Prefer TOON for reading and `--json` for strict parsing.
-- Use `pm guide <topic>` for local docs routing before opening deeper pages.
+- Use `pm install guide-shell --project` before `pm guide <topic>` when local docs routing is needed.
 - Use `pm contracts` for machine clients.
 - Every mutation writes history.
 
@@ -26,28 +27,37 @@ Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 | Bootstrap | `init`, `config`, `health` | create and inspect tracker setup |
 | Triage | `context`, `search`, `list*`, `aggregate`, `dedupe-audit` | find work and audit decomposition |
 | Lifecycle | `create`, `claim`, `update`, `append`, `close`, `release`, `delete`, `start-task`, `pause-task`, `close-task` | mutate item state |
+| Planning | `plan create`, `plan add-step`, `plan update-step`, `plan complete-step`, `plan link`, `plan approve`, `plan materialize` | agent-optimized living plans with ordered steps, evidence, decisions, validation, and materialization |
 | Logs | `comments`, `notes`, `learnings`, `comments-audit` | record progress and durable context |
 | Links | `files`, `docs`, `test`, `deps` | connect items to artifacts, tests, and relationships |
 | Verification | `test`, `test-all`, `test-runs`, `validate`, `gc` | run linked tests and repository checks |
-| History | `history`, `activity`, `restore`, `stats` | inspect and recover item state |
+| History | `history`, `history-redact`, `activity`, `restore`, `stats` | inspect, redact, and recover item state |
 | Calendar | `calendar`, `cal` | project deadlines, reminders, and events |
 | Packages | `install`, `upgrade`, `package`, `packages`, `extension`, package/extension command groups | install, upgrade, manage, and run package-backed extension commands |
-| Machines | `guide`, `contracts`, `completion`, `help` | local docs routing plus command contracts and shell helpers |
+| Machines | `contracts`, `help`, optional `guide`/`completion` | command contracts plus optional guide-shell docs routing and shell helpers |
 
 ## Bootstrap
 
 ```bash
 pm init
+pm init --defaults --with-packages
+pm init --agent-guidance status
+pm init --agent-guidance add
 pm config project list
 pm health --check-only
 ```
 
 `pm init` creates `.agents/pm`. `pm health --check-only` inspects without refreshing optional search artifacts.
+`pm init --agent-guidance ask` is the default behavior: prompt in TTY only when AGENTS/CLAUDE guidance is missing and no decline is recorded.
+Use `--agent-guidance add` to write guidance, `--agent-guidance skip` to persist a decline without writing, and `--agent-guidance status` to inspect guidance state.
+Use `--with-packages` for one-step agent setup when bundled package commands should be active immediately.
 
 ## Packages
 
 ```bash
+pm package                     # bare command defaults to --explore (list installed)
 pm install '*' --project
+pm package catalog --project
 pm install npm:@scope/pm-package --project
 pm package doctor --project --detail summary
 pm upgrade --dry-run
@@ -55,7 +65,8 @@ pm upgrade --packages-only
 pm upgrade --cli-only --repair
 ```
 
-`pm install` and `pm package` are the preferred package-first workflow. `pm install '*'`, shell-expanded `pm install *`, and `pm install all` install bundled first-party packages. `pm extension` remains as a compatibility command for direct extension lifecycle operations.
+`pm install` and `pm package` are the preferred package-first workflow. `pm package` and `pm extension` bare invocations default to `--explore` so agents can list installed packages without remembering an action flag. `pm install '*'`, shell-expanded `pm install *`, and `pm install all` install bundled first-party packages. `pm extension` remains as a compatibility command for direct extension lifecycle operations.
+When package-owned commands are unavailable, usage guidance includes an install-ready retry (for example `pm install calendar`, `pm install search-advanced`, `pm install governance-audit`, or `pm install guide-shell`).
 
 ## Triage
 
@@ -72,7 +83,17 @@ Use `context` first for a compact active-work snapshot. Use `search` when the re
 
 ## Create and Update
 
-Minimal progressive create:
+Shortest agent-friendly create (positional title + defaults to `Task` type):
+
+```bash
+pm create "Document command contracts"
+pm create "Fix login bug" --type Issue --priority 1
+```
+
+`pm create` defaults `--type` to `settings.governance.create_default_type` (falling back to `Task`).
+Pass `--create-mode strict` to require an explicit `--type` flag for governance-controlled flows.
+
+Minimal progressive create with explicit fields:
 
 ```bash
 pm create \
@@ -144,9 +165,9 @@ Use comments for progress and evidence, notes for implementation context, and le
 ## Linked Artifacts
 
 ```bash
-pm files <id> --add path=src/cli/main.ts,scope=project,note="command wiring"
+pm files <id> --add path=src/cli/main.ts,note="command wiring"
 pm files <id> --add-glob "src/cli/**/*.ts"
-pm docs <id> --add path=docs/COMMANDS.md,scope=project,note="public command docs"
+pm docs <id> --add path=docs/COMMANDS.md,note="public command docs"
 pm deps <id> --format tree
 ```
 
@@ -155,7 +176,7 @@ Linked files and docs keep reviews reproducible. `deps` is read-only and project
 ## Linked Tests
 
 ```bash
-pm test <id> --add command="node scripts/run-tests.mjs test -- tests/unit/output.spec.ts",scope=project,timeout_seconds=240
+pm test <id> --add command="node scripts/run-tests.mjs test -- tests/unit/output.spec.ts",timeout_seconds=240
 pm test <id> --run --progress
 pm test-all --status in_progress --progress
 ```
@@ -181,6 +202,7 @@ pm context --from today --to +7d --limit 10
 ```
 
 `calendar` defaults to markdown for human and agent readability. Other commands default to TOON unless configured otherwise.
+For `--include events` without explicit `--to`, `--recurrence-lookahead-days`, or `--occurrence-limit`, recurring expansion is intentionally capped to a bounded default window and emits a warning with retry hints for broader windows.
 
 ## Validation and Maintenance
 
@@ -198,11 +220,64 @@ Use dry-run modes before broad lifecycle or cleanup changes.
 ```bash
 pm history <id> --limit 20
 pm history <id> --diff --verify
+pm history-redact <id> --literal "[redacted_path_prefix]/private" --replacement "[redacted_path]"
+pm history-redact <id> --regex "/192\\.168\\.[0-9.]+/g" --dry-run
 pm activity --id <id> --limit 50
 pm restore <id> <timestamp-or-version>
 ```
 
 History is append-only. Restore appends a new restore event instead of rewriting old history.
+`history-redact` rewrites matching history payloads deterministically, recomputes hash chains, and appends an auditable `history_redact` marker entry when changes are applied.
+
+## Plan Workflow
+
+`pm plan` is the agent-optimized planning loop built on the first-class `Plan` item type. Plans persist ordered steps, evidence, decisions, discoveries, validation, and resume context. Each mutation appends a history entry; full hash-chain replay is preserved.
+
+```bash
+pm plan create --title "Refactor lock retry" --scope "Improve retry semantics" --harness claude-code --parent pm-epic1 --related pm-rel1,pm-rel2 --claim
+pm plan add-step <plan-id> --step-title "Read lock.ts" --step-body "Inspect retry path" --depends-on pm-task1
+pm plan update-step <plan-id> plan-step-001 --step-status in_progress --step-evidence "started reading lock.ts"
+pm plan complete-step <plan-id> plan-step-001 --step-evidence "lock.ts read; retry path captured"
+pm plan block-step <plan-id> plan-step-003 --step-blocked-reason "waiting on pm-task9 approval"
+pm plan link <plan-id> plan-step-002 --link pm-rel3 --link-kind discovered_from --link-note "found related util"
+pm plan decision <plan-id> --decision-text "Use exponential backoff" --decision-rationale "Avoid thundering herd"
+pm plan discovery <plan-id> --discovery-text "Found existing util in src/util/retry.ts"
+pm plan validation <plan-id> --validation-text "Coverage stays at 100%" --validation-command "node scripts/run-tests.mjs coverage"
+pm plan resume <plan-id> --resume-context "step 2 pending; tests still failing on retry path"
+pm plan approve <plan-id> --message "ready to execute"
+pm plan materialize <plan-id> --steps plan-step-002,plan-step-003 --materialize-type Task --materialize-parent pm-epic1
+pm plan show <plan-id> --depth brief
+pm plan show <plan-id> --depth standard
+pm plan show <plan-id> --depth deep
+pm plan show <plan-id> --fields id,title,steps_summary
+```
+
+Subcommand cheatsheet:
+
+| Subcommand | Purpose |
+|------------|---------|
+| `create` | Create a Plan item with scope, harness, parent, related, blocked-by, and optional auto-claim |
+| `show` | Progressive-disclosure read (brief / standard / deep) with current step + next-action hints |
+| `add-step` | Append a step with title/body/owner/status/dependencies/files/tests/docs |
+| `update-step` | Patch one step (title, body, status, evidence, owner, blocked reason) |
+| `complete-step` | Shortcut for setting a step to `completed` with evidence |
+| `block-step` | Shortcut for setting a step to `blocked` with required `--step-blocked-reason` |
+| `reorder-step` | Move a step to a new 1-based order |
+| `remove-step` | Drop a step and renumber remaining steps |
+| `link` / `unlink` | Add or remove `linked_items` on a step (with optional `--promote-to-item-dep`) |
+| `decision` | Append a decision log entry (decision/rationale/evidence) |
+| `discovery` | Append a discovery log entry |
+| `validation` | Append a validation check (text/command/expected) |
+| `resume` | Replace the resume-context summary for stateless agents |
+| `approve` | Move `plan_mode` to `approved` (default) or any other mode via `--mode` |
+| `materialize` | Create real pm items (default `Task`) from selected steps with bidirectional links |
+
+Invariants:
+
+- Exactly one step is `in_progress` per Plan; pass `--allow-multiple-active` for explicit parallel branches.
+- Blocking a step requires `--step-blocked-reason` (or an already-recorded reason).
+- `materialize` adds `discovered_from` + `parent` to each new item and an `implements` link back on the source step plus a `child` dependency on the Plan.
+- Search keyword corpus includes plan_scope, step titles/bodies, decisions, discoveries, validation, and step linked items.
 
 ## Machine Contracts
 

package/docs/CONFIGURATION.md

@@ -48,7 +48,8 @@ Precedence:
 | `validation.sprint_release_format` | `warn` or `strict_error` |
 | `validation.parent_reference` | `warn` or `strict_error` |
 | `item_types.definitions[]` | custom item types and type options |
-| `search.*` | search mode, scoring, providers, and vector settings |
+| `governance.create_default_type` | default `--type` used by the `pm create "title"` positional shortcut (defaults to `Task`) |
+| `search.*` | search mode, scoring, providers, embedding timeout, and vector settings |
 
 ## Environment Variables
 
@@ -116,6 +117,8 @@ pm search "release docs" --mode keyword --limit 10
 
 Semantic and hybrid search can use built-in OpenAI-compatible or Ollama providers plus vector stores such as Qdrant or LanceDB. If local Ollama is available and semantic settings are unset, `pm` can resolve local defaults automatically.
 
+For local Ollama or slower embedding providers, tune `search.embedding_batch_size`, `search.embedding_timeout_ms`, and `search.scanner_max_batch_retries` in project config before assuming semantic search is broken. Keyword search remains the fast baseline while semantic indexing catches up.
+
 Useful commands:
 
 ```bash